从零构建基础 AI Agent：工具篇

背景

在上一篇文章《从零构建基础 AI Agent》中，我们搭建了一个最基础的 AI Agent 框架。该框架仅包含与模型的连接、用户输入处理、对话上下文存储以及维持 Agent 运行的循环逻辑。然而，这样一个仅依赖内部知识进行问答的 Agent 实用性有限。

为了让 Agent 真正具备“工作”能力，即代表用户执行任务，必须赋予其在运行环境（即计算机）中采取行动的能力。实现这一目标的核心机制就是“工具”（Tools）。本文旨在深入解析如何为 AI Agent 集成工具，使其能够自主调用函数、操作文件系统、执行命令及访问网络，从而将静态的对话模型转化为动态的任务执行者。

核心内容

什么是工具（Tools）？

工具是暴露给大语言模型（LLM）的程序或函数，允许 LLM 自主调用。工具的复杂度跨度极大：

• 简单场景：在 Agent 代码中实现的 Python 函数。
• 复杂场景：基于 MCP（Model Context Protocol，模型上下文协议）的服务器，通过 HTTP 请求与 API 交互以读取或更新数据库。
  • 注：MCP 协议将在本系列的后续章节中详细讨论。

Agent 如何使用工具？

LLM 本质上是文本输出模型，因此需要特定的机制来调用工具：

1. 早期实现：依赖提示词让 LLM 输出特定格式的文本（如 Action: web_fetch），再由 Agent 框架解析文本并执行函数。这种方式可靠性较低，因为模型有时无法严格遵循预期格式。
2. 现代实现：现代 LLM 已原生支持工具调用（Native Tool Calling）。这些模型经过微调，能够直接输出结构化的 JSON 格式工具请求。这种原生实现内置了验证机制，最大限度地减少了幻觉（Hallucinations），提高了 Agent 调用工具时的可靠性。

构建基础工具集

为了增强 Agent 的能力，我们在之前的代码基础上创建了一个 tools 子模块，并实现了以下六个核心工具。这些工具虽然简单，但对于 Agent 在计算机环境中行动至关重要。

1. Bash 工具 (run_bash)

• 功能：执行 Bash 命令并返回输出。
• 实现细节：使用 subprocess.run 执行命令，捕获标准输出（stdout）和标准错误（stderr）。
• 评价：这是最强大但也最危险的工具。它允许 Agent 在计算机上执行任何操作，无需为每个程序单独编写工具。但这也带来了安全风险，后续章节将讨论如何加强安全性。

2. 读取文件工具 (read_file)

• 功能：读取文件内容，支持指定偏移量（offset）和行数限制（limit）。
• 实现细节：检查文件是否存在，读取文本并按行分割，返回指定范围的行及其行号。
• 用途：适用于代码 Agent 读取整个代码库或特定文件内容。

3. 文件搜索工具 (glob_files)

• 功能：在目录中根据通配符模式查找文件。
• 实现细节：使用 glob 模块递归搜索，返回匹配文件的唯一排序列表。
• 用途：帮助 Agent 探索计算机文件系统，了解有哪些文件可用，为后续读取或编辑做准备。

4. 内容搜索工具 (grep)

• 功能：使用正则表达式搜索文件内容，返回匹配行及其文件路径和行号。
• 实现细节：结合 glob 和正则表达式 re 模块，可选地通过文件名模式过滤搜索范围。
• 用途：与 glob_files 互补。先通过 glob 确定文件范围，再通过 grep 搜索具体内容。支持限制搜索特定类型的文件（如排除二进制文件）。

5. 写入文件工具 (write_file)

• 功能：将内容写入文件，若文件不存在则创建，若父目录不存在则自动创建。
• 实现细节：使用 Path.mkdir 确保目录结构存在，然后写入文本。
• 用途：对于需要生成代码、保存结果或产生输出的 Agent 而言，这是必不可少的工具。

6. 编辑文件工具 (edit_file)

• 功能：在文件中替换第一次出现的字符串。
• 实现细节：读取原文件，查找目标字符串，替换后写回。若文件不存在或字符串未找到则返回错误。
• 用途：相比 write_file 覆盖整个文件，edit_file 更安全。它允许 Agent 对现有文件进行微调（如修补特定行），而无需重写整个文件，避免了意外覆盖未读取内容的风险。

7. 网页抓取工具 (webfetch)

• 功能：获取公开网页的纯文本内容（限制 2 MB）。
• 实现细节：
  • 仅支持 http 和 https 协议。
  • 使用 BeautifulSoup 剥离 HTML 标签，提取可读文本。
  • 清理多余换行符，保持上下文窗口整洁且高效。
• 用途：让 Agent 能够访问互联网获取实时信息，同时通过限制大小和协议类型来防止上下文窗口被填满或遭受恶意攻击。

工具 Schema 定义

实现工具后，必须让 Agent 知道这些工具的存在、功能描述及参数结构。通过定义工具 Schema（通常以 JSON 格式），模型可以理解每个工具的 name、description 和 parameters，从而在需要时正确地生成调用请求。

关键要点

• 工具的定义：工具是连接 LLM 与外部环境的桥梁，可以是简单的 Python 函数，也可以是复杂的 API 服务。
• 原生工具调用的优势：现代 LLM 支持原生 JSON 格式的工具调用，相比早期的文本解析方式，具有更高的可靠性和更少的幻觉。
• 核心工具集构成：
  • 执行类：run_bash（强大但高风险，需后续加强安全管控）。
  • 文件管理类：read_file（读取）、write_file（创建/覆盖）、edit_file（安全修改）、glob_files（查找文件）。
  • 内容检索类：grep（正则搜索内容）、webfetch（获取网络纯文本）。
• 安全性考量：run_bash 赋予 Agent 系统级权限，存在安全隐患；webfetch 通过限制协议和大小来防止资源滥用。
• 工具 Schema 的重要性：必须为每个工具定义清晰的描述和参数结构，以便 LLM 能够准确理解并生成合法的调用指令。

意义与影响

本文介绍的“工具”机制是 AI Agent 从“聊天机器人”进化为“智能助手”的关键一步。通过赋予 LLM 执行命令、读写文件和访问网络的能力，Agent 不再局限于静态的知识检索，而是能够主动在数字环境中采取行动，解决实际问题。

这种架构设计体现了 Agent 开发的核心范式：感知（LLM 理解意图）-> 行动（调用工具）-> 反馈（获取结果）。虽然当前实现的工具集较为基础，但它为构建更复杂的自动化工作流奠定了基础。后续章节预计将深入探讨如何通过这些工具链解决更复杂的任务，并重点解决由此带来的安全性和稳定性挑战。