refactor(agents): remove YAML manifest agent support (#912)

[itomek]

Summary

Consolidates custom agents on a single definition format: Python agent.py. Deletes ~200 lines of dynamic type()-based class construction, Pydantic manifest validation, and per-agent MCP-config merging from src/gaia/agents/registry.py. Unblocks upcoming external-service work (OAuth-bound integrations) where capability declarations like REQUIRED_CONNECTIONS need a single class-attribute home the Agent UI can introspect.

The agent.yaml companion sidecar (declares models: next to a Python agent) is unchanged.

Closes #912

Why this matters

• One way to define a custom agent. Removes the parallel YAML schema and dynamic type() builder, so every agent is a regular Python class readable by mypy, IDEs, and git grep.
• Smaller, simpler registry. −276 lines from registry.py; the dynamic class builder, _TOOL_REGISTRY.clear() race risk, and the merged-MCP-config disk write are all gone.
• Foundation for Phase-1 connection work. OAuth scope declarations now have an unambiguous Python-class home rather than a parallel YAML field needing doubled validation and doubled UI handling.

Behaviour

• _load_from_dir loads only agent.py. A directory containing only agent.yaml (no sibling agent.py) emits a DeprecationWarning and is skipped.
• Companion-YAML guard. When both agent.py and agent.yaml exist, only models: is read. Legacy manifest fingerprint keys (manifest_version, tools, instructions, mcp_servers, id) trigger a DeprecationWarning enumerating the ignored keys instead of silently discarding them. A scalar models: value is rejected with a logger warning rather than leaking through as a string that would later iterate as characters.
• Type narrowing. AgentRegistration.source (dataclass) and AgentInfo.source (Pydantic) are now Literal["builtin", "custom_python"]. Pydantic enforces at the API boundary.
• Importer. Bundles whose entry directories ship YAML-only or no agent.py at all surface an actionable ImportResult.errors message rather than silently moving an unloadable directory into ~/.gaia/agents/. Exporter drops the YAML-only branch from _is_custom_agent_dir.

Removed

• AgentManifest Pydantic model and its validate_tools / validate_id validators.
• _load_manifest_agent, _create_manifest_agent_class, _write_merged_mcp_config from AgentRegistry.
• schemas/agent-manifest.schema.json and util/gen_manifest_schema.py (and the corresponding lint check in util/check_agent_conventions.py).
• All tests/unit/agents/test_registry.py cases that exercised the manifest loader.

Pre-merge verification

• ✅ No first-party agent ships as YAML. Built-in registrations in _register_builtin_agents are Python-only.
• ✅ BuilderAgent emits Python only. src/gaia/agents/builder/template.py generate_agent_source() returns Python source for all three render paths; tests/unit/agents/test_builder_agent.py already asserts no agent.yaml is written. No BuilderAgent changes required.
• ⏳ Internal demos / customer integrations. Please confirm before merge that no internal workshop, eval set, or customer hand-off relies on ~/.gaia/agents/*/agent.yaml.

Test plan

• python -m pytest tests/unit/agents/test_registry.py tests/unit/test_export_import.py -xvs — 45 passed
• python -m pytest tests/unit/ -x — 1642 passed, 15 skipped (3 pre-existing chat/ui/test_sse_confirmation.py flakes verified independent of this PR)
• python util/lint.py --all --fix — 6/6 quality checks pass
• grep -rn "AgentManifest\|_load_manifest_agent\|_create_manifest_agent_class\|_write_merged_mcp_config\|custom_manifest" src/ tests/ docs/ — no residual references outside the deprecation-warning string, the regression-guard test, and the release-notes entry
• python -c "import json; json.load(open('docs/docs.json'))" — Mintlify nav still valid JSON

Migration

Users with ~/.gaia/agents/<id>/agent.yaml manifests need to convert to agent.py. The release notes link to a new "Migrating from a YAML Manifest" section in docs/guides/custom-agent.mdx with a field-by-field translation table and a worked example. The fastest path is the Gaia Builder Agent (gaia chat --ui → + → Build a Custom Agent), which scaffolds a working agent.py.

[github-actions]

Summary

Clean, well-scoped removal of YAML-manifest agent support. The registry change is small and surgical (~−276 lines), the migration path is well-documented in docs/guides/custom-agent.mdx, and the importer/exporter changes correctly surface actionable errors instead of silently breaking. The biggest miss is stale guidance left in repo-onboarding docs (CLAUDE.md, .github/workflows/claude.yml, .claude/agents/*.md) — they still tell contributors to register agents via YAML manifests, which directly contradicts the new behaviour.

---

Issues Found

🟡 Important — Stale guidance in onboarding docs still recommends the removed YAML format

These files are not in the diff but actively contradict the PR. Both repo contributors and the gaia-agent-builder Claude agent read them as authoritative.

CLAUDE.md (4 lines, all stale):

• CLAUDE.md:284 — └── registry.py # YAML-manifest agent registry + KNOWN_TOOLS map
• CLAUDE.md:377 — "New agents are preferably registered via YAML manifests validated by Pydantic..."
• CLAUDE.md:389 — "...register it in KNOWN_TOOLS so YAML-manifest agents can declare it."
• CLAUDE.md:680 — "gaia-agent-builder — Creating a new GAIA agent (Python class or YAML manifest)..."

.github/workflows/claude.yml:195-196 — duplicated review-bot guidance:

            - **New agents** must be registered as a Python `agent.py` (subclass of `Agent` with `AGENT_ID` / `AGENT_NAME` class attributes). YAML manifests were removed in v0.17.5 (#912).
            - **New tool mixins** MUST be added to `KNOWN_TOOLS` in `src/gaia/agents/registry.py`; the BuilderAgent template uses this map to scaffold imports for new `agent.py` files.

.claude/agents/gaia-agent-builder.md — has an entire "B. YAML manifest" section (lines 38-41) and references to the deleted AgentManifest type (lines 28, 41, 65, 71).

.claude/agents/sdk-architect.md:32 — references AgentManifest (YAML spec).

This is the same kind of doc/code drift the PR's regression test (TestRemovedSymbols) was written to prevent — worth catching it in CLAUDE.md and the agent definitions too.

🟢 Minor — Obsolete subsections in code-index docs

• docs/sdk/sdks/code-index.mdx:204-214 — "Opting in from a YAML-manifest agent" with a class_path: / tools: YAML example. The whole subsection is now dead — either delete it or rewrite as a Python-agent recipe pointing back to docs/guides/custom-agent.mdx.
• docs/guides/code-index.mdx:134 — "YAML-manifest agents can opt in by listing code_index under tools..." same fix; reword to "Custom agents can compose CodeIndexToolsMixin directly...".

🟢 Minor — Stale docstring entry in convention linter

util/check_agent_conventions.py:17 still lists "Manifest JSON Schema is not stale" under "Hard checks", but _check_manifest_schema() was deleted in this PR.

- ``KNOWN_TOOLS`` entries in registry.py resolve to importable classes

(Drop the Manifest JSON Schema is not stale bullet entirely — it has no implementation behind it any more.)

🟢 Minor — Export silently drops YAML-only dirs; users get no migration prompt from that path

src/gaia/installer/export_import.py:99 — _is_custom_agent_dir returns False for YAML-only dirs, and the test test_export_skips_yaml_only_dirs documents this as intentional. The discovery path emits a DeprecationWarning for the same case, but the export path is silent. If a user runs export_custom_agents on a .gaia/agents/ containing one Python and one YAML agent, the resulting bundle quietly contains only the Python one — they have no signal to migrate.

Suggest emitting a single log.warning per skipped YAML-only directory, with the same migration link the importer uses. Not blocking; the test correctly captures the chosen tradeoff.

🟢 Minor — Non-string entries in companion models: are silently dropped

src/gaia/agents/registry.py:281 — models = [m for m in raw_models if isinstance(m, str)]. A list like [123, "Qwen3-0.6B-GGUF"] passes the outer isinstance(raw_models, list) guard, drops the int, and registers ["Qwen3-0.6B-GGUF"] with no warning. Mirrors the warning emitted for a scalar models: value — for consistency, consider warning when the filter drops anything:

                    raw_models = yaml_data.get("models")
                    if isinstance(raw_models, list):
                        bad = [m for m in raw_models if not isinstance(m, str)]
                        if bad:
                            logger.warning(
                                "registry: companion YAML %s: 'models' contains "
                                "non-string entries %r — ignoring those",
                                yaml_file,
                                bad,
                            )
                        models = [m for m in raw_models if isinstance(m, str)]
                    elif raw_models is not None:

---

Strengths

• Excellent regression-guard test (TestRemovedSymbols). Parametrised over both module-level and class-level deletions — exactly the pattern that prevents the deletions from accidentally being re-introduced by a later refactor.
• Companion-YAML manifest-fingerprint guard is a smart UX touch. Detecting manifest_version / tools / instructions / mcp_servers / id next to a Python agent and emitting an enumerated DeprecationWarning (rather than silently dropping the keys) preserves the principle from CLAUDE.md that legacy state should fail loudly.
• New _purge_custom_agent_modules autouse fixture (tests/unit/agents/test_registry.py:33) correctly prevents sys.modules cache leakage from importlib.util.spec_from_file_location reuse — a subtle bug that bites only when test order changes. Good defensive test hygiene.
• Type narrowing of AgentRegistration.source and AgentInfo.source to Literal["builtin", "custom_python"] removes a string-typed enum at the API boundary and lets Pydantic enforce it.
• Importer error messages name the agent ID, the cause, and the migration URL — exactly the three-part actionable error the CLAUDE.md "fail loudly" rule asks for.

---

Verdict

Approve with suggestions. No blockers. The 🟡 onboarding-doc inconsistencies should ideally be cleaned up in this PR (they're the same scope of work as the docs/guides/custom-agent.mdx rewrite already in the diff), but they can also be a follow-up if the maintainer prefers to keep this PR tightly scoped.

[kovtcharov-amd]

@claude can you evaluate the pros/cons of removing yaml support? I do think there's space for both where you implement the programmatic portions of an agent in a python file while using yaml for simple configurations of the agent. analyze what is cleanest and architecturally sound.

[github-actions]

@kovtcharov-amd — good question, and worth pulling apart. Two things are getting bundled in the term "YAML support" and they have different tradeoffs.

What this PR removed vs. what it kept

	Before	After
Full YAML manifest (id, name, instructions, tools, mcp_servers — entire agent declared in YAML, class built dynamically via type())	✅ Supported	❌ Removed
Companion sidecar agent.yaml next to agent.py, scoped to declarative config (models:)	✅ Supported	✅ Kept

The deletion is specifically the YAML-as-class-definition path — the one that did dynamic class construction, MRO stitching, _TOOL_REGISTRY.clear() per agent, and merged-MCP-config disk writes. The hybrid you're describing (Python for code, YAML for declarative config) is already in the codebase as the sidecar — see registry.py:262-292. Today it only reads models:, but that's a deliberate door, not a hard ceiling.

Pros / cons of going further on the hybrid

Pros of expanding the sidecar (YAML-for-config):

• Separation of concerns. Editing a description, conversation starter, or OAuth scope shouldn't require touching agent.py.
• Non-developer authoring. Domain experts / PMs can tweak metadata; Agent UI can render a form that round-trips YAML cleanly.
• Future Agent Hub fit (docs/plans/agent-hub.mdx). Shared Python "agent kits" + per-deployment YAML overrides is a well-trodden plugin shape.
• Multi-environment overrides. Same Python, different YAML per environment (rare but real).

Cons / what bit us last time:

• Two sources of truth. When agent.py has AGENT_ID = "x" and agent.yaml has id: y, someone has to define precedence and the UI has to know which one to surface. The current manifest-fingerprint guard at registry.py:268-278 exists precisely because this drift is real.
• mypy / IDE blindness. Anything in YAML is invisible to type-checkers and git grep.
• Doubled UI handling. The Phase-1 connection plumbing motivation (REQUIRED_CONNECTIONS) is exactly what gets cheaper with one path — adding YAML back doubles the UI handler surface again.
• YAGNI on most "config" fields. AGENT_ID, AGENT_NAME, CONVERSATION_STARTERS are one-line class attributes today. Moving them to YAML costs a parser, a schema, and a precedence rule for ~3 lines saved.

Architectural recommendation

I'd argue the cleanest position is what we have right now, with a clear rule for the sidecar:

Python is canonical. The sidecar carries only declarative fields where (a) the value is plain data, (b) the field is plausibly edited without a code change, (c) the Agent UI consumes it as a form.

models: qualifies because users tune available models per machine. Future candidates that pass that bar:

• oauth_scopes: / required_connections: — per-deployment, surfaced in a consent dialog
• mcp_servers: overrides (already a sibling mcp_servers.json, not a registry concern)
• branding / panel defaults if/when those exist

Fields that should not drift back into YAML:

• instructions / system prompt — frequently references self, dynamic context
• tools — mixin selection is a class-definition concern; @tool registration has Python semantics
• id / name / description — fine as Python class attrs; moving them to YAML buys nothing

Concrete next step if you want to push further on the hybrid: when REQUIRED_CONNECTIONS lands, add it to the sidecar (with Pydantic validation) rather than as a class attribute, and let the Agent UI read it without importing Python. That's the test case that proves the sidecar pattern scales — and it's the motivation called out in the PR description.

So: keep this PR as-is, treat the models:-only sidecar as the seed of the hybrid model rather than its end state, and grow the sidecar narrowly when an OAuth/connection field arrives that genuinely benefits from being declarative.