当现有生态中没有你所需的 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。
能力覆盖建议
可按优先级逐步实现:
- 基础:运行生命周期 + 文本消息流式输出
- 进阶:工具调用与结果、共享状态
- 高级:前端工具、人机协同中断、推理/活动/子智能体事件、生成式 UI 相关能力
参考模板与资源
- 官方仓库中的集成模板与现有实现(如 middleware/server starter、各框架集成目录)
- 事件参考:标准事件类型与字段
- 核心架构:端到端交互模型
- AG-UI Dojo:对照目标行为