本页介绍如何构建消费 AG-UI 事件流的应用。客户端可以是 Web 应用,也可以是任何能够接收、展示并响应 AG-UI 事件的系统。
适用场景
- 为现有产品接入智能体 Copilot / 助手能力
- 基于已支持 AG-UI 的框架或后端快速搭建交互界面
- 需要流式输出、工具可视化、状态同步与人机协同体验
快速创建
使用脚手架
npx create-ag-ui-app@latest脚手架可以帮助你选择客户端与服务端组合,生成可运行的示例项目。完成后按项目提示安装依赖并启动:
npm run dev
# 或根据项目实际脚本使用 pnpm/yarn提示:不同模板的端口与启动命令可能不同,请以生成项目的 README 为准。
应用端核心职责
一个典型的 AG-UI 应用需要完成以下工作:
- 建立连接:通过 HTTP(SSE) 或 WebSocket 等方式连接到智能体端点。
- 发送输入:向智能体提交
RunAgentInput等兼容输入(包含消息、线程信息、工具、状态、上下文等,具体字段视实现与 SDK 而定)。 - 订阅事件流:按顺序接收并处理 AG-UI 事件。
- 维护会话状态:将事件归并为消息列表、工具调用状态、共享状态与 UI 状态。
- 渲染交互界面:实时展示流式文本、思考/步骤、工具进展、生成式 UI 与中断请求。
- 回传用户交互:将用户回复、前端工具结果、审批/编辑结果等作为后续输入或响应提交。
事件处理建议
- 生命周期:在
RUN_STARTED时初始化运行状态,在RUN_FINISHED/RUN_ERROR时收尾并处理错误或中断结果。 - 文本消息:处理
TEXT_MESSAGE_START/CONTENT/END(或 Chunk 事件)实现流式渲染。 - 工具调用:处理
TOOL_CALL_START/ARGS/END/RESULT展示调用过程与结果;如支持前端工具,在收到调用后执行并回传结果。 - 状态同步:用
STATE_SNAPSHOT初始化,用STATE_DELTA(JSON Patch)增量更新共享状态。 - 消息快照:在需要全量同步时使用
MESSAGES_SNAPSHOT重建会话视图。 - 自定义扩展:通过
CUSTOM/RAW事件承载协议外能力,同时保持对标准事件的兼容。
与现有客户端生态结合
- CopilotKit:提供成熟的 Web 端集成方案,可作为生产级应用的起点。
- AG-UI Dojo:用于对照不同框架与特性的交互行为与实现思路。
- 自研客户端:当你需要完全自定义 UI 或运行在非 Web 环境时,可直接基于协议/SDK 实现。