Skip to content

AG-UI

Overview#

The Agent-User Interaction (AG-UI) protocol standardizes how frontend applications communicate with agents. In AG2, autogen.ag_ui.AGUIStream bridges a ConversableAgent to AG-UI event streams.

This solves common integration problems:

  • Streaming agent output to UI clients
  • Emitting tool-call lifecycle events
  • Synchronizing shared state snapshots
  • Supporting human-in-the-loop checkpoints through frontend actions and input-required flows

For protocol background, see AG-UI Protocol introduction.

When to use AG-UI vs direct integration#

Approach Use it when Trade-offs
AG-UI integration (AGUIStream) You need streaming UI, tool rendering, shared state sync, and a protocol-compatible client ecosystem Adds protocol event semantics you need to expose from your endpoint
Direct integration (custom REST/WebSocket contract) You only need a narrow, app-specific API and will own protocol design end-to-end You must define and maintain your own streaming/tool/state contract

Use AG-UI when you want a reusable UI contract across clients and frameworks.

Supported capabilities#

Verified AG-UI features are supported in AG2:

Installation#

Install AG2 with AG-UI support:

pip install "ag2[ag-ui]"

Basic server example#

Use the manual-dispatch pattern when you want full control over auth, logging, and middleware:

run_ag_ui.py
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
from fastapi import FastAPI, Header
from fastapi.responses import StreamingResponse

from autogen import ConversableAgent, LLMConfig
from autogen.ag_ui import AGUIStream, RunAgentInput

agent = ConversableAgent(
    name="support_bot",
    system_message="You help users with billing questions.",
    llm_config=LLMConfig({"model": "gpt-4o-mini"}),
)

stream = AGUIStream(agent)
app = FastAPI()

@app.post("/chat")
async def run_agent(
    message: RunAgentInput,
    accept: str | None = Header(None),
) -> StreamingResponse:
    return StreamingResponse(
        stream.dispatch(message, accept=accept),
        media_type=accept or "text/event-stream",
    )

Run it:

uvicorn run_ag_ui:app --reload --port 8000

Simpler way

If you want to use ASGI endpoint without additional logic, you can use the AGUIStream.build_asgi() method to build an ASGI endpoint and mount it to your ASGI application.

1
2
3
4
5
6
from autogen.ag_ui import AGUIStream
from fastapi import FastAPI

app = FastAPI()
stream = AGUIStream(agent)
app.mount("/chat", stream.build_asgi())

Test the endpoint#

curl -N -X POST http://127.0.0.1:8000/chat \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "thread_id": "thread-1",
    "run_id": "run-1",
    "messages": [{"id": "m1", "role": "user", "content": "Hello"}],
    "state": {},
    "context": [],
    "tools": []
  }'

Example stream (truncated):

data: {"type":"RUN_STARTED","threadId":"thread-1","runId":"run-1",...}
data: {"type":"TEXT_MESSAGE_CHUNK","delta":"Hello! How can I help?",...}
data: {"type":"RUN_FINISHED","threadId":"thread-1","runId":"run-1",...}

Rich UI with A2UIAgent#

A2UIAgent extends AG-UI with support for the A2UI protocol, enabling agents to generate structured UI components (cards, forms, buttons, images) instead of plain text. See the dedicated A2UI page for setup details, or the full A2UIAgent reference for configuration, validation, actions, and A2A integration.

UI clients#

Any AG-UI client works with this endpoint.

For React/Next.js UIs, CopilotKit is the recommended client path in AG2 docs because it provides:

  • Streaming chat components
  • Tool UI rendering hooks/components
  • Shared state patterns for interactive workflows

Start from the CopilotKit UI quickstart.

AG-UI Dojo#

For protocol-level testing and event inspection, use the AG2 Dojo profile:

Next steps#

  1. Build the AG-UI endpoint from the minimal example above.
  2. Follow the CopilotKit UI quickstart to connect a React/Next.js client.
  3. Validate runtime behavior with the AG2 Dojo - agentic_chat.