AG-UI

Expose Agno agents and teams over the AG-UI protocol for streaming frontends.

The AG-UI interface exposes an Agno agent or team over the Agent-User Interaction Protocol, a streaming event protocol that frontends like CopilotKit and Dojo consume.

Migrating from AGUIApp? See the v2 migration guide.

Setup

Follow the AG-UI setup guide to run the backend and connect a frontend.

Install the AG-UI dependencies: uv pip install 'agno[agui]'

Required configuration:

• OPENAI_API_KEY, or a key for whichever model provider you use.
• A frontend pointed at the {prefix}/agui endpoint. Use Dojo for local development.

AG-UI uses no tokens, OAuth, or signing secrets. The protocol endpoint is open by default.

Example Usage

Agent

basic.py

from agno.agent import Agent
from agno.models.openai import OpenAIResponses
from agno.os import AgentOS
from agno.os.interfaces.agui import AGUI

chat_agent = Agent(
    name="Assistant",
    model=OpenAIResponses(id="gpt-5.4"),
    instructions="You are a helpful AI assistant.",
    add_datetime_to_context=True,
    markdown=True,
)

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, port=9001)

Team

research_team.py

from agno.agent import Agent
from agno.models.openai import OpenAIResponses
from agno.os import AgentOS
from agno.os.interfaces.agui import AGUI
from agno.team import Team
from agno.tools.websearch import WebSearchTools

researcher = Agent(
    name="researcher",
    role="Research Assistant",
    model=OpenAIResponses(id="gpt-5.4"),
    tools=[WebSearchTools()],
)

writer = Agent(
    name="writer",
    role="Content Writer",
    model=OpenAIResponses(id="gpt-5.4"),
)

research_team = Team(
    name="research_team",
    members=[researcher, writer],
    instructions="Use the researcher to gather information, then the writer to create content.",
)

agent_os = AgentOS(
    teams=[research_team],
    interfaces=[AGUI(team=research_team)],
)
app = agent_os.get_app()

if __name__ == "__main__":
    agent_os.serve(app="research_team:app", reload=True, port=9001)

See more examples including agents with tools, reasoning, and teams.

The examples serve on port 9001, which Dojo expects. See the setup guide to run a frontend.

Sessions & State

AG-UI frontends send a thread_id, optional state, and the full message history with every request. The interface maps these to Agno and uses only the latest user message, letting the agent manage history through its session database.

AG-UI field	Maps to	Purpose
thread_id	session_id	Each thread is a separate conversation.
state	session_state	Shared state available to the agent during the run.
forwarded_props.user_id	user_id	Per-user memory and history.

Configure a database on the agent or team to persist history across restarts.

Reasoning

Reasoning streams to the frontend as AG-UI reasoning events. Native reasoning models and the ReasoningTools toolkit are both supported.

See the reasoning agent example.

Structured Output

Set output_schema to a Pydantic model to return typed output. The structured result streams to the frontend as content.

See the structured output example.

Frontend Tools

Tools marked external_execution=True run on the frontend instead of the backend. The interface streams the tool call to the client, the client executes it, and the result returns on the next request.

from agno.tools import tool

@tool(external_execution=True)
def generate_haiku(topic: str) -> str:
    """Generate a haiku and display it in the frontend."""
    return "Haiku generated and displayed in frontend"

Add external_execution_silent=True to suppress the assistant’s “I have tools to execute” message for cleaner UX.

See the agent with tools example.

Custom Events

Tools can yield custom events, which the interface delivers to the frontend in the AG-UI custom event format.

from dataclasses import dataclass
from agno.run.agent import CustomEvent
from agno.tools import tool

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

@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']}"

See Custom Events for details.

Multiple Instances

Run multiple agents or teams on one server by giving each AGUI interface a different prefix:

agent_os = AgentOS(
    agents=[chat_agent, research_agent],
    interfaces=[
        AGUI(agent=chat_agent, prefix="/chat"),
        AGUI(agent=research_agent, prefix="/web-research"),
    ],
)

Each instance mounts its own {prefix}/agui and {prefix}/status endpoints.

Security

The AG-UI endpoint is open by default and sets permissive CORS headers (Access-Control-Allow-Origin: *). It performs no signature verification or authentication.

Add authentication and restrict CORS before exposing the endpoint in production. The defaults suit local development with Dojo.

Troubleshooting

ImportError: ag_ui not installed

Cause: The AG-UI protocol package is missing.

Fix: Install it with uv pip install 'agno[agui]'.

Frontend cannot reach the backend

Cause: Port mismatch. Dojo runs on http://localhost:3000 and expects the backend on port 9001.

Fix: Serve the backend with agent_os.serve(app=..., port=9001) and confirm the frontend points at http://localhost:9001.

No streaming output in the frontend

Cause: The frontend is not reading the event stream, or a proxy is buffering it.

Fix: Confirm the request hits POST {prefix}/agui and that any proxy passes text/event-stream through without buffering.

CORS errors in the browser console

Cause: A proxy or gateway is stripping the interface’s CORS headers.

Fix: The interface sets Access-Control-Allow-Origin: * by default. Confirm your deployment layer preserves these headers.

Developer Resources

Setup Guide

Run the backend and connect a Dojo frontend step by step.

Interface Reference

Parameters, endpoints, and the Agno to AG-UI event map.

Deploy Guide

Serve the protocol endpoint for frontend integration.

Usage Examples

Tools, reasoning, structured output, teams, and multiple instances.