大模型应用开发 / 知识点

LangChain 开发速查手册

手册条目

CODE
定义自定义工具

将 Python 函数封装为可由模型调用的工具。

定义自定义工具

当模型需要查询业务数据、调用内部服务或执行受控动作时,用 @tool 把普通 Python 函数转换为 LangChain 工具。转换后可直接用 invoke() 测试,也可交给模型或 Agent 决定何时调用。

基本语法

函数名默认成为工具名,文档字符串成为工具说明,类型注解生成输入结构。说明应明确“什么时候调用”和“返回什么”,不要只写“查询数据”。

python
from langchain.tools import tool

ORDER_STATUS = {
    "ORD-1001": "PAID",
    "ORD-1002": "REFUNDED",
}

@tool
def get_order_status(order_id: str) -> str:
    """查询指定订单的状态;仅在用户提供明确订单号时调用。"""
    # 生产环境可在此调用数据库或订单服务,但应设置超时。
    status = ORDER_STATUS.get(order_id)
    if status is None:
        return f"订单 {order_id} 不存在"
    return f"订单 {order_id} 状态:{status}"

if __name__ == "__main__":
    print(get_order_status.name)
    print(get_order_status.invoke({"order_id": "ORD-1001"}))

预期输出

text
get_order_status
订单 ORD-1001 状态:PAID

invoke() 接收与工具输入结构一致的字典,适合在接入模型前验证参数校验、返回值和异常行为。

高频用法

  • 查询型工具:读取订单、库存、配置或知识库,优先返回简短字符串或字段明确的字典。
  • 动作型工具:发送通知、创建工单、执行退款等,必须在函数内部再次校验权限和业务状态。
  • 自定义名称:使用 @tool("order_status_lookup") 覆盖默认名称;名称优先使用 snake_case,避免空格和特殊字符。

风险与边界

模型生成的参数不能视为可信输入。若工具直接执行退款、删除或发信,参数错误可能造成不可逆操作;安全做法是增加权限校验、幂等键、金额或数量上限,并对高风险动作加入人工确认。

外部 API、数据库或文件操作可能超时或抛出异常,未处理时会中断工具调用链。生产环境应设置连接与读取超时,记录工具名、调用 ID 和脱敏参数,并把可恢复错误转换为清晰结果或交给 Agent 中间件重试。

不要让工具执行任意 eval、Shell 字符串或模型生成的 SQL。需要动态能力时使用白名单命令、参数化查询和受限执行账户。

排障清单

  • 模型不调用工具:检查工具说明是否写清触发条件,并确认工具已传入 bind_tools() 或 Agent 的 tools。
  • 参数校验失败:检查函数类型注解、必填参数名以及调用字典的键是否一致。
  • 工具已执行但回答错误:单独运行 tool.invoke(),确认返回值不是空值、异常文本或未经序列化的对象。
  • 重复执行副作用:为业务请求增加幂等键,不要依赖模型避免重复调用。

速查:先把函数做成可独立测试、可超时、可审计的业务接口,再交给模型调用。

目录与阅读设置

记录一个想法

LangChain 开发速查手册

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通