LangChain 之 Tool 工具

简介: 本文详解Agent工具设计核心:工具是Agent影响现实的唯一出口。强调工具契约三要素(name/description/args_schema)即API文档,须面向模型编写;推荐Pydantic定义强约束参数;严守四条硬规——描述写“何时用”、返回值结构化、一工具一事、身份信息走runtime不入schema;并提供容错、并发、token优化等工程实践。

一、工具:Agent 唯一能改变世界的出口

上一篇把提示词比作 Agent 的"岗位说明书"。但说明书再详细,如果这个人没有手脚,也只能停在纸面上。模型本身只会输出 token——它不能查库、不能发邮件、不能退款。工具(Tool)是 Agent 唯一能产生外部副作用的出口。

也正因如此,工具的质量直接决定 Agent 的上限。模型对工具的全部认知,只来自三样东西:

  • name:工具叫什么,比如 query_order、refund_order;
  • description:什么场景该用它;
  • args_schema:参数怎么填、每项什么含义。

这三样会被序列化进请求,成为模型看到的"工具清单"。所以写工具不是写一个函数,是写一份给模型看的 API 文档——调用方是一个不懂你业务、但会一字一句读文档的实习生。

对 Java 工程师,这个心智模型很好对齐:写 @RestController 时,方法是给另一个系统调的;写工具时,方法是给模型调的。区别在于——同事会看你的 Swagger 并追问,模型只会看你那两三行描述,填错了也不问,直接编一个。

下面这张图是一次工具调用的完整链路,值得先看一眼再读代码:

在这里插入图片描述

模型只负责两件事:选工具、填参数。校验、注入、执行、回填,全部在框架侧完成。理解这条链路的每个环节,后面的设计规矩才有落脚点。

二、三种定义方式,一条主线

LangChain 提供三种定义工具的方式,能力从简到繁,但主线只有一条:把契约写清楚。

2.1 @tool 装饰器:最小可用

import json
from langchain.agents import create_agent
from langchain.tools import tool
from init_llm import deepseek_llm

EMPLOYEES = {
   
    "E001": {
   "name": "张三", "department": "技术部", "position": "高级软件工程师"},
    "E002": {
   "name": "李四", "department": "市场部", "position": "市场经理"},
}

@tool("get_employee_info")
def get_employee_info(employee_id: str) -> str:
    """根据员工 ID 查询员工档案。

    Args:
        employee_id: 员工唯一标识,格式为 E + 3 位数字,例如 E001
    """
    record = EMPLOYEES.get(employee_id.upper())
    if record is None:
        return f"未找到 ID 为 {employee_id} 的员工,请确认编号格式(例如 E001)"
    return json.dumps(record, ensure_ascii=False)

agent = create_agent(
    model=deepseek_llm,
    tools=[get_employee_info],
    system_prompt="你是员工信息助手,只能依据工具返回的数据回答。",
)

resp = agent.invoke({
   "messages": [{
   "role": "user", "content": "查一下 E001 的档案"}]})
print(resp["messages"][-1].content)

四个容易踩的细节:

  1. 类型注解是必需的,它决定参数 schema,不写注解就等于没告诉模型怎么填;
  2. @tool("get_employee_info") 可显式命名,默认取函数名。名字请用 snake_case,含空格或特殊字符在部分厂商会直接报错;
  3. 传 description= 后,它会完全替代 docstring 成为唯一描述,两者不要都写又指望叠加;
  4. 参数名 config 和 runtime 是保留字,用它们当业务参数会在运行时抛错。

2.2 Pydantic:参数有约束时

参数一复杂——枚举、范围、格式规范——裸类型注解就不够用了。Pydantic 模型能把这层约束写进 schema:

from typing import Literal, Optional
from pydantic import BaseModel, Field, field_validator
from langchain.tools import tool

class TicketQueryInput(BaseModel):
    """工单查询条件,至少提供一个筛选字段。"""

    ticket_id: Optional[str] = Field(default=None, description="工单号,例如 TK2025012001")
    assigner: Optional[str] = Field(default=None, description="负责人姓名")
    status: Optional[Literal["open", "in_progress", "resolved", "closed"]] = Field(
        default=None, description="工单状态"
    )
    priority: Optional[Literal["low", "medium", "high", "urgent"]] = Field(
        default=None, description="优先级"
    )

    @field_validator("ticket_id")
    def upper_ticket_id(cls, v: Optional[str]) -> Optional[str]:
        return v.upper() if v else None


