# 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](https://docs.ag-ui.com/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](https://docs.copilotkit.ai/ag2/generative-ui/backend-tools) (`TOOL_CALL_START`, `TOOL_CALL_ARGS`, `TOOL_CALL_RESULT`, `TOOL_CALL_END`)
- [Frontend-tool dispatch](https://docs.copilotkit.ai/ag2/generative-ui/frontend-tools) (`TOOL_CALL_CHUNK` for client tools in `RunAgentInput.tools`)
- [Shared-state snapshots](https://docs.copilotkit.ai/ag2/shared-state) (`STATE_SNAPSHOT`) from context and agent state
- [Human input checkpoints](https://docs.copilotkit.ai/ag2/human-in-the-loop) (`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>``` | ```<br>from fastapi import FastAPI, Header<br>from fastapi.responses import StreamingResponse<br>from autogen import ConversableAgent, LLMConfig<br>from autogen.ag_ui import AGUIStream, RunAgentInput<br>agent = ConversableAgent(<br>    name="support_bot",<br>    system_message="You help users with billing questions.",<br>    llm_config=LLMConfig({"model": "gpt-4o-mini"}),<br>)<br>stream = AGUIStream(agent)<br>app = FastAPI()<br>@app.post("/chat")<br>async def run_agent(<br>    message: RunAgentInput,<br>    accept: str | None = Header(None),<br>) -> StreamingResponse:<br>    return StreamingResponse(<br>        stream.dispatch(message, accept=accept),<br>        media_type=accept or "text/event-stream",<br>    )<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 autogen.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",...}
```

## 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](https://docs.ag2.ai/0.13.3/docs/user-guide/ag-ui/a2ui/) for setup details, or the full [A2UIAgent reference](https://docs.ag2.ai/0.13.3/docs/user-guide/reference-agents/a2uiagent/) 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](https://docs.ag2.ai/0.13.3/docs/user-guide/ag-ui/copilotkit-quickstart).

## AG-UI Dojo

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

- [AG2 Dojo - agentic_chat](https://dojo.ag-ui.com/ag2/feature/agentic_chat)

## Next steps

1. Build the AG-UI endpoint from the minimal example above.
2. Follow the [CopilotKit UI quickstart](https://docs.ag2.ai/0.13.3/docs/user-guide/ag-ui/copilotkit-quickstart) to connect a React/Next.js client.
3. Validate runtime behavior with the [AG2 Dojo - agentic_chat](https://dojo.ag-ui.com/ag2/feature/agentic_chat).