Agent Protocol的Message规范深度解读:兼容OpenAI与Anthropic的通用消息格式是怎么设计的

原创2026-11-03 16:03:541,886 阅读

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 是理解整个规范的关键,它允许两种写法:

  1. 纯字符串:最简单的一行文本消息,等价于 OpenAI 风格的 "content": "你好";
  2. 内容块数组:每条消息由若干"内容块(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)把"内容块"进一步升级为模型输出的通用载体,并定义了明确的消息生命周期事件:

  1. message-start(消息开始)
  2. content-block-start(内容块开始)
  3. 0 个或多个 content-block-delta(增量数据)
  4. content-block-finish(内容块结束)
  5. 更多内容块……
  6. 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 规范用三个极简决策解决了"多厂商消息格式不互通"的老大难问题:

  1. 只锁文本——role + content 必需,文本块是唯一强约束;
  2. 其余透传——MessageAnyBlock 让 OpenAI、Anthropic 的私有结构原样通行;
  3. 能力协商——ap_io_messages 让消息模式成为可选能力,与完全自定义的输入输出 schema 并存。

对新手来说,这套设计的最大价值是:你写的 Agent 客户端不需要为每家模型厂商维护一套消息适配层,一个 messages 数组就能走天下。

登录后查看全文
agent-protocol