Custom Agents

Prerequisites: Complete the Setup guide and have the Agent UI running before you start.

Overview

GAIA’s agent registry lets you extend the Agent UI with your own custom agents. Each agent lives in its own directory under ~/.gaia/agents/ as a Python module. Once placed there, the agent appears automatically in the agent selector dropdown of the Gaia Agent UI. Custom agents can have their own:

Personality and instructions (system prompt)
Tools (RAG, file search, shell, image generation, vision, plus your own @tool functions)
Preferred models (override the server default)
Conversation starters (suggestion chips in the UI)
MCP servers (any Model Context Protocol server)
Connectors (Google, GitHub, and more) — give your agent permission to read your real email, calendar, repos, etc.

This guide builds a local custom agent in ~/.gaia/agents/ for your own Agent UI. When it’s ready to share — so anyone can install it from the Agent Hub — jump to Publish and share your agent.

Using Claude Code in the GAIA repo? Invoke the gaia-build-agent skill — it walks scaffolding → tools → model → test end-to-end, then hands off to the agent-hub-release skill for shipping.

Quick Start: Gaia Builder Agent

The fastest way to create an agent is to use the built-in Gaia Builder Agent.

Open the Agent UI

Start the GAIA Agent UI: gaia chat --ui

Click the + button

In the chat input footer, click the + icon (to the left of the agent picker). On the welcome screen, click Build a Custom Agent Template.

Follow the prompts

The Builder (an alpha feature) greets you, asks what to name the agent and what it should do, and asks whether you want MCP support — then scaffolds a starter agent with a personality and conversation starters tailored to your description.

Use your new agent

Your agent is immediately available in the agent selector dropdown — no restart needed.

The Builder creates a starter template at ~/.gaia/agents/<your-agent-name>/agent.py — a tailored persona and conversation starters (plus MCP wiring if you asked for it). It’s a starting point you extend, not a turnkey agent: it won’t fetch data or perform complex tasks on its own until you add tools. Open the file to refine the instructions and add capabilities (see Python Agent below).

Need your agent to read real data — Gmail, GitHub, your calendar? Skip ahead to Using GAIA connectors.

Python Agent

For full control — custom tools, built-in tool mixins, MCP servers, or complex logic — write a Python module.

Directory structure

~/.gaia/agents/
└── my-agent/
    ├── agent.py          # required — defines the Agent subclass
    └── agent.yaml        # optional sidecar — only the `models:` list is read

Minimal Python agent

from gaia.agents.base.agent import Agent
from gaia.agents.base.tools import _TOOL_REGISTRY, tool


class MyPythonAgent(Agent):
    AGENT_ID = "my-python-agent"
    AGENT_NAME = "My Python Agent"
    AGENT_DESCRIPTION = "An agent with a custom tool"

    def _get_system_prompt(self) -> str:
        return "You are a helpful assistant with a custom greet tool."

    def _register_tools(self) -> None:
        _TOOL_REGISTRY.clear()

        @tool
        def greet(name: str) -> str:
            """Greet a person by name."""
            return f"Hello, {name}! Welcome to GAIA."

This mirrors what the Builder Agent scaffolds. The only method a subclass must implement is _register_tools() (it’s abstract on the base Agent); the other two have sensible defaults you can override:

Method	Required?	Purpose
`_register_tools()`	Yes	Registers tools into `_TOOL_REGISTRY`
`_get_system_prompt()`	Optional	Returns the system prompt string (defaults to `""`, i.e. mixin prompts only)
`_create_console()`	Optional	Returns the console handler (defaults to `AgentConsole`, or a silent console in silent mode)

Adding built-in tools

GAIA ships with ready-to-use tool mixins. To enable most of them, inherit the mixin and call its register_*_tools() method from _register_tools(). The sd and vlm mixins are the exception — call init_sd() / init_vlm() (which set up the client and register the tools in one step):

