AG-UI（Agent-User Interaction Protocol）：让 AI 智能体走进前端应用的开放事件协议

AG-UI（Agent-User Interaction Protocol）：让 AI 智能体走进前端应用的开放事件协议

【免费下载链接】ag-uiAG-UI: the Agent-User Interaction Protocol. Bring Agents into Frontend Applications.项目地址: https://gitcode.com/gh_mirrors/agu/ag-ui

AG-UI（Agent-User Interaction Protocol）是一个开放、轻量、基于事件的协议，用于标准化 AI 智能体（Agent）与用户界面之间的连接，是当前 AI 应用生态中连接"智能体"与"人"的通用层。本文以仓库根目录 README.md 为主线，结合 docs/concepts/architecture.mdx、docs/concepts/events.mdx 等官方文档与integrations/、sdks/、middlewares/下的真实源码，系统讲解 AG-UI 的协议模型、事件体系、架构设计与三条集成路径，帮助你快速上手构建 AG-UI 应用或为新框架编写集成。

什么是 AG-UI

AG-UI 是 Agent 与用户（通过用户界面）之间的交互协议。它的核心定位是：通用、双向的智能体前端连接层——既允许智能体后端在运行期间向任何客户端发送事件流，也允许客户端向智能体发送输入，实现智能体状态、UI 意图与用户交互的双向流动。

从实现约束上看，AG-UI 对参与方只有两个简单要求（见 docs/concepts/architecture.mdx）：

• 智能体后端在执行期间发射与 AG-UI 约 16 种标准事件类型兼容的事件；
• 智能体后端能够接受几种简单的 AG-UI 兼容输入作为参数。

它不强制规定传输层，也不要求事件格式逐字段匹配，而是通过内置的中间件层（middleware）保证跨环境兼容：

• 兼容任何事件传输方式（SSE、WebSockets、Webhook 等）；
• 支持宽松的事件格式匹配（loose event format matching），让不同框架的智能体与不同应用之间能够广泛互操作；
• 附带参考 HTTP 实现与默认连接器（如HttpAgent），帮助团队快速起步。

简单地说：前端应用不需要为每个智能体框架写一套定制适配层，只要两端都"说 AG-UI"，就能直接互通。仓库中 middlewares/middleware-starter 与 integrations/server-starter 即为官方提供的最小可运行骨架，分别对应"翻译已有协议"与"直接发射事件"两种接入方式。

为什么 agentic 应用需要 AG-UI

传统的前后端交互是"请求-响应"模型：客户端发请求、服务端返回数据、客户端渲染、交互结束。而面向用户的智能体打破了这一模型，给服务端实现带来了一系列新挑战：

• 智能体是长时间运行的，并会持续流式输出中间结果，往往横跨多轮会话；
• 智能体是非确定性的，且可能非确定性地操控应用 UI；
• 智能体同时混用结构化与非结构化 I/O（文本、语音、工具调用、状态更新交织在一起）；
• 智能体需要用户交互式组合：例如递归地调用子智能体（sub-agent）。

AG-UI 用"基于事件的协议"这一抽象层来解决上述问题：它构建在 HTTP、WebSockets 等 Web 基础协议之上，专门为智能体时代设计，弥合传统客户端-服务端架构与动态、有状态的 AI 智能体之间的鸿沟。这一"为什么"的完整论证可见 docs/concepts/architecture.mdx 的 "Why Agentic Apps need AG-UI" 部分。

AG-UI 在 agentic 协议栈中的位置

当前开源智能体生态正在围绕一组互补的开放协议组织，AG-UI 是其中的"第三条腿"（参见 docs/agentic-protocols.mdx）：

层	协议	用途
Agent ↔ 用户交互	AG-UI（Agent-User Interaction Protocol）	将智能体连接到用户界面，支持实时、多模态、交互式体验
Agent ↔ 工具与数据	MCP（Model Context Protocol）	让智能体安全连接外部系统——工具、工作流与数据源
Agent ↔ Agent	A2A（Agent to Agent）	定义智能体如何在分布式系统中协调与共享工作

