LangChain 里的 Tool是把我经常被问到的一个问题彻底解决掉的东西大模型只能生成文本那它怎么查天气、查订单、读写数据库、调内部接口答案就是把模型之外的真实能力包装成一个一个可以被模型“点名调用”的函数这个函数就是 Tool。模型负责判断该干什么Tool 负责实际去干。这一章我会按自己在项目中真正用过的路径来写为什么需要 Tool、怎么创建 Tool、参数和描述怎么写模型才不会填错、怎么把 Tool 接入 Agent 跑起一个完整的“思考-调用-观察-回答”循环最后把调试时踩过的坑整理成一份可以直接对着排查的清单。适合正在学 LangChain 的开发者、想给模型接业务能力的后端工程师以及被“模型一本正经瞎编”折磨过的人。1.1 先说清楚模型到底缺什么大模型的强项是文本生成、知识压缩、逻辑推理但它有几个天生短板。第一训练数据有截止时间它不知道“今天”是哪天更不知道“现在的天气”“此刻的股价”这类实时信息。你直接问它“韶光市今天适合穿什么”它只能根据历史知识猜猜错了就是幻觉。第二它访问不了外部系统。企业内部的数据在数据库里、在业务接口后面模型本身没有凭据也没有通道去拿它唯一能接触到的就是用户输入的那段文本。第三它在精确计算上不可靠。让它算“2718 乘以 3649 等于多少”它可能给出一个看起来合理但结果错误的大数。不是模型笨是它的计算方式和普通程序不一样。Tool 的思路就是针对这三块短板做弥补把“获取实时数据”“读写业务系统”“执行精确计算”这些能力封装成函数由模型来调度。模型在回答过程中发现需要这些能力时会输出一个结构化的调用请求程序收到请求后执行对应函数再把结果喂回给模型最后模型基于真实结果组织回答。1.2 Tool、工具调用与 Function Calling 是什么关系刚开始接触时很容易被几个词绕晕Tool、Function Calling、bind_tools。我说一下自己理解后的结论。Function Calling 是模型服务商提供的一种底层能力指的是模型在生成回答时多输出一段结构化 JSON内容是“我想调用某个函数函数名是什么参数是什么”。它本质上是模型输出格式的一种扩展。Tool 是 LangChain 做的一层抽象。你写一个 Python 函数加上 tool 装饰器LangChain 会帮你把函数转换成模型服务商要求的 JSON Schema 描述发请求时随 Prompt 一起发给模型模型返回的调用请求LangChain 又能帮你解析成 Python 字典传给函数执行。bind_tools 就是把工具列表绑定到某个模型对象上绑定之后这个模型在回答时才有权限“提案”调用工具。注意只是提案。模型输出的是“我想调用”的意图真正执行函数的是你的代码或者 Agent 循环。提示很多新手绑完工具就以为模型会自动执行函数结果发现模型只是“说”要调用并没有真的执行于是怀疑框架有问题。实际上执行这一步必须由 Agent 或你自己的代码来完成这是理解 Tool 整个机制的核心。1.3 工具的描述就是模型的“说明书”一个非常容易被低估的事情是模型不会运行你的代码它只能阅读工具的 name 和 description 来决定要不要调用、怎么填参数。所以 description 写得清不清楚直接决定模型选工具的准确度。我见过太多失败案例。工具 description 写的是“查询天气功能”模型面对用户问“明天出门要不要带伞”可能根本想不到调它。更好的写法是直接说明触发场景“当用户询问任一城市天气、气温、降水、风力或出行建议时使用输入城市中文名称。如果用户只说‘那边’‘这里’先尝试从上下文推断城市无法推断时向用户确认。”这个道理跟给实习生写交接文档一样文档只写“负责接待”是没用的要写清楚“什么情况接待、接待时做什么、拿不准时问谁”。模型在信息不足时倾向于不调用工具而不是冒险调用。所以把描述写成“触发条件 参数说明 边界处理”三段式是性价比最高的优化。2.1 最常用的方式tool 装饰器最常用的创建方式是直接写一个带类型注解和 docstring 的函数加上 tool 装饰器。我平时八成以上的工具都是用这种方式创建的。from langchain_core.tools import tool tool def get_weather(city: str) - str: 查询指定城市的实时天气。 Args: city: 城市中文名称例如“韶光市”“星野市”。 # 这里替换成真实天气服务的调用逻辑 return f{city} 今天多云转晴气温 21~27 摄氏度。这个装饰器会自动帮你完成三件事函数名变成工具名docstring 变成工具描述类型注解生成参数 JSON Schema。返回值默认直接作为工具执行结果。这里有个值得注意的细节docstring 的第一段会成为工具描述的主体如果需要写给参数看的说明放在 Args 段落里LangChain 会解析并关联到对应参数上。所以 docstring 一定不要写“这是一个函数”这种等于没说的话每一句都要给模型的决策提供信息。如果不想用装饰器也可以用 Tool.from_function 这个类方法来创建效果等价适合那些不方便加装饰器、或者需要动态生成工具的场景。2.2 需要精细控制时用 BaseTool 和 args_schematool 能覆盖大部分场景但当你需要精确控制参数校验、默认值、参数描述、异步实现时自定义一个继承 BaseTool 的类更合适。from langchain_core.tools import BaseTool from pydantic import BaseModel, Field class WeatherInput(BaseModel): city: str Field(description城市中文名称) days: int Field(default1, description预报天数取值 1~3) class WeatherTool(BaseTool): name: str get_weather description: str 查询城市未来几天的天气适合回答与气温、降水、穿衣建议相关的问题 args_schema: type[BaseModel] WeatherInput def _run(self, city: str, days: int 1) - str: # 同步执行逻辑 return f{city} 未来 {days} 天以多云为主最高气温 27 度。 async def _arun(self, city: str, days: int 1) - str: # 异步执行逻辑用于 AsyncAgent 场景 return await self._async_query(city, days)args_schema 用 Pydantic 模型定义好处很明显参数类型校验发生在模型决定调用之后、函数执行之前如果模型填了错误类型或者缺了必填字段LangChain 会得到明确的校验错误并反馈给模型模型有机会修正参数再调一次而不是整个流程直接崩掉。注意BaseTool 子类里 _run 实现同步逻辑_arun 实现异步逻辑。如果只实现了 _run在异步 Agent 里调用会报 NotImplementedError。项目里如果用异步为主两个方法都建议实现。2.3 参数说明的实操写法把每个参数当表单字段我写参数描述时有个习惯把每个参数都当作“需要用户照着填的表单字段”来设计。参数名要直观Field 描述要写清楚格式、取值范围和缺失时的处理方式。比如一个查询订单的工具参数是 order_id如果描述只写“订单号”模型遇到用户说“查一下我上个订单”时就会很为难随便编一个 ID 会出错不调用又完不成任务。把描述改成“订单号形如 ORD-2025-0018如果用户没有提供完整订单号先询问用户”模型就知道该怎么处理了。还有一个实测很有用的技巧给可选参数设置合理的默认值能显著减少“模型少传参数导致报错”的概率。比如天气工具的 days 默认是 1用户没明确说要看几天时模型不会为了凑参数硬编一个数字。参数数量也值得注意。单个工具的参数尽量控制在 3 个以内参数越多模型填错的概率越高。如果一个工具需要五六个参数考虑拆成两个工具或者用更明确的业务对象做参数。3.1 多参数工具与 Pydantic 校验单参数函数只是热身真实业务里工具通常是多参数的。直接用类型注解也能生成 schema但更可控的方式是显式传入一个 Pydantic 模型作为 args_schematool 装饰器接受这个参数。from pydantic import BaseModel, Field class QueryOrderInput(BaseModel): order_id: str Field(description订单号格式 ORD-2025-0018用户未提供时先询问) with_items: bool Field(defaultFalse, description是否返回订单商品明细) tool(args_schemaQueryOrderInput) def query_order(order_id: str, with_items: bool False) - str: 根据订单号查询订单状态、金额和预计送达时间。 if with_items: return f订单 {order_id} 状态已发货金额¥1299明细保温杯 x1、数据线 x2 return f订单 {order_id} 状态已发货金额¥1299这里有个必须注意的一致性要求函数的参数名和 Pydantic 字段名必须完全一致类型也要对得上否则 LangChain 解析参数时会因为键名对不上而报错。我踩过这个坑函数里写的是 orderIdPydantic 里是 order_id结果模型填了 orderId解析时找不到对应字段。3.2 返回“文本 数据”的双通道结果工具的执行结果不一定非要是一段给人看的纯文本。在新版 LangChain 里可以通过 response_format 把返回值拆成两部分给模型看的文本内容和给业务系统用的结构化数据。from langchain_core.tools import tool tool(response_formatcontent_and_artifact) def get_sales_report(date: str) - tuple[str, dict]: 获取指定日期的销售汇总数据。 data {date: date, revenue: 250000, orders: 320, avg_order: 781.25} text f{date} 销售额 25 万元订单 320 单客单价约 781 元。 return text, data第一部分是模型组织回答时使用的摘要文本第二部分是结构化的原始数据。这个设计的价值在复杂业务里体现得很明显模型只看到摘要不会被一大段 JSON 干扰判断下游系统或者后续步骤拿 artifact 继续做数据加工不用再从文本里解析。我建议所有工具都遵循这个思路——返回值保持精简只给模型必要的结论和关键数字。至于完整明细走 artifact 或者文件系统不要让模型在一个上下文里塞进一整天的订单流水。3.3 工具组合与 bind_tools 绑定工具建好后下一步是把它们绑定到模型上。LangChain 的模型对象提供了 bind_tools 方法。from langchain_openai import ChatOpenAI llm ChatOpenAI( modelyour-default-model, temperature0, ) tools [get_weather, query_order, get_sales_report] llm_with_tools llm.bind_tools(tools)这行绑定代码背后做的事情不少LangChain 会读取每个工具的 name、description、args_schema转换成模型服务商要求的 JSON Schema 列表随着请求一起发给模型。模型看到这一组工具定义后在回答时才有机会输出对应的调用请求。特别提醒temperature 在工具调用场景下建议设成 0 或者比较低的值。温度越高模型输出越随机它可能在同一问题上每次调用不同的工具、填不同的参数这对工具调用场景非常致命。绑定之后先单独跑一次模型观察输出结构确认工具定义被正确理解。4.1 理解 tool_calls 输出结构工具绑定成功后先不要急着接 Agent我建议直接 invoke 一次看看模型返回了什么。result llm_with_tools.invoke(帮我查一下韶光市今天天气) print(result.tool_calls)正常情况下 result.tool_calls 是一个列表里面是类似这样的结构[ { name: get_weather, args: {city: 韶光市}, id: call_xxx, type: tool_call, } ]这说明模型已经完成了“判断用哪个工具、填什么参数”这一步。接下来需要你写代码解析 tool_calls、执行 get_weather、把执行结果包装成 ToolMessage 再回传给模型让模型基于工具结果生成最终回答。这一来一回就是最小可用的工具调用闭环。理解这个闭环后再看 Agent 会轻松很多——Agent 的本质就是帮你把这个循环自动跑起来。4.2 用 Agent 让循环自动跑手写循环可以加深理解但生产环境我更推荐直接用 LangChain 的 Agent 封装。目前稳定推荐的做法是 create_tool_calling_agent 加 AgentExecutor。from langchain.agents import AgentExecutor, create_tool_calling_agent from langchain_core.prompts import ChatPromptTemplate prompt ChatPromptTemplate.from_messages([ (system, 你是智能助手。回答需要实时数据时必须调用工具获取工具结果要如实转述。), (placeholder, {chat_history}), (human, {input}), (placeholder, {agent_scratchpad}), ]) agent create_tool_calling_agent(llm, tools, prompt) executor AgentExecutor(agentagent, toolstools)这个 Prompt 模板有几个占位符缺一个都会报错。{input} 是用户输入{chat_history} 是多轮对话的上下文{agent_scratchpad} 是 Agent 循环里的“草稿纸”专门存放中间的思考过程和工具调用记录。最后这个最容易漏手写 Prompt 时经常忘记加。调用方式和普通链一致response executor.invoke({input: 韶光市今天天气怎么样适合穿外套吗}) print(response[output])AgentExecutor 内部做了这样几件事第一轮让模型出 tool_calls模型说要调用 get_weather它就执行该函数把结果包装成 ToolMessage 追加到消息列表第二轮再让模型基于工具结果生成回答。如果模型第一轮就没有输出 tool_callsAgentExecutor 直接把回答返回循环终止。4.3 ReAct 循环、停止条件与开销控制Agent 的循环本质上是一种“思考-行动-观察”结构也就是 ReAct。模型先思考当前任务需要什么信息决定调用哪个工具拿到工具返回的观察结果后继续思考直到它认为信息足够不再请求调用工具才生成最终回答。有个初学者很容易困惑的点为什么模型明明可以直接回答还要先调一下工具这不是多此一举。比如你问“韶光市适合穿外套吗”模型判断这个问题依赖实时天气所以先查天气再回答把“瞎猜”变成“有依据的推断”。这正是 Tool 存在的核心理由。为了控制循环次数和成本AgentExecutor 提供了 max_iterations 参数默认是 15。我一般会在业务场景里调小比如 5 到 8防止模型在一个问题上反复调用工具导致时间拉长、费用失控。如果观察到日志里有大量重复调用同一个工具的行为基本可以断定是工具描述没写好模型在拿不到有效信息时只能反复尝试。5.1 load_tools 与内置工具很多基础能力其实不用自己实现。LangChain 提供了 load_tools 接口按名字加载一批预设工具。from langchain.agents import load_tools tools load_tools([requests_all, human])requests_all 类工具适合让模型访问指定的 HTTP 接口human 是个特殊工具模型遇到不确定的事时可以反过来向人提问确认——这个工具在需要人工介入审核的业务里特别好用。搜索类工具也有内置版本但注意这类工具背后往往绑定具体搜索服务商的账号和套餐。加载前一定要先确认环境变量配好、套餐计费方式能接受否则调用时要么直接报鉴权错误要么上线后每搜一次都在烧钱。我建议先看文档确认服务商再决定用哪个加载名。注意load_tools 返回的是工具列表本质和你手写的一样只是省了定义过程。但你无法控制它们内部的实现细节所以生产环境里涉及敏感数据或核心业务的还是建议自己写工具便于审计和加兜底逻辑。5.2 Toolkit为什么要按场景打包工具Toolkit 是“工具包”本质是围绕某个数据源或系统的一组工具的集合。比如操作数据库会包含列出表结构、执行查询、查看表数据等一组工具操作文件系统会包含列目录、读文件、写文件等一组工具。用 Toolkit 最大的收益是工具之间职责划分清晰。让模型查一个业务指标它需要先调用“列出现有表”了解有哪些数据再调用“执行查询”取数。如果只给一个巨大的全能工具模型反而容易在参数上翻车——工具拆得越细模型每个决策点的负担越轻。我在项目里用 Toolkit 的典型场景有两个。一是接入企业已有系统时把系统能力按“元数据查询”“实际操作”“权限校验”拆成多个工具二是做复杂任务拆解让模型能组合多个工具完成一个用户请求而不是要求一个工具把所有事情做完。不过也要提醒一句工具数量并不是越多越好。工具数量一多模型的选择空间变大误调用的概率也上升。每增加一个工具都应该有明确的触发场景并且在测试集上跑一遍回归看它会不会被错误触发。5.3 缓存、错误处理与安全边界工具如果很费时或者很贵比如调用外部付费接口建议做缓存保护。from langchain_core.cache import InMemoryCache from langchain.globals import set_llm_cache set_llm_cache(InMemoryCache())要注意这里缓存的是模型层面对相同请求的计算结果。如果只想对某个昂贵工具的执行结果做缓存更直接的方式是在函数内部自己做判断以城市名加日期作为 key命中就直接返回上一次的结果没命中再发真实请求。错误兜底也是必须考虑的。给工具加上 handle_tool_error 后工具执行抛异常时Agent 会把错误信息返回给模型由模型决定怎么应对而不是整个调用链直接崩溃。tool(handle_tool_error工具执行失败请将失败原因告知用户并停止后续操作) def get_weather(city: str) - str: ...最后是安全边界。工具一旦接上 Agent模型就能调度它而模型可能被用户的极端输入引导去做意料之外的事。所以工具的入参必须做强校验长度、格式、取值范围、权限都要在函数内部把关。永远不要写一个接受任意 SQL 或任意 URL 就执行的工具。这个边界意识应该和写工具本身同等重要。6.1 模型一直不调用工具先按顺序排查这是问得最多的一个问题。遇到时别先怀疑框架按顺序查第一确认模型服务商支持工具调用能力不是所有模型都原生支持 Function Calling。第二确认工具列表真的传进了 bind_tools并且返回对象被正确使用——忘记接收绑定结果是常见的低级失误。第三把系统提示词里“你可以调用工具”的交代写具体明确告诉模型什么场景下必须先调用工具再回答。第四检查工具的 name 和 description模型面对含糊描述时会选择不调用而不是冒险调用。我调试时遇到过一种很隐蔽的情况工具列表里混入了一个参数描述极其复杂的工具模型评估后认为调用风险高于是一律不调用任何工具。把它从工具列表里临时移除后其他工具恢复调用。这就是“一个坏工具拖垮所有工具”的真实案例排查时可以试试二分法把工具列表减半看模型是否恢复调用行为逐步定位问题工具。6.2 参数校验与 JSON 解析问题工具被调用却参数报错通常报的是 Pydantic 校验错误比如函数需要 str模型却传了 int或者传了未知参数名。原因多半是参数描述不够清楚模型根据用户原话猜了类型。解决办法在前面已经反复强调Field 描述里写清楚“传什么”“范围多少”“什么格式”。函数签名与 args_schema 字段不一致也会报错。Pydantic 模型里定义了 city 和 days函数却只声明了 city 一个参数执行时 LangChain 会因为多余的参数键而抛错。保持两边字段名、类型、默认值完全一致是最基本的检查项。JSON 解析失败通常不出现在使用 AgentExecutor 的标准流程里而是出现在你手动解析模型输出时。可以说自己写正则去解析工具调用是风险最大的做法我强烈建议直接用框架的 Agent 编排能力它们内部处理了消息类型转换和解析比自己维护一套解析逻辑稳健得多。6.3 Agent 循环异常与上下文超限循环不终止的典型表现是模型反复调用同一个工具日志里能看到大量重复执行记录。首先把 max_iterations 调小避免无限循环烧钱然后重点检查工具的返回值是否真正回答清了模型的问题。很多时候模型重复调用是因为工具返回的信息不全它拿不到关键字段只能再试一次。上下文超限则是工具返回太长的结果导致的。工具返回的一段完整数据表会原封不动进入模型上下文可能把窗口撑爆。解决方法是返回内容精简再精简给模型的只要结论和关键数字明细放 artifact 或者单独的文件交互。处理工具结果还有一个不易察觉的点工具结果会以 ToolMessage 形式重新进入模型上下文所以返回文本的语气会影响模型最终回答的语气。我习惯让工具返回中性、客观的事实陈述不带“亲好消息”这类带情绪的文案模型转述时会更可控。6.4 排查速查表现象先查什么大概率原因处理方向模型不调用工具bind_tools 是否生效、模型能力工具描述不清晰或模型不支持工具调用优化 description换支持工具调用的模型工具参数校验报错Pydantic 错误信息Field 描述不清导致模型填错类型强化参数说明控制参数数量工具执行了但答案不对工具返回内容返回文本丢失关键信息精简结构化返回减少模型推理负担循环反复调用同一工具Agent 日志返回值没有满足模型的信息需求补全返回内容调低 max_iterations上下文超限工具返回长度返回了整段原始数据只回传摘要明细放 artifact异步调用报 NotImplementedError工具类实现只写了 _run 没写 _arun补全异步方法6.5 调试辅助技巧调试 Agent 时打开 verbose 模式是最快的做法executor AgentExecutor( agentagent, toolstools, verboseTrue, )verbose 会打印模型每一步的思考、工具调用请求、工具返回结果一眼就能看到循环卡在哪一步。还可以从返回结果里拿中间步骤出来看result executor.invoke({input: 韶光市今天天气怎么样}) for step in result.get(intermediate_steps, []): print(step)我现场排查时总是先开 verbose然后判断是“模型选错工具”还是“工具本身报错”模型选错工具去改 description工具本身报错去改函数代码。这两类问题的处理方向完全不同方向错了会浪费大量时间。另外拿到中间步骤后可以打印每一步的消息类型和内容字段确认是 AIMessage 带 tool_calls还是 ToolMessage 带执行结果。类型对不上往往是版本差异或者消息被手动构造时漏了字段。最后分享一点我的使用习惯。如果你是要把 Tool 用到真实业务里建议先从单个工具跑通闭环再逐步增加工具和工具包。工具数量一多调试复杂度是上升的因为模型的决策空间变大、误定位率也上升。每次新增工具后至少用真实的用户问题做一轮回归重点观察它会不会被错误触发。工具描述和参数设计值得像产品文案一样反复打磨——我见过不少团队花大量精力写复杂的工具基类却不愿意花十分钟把 description 写清楚最后模型选不准工具反过来怀疑框架方向其实从一开始就偏了。