@tool(args_schema=TicketQueryInput)
def query_tickets(ticket_id=None, assigner=None, status=None, priority=None) -> str:
    """按条件查询工单,支持工单号 / 负责人 / 状态 / 优先级组合筛选。"""
    rows = [t for t in TICKETS
            if (not ticket_id or t["id"] == ticket_id)
            and (not assigner or t["assigner"] == assigner)
            and (not status or t["status"] == status)
            and (not priority or t["priority"] == priority)]
    if not rows:
        return "未找到符合条件的工单,可放宽筛选条件后重试"
    return json.dumps({
   "total": len(rows), "tickets": rows}, ensure_ascii=False, indent=2)

相比裸注解,这里多了三层保护:

  • Literal 把取值范围写死在 schema 里,模型看到的是四个合法值,而不是"一个字符串"——这是降低参数幻觉最划算的手段;
  • Field(description=...) 直接影响填参准确率,每个字段都要写,别省;
  • field_validator 做入口规范化,用户说"查 tk2025012001",模型照抄小写,validator 统一转大写,工具不必到处 .upper()。

关键在于:校验发生在模型填完参数、工具执行之前。校验失败时,错误信息会带着合法取值回到模型手里,模型据此自己改参数重试——这条回路本文第五节还会再遇到一次。

2.3 JSON Schema:Schema 来自配置

当参数结构不是写代码时定死的,而是来自配置中心、外部系统或运行时拼装,直接给字典更合适:

BOOK_SCHEMA = {
   
    "type": "object",
    "properties": {
   
        "title_keyword": {
   "type": "string", "description": "书名关键词,支持模糊匹配"},
        "author": {
   "type": "string", "description": "作者姓名"},
        "category": {
   
            "type": "string",
            "enum": ["技术", "文学", "历史", "科学", "经济学", "传记"],
            "description": "图书分类",
        },
    },
    "required": [],
}

@tool(args_schema=BOOK_SCHEMA)
def query_books(title_keyword: str = None, author: str = None, category: str = None) -> str:
    """查询企业图书库。至少提供关键词 / 作者 / 分类中的一个条件。"""
    ...

required: [] 表示字段都可选,但这恰恰是风险点:模型可能一个都不填。所以描述里必须补一句"至少提供一个条件",并在函数体里对空条件做兜底——schema 只能约束结构,约束不了语义。

2.4 怎么选

方式 适用场景 代价
@tool + 类型注解 参数简单、快速验证、内部小工具 无法表达枚举与自定义校验
@tool(args_schema=PydanticModel) 参数复杂、有枚举/范围/格式约束的企业级工具 多写一个模型类
@tool(args_schema=dict) Schema 由配置或外部系统动态提供 无静态类型检查,易写错

一句话选型:能用 Pydantic 就用 Pydantic。多写的十几行模型类,会在模型填错参数时以"自我修正"的形式还给你。

三、四条硬规矩

API 能跑通只是及格线。工具要稳,还得守四条规矩——这部分没有框架 API,全是设计经验。

规矩一:描述写"何时用",而不是"是什么"。

反面写法是 """查询订单。"""。正面写法要把触发场景和边界都写进去:

按订单号查询订单的物流与金额信息。用户问到"包裹到哪了""这单多少钱"时使用;不要用于退款(请用 refund_order)。

模型选工具靠的是语义匹配。告诉它什么情况"不要用",比告诉它功能是什么更能降低误调用——尤其是在你有 query_order 和 query_refund 两个相近工具的时候。

规矩二:返回值是写给模型读的,不是给程序解析的。

  • 返回带字段名的 JSON 字符串,别返回元组、ORM 对象 repr 或一坨纯文本日志;
  • 空结果要明确:返回"未找到符合条件的工单",而不是 None 或 []——模型看到空数组容易理解成"工具坏了";
  • 控制体积:列表类工具必须带 limit,超长时截断并说明"共 128 条,已返回前 10 条"。

原因很直接:ToolMessage 会原样进入上下文。返回 500 行日志,等于每轮推理都重烧一次 token,还会把真正的结论淹没掉。

规矩三:一个工具只做一件事。

