Sxnan opened a new issue, #775: URL: https://github.com/apache/flink-agents/issues/775
### Search before asking - [x] I searched in the [issues](https://github.com/apache/flink-agents/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: ```python 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): ```python 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): ```yaml chat_model_connections: - name: shared_ollama clazz: ollama base_url: http://localhost:11434 ``` **`topology.yaml`**: ```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 ``` ```python 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`: ```python agents: List[AgentSpec] = Field(default_factory=list) ``` Add a regression test covering the infra-only document: ```python 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! -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
