跳到主要内容

构建应用

使用兼容 AG-UI 的智能体与客户端,快速搭建面向用户的智能体应用。

本页介绍如何构建消费 AG-UI 事件流的应用。客户端可以是 Web 应用,也可以是任何能够接收、展示并响应 AG-UI 事件的系统。

适用场景

  • 为现有产品接入智能体 Copilot / 助手能力
  • 基于已支持 AG-UI 的框架或后端快速搭建交互界面
  • 需要流式输出、工具可视化、状态同步与人机协同体验

快速创建

使用脚手架

npx create-ag-ui-app@latest

脚手架可以帮助你选择客户端与服务端组合,生成可运行的示例项目。完成后按项目提示安装依赖并启动:

npm run dev
# 或根据项目实际脚本使用 pnpm/yarn

提示:不同模板的端口与启动命令可能不同,请以生成项目的 README 为准。

应用端核心职责

一个典型的 AG-UI 应用需要完成以下工作:

  1. 建立连接:通过 HTTP(SSE) 或 WebSocket 等方式连接到智能体端点。
  2. 发送输入:向智能体提交 RunAgentInput 等兼容输入(包含消息、线程信息、工具、状态、上下文等,具体字段视实现与 SDK 而定)。
  3. 订阅事件流:按顺序接收并处理 AG-UI 事件。
  4. 维护会话状态:将事件归并为消息列表、工具调用状态、共享状态与 UI 状态。
  5. 渲染交互界面:实时展示流式文本、思考/步骤、工具进展、生成式 UI 与中断请求。
  6. 回传用户交互:将用户回复、前端工具结果、审批/编辑结果等作为后续输入或响应提交。

事件处理建议

  • 生命周期:在 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 实现。

下一步

Type to search…

↑↓ navigate↵ selectEsc close