[Bug] Documented "split topology from infra" YAML pattern fails to load

[Sxnan]

Search before asking

• I searched in the issues and found nothing similar.

Description

Found during YAML doc verification (#742).

docs/content/docs/development/yaml.md line 385 recommends splitting a
topology file from an infrastructure file:

A common pattern is to split a topology file (the agents themselves) from
an infrastructure file (chat-model connections, vector stores, ...). The
infrastructure file can be swapped per environment (dev / staging / prod)
without touching the agent definitions.

The Loading and Running section (lines 362-380) shows:

agents_env.load_yaml(["./agents.yaml", "./shared.yaml"])

with no caveat that each file must contain an agents: block.

In python/flink_agents/api/yaml/specs.py:220-231 the top-level document
declares agents as a required field (no default):

class YamlAgentsDocument(BaseModel):
    model_config = ConfigDict(extra="forbid")

    agents: List[AgentSpec]                                    # required

    prompts: List[PromptSpec] = Field(default_factory=list)
    tools: List[ToolSpec] = Field(default_factory=list)
    ...
    chat_model_connections: List[DescriptorSpec] = Field(default_factory=list)
    ...

So an infra-only YAML containing only shared resources is rejected:

pydantic.ValidationError: 1 validation error for YamlAgentsDocument
agents
  Field required [type=missing, ...]

Adding a placeholder agents: [] to the infra file works around it, but
that workaround is not mentioned in the doc.

How to reproduce

infra.yaml (as the doc implies you can write):

chat_model_connections:
  - name: shared_ollama
    clazz: ollama
    base_url: http://localhost:11434

topology.yaml:

agents:
  - name: my_agent
    actions:
      - name: process_input
        function: my_pkg.actions:process_input
        listen_to: [input]
    chat_model_setups:
      - name: my_llm
        clazz: ollama
        connection: shared_ollama
        model: qwen3:8b

env = AgentsExecutionEnvironment.get_execution_environment()
env.load_yaml(["infra.yaml", "topology.yaml"])
# pydantic.ValidationError: agents: Field required

Fix

Make agents optional with an empty default in YamlAgentsDocument:

agents: List[AgentSpec] = Field(default_factory=list)

Add a regression test covering the infra-only document:

def test_yaml_document_allows_infra_only_file():
    YamlAgentsDocument.model_validate(
        {"chat_model_connections": [{"name": "x", "clazz": "ollama"}]}
    )

Per the schema-parity contract (SchemaParityTest), the Java POJO
org.apache.flink.agents.api.yaml.spec.YamlAgentsDocument needs the same
change so the checked-in docs/yaml-schema.json and both runtimes stay
aligned. Re-export the schema with
python -m flink_agents.api.yaml.specs > docs/yaml-schema.json after the spec
change.

Version and environment

Flink Agents 0.3.0 (main).

Are you willing to submit a PR?

• I'm willing to submit a PR!