←AI 实践笔记

Lesson 01 · s01 Agent Loop

一次工具调用,
在报文里长什么样

s01 的 README 把工具调用写成了五步 Python 代码,唯独没贴那几条 JSON。 看不见报文,这五步就只能背,不能懂。这一课把那一轮往返摊开。

先纠一个最容易错的地方

README 第 4 步里有这么一行:

output = run_bash(block.input["command"])

这是整段代码里唯一真正跑命令的地方——而 run_bash 是你自己写的函数,就在同一个文件里(code.py 第 69 行,里面是 subprocess.run)。模型没有跑任何东西。

模型从头到尾只做了一件事:在它的回复里多塞了一个块,内容大意是 「我想调 bash,命令是 ls,这次调用的编号是 toolu_01A」。 它把这个块吐出来就结束了这一轮,然后停在那儿等。

「工具调用」这个词有误导性。模型不调用工具,它只是提出请求。 调用的是你的循环。

一轮往返,四条报文

messages 这个列表在一轮工具调用里长了两条。谁写的、写了什么:

messages[] 谁写进去的 "role": "user" "帮我看看这个目录下有哪些文件" 你 "role": "assistant" type: "tool_use", id: "toolu_01A", name: "bash", input: {"command": "ls"} 模型 "role": "user" type: "tool_result", tool_use_id: "toolu_01A", content: "code.py\nREADME.md" 你 "role": "assistant" type: "text" —— 没有 tool_use,循环退出 模型 每一轮都把整个列表重发一次——模型自己不记得上一轮。

第 2 条和第 3 条之间那个 toolu_01A,是这一轮唯一的粘合剂。 模型可能一次提出三个调用,你回的三条结果就靠这个 id 各自认领。 少回一条,整轮报废——接口会直接报错,因为它看不出你漏答了哪个。

为什么工具结果挂在 "user" 名下

这一点几乎所有人第一次看都觉得别扭:命令是我跑的,结果是机器给的, 怎么算「用户说的话」?

因为 Anthropic 的 Messages 接口只有 user 和 assistant 两种角色,没有第三种(API 参考)。 工具结果不是模型说的,那就只能放在另一边。 "role": "user" 在这里的意思是「这不是模型自己产出的内容」, 而不是「这句话是人打的」。

这是各家接口的口味差异,不是原理差异。OpenAI 那套(DeepSeek 也用) 就多开了一个 "role": "tool" 的角色。同一件事,两种写法。 → 对照表

那份 TOOLS 声明是什么

code.py 顶上那段:

TOOLS = [{
    "name": "bash",
    "description": "Run a shell command.",
    "input_schema": {
        "type": "object",
        "properties": {"command": {"type": "string"}},
        "required": ["command"],
    },
}]

它不是注册,不是绑定,跟你的 run_bash 函数没有任何代码层面的联系。 它就是一段说明书,每一轮请求都随 messages 一起发给模型, 告诉它:你可以提这么一个请求,名字叫 bash,参数得叫 command,是个字符串。

模型照着这份说明书填表。表填好发回来,靠 block.input["command"] 取出来喂给 run_bash 的——还是你写的那行代码。 声明和执行是两件完全分开的事,中间只靠一个名字对上。

你自己项目里就有一份

src/digital_avatar/geweapi/deepseek_transport.py 的 _complete(),做的是同一件事,顺序一模一样:

s01 教程你的分身这一步在做什么
tools=TOOLSpayload["tools"] = [...tool_declaration()]发说明书
block.type == "tool_use"self._tool_calls(choice)看模型提没提请求
messages.append(assistant)conversation.append({...})把模型那轮原样放回去
run_bash(...)weather.look_up(city, ...)你的代码真正干活
tool_use_idtool_call_id结果认领哪个调用
while Trueallow_tool_calls=False← 唯一的不同

最后一行是重点。教程用 while True,模型想调几轮就调几轮。 你的分身把这个循环拆开摊平成了一次:查完天气再问一遍模型, 这一遍明确不许再提工具请求,提了就当无效重试。

这不是简化版,是一个有意的取舍——微信群里回一句话,不能让模型自己决定 要往返几趟。你已经在用 s01 的机制了,只是把它按住了。

回想一下

模型说要调 bash 执行 ls,真正去跑这条命令的是谁?

模型只产出一个 tool_use 块然后停下。run_bash 是你文件里的 subprocess.run,跑在你自己的机器上,用的是你自己的权限—— 所以 s01 的 README 才要提醒你去临时目录里跑。

工具结果为什么要用 "role": "user" 追加回去?

Messages 接口只有 user / assistant。工具结果不是模型产出的, 只能归到 user 那一侧。这是格式约束,不是语义上真的把它当成人说的话—— 换成 OpenAI 格式就有第三个角色 tool 了。

模型一次提了 3 个工具请求,你只回了 2 条结果,会怎样?

每个 tool_use 必须有一条 id 对得上的结果,接口才收。你自己代码里那句 「每个 tool_call 都必须有一条对应的 tool 消息,少一条整轮就废」写的就是这件事。

下一步

读这一份: Anthropic 官方 Tool use 总览。 只看开头到「How tool use works」那一节就够,十分钟。它把这一课讲的四条报文 用官方的话又说了一遍——两个来源对上了,你就可以放心把它当事实用。

动手(可选,五分钟): 在教程仓库里跑 python s01_agent_loop/code.py,问它「这个目录下有几个 py 文件」。 黄色那行就是模型填出来的 command。试着问一个不需要工具的问题 (比如「你是谁」),看循环是不是一轮就退出了。