Tool Calling：让 AI 调用工具

1. Tool Calling 是什么#

Tool Calling 指的是让 AI 在回答过程中调用外部工具。

这里的“工具”可以是：

• 一个普通函数
• 一个 HTTP API
• 一个数据库查询方法
• 一个文件读取方法
• 一个命令执行方法
• 一个业务系统接口
• 一个自动化脚本入口

模型负责判断“什么时候该用哪个工具”和“应该传什么参数”。程序负责真正执行工具，并把执行结果返回给模型。模型再根据工具结果继续生成回答或决定下一步动作。

一个典型流程如下：

1
用户提出任务
2
  ↓
3
AI 判断需要调用工具
4
  ↓
5
AI 生成工具名和参数
6
  ↓
7
程序执行工具
8
  ↓
9
程序把结果返回给 AI
10
  ↓
11
AI 基于结果输出最终回答

示例：

1
用户：帮我查一下北京今天的天气。
2

3
AI 选择工具：get_weather
4
AI 传入参数：{"city": "北京", "date": "today"}
5
程序执行查询
6
程序返回：{"temperature": "18-26°C", "condition": "晴"}
7
AI 回答：北京今天晴，气温 18-26°C。

Tool Calling 的核心价值，是让 AI 从“只会生成内容”升级为“可以连接外部能力并完成任务”。

2. 为什么需要 Tool Calling#

AI 模型有几个天然限制：

• 无法直接读取你的本地文件
• 无法直接查询你的数据库
• 无法直接调用你的内部接口
• 无法直接知道实时天气、库存、订单、部署状态
• 无法直接执行命令或修改系统

Tool Calling 可以把这些外部能力接进 AI 工作流。

它能带来几个直接收益：

• 获取实时数据
• 使用私有系统能力
• 执行业务动作
• 连接本地文件和命令行
• 让 AI 结果可以驱动自动化流程
• 把复杂任务拆成可执行步骤

从这一章开始，AI 就开始进入真实系统边界。工具设计越清楚，系统越稳定；权限控制越严谨，风险越可控。

3. Tool Calling 的基本组成#

一个工具通常包含四个部分：

• 工具名
• 工具描述
• 参数 schema
• 返回值设计

示例：

1
{
2
  "name": "get_weather",
3
  "description": "查询指定城市在指定日期的天气信息",
4
  "parameters": {
5
    "type": "object",
6
    "properties": {
7
      "city": {
8
        "type": "string",
9
        "description": "城市名称，例如：北京、上海、广州"
10
      },
11
      "date": {
12
        "type": "string",
13
        "description": "查询日期，例如：today、tomorrow、2026-05-28"
14
      }
15
    },
16
    "required": ["city", "date"]
17
  }
18
}

这个 schema 告诉模型三件事：

• 工具可以做什么
• 调用工具需要哪些参数
• 每个参数应该是什么类型和含义

模型看到用户问题后，会根据工具描述和参数规则生成调用参数。程序接到参数后，再执行真实函数。

4. function calling#

function calling 是 Tool Calling 最常见的形式。

它的基本思想是：把一个函数暴露给模型，让模型在需要时生成函数调用。

示例函数：

1
async function getWeather(city: string, date: string) {
2
  return {
3
    city,
4
    date,
5
    condition: "晴",
6
    temperature: "18-26°C"
7
  };
8
}

对应的工具定义：

1
{
2
  "name": "get_weather",
3
  "description": "查询天气信息",
4
  "parameters": {
5
    "type": "object",
6
    "properties": {
7
      "city": {
8
        "type": "string",
9
        "description": "城市名称"
10
      },
11
      "date": {
12
        "type": "string",
13
        "description": "日期"
14
      }
15
    },
16
    "required": ["city", "date"]
17
  }
18
}

用户提问：

1
帮我查一下上海明天的天气。

模型可能生成：

1
{
2
  "tool": "get_weather",
3
  "arguments": {
4
    "city": "上海",
5
    "date": "tomorrow"
6
  }
7
}

