AI Agent 实战教程 03：Tool Calling 入门
Tool Calling 是 AI Agent 从“会回答”走向“会执行”的关键能力。没有工具调用，模型只能生成文本；有了工具调用，模型才能访问外部系统，完成搜索、查询、写入、计算、文件处理、任务创建等真实动作。
很多 Agent 项目的第一步，都是把业务能力封装成工具。工具设计得越清晰，Agent 越稳定；工具设计得越模糊，模型越容易误用。
Tool Calling 的基本过程
Tool Calling 通常包含四个角色：用户、模型、工具描述和工具执行器。
用户提出目标，例如“帮我查一下某个标签是否存在”。模型根据上下文判断需要调用查询工具。工具描述告诉模型这个工具叫什么、能做什么、需要哪些参数。模型生成结构化参数后，系统执行工具，并把结果返回给模型。
模型本身不会真的访问数据库或执行命令。它只是生成一个“调用意图”。真正执行的是宿主系统。因此，Tool Calling 是模型推理能力和外部系统能力之间的桥梁。
工具 schema 为什么重要
工具 schema 是模型理解工具的主要依据。一个好的 schema 应该包含：
- 工具名称；
- 工具用途；
- 参数名称；
- 参数类型；
- 必填字段；
- 返回值结构；
- 使用限制；
- 风险说明。
比如一个创建任务工具，不应该只写“创建任务”。它应该说明 summary 是任务标题，due 是截止时间，assignee 是负责人 ID，返回值包含 taskId 和 url。
如果 schema 太模糊，模型可能传错参数、漏掉必填字段，或者在不该调用时调用。
工具应该尽量原子化
工具设计有一个重要原则：单个工具最好只做一类明确事情。
例如不要设计一个巨大的工具叫 「manage_task」，里面既能创建任务、删除任务、查询任务、修改负责人、上传附件。这样的工具对模型来说难以选择，对系统来说也难以做权限控制。
更好的方式是拆成：
- 「create_task」
- 「list_tasks」
- 「update_task」
- 「complete_task」
- 「delete_task」
这样每个工具的风险等级更清晰，也方便分别加确认机制。
读工具与写工具
Tool Calling 最大的风险来自写操作。读取数据通常风险较低，例如查询标签、获取文章、查看日程。但写操作可能改变系统状态，例如创建文章、删除数据、发送消息、修改配置。
因此工具可以按风险分层：
- 低风险：查询、读取、搜索；
- 中风险：创建草稿、上传文件、更新非关键字段；
- 高风险：删除、发布、发消息、部署、支付、修改权限。
低风险工具可以自动执行，高风险工具必须让用户确认。这个规则不应该只依赖模型判断，而应该由系统强制执行。
参数生成与校验
模型生成的参数不能直接信任。系统需要校验参数是否合法。例如：
- ID 是否是数字；
- URL 是否是合法在线资源；
- 文件路径是否存在；
- 日期格式是否正确；
- 枚举值是否在允许范围；
- 用户是否有权限操作目标资源。
工具执行器应该在调用真实系统前做校验，并返回结构化错误。这样模型才能根据错误修正下一步。
工具返回值设计
工具返回值也很重要。返回值应该尽量结构化，而不是只返回一段自然语言。
例如创建任务后，返回：
- taskId；
- title；
- url；
- status；
- createdAt。
这样 Agent 可以继续引用结果。用户说“把刚才那个任务标记完成”时，系统可以根据 taskId 执行，而不是重新猜测。
常见问题
第一个问题是工具太多。工具越多，模型选择错误的概率越高。可以通过工具分组、路由、按场景加载来降低复杂度。
第二个问题是工具描述不准确。模型会按描述使用工具，如果描述和真实行为不一致，就会产生错误调用。
第三个问题是缺少确认机制。很多演示系统可以自动删文件、自动发消息，但生产系统绝不能这样设计。
第四个问题是工具返回不可解析。返回一大段日志给模型，远不如返回结构化 JSON。
小结
Tool Calling 是 Agent 工程的核心能力。它让模型连接真实系统，但可靠性来自清晰 schema、原子工具、参数校验、结构化返回和权限控制。工具不是越多越好，而是越清晰、越可控越好。