AG-UI (Agent-User Interaction) Integration - AG2

AG-UI

Overview

The Agent-User Interaction (AG-UI) protocol standardizes how frontend applications communicate with agents. In AG2, ag2.ag_ui.AGUIStream bridges an Agent 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:

Streaming text events (TEXT_MESSAGE_START, TEXT_MESSAGE_CONTENT, TEXT_MESSAGE_END, TEXT_MESSAGE_CHUNK)
Backend tool lifecycle events (TOOL_CALL_START, TOOL_CALL_ARGS, TOOL_CALL_RESULT, TOOL_CALL_END)
Frontend-tool dispatch (TOOL_CALL_CHUNK for client tools in RunAgentInput.tools)
Shared-state snapshots (STATE_SNAPSHOT) from context and agent state
Human input checkpoints (input_required surfaced as user-visible message events)

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
`<br> 1<br> 2<br> 3<br> 4<br> 5<br> 6<br> 7<br> 8<br> 9<br>10<br>11<br>12<br>13<br>14<br>15<br>16<br>17<br>18<br>19<br>20<br>21<br>22<br>23<br>24<br>25<br>`

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.


`<br>1<br>2<br>3<br>4<br>5<br>6<br>`	`<br>from ag2.ag_ui import AGUIStream<br>from fastapi import FastAPI<br>app = FastAPI()<br>stream = AGUIStream(agent)<br>app.mount("/chat", stream.build_asgi())<br>`

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:

AG2 Dojo - agentic_chat

Next steps

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