在上一篇，我们给 Agent 画好了“思考-执行-停止”的状态机轨道。
现在，它需要进入“执行（Action）”阶段了。我们要给它配备两把最称手的兵器：网络请求（查资料） 和 文件读写（留存证据）。

在给 AI 配备工具时，很多新手会犯一个致命错误：把人类用的复杂工具原封不动地丢给 AI。
比如给 AI 开放一个可以执行任意 SQL 语句的接口，结果 AI 顺手就执行了全表扫描，把数据库搞挂了。

给 AI 写工具，核心原则是：封装得越傻瓜越好，防呆机制（防爆雷）做得越厚越好。

---

1. 怎么告诉 AI 它有什么工具？（Tool Schema）

大模型看不懂你的 Python 或 Java 代码。你必须用一种名为 JSON Schema 的通用语言，向大模型“自我介绍”你的工具箱里有什么。

这个过程就像给瞎子递菜单，你不仅要告诉它菜名，还要详细说明这道菜是用什么做的（参数）。

核心要素：

• name：工具名称（如 fetch_webpage）。
• description：详细描述这个工具能干嘛。这是大模型决定是否调用它的唯一依据！ 必须写得极其清晰。
• parameters：这个工具需要哪些输入参数，类型是什么，是不是必填的。

---

2. 实战开发：接入两类核心工具

工具一：安全的网络抓取（Web Fetcher）

痛点：直接让 AI 用 requests 去抓网页，它会被反爬虫拦住，或者抓回来一堆几万字的 HTML 乱码，瞬间把 Token 撑爆。

封装思路（防呆机制）：

1. 底层使用 BeautifulSoup 或 Playwright 过滤掉所有的 CSS、JS 和广告，只提取纯文本。
2. 强制截断：如果网页正文超过 2000 字，工具底层自动截断，并返回警告：“网页过长，已截取前 2000 字。”

给大模型的 Schema 示例：

{
  "name": "fetch_clean_webpage",
  "description": "抓取指定 URL 的网页内容。工具会自动剥离 HTML 标签和广告，只返回纯净的正文文本。适用于获取新闻、文档等信息。",
  "parameters": {
    "type": "object",
    "properties": {
      "url": {
        "type": "string",
        "description": "必须是一个完整的、合法的 HTTP/HTTPS 链接"
      }
    },
    "required": ["url"]
  }
}

工具二：带权限边界的文件写入（File Writer）

痛点：如果给 AI 开放了文件系统权限，它可能会不小心覆盖掉你电脑里的重要代码，甚至把你的 .ssh 密钥文件写坏。

封装思路（权限隔离）：

1. 在工具代码的底层，强制设定一个“工作目录（Workspace）”（比如 /tmp/agent_workspace/）。
2. 无论 AI 传入什么路径，工具都会进行检查，绝对不允许跳出这个工作目录。

给大模型的 Schema 示例：

{
  "name": "write_report_to_file",
  "description": "将你分析好的报告内容写入到本地文件中进行留存。",
  "parameters": {
    "type": "object",
    "properties": {
      "filename": {
        "type": "string",
        "description": "只需提供文件名（如 report.md），严禁包含路径分隔符（/ 或 \\）"
      },
      "content": {
        "type": "string",
        "description": "你要写入的完整报告内容"
      }
    },
    "required": ["filename", "content"]
  }
}

---

3. 本篇产出：工具清单、权限边界与审计格式

当你在团队内开发 Agent 时，每一把新增的工具都必须登记在册。请使用以下清单格式进行管理，确保没有高危工具在“裸奔”：

工具名称 (Tool Name)	核心功能	权限边界 (Boundary)	失败兜底 (Fallback)	审计要求
fetch_clean_webpage	抓取纯文本网页	无网络写权限，单次最大返回 2000 字符。	遇 403/404 返回：“目标网站拒绝访问”。	记录请求的 URL。
write_report_to_file	保存分析报告	仅限于 /workspace 目录。不允许覆盖已有文件。	遇同名文件返回：“文件已存在，请更换文件名”。	记录写入的文件名和大小。
query_database_schema	查表结构	数据库账号仅 Read-Only。严禁暴露用户密码字段。	遇查询超时返回：“数据库繁忙”。	记录查询的表名。

---

总结与复盘

• 大模型只负责“想”，工具代码负责“干”。
• 不要把大模型当成无所不能的神，要把它当成一个“容易犯错的实习生”。你给它分配的工具，必须自带“防割手”的安全罩。
• Schema 的 description 是重中之重。 它写得越清晰，大模型调用错工具的概率就越低。

下一步路线提示：
大脑（状态机）有了，手脚（工具）也接上了。我们的 Agent 终于可以去抓网页、写报告了。
但如果它在抓第 99 个网页的时候，你家断网了，程序崩溃退出。这前 98 个网页的辛苦劳动就白费了吗？
下一篇，我们将进入项目 C 的大结局：《失败可恢复：断点续跑与任务日志可重放》。