三者的技术目标各不相同且互补：一个智能体完全可以同时使用三者。例如一个智能体通过 MCP 调用工具、通过 A2A 与其他智能体协作、再通过 AG-UI 与前端应用交互。值得注意的是，AG-UI 还提供了与 MCP、A2A 的"握手"（handshake）能力——即 AG-UI 可以"代理"（front for）通过 MCP 与 A2A 协议暴露的智能体，使 AG-UI 客户端应用与库能够无缝使用 MCP 和 A2A 支持的智能体。仓库中 integrations/a2a 与 middlewares/a2a-middleware 就是这一互操作能力的落地实现。

另外，AG-UI 与 A2UI 是两个不同的规范（常被混淆）：A2UI 是生成式 UI 规范（允许智能体交付 UI 组件），而 AG-UI 是智能体↔用户交互协议（连接智能体前端与智能体后端），二者可以协同工作。AG-UI 与 MCP Apps、A2UI 等生成式 UI 规范均兼容，相关规范说明见 docs/concepts/generative-ui-specs.mdx。

核心架构与设计原则

AG-UI 采用客户端-服务器架构，标准化智能体与应用之间的通信：

架构中的四个基本角色：

• Application：面向用户的应用（聊天或任何 AI 赋能的界面）；
• AG-UI Client：通用通信客户端（如HttpAgent），或连接既有协议的特化客户端；
• Agents：处理请求并生成流式响应的后端 AI 智能体；
• Secure Proxy：提供附加能力并充当安全代理的后端服务。

协议层：一个抽象就绪

协议层的核心抽象非常简洁（见 docs/concepts/architecture.mdx）：

run(input: RunAgentInput) -> Observable<BaseEvent>

任何协议只要实现这一个函数签名即可接入 AG-UI。下面是文档中的最小智能体示例（TypeScript）：

// Core agent execution interface type RunAgent = () => Observable<BaseEvent> class MyAgent extends AbstractAgent { run(input: RunAgentInput): RunAgent { const { threadId, runId } = input return () => from([ { type: EventType.RUN_STARTED, threadId, runId }, { type: EventType.MESSAGES_SNAPSHOT, messages: [ { id: "msg_1", role: "assistant", content: "Hello, world!" } ], }, { type: EventType.RUN_FINISHED, threadId, runId }, ]) } }

标准 HTTP 客户端HttpAgent

AG-UI 提供标准 HTTP 客户端HttpAgent，可连接任何接受RunAgentInput类型 POST 请求体、并回传BaseEvent事件流的端点。它支持两类传输：

• HTTP SSE（Server-Sent Events）：基于文本的流式传输，兼容性广，易读易调试；
• HTTP 二进制协议：高性能、空间高效的自定义传输，适合生产环境的健壮二进制序列化。

该客户端的实现位于 sdks/typescript/packages/client，事件编解码则依赖 sdks/typescript/packages/encoder。

AG-UI 事件体系

事件是 AG-UI 中智能体与前端通信的基本单元。所有通信都建立在类型化事件之上，每个事件都继承自BaseEvent：

interface BaseEvent { type: EventType timestamp?: number rawEvent?: any }

事件严格类型化并经校验，确保各组件间通信可靠（见 docs/concepts/events.mdx）。

事件类型总览

协议将事件按用途分为以下几类：

类别	说明
生命周期事件（Lifecycle）	监控智能体 run 的进展
文本消息事件（Text Message）	处理流式文本内容
工具调用事件（Tool Call）	管理智能体的工具执行
状态管理事件（State Management）	同步智能体与 UI 之间的状态
活动事件（Activity）	表示进行中的活动进度
子智能体事件（Subagent）	追踪子智能体并归因其输出
特殊事件（Special）	支持自定义功能
推理事件（Reasoning）	支持推理可见性与隐私化延续
草稿事件（Draft）	处于开发中的提案事件

基础事件属性

所有事件共享一组基础属性：

属性	说明
type	具体的事件类型标识符
timestamp	可选，事件创建时间
rawEvent	可选，事件被转换前保存的原始数据
metadata	可选，附加到事件上的额外信息

