Skip to content

agent-ui.mdx

Latest commit

 

History

History
326 lines (235 loc) · 9.53 KB

agent-ui.mdx

File metadata and controls

326 lines (235 loc) · 9.53 KB
title Agent UI
description Your personal AI that lives on your PC — private, fast, and entirely yours
icon desktop

Ask your PC to find that contract you downloaded last month. Drop in a spreadsheet and get an instant analysis. Search across thousands of files in seconds. GAIA Agent UI puts a local AI agent in your browser — one that sees your files, understands your documents, and never sends a byte to the cloud.

{/* TODO: Add demo video — upload to assets.amd-gaia.ai then uncomment:

Two commands to get started:

npm install -g @amd-gaia/agent-ui
gaia-ui

Everything installs automatically — Python, the AI model, the backend. No accounts, no API keys, no cloud. Just your machine.

What You Can Do

Find Anything on Your PC

Ask the agent to locate files across your drives — by name, type, content, or recency. No more digging through folder trees.

"Find all Python files in my Downloads folder"

"Show me the largest files on my Desktop"

"Search my project for files that import pandas"

The agent searches your common folders first, then offers a deep search across all drives if nothing turns up.

Analyze Any Document

Drag files into the chat — or just ask the agent to find them. It indexes the content and lets you ask questions, extract data, compare sections, or get summaries. Works with:

Category Formats
Documents PDF, Word, PowerPoint, Excel, TXT, Markdown
Data CSV, JSON, XML, YAML, HTML
Code Python, JavaScript, TypeScript, Java, C/C++, Go, Rust, Ruby, Shell
Config INI, CFG, TOML

"Summarize this PDF in 3 bullet points"

"Compare these two contracts and list the differences"

"What's the total spend in this expense report?"

Install

The npm package handles everything — on first run it auto-installs Python, the GAIA backend, Lemonade Server, and a minimal model. 
**Requires:** [Node.js 18+](https://nodejs.org) (`winget install OpenJS.NodeJS.LTS` on Windows, `brew install node@20` on macOS)

```bash
npm install -g @amd-gaia/agent-ui
gaia-ui
```

The Agent UI opens automatically at [http://localhost:4200](http://localhost:4200).

| Flag | Description |
|------|-------------|
| `gaia-ui --port 8080` | Custom port |
| `gaia-ui --no-open` | Don't auto-open the browser |
| `gaia-ui --serve` | Serve frontend only (Node.js static server) |
| `gaia-ui --version` | Show version |

**Update:**

```bash
npm install -g @amd-gaia/agent-ui@latest
```
If you already have GAIA installed via pip/uv: 
```bash
gaia --ui
```

Or equivalently: `gaia chat --ui`

The Agent UI starts on [http://localhost:4200](http://localhost:4200).

| Flag | Description |
|------|-------------|
| `gaia --ui --ui-port 8080` | Custom port |
| `gaia --ui --base-url http://192.168.1.100:8000/api/v1` | Connect to Lemonade on another machine |

<Note>
  If you see a missing dependencies error, install the UI extras:

  ```bash
  uv pip install "amd-gaia[ui]"
  ```
</Note>

**Prerequisites (Python path only):**

The Python CLI path requires you to set up the backend manually:

```bash
gaia init --profile chat    # Downloads Lemonade Server + model (~25 GB)
lemonade-server serve       # Start the LLM server
```

Use `--profile minimal` for a smaller download (~400 MB).

Uninstall

```bash npm uninstall -g @amd-gaia/agent-ui ``` 
To also remove all GAIA data (sessions, config, downloaded models):

```bash
# macOS / Linux
rm -rf ~/.gaia

# Windows (PowerShell)
Remove-Item -Recurse -Force "$env:USERPROFILE\.gaia"
```
```bash uv pip uninstall amd-gaia ``` 
To also remove all GAIA data:

```bash
# macOS / Linux
rm -rf ~/.gaia

# Windows (PowerShell)
Remove-Item -Recurse -Force "$env:USERPROFILE\.gaia"
```

Sessions and Shortcuts

Sessions let you organize conversations by topic. They sync between the CLI (gaia chat) and the Agent UI — start in one, pick up in the other. Export any session as Markdown or JSON from the session menu.

Shortcut Action
Enter Send message
Shift+Enter New line
Escape Stop agent response
Ctrl+K Search across sessions

Extend with MCP

The agent supports the Model Context Protocol in both directions — connect external tools to expand what the agent can do, or expose the Agent UI itself so other AI tools can drive it.

Connect GitHub, Slack, databases, and more via MCP servers Let Claude Code, Cursor, or any MCP client control GAIA agents Misconfigured MCP servers can cause slow responses. If you experience timeouts, check `~/.gaia/mcp_servers.json` and remove any servers you don't need. See [Troubleshooting](#llm-response-times-out-or-fails) for details.

Troubleshooting

```bash lemonade-server serve ``` 
If not installed, run `gaia init --profile minimal` or follow the [Setup Guide](/setup).
```bash gaia download --agent chat ``` ```bash # npm CLI gaia-ui --port 8080 
# Python CLI
gaia --ui --ui-port 8080
```
Close any other GAIA Agent UI or CLI instances. Only one writer at a time is supported. - Ensure the file is a supported format and not password-protected - Keep file size under 100MB - For PDF image extraction, download the VLM model: `gaia download --agent chat` If you see "I wasn't able to generate a response" errors, check your MCP server configuration. Misconfigured or unreachable MCP servers cause the agent to wait up to 10 seconds per server before responding. 
Check your config:

```bash
# macOS / Linux
cat ~/.gaia/mcp_servers.json

# Windows (PowerShell)
Get-Content "$env:USERPROFILE\.gaia\mcp_servers.json"
```

If it contains servers you don't recognize or aren't running, either remove them or reset the file:

```json
{ "mcpServers": {} }
```

You can also manage MCP servers through the Agent UI settings panel or with the CLI:

```bash
gaia mcp status
```

Architecture

%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#ED1C24', 'primaryTextColor':'#fff', 'primaryBorderColor':'#C8171E', 'lineColor':'#F4484D', 'secondaryColor':'#2d2d2d', 'tertiaryColor':'#f5f5f5', 'fontFamily': 'system-ui, -apple-system, sans-serif'}}}%%
flowchart TD
    A(["Agent UI (Browser or Electron)"]) --> B(["FastAPI Backend · port 4200"])
    B --> C(["GAIA Core SDKs"])
    C --> D(["Lemonade Server · port 8000"])

    B -.- E(["REST API + SSE Streaming"])
    B -.- F(["SQLite Database"])
    C -.- G(["Agent · RAGSDK · LemonadeClient"])
    D -.- H(["Model Serving (NPU / iGPU)"])

    style A fill:#f8f9fa,stroke:#dee2e6,stroke-width:2px,color:#495057
    style B fill:#ED1C24,stroke:#C8171E,stroke-width:2px,color:#fff
    style C fill:#F4484D,stroke:#ED1C24,stroke-width:2px,color:#fff
    style D fill:#2d2d2d,stroke:#1a1a1a,stroke-width:2px,color:#fff
    style E fill:#f8f9fa,stroke:#dee2e6,stroke-width:1px,color:#6c757d
    style F fill:#f8f9fa,stroke:#dee2e6,stroke-width:1px,color:#6c757d
    style G fill:#f8f9fa,stroke:#dee2e6,stroke-width:1px,color:#6c757d
    style H fill:#f8f9fa,stroke:#dee2e6,stroke-width:1px,color:#6c757d

    linkStyle 0,1,2 stroke:#ED1C24,stroke-width:2px
    linkStyle 3,4,5,6 stroke:#dee2e6,stroke-width:1px,stroke-dasharray:5
Loading

For the REST API reference and backend classes, see the Agent UI SDK Reference.

Next Steps

REST endpoints, database schema, and Python backend API CLI-based document agent with RAG, debug mode, and chunking strategies Create a custom agent with tools in minutes Connect Claude Code, Cursor, or any MCP client to the Agent UI
**Hardware:** Tested on AMD Ryzen AI MAX+ 395 with Qwen3.5-35B-A3B-GGUF via Lemonade Server. Other configurations may work — [report issues here](https://github.com/amd/gaia/issues/new).

License

Copyright(C) 2024-2026 Advanced Micro Devices, Inc. All rights reserved.

SPDX-License-Identifier: MIT