Agent Registry

Source Code: src/gaia/agents/registry.py

Component: AgentRegistry Module: gaia.agents.registry Import: from gaia.agents.registry import AgentRegistry, AgentRegistration, KNOWN_TOOLS

Overview

AgentRegistry is the central catalog of agents available to the Agent UI. It is populated at server startup by AgentRegistry.discover(), which:

Registers built-in agents declared in code (today: chat, builder, optionally others).
Scans ~/.gaia/agents/ for custom agents. Each subdirectory must contain an agent.py defining a subclass of Agent. The registry imports the module via importlib, finds the Agent subclass with AGENT_ID and AGENT_NAME class attributes, and registers it.

The result is a keyed dict of AgentRegistration objects that the UI router (src/gaia/ui/routers/agents.py) lists and that _chat_helpers.py uses to instantiate agents per chat session.

The OpenAI-compatible API server (src/gaia/api/) still uses a separate, hard-coded AGENT_MODELS dict in src/gaia/api/agent_registry.py; it does not go through AgentRegistry. See API Server for how to wire new agents into the OpenAI surface.

Removed in v0.17.5 (#912): YAML manifest agents (a directory containing only agent.yaml, no agent.py) are no longer loaded. The registry emits a DeprecationWarning per such directory and skips it. See the Custom Agents guide for the migration recipe.

Core types

`KNOWN_TOOLS`

Map of tool-mixin keys to a lazily-imported (module, class) pair. Consumed by builder/template.py when scaffolding a new agent.py so users can opt into a mixin by name.

KNOWN_TOOLS = {
    "rag":         ("gaia.agents.tools.rag_tools",  "RAGToolsMixin"),
    "code_index":  ("gaia.agents.tools.code_index_tools","CodeIndexToolsMixin"),
    "file_search": ("gaia.agents.tools.file_tools",      "FileSearchToolsMixin"),
    "file_io":     ("gaia.agents.tools.file_io_tools",    "FileIOToolsMixin"),
    "shell":       ("gaia.agents.tools.shell_tools","ShellToolsMixin"),
    "screenshot":  ("gaia.agents.tools.screenshot_tools","ScreenshotToolsMixin"),
    "sd":          ("gaia.sd.mixin",                     "SDToolsMixin"),
    "vlm":         ("gaia.vlm.mixin",                    "VLMToolsMixin"),
}

`AgentRegistration`

Dataclass the registry stores per agent:

@dataclass
class AgentRegistration:
    id: str
    name: str
    description: str
    source: Literal["builtin", "custom_python"]
    conversation_starters: List[str]
    factory: Callable[..., Any]           # returns an Agent instance
    agent_dir: Optional[Path]
    models: List[str]                     # ordered preference list
    hidden: bool = False                  # excluded from UI agent selector when True

Public API

AgentRegistry is typically instantiated once per process and shared via src/gaia/ui/dependencies.py:

from gaia.agents.registry import AgentRegistry

registry = AgentRegistry()
registry.discover()                       # scans built-ins + ~/.gaia/agents/

# Introspect
entry = registry.get("chat")              # AgentRegistration
agent = entry.factory(**init_kwargs)      # create an Agent instance

Useful methods (see source for the full surface):

Method	Purpose
`discover()`	Scan built-ins and `~/.gaia/agents/`. Idempotent; logs results.
`get(id)`	Return the registration for `id` or `None`.
`list()`	Enumerate registered agents as a list of `AgentRegistration`.
`register_from_dir(path)`	Hot-load a single `~/.gaia/agents/<id>/` directory. Used by BuilderAgent so newly-scaffolded agents are immediately available.

The factory signature is deliberately free-form (**kwargs) — the caller filters to valid AgentConfig fields per agent (see chat_factory in the source for the common pattern using dataclasses.fields(...)).

Custom-agent directory layout

~/.gaia/agents/
  my-agent/
    agent.py               # required — defines the Agent subclass
    agent.yaml             # optional sidecar — only `models:` is read
    mcp_servers.json       # optional — MCP server config for MCPClientMixin
    README.md              # optional

The recommended way to scaffold a new agent is the Gaia Builder Agent (gaia chat --ui → + → Build a Custom Agent), which writes a ready-to-edit agent.py. See the Custom Agents guide for the full minimal example, the tool-mixin table, and the YAML-manifest migration recipe.

Agent UI Server — how the UI backend uses the registry to resolve chat sessions.
API Server — the separate OpenAI-style model registry used by gaia api start.
Custom Agents guide — Python agent recipes and the manifest → agent.py migration.

Core Framework

SDKs

Infrastructure

Code Infrastructure

Tool Mixins

Packaging

Agents & Apps

Overview

Core types

`KNOWN_TOOLS`

`AgentRegistration`

Public API

Custom-agent directory layout

​Overview

​Core types

​KNOWN_TOOLS

​AgentRegistration

​Public API

​Custom-agent directory layout

​Related

Overview

Core types

`KNOWN_TOOLS`

`AgentRegistration`

Public API

Custom-agent directory layout

Related