metadata是按 key 开放的附加信息对象（可携带 token 用量、trace id、finish reason 等），在基础事件上声明一次，因此每种事件类型都会携带。消费方将事件的 metadata 逐 key 合并进该事件构建出的消息中，后者覆盖前者（last write wins），这使得生产者可以在消息的最后一个事件上再发送 token 用量，而无需提前获知。完整的合并规则见 docs/concepts/metadata.mdx。

大多数事件还接受可选的subagentRunId，用于标识产生该事件的子智能体；未携带该字段的事件归属于父智能体。详见 docs/concepts/subagents.mdx。

生命周期事件

一次典型的智能体 run 遵循可预测的模式：以RunStarted开始，可包含多对可选的StepStarted/StepFinished，以RunFinished（成功）或RunError（失败）结束。RunStarted与RunFinished/RunError是强制的，构成一次 run 的边界；Step 事件可选，可多次出现。

RunStarted：标志智能体 run 开始，建立由唯一runId标识的执行上下文。主要属性：

属性	说明
threadId	会话线程 ID
runId	智能体 run 的 ID
parentRunId	可选，分支/时间旅行的谱系指针；若存在则指向同一线程内先前的 run，形成类似 git 的追加式日志
input	可选，发送给该 run 的精确智能体输入载荷

RunFinished：标志 run 结束，每个 run 都以RunFinished或RunError终止。它带有可选的outcome判别联合：

• 省略——尚未采用中断感知生命周期的旧生产者，按正常完成处理；
• outcome: { type: "success" }——正常完成，可选result留在事件根部以保持向后兼容；
• outcome: { type: "interrupt", interrupts: [...] }——run 因等待人工输入而暂停，非空interrupts数组位于 outcome 变体内；客户端通过发起新的 run 并在RunAgentInput中包含resume数组来恢复。完整的中断生命周期见 docs/concepts/interrupts.mdx。

RunError：标志 run 出错终止，之后不再处理。属性包括message（错误信息）与可选的code（错误码）。

StepStarted / StepFinished：标志 run 内某个子任务阶段的开始/结束，属性为stepName（步骤名，可以是当前执行的节点或函数名）。配对的stepName必须一致。

文本消息事件

文本消息遵循流式模式：TextMessageStart开始 → 一个或多个TextMessageContent递送文本块 →TextMessageEnd结束。

• TextMessageStart：初始化一条新消息，建立messageId；role标明发送方角色（"developer"、"system"、"assistant"、"user"、"tool"）。
• TextMessageContent：delta携带一段非空文本块，前端按接收顺序拼接即可得到完整消息；messageId与 Start 匹配。
• TextMessageEnd：标志消息完成，前端可据此收尾渲染（移除加载指示、触发滚动等）。
• TextMessageChunk：便捷事件，客户端流转换器会自动将其展开为 Start → Content → End 三元组：某个消息的首个 chunk 必须携带messageId（自动发出TextMessageStart，role缺省为 "assistant"）；带delta的 chunk 发出TextMessageContent；当流切换到新messageId或流结束时自动发出TextMessageEnd。

工具调用事件

工具调用同样采用流式模式：ToolCallStart→ 一个或多个ToolCallArgs（流式传输参数）→ToolCallEnd，之后由ToolCallResult返回执行结果。这使前端可以实时展示智能体正在调用什么工具、以什么参数调用，增强透明性。

• ToolCallStart：toolCallId（唯一标识）、toolCallName（工具名）、可选parentMessageId（关联父消息）。
• ToolCallArgs：delta携带参数数据块（通常是 JSON 片段，拼接后构成完整参数对象）。
• ToolCallEnd：标志工具调用定义完成。
• ToolCallResult：返回工具执行输出，属性含messageId、toolCallId、content（结果内容）与可选的role（通常为 "tool"）。
• ToolCallChunk：便捷事件，自动展开为 Start → Args → End：工具调用的首个 chunk 必须携带toolCallId与toolCallName（并传播parentMessageId）；带delta的 chunk 发出ToolCallArgs；切换到新toolCallId或流结束时自动发出ToolCallEnd。

状态管理事件