程序执行工具后，把结果返回给模型：

1
{
2
  "city": "上海",
3
  "date": "tomorrow",
4
  "condition": "多云",
5
  "temperature": "20-27°C"
6
}

最后模型基于工具结果回答用户。

5. tool schema 设计#

tool schema 是工具调用稳定性的关键。

一个好 schema 需要做到：

• 工具名清晰
• 工具描述具体
• 参数类型明确
• 必填字段明确
• 参数含义明确
• 枚举值尽量固定
• 输入边界可校验

1
get_weather
2
read_file
3
search_documents
4
query_database
5
create_ticket
6
send_notification
7
run_command

1
do_it
2
handle
3
process
4
tool1
5
api_call

1
读取工作区内指定路径的文本文件。只支持 .txt、.md、.json 文件，不支持读取工作区外的路径。

1
{
2
  "query": "查一下北京今天的天气"
3
}

1
{
2
  "city": "北京",
3
  "date": "today"
4
}

1
{
2
  "success": true,
3
  "data": {
4
    "city": "北京",
5
    "condition": "晴",
6
    "temperature": "18-26°C"
7
  },
8
  "error": null,
9
  "code": "OK",
10
  "metadata": {
11
    "source": "weather_api",
12
    "cached": false
13
  }
14
}

1
{
2
  "success": false,
3
  "data": null,
4
  "error": "city is required",
5
  "code": "VALIDATION_ERROR",
6
  "metadata": {}
7
}

6. 参数校验#

工具调用不能完全依赖模型自觉传对参数。程序必须做参数校验。

常见校验包括：

• 必填字段是否存在
• 字段类型是否正确
• 字符串长度是否合理
• 数字范围是否合理
• 日期格式是否正确
• 枚举值是否在允许范围内
• 文件路径是否在允许目录内
• SQL 查询是否只读
• 命令是否在白名单内

示例：

1
type ReadFileArgs = {
2
  path: string;
3
};
4

5
function validateReadFileArgs(args: ReadFileArgs) {
6
  if (!args.path) {
7
    throw new Error("path is required");
8
  }
9

10
  if (args.path.includes("..")) {
11
    throw new Error("path cannot include parent directory traversal");
12
  }
13

14
  if (!args.path.endsWith(".md") && !args.path.endsWith(".txt")) {
15
    throw new Error("only .md and .txt files are allowed");
16
  }
17
}

参数校验是工具安全的第一道门。

7. 工具调用失败处理#

工具调用可能失败。失败原因通常包括：

• 参数缺失
• 参数格式错误
• 外部 API 超时
• 数据库连接失败
• 文件不存在
• 权限不足
• 命令执行失败
• 第三方服务返回错误

失败处理建议：

• 给出明确错误码
• 保留原始错误日志
• 给模型返回简短可理解的错误信息
• 区分可重试和不可重试错误
• 对超时、限流、网络抖动设置重试策略
• 对危险操作失败禁止自动重试

示例返回：

1
{
2
  "success": false,
3
  "code": "FILE_NOT_FOUND",
4
  "error": "目标文件不存在，请确认路径是否正确。",
5
  "data": null
6
}

模型拿到这个结果后，可以继续向用户说明问题，也可以请求用户补充正确路径。

8. 多工具选择#

真实任务里经常会有多个工具。

例如：

• read_file：读取文件
• search_files：搜索文件
• query_database：查询数据库
• call_api：调用接口
• run_command：执行命令

用户提出任务：

1
帮我看一下项目启动失败的原因。

模型可能需要按顺序使用多个工具：

1. 调用 read_file 查看 package.json
2. 调用 run_command 执行启动命令
3. 调用 read_file 查看报错涉及的配置文件
4. 调用 search_files 搜索错误关键词
5. 汇总原因和修复建议

多工具选择要注意：

• 每个工具职责单一
• 工具描述互相区分
• 相似工具要写清使用场景
• 高风险工具要加确认机制
• 工具结果要能支撑下一步判断

如果两个工具描述太接近，模型容易选错。可以通过补充描述来降低混淆。