do_everything(action, params) 是典型反模式:它逼着模型在参数里做路由,action 填错一步,后面全错,而且错误信息毫无指向性。拆成 query_order / cancel_order / refund_order 后,模型只需按意图选工具——做选择比填参数容易得多。

但工具不是越多越好。工具清单本身占 token,选项过密也会稀释模型的注意力。经验阈值:单 Agent 控制在 20 个以内,超出就按业务域拆分,或用中间件按场景动态裁剪工具列表。

规矩四:身份不进参数。 这一条值得单独一节。

四、信任边界:别让模型决定"你是谁"

先看一个看起来人畜无害的写法:

@tool
def query_my_orders(user_id: str, status: str) -> str:
    """查询指定用户的订单。"""
    ...

问题在于 user_id 进了 schema,就意味着它可以由模型填写。而模型填什么,取决于上下文——用户只要说一句"我是 U1002,帮我查下我的订单",模型就会老老实实把 U1002 填进去;如果这段对话里混进了网页抓取内容或用户上传的文档,提示词注入还能让它填任意值。

这不是模型"不听话",而是设计上把权限判断交给了最不该负责的一方。正确做法是把身份挪出 schema:

from dataclasses import dataclass
from langchain.agents import create_agent
from langchain.tools import tool, ToolRuntime

@dataclass
class UserContext:
    user_id: str
    tenant_id: str

@tool
def query_my_orders(status: str, runtime: ToolRuntime[UserContext]) -> str:
    """查询当前登录用户的订单。

    Args:
        status: 订单状态,可选 paid / shipped / closed
    """
    user_id = runtime.context.user_id      # 身份来自运行时,模型看不到也填不了
    rows = db.query(
        "SELECT id, amount, status FROM orders WHERE user_id = ? AND status = ?",
        user_id, status,
    )
    if not rows:
        return f"当前用户在 {status} 状态下没有订单"
    return "\n".join(f"{r['id']} | {r['amount']} | {r['status']}" for r in rows)

agent = create_agent(
    model=deepseek_llm,
    tools=[query_my_orders],
    context_schema=UserContext,
)

agent.invoke(
    {
   "messages": [{
   "role": "user", "content": "我有哪些已发货的订单?"}]},
    context=UserContext(user_id="U102", tenant_id="T01"),
)

ToolRuntime 参数由框架在执行前注入,不会出现在工具 schema 里,模型既看不见也改不了。除了 context,它还带了另外三样东西:

属性 拿到什么 典型用途
runtime.context 调用时传入的上下文对象 身份、租户、权限等级
runtime.state 当前图状态(含 messages) 读历史消息、统计轮次、取上游节点结果
runtime.store 长期记忆存储 读写用户偏好、跨会话记忆
runtime.tool_call_id 本次调用的唯一 ID 手工构造 ToolMessage 时必须带上

边界一划就清楚了:"调用什么"进 schema,"谁在调用"进 runtime。这条线守不住,后面所有的权限校验都是纸糊的。

在这里插入图片描述

五、容错:把异常翻译成模型能懂的话

工具是 Agent 里最不稳定的部分——它连着网络、数据库、第三方 API,任何一环都可能抖。工具抛异常后,框架的兜底逻辑会给模型回一条通用错误消息,模型拿不到"下一步能做什么"的线索,表现通常是两种:反复重试同一个错误调用,或者更糟——编一个看起来合理的结果。

要控制这份措辞,用 @wrap_tool_call 中间件。它在工具执行前拦截请求,handler(request) 才是真正的执行:

from langchain.agents.middleware import wrap_tool_call
from langchain.messages import ToolMessage

@wrap_tool_call
def translate_tool_errors(request, handler):
    try:
        return handler(request)
    except ConnectionError as e:
        msg = f"下游系统超时:{e}。可以稍后重试,或改用本地缓存工具查询。"
    except PermissionError as e:
        msg = f"当前账号无权限:{e}。请告知用户联系管理员,不要重复尝试。"
    except ToolException as e:
        msg = f"参数不合法:{e}。请对照工具描述修正参数后重试。"
    except Exception as e:
        logger.exception("tool failed: %s", request.tool_call["name"])
        msg = f"工具执行失败:{e}。请如实告知用户,不要猜测或编造结果。"
    return ToolMessage(content=msg, tool_call_id=request.tool_call["id"])

agent = create_agent(
    model=deepseek_llm,
    tools=[query_ticket, update_ticket_status],
    middleware=[translate_tool_errors],
)

