Agent Protocol的Message规范深度解读:兼容OpenAI与Anthropic的通用消息格式是怎么设计的
Agent Protocol的Message规范深度解读:兼容OpenAI与Anthropic的通用消息格式是怎么设计的
Agent Protocol 是一个面向 LLM Agent 生产部署的框架无关 API 规范,其核心亮点之一就是一套兼容 OpenAI 与 Anthropic 的通用消息格式(Message 规范)。这篇文章带你快速看懂 Message 规范的设计思路:它只用 role 和 content 两个必需字段,就同时容纳了主流大模型厂商的消息结构,让不同实现的服务端和客户端可以无缝互通。
为什么需要一套统一的 Agent 消息格式
在做 Agent 应用时,每个模型厂商都有自己的消息结构:OpenAI 的 messages 数组、Anthropic 的 content blocks、各家工具调用的私有格式……如果你换了一个模型提供商,输入输出的转换代码就要重写一遍。
Agent Protocol 的思路是:定义一个所有主流格式的公共子集作为协议级的 Message 规范。README 中的官方表述是——
我们定义了一个 Message spec,它是 OpenAI 和 Anthropic 等主要 LLM 提供商所支持的消息格式的一个子集(a subset of the message formats supported by major LLM providers, such as OpenAI and Anthropic)。
也就是说,协议只保证"各家都有的部分",而"各家独有的部分"通过扩展机制原样透传,既不丢失信息,也不强制你理解所有厂商的差异。
Message 对象核心结构:2 个必需字段看懂消息规范
Message 的完整定义位于 openapi.json 的 components/schemas/Message 中,字段非常克制:
| 字段 | 类型 | 是否必需 | 说明 |
|---|---|---|---|
role |
string | ✅ 必需 | 消息的角色(发送方身份) |
content |
string 或 内容块数组 | ✅ 必需 | 消息正文,支持两种形态 |
id |
string | 可选 | 消息的唯一标识 |
metadata |
object | 可选 | 任意附加元数据 |
其中 additionalProperties: true 意味着你甚至可以在 Message 上自由添加协议未定义的字段,这是兼容性的第一道保险。
content 的双形态设计:字符串或内容块数组
content 是理解整个规范的关键,它允许两种写法:
- 纯字符串:最简单的一行文本消息,等价于 OpenAI 风格的
"content": "你好"; - 内容块数组:每条消息由若干"内容块(content block)"组成,这是 Anthropic 风格的结构化消息。
这种"二选一"的设计让轻量场景保持极简,而多模态、工具调用等复杂场景又能获得完整表达能力。
内容块设计:如何同时兼容 OpenAI 与 Anthropic
当 content 是数组时,每个块要么是标准化的文本块,要么是任意类型的透传块。规范里只定义了两种:
MessageTextBlock:唯一被"锁死"的块类型
文本块要求 type 固定为 "text",并带有 text 字段,可选携带 metadata(定义见 openapi.json):
{ "type": "text", "text": "天气是晴天", "metadata": {} }
文本是所有厂商消息格式的交集,所以协议只对文本块做强约束。
MessageAnyBlock:任意块类型的透传机制
这是兼容性的精髓所在。除文本外的任何块——OpenAI 风格的工具调用、Anthropic 风格的 thinking 块、图片、音频……只要带一个 type 字段,其余字段全部允许(additionalProperties: true),都可以作为 MessageAnyBlock 直接放进 content 数组(定义见 openapi.json):
{ "type": "tool_use", "id": "toolu_01", "name": "search", "input": {...} }
- 你的服务端是 Anthropic 后端?把它的 content block 原样放进来即可;
- 你的客户端要转发给 OpenAI?自行做局部转换,协议不拦你;
- 未来厂商出现新块类型?不用改协议,
type是什么就传什么。
对应的 Python 客户端模型可参考 message.py、content.py,文档见 Message.md 和 MessageAnyBlock.md。
Message 在协议中的位置:Thread、Run 与能力声明
Message 不是孤立存在的,它嵌在协议的几个关键资源里:
- Thread(线程):每个线程除了自由形态的
values状态外,还有一个独立的messages字段,存放当前线程的消息列表(openapi.json)。规范还特别规定:如果values里已含消息,返回时应将其移入messages字段,避免重复。 - Run(运行):
/runs/wait的响应RunWaitResponse同样返回messages数组(openapi.json),代表本次运行的消息产出。 - 能力声明:并非所有 Agent 都走消息模式(有些 Agent 输入输出是完全自定义的 schema)。因此协议提供了
ap_io_messages能力位(AgentCapabilities.md)——Agent 声明支持消息后,客户端才知道 threads/runs 端点里会用到messages键。
这一层"能力协商"让 Message 规范成为可选但标准化的能力,而不是一刀切的强制。
流式场景下的消息生命周期
静态消息之外,Agent Protocol 的流式规范(streaming/protocol.cddl、streaming/README.md)把"内容块"进一步升级为模型输出的通用载体,并定义了明确的消息生命周期事件:
message-start(消息开始)content-block-start(内容块开始)- 0 个或多个
content-block-delta(增量数据) content-block-finish(内容块结束)- 更多内容块……
message-finish(消息结束)
几个值得新手记住的设计点:
- 角色统一为
ai/human/system(protocol.cddl),跨厂商语义对齐; - 块不交错:块 N 一定在块 N+1 开始前结束,保证客户端拼装逻辑是确定性的;
- 增量语义显式化:
text-delta追加文本、block-delta浅合并字段,工具调用参数先以tool_call_chunk分片流出,结束时自动"升级"为完整的tool_call块; - 未知类型宽容处理:规范要求消费者对未知的块类型做安全降级而非报错,为新厂商块类型留足空间。
快速上手:在哪里查看 Message 规范的完整定义
| 想查什么 | 去哪里看 |
|---|---|
| Message 的 JSON Schema | openapi.json |
| 协议设计理念与端点总览 | README.md |
| 流式消息事件定义 | streaming/README.md、streaming/protocol.cddl |
| Python 客户端模型与文档 | client-python/docs/Message.md、client-python/ap_client/models/ |
| 参考服务端实现(FastAPI + Pydantic) | server/ap_server/models.py |
总结
Agent Protocol 的 Message 规范用三个极简决策解决了"多厂商消息格式不互通"的老大难问题:
- 只锁文本——
role+content必需,文本块是唯一强约束; - 其余透传——
MessageAnyBlock让 OpenAI、Anthropic 的私有结构原样通行; - 能力协商——
ap_io_messages让消息模式成为可选能力,与完全自定义的输入输出 schema 并存。
对新手来说,这套设计的最大价值是:你写的 Agent 客户端不需要为每家模型厂商维护一套消息适配层,一个 messages 数组就能走天下。