Tool	Mixin	Register call
`rag`	`gaia.agents.tools.rag_tools.RAGToolsMixin`	`self.register_rag_tools()`
`file_search`	`gaia.agents.tools.file_tools.FileSearchToolsMixin`	`self.register_file_search_tools()`
`file_io`	`gaia.agents.tools.file_io_tools.FileIOToolsMixin`	`self.register_file_io_tools()`
`shell`	`gaia.agents.tools.shell_tools.ShellToolsMixin`	`self.register_shell_tools()`
`screenshot`	`gaia.agents.tools.screenshot_tools.ScreenshotToolsMixin`	`self.register_screenshot_tools()`
`sd`	`gaia.sd.mixin.SDToolsMixin`	`self.init_sd()`
`vlm`	`gaia.vlm.mixin.VLMToolsMixin`	`self.init_vlm()`

To call out to external services (Gmail, GitHub, Slack, etc.) without baking API keys into your code, use GAIA connectors instead of writing your own auth.

Overriding the default model (optional)

If your agent needs a specific model, set model_id in __init__():

def __init__(self, **kwargs):
    kwargs.setdefault("model_id", "Gemma-4-E4B-it-GGUF")
    super().__init__(**kwargs)

Alternatively, create a companion agent.yaml next to agent.py with a models: list — the registry reads that list as an ordered preference. The sidecar only honours the models: key; any other top-level key is ignored.

Using GAIA connectors

If your agent needs to act on your behalf — read your inbox, list your calendar events, query GitHub, post to Slack, etc. — wire it up to a GAIA connector rather than asking users to paste API tokens into your code. A connector lets users:

Authenticate once in Settings → Connections (OAuth flow for Google-style providers, paste-an-API-key for MCP servers).
Grant scopes per agent so each agent only sees the data it actually needs. The Agent UI surfaces this when a user first picks your agent.
Trust that secrets stay in the OS keyring, never in plaintext files or env vars baked into your code.

Declare what your agent needs by setting REQUIRED_CONNECTORS on the class, and call get_credential_sync(connector_id, agent_id, required_scopes=[...]) from inside a tool to get a usable token. The connectors-demo agent is a working reference for both oauth_pkce (Google) and mcp_server (GitHub) connectors.

Read the connectors guide

Walks through what connectors are, how the OAuth + MCP flows differ, per-agent grants, and a step-by-step setup for Google and GitHub.

Export and import agents