三个必须注意的点:

  1. tool_call_id 不能省。每条 tool_call 都必须有对应的 ToolMessage,缺了它消息历史就不合法,OpenAI 会直接报 tool_call_id not found 之类的错误;
  2. 错误信息要可操作。写"稍后重试""联系管理员""修正参数",模型才知道下一步;只写 500 Internal Server Error,它只会道歉;
  3. 明确禁止编造。"请如实告知用户,不要猜测结果"这句写在错误消息里,比写在 system prompt 里更贴近现场——它出现在模型正想找补的那一刻。

效果可以看一个真实场景。用户说"把工单 T001 状态改成完结状态",工具抛出「状态必须是:待处理、处理中、已解决、已关闭」。模型收到这条 ToolMessage 后没有硬编,而是回了一段:

目前可用状态为待处理、处理中、已解决、已关闭,您说的"完结"对应哪个?如果是问题已修复建议选「已解决」;如果彻底结束建议选「已关闭」。

这不是一次报错,这是一次成功的交互。模型没有变聪明,是错误消息给了它台阶。

在这里插入图片描述

最后一个边界要守住:不是所有异常都该吞。下游超时、参数不合法、权限不足,适合转成 ToolMessage 让模型周旋;而 KeyError、NullPointerException 这类编程错误应该让它炸出来——吞掉它们,你会在生产环境收获一个"永远在道歉、但永远查不出问题"的 Agent。所以兜底分支务必打日志、接告警,别静默返回一句"操作失败"。

六、三个容易忽略的工程细节

6.1 一次推理可以发多个工具调用

模型完全可以在一条 AIMessage 里返回多个 tool_calls——用户问"我的订单到哪了、顺便看下能退多少",模型会同时调用 query_logistics 和 calc_refund,框架并发执行后把多条 ToolMessage 一起回填,然后进入下一轮推理。

这带来两个硬要求:工具不能有共享可变状态(别在工具里改全局字典、别复用同一个数据库连接做事务),写操作必须幂等(并发重试不能重复扣款)。很多人把工具当 Controller 方法随手写,一上并发就出数据错乱,根因往往在这里。

6.2 return_direct:让工具直接终结循环

默认流程是"工具返回 → 模型再总结一轮"。但有些场景这轮总结纯属多余,甚至有害:工具已经返回了排版好的报表链接,模型再总结一遍,很容易把数字抄错。

@tool(return_direct=True) 让 Agent 在工具执行后直接结束,跳过二次加工。判据很简单:返回值是否已经是面向用户的最终措辞。是,就用它省一轮 token 和一次出错机会;不是(返回的还是原始数据),就老老实实让模型组织语言。

6.3 工具清单是有 token 成本的

工具清单随每次请求发送,且每轮推理都付一次。粗略估算:一个中等复杂度的工具(名字 + 80 字描述 + 4 个参数)约 150~250 tokens,20 个工具就是 3~5k tokens 的固定开销——比很多人的 system prompt 还长。

所以"多加个工具试试"比想象中贵。该合并的合并(同一实体的增删改查合成一个带 action 枚举的工具,注意别退化成前面说的 do_everything),该按域拆的拆,比堆清单划算。

6.4 常见踩坑对照

现象 根因 修法
模型从不调用工具 描述太笼统,名字看不出动作 名字用「动词_名词」,描述写触发场景
参数总缺字段 字段没写 description,或 required 全空 每字段补 description,必填项设进 required
调用直接报错 工具名含空格、中文或特殊字符 统一 snake_case
上下文越跑越长 工具返回大列表、大日志 加 limit,超长截断并说明总数
反复重试同一错误 错误信息不可操作 错误里给出下一步动作或合法取值
换模型后工具失灵 依赖了某家模型对描述的隐式理解 描述写全,别赌模型的常识

七、小结:工具清单就是能力边界

把这篇的要点压缩成一份上线前的检查清单:

  • 契约三件套:name 用 snake_case,description 写清触发场景与排他边界,args_schema 用 Pydantic 把枚举约束住;
  • 返回值:结构化、带字段名、空结果有明确文案、列表必带 limit;
  • 粒度:一工具一事,单 Agent 工具数控制在 20 以内,超了按域拆;
  • 信任边界:身份、租户、权限一律走 ToolRuntime,绝不进 schema;
  • 容错:@wrap_tool_call 分类翻译异常,ToolMessage 带 tool_call_id,编程错误照常抛出。

