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",...}

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.