AG-UI

Expose Agno agents via the AG-UI protocol

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

1. Install backend dependencies

   uv pip install ag-ui-protocol
   
2. 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.5"))
   
   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 in /ag-ui/typescript-sdk: pnpm install
   3. Build the Agno package in /ag-ui/integrations/agno: pnpm run build
   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.

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 agno.run.agent import CustomEvent

@dataclass
class CustomerProfileEvent(CustomEvent):
    customer_name: str
    customer_email: str

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"],
    )
    
    return 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.

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. Auto-adds *.yaml, *.yml.
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.