Custom agents can be packaged into a single .zip bundle and shared between machines, teammates, or environments. GAIA supports export and import from both the Agent UI and the CLI. Exports include every ~/.gaia/agents/* directory with an agent.py — the installer-seeded bundled example included; imported copies land as user-owned agents the seeder never touches.

From the Agent UI

Open Settings → Custom Agents.

Export All — packages every custom agent under ~/.gaia/agents/ into a single .zip file and downloads it. Disabled when you have no custom agents.
Import — opens a file picker for a .zip bundle and shows a confirmation dialog listing the agent IDs that will be installed. Imported agents register into the live registry; in most cases no restart is required.

From the CLI

# Export every custom agent to ~/.gaia/export.zip
gaia agent export

# Export to a specific path
gaia agent export --output ./my-agents.zip

# Import a bundle (shows IDs and prompts for confirmation)
gaia agent import ./my-agents.zip

# Import non-interactively (CI / scripts)
gaia agent import ./my-agents.zip --yes

See the CLI reference for full option details.

What’s in the bundle

Each .zip contains a bundle.json manifest at the root and one directory per agent:

my-agents.zip
├── bundle.json                  # { format_version, exported_at, gaia_version, agent_ids[] }
├── my-research-bot/
│   ├── agent.py
│   └── agent.yaml               # if present
└── my-greeter/
    └── agent.py

Bundles are validated on import. The receiving end enforces conservative limits (max 1000 entries, 500 MB uncompressed, 50 MB per file, 100 MB upload via the UI) and rejects symlinks or path-traversal entries.

Security

Bundles ship your agent source as-is. Any API keys, hardcoded tokens, or secrets embedded in agent.py will be included in the export. Review the bundle — or better, move secrets to GAIA connectors — before sharing.

Importing runs third-party code. A bundle’s agent.py files execute inside your GAIA process. Both the CLI (gaia agent import without --yes) and the UI surface the agent IDs and require explicit confirmation before installing. Only import bundles from sources you trust.

The UI endpoints (POST /api/agents/export and POST /api/agents/import) are localhost-only, CSRF-guarded with the X-Gaia-UI header, and disabled while a tunnel is active.

Examples

Example Agent — simple personality

from gaia.agents.base.agent import Agent
from gaia.agents.base.console import AgentConsole


class ExampleAgent(Agent):
    AGENT_ID = "example-agent"
    AGENT_NAME = "Example Agent"
    AGENT_DESCRIPTION = (
        "A bundled example agent that shows how installer-seeded custom agents work"
    )
    CONVERSATION_STARTERS = [
        "What are you an example of?",
        "How do I build my own agent like you?",
    ]

    def _get_system_prompt(self) -> str:
        return (
            "You are GAIA's bundled Example Agent — a working demonstration of a "
            "custom agent seeded by the installer. Explain plainly that you exist "
            "to show how custom agents are packaged and loaded, and point anyone "
            "who wants to build their own to "
            "https://amd-gaia.ai/docs/guides/custom-agent."
        )

    def _create_console(self) -> AgentConsole:
        return AgentConsole()

    def _register_tools(self) -> None:
        pass

Research Agent — RAG + file search

from gaia.agents.base.agent import Agent
from gaia.agents.base.console import AgentConsole
from gaia.agents.base.tools import _TOOL_REGISTRY
from gaia.agents.tools.rag_tools import RAGToolsMixin
from gaia.agents.tools.file_tools import FileSearchToolsMixin


class ResearchAgent(Agent, RAGToolsMixin, FileSearchToolsMixin):
    AGENT_ID = "research-agent"
    AGENT_NAME = "Research Agent"
    AGENT_DESCRIPTION = "Searches documents and files to answer questions"
    CONVERSATION_STARTERS = [
        "Summarize my project notes",
        "Find files related to...",
        "What does the documentation say about...?",
    ]

    def _get_system_prompt(self) -> str:
        return (
            "You are a thorough research assistant. When asked a question, "
            "first search available documents and files before answering. "
            "Always cite your sources."
        )

    def _create_console(self) -> AgentConsole:
        return AgentConsole()

    def _register_tools(self) -> None:
        _TOOL_REGISTRY.clear()
        self.register_rag_tools()
        self.register_file_search_tools()

Code Review Agent — shell + file I/O

from gaia.agents.base.agent import Agent
from gaia.agents.base.console import AgentConsole
from gaia.agents.base.tools import _TOOL_REGISTRY
from gaia.agents.tools.shell_tools import ShellToolsMixin
from gaia.agents.tools.file_io_tools import FileIOToolsMixin


class CodeReviewAgent(Agent, FileIOToolsMixin, ShellToolsMixin):
    AGENT_ID = "code-review-agent"
    AGENT_NAME = "Code Review Agent"
    AGENT_DESCRIPTION = "Reviews code and runs linters"

    def _get_system_prompt(self) -> str:
        return (
            "You are an expert code reviewer. You read files, run linters, "
            "and provide actionable feedback. Be specific about file names "
            "and line numbers. Prioritize correctness and security."
        )

    def _create_console(self) -> AgentConsole:
        return AgentConsole()

    def _register_tools(self) -> None:
        _TOOL_REGISTRY.clear()
        self.register_file_io_tools()
        self.register_shell_tools()

Troubleshooting

My agent doesn't appear in the selector

Ensure the directory is under ~/.gaia/agents/<id>/ and contains agent.py.
The directory name does not need to match the AGENT_ID class attribute, but it helps.
Check the server logs for warnings like Failed to load agent from ....
If you created the agent manually (not via the Builder), restart the GAIA server — discovery runs at boot. Agents created via the Builder Agent are loaded immediately without a restart.

Agent fails to load

Check the server logs for load errors. Ensure AGENT_ID, AGENT_NAME, and AGENT_DESCRIPTION are set as class attributes, and that the required _register_tools() method is implemented (_get_system_prompt() and _create_console() are optional overrides).

Imported agent doesn't appear or shows errors

The import response (UI status banner or CLI output) lists per-agent errors under errors[] — check those first.
Confirm each agent directory in the bundle contains an agent.py at its root. Bundles missing agent.py are rejected.
If requires_restart: true is reported, restart the GAIA server to pick up the new agent.
Bundles produced on a different GAIA version may reference imports that don’t exist locally — check the server logs for ImportError.

MCP server not connecting

Ensure npx or the MCP server command is installed and accessible in $PATH.
Check the server logs for MCP connection errors.
Test the MCP server standalone before adding it to your agent.

Agent uses wrong model

If your preferred model isn’t loaded on the Lemonade server, GAIA falls back to the server default. Run gaia init to download additional models.

The agent you built lives in ~/.gaia/agents/ — yours, on your machine. To let anyone install it from the Agent Hub (and PyPI/npm), package it as a hub agent and publish it through the curated PR route:

Package it

gaia agent init <id> scaffolds a publishable package under hub/agents/python/<id>/ — a gaia-agent.yaml manifest, your agent code, a README, and pyproject.toml. Move your agent.py logic in and fill the manifest.

Validate it

gaia agent test --lint checks the manifest and that the agent loads. Add tests and a README — both are required for review.

Open a PR

Commit the package under hub/agents/python/<id>/ and open a PR to amd/gaia. The PR route needs no token — maintainers review, and the automated pipeline publishes it to the Hub + PyPI on merge. (A direct-publish token route exists too, for maintainers.)

What’s required: a valid manifest, a README, tests, and passing review. The full contract — manifest fields, the four package parts, versioning + immutability, and both publish routes — is in the publishing guide.

Publishing guide → Hub + PyPI

The complete walkthrough: package layout, manifest, the no-token PR route vs direct token publish, requirements, and verification.

Claude Code skills

In the GAIA repo, the gaia-build-agent skill builds and the agent-hub-release skill cuts a frozen-binary + npm sidecar release (like the email agent). Invoke them with the Skill tool.

Next Steps

Agent System SDK

Deep dive into the base Agent class, tool registry, and state machine

MCP Integration

Connect any MCP server to extend your agent with external tools

GAIA Connectors

Give your agent permission to read Gmail, GitHub, Slack, and more — without baking API keys into code

RAG SDK

Add document Q&A to your agent with the RAG SDK

Agent UI Guide

Learn about the GAIA Agent UI and how agents are surfaced there

Custom Installer

Ship your agent pre-loaded in a branded, signed GAIA installer

Getting Started

C++ Framework

Python Framework

Overview

Quick Start: Gaia Builder Agent

Python Agent

Directory structure

Minimal Python agent

Adding built-in tools

Overriding the default model (optional)

Using GAIA connectors

Read the connectors guide

Export and import agents

From the Agent UI

From the CLI

What’s in the bundle

Security

Examples

Troubleshooting

Publishing guide → Hub + PyPI

Claude Code skills

Next Steps

Agent System SDK

MCP Integration

GAIA Connectors

RAG SDK

Agent UI Guide

Custom Installer

​Overview

​Quick Start: Gaia Builder Agent

​Python Agent

​Directory structure

​Minimal Python agent

​Adding built-in tools

​Overriding the default model (optional)

​Using GAIA connectors

Read the connectors guide

​Export and import agents

​From the Agent UI

​From the CLI

​What’s in the bundle

​Security

​Examples

​Troubleshooting

​Publish and share your agent

Publishing guide → Hub + PyPI

Claude Code skills

​Next Steps

Agent System SDK

MCP Integration

GAIA Connectors

RAG SDK

Agent UI Guide

Custom Installer

Overview

Quick Start: Gaia Builder Agent

Python Agent

Directory structure

Minimal Python agent

Adding built-in tools

Overriding the default model (optional)

Using GAIA connectors

Export and import agents

From the Agent UI

From the CLI

What’s in the bundle

Security

Examples

Troubleshooting

Publish and share your agent

Next Steps