ag2-ag-ui

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

AG-UI integration

AG-UI集成

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.

用户正在构建一个Web UI（React / Next.js / 任何支持HTTP+SSE的框架），需要与AG2 Agent交互。
他们希望通过标准协议向前端提供流式文本、推理过程、工具调用渲染、共享状态同步或子任务步骤跟踪功能，而非自定义REST/WebSocket协议。
他们正在使用或考虑使用CopilotKit（推荐的React客户端）。

如果是自定义的专用API，且你完全掌控协议两端，则无需使用AG-UI，直接编写普通端点即可。

Supported AG-UI features

支持的AG-UI功能

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`

功能	状态
运行生命周期（ `RUN_STARTED` / `RUN_FINISHED` / `RUN_ERROR` ）	✓
流式文本事件（ `TEXT_MESSAGE_START` / `_CONTENT` / `_END` / `_CHUNK` ）	✓
推理事件（ `REASONING_START` / `_END` , `REASONING_MESSAGE_START` / `_CONTENT` / `_END` ）	✓
后端工具生命周期（ `TOOL_CALL_START` / `_ARGS` / `_RESULT` / `_END` ）	✓
前端工具调度（针对 `RunAgentInput.tools` 中的客户端工具的 `TOOL_CALL_CHUNK` ）	✓
共享状态快照（ `STATE_SNAPSHOT` ）	✓
子任务步骤（ `STEP_STARTED` / `STEP_FINISHED` ，在 `TaskStarted` / `TaskCompleted` 时触发）	✓
作为AG-UI事件呈现的人工输入检查点	✗ — 无人工输入事件系列； `hitl_hook` 直接传递给 `agent.ask`

Installation

安装

bash

pip install "ag2[ag-ui]"

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

bash

pip install "ag2[ag-ui]"

必须执行。在交付代码前运行此安装命令。如果无法执行命令，请明确说明
pip install
的具体指令。

60-second recipe — FastAPI server

60秒快速实现 — FastAPI服务器

python

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",
    )

bash

uvicorn run_ag_ui:app --reload --port 8000

Test:

bash

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

python

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",
    )

bash

uvicorn run_ag_ui:app --reload --port 8000

测试：

bash

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

Lower-friction alternative —

build_asgi()

更简便的替代方案 —

build_asgi()

If you don't need custom auth / middleware, mount the ASGI endpoint directly:

python

from ag2.ag_ui import AGUIStream
from fastapi import FastAPI

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

如果不需要自定义认证/中间件，可以直接挂载ASGI端点：

python

from ag2.ag_ui import AGUIStream
from fastapi import FastAPI

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

CopilotKit frontend (recommended for React / Next.js)

CopilotKit前端（推荐用于React / Next.js）

Two ways to start:

bash

undefined

两种启动方式：

bash

undefined

Option A — CopilotKit bootstrap

选项A — CopilotKit快速初始化

npx copilotkit@latest create -f ag2

Option B — clone the reference starter

选项B — 克隆参考启动模板

https://github.com/ag2ai/ag2-copilotkit-starter


The starter layout:

ag2-copilotkit-starter/ ├── agent-py/ # Python backend (AG2 + AG-UI) └── ui-react/ # React + CopilotKit frontend


Backend serves `/chat` on port 8008 by default. The Next.js route at `ui-react/app/api/copilotkit/route.ts` bridges the UI to the backend:

```tsx
import { HttpAgent } from "@ag-ui/client";
import { CopilotRuntime, ExperimentalEmptyAdapter, copilotRuntimeNextJSAppRouterEndpoint } from "@copilotkit/runtime";
import { NextRequest } from "next/server";

const agent = new HttpAgent({ url: "http://localhost:8008/chat" });
const runtime = new CopilotRuntime({ agents: { weather_agent: agent } });

export async function POST(req: NextRequest) {
  const { handleRequest } = copilotRuntimeNextJSAppRouterEndpoint({
    runtime,
    serviceAdapter: new ExperimentalEmptyAdapter(),
    endpoint: "/api/copilotkit",
  });
  return handleRequest(req);
}

Wrap your app:

tsx

import { CopilotKit } from "@copilotkit/react-core";
import "@copilotkit/react-ui/styles.css";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <CopilotKit agent="weather_agent" runtimeUrl="/api/copilotkit">
          {children}
        </CopilotKit>
      </body>
    </html>
  );
}

Render chat (

<CopilotChat />

), and use

useCopilotAction({...})

in client components to render generative UI tied to backend tool calls.


启动模板结构：

ag2-copilotkit-starter/ ├── agent-py/ # Python后端（AG2 + AG-UI） └── ui-react/ # React + CopilotKit前端


后端默认在8008端口提供`/chat`服务。Next.js路由`ui-react/app/api/copilotkit/route.ts`负责将UI与后端连接：

