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 这个列表在一轮工具调用里长了两条。谁写的、写了什么:
第 2 条和第 3 条之间那个 toolu_01A,是这一轮唯一的粘合剂。
模型可能一次提出三个调用,你回的三条结果就靠这个 id 各自认领。
少回一条,整轮报废——接口会直接报错,因为它看不出你漏答了哪个。
这一点几乎所有人第一次看都觉得别扭:命令是我跑的,结果是机器给的, 怎么算「用户说的话」?
因为 Anthropic 的 Messages 接口只有 user 和
assistant 两种角色,没有第三种(API 参考)。
工具结果不是模型说的,那就只能放在另一边。
"role": "user" 在这里的意思是「这不是模型自己产出的内容」,
而不是「这句话是人打的」。
"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=TOOLS | payload["tools"] = [...tool_declaration()] | 发说明书 |
block.type == "tool_use" | self._tool_calls(choice) | 看模型提没提请求 |
messages.append(assistant) | conversation.append({...}) | 把模型那轮原样放回去 |
run_bash(...) | weather.look_up(city, ...) | 你的代码真正干活 |
tool_use_id | tool_call_id | 结果认领哪个调用 |
while True | allow_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。试着问一个不需要工具的问题
(比如「你是谁」),看循环是不是一轮就退出了。