LangChain Tool Calling实战：让大模型学会调用外部工具

最近在做智能体项目的时候，团队里好几个同事都在同一个地方卡了壳：模型能聊天，但一让它查天气、算数学、查数据库，它就一本正经地开始“编”答案。直到我们把 LangChain 的 Tool Calling 真正用起来，这个问题才算彻底解决。这篇文章就围绕 LangChain 工具调用这个核心机制，把它的工作原理、实操方法和踩坑记录完整梳理一遍，希望对正在做 Agent 开发的你有所帮助。

1. 先搞清楚：Tool Calling 到底在解决什么问题

1.1 大模型的能力边界在哪里

很多人刚开始接触大模型应用开发时，都会有一个错觉：模型什么都知道。实际上，大模型只是一个“文本生成器”，它的知识截止于训练数据，它没法知道你此刻所在城市的实时天气，也算不出 123456 乘以 789012 这种大数精确结果，更没法替你查询企业内部数据库里的订单状态。

这不是模型“笨”，而是它的设计目标本身就不包含这些能力。模型擅长的是语言理解、逻辑推理和文本生成，而不是调用外部系统、执行精确计算或访问实时数据。

Tool Calling（工具调用）就是为了解决这个边界问题而生的。它的思路很朴素：当模型遇到自己搞不定的任务时，不强迫它硬答，而是让它“申请”调用一个外部工具，拿到工具的返回结果后再继续作答。

1.2 Tool Calling 与 Function Calling 的关系

在 LangChain 的发展脉络里，先有 Function Calling 这个概念，后来统一演进为 Tool Calling。很多人问我这两个到底有什么区别，我用大白话解释一下：

Function Calling 是早期模型接口里的叫法，它让模型学会从一段 JSON 里挑出该调哪个函数、参数填什么。而 Tool Calling 是 LangChain 在更上层做的统一抽象，它把“函数”扩展成了更通用的“工具”——可以是一个 API 接口、一段数据库查询、一个代码执行器，甚至另一个 Agent。

所以你可以把 Tool Calling 理解为：LangChain 把“模型要调外部函数”这件事做成了标准协议，你只要定义好工具，框架负责处理模型与工具之间的所有消息流转。

1.3 它解决的核心痛点

传统开发大模型应用时，最大的痛点是不确定性。你问模型“北京的天气怎么样”，它可能回答“北京今天晴，23度”——这个数字完全是编的，但它说得头头是道。

要解决“幻觉”问题，常规方案是在提示词里加规则“不知道的就老实说不知道”，但效果不稳定。Tool Calling 给出了一个更优雅的解法：模型不再需要“知道”答案，它只需要“知道”去哪里找答案。当模型判断自己需要外部信息时，它会输出一个结构化的调用意图（比如“调用 get_weather 工具，参数 location=北京”），由代码去真实执行这个调用，再把真实结果交给模型组织语言。

这套机制让应用从“模型背书”变成了“工具背书”，准确性完全由工具的执行结果来保证。

2. 工具定义：从零开始写一个可调用工具

2.1 用 @tool 装饰器快速定义

LangChain 提供了多种定义工具的方式，最推荐的是@tool装饰器。直接看代码：

from langchain_core.tools import tool from datetime import datetime @tool def get_current_time() -> str: """返回当前的日期和时间，格式为 YYYY-MM-DD HH:MM:SS""" return datetime.now().strftime("%Y-%m-%d %H:%M:%S")

就这么简单，一个工具就定义好了。@tool装饰器会自动从函数的名称、文档字符串（docstring）、参数类型推导出工具的 JSON Schema，LangChain 会把这段 Schema 注入到发给模型的提示词里，让模型知道“有这么个工具可用”。

2.2 参数 Schema 为什么要讲究

实际项目里，工具往往不止一个参数。比如一个查询航班信息的工具，可能需要起点、终点、日期三个参数。这时候参数 Schema 的清晰度会直接影响模型调用是否准确。

@tool def search_flight(departure: str, arrival: str, date: str) -> str: """查询指定日期从出发地到目的地的航班信息 Args: departure: 出发城市名称，如"北京" arrival: 到达城市名称，如"上海" date: 日期，格式 YYYY-MM-DD """ # 这里调用真实的航班查询 API return f"查询到 {departure} 到 {arrival} 在 {date} 的航班信息：..."

