跳到主要内容

构建集成

为智能体框架、自研后端或现有协议实现 AG-UI 支持。

当现有生态中没有你所需的 AG-UI 集成,或你希望让自研智能体系统对接标准客户端时,需要构建 AG-UI 集成(Integration)。

何时需要构建集成

  • 你使用的智能体框架/平台尚未提供 AG-UI 支持
  • 你有自研的 Agent 编排、工具系统或运行时,希望暴露统一交互协议
  • 你希望将已有协议/事件体系转换为 AG-UI 事件流

如果已有现成集成(如 LangGraph、CrewAI、Mastra 等),通常可直接使用对应集成并转向构建应用。

两种实现方式

1. 直接发射 AG-UI 事件

在智能体或服务端执行逻辑中,按协议要求直接产生并输出 AG-UI 事件。

优点:语义最贴近协议,行为可控,便于精细支持流式、状态与中断等能力。
适用:新建服务、自研运行时、可深度改造执行流程的系统。

关键要求:

  • 在一次运行中正确发出生命周期事件(如 RUN_STARTED,以及 RUN_FINISHED 或 RUN_ERROR)。
  • 对流式内容使用 Start/Content/End 或 Chunk 模式。
  • 为工具调用、状态同步等能力输出对应事件。
  • 保证事件中的标识符(threadId、runId、messageId、toolCallId 等)一致且可关联。

2. 通过中间件/适配层转换

将现有框架或协议的事件/回调转换为 AG-UI 事件,并将 AG-UI 输入转换为后端可理解的请求。

优点:复用现有系统能力,改造成本较低。
适用:已有成熟 Agent 框架、希望快速接入 AG-UI 客户端生态的场景。

关键要求:

  • 建立清晰的事件映射(消息、工具、状态、生命周期、错误)。
  • 处理流式分片与结束条件,避免消息或工具调用无法闭合。
  • 在必要时使用 RAW/CUSTOM 事件承载无法直接映射的信息,同时尽量提供标准事件。

集成实现要点

输入处理

集成需要接收 AG-UI 兼容输入(具体结构以协议/SDK 为准),通常包括:

  • 线程与运行标识(threadId、runId 等)
  • 消息历史与当前用户输入
  • 可用工具定义(含前端工具)
  • 共享状态与上下文
  • 中断恢复时的响应数据(如适用)

事件输出

  • 传输层:可选择 SSE、WebSocket 等;确保支持流式推送与连接管理。
  • 顺序与一致性:同一消息/工具调用的事件应可通过 ID 正确关联。
  • 错误处理:在失败时发出 RUN_ERROR(并按实现约定携带错误信息),避免客户端悬挂。
  • 状态同步:按需发出 STATE_SNAPSHOT / STATE_DELTA / MESSAGES_SNAPSHOT。

能力覆盖建议

可按优先级逐步实现:

  1. 基础:运行生命周期 + 文本消息流式输出
  2. 进阶:工具调用与结果、共享状态
  3. 高级:前端工具、人机协同中断、推理/活动/子智能体事件、生成式 UI 相关能力

参考模板与资源

  • 官方仓库中的集成模板与现有实现(如 middleware/server starter、各框架集成目录)
  • 事件参考:标准事件类型与字段
  • 核心架构:端到端交互模型
  • AG-UI Dojo:对照目标行为

下一步

Type to search…

↑↓ navigate↵ selectEsc close