《手搓 Agent》系列第 6 篇,共 10 篇。系列导读与目录|上一篇:学会翻书——RAG,先查资料再回答
图 6-1 系列地图。这一篇回到右边绿色的框:手脚。
前言
上一篇结尾数了数,小记的工具已经有四个了。工具一多,它开始犯两种错:选错工具,填错参数。
我的第一反应是模型不够聪明。后来把出错的那几圈翻出来看,发现很多时候问题在我这边:两个工具的描述读起来差不多,参数名只有一个字母,出错时只返回一句“失败”。换成一个新来的同事,拿着这样的说明也会用错。
第二篇讲过,模型看不到工具里面的代码。它对一个工具的全部了解,就是我写给它的那几行字,加上每次调用返回的那段文字。这些文字写得清不清楚,决定了它用得对不对。
这一篇分两半。前一半讲怎么把工具写清楚。后一半给小记一个万能工具:让它自己写代码、自己运行。小记升到 v0.6。
本篇要点:
- 工具的名字、描述、参数、返回值,都是写给模型看的,要像给人写说明书一样写。
- 工具不是越多越好。与其给一堆专用工具,不如给一个能运行代码的。
- 读文件、写文件、运行命令,再加上那个循环,就是 Coding Agent 干活的方式。
一、模型眼里的工具
人用软件靠的是界面:按钮上写着字,点错了会弹出提示。模型用工具也有一个“界面”,只不过全是文字。
图 6-2 中间的函数怎么实现,模型一无所知。它看到的只有两头的文字。
- 调用之前,它看到的是说明书:名字、描述、参数。
- 调用之后,它看到的是返回值:正常时是结果,出错时是报错。
所以设计一个工具,除了把函数写对,还要把这四样文字写好。下面一样一样看。
二、说明书怎么写
2.1 一个反例,一个改写
同一个“读笔记”的工具,说明书可以写成两个样子。
BAD = {"type": "function", "function": { # 含糊版:模型只能猜
"name": "get",
"description": "获取笔记",
"parameters": {"type": "object", "properties": {"s": {"type": "string"}}}}}
READ_NOTE = {"type": "function", "function": { # 清楚版
"name": "read_note",
"description": "读 notes 文件夹里的一篇笔记,返回正文。只知道主题、不知道文件名时不要用它猜。"
"一次最多返回 limit 个字,没读完时末尾会提示怎么接着读。",
"parameters": {"type": "object", "required": ["name"], "properties": {
"name": {"type": "string", "description": "带后缀的文件名,例如 上下文.md"},
"offset": {"type": "integer", "description": "从第几个字开始读,默认 0"},
"limit": {"type": "integer", "description": "最多读多少字,默认 2000"}}}}}
图 6-3 左边的写法,每一项都要模型去猜。
对着含糊版,模型要猜三件事:获取的是哪一篇,全文还是标题;s 该填文件名、主题,还是关键词;它和别的工具有什么区别。猜错一件,这一圈就白转了。
2.2 名字、描述、参数
名字用“动词加对象”,让人一眼看出它做什么。read_note 比 get 好。几个工具功能相近时,名字里要带出区别:search_notes 是按意思找几段,read_note 是读指定的一篇。
描述至少回答三个问题:
- 它做什么,返回什么。
- 什么时候该用它。
- 什么时候别用它。
第三条最容易漏,偏偏最管用。模型选错工具,多半是因为两个工具的描述都只写了自己能做什么,没写边界在哪。清楚版里那句“只知道主题、不知道文件名时不要用它猜”,就是在划边界。
参数有四条:
- 名字用完整的词,
name、offset,不用s、n。 - 写清格式,给一个例子。日期、编号、文件名这类有格式要求的,一个例子比一段解释管用。
- 能不要的参数就不要,有默认值的把默认值写出来。
- 取值只有固定几种的,用枚举列出来,别让它自由发挥。
提示 发现它老是选错工具、填错参数,先别急着改系统提示词,回头把工具的说明书读一遍。把自己当成第一次见到这个工具的人,看凭这几行字能不能用对。
三、返回值也是写给它看的
3.1 太长了怎么办
一篇笔记两万字,read_note 该返回什么?
图 6-4 中间那种最危险:它不知道自己只看了一部分。
全文塞回去,上下文一下被占掉一大块,之后每一圈都要重发。悄悄截断更糟,它会照着半篇笔记下结论。稳妥的做法是只给一段,同时告诉它全文多长、怎么接着读。这就是第四篇说的“裁剪要留一条退路”。
3.2 报错要能指路
工具出了错,返回什么,决定了模型下一步怎么走。
| 报错的写法 | 模型接下来会怎样 |
|---|---|
| 程序直接崩掉 | 没有接下来了 |
| 失败 | 不知道错在哪,多半原样再试一次 |
| 没有 rag.md 这篇笔记 | 知道错在哪,但不知道该换成什么 |
| 没有 rag.md 这篇笔记。现有的笔记:……。请换成其中一个名字再试 | 知道错在哪,也知道下一步怎么办 |
一条好的报错说清三件事:错在哪,为什么,下一步可以怎么做。
还有一条容易忽略:不要悄悄替它改参数。比如它传来一个不存在的文件名,工具“好心”地挑了一个名字最像的读出来。它不知道被换过,会把这篇当成它要的那篇。对不上就明说,让它自己决定。
3.3 改写后的 read_note
下面是准备工作和改写后的函数。要看的是两个 return 前面各加了什么。
import json, os, pathlib, subprocess, sys
from openai import OpenAI
client = OpenAI(base_url=os.environ["LLM_BASE_URL"], api_key=os.environ["LLM_API_KEY"])
MODEL = os.environ["LLM_MODEL"]
NOTES = pathlib.Path("notes")
if not NOTES.exists(): # 没有 notes 文件夹的话,先建三篇样例:一篇短的,一篇很长的,一篇编码是 GBK 的旧笔记
NOTES.mkdir()
(NOTES / "工具.md").write_text("模型只输出想调用哪个工具,真正动手的是我的程序。", encoding="utf-8")
(NOTES / "上下文.md").write_text("\n".join(f"第 {i} 条:上下文是模型看到的全部世界。" for i in range(1, 301)), encoding="utf-8")
(NOTES / "旧笔记.md").write_text("这是很早以前记的一篇笔记。", encoding="gbk")
def read_note(name, offset=0, limit=2000):
"""读一篇笔记。太长就只给一段,并说明怎么接着读;找不到就告诉它有哪些。"""
path = NOTES / name
if not path.exists():
names = "、".join(sorted(p.name for p in NOTES.glob("*.md")))
return f"出错了:没有 {name} 这篇笔记。现有的笔记:{names}。请换成其中一个名字再试。"
text = path.read_text(encoding="utf-8")
part = text[offset:offset + limit]
if offset + limit < len(text):
part += f"\n\n[全文 {len(text)} 字,这里是第 {offset} 到 {offset + limit} 字。接着读请用 offset={offset + limit}]"
return part
不经过模型,直接调用这个函数看看它返回什么。read_note("rag.md"):
出错了:没有 rag.md 这篇笔记。现有的笔记:上下文.md、工具.md、旧笔记.md。请换成其中一个名字再试。
read_note("上下文.md") 返回前 2000 字,末尾多出一行:
[全文 6791 字,这里是第 0 到 2000 字。接着读请用 offset=2000]
这两句话都是写给模型看的。它读到之后该做什么,句子里已经说了。
四、工具不是越多越好
把每个需求都做成一个工具,工具很快就有二三十个。这会带来两个麻烦。
- 占上下文。 每个工具的说明书都在静态前缀里,每一圈都要发。写得越清楚越长,二三十个工具就是好几千字。
- 互相干扰。 工具越多、越像,选错的机会越大。
所以工具要少而清楚。两个常用的办法:
- 功能重叠的并成一个。能用一个参数区分的,就不要拆成两个工具。
- 按“要办成的事”来设计,不照着底层有哪些接口来设计。比如把一篇笔记挪进归档文件夹,如果只给“复制”和“删除”两个工具,它得连调两次,中间出错还会留下半截。直接给一个“归档”,一步到位。
可需求是没有尽头的。今天要统计字数,明天要批量改文件名,后天要把笔记导出成表格,不可能每样都做一个工具。有没有一个工具,能顶替一大堆专用工具?
五、万能工具:让它写代码并运行
5.1 为什么是代码
有。让模型自己写一段代码,我的程序替它运行,把输出还给它。
拿一个具体的任务比一比:统计每篇笔记的字数,从多到少排。
图 6-5 同一个任务,左边要把每篇笔记都读进上下文,右边只有结果进上下文。
写代码的办法好在三处:
- 圈数少。 不管有多少篇笔记,一段代码一次处理完。
- 省上下文。 笔记的内容在代码里流过,不进上下文,进来的只有最后几行结果。
- 算得准。 第一篇讲过,模型是在猜下一个词,不是在计算,数数、算数、排序它会出错。这些交给程序,不会错。
还有一层更要紧:没有现成工具的事,它也能做了。改文件名、转格式、画图,只要代码能做到。会写代码,相当于有了一个可以临时造工具的工具。
5.2 run_python
下面是这个工具。要看的是出了各种状况时,它分别返回什么。
def run_python(code):
"""把模型写的代码存成文件,另起一个 Python 进程运行,返回它打印的内容。"""
pathlib.Path("_task.py").write_text(code, encoding="utf-8")
try:
r = subprocess.run([sys.executable, "_task.py"], capture_output=True, text=True, timeout=30)
except subprocess.TimeoutExpired:
return "出错了:运行超过 30 秒,被中止了。请检查有没有死循环,或者把任务拆小。"
out = r.stdout + ("\n[报错]\n" + r.stderr if r.returncode else "")
if len(out) > 3000: # 输出太长时留头留尾:开头看得出在做什么,报错一般在结尾
out = out[:1500] + f"\n……(中间省略 {len(out) - 3000} 字)……\n" + out[-1500:]
return out or "(运行成功,但没有打印任何内容。想看结果要用 print)"
RUN_PYTHON = {"type": "function", "function": {
"name": "run_python",
"description": "运行一段 Python 代码,返回它 print 出来的内容。需要计数、排序、批量处理文件时用它,不要自己心算。"
"代码在当前目录运行,笔记在 notes 文件夹里。",
"parameters": {"type": "object", "required": ["code"], "properties": {
"code": {"type": "string", "description": "完整的 Python 代码,结果要用 print 输出"}}}}}
- 代码在另一个进程里运行。它写出死循环或者运行崩了,都不会连累小记自己,最多等 30 秒。
- 代码报错时,把报错原样还给它。这是它改代码的依据。
- 输出太长时留头留尾。什么都没输出时也回一句话,告诉它要用
print。 - 描述里写了什么时候该用它:“需要计数、排序、批量处理文件时用它,不要自己心算”。
注意
run_python会执行模型写出来的任何代码,包括删除文件。这里只有超时,没有任何隔离。请在一个专门的空文件夹里试,里面不要放重要的东西。怎么把它关进笼子,第八篇讲。
六、Coding Agent 就是这么干活的
6.1 接上循环,跑一次
循环还是第二篇那个,多了一处:工具自己抛了异常,也接住,交还给模型。
TOOLS = [READ_NOTE, RUN_PYTHON]
FUNCTIONS = {"read_note": read_note, "run_python": run_python}
messages = [{"role": "system", "content": "你是小记,帮我整理 notes 文件夹里的学习笔记。回答尽量简短。"}]
def run(question, max_steps=8):
messages.append({"role": "user", "content": question})
for step in range(1, max_steps + 1):
resp = client.chat.completions.create(model=MODEL, messages=messages, tools=TOOLS)
msg = resp.choices[0].message
messages.append(msg)
if not msg.tool_calls:
return msg.content
for call in msg.tool_calls:
print(f" [第 {step} 圈] {call.function.name} {call.function.arguments}")
try:
result = FUNCTIONS[call.function.name](**json.loads(call.function.arguments))
except Exception as e: # 工具自己出了错,也要把错误交还给模型,不能让程序崩掉
result = f"出错了:{e}"
print(" 结果:" + result.strip()[-100:].replace("\n", " "))
messages.append({"role": "tool", "tool_call_id": call.id, "content": result})
return "步数用完了,还没做完。"
while True: # 按 Ctrl+C 退出
print("小记:" + run(input("我:")))
把四段代码按顺序放进同一个文件,就是小记 v0.6(第一段里的 BAD 只是反例,程序用不到,留着也不碍事)。样例笔记里我故意放了一篇 GBK 编码的旧笔记,然后让它统计字数:
我:notes 里每篇笔记各有多少字?按字数从多到少排。
[第 1 圈] run_python {"code": "import os\n……t = open(os.path.join('notes', f), encoding='utf-8').read()\n……"}
结果:……UnicodeDecodeError: 'utf-8' codec can't decode byte 0xd5 in position 0: invalid continuation byte
[第 2 圈] run_python {"code": "……raw = open(p,'rb').read()\n for enc in ('utf-8','gb18030','utf-16'):\n try:\n t = raw.decode(enc); break\n except UnicodeDecodeError: continue\n……"}
结果:5892 6791 utf-8 上下文.md 24 24 utf-8 工具.md 13 13 gb18030 旧笔记.md 总数 3
[第 3 圈] run_python {"code": "……"}
结果:notes 3 旧笔记.md 工具.md 上下文.md 总文件数 3
小记:notes 里共 3 篇:
| 笔记 | 字数(不含空白) |
|---|---|
| 上下文.md | 5892 |
| 工具.md | 24 |
| 旧笔记.md | 13 |
补充一句:旧笔记.md 的编码是 GBK(其他两篇是 UTF-8),读的时候要留意中文会不会乱码。
它写的代码比较长,上面用省略号删掉了一部分。
第 1 圈它按最常见的 UTF-8 去读,撞上了那篇旧笔记,代码报错。报错原样回到它手里。第 2 圈它把代码改成几种编码挨个试,跑通了。第 3 圈它又核对了一遍文件总数,才回答。
没有人告诉它旧笔记是 GBK 编码,是报错告诉它的。跑、看报错、改、再跑,这中间我一句话都没插。
这是我这一次运行的记录。模型每次写出的代码不一样,转的圈数也会不一样。
6.2 读、改、跑、看结果
把上面的过程画出来,是一个圈。
图 6-6 报错不是终点,是下一圈的输入。
现在常见的编程助手,也就是 Coding Agent,核心就是这个圈。它们手里的工具其实很少:读文件、写文件、运行命令,外加搜索。循环也还是第二篇那个循环。
写代码是 Agent 最先做成的事情,有一个朴素的原因:对不对,跑一下就知道。运行结果和报错是现成的反馈,而且做不了假。写一篇文章、做一份调研,就很难有这么明确的信号。
反过来这也是用好它的窍门:先给它一个能自己检验的办法,比如一组测试、一个能运行的例子。它有了检验的办法,才能自己一圈一圈转下去,不用我每一步都盯着。
常见误区
| 我原来以为 | 实际上 |
|---|---|
| 它用错工具,是模型不够聪明 | 先看说明书。描述含糊、边界没写,换谁来都得猜 |
| 工具描述是写给开发者看的注释 | 是写给模型看的。它只能靠这几行字决定用不用、怎么用 |
| 工具返回的内容越全越好 | 越长越占上下文。要截断,并且说明怎么接着读 |
| 出错时返回一句“失败”就行 | 报错要说清错在哪、下一步可以怎么做 |
| 工具越多,它能做的事越多 | 说明书占上下文,相近的工具还会互相干扰。少而清楚更好 |
| 让它运行代码,只有写程序时才用得上 | 计数、排序、批量处理,写代码比一圈圈调工具又快又准 |
小结
- 模型对工具的全部了解,是说明书和返回值这两头的文字。设计工具就是把这些文字写好。
- 描述要写清做什么、什么时候用、什么时候别用。参数要有格式和例子。
- 返回值太长要截断并说明怎么接着读。报错要能指路,不要悄悄替它改参数。
- 工具要少而清楚。
- 给它一个运行代码的工具,很多专用工具就不需要了。报错会成为它下一圈的输入。
这一版的小记:
| 小记 v0.6 | |
|---|---|
| 比上一版多了什么 | read_note 能分段读,报错会指路;新增 run_python 工具 |
| 能做什么 | 统计、排序、批量处理这类事,自己写代码完成;代码报错了自己改 |
| 还有什么问题 | 想要新的能力,每一样都得我自己动手写成工具 |
下一篇
小记现在能读笔记,能写代码。可我还想让它查网页、看日历、读团队的文档。
这些能力别人早就写好了。难道我要照着每个服务的接口,一个个重写成自己的工具?反过来,我给小记写的笔记工具,换一个 Agent 程序也用不上,还得照着那边的格式再写一遍。
工具能不能像插头一样,写一次,哪个 Agent 都能插上用?下一篇让它借来工具箱。
下一篇:手搓 Agent(七):借来工具箱——MCP 和 Skill(写完后在这里补链接)