Custom Agents

~/.gaia/agents/
└── my-agent/
    └── agent.yaml        # required

manifest_version: 1
id: my-agent
name: My Agent
instructions: You are a helpful assistant.

manifest_version: 1

# Unique ID used internally (lowercase letters, numbers, hyphens only)
id: weather-agent

# Display name shown in the UI agent selector
name: Weather Agent

# One-line description shown as a tooltip
description: An agent that provides weather updates

# System prompt — defines your agent's personality and behavior
instructions: |
  You are a cheerful weather forecaster who always relates topics back
  to the current weather. When you don't know the actual weather, make
  a playful estimate based on the season.

  Be concise, friendly, and always sign off with a weather pun.

# Tools that give your agent extra capabilities.
# Available: rag, file_search, file_io, shell, screenshot, sd, vlm
# Omit this field to get the defaults: [rag, file_search]
tools: []

# Preferred models — first available model is used at runtime.
# Omit to use the server's current default model.
models:
  - Qwen3.5-35B-A3B-GGUF
  - Qwen3-0.6B-GGUF

# Suggestion chips shown on the welcome screen for this agent.
conversation_starters:
  - "What's the weather like today?"
  - "Tell me a weather fun fact"
  - "What should I wear tomorrow?"

# MCP (Model Context Protocol) servers — each entry is a subprocess
# that provides additional tools to your agent.
# mcp_servers:
#   time:
#     command: npx
#     args: ["-y", "@anthropic/mcp-time-server"]
#
#   weather:
#     command: npx
#     args: ["-y", "@anthropic/mcp-weather-server"]
#     env:
#       WEATHER_API_KEY: "your-api-key-here"

~/.gaia/agents/
└── my-python-agent/
    ├── agent.py          # required — Python takes precedence over YAML
    └── agent.yaml        # optional — used only for the `models` field

from gaia.agents.base.agent import Agent
from gaia.agents.base.console import AgentConsole
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 _create_console(self) -> AgentConsole:
        return AgentConsole()

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

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