GAIA Agent Builder

Building a GAIA Agent

How to take an idea to a working, testable GAIA agent — a Python class that runs locally on AI PCs. This skill covers build; publishing is its sibling agent-hub-release skill and the author guide docs/guides/hub-publishing.mdx. The full prose walkthrough is docs/guides/custom-agent.mdx.

Read CLAUDE.md first — the "No Silent Fallbacks", code-reuse, testing, and eval rules all apply to a new agent.

The mental model

A GAIA agent is one Python class that inherits from the base Agent (src/gaia/agents/base/agent.py) and exposes capabilities as @tool-decorated methods. The base class owns the agent loop, tool registry, state, error recovery, and (via mixins) MCP / OpenAI-API exposure — you write the prompt + the tools, not the plumbing. There are no YAML agent manifests for in-core agents (removed in v0.17.5); a publishable hub package adds a gaia-agent.yaml manifest on top (see the publish skill).

Steps

1. Scaffold. gaia agent init my-agent generates a starter package at ./my-agent/. For a publishable hub package in this repo, add --layout hub so it lands at hub/agents/<id>/python/:

   gaia agent init my-agent -o hub/agents/ --layout hub

   Then mirror an existing package for structure: hello-world or word-count for a minimal one, email for a full published agent.

2. Write the Agent subclass. Inherit from Agent (or a closer base like ChatAgent, which the flagship GaiaAgent extends). Leave model_id unset — that inherits the base default, Gemma-4-E4B-it-GGUF (DEFAULT_MODEL_NAME), which is right for nearly every agent. Every agent sharing one model is what keeps a single model resident, so switching agents never triggers an eviction + cold reload. Only set model_id when the agent genuinely needs a different model (e.g. the email agent picks the NPU model gemma4-it-e2b-FLM when one is present and servable), and say why. Keep the constructor thin.

3. Register tools with @tool. Each @tool method is a capability the LLM can call; its docstring is the schema the model sees, so write it for the model (one line of intent + each arg). Return structured data or an actionable error — never swallow exceptions into a placeholder (No Silent Fallbacks).

4. Reuse, don't reinvent — compose mixins. Before writing file/web/RAG/shell/SQL logic, check KNOWN_TOOLS in src/gaia/agents/registry.py: rag, file_io, file_search, shell, browser, scratchpad, code_index, vlm, sd, … Compose them by name instead of duplicating. New shared logic → add a mixin and register it in KNOWN_TOOLS.

5. System prompt. Implement _get_system_prompt() — state the agent's job, when to use which tool, and the output contract. This is an LLM-affecting surface, so it's covered by the eval rule below.

6. Make it discoverable. An in-core agent is added to src/gaia/agents/registry.py (and a gaia <cmd> subparser in src/gaia/cli.py if it's a CLI command). A hub package is auto-discovered from its gaia-agent.yaml manifest — no registry.py edit; just make sure the manifest's python.entry_module / entry_class point at your class.

7. Test it — actually run it. Unit tests with a mocked LLM for tool logic (tests/), then run the real CLI a user would (gaia <cmd> ... or python my_agent.py) — never only the Python module. Follow the gaia-testing skill for real-world evidence.

8. Eval if it touches LLM behavior. If you wrote/changed a system prompt, tool docstrings, the tool schema, the model, or error classification, you MUST run gaia eval agent against the relevant category before calling it done, and compare to a baseline only if one is committed for the same agent — none is yet, so report the scores you measured (CLAUDE.md eval rule). Unit tests don't catch LLM regressions.