ag2-ag-ui

AG-UI integration

When to use

• The user is building a web UI (React / Next.js / anything HTTP+SSE) that should talk to an AG2 agent.
• They want streaming text, reasoning, tool-call rendering, shared state sync, or sub-task step tracking surfaced to the frontend with a standard protocol — not a custom REST/WebSocket contract.
• They're using or considering CopilotKit (the recommended React client).

For a custom narrow-purpose API where you own the contract end-to-end, skip AG-UI and write a plain endpoint instead.

Supported AG-UI features

Feature	Status
Run lifecycle (RUN_STARTED / RUN_FINISHED / RUN_ERROR)	✓
Streaming text events (TEXT_MESSAGE_START / _CONTENT / _END / _CHUNK)	✓
Reasoning events (REASONING_START / _END, REASONING_MESSAGE_START / _CONTENT / _END)	✓
Backend tool lifecycle (TOOL_CALL_START / _ARGS / _RESULT / _END)	✓
Frontend-tool dispatch (TOOL_CALL_CHUNK for client tools in RunAgentInput.tools)	✓
Shared-state snapshots (STATE_SNAPSHOT)	✓
Sub-task steps (STEP_STARTED / STEP_FINISHED, emitted on TaskStarted / TaskCompleted)	✓
Human input checkpoints surfaced as AG-UI events	✗ — no human-input event family; hitl_hook passes through to agent.ask

Installation

pip install "ag2[ag-ui]"

Required. Run this install before delivering the code. If you cannot run commands, state the exact pip install command.

60-second recipe — FastAPI server

from fastapi import FastAPI, Header
from fastapi.responses import StreamingResponse

from ag2 import Agent
from ag2.ag_ui import AGUIStream, RunAgentInput
from ag2.config import OpenAIConfig

agent = Agent(
    name="support_bot",
    prompt="You help users with billing questions.",
    config=OpenAIConfig(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",
    )