自定义工具使用

时长：约 36 分钟（2160 秒）

本节要点

工具（插件）是智能体与现实世界交互的关键接口，核心价值是突破 LLM「只能生成文本」的局限。
工具的完整生命周期：定义与注册 → 发现与调用 → 结果返回与异常处理 → 工具下线管理。
工具描述规范（Function Schema）：名称、描述、参数，以及 required、default 等约束。
三大开发原则：单一职责、清晰的描述、错误处理与反馈。
工具注册与发现机制：统一注册中心与动态加载。
两个实操：用 Python + Schema 开发计算器工具，以及对接 OpenWeatherMap 开发天气查询工具。

一、工具的生命周期

一个工具从诞生到下线，要经历四个阶段：

定义与注册：开发者编写功能函数，并定义 JSON Schema 描述（含名称、参数、约束），随后把工具注册到智能体注册表，让智能体感知可用的工具资源；
发现与调用：LLM 根据用户请求和当前状态，基于工具描述从注册表中发现适配工具，确定目标后生成包含「名称 + 参数」的调用指令，由编排引擎解析并执行实际函数；
结果返回与异常处理：工具执行完毕向编排引擎返回结构化结果（如 JSON）供 LLM 处理；若调用失败，要返回标准化错误信息，避免工作流崩溃；
工具下线管理：当工具功能过时或不再被业务需要时，从注册表移除该工具及其 Schema，完成全生命周期闭环。

二、工具描述规范（Function Schema）

Function Schema 是描述工具功能与接口的核心 JSON 对象，也是 LLM 理解工具、生成正确调用参数的唯一依据。以 get_weather 为例，它包含名称、功能描述、参数定义等关键信息——定义越精准，模型调用成功率越高。

参数体系支持常见的 JSON 标准数据类型：字符串 string、数字 number/integer、布尔值 boolean、数组 array 和对象 object，能灵活适配各类工具的输入需求。

规则约束有两类关键机制：

required 数组：明确调用工具时必须传入的关键参数，保障执行有效性；
default 关键字：为非必填参数设置默认值，用户未指定时自动填充，提升容错率。

在实际平台里，这部分常以 OpenAPI / Swagger 规范的形式填写。课程在 Dify 里以「高德步行路线规划 API」为例，编写了包含 openapi: 3.0.0、info.title、servers、paths、parameters（key、origin、destination）与 responses 的完整 Schema，并测试返回了包含左转/右转指令、距离、时长、路线坐标的步行导航结果。

三、开发原则（一）：单一职责

一个工具应当只专注完成一件核心任务并把它做到极致，拒绝功能堆砌。这是软件工程里单一职责原则（SRP）在 LLM 工具开发中的落地。

四大优势：高内聚让功能边界清晰易懂；可复用性使其适配多个工作流场景；功能单一降低了测试用例复杂度；更重要的是，简洁的功能描述能大幅提升 LLM 对「何时调用」的判断准确率。

正反案例：

反面：编写 do_everything 万能工具，把查天气、查股票等混在一起，导致描述模糊，LLM 难以精准触发，维护成本极高；
正面：拆分为 get_weather、get_stock_price 等独立工具，功能明确、语义清晰，既便于 LLM 理解调用，也利于后续迭代与测试。

四、开发原则（二）：清晰的描述

描述是 LLM 调用工具的「唯一说明书」——LLM 无法直接理解代码逻辑，完全依赖描述文本判断是否调用工具。模糊的描述会让工具被「雪藏」，精准的描述能最大化工具利用率。

优质描述的四要素：

核心功能 + 适用场景：明确工具「做什么」和「何时用」，给出具体业务案例；
边界说明 + 参数释义：界定「何时不用」避免误调用，同时详细解释参数的含义、格式与取值范围。

正反案例：反面是仅标注 search 和参数 q 的「黑盒」描述，无场景说明也无参数解释，LLM 无法判断是搜网页、航班还是文档；正面是 search_flight，明确适用「机票预订/动态查询」场景，参数细化为出发地、目的地、日期并附格式示例。

五、开发原则（三）：错误处理与反馈

核心原则：拒绝未捕获异常，返回可解析反馈。工具执行失败时，绝不抛出未处理的异常导致工作流崩溃，而要返回标准化的错误信息。

规范要求：无论成功还是失败，工具返回结果都遵循统一 JSON 结构——

