打造 Agent 最常用的一组基础工具

前面三节，我们已经把 Tool Calling 的底层链路搭起来了。

我们知道模型只是提出：

{
  "name": "read_file",
  "arguments": {
    "path": "app.py"
  }
}

真正执行的是 Harness；我们也已经实现 Tool Registry，让 Harness 知道有哪些 Tool、真实 Python 函数在哪里；随后又实现 Tool Schema，让模型知道工具的名称、用途和参数结构。

现在问题终于来到最实际的一步，到底给 Agent 什么工具，它才真的能开始做事？

这一节我们正式实现七个最常用的基础 Tool：

read_file
write_file
edit_file
list_files
search_files
run_python
run_shell

这七个工具看起来普通，但对 Coding Agent 来说，它们几乎就是最基础的“眼睛、手和验证能力”。

为了不把七个名字记成一张清单，我们先按行为理解：

观察：list_files / search_files / read_file
修改：write_file / edit_file
验证：run_python / run_shell

观察类工具主要增加证据，修改类工具会改变 workspace，执行类工具还会启动新进程。越往后副作用越大，需要的限制也越严格。实际运行时不必每轮都暴露全部工具：只读任务先给观察类工具，确认需要修改后再开放写入和执行能力，模型的动作空间更小，误操作也更容易控制。

这里可以先用一张图把七个 Tool 的位置摆清楚。观察类能力负责“看见事实”，修改类能力负责改变 workspace，执行类能力则负责验证假设。三类工具并不是平铺的一张清单，而是副作用和约束逐渐增强的一条能力链。

后面逐个实现时，大家可以一直带着这张图去看：Tool 越接近真实修改和进程执行，Harness 就越需要补上路径、权限、超时和结果控制。

list_files 让 Agent 先看到项目结构。

search_files 让它在不知道准确路径时找线索。

read_file 让它真正读取代码与配置。

write_file、edit_file 让它修改项目。

run_python、run_shell 则让它验证自己的判断，而不是只凭语言猜测。

更重要的是，我们不会只写七个裸函数。

我们会从一开始就给它们加入：

workspace
路径解析
错误结构化
超时
输出截断
统一 Tool Result

因为一个真正可用的 Agent，工具不是“能运行”就够，而是要“可控、可验证、可反馈”。

这一节最后，我们会让 Agent 第一次真正完成，自己查找文件 → 读取内容 → 做出判断。

这也是整门课第一次，你会明显感觉到，“它真的开始像一个 Agent 了。”

开场引入

如果你自己在一个陌生 Python 项目里排查问题，第一反应通常不是，“我先猜一个最终答案。”

而是会做一系列非常具体的小动作。

比如项目启动失败，你可能先：

ls

看目录。

发现有：

src/
requirements.txt
README.md

然后读：

README.md

看启动方式。

再读：

src/main.py

再搜索：

API_KEY
DATABASE_URL
requests

如果发现代码里 import 了某个包，再去看依赖文件。

然后运行：

python3 src/main.py

或者：

pytest

看真实报错。

你会发现，我们人类排障时最常用的能力，其实并不复杂。

真正重要的是，我们可以不断观察环境、执行动作、根据结果修正判断。

Agent 也是一样。

它不需要一开始就拥有几十个高级 Tool。

只要先有几个最基础、最稳定的能力，就已经可以完成大量任务。

所以这一节我们不追求“大而全”。

我们先把最常见的七个工具做扎实。

这里有一个非常重要的工程原则，Tool 的设计质量，直接决定 Agent 的行为质量。

比如 read_file 如果没有路径边界，模型可能读取 workspace 之外的文件。

run_shell 如果直接：

subprocess.run(command, shell=True)

而没有任何限制，风险会非常大。

search_files 如果一口气扫几十万个文件、把所有结果塞回 Context，Agent 很快就会爆上下文。

run_python 如果不设 timeout，模型生成一个死循环，整个 Run 就卡住。

所以我们不能把 Tool 当成“随手包一个函数”。

一个合格 Tool 至少要考虑：

输入是什么？
输出是什么？
失败怎么表示？
是否有副作用？
是否可能很慢？
结果会不会太大？
是否越过 workspace？

这一节我们会边实现边回答这些问题。

知识地图

这一节把前面的 Tool Registry 与 Tool Schema 真正变成可用能力。

如果把上面的链路换成更接近真实使用的视角，可以看到它其实是在逐步缩小不确定性：先知道“项目里有什么”，再知道“线索在哪”，最后才读取完整上下文。

这种顺序比连续猜测文件名稳定得多。每一步拿到的 Observation，都会直接决定下一次 Tool Call，而不是提前把整个项目一股脑塞给模型。