Skip to main content
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:
  1. Registers built-in agents declared in code (today: chat, builder, optionally others).
  2. 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):
MethodPurpose
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.