1. 为什么应用层通信格式是 Agent 系统的隐形骨架做 Agent 开发的人十有八九都经历过这样的场景单 Agent 跑得好好的一旦接入第二个 Agent整个链路就开始抽风。要么是消息发出去对方收不到要么是收到了但字段对不上要么是工具调用的参数在传递过程中被悄悄改了类型。排查半天最后发现不是模型不行也不是框架有 bug而是两个 Agent 之间“说话的方式”没对齐。这就是应用层通信格式要解决的问题。它不负责模型推理不负责工具执行甚至不直接参与业务逻辑但它决定了整个多 Agent 系统能不能稳定运转。你可以把它理解成快递面单包裹本身是内容面单是格式面单写错了包裹再值钱也送不到。我接触过的 Agent 项目里通信格式的设计往往是最容易被忽视、又最容易在后期变成技术债的部分。早期为了跑通 demo大家习惯用最随意的 JSON 糊弄过去字段名随手起嵌套层级看心情。等到 Agent 数量从两个变成五个从单机变成分布式问题就集中爆发了。所以这篇文章不聊虚的直接从实际项目出发把 LLM/Agent 之间应用层通信格式的设计思路、核心细节、实操方案和踩坑经验完整拆一遍。适合谁看如果你正在做 Agent 开发不管是单 Agent 调工具还是多 Agent 协作或者你在设计 Agent 框架、编排层、消息中间件这篇文章里的内容都能直接参考。即使你目前只用过一两个 Agent 框架对底层通信还没什么感知看完也能建立起一套完整的认知。2. 通信格式的整体设计与选型思路2.1 先搞清楚通信的参与者是谁设计通信格式之前必须先把参与者的角色理清楚。在一个典型的 Agent 系统里通信可能发生在以下几种实体之间LLM 与 Agent 运行时模型输出结构化指令运行时解析并执行Agent 与 Agent多个 Agent 之间传递任务、结果、状态Agent 与工具层Agent 调用外部工具工具返回执行结果Agent 与编排层编排器下发任务、收集结果、协调流程Agent 与记忆层读写短期记忆、长期记忆、知识库每一种通信场景对格式的要求都不一样。LLM 与运行时之间更关注解析的鲁棒性因为模型输出天然带有不确定性Agent 与 Agent 之间更关注语义的完整性和可追溯性Agent 与工具层之间更关注参数的精确性和错误处理。我见过不少项目用一套格式打天下结果就是要么过于宽松导致 Agent 之间语义丢失要么过于严格导致模型输出频繁解析失败。合理的做法是分层设计底层用统一的信封格式保证可传输、可路由、可追踪上层用不同的 payload schema 适配不同场景。2.2 为什么不能直接用自然语言有人会问既然都是 LLM为什么不直接让 Agent 之间用自然语言通信答案很简单自然语言适合人读不适合系统解析。自然语言的问题在于歧义性。同一句话在不同上下文里可能有完全不同的含义而 Agent 系统需要的是确定性的字段和值。举个例子“帮我查一下北京明天的天气”这句话人能理解但系统要解析出 intentweather_query、location北京、date明天、actionquery这些结构化信息用自然语言表达时解析成本极高且不稳定。另一个问题是可验证性。结构化格式可以用 schema 校验字段缺失、类型错误、枚举值越界都能在传输层直接拦截。自然语言做不到这一点你没法用 JSON Schema 去校验一段自由文本。还有一个容易被忽视的点自然语言通信会消耗大量 token。两个 Agent 来回用自然语言确认需求几轮下来 token 消耗可能比实际任务执行还多。结构化格式在 token 效率上有明显优势。2.3 信封加载荷的分层设计我在多个项目里验证下来最稳妥的方案是采用“信封 载荷”的分层结构。信封层负责路由、追踪、版本控制载荷层负责业务语义。信封层的核心字段包括字段名类型说明message_idstring全局唯一消息 ID用于去重和追踪correlation_idstring关联 ID用于串联一次完整交互的多条消息senderstring发送方标识receiverstring接收方标识message_typeenum消息类型request/response/event/errortimestampint64毫秒级时间戳versionstring通信协议版本号payloadobject业务载荷载荷层则根据 message_type 和具体场景定义不同的 schema。比如 request 类型的载荷包含 action、parameters、contextresponse 类型的载荷包含 status、result、error。这种分层的好处是信封层可以统一处理序列化、反序列化、路由、重试、日志载荷层可以独立演进而不影响传输基础设施。我在一个多 Agent 协作项目里用这套结构后来新增了三种消息类型信封层完全没动只扩展了载荷 schema迁移成本几乎为零。2.4 选型时容易踩的三个坑第一个坑是过度设计。有些团队一上来就搞一套完整的 RPC 协议定义了二十几种消息类型结果实际用到的不到五种。通信格式应该跟着业务走先跑通核心链路再逐步扩展。第二个坑是忽略版本兼容。Agent 系统迭代快今天定义的字段明天可能就要改。如果格式里没有版本号新旧 Agent 混跑时就会出现解析失败。我的做法是在信封层强制带 version 字段载荷层根据版本号做兼容处理。第三个坑是把通信格式和存储格式混为一谈。通信格式关注的是传输效率和解析速度存储格式关注的是查询效率和持久化。两者可以共用 schema但序列化方式可能不同。比如通信时用 JSON 保证可读性存储时用 MessagePack 或 Protobuf 压缩体积。3. 核心细节解析与实操要点3.1 消息类型的划分与语义定义消息类型是通信格式的骨架。划分得太粗接收方无法区分意图划分得太细发送方不知道该用哪个。我在实践中总结出一套最小可用的类型集合request请求执行某个动作期待对方返回结果response对 request 的响应包含成功结果或错误信息event单向通知不期待响应比如状态变更、进度上报error异常情况上报可能独立于 request/response 存在heartbeat心跳保活用于检测 Agent 是否在线这五种类型覆盖了绝大多数场景。如果业务需要更细的划分建议在 payload 里用 action 字段区分而不是新增 message_type。因为 message_type 影响的是传输层的处理逻辑action 影响的是业务层的处理逻辑两者不应该混在一起。注意message_type 一旦确定就不要轻易新增。每新增一种类型所有接收方都要更新解析逻辑成本很高。能用 payload 字段区分的就不要动 message_type。3.2 载荷 schema 的设计原则载荷 schema 的设计直接决定了 Agent 之间能不能正确理解彼此。我踩过的坑包括字段命名不统一、嵌套层级过深、可选字段太多导致解析分支爆炸。后来总结出几条原则字段命名用 snake_case不用 camelCase。这不是审美问题而是兼容性问题。Python 生态默认 snake_caseJavaScript 生态默认 camelCase如果通信格式不统一跨语言 Agent 交互时就要做字段名转换增加出错概率。统一用 snake_case前端做一层转换即可。嵌套层级不超过三层。层级越深解析越复杂调试越困难。如果发现 payload 嵌套超过三层说明数据结构设计有问题应该考虑扁平化或者拆分消息。可选字段必须有默认值。可选字段是解析分支爆炸的根源。如果某个字段可能不存在接收方就要写 if-else 判断。更好的做法是给可选字段设默认值让接收方始终能拿到一个确定的值。枚举值用字符串不用数字。数字枚举在日志里不可读排查问题时还要查表。字符串枚举虽然占空间但可读性和可调试性远超数字。3.3 工具调用的参数传递格式工具调用是 Agent 通信里最复杂的场景之一。LLM 输出的工具调用参数天然带有不确定性可能多一个字段可能少一个字段可能类型不对。如果通信格式不够健壮工具调用失败率会很高。我的做法是在载荷里定义统一的 tool_call 结构{ tool_name: search_weather, tool_call_id: call_abc123, parameters: { location: 北京, date: 2025-01-15 }, timeout_ms: 5000, retry_policy: { max_retries: 2, backoff_ms: 500 } }关键点在于 tool_call_id。这个 ID 由发送方生成接收方在返回结果时必须带上同一个 ID。这样即使多个工具调用并发执行也能正确匹配请求和响应。我见过不少项目忽略了这个字段结果并发调用时结果串了排查起来非常痛苦。parameters 字段建议用扁平结构不要嵌套。因为工具参数通常就是一组键值对嵌套只会增加解析复杂度。如果某个参数本身是复杂对象用 JSON 字符串序列化后传入由工具内部解析。3.4 错误信息的标准化表达错误处理是通信格式里最容易被敷衍的部分。很多项目直接用 HTTP 状态码或者简单的 error message 字段结果排查问题时信息不够用。我建议错误信息至少包含以下字段字段名说明error_code机器可读的错误码用于程序判断error_message人类可读的错误描述用于日志和调试error_source错误来源sender/receiver/tool/llmretryable是否可重试details详细错误信息比如堆栈、原始响应error_code 的设计要遵循一个原则同一个错误在不同 Agent 之间必须一致。比如“参数校验失败”这个错误不能 A Agent 用 PARAM_INVALIDB Agent 用 INVALID_PARAM。建议在项目初期就定义一份错误码表所有 Agent 共用。retryable 字段也很关键。有些错误重试就能解决比如网络超时有些错误重试多少次都没用比如参数格式错误。接收方根据 retryable 决定是否重试可以避免无效重试浪费资源。3.5 上下文传递的取舍Agent 之间通信时上下文传递是一个绕不开的问题。传多了 token 消耗大传少了对方理解不了。我的经验是只传必要上下文且上下文要结构化。必要上下文包括当前任务描述、已完成步骤、当前步骤、可用工具列表。这些信息用结构化字段表达而不是把整个对话历史塞进去。对话历史可以用引用 ID 代替接收方根据需要去记忆层拉取。举个例子Agent A 让 Agent B 帮忙查天气不需要把之前十轮对话都传过去只需要传{ task: 查询北京明天天气, context: { user_intent: 出行规划, previous_steps: [确认出行日期], available_tools: [search_weather, search_flight] } }这样既保留了必要的语义信息又控制了 token 消耗。4. 实操过程与核心环节实现4.1 从零搭建一套通信格式的完整步骤假设你现在要从零设计一套 Agent 通信格式我建议按以下步骤推进第一步梳理通信场景。列出系统中所有需要通信的实体对以及它们之间需要传递的信息类型。比如 Agent 到工具层需要传工具名和参数Agent 到编排层需要传任务状态和结果。第二步定义信封结构。根据场景梳理结果确定信封层需要哪些字段。通常 message_id、correlation_id、sender、receiver、message_type、timestamp、version 是必备的。第三步定义载荷 schema。针对每种 message_type 和场景定义具体的载荷结构。建议用 JSON Schema 或 Pydantic 模型来描述方便校验和文档生成。第四步实现序列化与反序列化。选择序列化方式。JSON 可读性好但体积大MessagePack 体积小但可读性差Protobuf 性能好但需要定义 IDL。我的建议是内部通信用 JSON跨网络通信用 MessagePack 或 Protobuf。第五步实现校验层。在接收方解析消息之前先用 schema 校验。校验失败直接返回 error不要尝试容错解析否则会把问题掩盖到更深的层次。第六步实现路由层。根据 receiver 字段把消息路由到对应的 Agent。路由层可以基于内存映射也可以基于消息队列。第七步实现追踪层。用 message_id 和 correlation_id 串联日志方便排查问题。建议在日志里强制打印这两个字段。第八步压测与调优。用真实场景压测观察序列化耗时、传输耗时、解析耗时。如果发现瓶颈优先优化序列化方式其次优化网络传输。4.2 一个可落地的 JSON Schema 示例下面是我在一个多 Agent 项目里实际使用的信封 schema基于 JSON Schema 描述{ $schema: http://json-schema.org/draft-07/schema#, title: AgentMessage, type: object, required: [message_id, sender, receiver, message_type, timestamp, version, payload], properties: { message_id: { type: string, pattern: ^msg_[a-zA-Z0-9]{16}$ }, correlation_id: { type: string, pattern: ^corr_[a-zA-Z0-9]{16}$ }, sender: { type: string, minLength: 1 }, receiver: { type: string, minLength: 1 }, message_type: { type: string, enum: [request, response, event, error, heartbeat] }, timestamp: { type: integer, minimum: 0 }, version: { type: string, pattern: ^\\d\\.\\d$ }, payload: { type: object } } }这个 schema 的好处是任何不符合规范的消息在接收方都会被直接拦截不会进入业务逻辑。message_id 和 correlation_id 用正则约束格式避免随意生成导致追踪困难。4.3 工具调用链路的完整实现工具调用是通信格式落地时最复杂的环节。我以一个天气查询工具为例展示完整链路。Agent A 需要查询北京天气它构造如下消息{ message_id: msg_a1b2c3d4e5f6g7h8, correlation_id: corr_x1y2z3w4v5u6t7s8, sender: agent_planner, receiver: tool_executor, message_type: request, timestamp: 1705300000000, version: 1.0, payload: { action: tool_call, tool_name: search_weather, tool_call_id: call_weather_001, parameters: { location: 北京, date: 2025-01-15 }, timeout_ms: 5000 } }tool_executor 收到消息后先校验信封 schema再校验 payload schema。校验通过后执行工具构造响应{ message_id: msg_h8g7f6e5d4c3b2a1, correlation_id: corr_x1y2z3w4v5u6t7s8, sender: tool_executor, receiver: agent_planner, message_type: response, timestamp: 1705300001200, version: 1.0, payload: { tool_call_id: call_weather_001, status: success, result: { location: 北京, date: 2025-01-15, weather: 晴, temperature: 5°C } } }注意 correlation_id 在请求和响应中保持一致这样即使有多个并发请求也能正确匹配。tool_call_id 也保持一致用于匹配具体的工具调用。4.4 多 Agent 协作时的消息流转多 Agent 协作时消息流转会更复杂。我以一个“规划 Agent 执行 Agent 审核 Agent”的三 Agent 架构为例。规划 Agent 收到用户任务后拆解成子任务通过 request 消息发给执行 Agent。执行 Agent 执行完成后通过 response 消息返回结果。规划 Agent 收到结果后再通过 request 消息发给审核 Agent 审核。审核 Agent 返回审核结果规划 Agent 汇总后返回给用户。整个链路中correlation_id 贯穿始终message_id 每条消息唯一。这样在日志系统里通过 correlation_id 就能还原出完整的任务执行链路。实操心得多 Agent 协作时建议在 payload 里加一个 trace 字段记录消息经过的 Agent 列表。这样排查问题时能快速定位是哪个环节出了问题。4.5 性能优化序列化与传输的取舍通信格式的性能主要体现在序列化和传输两个环节。JSON 序列化在 Python 里大约 1-2 微秒每 KBMessagePack 大约 0.5-1 微秒每 KBProtobuf 大约 0.2-0.5 微秒每 KB。传输方面JSON 体积最大MessagePack 约为 JSON 的 60%Protobuf 约为 JSON 的 40%。如果 Agent 之间通信频率不高比如每秒几十条消息JSON 完全够用。如果频率达到每秒几千条建议换 MessagePack 或 Protobuf。我做过一个压测用 JSON 时单机吞吐约 5000 条每秒换 MessagePack 后提升到 12000 条每秒换 Protobuf 后提升到 20000 条每秒。但性能不是唯一考量。JSON 的可读性在调试时价值巨大很多问题看一眼日志就能定位。我的建议是开发环境用 JSON生产环境根据吞吐量决定是否切换。如果切换保留一个 JSON 调试开关方便排查问题。5. 常见问题与排查技巧实录5.1 消息解析失败的典型原因消息解析失败是通信格式落地后最常见的问题。我整理了一份排查清单现象可能原因排查方法字段缺失发送方 schema 版本旧检查双方 version 字段类型错误序列化方式不一致检查双方序列化配置枚举越界新增枚举值未同步检查枚举定义是否一致嵌套过深数据结构设计问题检查 payload 层级编码问题字符集不一致统一用 UTF-8排查时建议先看日志里的原始消息确认消息本身是否符合 schema。如果消息本身没问题再看接收方的解析逻辑。很多时候问题出在接收方用了旧版本的 schema。5.2 消息丢失与重复的处理消息丢失和重复是分布式通信的经典问题。Agent 系统里同样会遇到。消息丢失的常见原因是网络抖动或接收方处理超时。解决方案是引入确认机制接收方收到消息后返回 ack发送方在超时未收到 ack 时重试。重试次数和超时时间根据业务容忍度设置一般建议重试 2-3 次超时 3-5 秒。消息重复的常见原因是重试机制导致的重复投递。解决方案是引入去重机制接收方根据 message_id 判断是否已处理过已处理过的直接返回上次结果不重复执行。注意去重需要存储已处理的 message_id存储时间至少覆盖最大重试窗口。如果存储成本高可以用布隆过滤器做近似去重。5.3 跨语言 Agent 的兼容性问题跨语言 Agent 通信时兼容性问题会集中爆发。Python 的 dict 和 JavaScript 的 object 在序列化时行为不同Go 的 struct 和 Java 的 class 在字段命名上也有差异。我的经验是通信格式用最通用的 JSON字段命名统一用 snake_case类型统一用 JSON 原生类型。避免使用语言特有的类型比如 Python 的 tuple、JavaScript 的 undefined、Go 的 interface{}。如果必须传递复杂类型用 JSON 字符串序列化后作为字符串字段传递由接收方根据约定反序列化。这样虽然损失了一些性能但兼容性最好。5.4 版本升级时的平滑迁移Agent 系统迭代快通信格式难免要升级。版本升级时最怕的是新旧 Agent 混跑导致解析失败。我的做法是在信封层带 version 字段接收方根据 version 选择对应的解析逻辑。新版本 Agent 兼容旧版本消息旧版本 Agent 遇到新版本消息时返回明确的错误而不是崩溃。具体实现上可以用策略模式每个版本对应一个解析器接收方根据 version 字段选择解析器。新版本解析器可以复用旧版本的逻辑只覆盖变更部分。迁移时建议分阶段推进先让新版本 Agent 兼容旧版本消息再逐步升级旧版本 Agent最后移除旧版本兼容逻辑。整个过程可能需要几周时间但能保证系统稳定。5.5 调试工具与日志规范通信格式的调试离不开好的工具和日志。我建议在项目初期就建立以下基础设施消息日志所有消息强制打印 message_id、correlation_id、sender、receiver、message_type、timestamp。日志格式统一方便 grep 和聚合。链路追踪用 correlation_id 串联一次完整交互的所有消息在日志系统里能一键还原链路。schema 校验工具提供一个命令行工具输入消息 JSON输出校验结果。方便开发和测试时快速验证。消息回放工具把历史消息录下来支持回放。排查问题时可以复现现场。这些工具的开发成本不高但能大幅提升排查效率。我在一个项目里花了两天做了消息回放工具后来排查一个偶现问题用回放工具十分钟就定位了省下了至少两天的排查时间。5.6 高频踩坑点速查最后整理一份高频踩坑点供快速对照字段命名不统一跨语言时频繁转换可选字段太多解析分支爆炸枚举值用数字日志不可读缺少 message_id无法去重和追踪缺少 correlation_id无法串联链路错误信息不标准排查困难版本号缺失升级时兼容性差序列化方式不统一跨语言解析失败超时和重试策略缺失消息丢失无感知上下文传递过多token 消耗失控这些问题我在不同项目里都遇到过每一个都付出了不小的排查成本。希望这份清单能帮你提前规避。实操心得通信格式的设计不要追求一步到位先跑通核心链路再逐步完善。我见过太多项目在格式设计上花了大量时间结果业务逻辑还没跑通格式设计得再完美也没用。先让消息能传起来再让消息传得稳最后让消息传得快。