大模型应用开发 / 系统课时
自定义工具开发
自定义工具开发
本课完成一个可验证的自定义工具:先定义清晰的输入契约,再实现业务逻辑并进行独立测试,最后整理成可注册给 Agent 的工具列表。完成后,你能判断问题究竟出在工具函数、参数结构,还是 Agent 的选择过程。
学习目标
- 使用
@tool和 Pydantic 模型定义工具名称、说明与参数约束 - 在接入 Agent 前独立调用工具并核对返回结果
- 识别工具设计中的异常、权限与副作用边界
工具本质是可被模型理解的函数契约
普通 Python 函数只对开发者可读;工具还要把名称、用途、参数结构和返回值交给模型。模型主要依据工具说明判断“何时调用”,依据参数 Schema 生成“如何调用”,因此描述含糊或字段语义重叠会直接降低调用成功率。

工具应当“职责单一、参数可判定、输出可解释”。不要让一个工具同时承担查询、修改和通知三种动作,也不要把整段自然语言塞进一个万能参数。
编写并独立验证工具
下面实现运费计算工具。Pydantic 负责限制重量范围和地区取值,工具函数只处理确定性的业务计算。示例不依赖模型,可直接运行,适合先做单元级验证。
python
from typing import Literal
from langchain.tools import tool
from pydantic import BaseModel, Field
class ShippingInput(BaseModel):
weight_kg: float = Field(gt=0, le=100, description="包裹重量,单位为千克")
region: Literal["MY", "SG", "HK"] = Field(description="目的地区代码")
@tool("calculate_shipping", args_schema=ShippingInput)
def calculate_shipping(weight_kg: float, region: str) -> str:
"""计算指定地区包裹的标准运费,不处理保险和加急费用。"""
base_fee = {"MY": 8.0, "SG": 18.0, "HK": 22.0}[region]
extra_fee = max(weight_kg - 1, 0) * 3.5
return f"{base_fee + extra_fee:.2f} MYR"
def main() -> None:
result = calculate_shipping.invoke({"weight_kg": 2.5, "region": "MY"})
tools = [calculate_shipping]
print(calculate_shipping.name)
print(sorted(calculate_shipping.args))
print(result)
print([item.name for item in tools])
if __name__ == "__main__":
main()预期输出:
text
calculate_shipping
['region', 'weight_kg']
13.25 MYR
['calculate_shipping']运行成功说明函数、Schema 和工具包装均可用。注册给 Agent 时,把同一个对象放入 tools 参数即可,例如 create_agent(model=..., tools=[calculate_shipping]);不要重新传入未装饰的原始函数。
处理边界与失败方式
参数校验错误应尽量在 Schema 层暴露,例如重量小于等于零、地区代码不受支持。外部接口超时、数据库异常等运行期问题,则应记录工具名、关键参数和可重试性,再返回对 Agent 有意义的错误,而不是吞掉异常并伪造成功结果。
有写入副作用的工具需要额外保护:为订单号、请求号等业务键设计幂等机制;对删除、付款、发信等高风险动作增加权限校验或人工确认;日志中不得输出密钥、完整身份证号和支付凭证。
按自己的节奏,确认真正理解。