1. 从一次“工具卡片渲染失败”说起：Agent-UI 协议到底解决什么问题
如果你正在做 AI Agent 产品，大概率遇到过这种场景：模型明明调用了搜索工具，返回了结构化的餐厅列表，但前端只能把 JSON 字符串原样打印出来，用户看到一坨[{"name":"川办餐厅","rating":4.8}]，既没有图片也没有预订按钮。这不是模型能力问题，而是 Agent 和 UI 之间缺少一套约定——Agent 不知道该怎么“描述界面”，前端也不知道该怎么“理解 Agent 的意图”。
这就是 Agent-UI 协议要解决的核心问题。传统 Chatbot 是 Request-Response 模式：用户发文本，模型回文本。但 Agent 时代，输出变成了文本 + 结构化数据 + UI 控制状态，运行时间从毫秒级拉长到秒级甚至分钟级，交互从单轮问答变成多轮工具调用加人机协作。没有协议，前端只能靠猜。
目前业界有三条截然不同的技术路线。AG-UI 由 CopilotKit 主导，核心是事件驱动的状态同步，让前端实时感知 Agent 的每一步思考；A2UI 由 Google 推出，走声明式 UI 组件规范路线，Agent 描述意图、客户端负责渲染；MCP-UI 则是社区基于 Anthropic 的 Model Context Protocol 做的可视化扩展，让工具调用结果具备可视化能力。三者不是互斥关系，而是可以组合使用。
这篇文章会从事件流、组件描述、工具调用边界三个维度逐一对照，给出可复制的 endpoint 和 Base URL 配置，以及最小验证步骤。同时说明如何借助 TaoToken 统一 Key/API 通道完成多协议并行调试——毕竟同时维护三套 API Key 和 endpoint 配置，本身就是一件让人头疼的事。
适合谁读：正在做 Agent 前端联调的工程师、需要选型 Agent-UI 方案的技术负责人、以及想理解三种协议差异的全栈开发者。下面从实际配置开始，每一步都可以跟着做。
2. TaoToken 统一 Key 通道：多协议并行调试的前置准备
在深入三种协议的配置之前，先把 API 通道这件事解决掉。三种 Agent-UI 协议在联调阶段都需要调用 LLM，如果每个协议各配一套 Key 和 Base URL，调试成本会成倍增加。TaoToken 的价值在于提供统一的 API 通道，让你用同一个 Key 就能切换不同模型，省去反复改配置的麻烦。
先拿到 Key。访问 TaoToken 官网 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 注册后，进入控制台创建 API Key。控制台地址是 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite ，在 API Keys 页面点击创建，复制生成的 Key 保存好。这个 Key 后面会在三个 Agent 的.env文件里复用。
Base URL 统一使用https://taotoken.net/api，注意这个地址不带 UTM 参数，是纯 API 端点。模型 ID 根据你的需求选择，联调阶段建议用响应速度快的模型，比如gpt-4o-mini或claude-3-5-sonnet，具体可用模型列表可以在模型对话页面 https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=models&utm_campaign=rewrite 查看。
这里有个关键点：三种 Agent-UI 协议的服务端都需要调用 LLM，但它们对 OpenAI 兼容接口的依赖方式不同。AG-UI 的 Python Agent 通常直接用openaiSDK，A2UI 的生成器可能用httpx直接请求，MCP-UI 的工具执行层可能用 LangChain。TaoToken 的 OpenAI 兼容接口意味着你只需要改base_url和api_key两个参数，不用改业务代码。
我试过在同一个项目里同时跑三个 Agent 服务，每个服务的.env都指向同一个 TaoToken Key，切换模型时只改一个环境变量，三个服务同时生效。这比每个服务单独申请 Key、单独配置要省事得多。
如果你后续要做长期编码或 Agent 开发，可以考虑 Coding Plan https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite ，它提供更稳定的配额和更低的延迟，适合持续调试场景。接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，里面有完整的接口说明和错误码对照。
配置完成后，先用一个最简单的 curl 请求验证 Key 是否可用：
curl https://taotoken.net/api/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $TAOTOKEN_API_KEY" \ -d '{ "model": "gpt-4o-mini", "messages": [{"role": "user", "content": "ping"}], "max_tokens": 10 }'如果返回正常的 JSON 响应，说明 Key 和 Base URL 都没问题。接下来就可以把这个配置复制到三个 Agent 服务里了。
3. 三协议可复制配置：AG-UI、A2UI、MCP-UI 的 endpoint 与 settings 片段
这一节给出三种协议在真实工程中的可复制配置。每个配置都包含 Base URL、Key、Model ID 三件套，以及协议特有的 endpoint 和 settings 片段。你可以直接复制到项目里，改一下端口和路径就能跑。
3.1 AG-UI 配置：SSE 事件流 + OpenAI 兼容接口
AG-UI 的服务端是一个 HTTP 服务，通过 SSE 推送事件流。核心配置在.env和 Agent 初始化代码里。
.env文件：
TAOTOKEN_API_KEY=sk-你的Key TAOTOKEN_BASE_URL=https://taotoken.net/api TAOTOKEN_MODEL=gpt-4o-mini AG_UI_PORT=8001Agent 服务端初始化（Python）：
import os from openai import AsyncOpenAI from sse_starlette.sse import EventSourceResponse client = AsyncOpenAI( api_key=os.getenv("TAOTOKEN_API_KEY"), base_url=os.getenv("TAOTOKEN_BASE_URL"), ) MODEL_ID = os.getenv("TAOTOKEN_MODEL", "gpt-4o-mini") async def generate_events(messages: list): yield create_event("RUN_STARTED", {"threadId": "t1", "runId": "r1"}) stream = await client.chat.completions.create( model=MODEL_ID, messages=messages, stream=True, ) async for chunk in stream: delta = chunk.choices[0].delta if delta.content: yield create_event("TEXT_MESSAGE_CONTENT", { "messageId": "msg_001", "delta": delta.content, }) if delta.tool_calls: yield create_event("TOOL_CALL_START", { "toolCallId": delta.tool_calls[0].id, "toolCallName": delta.tool_calls[0].function.name, }) yield create_event("RUN_FINISHED", {"threadId": "t1", "runId": "r1"})前端 endpoint 配置（React）：
const AG_UI_ENDPOINT = "http://localhost:8001/run"; const response = await fetch(AG_UI_ENDPOINT, { method: "POST", headers: { "Content-Type": "application/json", Accept: "text/event-stream", }, body: JSON.stringify({ messages: [{ role: "user", content }] }), });注意Accept: text/event-stream这个 header 必须带上，否则服务端可能返回普通 JSON 而不是 SSE 流。
3.2 A2UI 配置：JSONL 流 + 声明式组件
A2UI 的服务端输出 JSONL（每行一个 JSON 消息），前端逐行解析。配置重点是 catalog 和 surface 的初始化。
.env文件：
TAOTOKEN_API_KEY=sk-你的Key TAOTOKEN_BASE_URL=https://taotoken.net/api TAOTOKEN_MODEL=claude-3-5-sonnet A2UI_PORT=8002 A2UI_CATALOG=a2ui.dev:standardA2UI 生成器配置（Python）：
import os, json import httpx TAOTOKEN_BASE_URL = os.getenv("TAOTOKEN_BASE_URL") TAOTOKEN_API_KEY = os.getenv("TAOTOKEN_API_KEY") MODEL_ID = os.getenv("TAOTOKEN_MODEL", "claude-3-5-sonnet") CATALOG_ID = os.getenv("A2UI_CATALOG", "a2ui.dev:standard") async def generate_ui(restaurants: list): yield json.dumps({ "createSurface": { "surfaceId": "main", "catalogId": CATALOG_ID, } }) components = build_restaurant_components() yield json.dumps({ "updateComponents": { "surfaceId": "main", "components": components, } }) yield json.dumps({ "updateDataModel": { "surfaceId": "main", "path": "/restaurants", "op": "replace", "value": restaurants, } })前端 endpoint 配置：
const A2UI_ENDPOINT = "http://localhost:8002/run"; const response = await fetch(A2UI_ENDPOINT, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ messages: [{ role: "user", content }] }), }); const reader = response.body.getReader(); const decoder = new TextDecoder(); let buffer = ""; while (true) { const { done, value } = await reader.read(); if (done) break; buffer += decoder.decode(value, { stream: true }); const lines = buffer.split("\n"); buffer = lines.pop() || ""; for (const line of lines) { if (!line.trim()) continue; const msg = JSON.parse(line); processA2UIMessage(msg); } }A2UI 的 JSONL 格式意味着你必须处理“半行”问题——网络分片可能把一行 JSON 切成两半，所以要用 buffer 缓存不完整的行。
3.3 MCP-UI 配置：工具返回 UIResource
MCP-UI 的配置重点在工具定义和 UIResource 的返回格式。服务端需要声明哪些工具会返回 UI。
.env文件：
TAOTOKEN_API_KEY=sk-你的Key TAOTOKEN_BASE_URL=https://taotoken.net/api TAOTOKEN_MODEL=gpt-4o-mini MCP_UI_PORT=8003 MCP_UI_SANDBOX=trueMCP-UI 工具定义（Python）：
import os from mcp.server import Server server = Server("restaurant-mcp-ui") @server.tool("search_restaurants") async def search_restaurants(cuisine: str, location: str): results = await do_search(cuisine, location) html = render_restaurant_cards(results) return { "type": "ui_resource", "resource": { "uri": "ui://restaurant/list", "mimeType": "text/html", "text": html, }, }前端 endpoint 配置：
const MCP_UI_ENDPOINT = "http://localhost:8003/run"; const response = await fetch(MCP_UI_ENDPOINT, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ tool_call: { toolName: "search_restaurants", params } }), }); const result = await response.json(); if (result.type === "ui_resource") { setCurrentUI(result.resource); }MCP-UI 的mimeType决定了渲染方式：text/html走 iframe srcDoc 沙箱，text/uri-list走 iframe src 外部页面，application/vnd.mcp-ui.remote-dom+javascript走 Remote DOM 沙箱执行。
三种配置的共同点是都指向同一个 TaoToken Base URL 和 Key，区别只在协议特有的 endpoint 和消息格式。这样你在调试时只需要关注协议本身的差异，不用被 API 配置分散注意力。
4. 最小验证请求：从 curl 到前端渲染的成功结果
配置写好了，接下来要验证每一层是否真的通了。验证顺序建议从服务端到前端：先用 curl 确认 Agent 服务能返回正确格式，再用浏览器确认前端能渲染。
4.1 AG-UI 验证：SSE 流是否正常推送
启动 AG-UI Agent 服务后，用 curl 发一个请求：
curl -N -X POST http://localhost:8001/run \ -H "Content-Type: application/json" \ -H "Accept: text/event-stream" \ -d '{"messages":[{"role":"user","content":"帮我找一家北京的川菜馆"}]}'-N参数关闭 curl 的缓冲，让你实时看到 SSE 事件。正常输出应该是：
event: RUN_STARTED data: {"threadId":"t1","runId":"r1"} event: TEXT_MESSAGE_START data: {"messageId":"msg_001","role":"assistant"} event: TEXT_MESSAGE_CONTENT data: {"messageId":"msg_001","delta":"好的，我来帮您"} event: TOOL_CALL_START data: {"toolCallId":"call_001","toolCallName":"search_restaurants"} event: TOOL_CALL_RESULT data: {"toolCallId":"call_001","result":"[{\"name\":\"川办餐厅\"}]"} event: RUN_FINISHED data: {"threadId":"t1","runId":"r1"}如果只看到RUN_STARTED就断了，说明 LLM 调用失败，检查 TaoToken Key 和 Base URL 是否正确。如果看到RUN_ERROR，事件里会带错误信息。
前端验证：打开http://localhost:3000/ag-ui-demo，输入同样的问题，应该能看到打字机效果的文字逐字出现，然后工具调用卡片弹出，最后渲染出餐厅列表。
4.2 A2UI 验证：JSONL 流是否逐行输出
A2UI 的验证用 curl 也能做：
curl -N -X POST http://localhost:8002/run \ -H "Content-Type: application/json" \ -d '{"messages":[{"role":"user","content":"推荐几家餐厅"}]}'正常输出是每行一个 JSON：
{"createSurface":{"surfaceId":"main","catalogId":"a2ui.dev:standard"}} {"updateComponents":{"surfaceId":"main","components":[{"id":"root","component":{"Column":{"children":{"explicitList":["header","list"]}}}}]}} {"updateDataModel":{"surfaceId":"main","path":"/restaurants","op":"replace","value":[{"name":"川办餐厅","rating":4.8}]}}关键检查点：createSurface必须最先出现，updateComponents里的组件 ID 必须和updateDataModel里的 path 对应。如果前端渲染空白，大概率是组件树构建失败——检查root组件是否存在，以及children的explicitList是否引用了不存在的组件 ID。
前端验证：打开http://localhost:3000/a2ui-demo，应该看到原生组件渲染的餐厅卡片列表，每张卡片有名称、评分、价格，点击预订按钮会触发userAction消息回传。
4.3 MCP-UI 验证：UIResource 是否被正确渲染
MCP-UI 的验证分两步。先验证工具返回：
curl -X POST http://localhost:8003/run \ -H "Content-Type: application/json" \ -d '{"tool_call":{"toolName":"search_restaurants","params":{"cuisine":"川菜","location":"北京"}}}'正常返回：
{ "type": "ui_resource", "resource": { "uri": "ui://restaurant/list", "mimeType": "text/html", "text": "<div class='restaurant-list'>...</div>" } }然后验证前端渲染。打开http://localhost:3000/mcp-ui-demo，应该看到 iframe 内嵌的 HTML 卡片。如果 iframe 空白，检查mimeType是否被UIResourceRenderer支持，以及text字段是否包含完整的 HTML 字符串。
MCP-UI 的 Remote DOM 模式验证稍微复杂一些。你需要确认 iframe 的srcDoc是否正确注入，以及postMessage通信是否正常。在浏览器控制台里应该能看到tool类型的消息从 iframe 发到父窗口。
三种协议都验证通过后，你就有了一个可以并行调试的环境。三个 Agent 服务跑在不同端口，前端通过路由切换，共用同一个 TaoToken Key。接下来看常见报错怎么排查。
5. 本篇常见错排查：401、local proxy failed、reading choices、OAuth
联调阶段最容易卡在几个典型报错上。这一节按报错信息逐一对照，给出排查路径。
5.1 401 Unauthorized：Key 或 Base URL 配错
这是最常见的错误。AG-UI 服务端日志里出现：
openai.AuthenticationError: Error code: 401 - {'error': {'message': 'Invalid API key'}}排查步骤：先确认.env里的TAOTOKEN_API_KEY没有多余空格或换行。然后确认base_url是https://taotoken.net/api，不是https://taotoken.net/api/v1——OpenAI SDK 会自动拼接/v1，如果你手动加了会导致路径变成/api/v1/v1/chat/completions。
用 curl 直接测 Key：
curl https://taotoken.net/api/v1/models \ -H "Authorization: Bearer $TAOTOKEN_API_KEY"如果这个请求返回 401，说明 Key 本身有问题，去控制台重新生成一个。如果返回模型列表，说明 Key 没问题，问题在 SDK 配置。
5.2 local proxy failed：网络层拦截
这个报错通常出现在企业内网环境：
APIConnectionError: Connection error. local proxy failed意思是 SDK 尝试连接时被本地网络层拦截了。排查方向：确认你的运行环境能正常访问https://taotoken.net/api，用curl -v看 TLS 握手是否成功。如果是公司网络，可能需要配置HTTPS_PROXY环境变量指向公司提供的出口。注意不要使用任何非官方的网络工具，直接用系统或公司提供的标准网络配置即可。
另一个可能原因是 DNS 解析失败。试试nslookup taotoken.net，如果解析不到 IP，检查 DNS 设置。
5.3 reading choices：SSE 流解析失败
AG-UI 前端报错：
TypeError: Cannot read properties of undefined (reading 'choices')这个错误通常发生在服务端代码里，chunk.choices[0]为 undefined。原因是流式响应中某些 chunk 的choices数组为空——比如最后一个 chunk 只包含 usage 信息。修复方式：
async for chunk in stream: if not chunk.choices: continue delta = chunk.choices[0].delta if delta.content: yield create_event("TEXT_MESSAGE_CONTENT", {...})A2UI 的类似错误是reading 'delta'，原因一样，加个空值检查就行。
5.4 OAuth token expired：认证过期
如果你用的是需要 OAuth 的模型服务，可能会遇到：
OAuth token expired, please re-authenticateTaoToken 的 API Key 模式不涉及 OAuth，但如果你在 Agent 代码里混用了其他认证方式，需要检查是否有多余的 token 刷新逻辑。统一用 API Key 认证可以避免这类问题。
5.5 三件套检查清单
当遇到任何连接问题时，按这个清单逐项检查：
| 检查项 | 正确值 | 常见错误 |
|---|---|---|
| Base URL | https://taotoken.net/api | 多了/v1或少了https |
| API Key | sk-开头 | 复制时带了空格 |
| Model ID | gpt-4o-mini等 | 拼写错误或模型不存在 |
| Content-Type | application/json | 漏写导致 415 |
| Accept | text/event-stream（AG-UI） | 漏写导致返回普通 JSON |
如果三件套都正确但还报错，去接入文档 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite 查错误码对照表，或者在模型对话页面 https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=models&utm_campaign=rewrite 直接测试模型是否可用。
排查完这些常见错误，你的三协议联调环境应该就稳定了。最后说一下怎么根据场景选型，以及什么时候该组合使用。
6. 选型与组合：从场景出发的 Agent-UI 协议决策
三种协议不是非此即彼的关系，而是各有适用场景。选型的核心问题是：UI 控制权在谁手里，以及你需要多强的实时性。
如果你的场景是企业级 Copilot，需要 Agent 操作现有 UI 状态——比如高亮表格行、填写表单、实时展示思考过程——AG-UI 是首选。它的STATE_DELTA事件基于 JSON Patch RFC 6902，前端可以直接把增量应用到现有状态树，不需要重新渲染整个界面。这种“前端主导”的模式让 Agent 只负责广播状态变化，UI 怎么渲染完全由前端决定。
如果你的场景是跨平台消费级 App，同一套界面要在 Web、iOS、Android 上原生渲染，A2UI 更合适。它的邻接表组件模型让 LLM 可以逐个生成组件，不用一次性输出完整嵌套结构，这对流式生成特别友好。而且白名单组件库机制从根本上杜绝了 XSS 风险——Agent 只能说“渲染一个 Card”，不能说“执行这段 script”。
如果你的场景是开发者工具或 IDE 插件，需要快速为现有工具添加 UI，MCP-UI 是最轻量的选择。它复用 MCP 协议，在工具返回值里加一个ui_resource字段就行，不需要定义新的传输层。第三方开发者可以用 HTML 或 Remote DOM 贡献 UI 片段，宿主通过 iframe 沙箱隔离。
复杂场景下三者可以组合。AG-UI 作为“总线”负责事件路由和状态同步，A2UI 负责复杂跨平台 UI 的声明式描述，MCP-UI 负责工具级别的快速 UI 扩展。AG-UI 官方提供了@ag-ui/mcp-apps-middleware，可以把 MCP-UI 的 UIResource 自动映射为ACTIVITY_SNAPSHOT事件，前端根据activityType路由到不同的渲染器。
实际工程中，我建议先用 AG-UI 搭起事件流骨架，因为它的 SSE 传输和状态同步机制最成熟。然后根据 UI 复杂度决定是否引入 A2UI——如果界面简单，直接用 AG-UI 的TOOL_CALL_RESULT渲染就够了；如果界面复杂且需要跨平台，再加 A2UI 渲染器。MCP-UI 适合作为工具层的补充，特别是当你需要复用现有 MCP Server 的时候。
配置层面，三种协议共用同一个 TaoToken Base URL 和 Key，切换协议只需要改前端 endpoint 和服务端端口。这种统一通道的设计让多协议并行调试变得可行——你可以在同一个项目里同时跑三个 Demo，对比它们的实际效果，再决定最终选型。
最后给一个实用技巧：在.env里把TAOTOKEN_MODEL单独抽出来，三个 Agent 服务都读这个变量。这样你想换模型测试时，只改一个地方，三个协议同时生效。联调阶段用响应快的模型，生产环境再换成能力更强的，切换成本几乎为零。