{
  "status": "success | error",
  "data": { },
  "error": { "type": "...", "description": "...", "suggestion": "..." }
}

成功时 status = success 并携带 data 数据体；失败时 status = error 并补充 error 对象，明确错误类型、具体描述与修复建议。

价值意义：结构化的错误信息让 LLM 能精准识别问题根源，据此自动尝试参数修正、逻辑调整，或向用户清晰反馈问题，从而提升智能体的鲁棒性。

六、工具注册与发现机制

工具如何被智能体「看到」和「用上」？课程讲了两种机制：

统一注册中心（Centralized Registry）：把所有可用工具集中在一处注册与管理。开发者先将工具 Schema 与实现函数注册至中心；智能体启动时加载所有工具 Schema；LLM 决策时依据这些已加载的 Schema 描述进行调用。优势是集中管控、降低维护成本，让智能体更高效地发现和使用工具。
动态加载（Dynamic Loading）：工具可在智能体运行过程中被动态添加或移除，无需重启应用。常见实现有插件系统（工具以独立模块存在、灵活加载）和热重载（监控工具定义文件变化，文件更新后自动加载）。优点是灵活性极高，适配功能频繁迭代的场景，便于持续集成和部署新工具。

七、实操：开发计算器工具与天气查询工具

7.1 计算器工具（LangChain 注册）

自定义工具实战的三步：

核心逻辑：编写 calculate 函数，接收数学表达式字符串，通过 eval 执行运算并捕获异常——表达式非法则返回错误信息，保证工具健壮；
接口定义：通过 JSON Schema 定义工具名称、功能描述与入参规范，明确 expression 为必填字符串参数，这是 LLM 与工具交互的「契约」；
框架集成：基于 LangChain 的 Tool 类封装函数与描述信息，生成 calculator_tool 对象完成注册。注册后 LLM 能根据用户问题意图自动触发计算。

7.2 天气查询工具（对接 OpenWeatherMap）

目标是对接第三方气象 API，实现城市天气信息的获取、解析与结构化输出，为智能体提供实时环境感知能力。

代码实现：用 Python requests 发起 HTTP GET 请求，用 try-except 捕获网络异常，解析返回的 JSON，提取天气描述 description 与摄氏温度 temp 核心字段，封装为统一 JSON 结果返回；
框架集成：编写包含 name、description、parameters 的 JSON Schema，与天气查询函数绑定后注册到智能体框架。

关键代码逻辑总结：参数化配置 API 请求（城市名、密钥、单位）实现灵活性；把非结构化的 API 响应转化为固定结构的 JSON，降低下游处理复杂度；完善的异常捕获保障工具在网络故障或接口变更时的鲁棒性。

小结

本课把「工具」从概念落到工程实践。工具的生命周期贯穿「定义注册 → 发现调用 → 结果与异常 → 下线」；Function Schema（名称 + 描述 + 参数 + required/default 约束）是 LLM 与工具交互的唯一契约；开发上要守住单一职责、清晰描述、错误处理三条原则；机制上靠「统一注册中心 + 动态加载」让工具可管理、可扩展。两个实操（计算器、天气查询）演示了「写函数 → 定 Schema → 注册框架」的标准范式。

自测题

工具的完整生命周期包含哪四个阶段？每个阶段做什么？
Function Schema 为什么被称为 LLM 与工具交互的「唯一契约」？required 和 default 分别解决什么问题？
为什么工具要遵循「单一职责」？请用 do_everything 与 get_weather/get_stock_price 的对比说明。
一条优质的工具描述应当包含哪四个要素？反面「黑盒」描述会导致什么问题？
工具执行失败时应该怎样返回结果？为什么结构化错误信息比抛异常更好？

答案提示：1. 定义与注册、发现与调用、结果返回与异常处理、下线管理。2. LLM 只能依据 Schema 描述判断工具用途与参数；required 校验必填参数，default 给非必填参数兜底。3. 高内聚、可复用、易测试、描述精准；万能工具描述模糊、LLM 难触发、难维护。4. 核心功能 + 适用场景 + 边界说明 + 参数释义；描述模糊会导致工具被雪藏、调用成功率低。5. 返回统一 JSON（status/data/error）；结构化错误让 LLM 能识别根源并修正，避免工作流崩溃。