每个参数写成什么含义、什么格式，必须在 docstring 里写清楚。模型就是靠这些描述来决定参数填什么的。如果描述含糊，模型就很容易把用户输入里的地名填错位置。

注意：工具名称和参数描述尽量避免模糊词汇。比如“departure”叫“出发地”，不要写成“a”，模型不是你肚子里的蛔虫，它只认你没写清楚的文字。

2.3 工具定义背后的原理

当你调用@tool装饰一个函数，LangChain 会把函数包成一个Tool对象，里面最关键的一个属性叫args_schema，它是个 Pydantic 模型，描述了工具的入参结构。

模型调用工具时，并不是直接执行你的 Python 函数，而是先生成一段符合这个 Schema 的 JSON 参数，LangChain 再用这段 JSON 去调用你的函数。整个过程分成两步：

1. 模型根据用户的问题和工具 Schema，决定“我要用 search_flight，参数是 ‘北京’、‘上海’、‘2026-03-15’”
2. LangChain 收到这段结构化意图，解析 JSON 后调用真实函数，拿回结果

第一次理解这个过程时，我有一个很深的体会：模型其实“不会”调用工具，它只是“说”它想调用哪个工具。真正执行工具的是框架层代码。理解这一点，后续调试就能事半功倍。

3. 核心流程：一次完整工具调用的五个环节

3.1 从消息流转看 Tool Calling

LangChain 的工具调用不是一次 HTTP 请求就完事的，它是一个多轮消息往返的过程。我把它拆成五个环节：

1. 构建工具列表，绑定到模型
2. 用户发出问题，模型判断需要调用工具，返回一个“调用意图”
3. 代码解析意图，真正执行对应的工具函数
4. 把工具执行结果封装成一条新消息，回传给模型
5. 模型结合工具结果，生成最终答复

用代码表示这个过程：

from langchain_openai import ChatOpenAI model = ChatOpenAI(model="gpt-4o", temperature=0) tools = [get_current_time, search_flight] model_with_tools = model.bind_tools(tools) response = model_with_tools.invoke("现在几点了？北京到上海的航班怎么样？") # 如果模型认为需要调用工具，response.tool_calls 会有内容 print(response.tool_calls)

运行后你会发现，模型并没有直接回答“几点了”，而是返回了一个结构化的tool_calls列表，里面包含工具名和一个参数 dict。

3.2 bind_tools 到底做了什么

很多初学者会好奇bind_tools是不是一个很复杂的操作。它做的事情其实很“笨”：

1. 把工具的 JSON Schema 收集起来
2. 在发起模型请求时，把这些 Schema 附加到请求体里
3. 给模型一个“可调用工具清单”

模型在训练时已经学会了“看到工具清单就按格式输出调用意图”的行为模式，所以bind_tools就是完成了这种格式上的对接。

3.3 ToolMessage：工具回传结果的载体

当代码执行完工具函数后，需要把结果交还给模型。LangChain 用ToolMessage来承载这部分内容：

from langchain_core.messages import ToolMessage tool_result = "当前时间：2026-03-15 14:30:00" tool_message = ToolMessage( content=tool_result, tool_call_id=response.tool_calls[0]["id"] )

这个tool_call_id是关键，它把工具调用指令和工具返回结果一一对应起来。在多工具并行场景下，每个工具结果都必须“认领”自己对应的那次调用，模型才能正确地把结果归属到恰当的步骤。

我见过很多报错，都是因为忘了传 tool_call_id，或者传错了。这个字段就像快递单号，消息流转全靠它对得上。

4. 实操案例：做一个能查天气和算数的助手

4.1 定义两个工具

理论再多不如跑一个完整案例。我们做一个具有两个工具的小助手：支持实时天气查询和数学计算。

from langchain_core.tools import tool import math @tool def get_weather(city: str) -> str: """查询指定城市的当前天气 Args: city: 城市名称，如"上海" """ # 这里对接真实天气 API weather_data = { "上海": "多云，23℃", "北京": "晴，18℃", "广州": "雷阵雨，26℃", } return weather_data.get(city, f"暂无 {city} 的天气数据") @tool def calculator(expression: str) -> str: """计算数学表达式的值 Args: expression: 数学表达式，如 "123456 * 789012" """ try: result = eval(expression) return f"计算结果：{result}" except Exception as e: return f"表达式错误：{e}"

