AG-UI 1.0 已把 Agent 与用户界面之间的事件流钉成稳定规范：每个事件字段由 JSON Schema 约束，TypeScript / Python / .NET SDK 从同一份 schema 生成，0.x 与 1.0 双向兼容。2026-09-30 CopilotKit 博文同时写入子代理 subagentRunId、metadata、多模态工具结果、人机中断（HITL）以及 RUN_FINISHED 上的 token usage。下文事实以该博文为准，采用口径跟随原文表述，不做独立背书。

主源：Introducing AG-UI 1.0（Anmol Baranwal、Eli Berman，2026-09-30）。AG-UI 全称 Agent-User Interaction Protocol，定位是标准化 Agent 后端与面向用户应用之间的双向事件流；工具侧 MCP、Agent 间 A2A，用户面这一层由 AG-UI 补齐。博文称其已被 Google、Microsoft、Amazon 与 Oracle 采用，并得到多数 Agent 框架支持（文中举例含 LangChain、Mastra、Anthropic Claude Managed Agents；后文还列 Google ADK、OpenAI Agents SDK、Strands Agents、Microsoft Agent Framework、Pydantic AI 等）。这些属于官方表述，本文按「厂商自述」处理，不外推成已验证的企业级落地清单。

稳定规范：Schema 管字段，Spec 管行为

1.0 规范分两块。JSON Schema（单文件 schema.json）描述每个事件、应用侧请求 RunAgentInput 以及相关类型；任意语言的 JSON Schema 校验器都能验事件。规范文本则写清 Schema 说不清的规则：事件顺序、run 如何起止、错误如何处理。每条规则标明适用于 producer（发事件的 Agent 侧）还是 consumer（客户端 / UI）。字段冲突时以 Schema 为准；实现违反规则，算实现有 bug。

官方先以 draft 公开讨论，Anthropic、Pydantic AI、TanStack 团队反馈进入终稿。博文写明：1.0 规范本身不会再改，今天按它构建的东西可以继续工作；后续版本走同一套流程。Schema 很严，未声明字段会校验失败，例外是留给自定义数据的位置（例如 metadata）。较新的 Agent 若冒出旧客户端不认识的字段或事件，规范要求客户端跳过并告警，而不是整条流失败，以便协议继续演进时旧客户端仍能跑。

TypeScript、Python 与 .NET SDK 现从这份 Schema 生成。升级到 1.0 SDK 时，博文给出若干小改动：TypeScript 校验器迁到 @ag-ui/core/schemas；事件上随意挂的自定义字段改走 metadata；SubAgentInfo / subAgents 更名为 SubagentInfo / subagents；ToolMessage.content 可为字符串或内容部件列表。Python 模型改为 Schema 生成，JSON Patch 条目变成带属性的对象（patch["path"] → patch.path）。.NET 迁移细节指向官方 migration guide；同站另文提到 Microsoft 贡献了 first-class .NET SDK，并与 AG-UI 1.0 一并在 NuGet 到 1.0。

子代理：用 subagentRunId 把并行输出拆开

1.0 增加子代理支持。旅行规划这类场景里，主 Agent 可能同时拉起搜航班与搜酒店两个子代理；此前输出挤进同一条聊天流，UI 分不清归属。现在子代理发出的事件带各自 id，前端可以按卡片分别渲染：

{ "type": "SUBAGENT_STARTED", "subagentRunId": "sub-1", "name": "flight-search" }
{ "type": "TEXT_MESSAGE_CONTENT", "messageId": "msg-1", "subagentRunId": "sub-1", "delta": "Found 3 flights..." }
{ "type": "SUBAGENT_FINISHED", "subagentRunId": "sub-1" }

关键字段是 subagentRunId：生命周期事件与内容事件共用它，把并行流钉到同一条子代理轨迹上。

metadata：把自定义数据正面交给前端

metadata 允许 Agent 把任意自定义数据送到前端，例如消息下展示所用模型，或挂上指向日志的 trace id。后端示例（博文 Python 风格）：

TextMessageEndEvent(
    message_id="msg-1",
    metadata={"acme.model": "gpt-5.5", "acme.trace_id": "tr_8f2a"},
)

浏览器侧可读到同一份对象。这对可观测与产品埋点更友好：以前往事件对象上塞未声明字段，1.0 起自定义载荷应走 metadata，也与「Schema 严校验、例外留给 metadata」一致。

多模态工具结果与 HITL 中断

TOOL_CALL_RESULT 的内容不再限于纯文本，可以带图像、音频、视频与文档。发票工具可以直接回传 PDF：

{
  "type": "TOOL_CALL_RESULT",
  "messageId": "msg-2",
  "toolCallId": "call-1",
  "content": [
    { "type": "text", "text": "Here is your invoice." },
    {
      "type": "document",
      "source": {
        "type": "url",
        "value": "https://example.com/invoice.pdf",
        "mimeType": "application/pdf"
      }
    }
  ]
}

人机协同方面，1.0 引入 interrupts：Agent 需要用户输入时，run 可以暂停；UI 展示审批按钮，下一次 run 带着用户答复从断点继续。博文举例是发邮件前征求批准。run 也可以以 cancelled 结束，用户主动停下的 run 不再与正常完成或失败混为一谈。

RUN_FINISHED 上的 usage，以及和 0.x 怎么共存

run 结束时可报告 token 用量，并对 input、output、cached、reasoning 等类别有明确规则。子代理消耗计入启动它的那次 run。示例：

{
  "type": "RUN_FINISHED",
  "threadId": "t1",
  "runId": "r1",
  "usage": [
    {
      "model": "gpt-5.5",
      "inputTokens": 1200,
      "outputTokens": 340,
      "cachedInputTokens": 800
    }
  ]
}

兼容性是升级时的硬约束：AG-UI 1.0 向后兼容；0.x Agent 可配 1.0 客户端，1.0 Agent 也可配 0.x 客户端，一侧先升不必整栈齐步。完整变更见官方 changelog；动手前按 migration guide 改 SDK 细节即可。

现在只需做的一件事

若你已经在对接某套 Agent 流式输出，先打开 AG-UI 1.0 博文与 Spec，对照自家事件是否能映射到 Schema，并用 npx create-ag-ui-app@latest 起一个最小客户端验证子代理 id、metadata、中断与 RUN_FINISHED.usage。框架是否在「多数支持」名单里，以 Dojo 集成与官方文档为准，不要把厂商自述直接写成选型结论。

— 感谢阅读 —
# Agent# 智能体

一起交流

分享你的思考，让讨论更进一步。