状态同步采用高效的**快照-增量（snapshot-delta）**模式：完整快照在开始或偶尔发送，日常更新用增量：

• StateSnapshot：snapshot携带完整状态；前端应替换现有状态模型而非合并。
• StateDelta：delta为 RFC 6902 定义的 JSON Patch 操作数组；前端按序应用补丁保持状态一致，若发现不一致可请求新的快照。
• MessagesSnapshot：messages携带当前会话的完整消息历史，用于初始化聊天记录、断线重连后同步、或用户中途加入会话。

文档还特别说明：MessagesSnapshot中activity与reasoning角色是"全有或全无"的——若快照携带任一角色的消息，则必须是该角色的完整集合（重复条目替换客户端副本、缺失条目被移除）；若完全不带，则客户端保留已有消息。两者默认是客户端侧的，activity消息不会回传给智能体（会从RunAgentInput中剥离），reasoning通常只以流式Reasoning事件存在。

活动事件

活动事件（Activity Events）暴露聊天消息之间进行中的结构化活动更新，同样遵循快照/增量模式，便于 UI 立即渲染完整视图并随新信息增量更新：

• ActivitySnapshot：messageId（活动消息标识）、activityType（活动判别符，如"PLAN"、"SEARCH"）、content（结构化 JSON 载荷）、可选replace（默认true；为false时若消息已存在则忽略快照）。
• ActivityDelta：messageId、activityType（镜像最近快照的值）、patch（RFC 6902 JSON Patch 操作数组）。

注意：活动消息与文本/推理消息共享同一 ID 空间，其messageId不得与文本或推理消息重复。

子智能体事件

当智能体把工作委派给子智能体时，SubagentStarted/SubagentFinished/SubagentError三个事件界定子智能体的活动范围并给出可显示的名称，配合大多数其他事件上的subagentRunId归因，前端就能区分并发流式输出来自哪个子智能体。

• SubagentStarted：subagentRunId（本次调用的不透明标识，标识一次调用而非可复用的定义）、name（用于显示的名称/类型）、可选description、parentSubagentRunId（嵌套时）、parentToolCallId（派生子智能体的工具调用）、parentMessageId。
• SubagentFinished：result（可选完成载荷，镜像RunFinished.result）、outcome（可选判别联合：{ type: "success" }或{ type: "suspended", interruptIds?: string[] }；省略视为成功，suspended表示子智能体中途检查点挂起等待外部输入）。
• SubagentError：message与可选code。

特别地，StateSnapshot/StateDelta上的归因是溯源（provenance）而非所有权：它记录是哪个子智能体产生了更新，状态仍是 run 作用域的单一文档，不存在"每个子智能体的独立状态"。完整模型见 docs/concepts/subagents.mdx。

推理事件（Reasoning）

推理事件支持 LLM 推理的可见性与延续性，同时维护隐私：智能体可以浮出推理信号（如摘要），并通过加密推理条目（encrypted reasoning items）跨轮次延续推理状态——尤其适用于store:false或零数据留存策略——而不暴露原始思维链（chain-of-thought）。该设计受 OpenAI 加密推理条目与 Gemini Thought Signatures 启发。

事件包括：ReasoningStart（开始推理，建立messageId）、ReasoningMessageStart/ReasoningMessageContent（delta为推理内容块，需拼接）/ReasoningMessageEnd（流式推理消息的三元组）、ReasoningMessageChunk（自动开闭消息的便捷事件：空delta或下一个非推理事件隐式关闭消息）、ReasoningEnd（结束）。此外还有：

• ReasoningEncryptedValue：将加密的思维链附加到消息或工具调用上。属性subtype（"message" 或 "tool-call"）、entityId（所属消息/工具调用 ID）、encryptedValue（加密内容块）。客户端只做不透明存储与转发，只有智能体（或授权后端）能解密。使用场景包括：给AssistantMessage/ReasoningMessage附加推理以保留后续轮次的上下文；给工具调用附加推理以记录参数选择原因。

隐私考量、合规指引与实现示例见 docs/concepts/reasoning.mdx。

特殊事件

