本页基于官方文档 AG-UI Introduction 整理与翻译,力求完整覆盖其核心内容。
AG-UI 协议是什么
AG-UI(Agent–User Interaction Protocol,智能体-用户交互协议)是一个开放、轻量、事件驱动的协议,用于标准化 AI 智能体与面向用户应用之间的连接方式。
AG-UI 被设计为用户应用与任意智能体后端之间通用的双向交互连接层。它在保持简单与灵活的同时,标准化了智能体状态、UI 意图与用户交互如何在模型/智能体运行时与前端应用之间流动,使开发者能够快速交付可靠、可调试、体验良好的智能体功能,而无需反复编写复杂的临时对接代码。
智能体协议栈(Agentic Protocols)
AG-UI 是三个重要开放智能体协议之一,各自关注不同层面:
| 层面 | 协议 | 作用 |
|---|---|---|
| 智能体 ↔ 用户交互 | AG-UI(Agent–User Interaction Protocol) | 连接智能体与面向用户应用的开放、事件驱动标准,实现实时、多模态、可交互体验 |
| 智能体 ↔ 工具与数据 | MCP(Model Context Protocol) | 开放标准(源自 Anthropic),让智能体安全连接外部系统——工具、工作流与数据源 |
| 智能体 ↔ 智能体 | A2A(Agent to Agent) | 开放标准(源自 Google),定义智能体在分布式系统中如何协作与共享工作 |
关于 “A2UI” 与 “AG-UI” 的区别:两者名称相似但定位不同,且可以很好地协同工作。A2UI 是一种生成式 UI 规范,用于让智能体交付 UI 组件/控件;AG-UI 是智能体↔用户交互协议,用于连接智能体前端与任意智能体后端。了解更多:https://copilotkit.ai/ag-ui-and-a2ui
核心构建块(当前与规划中)
AG-UI 围绕可组合的交互能力构建,主要包括:
- 流式聊天(Streaming chat):实时 token 与事件流,支持响应式多轮会话,以及取消与恢复。
- 多模态(Multimodality):类型化附件与实时媒体(文件、图片、音频、转录等);支持语音、预览、标注与来源信息。
- 生成式 UI - 静态(Generative UI, static):将模型输出渲染为稳定、类型化组件,由应用控制展示。
- 生成式 UI - 声明式(Generative UI, declarative):小型声明式语言用于表达受约束但开放的智能体 UI;智能体提出结构与约束,应用校验后挂载。
- 共享状态(Shared state):只读与读写状态。智能体与应用共享的类型化存储,通过事件溯源的增量差异流式同步,并支持冲突处理以实现顺畅协作。
- 思考步骤(Thinking steps):基于 trace 与工具事件可视化中间推理过程;不暴露原始思维链(raw chain of thought)。
- 前端工具调用(Frontend tool calls):从智能体到前端执行动作的类型化交接,并将结果返回。
- 后端工具渲染(Backend tool rendering):在应用与聊天中可视化后端工具输出,将副作用作为一等事件发出。
- 中断/人机协同(Interrupts, human in the loop):在流程中暂停、批准、编辑、重试或升级处理,而不丢失状态。
- 子智能体与组合(Sub-agents and composition):嵌套委派,具备作用域状态、追踪与取消能力。
- 智能体引导(Agent steering):通过实时用户输入动态重定向智能体执行,以引导行为与结果。
- 工具输出流式传输(Tool output streaming):流式传输工具结果与日志,使 UI 能实时渲染长耗时效果。
- 自定义事件(Custom events):用于协议未覆盖需求的开放式数据交换。
为什么智能体应用需要 AG-UI
智能体应用打破了智能体时代之前主导前后端开发的简单请求/响应模型:客户端发起请求,服务器返回数据,客户端渲染,然后交互结束。
面向用户智能体的需求
虽然智能体本质上也是软件,但它们表现出一些特性,使其难以通过传统 REST/GraphQL API 提供服务:
- 智能体是长时间运行的,并会流式输出中间工作——通常跨越多轮会话。
- 智能体具有非确定性,并可能非确定性地控制应用 UI。
- 智能体同时混合结构化与非结构化 I/O(例如文本与语音,以及工具调用和状态更新)。
- 智能体需要用户可参与的组合能力:例如可能调用子智能体,且往往是递归的。
- 以及更多……
AG-UI 是一种事件驱动协议,用于实现智能体前端与后端之间的动态通信。它建立在 Web 基础协议(HTTP、WebSocket)之上,作为面向智能体时代的抽象层,弥合传统客户端-服务器架构与 AI 智能体动态、有状态本质之间的鸿沟。
AG-UI 实践与演示
你可以在 AG-UI Dojo 中查看不同框架下 AG-UI 特性的演示应用,包含预览、代码与讲解文档。
支持的集成
AG-UI 源于 CopilotKit 与 LangChain、CrewAI 的早期合作,并将广受欢迎的智能体-用户交互基础设施带入更广泛的生态。以下为概览(具体状态与资源请以官方页面为准):
智能体框架 - 合作伙伴
智能体框架 - 官方/一方集成(示例)
- Microsoft Agent Framework:Supported(Docs、Demos)
- Google ADK:Supported(Docs、Demos)
- Google ADK (JavaScript):Supported(Quickstart、Demos)
- AWS Strands Agents:Supported(Docs、Demos)
- Mastra:Supported(Docs、Demos)
- Pydantic AI:Supported(Docs、Demos)
- Agno:Supported(Docs、Demos)
- LlamaIndex:Supported(Docs、Demos)
- AG2:Supported(Docs、Demos)
- AWS Bedrock Agents:In Progress
智能体框架 - 社区集成(示例)
- OpenAI Agents SDK、Cloudflare Agents、Claude Agent SDK、Claude Managed Agents SDK、Langroid、Omnara 等均有对应支持/集成资源(详见生态与集成与官方文档)。
智能体交互协议
- A2A Middleware:Supported(Docs)
基础设施与部署
- Amazon Bedrock AgentCore:Supported(Docs)
规范
SDK
官方与社区提供多语言 SDK,包括 TypeScript、Kotlin、Go、Java、.NET、Python、Dart、Rust、Ruby、C++ 等(状态与入门链接见 SDK 与客户端 与官方文档)。
客户端
AG-UI 客户端不必是 Web 应用。协议描述的是事件流而非渲染目标,因此终端、移动应用或聊天平台都可以作为客户端。
聊天平台客户端是任何人都可以基于 AG-UI 构建的。Channels SDK 是其中一种实现,OpenTag 是基于它构建的完整应用:将 Python LangGraph 智能体通过 AG-UI 接入 Slack 与 Microsoft Teams。在该应用中,智能体及其运行时由用户自托管,而平台凭据与消息投递可由 CopilotKit Intelligence(托管服务,非协议的一部分)处理。
快速开始
根据你的需求选择路径:
- 构建智能体应用:构建由兼容 AG-UI 的智能体驱动的应用
- 构建 AG-UI 集成:为新的智能体框架、自研方案或无框架场景实现集成
- 构建 AG-UI 兼容客户端:为兼容智能体构建新的客户端(Web、移动端、Slack、消息平台等)
深入探索
资源与支持
- 资源与链接:文档、示例、路线图与贡献入口
- 问题反馈与功能请求:GitHub Issues
- 社区讨论:Discord