Skip to main content
Source Code: src/gaia/agents/registry.py
Component: AgentRegistry Module: gaia.agents.registry Import: from gaia.agents.registry import AgentRegistry, AgentManifest, 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 — either a YAML manifest.yaml file or a Python module exporting a factory — and registers each subdirectory it finds.
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.

​
Core types

​
AgentManifest

Pydantic v2 model used to validate a YAML manifest.yaml file under ~/.gaia/agents/<agent-id>/. 
class AgentManifest(BaseModel):
    manifest_version: int = 1
    id: str                                       # lowercase/digits/hyphen, ≤ 52 chars
    name: str
    description: str = ""
    instructions: str = ""                        # system prompt for YAML-only agents
    tools: List[str] = ["rag", "file_search"]     # must be a subset of KNOWN_TOOLS
    mcp_servers: Dict[str, Dict[str, Any]] = {}
    models: List[str] = []                        # ordered preference list
    conversation_starters: List[str] = []
Validators enforce an ID regex (lowercase letters, digits, and hyphens, up to 52 chars; see validate_id in the source for the exact pattern) and check every tool in tools appears in KNOWN_TOOLS.

​
KNOWN_TOOLS

Whitelist of tool-mixin keys a manifest may reference. Each maps to a lazily- imported (module, class) pair: 
KNOWN_TOOLS = {
    "rag":         ("gaia.agents.chat.tools.rag_tools",  "RAGToolsMixin"),
    "file_search": ("gaia.agents.tools.file_tools",      "FileSearchToolsMixin"),
    "file_io":     ("gaia.agents.code.tools.file_io",    "FileIOToolsMixin"),
    "shell":       ("gaia.agents.chat.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: str                           # "builtin" | "custom_python" | "custom_manifest"
    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 raise KeyError.
list()Enumerate registered agents as a list of AgentRegistration.
refresh()Re-scan ~/.gaia/agents/ to pick up new YAML manifests at runtime.
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/
    manifest.yaml          # required for YAML-only agents
    agent.py               # optional — Python factory alternative
    README.md              # optional
Minimal manifest.yaml: 
manifest_version: 1
id: my-agent
name: My Custom Agent
description: Example agent for showing how custom registration works.
instructions: |
  You are a helpful assistant. Use the available tools when the user asks.
tools:
  - rag
  - file_search
models:
  - Qwen3.5-35B-A3B-GGUF
conversation_starters:
  - "What can you help me with?"
For Python-based custom agents, agent.py must export a factory(**kwargs) function that returns an Agent subclass instance. The registry imports the module lazily at discovery time.
  • 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.