Skip to main content
AG-UI, the Agent-User Interaction Protocol, standardizes how AI agents connect to front-end applications.
Migration from Apps: If you’re migrating from AGUIApp, see the v2 migration guide for complete steps.

​
Example usage

1

Install backend dependencies

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 OpenAIChat
from agno.os import AgentOS
from agno.os.interfaces.agui import AGUI

chat_agent = Agent(model=OpenAIChat(id="gpt-4o"))

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 your Agno Agent

With Dojo running, open http://localhost:3000 and select your Agno agent.
You can see more in our cookbook examples.

​
Custom Events

Custom events you create in your 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 your FastAPI app (including the AGUI router) with Uvicorn.
AGUI mounts protocol-compliant routes on your app.

​
AGUI interface

Main entry point for AG-UI exposure.

​
Initialization Parameters

ParameterTypeDefaultDescription
agentOptional[Agent]NoneAgno Agent instance.
teamOptional[Team]NoneAgno Team instance.
Provide agent or team.

​
Key Method

MethodParametersReturn TypeDescription
get_routeruse_async: bool = TrueAPIRouterReturns 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 your AgentOS

Use AgentOS.serve to run your app with Uvicorn.

​
Parameters

ParameterTypeDefaultDescription
appUnion[str, FastAPI]requiredFastAPI app instance or import string.
hoststr"localhost"Host to bind.
portint7777Port to bind.
reloadboolFalseEnable auto-reload for development.
See cookbook examples for updated interface patterns.
⌘I