Reference · Tool Call Anatomy

工具调用报文速查

一轮工具调用的骨架,以及两家接口的字段对照。忘了哪个字段叫什么名字的时候翻这一页。

不变的骨架

换哪家模型、哪个 SDK,这四步都一样,顺序也一样:

步谁做做什么
1你把工具声明连同整个消息列表发过去
2模型回一个调用请求:工具名 + 参数 + 一个 id。它不执行任何东西
3你把模型那一轮原样存回列表,执行工具,再按 id 追加结果
4模型拿到结果继续。没有新请求 = 这轮结束

字段对照

概念Anthropic(Claude)OpenAI 系(DeepSeek 也是)
工具声明tools=[{name, description, input_schema}]tools=[{type:"function", function:{...}}]
模型的请求回复里的 tool_use blockmessage.tool_calls 数组
调用编号id → "toolu_01A..."id → "call_abc..."
参数input(已是对象)function.arguments(是 JSON 字符串,要 parse)
结果的角色"role": "user""role": "tool"
结果回执 idtool_use_idtool_call_id
结果内容tool_result block 的 content该条消息的 content(字符串)
最容易踩的一格:OpenAI 系的 arguments 是字符串不是对象。 拿到手要先 json.loads,而且模型有可能填出不合法的 JSON——这一步要包异常。

报文样例

Anthropic

// 2. 模型回的(assistant 消息里的一个 block)
{"type": "tool_use", "id": "toolu_01A",
 "name": "bash", "input": {"command": "ls"}}

// 3. 你追加的
{"role": "user", "content": [
  {"type": "tool_result", "tool_use_id": "toolu_01A",
   "content": "code.py\nREADME.md"}
]}

OpenAI / DeepSeek

// 2. 模型回的,你要把整条 assistant 消息原样存回去
{"role": "assistant", "content": "",
 "tool_calls": [{"id": "call_abc", "type": "function",
   "function": {"name": "get_weather",
                "arguments": "{\"city\": \"杭州\"}"}}]}

// 3. 你追加的,每个 call 一条
{"role": "tool", "tool_call_id": "call_abc",
 "content": "{\"温度\": \"18℃\", \"天气\": \"小雨\"}"}

模型凭什么选这个工具

它不知道你有哪些工具,也不知道工具能干什么。它只读到三段文字, 然后做匹配:

它读到的你的天气工具里写的是
工具名get_weather
工具描述「查询某个城市当前和未来两天的天气。群成员问到冷热、下雨、穿什么、要不要带伞、适不适合出门时使用。」
参数描述「城市名,中文,例如「杭州」。没有提到城市时用「杭州」。」

注意描述的写法:它写的是什么时候用我,不是我是什么。 这是有效写法。参数描述里那句「没有提到城市时用杭州」也是同一个路数—— weather.py:148 的注释写着,这句话是原型里 7/7 都传对城市的原因之一。

实测过的证据(weather.py:63): 「只给函数签名、不给这句话,实测七句该查的漏三句。」 那句被去掉的话是 TOOL_HINT,注释原文: 「这句话是承重的,不是文档。」

所以结论是:选哪个工具是提示词工程,不是代码逻辑。 工具选错了,去改描述,不是去改分发代码——ADR-0009 删掉那 1300 行意图分类器 走的就是这条路。

可以自己验:把 get_weather 改名成 function_a、 描述清空,模型基本就不调它了。工具本身一行没动。

三条铁律

规矩违反的后果
每个调用请求都要有一条 id 对得上的结果,一个都不能少 整轮请求被接口拒掉,不是只丢那一个
模型那一轮要原样放回消息列表,再放工具结果 接口看不出这些结果在回应什么,报错
工具声明每一轮都要重发,它不是注册一次就生效 模型不知道自己有工具,直接编答案

小词典

词是什么不是什么
工具调用模型提出的一个请求不是模型执行了什么
工具声明 / schema随每轮请求发过去的一段说明书不是注册,不与你的函数有代码联系
harness循环本身:发请求、认请求、执行、回填不是模型,不含任何智能
一轮(turn)从用户提问到模型不再提工具请求不是一次 HTTP 请求
content blockAnthropic 回复由多个块拼成,text / tool_use 混排回复不是一整段字符串