• Raw：透传外部系统事件。event保存原始事件数据，可选source标识来源系统，用于与不原生遵循 AG-UI 的事件系统互操作。
• Custom：应用自定义事件。name标识自定义事件类型，value携带数据。这是协议扩展机制，无需修改规范即可扩展语义，但团队应记录自定义事件以保证跨实现一致性。

草稿事件与弃用事件

处于草案状态的扩展（可能变更）包括：MetaEvent（边带注解事件，可出现在流中任意位置，属性metaType与payload，用于用户反馈或外部系统信号，提案见 docs/drafts/meta-events.mdx）以及扩展版生命周期事件（RunFinished新增outcome/result字段、RunStarted新增parentRunId/input字段，用于支持中断与分支）。

以下THINKING_*事件已弃用，将在 1.0.0 版本移除，请改用对应的REASONING_*事件：

弃用事件	替代事件
THINKING_START	REASONING_START
THINKING_END	REASONING_END
THINKING_TEXT_MESSAGE_START	REASONING_MESSAGE_START
THINKING_TEXT_MESSAGE_CONTENT	REASONING_MESSAGE_CONTENT
THINKING_TEXT_MESSAGE_END	REASONING_MESSAGE_END

迁移指南见 docs/concepts/reasoning.mdx 的 "Migration from Thinking Events" 一节。

事件流模式与实现要点

协议中的事件通常遵循三种模式：

1. Start-Content-End 模式：用于流式内容（文本消息、工具调用）——Start发起流，Content递送数据块，End标志完成；
2. Snapshot-Delta 模式：用于状态同步——Snapshot提供完整状态，Delta提供增量更新；
3. Lifecycle 模式：用于监控 run——Started标志开始，Finished/Error标志结束。

实现事件处理器时：按接收顺序处理事件；相同 ID（如messageId、toolCallId）的事件属于同一条逻辑流；实现应对乱序投递保持健壮；自定义事件应遵循既有模式以保持一致性。

AG-UI 的能力构建块

结合 docs/concepts/architecture.mdx 与 Dojo 中的演示（apps/dojo），AG-UI 目前已覆盖以下能力（部分为近期新增/规划中）：

• 流式聊天（Streaming chat）：实时 token 与事件流，支持多轮会话的取消与恢复；
• 多模态（Multimodality）：类型化附件与实时媒体（文件、图片、音频、转写），支持语音、预览、注解、来源追踪；
• 生成式 UI（静态）：将模型输出渲染为受应用控制的稳定类型化组件；
• 生成式 UI（声明式）：小型声明式语言，智能体提出组件树与约束，应用校验后挂载；
• 共享状态（Shared state）：智能体与应用共享的类型化存储（只读与读写），基于流式事件溯源的 diff 与冲突解决；
• 思考步骤（Thinking steps）：从 trace 与工具事件可视化中间推理，不暴露原始思维链；
• 前端工具调用（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 应用

AG-UI 提供 CLI 脚手架工具，可在数秒内创建一个新的 AG-UI 应用（自动装配客户端与服务器）：

npx create-ag-ui-app my-agent-app

若使用最新版本脚手架：

npx create-ag-ui-app@latest

搭建完成后启动服务：

npm run dev

对于 CopilotKit 示例，打开 http://localhost:3000 即可看到应用运行。完整步骤见 docs/quickstart/applications.mdx。CLI 工具的源码位于 sdks/typescript/packages/cli。

三条集成路径：Server、Middleware 与 Client

根据你的场景，AG-UI 集成分为三种类型（总览见 docs/quickstart/introduction.mdx）：

类型	方式	适用场景
Server 实现	从智能体或服务器直接发射 AG-UI 事件	从零构建新智能体框架、需要最大程度控制事件发射、将智能体暴露为独立 API
Middleware 实现	翻译已有协议/应用为 AG-UI 事件	已有系统或框架受限、无法直接控制智能体框架、需要通用翻译现有协议
Client 实现	构建消费 AG-UI 事件的对话应用	探索/研究协议本身，或为非 Web 场景（终端、移动端、聊天平台）构建客户端

Server：搭建一个 AG-UI 兼容的 OpenAI 流式服务器

