工具结果回填 协议

它是什么

工具结果回填是把工具执行结果送回模型的协议动作：执行完工具后，为每个调用追加一条 { role: 'tool', tool_call_id, content } 消息，tool_call_id 与调用 id 一一配对，再连同带 tool_calls 的 assistant 消息一起发起第二次请求。模型是无状态的，它只看得见这次请求里的消息——丢掉 assistant 消息或配错 id，第二轮就会答非所问，这是最常见的实现错误。

两条硬约束

• 结果必须是字符串：模型只能读文本。函数返回对象/数组/数字都要序列化；返回 undefined（动作型工具如「邮件已发送」）就回填一句 "success" 之类的说明；
• 必须用 role: 'tool'，不要拼进 user 消息：协议给了专门的工具角色，拼进 user 文本（「工具返回：24°C」）会丢失配对信息（哪个结果对应哪个调用），模型一多问几个就乱。

错误怎么回填

工具失败时不是把异常抛给用户，而是把错误文本作为 tool_result 回填，让模型读到失败原因后自己纠正重试——第 08 章的统一错误协议把它工程化。OpenAI 与 Anthropic 的载体不同（独立的 role: 'tool' 消息 vs 下一条 user 消息里的 tool_result block），配对逻辑相同（tool_call_id ↔ tool_use_id）。完整流程见第 06 章。