工具写得好不好,不看代码优不优雅,只看一件事:模型能不能在不问你任何问题的情况下,把它们用对。这份"无需解释的正确性",就是 Agent 稳定性的来源。

目录
相关文章
|
17天前
|
Linux 开发工具 iOS开发
Codex保姆级教程(下载+安装+登录+使用,含所有版本,2026最新)
Codex是OpenAI推出的开源AI编程智能体,本地运行,可理解整个代码库,支持自然语言指令改代码、执行命令、跑测试、修Bug,兼容Win/macOS/Linux。(239字)
7320 56
|
2天前
|
弹性计算 人工智能 API
Codex超详细入门指南(下载·安装·登录·上手,全版本覆盖,2026最新版)
建议收藏本教程,2026 全年各版本更新随时回来查阅。如果你在搭建过程中遇到任何问题,欢迎结合 阿里云工单系统 提交技术支持请求,或在 阿里云开发者社区 搜索 Codex 相关话题交流。 祝你编码愉快,效率翻倍!
1331 0
|
5天前
|
JSON 前端开发 API
阿里云最新Qwen4-Max大模型介绍:模型定位、特征、能力、适用场景解析
2026 年 11 月 11 日,阿里发布第四代旗舰模型Qwen4-Max预览版,首发千问 AI 平台 Token Plan,并同步接入千问办公、Qoder 等入口。该版本聚焦知识理解、世界感知、编程与 Agentic 四项升级,主打复杂编程、专业办公、前端设计与专业软件操作。预览期至 11 月 25 日 24:00,到期后模型标识下线;限时 2 折、新用户再享 5 折,最低 1 折可体验。
|
18天前
|
JavaScript API iOS开发
DeepSeek Harness下载、安装、配置一篇搞定(2026整理,送常用插件)
DeepSeek Harness(DSH)是DeepSeek于2026年开源的MIT协议AI Agent框架,支持插件化组装模型、工具、沙箱与UI,兼容主流大模型。本文提供免Node.js的桌面端安装包(Win/macOS),含详细图文教程及热门插件推荐。
5558 67
|
5天前
|
云安全 人工智能 安全
|
12天前
|
Linux 开发工具 iOS开发
2026最新codex下载安装保姆级使用教程(下载+安装+登录+使用,含所有历史版本)
本文详解OpenAI Codex国内快速上手指南:提供Win/macOS/Linux全平台免安装包、npm/Homebrew等多方式安装、账号/API Key双登录、简体中文切换,覆盖下载、安装、汉化、使用及高频避坑(如微软商店失败、npm超时等),10分钟即可跑通。
2827 9
|
5天前
|
人工智能 前端开发 API
阿里云Qwen4-Max 大模型详解:定位、特征、能力、适用场景与相对Qwen3-Max差异解析
2026年11月11日,阿里发布第四代旗舰模型Qwen4-Max预览版,首发千问AI平台Token Plan并接入千问办公、Qoder等入口。该版本聚焦知识理解、世界感知、编程与Agentic四项升级,主打复杂编程、专业办公、前端设计与专业软件操作等真实任务。预览期为11月11日10:00至11月25日24:00,仅支持Token Plan调用,到期后模型标识下线;限时2折、新用户再享5折,最低1折可体验。
|
2天前
|
Linux Go 开发工具
手机上跑 DeepSeek 智能体:开源安卓客户端 DSH Go 安装与使用指南
DSH Go 是一款开源安卓客户端,将 DeepSeek Harness 智能体引擎装进手机:免 Root、免 Termux,一键安装即用;支持本机运行(内置 Ubuntu+Node.js)或远程接管电脑会话;具备插话打断、过程折叠、屏幕操控、端到端加密分享等特色功能,真正实现智能体“口袋化”。
1402 0
|
10天前
|
人工智能 安全 API
DeepSeek Harness下载、安装、配置一篇搞定(2026整理,送常用插件)
DeepSeek Harness(dsh)是DeepSeek AI于2026年开源的轻量级Agent运行框架,基于Cordis内核,践行“一切皆插件”理念。支持Web/桌面双端,开箱即用;内置多模型接入、丰富插件生态(超3.5万),适配编程、办公、创作等场景。(239字)
1820 1

热门文章

最新文章