Server 方式的核心是：实现一个 HTTP 端点，接收RunAgentInput，回传 AG-UI 事件流。仓库提供了可复制的模板 integrations/server-starter，步骤（详见 docs/quickstart/server.mdx）：

1. 克隆仓库后复制模板：cp -r integrations/server-starter integrations/openai-server；
2. 更新新目录下package.json的name/author/version字段；
3. 在src/index.ts中重命名类：export class OpenAIServerAgent extends HttpAgent {}；
4. 将集成注册进 Dojo 的 apps/dojo/src/menu.ts 与 apps/dojo/src/agents.ts，并在 apps/dojo/package.json 的dependencies中加入"@ag-ui/openai-server": "workspace:*"；
5. 启动 Python 服务器与 Dojo 后即可在浏览器中试聊。

一个最小 AG-UI 端点的骨架如下（Python + FastAPI，使用ag_uiSDK）：

from fastapi import FastAPI, Request from fastapi.responses import StreamingResponse from ag_ui.core import ( RunAgentInput, EventType, RunStartedEvent, RunFinishedEvent, TextMessageStartEvent, TextMessageContentEvent, TextMessageEndEvent, ) from ag_ui.encoder import EventEncoder import uuid app = FastAPI(title="AG-UI Endpoint") @app.post("/") async def agentic_chat_endpoint(input_data: RunAgentInput, request: Request): accept_header = request.headers.get("accept") encoder = EventEncoder(accept=accept_header) async def event_generator(): yield encoder.encode(RunStartedEvent( type=EventType.RUN_STARTED, thread_id=input_data.thread_id, run_id=input_data.run_id, )) message_id = str(uuid.uuid4()) yield encoder.encode(TextMessageStartEvent( type=EventType.TEXT_MESSAGE_START, message_id=message_id, role="assistant", )) yield encoder.encode(TextMessageContentEvent( type=EventType.TEXT_MESSAGE_CONTENT, message_id=message_id, delta="Hello world!", )) yield encoder.encode(TextMessageEndEvent( type=EventType.TEXT_MESSAGE_END, message_id=message_id, )) yield encoder.encode(RunFinishedEvent( type=EventType.RUN_FINISHED, thread_id=input_data.thread_id, run_id=input_data.run_id, )) return StreamingResponse(event_generator(), media_type=encoder.get_content_type())

在此基础上接入 OpenAI 的chat.completions.create(..., stream=True)，将每个 chunk 的delta.content转发为TextMessageChunkEvent（文本）或ToolCallChunkEvent（工具调用），最后发射RunFinishedEvent（异常时发射RunErrorEvent），即构成完整可用的流式服务器。可用以下curl验证端点：

curl -X POST http://localhost:8000/ \ -H "Content-Type: application/json" \ -H "Accept: text/event-stream" \ -d '{ "threadId": "thread_123", "runId": "run_456", "state": {}, "messages": [ { "id": "msg_1", "role": "user", "content": "Hello, how are you?" } ], "tools": [], "context": [], "forwardedProps": {} }'

EventEncoder会根据请求的Accept头自动选择 SSE 文本编码或二进制编码，media_type=encoder.get_content_type()保证响应头匹配。Python SDK 实现见 sdks/python/ag_ui。

Middleware：把任意协议翻译成 AG-UI

Middleware 方式适用于已有协议/应用。仓库模板 middlewares/middleware-starter 展示了如何继承AbstractAgent并返回Observable<BaseEvent>：