9. 人工确认机制#

Tool Calling 一旦连接真实系统，就可能产生实际影响。涉及修改、删除、付款、发布、重启、发消息等动作时，需要加入人工确认。

适合人工确认的场景包括：

• 删除文件
• 修改数据库
• 执行部署
• 重启服务
• 发送邮件或通知
• 创建订单
• 发起付款
• 修改权限
• 运行高风险命令

确认前应该展示：

• 将要调用的工具
• 将要传入的参数
• 影响范围
• 风险点
• 可回滚方式

示例：

1
即将执行工具：delete_file
2
目标路径：docs/old-plan.md
3
影响范围：删除该文件
4
风险提示：删除后需要从 Git 历史或备份恢复
5

6
请确认是否继续。

人工确认机制可以防止模型误操作，也能让用户理解即将发生的动作。

10. 危险操作拦截#

有些工具能力风险很高，必须在程序层做拦截。

高风险操作包括：

• 删除文件或目录
• 批量修改数据
• 执行 shell 命令
• 访问敏感路径
• 查询敏感数据
• 调用付款接口
• 修改生产环境配置
• 上传密钥或 token

常见拦截方式：

• 路径限制
• 命令白名单
• 参数黑名单
• 只读模式
• 沙箱执行
• 二次确认
• 权限分级
• 审计日志

命令执行工具尤其需要谨慎。

示例策略：

1
run_command 工具规则：
2
1. 默认只允许执行 npm test、npm run lint、npm run build。
3
2. 禁止执行 rm、del、format、shutdown、curl 上传敏感文件等命令。
4
3. 禁止访问工作区外路径。
5
4. 需要修改文件或删除文件时，必须先展示计划并等待确认。
6
5. 每次执行记录命令、参数、时间、调用用户和结果。

安全边界要写在程序里，不能只写在 Prompt 里。

11. 常见工具示例#

1
{
2
  "name": "get_weather",
3
  "description": "查询指定城市的天气信息",
4
  "parameters": {
5
    "type": "object",
6
    "properties": {
7
      "city": {
8
        "type": "string",
9
        "description": "城市名称"
10
      },
11
      "date": {
12
        "type": "string",
13
        "description": "日期，支持 today、tomorrow 或 YYYY-MM-DD"
14
      }
15
    },
16
    "required": ["city"]
17
  }
18
}

1
{
2
  "name": "read_file",
3
  "description": "读取工作区内指定路径的文本文件",
4
  "parameters": {
5
    "type": "object",
6
    "properties": {
7
      "path": {
8
        "type": "string",
9
        "description": "相对工作区的文件路径"
10
      }
11
    },
12
    "required": ["path"]
13
  }
14
}

1
{
2
  "name": "query_database",
3
  "description": "执行只读数据库查询，用于获取业务数据",
4
  "parameters": {
5
    "type": "object",
6
    "properties": {
7
      "sql": {
8
        "type": "string",
9
        "description": "只允许 SELECT 查询"
10
      }
11
    },
12
    "required": ["sql"]
13
  }
14
}

1
{
2
  "name": "get_order_by_id",
3
  "description": "根据订单 ID 查询订单概要",
4
  "parameters": {
5
    "type": "object",
6
    "properties": {
7
      "order_id": {
8
        "type": "string",
9
        "description": "订单 ID"
10
      }
11
    },
12
    "required": ["order_id"]
13
  }
14
}

1
{
2
  "name": "run_command",
3
  "description": "在工作区内执行允许列表中的命令",
4
  "parameters": {
5
    "type": "object",
6
    "properties": {
7
      "command": {
8
        "type": "string",
9
        "description": "要执行的命令"
10
      },
11
      "cwd": {
12
        "type": "string",
13
        "description": "执行目录，必须在工作区内"
14
      }
15
    },
16
    "required": ["command"]
17
  }
18
}

12. Tool Calling Prompt 写法#

设计工具后，还需要写清楚模型如何使用工具。

示例 Prompt：

