2.5 工具 Tools 与能力扩展

2.5 工具（Tools）与能力扩展

本节摘要：工具是智能体的"手脚"——没有工具，智能体只会说；有了工具，智能体才能做。本节讲清工具的创建方式（函数工具、类工具）、工具集管理、错误处理与动态工具，让你能把任何业务能力"挂"到智能体上。

本节导读

阅读完本节，你应当能够：

1. 用装饰器创建函数工具
2. 创建带状态/依赖的工具
3. 管理工具集与错误
4. 使用动态工具
5. 设计合理的工具边界

一、问题与直觉

"让智能体查订单、发邮件、算数据"——这些能力都不是模型自带的，靠工具挂载。工具的价值在于：把模型"会说"变成"会做"。SDK 里创建工具极简——一个装饰器，普通函数秒变智能体可调用的工具。

工具设计是整个智能体工程里最容易被低估的一环。很多项目前期只挂了几个简单函数，后期工具一多，模型开始"选错工具"、"参数传错"，问题一个接一个。根因往往是工具说明书不清晰、职责不单一。所以本节除了讲"怎么创建"，更重点讲"怎么设计"。

二、核心原理

工具是智能体的能力扩展：

2.1 工具创建的两类方式

函数工具适合"无状态、一次调用"的能力（查天气、算数、查订单）；类工具适合"带状态、需要初始化依赖"的能力（连数据库的客户端、带缓存的服务）。

2.2 工具与模型的"说明书"

模型不"执行"工具，它"决定"要不要调——依据是函数的签名与 docstring。所以工具的"说明书"（签名 + 说明）质量，直接决定模型调用是否准确。

三、工程实践要点

3.1 函数工具示例

from agents import function_tool

@function_tool
def get_order_status(order_id: str) -> str:
    """查询订单状态。

    参数 order_id 是订单号字符串，例如 10086。
    返回订单状态文本，如"已发货""配送中""已签收"。
    """
    return order_service.query(order_id)
​

docstring 里写清楚"参数是什么、返回什么、什么情况下会失败"，模型才知道什么时候调、怎么传参、怎么解读结果。

💡 关键直觉：docstring 是写给模型看的，不是写给人看的——把参数含义、返回格式写清楚，模型才能正确调用。说明书越清楚，调用越准。

3.2 工具集管理

3.3 工具错误处理

@function_tool
def query_api(url: str) -> str:
    """查询外部 API，返回响应文本。"""
    try:
        return http_get(url)
    except Exception as e:
        return f"查询失败: {e}"   # 把错误返回给模型，而不是抛异常
​

⚠️ 常见坑：工具抛异常不捕获。工具异常会中断整个运行——把错误转成文本返回给模型，让模型决定"重试还是说明失败"，流程更健壮。

3.4 动态工具

# 概念：运行时按场景武装工具
base_tools = [查询库存, 查询价格]
vip_tools = base_tools + [查询会员积分, 申请优惠券]

vip_agent = Agent(name="VIP客服", instructions="...", tools=vip_tools)
regular_agent = Agent(name="普通客服", instructions="...", tools=base_tools)
​

与其在运行时反复增删同一个 Agent 的工具，不如按场景预定义几套工具集，再创建对应的 Agent 实例——更清晰、也更好排查。

3.5 工具边界设计

工具职责：一件事一个工具，不要一个工具干三件事
工具权限：能只读就不给写，能查自己就不给查全库
工具数量：够用就好，模型上下文不是无限的
​

3.6 工具的测试与调试

工具是智能体系统里"确定性"最高的部分，值得单独测试。三个层面：单元测试——直接调用函数，验证参数与返回值，不经过模型；集成测试——把工具挂到 Agent 上，用真实对话验证"模型能否正确选择并调用"；异常测试——模拟工具返回失败，验证模型能否如实说明。调试工具问题时，先用一个临时 Agent 只挂这个工具，排除其他工具的干扰；再看模型输出的工具调用参数是否合理。把工具当成普通函数测试，出错概率能降一大半。

要点速记

• 要点一：两类工具——函数（简单）、类（复杂）
• 要点二：docstring 是给模型的说明书
• 要点三：工具按需挂载，防选错
• 要点四：工具错误转文本返回，不抛异常
• 要点五：动态工具按场景武装
• 要点六：工具让智能体"会做"而不是"只会说"

核心组件全部讲完，第 3 章升级——追踪、协作、守护等高级特性。