​

GAIA SDK Reference

​

What is GAIA?

• Answer questions by searching through documents
• Process images and extract information
• Interact with databases
• Respond to voice commands
• Automate workflows
• And much more!

• Developers building custom AI agents
• Teams creating specialized AI workflows
• Researchers experimenting with AI applications
• Anyone wanting to run AI locally on AMD hardware

• 🏠 Privacy: Everything runs on your machine
• ⚡ Speed: AMD NPU/iGPU acceleration
• 🔧 Flexibility: Build exactly what you need
• 📦 Distribution: Share agents via pip install

​

How This Documentation Works

• 📖 What it does - High-level purpose
• 🎯 When to use it - Common use cases
• 💻 Code examples - Working, copy-paste ready code
• ⚠️ Important notes - Gotchas and best practices

1. Quick Start - Build your first agent in 5 minutes
2. Core Agent System - Understand the foundation
3. Complete Examples - See real-world patterns

​

Quick Start

​

Understanding AI Agents

User input → Your code → Output

User input → LLM decides what to do → Calls your tools → LLM formats output → User gets answer

• Users talk naturally: “Find customers in Texas and email them”
• LLM breaks it down: Use search_customers tool, then send_email tool
• Your code just provides the tools, LLM orchestrates them
• No complex if/else logic needed!

​

Installation

# Install uv if you don't have it
curl -LsSf https://astral.sh/uv/install.sh | sh  # Linux
# or
irm https://astral.sh/uv/install.ps1 | iex  # Windows PowerShell

# Install GAIA
uv pip install amd-gaia

• Python 3.10 or higher
• Lemonade Server running (for local LLM inference)
  Copy

  # Start Lemonade Server
  lemonade-server serve
  

• ⚡ 10-100x faster than pip
• 🔒 Better dependency resolution
• 📦 Recommended by GAIA team

​

Your First Agent (5 Minutes)

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

class MyAgent(Agent):
    """Custom agent for my use case."""

    # Step 1: Tell the agent its purpose
    def _get_system_prompt(self) -> str:
        return "You are a helpful assistant that can search and analyze data."

    # Step 2: Choose how to display output
    def _create_console(self):
        from gaia.agents.base.console import AgentConsole
        return AgentConsole()  # Rich CLI output with colors

    # Step 3: Define tools the agent can use
    def _register_tools(self):
        @tool
        def search_data(query: str) -> dict:
            """Search for data matching the query."""
            # Your implementation here
            # This is what actually gets called when LLM decides to search
            return {"results": ["item1", "item2"], "count": 2}

        @tool
        def analyze_data(data_id: str) -> dict:
            """Analyze a specific data item."""
            # Your implementation here
            return {"analysis": "Data is valid", "confidence": 0.95}

# Step 4: Use the agent
if __name__ == "__main__":
    agent = MyAgent()

    # User talks naturally
    result = agent.process_query("Search for user data and analyze it")

    # LLM automatically:
    # 1. Calls search_data("user")
    # 2. Calls analyze_data("item1")
    # 3. Formats a natural response

    print(result)

1. You defined tools (search_data, analyze_data)
2. You described the agent’s personality (system prompt)
3. The agent automatically figured out which tools to call and in what order
4. The LLM orchestrated the workflow based on user’s natural language

​

What’s Next?

​

Core Concepts

• Agent System - Foundation of all GAIA agents
• Tools - Registering agent capabilities
• Console - Output handling and display

​

SDKs

• Chat SDK - Conversational AI with memory
• MCP Client - Connect to external tools via Model Context Protocol
• LLM Integration - Working with language models
• Vision Models - Image understanding

​

User Guides

• Document Q&A - RAG-powered document search and retrieval
• Voice Interaction - Speech-to-text and text-to-speech
• Agent Routing - Multi-agent orchestration
• API Server - OpenAI-compatible API

​

Advanced Topics

• Tool Mixins - Reusable tool collections
• Code Mixins - Development tool sets

​

Guides & Resources

• Configuration - Environment and settings
• Testing - Testing your agents
• Security - Security best practices
• Best Practices - Code organization and patterns
• Complete Examples - Full working examples
• Advanced Patterns - Complex use cases
• Troubleshooting - Common issues and solutions

​

Get Help

• GitHub Issues - Bug reports and features
• Discord Community - Chat with developers
• Email: [email protected]

​

License