> ## Documentation Index
> Fetch the complete documentation index at: https://amd-gaia.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Registry

> How GAIA discovers and instantiates agents from built-in modules and ~/.gaia/agents/

<Info>
  **Source Code:** [`src/gaia/agents/registry.py`](https://github.com/amd/gaia/blob/main/src/gaia/agents/registry.py)
</Info>

<Note>
  **Component:** AgentRegistry
  **Module:** `gaia.agents.registry`
  **Import:** `from gaia.agents.registry import AgentRegistry, AgentRegistration, KNOWN_TOOLS`
</Note>

***

## 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.

<Note>
  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](/docs/sdk/infrastructure/api-server) for
  how to wire new agents into the OpenAI surface.
</Note>

<Warning>
  **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](/docs/guides/custom-agent#migrating-from-a-yaml-manifest) for
  the migration recipe.
</Warning>

***

## Core types

### `KNOWN_TOOLS`

Map of tool-mixin keys to a lazily-imported `(module, class)` pair. Consumed
by [`builder/template.py`](https://github.com/amd/gaia/blob/main/src/gaia/agents/builder/template.py)
when scaffolding a new `agent.py` so users can opt into a mixin by name.

```python theme={null}
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:

```python theme={null}
@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`:

```python theme={null}
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](/docs/guides/custom-agent)
for the full minimal example, the tool-mixin table, and the YAML-manifest
migration recipe.

***

## Related

* [Agent UI Server](/docs/spec/agent-ui-server) — how the UI backend uses the
  registry to resolve chat sessions.
* [API Server](/docs/sdk/infrastructure/api-server) — the separate OpenAI-style
  model registry used by `gaia api start`.
* [Custom Agents guide](/docs/guides/custom-agent) — Python agent recipes and
  the manifest → `agent.py` migration.