用 AG-UI 协议给 Agent 做实时流式前端：CopilotKit 实战

你花大力气把 Agent 后端跑通了，结果前端只能「转圈圈，等它一口气吐完答案」。用户看不到它在想什么、调了什么工具，体验像黑盒。AG-UI（Agent-User Interaction Protocol）就是来解决这个的：它定义了一套事件流标准——后端把「思考中 / 调用了搜索工具 / 工具返回了什么 / 最终消息」按统一的事件格式实时推给前端，前端照着渲染即可。

🔌 本教程适合：全栈 / 前端开发者，以及任何想给已有 Agent 套个「能看过程」的交互界面的人。你需要 Node 18+、会一点 React。

先搞懂：AG-UI 在解决什么？

过去每个 Agent 框架都有自己的流式格式，前端得为每家写适配。AG-UI 把这件事标准化成一组事件类型：

事件	前端用它做什么
RUN_STARTED / RUN_FINISHED	显示「正在思考 / 完成」状态
TEXT_MESSAGE_CONTENT	逐字流式渲染对话
TOOL_CALL_START / TOOL_CALL_END	展示「正在调用搜索…」进度卡
STATE_DELTA	实时同步 Agent 的中间状态

AG-UI 只是「协议」，不是某个产品。CopilotKit 是目前最顺手的实现之一，帮你在前后端把这套事件流接起来。你也可以用 LangGraph / 自研后端自行发出这些事件。

Step 1：后端 Agent 接入 AG-UI

1 让后端吐出标准事件

用 CopilotKit 的后端 SDK 包住你的 Agent（以 Python 为例）：

from copilotkit import CopilotKitSDK, LangGraphAgent
from your_agent import graph

sdk = CopilotKitSDK(
    agents=[LangGraphAgent(name="my_agent", graph=graph)]
)
# sdk 会自动把 Agent 的执行转成 AG-UI 事件流

💡 如果你用 LangGraph，CopilotKit 几乎零改动就能接；自研后端则按 AG-UI 事件 schema 自己 emit 即可，协议是开放的。

Step 2：前端起 React 项目 + 装 CopilotKit

2 装 UI 与运行时

npm create vite@latest agent-ui -- --template react-ts
cd agent-ui
npm install @copilotkit/react-ui @copilotkit/react-core
npm install @copilotkit/runtime   # 若后端也用 Node 可省

注意公共运行时（public runtime）仅供快速试用。生产请自建 runtime 指到你自己的后端，否则会经过第三方中转，涉及数据出域风险。

Step 3：接上聊天界面组件

3 三行代码拥有可用 UI

在 App.tsx 里用 CopilotProvider 包住，并放入 CopilotSidebar：

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

export default function App() {
  return (
    <CopilotProvider runtimeUrl="http://localhost:8000/copilotkit">
      <CopilotSidebar>
        <YourApp />
      </CopilotSidebar>
    </CopilotProvider>
  );
}

🚀 现在右侧就有一个聊天侧边栏，发消息会实时把 Agent 的回复与工具调用过程流式展示出来——不用写一行渲染逻辑。

Step 4：自定义中间态组件

4 把「工具在跑」可视化

利用 AG-UI 的 useCoAgentStateRender 钩子，监听 Agent 状态并渲染自定义进度：

import { useCoAgentStateRender } from "@copilotkit/react-core";

useCoAgentStateRender({
  name: "my_agent",
  render: ({ state }) => <div>当前步骤：{state.currentStep}</div>,
});

让「过程可见」是信任的关键。Agent 做多步任务时，进度卡比一个最终答案更能让用户耐心等待、也更易排查问题。

Step 5 & 6：人类介入与部署

5 关键时刻让人拍板

AG-UI 支持 human-in-the-loop：后端在危险动作前 emit 一个等待事件，前端弹出确认框，人点通过后才继续：

// 后端
emit({ type: "HUMAN_APPROVAL_REQUEST", payload: { action: "send_email" } })
// 前端用 useCopilotAction 渲染确认 UI

第 6 步部署：前端 npm run build 静态托管，后端 runtime 与你的 Agent 一同部署（Docker / 你熟悉的 PaaS），把 runtimeUrl 换成生产地址即可。

🎉 至此你拥有了一个「边想边展示 + 关键步可人工把关」的 Agent 界面。AG-UI 的标准事件流让你以后换后端也不用重写前端。

常见问题速查

现象	大概率原因 & 解决
界面收不到流式	runtimeUrl 没指对；或后端未用 CopilotKit SDK 包装 Agent
工具调用不显示	后端 Agent 的工具未通过 AG-UI 适配层暴露
想接自己的非 LangGraph 后端	按 AG-UI 事件 schema 自行 emit 对应事件类型
数据合规顾虑	自建 runtime，别用公共 runtime，数据留在本机/内网

📚 更多教程 📰 智能体资讯

← 返回教程中心