ag2-ag-ui

AG2 AG-UI 集成用于把 AG2 的 Agent 通过 AG-UI 协议暴露给前端，让前端（CopilotKit、自定义 React/Next.js，或任何 AG-UI 客户端）能够以标准协议流式接收响应。

用途

当用户正在构建一个 Web UI（React / Next.js / 任何 HTTP+SSE 客户端），并希望它与 AG2 agent 通信时，适合使用本集成。它面向以下需求：希望向前端暴露流式文本、推理内容、工具调用渲染、共享状态同步或子任务步骤跟踪，并且使用标准协议而不是自定义 REST/WebSocket 契约；正在使用或考虑使用 CopilotKit（推荐的 React 客户端）。如果只是需要一个自定义的、窄用途的 API，并且端到端完全掌控契约，则应跳过 AG-UI，直接编写普通端点。

支持的 AG-UI 特性

运行生命周期（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）：支持
前端工具分发（TOOL_CALL_CHUNK，用于 RunAgentInput.tools 中的客户端工具）：支持
共享状态快照（STATE_SNAPSHOT）：支持
子任务步骤（STEP_STARTED / STEP_FINISHED，在 TaskStarted / TaskCompleted 时发出）：支持
人类输入检查点以 AG-UI 事件形式呈现：不支持——没有人类输入事件族；hitl_hook 会传递到 agent.ask

安装

pip install "ag2[ag-ui]"

这是必需步骤。在交付代码前先运行此安装。如果无法运行命令，请说明确切的 pip install 命令。

60 秒快速上手 — FastAPI 服务器

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

启动命令：

uvicorn run_ag_ui:app --reload --port 8000

测试命令：

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":[]}'

更低摩擦的替代方案 — build_asgi()

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

from ag2.ag_ui import AGUIStream
from fastapi import FastAPI

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

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

两种启动方式：

# 方式 A — CopilotKit 引导
npx copilotkit@latest create -f ag2

# 方式 B — 克隆参考启动模板
# https://github.com/ag2ai/ag2-copilotkit-starter

启动模板目录结构：

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

后端默认在 8008 端口提供 /chat。ui-react/app/api/copilotkit/route.ts 中的 Next.js 路由负责把 UI 桥接到后端：

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);
}

包裹应用：

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。

生产环境检查清单

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

深入了解

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

常见陷阱

缺少 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 的代理之后 — 许多代理默认缓冲 event-stream 响应。在该路由上禁用缓冲。
尝试将 AGUIStream 与经典 ConversableAgent 一起使用 — 此处描述覆盖的是 ag2.Agent。经典 AG2 agent 可以以不同方式暴露；请查阅 AG2 文档了解该路径。