注意，calculator里使用eval只是演示，实际生产中请使用安全计算库或者干脆交给专门的代码执行服务，防止注入风险。

4.2 搭一个完整的循环调用逻辑

有了工具后，我们需要写一个循环：模型决定是否调用工具，如果调用就执行，然后把结果回传，再来一轮，直到模型不再需要工具。

from langchain_core.messages import HumanMessage, AIMessage, ToolMessage def run_agent(user_query: str, tools: list, model): model_with_tools = model.bind_tools(tools) messages = [HumanMessage(content=user_query)] max_rounds = 5 # 防止死循环 for _ in range(max_rounds): response = model_with_tools.invoke(messages) messages.append(response) if not response.tool_calls: # 模型不再需要调工具，这就是最终答复 return response.content # 执行所有工具调用（可能有多个并行工具） for tool_call in response.tool_calls: tool_name = tool_call["name"] tool_args = tool_call["args"] tool_obj = next(t for t in tools if t.name == tool_name) result = tool_obj.invoke(tool_args) messages.append(ToolMessage( content=result, tool_call_id=tool_call["id"] )) return "超过最大轮数，已自动终止" # 使用示例 result = run_agent("上海天气怎么样？顺便算一下 123456 * 789012", [get_weather, calculator], model) print(result)

4.3 执行结果拆解

我实际跑了一遍，模型的决策过程大致是：

1. 模型看到“上海天气怎么样”，输出 tool_call:get_weather，参数{"city": "上海"}
2. 模型看到“顺便算一下”，输出第二个 tool_call:calculator，参数{"expression": "123456 * 789012"}
3. 两个工具并行执行，返回“多云，23℃”和“计算结果：97408265472”
4. 模型读完两个 ToolMessage 后，输出最终答复：“上海当前多云，23℃。另外，123456 × 789012 = 97408265472。”

这里值得注意的一点是：用户一句话里提了两个独立需求，模型会同时产生两个tool_calls，而不是一个一个排队调用。LangChain 支持这种并行工具调用，执行效率比串行高不少。

5. 复杂工具定义：多参数、嵌套结构与动态选择

5.1 用 Pydantic 模型定义更复杂的入参

当工具的入参比较复杂时，比如需要嵌套结构，用函数的 docstring 就不太够用了。这时候推荐用 Pydantic 模型显式定义args_schema：

from pydantic import BaseModel, Field from langchain_core.tools import tool class BookingInput(BaseModel): """酒店预订参数""" city: str = Field(description="城市名称") check_in: str = Field(description="入住日期，YYYY-MM-DD") check_out: str = Field(description="离店日期，YYYY-MM-DD") room_count: int = Field(default=1, description="房间数量") @tool(args_schema=BookingInput) def book_hotel(city: str, check_in: str, check_out: str, room_count: int = 1) -> str: """预订酒店""" return f"已预订 {city} {check_in} 至 {check_out} 的 {room_count} 间房"

用Field(description=...)写参数说明，比在 docstring 里写更规范，Pydantic 生成的 JSON Schema 也会结构化得多。而且类型必须写准确——room_count是 int，模型就会尝试把用户说的“两间”转成2，不是硬塞一个字符串进去。

5.2 工具的动态加载与选择性暴露

一个真实项目里，工具数量可能很多：十几个 API、数据库查询、内部文档检索，全都绑给模型不仅浪费 token，还会让模型“挑花眼”选错工具。LangChain 里可以做工具路由，根据用户输入动态选择暴露哪些工具。

一种常用做法是用一个“路由工具”：

@tool def route_to_department(query: str) -> str: """将问题路由到对应处理工具，返回目标工具名称""" if any(k in query for k in ["天气", "温度", "下雨"]): return "weather_tool" elif any(k in query for k in ["机票", "航班"]): return "flight_tool" else: return "default_tool"

第一轮用route_to_department判断问题领域，第二轮再把目标工具绑定给模型。这样做的好处是：全局只暴露一个路由工具，模型选择难度小，准确率更高，同时也能控制每次请求的 token 消耗。

5.3 工具之间如何分工才合理

工具设计的粒度，直接影响 Agent 的表现。我踩过的坑是：一开始把工具设计得“太细”，比如分别定义“查询上海天气”“查询北京天气”“查询广州天气”三个工具，结果模型经常选错。正确的做法是：一个get_weather工具，把城市作为参数，让模型自己填。

