# amd/gaia architecture

> Architecture diagram of the GitHub repository amd/gaia, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/amd/gaia
- Repository: https://github.com/amd/gaia

## Overview

GAIA is a local-first AI agent framework and desktop application for building and using tool-enabled agents. The principal workflow is a user request entering through the UI or API, being handled by an agent that can invoke tools and local or optional cloud models, and returning a response. Major documented branches include RAG, voice, vision, MCP, plugins, and the C++ framework. The graph reflects README claims and the supplied source index; unsampled subsystems are represented at their documented boundaries, and unsupported internal links are omitted.

Main entry points: [`src/gaia/agents/base/agent.py`](https://github.com/amd/gaia/blob/main/src/gaia/agents/base/agent.py) (Agent framework), [`src/gaia/agents/base/tools.py`](https://github.com/amd/gaia/blob/main/src/gaia/agents/base/tools.py) (Tool orchestration), [`src/gaia/agents/base/readiness.py`](https://github.com/amd/gaia/blob/main/src/gaia/agents/base/readiness.py) (Runtime readiness), [`src/gaia/llm/lemonade_manager.py`](https://github.com/amd/gaia/blob/main/src/gaia/llm/lemonade_manager.py) (Lemonade manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_desktop["Desktop UI<br/>[App.tsx]"]
  node_api["Agent API<br/>[app.py]"]
end

subgraph group_agents["Agent runtime"]
  node_agent["Agent framework<br/>[agent.py]"]
  node_tools["Tool orchestration<br/>[tools.py]"]
  node_memory["Agent memory<br/>[memory.py]"]
  node_readiness["Runtime readiness<br/>[readiness.py]"]
  node_config["Configuration<br/>[config.py]"]
  node_logger["Logging<br/>[logger.py]"]
end

subgraph group_inference["Models and inference"]
  node_llm["LLM gateway<br/>[gateway.py]"]
  node_lemonade["Lemonade client<br/>[lemonade_client.py]"]
  node_manager["Lemonade manager"]
  node_embedded["Embedded inference"]
end

subgraph group_capabilities["Agent capabilities"]
  node_rag["Document RAG<br/>[rag_tools.py]"]
  node_voice["Voice processing<br/>[audio_client.py]"]
  node_vision["Image understanding<br/>[file_io_tools.py]"]
  node_skills["Skills system<br/>[format.py]"]
  node_skill_audit["Skill auditing<br/>[engine.py]"]
end

subgraph group_extensions["Extensions"]
  node_connectors["Connectors<br/>[api.py]"]
  node_mcp["MCP integration"]
  node_plugins["Agent registry<br/>[registry.py]"]
  node_cpp["C++ framework<br/>[agent.cpp]"]
end

node_user(("User"))
node_result["Agent response"]

node_user -->|"submits request"| node_desktop
node_user -->|"submits request"| node_api
node_desktop -.->|"uses API"| node_api
node_api -.->|"routes request"| node_agent
node_agent -->|"orchestrates tools"| node_tools
node_agent -->|"uses memory"| node_memory
node_agent -->|"checks readiness"| node_readiness
node_agent -.->|"requests inference"| node_llm
node_llm -->|"uses client"| node_lemonade
node_manager -->|"manages client"| node_lemonade
node_manager -->|"starts backend"| node_embedded
node_readiness -->|"checks service"| node_lemonade
node_readiness -->|"checks startup"| node_manager
node_tools -->|"offers document search"| node_rag
node_tools -.->|"offers voice tools"| node_voice
node_tools -.->|"offers image tools"| node_vision
node_agent -.->|"loads skills"| node_skills
node_skill_audit -->|"audits format"| node_skills
node_tools -.->|"accesses integrations"| node_connectors
node_tools -->|"uses MCP tools"| node_mcp
node_plugins -->|"discovers agents"| node_agent
node_agent -->|"returns response"| node_result
node_user -->|"embeds framework"| node_cpp

click node_desktop "https://github.com/amd/gaia/blob/main/src/gaia/apps/webui/src/App.tsx"
click node_api "https://github.com/amd/gaia/blob/main/src/gaia/api/app.py"
click node_agent "https://github.com/amd/gaia/blob/main/src/gaia/agents/base/agent.py"
click node_tools "https://github.com/amd/gaia/blob/main/src/gaia/agents/base/tools.py"
click node_memory "https://github.com/amd/gaia/blob/main/src/gaia/agents/base/memory.py"
click node_readiness "https://github.com/amd/gaia/blob/main/src/gaia/agents/base/readiness.py"
click node_config "https://github.com/amd/gaia/blob/main/src/gaia/config.py"
click node_logger "https://github.com/amd/gaia/blob/main/src/gaia/logger.py"
click node_llm "https://github.com/amd/gaia/blob/main/src/gaia/llm/gateway.py"
click node_lemonade "https://github.com/amd/gaia/blob/main/src/gaia/llm/lemonade_client.py"
click node_manager "https://github.com/amd/gaia/blob/main/src/gaia/llm/lemonade_manager.py"
click node_embedded "https://github.com/amd/gaia/blob/main/src/gaia/llm/lemonade_embedded.py"
click node_rag "https://github.com/amd/gaia/blob/main/src/gaia/agents/tools/rag_tools.py"
click node_voice "https://github.com/amd/gaia/blob/main/src/gaia/audio/audio_client.py"
click node_vision "https://github.com/amd/gaia/blob/main/src/gaia/agents/tools/file_io_tools.py"
click node_skills "https://github.com/amd/gaia/blob/main/src/gaia/skills/format.py"
click node_skill_audit "https://github.com/amd/gaia/blob/main/src/gaia/skills/audit/engine.py"
click node_connectors "https://github.com/amd/gaia/blob/main/src/gaia/connectors/api.py"
click node_mcp "https://github.com/amd/gaia/blob/main/src/gaia/mcp/client/mcp_client_manager.py"
click node_plugins "https://github.com/amd/gaia/blob/main/src/gaia/agents/registry.py"
click node_cpp "https://github.com/amd/gaia/blob/main/cpp/src/agent.cpp"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_desktop,node_api,node_user toneBlue
class node_agent,node_tools,node_memory,node_readiness,node_config,node_logger toneAmber
class node_llm,node_lemonade,node_manager,node_embedded toneMint
class node_rag,node_voice,node_vision,node_skills,node_skill_audit toneRose
class node_connectors,node_mcp,node_plugins,node_cpp,node_result toneIndigo
```

## Components

### User interfaces

- [Desktop UI](https://github.com/amd/gaia/blob/main/src/gaia/apps/webui/src/App.tsx): `src/gaia/apps/webui/src/App.tsx`
- [Agent API](https://github.com/amd/gaia/blob/main/src/gaia/api/app.py): `src/gaia/api/app.py`

### Agent runtime

- [Agent framework](https://github.com/amd/gaia/blob/main/src/gaia/agents/base/agent.py): `src/gaia/agents/base/agent.py`
- [Tool orchestration](https://github.com/amd/gaia/blob/main/src/gaia/agents/base/tools.py): `src/gaia/agents/base/tools.py`
- [Agent memory](https://github.com/amd/gaia/blob/main/src/gaia/agents/base/memory.py): `src/gaia/agents/base/memory.py`
- [Runtime readiness](https://github.com/amd/gaia/blob/main/src/gaia/agents/base/readiness.py): `src/gaia/agents/base/readiness.py`
- [Configuration](https://github.com/amd/gaia/blob/main/src/gaia/config.py): `src/gaia/config.py`
- [Logging](https://github.com/amd/gaia/blob/main/src/gaia/logger.py): `src/gaia/logger.py`

### Models and inference

- [LLM gateway](https://github.com/amd/gaia/blob/main/src/gaia/llm/gateway.py): `src/gaia/llm/gateway.py`
- [Lemonade client](https://github.com/amd/gaia/blob/main/src/gaia/llm/lemonade_client.py): `src/gaia/llm/lemonade_client.py`
- [Lemonade manager](https://github.com/amd/gaia/blob/main/src/gaia/llm/lemonade_manager.py): `src/gaia/llm/lemonade_manager.py`
- [Embedded inference](https://github.com/amd/gaia/blob/main/src/gaia/llm/lemonade_embedded.py): `src/gaia/llm/lemonade_embedded.py`

### Agent capabilities

- [Document RAG](https://github.com/amd/gaia/blob/main/src/gaia/agents/tools/rag_tools.py): `src/gaia/agents/tools/rag_tools.py`
- [Voice processing](https://github.com/amd/gaia/blob/main/src/gaia/audio/audio_client.py): `src/gaia/audio/audio_client.py`
- [Image understanding](https://github.com/amd/gaia/blob/main/src/gaia/agents/tools/file_io_tools.py): `src/gaia/agents/tools/file_io_tools.py`
- [Skills system](https://github.com/amd/gaia/blob/main/src/gaia/skills/format.py): `src/gaia/skills/format.py`
- [Skill auditing](https://github.com/amd/gaia/blob/main/src/gaia/skills/audit/engine.py): `src/gaia/skills/audit/engine.py`

### Extensions

- [Connectors](https://github.com/amd/gaia/blob/main/src/gaia/connectors/api.py): `src/gaia/connectors/api.py`
- [MCP integration](https://github.com/amd/gaia/blob/main/src/gaia/mcp/client/mcp_client_manager.py): `src/gaia/mcp/client/mcp_client_manager.py`
- [Agent registry](https://github.com/amd/gaia/blob/main/src/gaia/agents/registry.py): `src/gaia/agents/registry.py`
- [C++ framework](https://github.com/amd/gaia/blob/main/cpp/src/agent.cpp): `cpp/src/agent.cpp`

### Other components

- **User**
- **Agent response**

## Connections

- User → Desktop UI: submits request (evidence: `README.md`)
- User → Agent API: submits request (evidence: `README.md`)
- Desktop UI → Agent API: uses API
- Agent API → Agent framework: routes request
- Agent framework → Tool orchestration: orchestrates tools (evidence: `README.md`)
- Agent framework → Agent memory: uses memory (evidence: `hub/agents/chat/python/gaia_agent_chat/agent.py`)
- Agent framework → Runtime readiness: checks readiness (evidence: `src/gaia/agents/base/readiness.py`)
- Agent framework → LLM gateway: requests inference
- LLM gateway → Lemonade client: uses client (evidence: `src/gaia/llm/lemonade_client.py`)
- Lemonade manager → Lemonade client: manages client (evidence: `src/gaia/llm/lemonade_manager.py`)
- Lemonade manager → Embedded inference: starts backend (evidence: `src/gaia/llm/lemonade_manager.py`)
- Runtime readiness → Lemonade client: checks service (evidence: `src/gaia/agents/base/readiness.py`)
- Runtime readiness → Lemonade manager: checks startup (evidence: `src/gaia/agents/base/readiness.py`)
- Tool orchestration → Document RAG: offers document search (evidence: `README.md`)
- Tool orchestration → Voice processing: offers voice tools
- Tool orchestration → Image understanding: offers image tools
- Agent framework → Skills system: loads skills
- Skill auditing → Skills system: audits format (evidence: `src/gaia/skills/audit/engine.py`)
- Tool orchestration → Connectors: accesses integrations
- Tool orchestration → MCP integration: uses MCP tools (evidence: `README.md`)
- Agent registry → Agent framework: discovers agents (evidence: `README.md`)
- Agent framework → Agent response: returns response (evidence: `README.md`)
- User → C++ framework: embeds framework (evidence: `README.md`)