1
你是一个项目排障助手。
2

3
你可以使用以下工具：
4
1. read_file：读取工作区内的文本文件。
5
2. search_files：搜索工作区内的文件名或文本内容。
6
3. run_command：执行允许列表中的命令。
7

8
规则：
9
1. 如果问题需要真实文件内容，请先读取文件。
10
2. 如果不知道文件位置，请先搜索。
11
3. 如果需要验证构建或测试结果，可以执行命令。
12
4. 涉及删除、覆盖、发布、上传、修改数据库等动作时，必须先请求用户确认。
13
5. 工具返回失败时，先解释失败原因，再决定是否需要用户补充信息。
14

15
任务：
16
请帮我分析项目启动失败的原因。

这个 Prompt 明确了工具清单、使用规则和风险边界。

13. Tool Calling 和 Structured Output 的关系#

Tool Calling 经常依赖 Structured Output。

原因很简单：模型调用工具时，需要输出结构化参数。

例如：

1
{
2
  "tool": "read_file",
3
  "arguments": {
4
    "path": "package.json"
5
  }
6
}

如果参数格式不稳定，程序就无法可靠执行工具。所以第二章学到的 JSON、schema、字段校验，在第三章会继续使用。

可以这样理解两者关系：

• Structured Output 让 AI 输出稳定数据
• Tool Calling 让稳定数据驱动外部工具

先把结构化输出练扎实，再学习工具调用，会更容易理解工程实现。

14. 常见问题#

1
工具：handle_task
2
描述：处理任务

1
工具：search_documents
2
描述：在项目文档库中搜索与用户问题相关的 Markdown 文档，返回标题、路径和摘要。

1
{
2
  "input": "帮我查一下订单 123 的状态"
3
}

1
{
2
  "order_id": "123"
3
}

1
允许 AI 执行任意 shell 命令。

1
只允许 AI 执行白名单命令，例如 npm test、npm run lint、npm run build。其他命令需要人工确认。

1
{
2
  "message": "文件不存在"
3
}

1
{
2
  "success": false,
3
  "code": "FILE_NOT_FOUND",
4
  "error": "文件不存在",
5
  "data": null
6
}

15. Tool Calling 练习清单#

可以按下面顺序练习：

1. 写一个天气查询工具
2. 写一个文件读取工具
3. 写一个文档搜索工具
4. 写一个数据库只读查询工具
5. 写一个命令执行工具，并加入白名单
6. 给工具返回值增加 success、data、error、code
7. 给参数增加 schema 校验
8. 给危险操作增加人工确认
9. 让 AI 根据任务自动选择工具
10. 记录每一次工具调用日志

每个练习都可以检查三个问题：

• 模型是否选对工具
• 参数是否符合 schema
• 工具失败时是否能给出清楚反馈

16. 阶段验收标准#

学完这一章，可以用下面的问题检查自己：

• 我能不能把一个函数封装成 AI 工具？
• 我能不能写出清楚的工具描述？
• 我能不能设计可校验的工具参数？
• 我能不能设计统一的工具返回值？
• 我能不能处理工具调用失败？
• 我能不能让 AI 在多个工具中选择合适工具？
• 我能不能给危险操作加确认和拦截？
• 我能不能记录工具调用日志？

如果这些问题大多数都能做到，说明 Tool Calling 阶段已经基本合格。

17. 本章总结#

Tool Calling 的核心是把外部能力封装成模型可以理解、程序可以执行、风险可以控制的工具。

一套可用的 Tool Calling 设计，建议至少包含：

• 清晰的工具名
• 明确的工具描述
• 可校验的参数 schema
• 统一的返回值结构
• 完整的失败处理
• 多工具选择规则
• 人工确认机制
• 危险操作拦截
• 审计日志

Tool Calling 是 AI 工程化路线中的关键一步。它让 AI 可以连接函数、API、文件系统、数据库和命令行，从生成内容走向执行任务。

这一章的目标很明确：让 AI 能调用工具，同时让每一次调用都可理解、可校验、可追踪、可控制。