> ## 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.
# Quickstart
> Run AI agents locally in minutes, or build your first custom agent
**Not a developer?** Start with the [Desktop Installer](/docs/guides/install) — one download, one double-click, and you're chatting with a GAIA agent in under 10 minutes. No terminal required.
Run AI agents **100% locally** on your AMD hardware — analyze documents, generate code, answer questions, and accomplish tasks on your PC without sending data to the cloud.
## Recommended: Desktop Installer
The **GAIA Agent UI** desktop app is the primary install path for end users. It ships as a native installer for Windows, macOS, and Linux, handles the Python backend setup automatically on first launch, and auto-updates.
Download the `.exe` NSIS installer
Download the `.dmg` (Apple Silicon)
Download the `.deb` or `.AppImage`
**See the full [Installation guide](/docs/guides/install)** for step-by-step instructions per platform, first-launch setup details, update and uninstall instructions, and privacy information. If something goes wrong, the [installation troubleshooting guide](/docs/reference/install-troubleshooting) covers every common failure mode.
After installing the desktop app, launch it and start chatting with agents right away — no terminal required. To **write your own** custom Python agent (the [Build Your First Agent](#build-your-first-agent) tutorial below), first complete one of the **developer install paths** in the next section: they create the Python environment and project directory that the tutorial saves your agent file into. The desktop app on its own doesn't provide a place to run a Python script.
***
## For developers
The rest of this page covers the **developer install paths** (npm CLI, pip, clone-and-install) for people who want to build agents, extend GAIA, or run it from source. End users should use the [desktop installer](/docs/guides/install) above.
### Agent UI (npm)
For developers who prefer npm and Node.js tooling. Ships the same Electron app as the desktop installer but driven from the command line.
```bash theme={null}
npm install -g @amd-gaia/agent-ui
```
Then run:
```bash theme={null}
gaia-ui
```
On first run, GAIA automatically installs the Python backend and all dependencies.
Requires [Node.js 20+](https://nodejs.org). If you don't have it:
* **Windows:** `winget install OpenJS.NodeJS.LTS`
* **macOS:** `brew install node@20`
* **Linux:** `curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - && sudo apt install -y nodejs`
See the [Agent UI guide](/docs/guides/agent-ui) for more details.
#### Update
```bash theme={null}
npm install -g @amd-gaia/agent-ui@latest
```
On next run, GAIA automatically updates the Python backend to match.
To install a specific version (current release is **v0.20.1**):
```bash theme={null}
npm install -g @amd-gaia/agent-ui@0.20.1
```
#### Uninstall
```bash theme={null}
npm uninstall -g @amd-gaia/agent-ui
rm -rf ~/.gaia
```
On Windows (PowerShell):
```powershell theme={null}
npm uninstall -g @amd-gaia/agent-ui
Remove-Item -Recurse -Force "$env:USERPROFILE\.gaia"
```
***
### CLI Install
**First time here?** Complete the [Setup](/docs/setup) guide first to install uv (Python package manager).
**Recommended for users** wanting to try the GAIA CLI.
Install GAIA globally with a single command:
Open **PowerShell** and run:
```powershell theme={null}
irm https://amd-gaia.ai/install.ps1 | iex
```
This will:
* ✅ Install `uv` (if not already installed)
* ✅ Download Python 3.12 (if needed)
* ✅ Create `%USERPROFILE%\.gaia\venv` virtual environment
* ✅ Install GAIA CLI (accessible globally via PATH)
* ✅ Add GAIA to your PATH
After installation, close and reopen your terminal, then run:
```powershell theme={null}
gaia init --profile minimal
```
Open a **terminal** and run:
```bash theme={null}
curl -fsSL https://amd-gaia.ai/install.sh | sh
```
This will:
* ✅ Install `uv` (if not already installed)
* ✅ Download Python 3.12 (if needed)
* ✅ Create `~/.gaia/venv` virtual environment
* ✅ Install GAIA CLI (accessible globally via PATH)
* ✅ Add GAIA to your PATH
After installation, reload your shell config, then run:
```bash theme={null}
source ~/.bashrc # or ~/.zshrc
gaia init --profile minimal
```
***
### Manual Install
**Recommended for developers** integrating GAIA into their projects.
Choose your platform and installation type:
Installs [amd-gaia](https://pypi.org/project/amd-gaia/) from PyPI in a project-specific virtual environment.
### Step 1: Create Project Directory
Open **PowerShell** and run:
```powershell theme={null}
mkdir my-gaia-project
```
```powershell theme={null}
cd my-gaia-project
```
### Step 2: Create Virtual Environment
```powershell theme={null}
uv venv .venv --python 3.12
```
uv will automatically download Python 3.12 if not already installed.
### Step 3: Activate the Environment
Windows users: run:
```powershell theme={null}
.\.venv\Scripts\Activate.ps1
```
Linux users: `source .venv/bin/activate`
If you see a script execution error, run this once:
```powershell theme={null}
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
```
Then retry the activation command.
You should see `(.venv)` in your terminal prompt when activated.
### Step 4: Install GAIA
```powershell theme={null}
uv pip install amd-gaia
```
**Optional extras:** `uv pip install "amd-gaia[talk,rag]"` for voice and document Q\&A features.
### Step 5: Verify Installation
```powershell theme={null}
gaia -v
```
### Step 6: Initialize GAIA
Install Lemonade Server and download models with a single command:
```powershell theme={null}
gaia init --profile minimal
```
Use `--profile chat` for the full experience (\~25GB), `--profile vlm` for vision/document extraction (\~3GB), or `--profile minimal` for a quick start (\~400MB).
See [CLI Reference](/docs/reference/cli#init-command) for all profiles.
Installs [amd-gaia](https://pypi.org/project/amd-gaia/) from PyPI in a project-specific virtual environment.
### Step 1: Create Project Directory
Open a **terminal** and run:
```bash theme={null}
mkdir my-gaia-project
```
```bash theme={null}
cd my-gaia-project
```
### Step 2: Create Virtual Environment
```bash theme={null}
uv venv .venv --python 3.12
```
uv will automatically download Python 3.12 if not already installed.
### Step 3: Activate the Environment
```bash theme={null}
source .venv/bin/activate
```
You should see `(.venv)` in your terminal prompt when activated.
### Step 4: Install GAIA
**Linux users:** GAIA depends on PyTorch (via `transformers` package). Always use `--extra-index-url` to install CPU-only PyTorch and avoid large CUDA packages (\~2GB → \~200MB).
```bash theme={null}
uv pip install amd-gaia --extra-index-url https://download.pytorch.org/whl/cpu
```
**Optional extras:** Add `[talk,rag]` for voice and document Q\&A features:
```bash theme={null}
uv pip install "amd-gaia[talk,rag]" --extra-index-url https://download.pytorch.org/whl/cpu
```
### Step 5: Verify Installation
```bash theme={null}
gaia -v
```
### Step 6: Initialize GAIA
Install Lemonade Server and download models with a single command:
```bash theme={null}
gaia init --profile minimal
```
Use `--profile chat` for the full experience (\~25GB), `--profile vlm` for vision/document extraction (\~3GB), or `--profile minimal` for a quick start (\~400MB).
See [CLI Reference](/docs/reference/cli#init-command) for all profiles.
For contributors. Clones [amd/gaia](https://github.com/amd/gaia) from GitHub.
**Requires:** [Git for Windows](https://git-scm.com/download/win) must be installed.
### Step 1: Clone the Repository
Open **PowerShell** and run:
```powershell theme={null}
git clone https://github.com/amd/gaia.git
```
```powershell theme={null}
cd gaia
```
### Step 2: Create Virtual Environment
```powershell theme={null}
uv venv .venv --python 3.12
```
uv will automatically download Python 3.12 if not already installed.
### Step 3: Activate the Environment
Windows users: run:
```powershell theme={null}
.\.venv\Scripts\Activate.ps1
```
Linux users: `source .venv/bin/activate`
If you see a script execution error, run this once:
```powershell theme={null}
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
```
Then retry the activation command.
You should see `(.venv)` in your terminal prompt when activated.
### Step 4: Install in Editable Mode
```powershell theme={null}
uv pip install -e ".[dev]"
```
**With all extras:** `uv pip install -e ".[dev,talk,rag]"` for voice and document Q\&A features.
### Step 5: Verify Installation
```powershell theme={null}
gaia -v
```
Changes to GAIA source code will take effect immediately without reinstalling.
### Step 6: Initialize GAIA
Install Lemonade Server and download models with a single command:
```powershell theme={null}
gaia init --profile minimal
```
Use `--profile chat` for the full experience (\~25GB), `--profile vlm` for vision/document extraction (\~3GB), or `--profile minimal` for a quick start (\~400MB).
See [CLI Reference](/docs/reference/cli#init-command) for all profiles.
For contributors. Clones [amd/gaia](https://github.com/amd/gaia) from GitHub.
**Requires:** Git must be installed (`sudo apt install git`).
### Step 1: Clone the Repository
Open a **terminal** and run:
```bash theme={null}
git clone https://github.com/amd/gaia.git
```
```bash theme={null}
cd gaia
```
### Step 2: Create Virtual Environment
```bash theme={null}
uv venv .venv --python 3.12
```
uv will automatically download Python 3.12 if not already installed.
### Step 3: Activate the Environment
```bash theme={null}
source .venv/bin/activate
```
You should see `(.venv)` in your terminal prompt when activated.
### Step 4: Install in Editable Mode
**Linux users:** GAIA depends on PyTorch (via `transformers` package). Always use `--extra-index-url` to install CPU-only PyTorch and avoid large CUDA packages (\~2GB → \~200MB).
```bash theme={null}
uv pip install -e ".[dev]" --extra-index-url https://download.pytorch.org/whl/cpu
```
**With all extras:** Add `[talk,rag]` for voice and document Q\&A features:
```bash theme={null}
uv pip install -e ".[dev,talk,rag]" --extra-index-url https://download.pytorch.org/whl/cpu
```
### Step 5: Verify Installation
```bash theme={null}
gaia -v
```
Changes to GAIA source code will take effect immediately without reinstalling.
### Step 6: Initialize GAIA
Install Lemonade Server and download models with a single command:
```bash theme={null}
gaia init --profile minimal
```
Use `--profile chat` for the full experience (\~25GB), `--profile vlm` for vision/document extraction (\~3GB), or `--profile minimal` for a quick start (\~400MB).
See [CLI Reference](/docs/reference/cli#init-command) for all profiles.
**Having issues?** Check the [Troubleshooting](/docs/reference/troubleshooting) guide, [create an issue](https://github.com/amd/gaia/issues) on GitHub, or contact us at [gaia@amd.com](mailto:gaia@amd.com).
***
## Build Your First Agent
Make sure your virtual environment is still activated (you should see `(.venv)` in your prompt). If commands aren't working as expected, try prefixing them with [`uv run`](https://docs.astral.sh/uv/reference/cli/#uv-run).
Using your text editor, create a file named `my_agent.py` in the project directory you created during install — `my-gaia-project` for the PyPI paths, or the cloned `gaia` folder for the clone paths. This is the same folder where you ran `uv venv` and activated `(.venv)`.
```python theme={null}
import platform
from datetime import datetime
from gaia.agents.base.agent import Agent
from gaia.agents.base.tools import tool
class MyAgent(Agent):
"""A simple agent that can report system information."""
def _get_system_prompt(self) -> str:
return """You are a system monitoring assistant.
When users ask about time or system details, use the get_system_info tool."""
def _register_tools(self):
@tool
def get_system_info() -> dict:
"""Get current time, date, platform, and Python version."""
return {
"time": datetime.now().strftime("%H:%M:%S"),
"date": datetime.now().strftime("%Y-%m-%d"),
"platform": platform.system(),
"python": platform.python_version()
}
# Use the agent. model_id pins the ~4B model that `gaia init` already
# downloaded; omit it and the agent base defaults to a much larger model
# that won't fit on most machines.
agent = MyAgent(model_id="Gemma-4-E4B-it-GGUF")
result = agent.process_query("What time is it and what system am I on?")
print(result.get("result"))
```
**Why `model_id`?** Without it, the `Agent` base class defaults to a large
\~20GB model that `gaia init --profile minimal` never downloaded — on a typical
16–32GB machine it fails to load with `failed to fit params to free device
memory`. `Gemma-4-E4B-it-GGUF` is the tool-calling model every `gaia init`
profile installs, so it's already on disk and runs comfortably.
**View full source:** [`agent.py`](https://github.com/amd/gaia/blob/main/src/gaia/agents/base/agent.py) · [`tools.py`](https://github.com/amd/gaia/blob/main/src/gaia/agents/base/tools.py)
**Run it** (in your terminal/PowerShell):
```
python my_agent.py
```
First run may take a moment while GAIA starts Lemonade Server and loads the LLM.
You'll see the agent thinking, creating a plan, and executing the tool:
```
🤖 Processing: 'What time is it and what system am I on?'
...
🔧 Executing operation
Tool: get_system_info
✅ Tool execution complete
{
"time": "15:03:26",
"date": "2025-12-17",
"platform": "Windows",
"python": "3.12.12"
}
...
✨ Processing complete!
```
Final output (will vary based on your system):
```
The current time is 15:03:26 and you are on a Windows system running Python 3.12.12.
```
**It works!** The agent called the `get_system_info` tool and returned real data from your system.
**Tip:** The tool's docstring is how the LLM knows what the tool does. Be descriptive!
`"""Get current time, date, platform, and Python version."""` tells the LLM this tool can answer time-related questions.
***
## How It Works
### The Agent Base Class
The `Agent` class handles the core loop: receiving queries, calling the LLM, executing tools, and returning responses. You extend it by defining:
* **`_get_system_prompt()`** — Instructions that shape the agent's behavior
* **`_register_tools()`** — Functions the agent can call to take actions
### System Prompt
The system prompt tells your agent who it is and how to make decisions. You define it by returning a string:
```python theme={null}
def _get_system_prompt(self) -> str:
return """You are a system monitoring assistant.
When users ask about time or system details, use the get_system_info tool."""
```
For agents, a good prompt includes:
* **Role**: What the agent specializes in — *"You are a code review assistant..."*
* **Tool guidance**: When to use tools vs. respond directly — *"Use the search tool for questions about files..."*
* **Style**: Tone and boundaries — *"Be concise. Only answer questions about this codebase."*
The system prompt and tools work together: the prompt shapes *how* the agent reasons, while tools define *what* it can do.
### Tools
Tools are just Python functions with the `@tool` decorator:
```python theme={null}
@tool
def get_system_info() -> dict:
"""Get current time, date, platform, and Python version."""
return {"time": "14:32:05", "platform": "Windows", ...}
```
The LLM automatically sees all registered tools and their docstrings. When you ask a question, it decides which tools (if any) to call based on their descriptions. **That's it** — no configuration, no routing logic. Just write functions and the agent knows what it can do.
### The Agent Loop
When you call `agent.process_query("What time is it?")`, GAIA runs an iterative loop:
The LLM receives your query plus the system prompt and available tools. It decides what to do next.
If the LLM decides to use a tool, GAIA executes it and captures the result.
The tool result is sent back to the LLM, which can then decide to call another tool or respond.
When the LLM has enough information, it generates a natural language response for the user.
This loop continues until the LLM decides it has a complete answer. Complex tasks may involve multiple tool calls before responding.
***
## What's Next?
You've built a simple agent. Now let's build something practical: an agent that analyzes your system hardware and recommends which LLMs you can run locally.
Build an agent that detects your hardware and recommends which LLMs you can run locally.
### More Playbooks
Build a document Q\&A agent with RAG capabilities
Build an agent that generates and validates code projects
Step-by-step tutorials for building real-world agents
### Guides & Reference
Pre-built agents for chat, voice, code, Jira, Docker, and more
Use MCP to connect your agent to GitHub, databases, filesystems, and hundreds more
Complete API documentation for all components
Command-line tools for chat, voice, RAG, and more
Learn GAIA terminology: agents, tools, RAG, NPU, and more
Testing, linting, and contributing to GAIA
**Stuck?** Join our [Discord](https://discord.com/channels/1392562559122407535/1402013282495102997) or [create an issue](https://github.com/amd/gaia/issues) on GitHub.
***
**License**
Copyright(C) 2024-2026 Advanced Micro Devices, Inc. All rights reserved.
SPDX-License-Identifier: MIT