手搓 Agent(六):练出巧手——好工具长什么样,再给它一台电脑

0 阅读15分钟

《手搓 Agent》系列第 6 篇,共 10 篇。系列导读与目录|上一篇:学会翻书——RAG,先查资料再回答

图 6-1 系列地图

图 6-1 系列地图。这一篇回到右边绿色的框:手脚。

前言

上一篇结尾数了数,小记的工具已经有四个了。工具一多,它开始犯两种错:选错工具,填错参数。

我的第一反应是模型不够聪明。后来把出错的那几圈翻出来看,发现很多时候问题在我这边:两个工具的描述读起来差不多,参数名只有一个字母,出错时只返回一句“失败”。换成一个新来的同事,拿着这样的说明也会用错。

第二篇讲过,模型看不到工具里面的代码。它对一个工具的全部了解,就是我写给它的那几行字,加上每次调用返回的那段文字。这些文字写得清不清楚,决定了它用得对不对。

这一篇分两半。前一半讲怎么把工具写清楚。后一半给小记一个万能工具:让它自己写代码、自己运行。小记升到 v0.6。

本篇要点:

  • 工具的名字、描述、参数、返回值,都是写给模型看的,要像给人写说明书一样写。
  • 工具不是越多越好。与其给一堆专用工具,不如给一个能运行代码的。
  • 读文件、写文件、运行命令,再加上那个循环,就是 Coding Agent 干活的方式。

一、模型眼里的工具

人用软件靠的是界面:按钮上写着字,点错了会弹出提示。模型用工具也有一个“界面”,只不过全是文字。

图 6-2 模型眼里的工具

图 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 两种写法

图 6-3 左边的写法,每一项都要模型去猜。

对着含糊版,模型要猜三件事:获取的是哪一篇,全文还是标题;s 该填文件名、主题,还是关键词;它和别的工具有什么区别。猜错一件,这一圈就白转了。

2.2 名字、描述、参数

名字用“动词加对象”,让人一眼看出它做什么。read_note 比 get 好。几个工具功能相近时,名字里要带出区别:search_notes 是按意思找几段,read_note 是读指定的一篇。

描述至少回答三个问题:

  • 它做什么,返回什么。
  • 什么时候该用它。
  • 什么时候别用它。

第三条最容易漏,偏偏最管用。模型选错工具,多半是因为两个工具的描述都只写了自己能做什么,没写边界在哪。清楚版里那句“只知道主题、不知道文件名时不要用它猜”,就是在划边界。

参数有四条:

  • 名字用完整的词,name、offset,不用 s、n。
  • 写清格式,给一个例子。日期、编号、文件名这类有格式要求的,一个例子比一段解释管用。
  • 能不要的参数就不要,有默认值的把默认值写出来。
  • 取值只有固定几种的,用枚举列出来,别让它自由发挥。

提示 发现它老是选错工具、填错参数,先别急着改系统提示词,回头把工具的说明书读一遍。把自己当成第一次见到这个工具的人,看凭这几行字能不能用对。

三、返回值也是写给它看的

3.1 太长了怎么办

一篇笔记两万字,read_note 该返回什么?

图 6-4 返回值的三种写法

图 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 专用工具和写代码

图 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 的循环

图 6-6 报错不是终点,是下一圈的输入。

现在常见的编程助手,也就是 Coding Agent,核心就是这个圈。它们手里的工具其实很少:读文件、写文件、运行命令,外加搜索。循环也还是第二篇那个循环。

写代码是 Agent 最先做成的事情,有一个朴素的原因:对不对,跑一下就知道。运行结果和报错是现成的反馈,而且做不了假。写一篇文章、做一份调研,就很难有这么明确的信号。

反过来这也是用好它的窍门:先给它一个能自己检验的办法,比如一组测试、一个能运行的例子。它有了检验的办法,才能自己一圈一圈转下去,不用我每一步都盯着。

常见误区

我原来以为实际上
它用错工具,是模型不够聪明先看说明书。描述含糊、边界没写,换谁来都得猜
工具描述是写给开发者看的注释是写给模型看的。它只能靠这几行字决定用不用、怎么用
工具返回的内容越全越好越长越占上下文。要截断,并且说明怎么接着读
出错时返回一句“失败”就行报错要说清错在哪、下一步可以怎么做
工具越多,它能做的事越多说明书占上下文,相近的工具还会互相干扰。少而清楚更好
让它运行代码,只有写程序时才用得上计数、排序、批量处理,写代码比一圈圈调工具又快又准

小结

  • 模型对工具的全部了解,是说明书和返回值这两头的文字。设计工具就是把这些文字写好。
  • 描述要写清做什么、什么时候用、什么时候别用。参数要有格式和例子。
  • 返回值太长要截断并说明怎么接着读。报错要能指路,不要悄悄替它改参数。
  • 工具要少而清楚。
  • 给它一个运行代码的工具,很多专用工具就不需要了。报错会成为它下一圈的输入。

这一版的小记:

小记 v0.6
比上一版多了什么read_note 能分段读,报错会指路;新增 run_python 工具
能做什么统计、排序、批量处理这类事,自己写代码完成;代码报错了自己改
还有什么问题想要新的能力,每一样都得我自己动手写成工具

下一篇

小记现在能读笔记,能写代码。可我还想让它查网页、看日历、读团队的文档。

这些能力别人早就写好了。难道我要照着每个服务的接口,一个个重写成自己的工具?反过来,我给小记写的笔记工具,换一个 Agent 程序也用不上,还得照着那边的格式再写一遍。

工具能不能像插头一样,写一次,哪个 Agent 都能插上用?下一篇让它借来工具箱。

下一篇:手搓 Agent(七):借来工具箱——MCP 和 Skill(写完后在这里补链接)