1. 为什么应用层通信格式是 Agent 系统的隐形地基
做过 Agent 项目的人大概都有过这种体验：单 Agent 跑 demo 的时候一切顺滑，一旦接入第二个 Agent、或者把工具调用拆到独立服务里，整个系统就开始出各种莫名其妙的错——参数对不上、工具名找不到、多轮对话里上下文丢失、流式输出拼不回去。排查半天发现不是模型不行，也不是框架有 bug，而是两个 Agent 之间"说话"的格式没对齐。
这就是应用层通信格式要解决的问题。它指的是 LLM/Agent 系统在应用层交换消息时约定的数据结构与语义规范，涵盖消息角色划分、内容块组织、工具调用描述、多模态载荷、流式分片、错误传递等一整套约定。往小了说它是一份 JSON Schema，往大了说它是整个 Agent 生态的"普通话"——没有它，每个框架各说各的方言，编排层就得写一堆适配代码。
这篇文章适合三类人看：一是正在做多 Agent 编排、被消息格式折磨过的开发者；二是准备自研 Agent 框架、需要设计内部协议的架构同学；三是用现成框架但想搞懂"为什么这么设计"的进阶使用者。我会从协议选型的取舍讲起，把 OpenAI 风格、Anthropic 风格、MCP 这几套主流格式拆开对比，再给出一套可直接抄的落地实现和踩坑清单。全文基于我实际做过的几个多 Agent 项目经验，不是纸上谈兵。
2. 通信格式的整体设计与选型思路
2.1 先搞清楚"通信"到底发生在哪几层
很多人一上来就纠结用哪个格式，其实没分清通信的层次。Agent 系统里的通信至少分三层，每层的格式诉求完全不同。
第一层是模型与推理服务之间的通信，也就是你发 HTTP 请求给模型 API 那一层。这一层的格式基本被厂商锁死了，你只能适配，没得选。第二层是Agent 与工具/外部服务之间的通信，典型代表是 MCP（Model Context Protocol），这一层是当前标准化最活跃的地方。第三层是Agent 与 Agent 之间的通信，也就是多智能体协作时的消息传递，这一层目前最混乱，各家框架自定义居多。
分清楚层次之后你会发现，所谓"选格式"其实是分层的决策：底层跟着厂商走，中层尽量靠 MCP 这类开放协议，上层才是你真正需要自己设计的地方。我见过不少项目把三层混在一起设计，结果就是模型 API 一升级，整个系统的消息结构全崩。
2.2 为什么不能直接用自然语言当通信格式
新手最容易犯的错，是让 Agent 之间直接传自然语言字符串。看起来简单，实际上埋了一堆雷。
自然语言没有强类型约束，A Agent 说"帮我查一下北京天气"，B Agent 可能理解成"查询天气接口"也可能理解成"解释天气概念"。没有结构化字段，你就没法做参数校验、没法做重试幂等、没法做可观测性埋点。更致命的是，当消息需要携带工具调用、多模态内容、引用来源这些复合信息时，纯文本根本表达不了，只能靠约定俗成的分隔符硬凑，维护成本极高。
结构化格式的核心价值在于可校验、可路由、可观测。可校验意味着你可以在消息进入处理逻辑前就拦掉格式错误；可路由意味着编排层能根据消息类型字段决定下一步走向；可观测意味着每条消息都能被结构化记录、检索、回放。这三点在单 Agent demo 里体现不出来，但一旦系统上规模，就是生死线。
2.3 主流格式的取舍：OpenAI 风格 vs Anthropic 风格 vs MCP
目前实际项目里最常打交道的三套格式，各有各的设计哲学，我做个横向对比。
| 维度 | OpenAI Chat 风格 | Anthropic Messages 风格 | MCP |
|---|---|---|---|
| 消息角色 | system/user/assistant/tool | user/assistant（system 独立参数） | 基于 JSON-RPC 的方法调用 |
| 工具调用 | tool_calls 数组 + tool 角色回填 | content 块中的 tool_use/tool_result | tools/list、tools/call 方法 |
| 多模态 | content 数组，type 区分 | content 块数组，类型更细 | 通过 resource 抽象 |
| 流式 | SSE delta 增量 | SSE 事件类型丰富 | 支持但实现复杂 |
| 定位 | 模型 API 事实标准 | 模型 API + 内容块模型 | 工具/上下文协议 |
选型建议很直接：如果你的系统只对接一家模型，用它的原生格式最省事；如果要多模型混用，建议在内部定义一套归一化的中间格式，在边界处做转换。MCP 不要拿来当 Agent 间通信格式用，它是为工具调用设计的，硬套到 Agent 协作上会很别扭——这点后面会细说。
2.4 设计内部格式的三条硬原则
不管最终选哪套，自研内部格式时我总结出三条不能破的原则。
第一，内容块化（content blocks）而非纯字符串。把消息内容设计成块数组，每块有 type 字段，文本、图片、工具调用、工具结果都是块。这样扩展新类型时不用改整体结构，向后兼容性好。第二，角色与内容分离。角色只表达"谁说的"，内容块表达"说了什么"，不要把工具调用信息塞进角色字段里。第三，显式优于隐式。所有可选字段要么有默认值要么明确标注，不要靠"字段缺失就代表某种含义"这种隐式约定，跨语言序列化时最容易在这里翻车。
3. 核心细节解析与实操要点
3.1 消息结构的最小可用设计
先给一套我实际项目里用过的内部消息格式，基于 JSON，可以直接抄。
{ "id": "msg_01HXYZ", "role": "assistant", "content": [ {"type": "text", "text": "我来帮你查一下天气"}, {"type": "tool_use", "id": "call_abc", "name": "get_weather", "input": {"city": "北京"}} ], "timestamp": 1700000000, "metadata": {"agent_id": "planner", "trace_id": "trace_123"} }几个关键点值得展开。id是消息唯一标识，用于去重和追踪，多 Agent 并发时没有它你会疯。role只允许几个枚举值，不要自由发挥。content是块数组，这是整个设计的核心。tool_use块里的id是工具调用标识，工具结果回填时要带上同一个 id 做关联，这是最容易出错的地方。metadata放追踪信息，不要污染核心字段。
工具结果的格式对应如下：
{ "role": "tool", "content": [ {"type": "tool_result", "tool_use_id": "call_abc", "content": "北京晴，25度"} ] }注意tool_use_id必须和请求时的id严格对应。我踩过的坑是：并发调用多个工具时，如果不用 id 关联而是靠顺序，一旦某个工具超时重试，结果就全错位了。
3.2 工具调用的参数校验与容错
工具调用是通信格式里最容易出问题的环节。模型生成的参数经常不符合 schema——少字段、类型错、多传了不存在的字段。我的做法是在格式层就做校验，而不是等到工具执行时才报错。
具体来说，每个工具定义要带一份 JSON Schema，消息进入执行前先跑一遍校验。校验失败不要直接抛异常给模型，而是把错误信息作为 tool_result 回填，让模型自己修正。这个"错误回填"机制是 Agent 自主容错的关键，格式设计上要预留is_error字段：
{"type": "tool_result", "tool_use_id": "call_abc", "is_error": true, "content": "参数 city 缺失"}提示：错误信息要写得对模型友好，明确说清哪个字段错了、期望什么类型，不要抛原始堆栈。模型看到堆栈基本没法自我修正。
3.3 流式输出的分片与重组
流式场景下通信格式会复杂一个量级。模型返回的是 SSE 增量事件，每个事件只带一小段内容，你需要按规则拼回完整消息。核心难点是工具调用的流式——参数是分片到达的，得按 index 累积。
我处理流式的经验是：维护一个"消息累积器"，按事件类型分派。文本 delta 直接追加到对应文本块；工具调用 delta 按index找到对应块，把arguments字符串拼接起来，等流结束后再解析成 JSON。这里有个坑，工具参数在流式过程中是不完整的 JSON 字符串，中途解析必然失败，必须等该工具调用的所有分片到齐再 parse。
# 简化的流式累积逻辑 accumulator = {} for event in stream: if event.type == "text_delta": buffer["text"] += event.text elif event.type == "tool_use_delta": idx = event.index accumulator.setdefault(idx, {"args": ""}) accumulator[idx]["args"] += event.partial_json # 流结束后统一解析 for idx, item in accumulator.items(): item["parsed"] = json.loads(item["args"])3.4 多 Agent 场景下的消息路由字段
单 Agent 时消息格式够用就行，多 Agent 时必须加路由信息。我在 metadata 里固定放三个字段：sender（发送方 agent_id）、receiver（目标 agent_id，广播时为空）、intent（消息意图，如 request/response/notify）。
intent字段特别有用，编排层可以据此决定是否等待响应、是否记录日志、是否触发下一跳。没有它，你就得靠解析内容猜意图，脆弱得不行。另外建议加一个correlation_id，把一次完整协作链路的所有消息串起来，排查问题时能一键拉出全链路。
4. 实操过程与核心环节实现
4.1 从零搭一套归一化消息层
假设你要做一个支持多模型、多 Agent 的系统，我推荐的做法是：内部定义一套归一化格式，在模型 API 边界做双向转换。下面是从零搭建的完整步骤。
第一步，定义归一化消息模型。用你熟悉的语言定义数据类，字段参考 3.1 节的结构。关键是 content 块用联合类型（union type），每种块类型一个类。Python 里可以用 Pydantic，TypeScript 里用 zod，都能自动生成校验和序列化。
第二步，写模型适配器。每个模型厂商一个适配器，负责把归一化格式转成厂商格式、把厂商响应转回归一化格式。适配器要处理角色映射（比如有的厂商没有 system 角色，得合并进第一条 user 消息）、工具定义转换、流式事件转换。
第三步，接入工具执行层。工具注册时带 schema，执行前校验，执行后按统一格式回填。工具执行要加超时和重试，超时后回填is_error让模型决策。
第四步，加可观测性。每条消息进出都打结构化日志，带 trace_id。这一步别省，多 Agent 出问题时全靠它。
4.2 参数计算：上下文窗口与消息裁剪
通信格式和上下文管理是绑在一起的。消息越攒越多，迟早超窗口。我的裁剪策略是：保留 system 消息、保留最近 N 轮完整对话、中间的工具调用结果做摘要压缩。
具体算一下：假设模型窗口 128k token，system 占 2k，每轮对话平均 1.5k，工具结果平均 3k。如果保留最近 10 轮，就是 10 × 4.5k = 45k，加上 system 和当前输入，总共约 50k，留足余量。超过阈值时，把最老的工具结果替换成一句摘要"此前调用 get_weather 返回北京晴天"。这个摘要本身也是消息格式的一部分，建议用特殊的 content 块类型summary标记，方便后续识别。
注意：裁剪时绝对不能拆散 tool_use 和对应的 tool_result，它们必须成对出现，否则模型会报错。裁剪的最小单位是"一轮完整交互"。
4.3 一次完整的多 Agent 协作实录
我拿一个实际项目举例：一个"研究 Agent"负责搜集资料，"写作 Agent"负责成文，中间通过消息层通信。
流程是这样的：用户请求进入，编排层生成correlation_id，发给研究 Agent 一条intent=request的消息。研究 Agent 调用搜索工具，工具结果按格式回填，研究 Agent 整理后发一条intent=response的消息给编排层。编排层转发给写作 Agent，写作 Agent 流式生成，每个 delta 都带同一个correlation_id。全程消息都进日志。
实测下来，这套流程最稳的地方在于所有跨 Agent 的消息都走同一套格式，没有特例。一旦你为某个 Agent 开了后门用自定义格式，后面维护就是灾难。踩过的坑是：早期写作 Agent 直接返回纯文本，编排层得特判，后来统一成 content 块后代码清爽了一大截。
4.4 错误传递与重试的格式约定
错误在通信格式里要有明确表达。我分三类：格式错误（消息本身不合法，直接拒绝并记录）、工具错误（工具执行失败，回填 is_error 让模型决策）、系统错误（网络、超时等，触发重试）。
重试要幂等，靠消息 id 去重。重试次数建议 3 次，指数退避。超过次数后，把错误作为 tool_result 回填，让模型决定是换个工具还是放弃。这套机制让 Agent 有了基本的自主容错能力，不用人工介入大部分临时故障。
5. 常见问题与排查技巧实录
5.1 高频问题速查表
| 现象 | 可能原因 | 排查方向 |
|---|---|---|
| 工具调用参数解析失败 | 流式分片未拼完就 parse | 检查是否等流结束再解析 |
| 工具结果对不上调用 | 未用 id 关联，靠顺序 | 检查 tool_use_id 是否匹配 |
| 多轮后模型报格式错 | tool_use/result 被拆散 | 检查裁剪逻辑是否成对保留 |
| 多 Agent 消息丢失 | 无 correlation_id 追踪 | 补全追踪字段 |
| 流式输出乱序 | 未按 index 累积 | 检查累积器实现 |
| 角色映射错误 | 厂商无 system 角色 | 检查适配器角色转换 |
5.2 三个我踩过的深坑
坑一：把 MCP 当 Agent 间通信格式用。MCP 是为工具调用设计的，它的方法调用模型适合"请求-响应"式交互，但 Agent 间协作经常是异步、多轮、带状态的，硬套 MCP 会写出一堆别扭的适配代码。正确做法是 Agent 间用自定义消息格式，工具调用才用 MCP。
坑二：content 块类型设计得太细。一开始我给每种内容都定义了独立类型，结果类型爆炸，适配器里全是 switch。后来收敛成 text、tool_use、tool_result、image 四类，其他都归到 text 里用子字段区分，维护成本骤降。
坑三：忽略时间戳和顺序。多 Agent 并发时消息到达顺序不保证，没有时间戳和序号，回放日志时根本理不清因果。加上单调递增的序号后，问题定位快了很多。
5.3 独家避坑技巧
分享几个文档里不会写但很实用的技巧。第一，给消息格式写一份 JSON Schema 并纳入 CI，任何字段改动都跑一遍兼容性测试，防止手滑改坏。第二，准备一套"格式回放"工具，把生产日志里的消息喂回系统，能复现大部分线上问题。第三，工具 schema 里的 description 要写得极其详细，模型生成参数的质量和描述质量强相关，这是投入产出比最高的一处优化。第四，给 content 块加一个cache_control之类的标记字段，方便后续做 prompt 缓存，能省不少 token 成本。
6. 格式演进与向后兼容的实操建议
通信格式不是定完就不动的，随着业务扩展一定会加字段、加类型。我的经验是永远只做加法，不做破坏性修改。加新字段时给默认值，加新块类型时老代码要能忽略未知类型而不是报错。解析时用"宽松模式"，遇到不认识的字段跳过而非抛异常。
版本管理上，建议在消息顶层加一个schema_version字段，但不要用它做分支逻辑——分支逻辑应该基于字段是否存在，而不是版本号。版本号只用于日志和监控，方便你知道线上跑的是哪套格式。
最后再分享一个小技巧：把消息格式的定义单独抽成一个包（package），所有 Agent、适配器、工具都依赖这个包，而不是各自复制一份结构定义。这样格式一改，全系统同步更新，不会出现"这个 Agent 用旧格式、那个用新格式"的割裂。我在实际项目里就是这么做的，多 Agent 协作的稳定性提升非常明显，尤其是当 Agent 数量超过五个之后，统一格式带来的收益是指数级的。