```tsx
import { HttpAgent } from "@ag-ui/client";
import { CopilotRuntime, ExperimentalEmptyAdapter, copilotRuntimeNextJSAppRouterEndpoint } from "@copilotkit/runtime";
import { NextRequest } from "next/server";

const agent = new HttpAgent({ url: "http://localhost:8008/chat" });
const runtime = new CopilotRuntime({ agents: { weather_agent: agent } });

export async function POST(req: NextRequest) {
  const { handleRequest } = copilotRuntimeNextJSAppRouterEndpoint({
    runtime,
    serviceAdapter: new ExperimentalEmptyAdapter(),
    endpoint: "/api/copilotkit",
  });
  return handleRequest(req);
}

包装你的应用：

tsx

import { CopilotKit } from "@copilotkit/react-core";
import "@copilotkit/react-ui/styles.css";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <CopilotKit agent="weather_agent" runtimeUrl="/api/copilotkit">
          {children}
        </CopilotKit>
      </body>
    </html>
  );
}

渲染聊天组件（

<CopilotChat />

），并在客户端组件中使用

useCopilotAction({...})

渲染与后端工具调用关联的生成式UI。

Production checklist

生产环境检查清单

CORS — allow your frontend origin on the AG-UI backend (
```
POST
```
,
```
OPTIONS
```
, auth headers).
Auth — protect both
```
/api/copilotkit
```
(Next.js route) and backend
```
/chat
```
. Don't rely on client-only secrets.
SSE buffering — verify backend response is
```
Content-Type: text/event-stream
```
and that proxy layers (Nginx, CloudFront, etc.) don't buffer SSE.
Timeouts / retries — conservative values for long-running tool workflows; only retry idempotent requests.
Tool inputs are untrusted — validate and authorize server-side before invoking privileged tools. Log tool execution with request IDs.
Tool name parity — frontend
```
useCopilotAction
```
```
name
```
must match backend
```
@tool
```
name exactly.

CORS — 在AG-UI后端允许你的前端源（支持
```
POST
```
、
```
OPTIONS
```
及认证头）。
认证 — 保护
```
/api/copilotkit
```
（Next.js路由）和后端
```
/chat
```
端点。不要依赖仅客户端的密钥。
SSE缓冲 — 验证后端响应的
```
Content-Type
```
为
```
text/event-stream
```
，且代理层（Nginx、CloudFront等）不会缓冲SSE。
超时/重试 — 针对长时间运行的工具流程设置保守值；仅重试幂等请求。
工具输入不可信 — 在调用特权工具前，在服务器端验证并授权。使用请求ID记录工具执行情况。
工具名称一致性 — 前端
```
useCopilotAction
```
中的
```
name
```
必须与后端
```
@tool
```
的名称完全匹配。

Going deeper

深入学习

website/docs/user-guide/ag-ui/index.mdx

—

AGUIStream

, supported events, basic server.

```
website/docs/user-guide/ag-ui/copilotkit-quickstart.mdx
```
— full React + CopilotKit walkthrough (file layout, route, layout, chat component, weather-card example).
AG-UI protocol: https://docs.ag-ui.com/introduction
Reference starter: https://github.com/ag2ai/ag2-copilotkit-starter
For protocol-level testing: AG2 Dojo profile https://dojo.ag-ui.com/ag2/feature/agentic_chat

```
website/docs/user-guide/ag-ui/index.mdx
```
— 介绍
```
AGUIStream
```
、支持的事件及基础服务器配置。
```
website/docs/user-guide/ag-ui/copilotkit-quickstart.mdx
```
— 完整的React + CopilotKit入门指南（文件结构、路由、布局、聊天组件、天气卡片示例）。
AG-UI协议文档：https://docs.ag-ui.com/introduction
参考启动模板：https://github.com/ag2ai/ag2-copilotkit-starter
协议级测试：AG2 Dojo配置文件 https://dojo.ag-ui.com/ag2/feature/agentic_chat

Common pitfalls

常见陷阱

Missing
ag-ui
extra —

pip install "ag2[ag-ui]"

is required; without it

from ag2.ag_ui import AGUIStream

will fail.

CORS blocked — frontend can't hit the backend in dev. Add
```
CORSMiddleware
```
to the FastAPI app for the dev origin.
No streaming output — proxy or
```
Content-Type
```
issue. Test with raw
```
curl -N
```
first to isolate.
Tool UI not rendering — tool name on the React side (
```
useCopilotAction({ name: "..." })
```
) doesn't exactly match the backend
```
@tool
```
name.
Putting the endpoint behind a SSE-incompatible proxy — many proxies buffer event-stream responses by default. Disable buffering on the route.
Trying to use
AGUIStream
with classic
ConversableAgent
— the description here covers
```
ag2.Agent
```
. Classic AG2 agents can be exposed differently; check the AG2 docs for that path.

缺少
ag-ui
扩展包 — 必须执行

pip install "ag2[ag-ui]"

；否则

from ag2.ag_ui import AGUIStream

会执行失败。

CORS被阻止 — 开发环境中前端无法访问后端。为FastAPI应用添加
```
CORSMiddleware
```
，允许开发源访问。
无流式输出 — 代理或
```
Content-Type
```
问题。先使用原始
```
curl -N
```
命令测试以排查问题。
工具UI未渲染 — React端的工具名称（
```
useCopilotAction({ name: "..." })
```
）与后端
```
@tool
```
的名称不完全匹配。
将端点放置在不兼容SSE的代理后 — 许多代理默认会缓冲事件流响应。需禁用该路由的缓冲功能。
尝试将
AGUIStream
与经典
ConversableAgent
配合使用 — 本文描述的内容针对
```
ag2.Agent
```
。经典AG2 Agent的暴露方式不同；请查看AG2文档获取相关方法。

ag2-ag-ui

Original

Translation

AG-UI integration

AG-UI集成

When to use

何时使用

Supported AG-UI features

支持的AG-UI功能

Installation

安装

60-second recipe — FastAPI server

60秒快速实现 — FastAPI服务器

Lower-friction alternative —
`build_asgi()`

更简便的替代方案 —
`build_asgi()`

CopilotKit frontend (recommended for React / Next.js)

CopilotKit前端（推荐用于React / Next.js）

Option A — CopilotKit bootstrap

选项A — CopilotKit快速初始化

Option B — clone the reference starter

选项B — 克隆参考启动模板

https://github.com/ag2ai/ag2-copilotkit-starter

https://github.com/ag2ai/ag2-copilotkit-starter

Production checklist

生产环境检查清单

Going deeper

深入学习

Common pitfalls

常见陷阱