AG-UI 1.0 是第一个有规范支撑的版本:schema 是唯一事实来源,每个 SDK 的协议类型都由它生成,过去只存在于 TypeScript 客户端中的行为规则也被写了下来。大多数变化是增量式的。本页讲的是需要你动手的部分——各 SDK 要改什么,以及什么可以继续工作。
协议级变更见规范的 Key Changes;本页只说明它们对你已有代码意味着什么。
哪些继续有效
- 0.x 智能体可继续对接 1.0 客户端。TypeScript 客户端带有常驻兼容边界,会翻译入站流中已退役的形状:五个
THINKING_*事件转为REASONING_*、旧binary内容部分转为媒体类型对应的部分、历史上被接受的整字段null转为缺省字段。每次入站翻译都会告警。这些 shim 记录在DEPRECATIONS.md,并有过期时间。 - 1.0 智能体可继续对接 0.x 客户端。1.0 新增的一切(
RUN_FINISHED.outcome、子智能体事件、protocolVersion、活动事件)要么是可选的,要么是新事件类型,旧客户端会忽略未知内容。 - 线上格式不变。JSON over SSE 与 protobuf 绑定的 framing 未变;你今天发送的字段名就是 1.0 读取的字段名,例外见本页。
生产者:声明你的版本
1.0 生产者必须在 RUN_STARTED 上声明它所使用的协议版本(见 Versioning)。该字段在 schema 中是可选的——因为“缺失”正是识别 1.0 之前生产者的方式。因此当你自己构建事件时,没有 SDK 会替你添加。
使用 SDK 的常量,不要手写字符串,也不要回显 RunAgentInput.protocolVersion:声明表达的是生产者自己的版本。
.NET:AGUI.Server 在把 ChatResponseUpdate 流转换时会自动构建 RUN_STARTED 并携带 AGUIProtocol.Version;若你自行发射 RunStartedEvent,需自行设置:
new RunStartedEvent
{
ThreadId = threadId,
RunId = runId,
ProtocolVersion = AGUIProtocol.Version,
};中间件与代理转发生产者的 RUN_STARTED 时,必须保持其 protocolVersion 不变:不要添加、覆盖或移除。只有把流转译成不同版本的层才声明它发射的版本。
TypeScript
TypeScript SDK 变化最大,因为协议行为过去就在这里定义。
省略整个可选 null 字段
可选协议字段必须缺省而不是 null,包括 rawEvent、RUN_FINISHED.result、forwardedProps。EventEncoder 与出站 HTTP 输入会在传输前省略这些字段;内存中的智能体也应发射规范形状。
旧生产者对一组固定的整字段可选 null 仍保持兼容(客户端在验证前将其转为缺省并告警),覆盖 rawEvent、subagentRunId、RUN_STARTED.parentRunId、RUN_STARTED.input、RUN_FINISHED.result、RUN_FINISHED.outcome.pendingToolCallIds、RUN_FINISHED.usage[] 中的 provider/reasoningTokens/cachedInputTokens/cacheWriteInputTokens、RUN_ERROR.usage、SUBAGENT_FINISHED.result、TOOL_CALL_RESULT.role、resume-entry payload、媒体部分的 metadata、tool parameters、RunAgentInput.forwardedProps 等。
这是客户端容忍,不是协议变更:生产者仍必须省略这些字段。
直接 schema 验证仍然严格,不会触发客户端兼容边界。接受旧 RunAgentInput 的请求处理器需在调用 RunAgentInputSchema.parse 前本地省略历史上可接受的 null。
zod 成为 @ag-ui/core 的可选 peer 依赖
所有验证器迁移(包括历史别名 EventSchemas、*InputPartSchema 名称、OptionalMetadataSchema)以及能力 schema。@ag-ui/client 不再重新导出它们;@ag-ui/client 自身仍依赖 zod,因为其执行阶段使用它验证,安装方式不变。
未知内容不再到达你的代码
客户端在中间件之后有统一的执行阶段,覆盖所有路径:
- 类型无法识别的事件被丢弃并告警
- 已知事件上的未知属性被剥离并告警(指明路径)
- 协议定义字段上的格式错误值(例如字符串位置出现数字)会使运行失败,和以前一样
如果你在订阅者中读取事件上的非标准属性,它在订阅者看到之前已被移除。额外数据的合规通道是 metadata——它在每个事件与消息上都是开放键,且永不被剥离。发送侧同理:RunAgentInput 上的未知键在传输前被剥离;为此存在的字段是 forwardedProps,可携带任意 JSON 原样传给智能体。
1.0 中更严格的行为
推理开/闭纪律会被验证:REASONING_MESSAGE_CONTENT/END 指向未开启的消息、关闭未开启的 span、运行结束时仍有 span 或消息未关闭,都会使运行失败。span 与推理消息是独立命名空间:推理消息不必位于 span 内,REASONING_START 的 id 也不会开启推理消息。
执行保证覆盖所有路径:未知内容会被剥离并告警、已知字段的格式错误值是致命错误——现在在安装中间件时以及 protobuf 绑定上同样成立,不仅限于普通 SSE 路径。
从公共 API 中退役
- 五个
THINKING_*事件(枚举成员、类型、schema、工厂)。请发射REASONING_*;入站旧流仍会被兼容边界翻译。 BinaryInputContent({ type: "binary" })。请使用带source的媒体部分(image、audio、video、document)。入站旧部分仍会被翻译。@ag-ui/client的stripUnknown与StripResult(执行阶段内部实现)。
重命名与类型变更
SubAgentInfo→SubagentInfo;AgentCapabilities上的multiAgent.subAgents→subagents。wire key 随之改变且没有别名。RunAgentInput.tools与.context在 TypeScript 类型上变为非可选;wire 上缺省仍表示空,SDK 以[]呈现。AbstractAgent.maxVersion弃用,改用maxProtocolVersion;旧名覆盖仍可用并告警一次。- 内容部分按“是什么”而非“方向”命名:
InputContent→ContentPart、TextInputContent→TextPart、ImageInputContent→ImagePart(audio/video/document 同理)、InputContentSource→PartSource等。旧名作为弃用别名导出,wiretype值不变。 PartSource增加第三个分支FileSource(type: "file"):由模型提供商为已上传字节签发的句柄。按source.type穷举的代码需要新增分支;永远不要把它当作 URL。ToolMessage.content与ToolCallResultEvent.content变为string | ContentPart[];contentToText()可拼接文本部分,contentHasMedia()判断扁平化是否丢失内容。- 每个内容部分都有可选
id,TextPart也有媒体部分早已具备的可选metadata。 - 能力上的
execution.maxIterations与maxExecutionTime验证为非负整数且在 JS 安全范围内。
新增且值得了解
客户端在每个 RunAgentInput 上声明 protocolVersion: "1.0",并在 RUN_STARTED 上读取生产者的答复,当生产者使用更新或无法解析的版本时告警。将 maxProtocolVersion 固定在该客户端包版本以下会省略该字段,以兼容会拒绝未知成员的 peer。
Protobuf 解码会合并 singular 消息字段的重复出现(包括嵌套消息、metadata 与 run input):后出现的标量胜出,重复列表按序追加,缺省字段保留先前值。TypeScript 与 .NET 遵循相同的 protobuf 合并规则。
Python
Python SDK 是生产者侧的:它定义智能体发射的形状。变化更窄,但其中一项会影响任何解析其输出的人。
缺省字段被省略,而非 null
无值字段会从 JSON 中省略,而不是写成 null。这在 1.0 之前(ag-ui-protocol 0.1.20)已发布。读取方使用 if payload["parentMessageId"] is None 的代码需要改为 "parentMessageId" not in payload。作为值的 null 仍保留。
生成模型取代手写模型
ag_ui.core 保留其导出的所有名称(除退役/重命名项),现在从生成源代码重新导出,构造方式不变:snake_case 关键字参数、wire 上使用别名。三点行为差异:
- 单值字面量(
type、固定role)默认为其唯一合法值,无需再写。 - 带 schema 默认值的字段(文本消息的
role、patch 的replace)在缺省时解析为None,而非物化默认值。 - JSON Patch 操作解析为类型化操作模型,wire 形式完全相同。
验证仍与以前一样宽容:未知键保留,pydantic 默认强制转换适用。严格契约是规范的 fixture 语料,而非 SDK 模型。
将 JSON Patch 条目作为对象读取
from ag_ui.core import StateDeltaEvent
event = StateDeltaEvent(delta=[{"op": "replace", "path": "/count", "value": 1}])
operation = event.delta[0]
assert operation.path == "/count" # 以前:event.delta[0]["path"]
assert operation.op == "replace" # 以前:event.delta[0].get("op")
patches = [operation.model_dump(by_alias=True) for operation in event.delta]同时兼容旧字典与 1.0 模型的适配器,可对字典条目原样保留,仅在条目为模型时调用 model_dump(by_alias=True)。
退役
MetadataMixin(来自ag_ui.core、ag_ui.core.types、ag_ui.core.events)。生成模型已自带 metadata 字段。自定义模型可继承ag_ui.core.types的ConfiguredBaseModel并声明metadata: Optional[Metadata] = None。THINKING_*事件。请发射REASONING_*;生产者侧没有 shim,TypeScript 客户端会翻译旧流。- 作为部分的
BinaryInputContent:ContentPart不再有binary成员,携带它的消息会在RunAgentInput验证时被拒绝。该类本身仍可导入一个版本,但 SDK 不再构造它。请使用媒体部分。
重命名
SubAgentInfo→SubagentInfo;MultiAgentCapabilities.sub_agents→subagents(wire keysubagents)。SubAgentInfo作为别名导出一个版本;旧字段与 wire key 不保留。ExecutionCapabilities.max_iterations与max_execution_time现在拒绝负值。- 内容部分按“是什么”命名:
InputContent→ContentPart、TextInputContent→TextPart、ImageInputContent→ImagePart等;旧名作为别名导出。 PartSource增加FileSource(type="file");按来源类分支的代码需要新增分支;永远不要把它当作 URL。ToolMessage.content与ToolCallResultEvent.content变为Union[str, List[ContentPart]];每个部分有可选id,TextPart有可选metadata。
.NET
.NET SDK 跨度最大,因为它是最后一个仍在手写协议类型的 SDK,同时获得了一项另外两个 SDK 早已具备的能力。
生成模型取代约 60 个手写类
消费者看到的表面与以前相同,减去 schema 退役的部分:相同的 sealed 类、相同的 [JsonPropertyName] wire 名称、缺省成员写入时省略。.NET 对未识别内容的容忍不变——未知属性会被跳过(System.Text.Json 一贯行为)。
一项行为更宽容:SDK 没有模型的事件类型现在会被两个流读取器跳过并给出 trace 告警,而不是结束流。单独解码单个未知事件仍会抛出 AGUIUnknownEventTypeException。
退役
AGUIBinaryInputContent、其类型常量与转换器分支。跨 Microsoft.Extensions.AI 边界的DataContent/UriContent会转为媒体类型对应的部分,文件名放在该部分的 metadata 中。.NET 没有中间件层,也不翻译入站旧部分:{ "type": "binary" }是未知判别符,转换器会抛出JsonException使反序列化失败。
重命名与类型变更
SubAgentInfo→SubagentInfo;MultiAgentCapabilities.SubAgents→Subagents(wire keysubagents)。无别名,旧 key 会被跳过。AgentCapabilities.Custom与IdentityCapabilities.Metadata变为JsonElement?;用JsonSerializer.SerializeToElement(...)构建。ExecutionCapabilities.MaxIterations与MaxExecutionTime变为long?。Tool.Parameters与RunAgentInput.ForwardedProperties(wire keyforwardedProps)为可空JsonElement?;消息的Id为非空字符串且总会写入。AGUIUserContent→AGUIContent:string-or-parts 联合不再只属于用户消息。AGUIToolMessage.Content与ToolCallResultEvent.Content变为AGUIContent。AGUIInputContentSource增加第三个子类AGUIInputContentFileSource(type: "file",常量AGUIInputContentSourceTypes.File);对来源层级switch的代码需要新增分支;永远不要把它当作 URL。
AOT
源生成序列化上下文是 AOT 编译下唯一的解析器。工具结果按其运行时类型序列化,未在上下文中注册的类型会抛出 NotSupportedException。1.0 中显式注册了 int。
下一步
- 协议级差异:Key Changes
- 能力声明现在的要求:Capabilities
- 1.0 与旧版本如何对话:Versioning and compatibility