反过来，如果工具太“粗”，比如一个大而全的execute_sql工具，什么查询都往里塞，模型生成的 SQL 很可能因为上下文理解偏差而执行出错。合适的粒度是：一个工具对应一个清晰的能力边界，参数尽量精简、语义尽量明确。

6. 常见问题与排查技巧实录

6.1 模型返回了 tool_calls，内容却是 null

这个问题在刚上手时出现频率极高。模型在tool_calls字段里给了名字，但args是null或者是一个不完整 JSON。大部分情况下是工具 Schema 描述不清或者参数描述冲突导致的。

排查思路：

1. 把模型返回的原始response打印出来，确认tool_calls的实际结构
2. 检查工具的 JSON Schema 是否生成了，参数类型和描述是否合理
3. 尝试给工具和参数加上更明确的描述，比如“城市名称，必须是中文全称”

一个实际例子：某次让模型调用书查询工具，参数描述是“书名”，模型返回的args是{"book_number": ""}，空字符串。原因是我在函数签名里同时存在book_name和book_no两个近似字段，模型混淆了。改成统一字段并删除冗余参数后，问题消失。

6.2 工具结果太长，把上下文撑爆

工具返回的内容往往比模型原始输出的 token 数大得多。比如查数据库时返回了几百行数据，全塞进ToolMessage，下一轮请求很快就超出模型的上下文窗口。

我常用的对策是“结果压缩”和“内容截断”双管齐下：

• 在工具内部先聚合数据，只返回汇总统计，不要返回明细
• 使用 LangChain 的trim_messages工具，在把消息列表发给模型之前，按 token 上限裁剪掉最旧的中间消息

from langchain_core.messages import trim_messages trimmed = trim_messages( messages, max_tokens=3000, strategy="last", token_counter=model, include_system=True, )

6.3 Agent 陷入调用死循环

如果工具调用没有终止条件，Agent 可能在两个工具之间反复横跳，甚至自己调用自己，烧掉大量 token。默认情况下我的run_agent循环设了max_rounds = 5，这是防死循环的底线。

另一种死循环是“工具执行成功但模型认为没成功”。比如工具返回的字符串里带了特殊格式，模型误读为“出错了”，于是反复重试。解决方式是让工具返回明确的成功信号，比如固定加前缀[成功]或[失败]，减少模型的误判空间。

6.4 常见问题速查表

7. 使用 Tool Calling 的一些个人心得体会

做 LangChain 工具调用开发有一阵子了，最深的感受是：工具调用本身不难，难的是对消息流的理解和对工具边界的把握。

消息流这件事，很多人一开始不习惯。普通开发是“请求-响应”一次搞定，而工具调用是“对话-决策-执行-回填-再对话”的多轮过程。最开始调试时，我经常对着messages列表一脸懵，不知道哪条消息是模型说的、哪条是工具返回的。后来养成了一个习惯：把 messages 全部打印出来，每一条都标注它的 type（human / ai / tool），再打印 response.tool_calls 的内容。一旦你亲眼看完两三轮完整的消息流转，整个机制就再也没有神秘感了。

工具边界的把握则需要在实际项目中反复打磨。有同事做过一个客服助手，一开始把“查订单”“查物流”“查售后政策”三个能力塞进一个工具里，结果模型频繁把订单号塞到物流参数里。后来拆成三个独立工具，每个都写清楚参数含义，模型调用准确率立刻就上去了。

还有一点值得说的：工具调用只是手段，不是目的。很多人沉迷于把 Agent 做得越来越复杂，工具越挂越多，最后反而因为选择太多而出错。我个人的做法是：能用一两个工具解决的需求，绝不上三四个。简单往往意味着更稳定。

最后分享一个调参小技巧。模型参数里，temperature对工具调用的准确性影响很大。我在做 Agent 任务时会把temperature设为 0 或极低值，这样模型在生成工具调用 JSON 时更“保守”，不太会自由发挥出一些奇怪的参数值。如果你发现模型生成的工具参数老是和用户原话不一致，先回忆一下自己是不是把temperature调太高了。

Tool Calling 是 LangChain 生态里最值得吃透的一块基础设施。把消息流转机制搞懂，把工具定义规范练熟，你在构建智能体应用时就会觉得特别顺手。接下来不管是做多 Agent 协作、做流程编排还是接外部的 API 生态，都能在这个基础上继续往上搭。