> ## 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.

# API Server

<Info>
  **Source Code:** [`src/gaia/api/`](https://github.com/amd/gaia/blob/main/src/gaia/api/)
</Info>

<Note>
  **Import:** `from gaia.api.openai_server import app`
</Note>

***

**Detailed Spec:** [spec/api-server](/docs/spec/api-server)

## 7.1 OpenAI-Compatible API

**Purpose:** Expose GAIA agents as OpenAI-compatible REST API.

```python theme={null}
from gaia.api.openai_server import app
import uvicorn

# Run server (app is a module-level FastAPI instance)
uvicorn.run(app, host="0.0.0.0", port=8080)

# Now accessible via the OpenAI SDK:
# from openai import OpenAI
# client = OpenAI(base_url="http://localhost:8080/v1", api_key="dummy")
# response = client.chat.completions.create(
#     model="gaia-code",
#     messages=[{"role": "user", "content": "Write Python code"}]
# )
```

<Note>
  **Port 8080 is shared by default with `gaia mcp docker`.** Run one of them on a
  different port (e.g. `gaia api start --port 8081`) if you need both alive at
  the same time.
</Note>

***

## 7.2 Custom API Agent

**Import:** `from gaia.agents.base.api_agent import ApiAgent`

`ApiAgent` is a mixin that already subclasses the core `Agent`; you only need to
inherit from `ApiAgent`:

```python theme={null}
from gaia.agents.base.api_agent import ApiAgent
from gaia.agents.base.tools import tool

class MyAPIAgent(ApiAgent):
    """Agent exposed via OpenAI-compatible API."""

    def get_model_id(self) -> str:
        # Model ID shown in /v1/models
        return "my-custom-agent"

    def get_model_info(self) -> dict:
        return {
            "max_input_tokens": 4096,
            "max_output_tokens": 2048,
            "description": "Custom agent for data analysis",
            "capabilities": ["data_analysis", "visualization"],
        }

    def _get_system_prompt(self) -> str:
        return "You are a data analysis assistant."

    def _register_tools(self):
        @tool
        def analyze(data: str) -> dict:
            """Analyze data."""
            return {"analysis": "Data is valid"}
```

### Registering new agents with the server

The API server exposes a **static registry** of agent models at
`src/gaia/api/agent_registry.py`, not a runtime `register()` API. To add a new
model, append an entry to `AGENT_MODELS`:

```python theme={null}
# src/gaia/api/agent_registry.py
AGENT_MODELS = {
    "gaia-code": {
        "class_name": "gaia_agent_routing.agent.RoutingAgent",
        "init_params": {
            "api_mode": True,
            "silent_mode": True,
            "streaming": False,
            "max_steps": 100,
        },
        "description": "Intelligent routing agent ...",
    },
    # 👇 New entry
    "my-agent": {
        "class_name": "my_package.my_agent.MyAPIAgent",
        "init_params": {"api_mode": True, "silent_mode": True},
        "description": "Custom agent for data analysis",
    },
}
```

The server imports `class_name` lazily on the first request. `init_params` are
passed to the agent's constructor; `gaia api start --debug`, `--show-prompts`,
`--streaming`, and `--step-through` inject `GAIA_API_*` env-vars that the
registry merges into `init_params` at startup.

<Note>
  Runtime plug-in discovery is on the roadmap (see
  [`src/gaia/agents/registry.py`](https://github.com/amd/gaia/blob/main/src/gaia/agents/registry.py)),
  but the OpenAI-compatible server still requires editing `AGENT_MODELS` and
  restarting the process.
</Note>

***

## 7.3 SSE Streaming

**Import:** `from gaia.api.sse_handler import SSEOutputHandler`

```python theme={null}
from gaia.api.sse_handler import SSEOutputHandler

# Create SSE handler
sse = SSEOutputHandler()

# Use with agent (parameter name is output_handler, not console)
agent = MyAgent(output_handler=sse)

# Process query — events are pushed as they happen
result = agent.process_query("Generate code")
```

### Events emitted

The API-layer `SSEOutputHandler` emits a strict subset used for OpenAI-style
chat completions: `chunk` (streamed token deltas) and `answer` (final message).
The Agent UI uses a richer handler in `src/gaia/ui/sse_handler.py` that emits
additional events — `tool_start`, `tool_end`, `tool_result`, `thinking`,
`processing`, `error`. When wiring SSE through the Agent UI routers you will see
both surfaces.

```json theme={null}
// Example payloads emitted by src/gaia/ui/sse_handler.py
{"event": "tool_start", "data": {"name": "generate_code", "args": {...}}}
{"event": "tool_result", "data": {"name": "generate_code", "result": {...}}}
{"event": "answer", "data": {"text": "Here's the code..."}}
```

***

## Related Topics

* [Core Agent System](../core/agent-system) - Learn about the base Agent class
* [MCP Integration](./mcp) - Model Context Protocol support
* [Specialized Agents](../agents/specialized) - Pre-built agent implementations
* [Application Packaging](../packaging) - Package agents for distribution

***

<small style="color: #666;">
  **License**

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

  SPDX-License-Identifier: MIT
</small>