> ## Documentation Index
> Fetch the complete documentation index at: https://agno-v2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# AG-UI

> Expose Agno agents via the AG-UI protocol

AG-UI, the [Agent-User Interaction Protocol](https://github.com/ag-ui-protocol/ag-ui), standardizes how AI agents connect to frontend applications.

> [!NOTE]
>
> **Migration from Apps**: For migration from `AGUIApp`, see the [v2 migration guide](https://agno-v2.mintlify.site/other/v2-migration.md#8-apps-interfaces) for complete steps.

## Example usage

**1. Install backend dependencies**

```bash theme={null}
uv pip install 'agno[os,agui]' openai
```

**2. Run the backend**

Expose an Agno agent through the AG-UI interface using `AgentOS` and `AGUI`.

```python basic.py theme={null}
from agno.agent.agent import Agent
from agno.models.openai import OpenAIResponses
from agno.os import AgentOS
from agno.os.interfaces.agui import AGUI

chat_agent = Agent(model=OpenAIResponses(id="gpt-5.4"))

agent_os = AgentOS(agents=[chat_agent], interfaces=[AGUI(agent=chat_agent)])
app = agent_os.get_app()

if __name__ == "__main__":
    agent_os.serve(app="basic:app", reload=True)
```

**3. Run the frontend**

Use Dojo (`ag-ui`'s frontend) as an advanced, customizable interface for AG-UI agents.

1. Clone: `git clone https://github.com/ag-ui-protocol/ag-ui.git`
2. Install dependencies from the repository root: `pnpm install`
3. Build Dojo and its dependencies (including the Agno package): `pnpm build --filter=demo-viewer`
4. Start Dojo following the instructions in the repository.

**4. Chat with the Agno Agent**

With Dojo running, open `http://localhost:3000` and select the Agno agent.

Additional examples are available in the [cookbook](https://github.com/agno-agi/agno/tree/main/cookbook/05_agent_os/16_agui).

## Custom Events

Custom events created in tools are automatically delivered to AG-UI in the AG-UI custom event format.

**Creating custom events:**

```python theme={null}
from dataclasses import dataclass
from typing import Optional

from agno.run.agent import CustomEvent

@dataclass
class CustomerProfileEvent(CustomEvent):
    customer_name: Optional[str] = None
    customer_email: Optional[str] = None
```

**Yielding from tools:**

```python theme={null}
from agno.tools import tool

@tool()
async def get_customer_profile(customer_id: str):
    customer = fetch_customer(customer_id)

    yield CustomerProfileEvent(
        customer_name=customer["name"],
        customer_email=customer["email"],
    )

    yield f"Profile retrieved for {customer['name']}"
```

Custom events are streamed in real-time to the AG-UI frontend.

See [Custom Events documentation](https://agno-v2.mintlify.site/agents/running-agents.md#custom-events) for more details.

## Core Components

* `AGUI` (interface): Wraps an Agno `Agent` or `Team` into an AG-UI compatible FastAPI router.
* `AgentOS.serve`: Serves the FastAPI app (including the AGUI router) with Uvicorn.

`AGUI` mounts protocol-compliant routes on the app.

## `AGUI` interface

Main entry point for AG-UI exposure.

### Initialization Parameters

| Parameter | Type | Default | Description |
| - | - | - | - |
| `agent` | `Optional[Union[Agent, RemoteAgent]]` | `None` | Agno `Agent` or `RemoteAgent` instance. |
| `team` | `Optional[Union[Team, RemoteTeam]]` | `None` | Agno `Team` or `RemoteTeam` instance. |
| `prefix` | `str` | `""` | Route prefix (e.g., `/chat`, `/web-research`). |
| `tags` | `Optional[List[str]]` | `["AGUI"]` | OpenAPI tags for the router. |

Provide `agent` or `team`.

### Key Method

| Method | Parameters | Return Type | Description |
| - | - | - | - |
| `get_router` | None | `APIRouter` | Returns the AG-UI FastAPI router and attaches endpoints. |

## Endpoints

Mounted at the interface's route prefix (root by default):

* `POST /agui`: Main entrypoint. Accepts `RunAgentInput` from `ag-ui-protocol`. Streams AG-UI events.
* `GET /status`: Health/status endpoint for the interface.

Refer to `ag-ui-protocol` docs for payload details.

## Authorization

With [authorization](https://agno-v2.mintlify.site/agent-os/security/authorization/overview.md) enabled, `POST /agui` requires the run scope for the interface's bound entity: `agents:run` for an agent, `teams:run` for a team. Send the JWT as `Authorization: Bearer <token>`. `GET /status` requires a valid token but no scope.

For anonymous callers, `forwardedProps.user_id` attributes the run to a user. Authenticated callers are pinned to their token's principal, and a client-supplied `user_id` is ignored. See [Scopes](https://agno-v2.mintlify.site/agent-os/security/authorization/scopes.md) for the full route-to-scope mapping.

## Serving AgentOS

Use `AgentOS.serve` to run the app with Uvicorn.

### Parameters

| Parameter | Type | Default | Description |
| - | - | - | - |
| `app` | `Union[str, FastAPI]` | required | FastAPI app instance or import string. |
| `host` | `str` | `"localhost"` | Host to bind. Override with `AGENT_OS_HOST` env var. |
| `port` | `int` | `7777` | Port to bind. Override with `AGENT_OS_PORT` env var. |
| `reload` | `bool` | `False` | Enable auto-reload for development. |
| `reload_includes` | `Optional[List[str]]` | `None` | File patterns to watch for auto-reload. |
| `reload_excludes` | `Optional[List[str]]` | `None` | File patterns to exclude from reload. |
| `workers` | `Optional[int]` | `None` | Number of Uvicorn worker processes. |
| `access_log` | `bool` | `False` | Enable Uvicorn access logging. |

See [cookbook examples](https://github.com/agno-agi/agno/tree/main/cookbook/05_agent_os/16_agui) for updated interface patterns.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.