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 block | message.tool_calls 数组 |
| 调用编号 | id → "toolu_01A..." | id → "call_abc..." |
| 参数 | input(已是对象) | function.arguments(是 JSON 字符串,要 parse) |
| 结果的角色 | "role": "user" | "role": "tool" |
| 结果回执 id | tool_use_id | tool_call_id |
| 结果内容 | tool_result block 的 content | 该条消息的 content(字符串) |
arguments 是字符串不是对象。
拿到手要先 json.loads,而且模型有可能填出不合法的 JSON——这一步要包异常。
// 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"}
]}
// 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 block | Anthropic 回复由多个块拼成,text / tool_use 混排 | 回复不是一整段字符串 |