export class OpenAIAgent extends AbstractAgent { private openai: OpenAI constructor(openai?: OpenAI) { super() this.openai = openai ?? new OpenAI() } run(input: RunAgentInput): Observable<BaseEvent> { return new Observable<BaseEvent>((observer) => { observer.next({ type: EventType.RUN_STARTED, threadId: input.threadId, runId: input.runId } as any) // ...调用 OpenAI API，把响应块转为 TEXT_MESSAGE_CHUNK / TOOL_CALL_CHUNK 事件 observer.next({ type: EventType.RUN_FINISHED, threadId: input.threadId, runId: input.runId } as any) observer.complete() }) } }

"翻译输入 → 转发流式块 → 发射 AG-UI 事件"这一模式适用于 REST/GraphQL API、WebSocket，乃至 MQTT 等 IoT 协议。详细教程见 docs/quickstart/middleware.mdx。仓库中还提供了多个真实中间件示例，例如 middlewares/a2a-middleware（A2A 协议翻译）、middlewares/a2ui-middleware（生成式 UI / A2UI 事件处理）、middlewares/mcp-apps-middleware（MCP Apps 集成）、middlewares/mcp-middleware（MCP 工具集成）与 middlewares/event-throttle-middleware（事件节流）。

Client：构建一个终端聊天客户端

客户端不必是 Web 应用——AG-UI 描述的是事件流而非渲染目标，因此终端、移动应用、聊天平台（Slack、Microsoft Teams 等）都可以作为客户端。仓库提供了完整的终端示例 apps/client-cli-example，教程见 docs/quickstart/clients.mdx。要点：

1. 安装依赖：pnpm add @ag-ui/client @ag-ui/core @ag-ui/mastra（示例基于 Mastra 智能体）；
2. 用MastraAgent包装一个 MastraAgent，配置模型（如openai/gpt-4o）与基于 LibSQL 的持久化记忆；
3. 在终端主循环中向agent.messages追加用户消息，调用agent.runAgent({}, {...})并注册事件回调：

await agent.runAgent( {}, // No additional configuration needed { onTextMessageStartEvent() { process.stdout.write("🤖 Assistant: ") }, onTextMessageContentEvent({ event }) { process.stdout.write(event.delta) }, onTextMessageEndEvent() { console.log("\n") }, } )

4. 运行pnpm dev即可在终端与智能体实时对话；随后可添加src/tools/weather.tool.ts之类的 Zod 定义工具，让智能体具备真实能力。

官方推荐的生产级客户端是 CopilotKit，它已原生理解 AG-UI，提供开箱即用的 React 组件，直接指向你的 AG-UI 端点即可获得完整聊天 UI。

集成生态全景

AG-UI 起源于 CopilotKit 与 LangChain、CrewAI 的初始合作，将广受欢迎的"智能体-用户交互"基础设施带入了更广泛的智能体生态。README 中按层级给出了完整支持矩阵，仓库 integrations 目录即这些集成的源码所在：

Frameworks（内置智能体）

• Built-in Agent：✅ Supported（Docs 见 docs/concepts/agents.mdx）

Partnerships（合作框架）

• LangChain / LangGraph：✅ Supported，集成源码 integrations/langchain、integrations/langgraph
• CrewAI：✅ Supported，集成源码 integrations/crew-ai

1st Party（官方一等集成）

• Microsoft Agent Framework：✅ Supported，integrations/microsoft-agent-framework
• Google ADK：✅ Supported，integrations/adk-middleware
• AWS Strands Agents：✅ Supported，integrations/aws-strands
• Mastra：✅ Supported，integrations/mastra
• Pydantic AI：✅ Supported，integrations/pydantic-ai
• Agno：✅ Supported，integrations/agno
• LlamaIndex：✅ Supported，integrations/llama-index
• AG2：✅ Supported，integrations/ag2
• AWS Bedrock Agents：🛠️ In Progress

Community（社区集成）

• Claude Agent SDK：✅ Supported，integrations/claude-agent-sdk
• Claude Managed Agents SDK：✅ Supported，integrations/claude-managed-agents
• Langroid：✅ Supported，integrations/langroid
• OpenAI Agent SDK：🛠️ In Progress
• Cloudflare Agents：🛠️ In Progress（社区目录 integrations/community/cloudflare-agents）
• 其他社区示例还包括 Genkit（integrations/community/genkit）与 Spring AI 等

Agent Interaction Protocols

• A2A：✅ Supported（Partnership），集成 integrations/a2a 与中间件 middlewares/a2a-middleware

Infrastructure / Deployment

• Amazon Bedrock AgentCore：✅ Supported（1st Party）

Specification（标准）

• Oracle Agent Spec：✅ Supported，集成 integrations/agent-spec

Generative UI

• MCP Apps：✅ Supported，中间件 middlewares/mcp-apps-middleware

SDKs（多语言）

• Kotlin（sdks/community/kotlin）、Go（sdks/community/go）、Dart（sdks/community/dart）、Java（sdks/community/java）、Rust（sdks/community/rust）、Ruby（sdks/community/ruby）、C++（sdks/community/c++）均为 ✅ Supported；Nim、Flowise、Langflow 处于 In Progress。

官方 SDK

• TypeScript：核心包见 sdks/typescript/packages（core、client、encoder、proto、cli、a2ui-toolkit），其中core提供协议核心类型与AbstractAgent，client提供HttpAgent与客户端抽象；
• Python：sdks/python/ag_ui 提供ag_ui.core（事件与输入类型）、ag_ui.encoder（SSE/二进制编码）等，另有 sdks/python/a2ui_toolkit 工具包；
• .NET：sdks/dotnet 包含AGUI.Abstractions、AGUI.Client、AGUI.Server、AGUI.Protobuf、AGUI.A2UI等程序集与 GettingStarted 示例。

Clients

• CopilotKit：✅ Supported（1st Party，生产级 React 客户端）；
• Terminal + Agent：✅ Supported（Community，示例 apps/client-cli-example，文档 docs/quickstart/clients.mdx）；
• Chat platforms（Slack、Microsoft Teams）：✅ Supported（1st Party Channels SDK 方案）；
• React Native：✅ Supported（1st Party）。

AG-UI 客户端不一定是 Web 应用：协议描述的是事件流而非渲染目标，因此终端、移动应用或聊天平台都可以充当客户端。全部集成列表见 docs/integrations.mdx。

AG-UI Dojo：积木式示例查看器

apps/dojo 是 AG-UI 官方的Building-Blocks Viewer（积木查看器），通过简单聚焦的示例演示 AG-UI 的核心能力——每个示例仅 50–200 行代码。Dojo 将上述每种框架集成与shared_state、tool_based_generative_ui、agentic_chat等功能组合成可在线交互的演示页，每个演示都配有代码与讲解，是学习各集成写法、观察 AG-UI 事件流实际效果的最佳入口。Dojo 是一个 Next.js 应用，其框架注册逻辑集中在 apps/dojo/src/menu.ts 与 apps/dojo/src/agents.ts，pnpm dev即可本地运行；apps/dojo/e2e下还提供了覆盖 265 个测试文件的 Playwright 端到端测试套件。

参与贡献与许可证

AG-UI 欢迎社区贡献。无论是新增框架集成、新 SDK 语言、示例改进还是文档修订，请先阅读 CONTRIBUTING.md 了解规范与命名约定（集成放置于integrations/目录，中间件放置于middlewares/目录），并通过 Pull Request 提交。仓库同时维护 docs/development/roadmap.mdx（路线图）与 docs/development/updates.mdx（更新记录），docs/development/contributing.mdx 提供了面向文档贡献者的指南；仓库根目录的 AGENTS.md 与 CLAUDE.md 则面向 AI 辅助开发场景，说明了构建、测试与提交约定。

AG-UI 以MIT 许可证开源（见 LICENSE），可自由用于商业与非商业项目。

小结

AG-UI 用一套"约 16 种标准事件类型 + 简单输入约定 + 传输无关中间件"的最小约束，打通了智能体后端与任意用户界面之间的双向通道：生命周期事件界定 run 边界，文本与工具调用事件以 Start-Content-End 流式模式提供实时体验，快照-增量模式高效同步状态，子智能体事件解决并发流归因，推理事件在隐私前提下保留推理延续性，Raw/Custom 事件则保证协议可扩展。无论你是用npx create-ag-ui-app直接搭建应用、参考server-starter编写自己的服务器、基于middleware-starter翻译既有协议，还是构建终端/移动端等非 Web 客户端，都可以从本仓库的 integrations、middlewares、sdks 与 apps/dojo 中找到可直接参考、复制和运行的实现。

【免费下载链接】ag-uiAG-UI: the Agent-User Interaction Protocol. Bring Agents into Frontend Applications.项目地址: https://gitcode.com/gh_mirrors/agu/ag-ui