AG-UI

AG-UI, the Agent-User Interaction Protocol, standardizes how AI agents connect to frontend applications.

Migration from Apps: For migration from AGUIApp, see the v2 migration guide for complete steps.

Example usage

Install backend dependencies

uv pip install 'agno[os,agui]' openai

Run the backend

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

basic.py

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)

Run the frontend

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

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

Chat with the Agno Agent

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

Additional examples are available in the cookbook.

Custom Events

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

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:

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 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 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 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 for updated interface patterns.

Get Started

AgentOS

Example Usage

Example usage

Custom Events

Core Components

`AGUI` interface

Initialization Parameters

Key Method

Endpoints

Authorization

Serving AgentOS

Parameters

​Example usage

​Custom Events

​Core Components

​AGUI interface

​Initialization Parameters

​Key Method

​Endpoints

​Authorization

​Serving AgentOS

​Parameters

Example usage

Custom Events

Core Components

`AGUI` interface

Initialization Parameters

Key Method

Endpoints

Authorization

Serving AgentOS

Parameters