LangChain 学习笔记(09):工具(Tool)定义与调用闭环
📌 TL;DR(先看结论)
- 工具(Tool)就是「给大模型装上的手脚」 :大模型只会「说话」,不会「做事」。你用一个 Python 函数 + 一段描述,就把它包装成模型能识别、能调用的「工具」。模型判断该调用哪个工具时,只返回工具名 + 参数 (
tool_calls),真正的执行还是你本地代码做的。 - 定义工具有两种主流姿势 :
@tool装饰器(简单函数直接用,靠 Docstring 自动生成参数描述)和StructuredTool.from_function(没有 Docstring 或要精确控制时用 Pydantic 强制声明参数 schema)。一句话:简单用@tool,精确用StructuredTool。 - 调用闭环三步走(务必背下来) :①
model.bind_tools(tools)把工具塞给模型 → ② 模型返回AIMessage.tool_calls(只有意图,没执行)→ ③ 你遍历tool_calls本地invoke执行,把结果拼成ToolMessage再丢回给模型生成最终答案。漏了任何一步,工具都「白调」。
一、第一小时:理论(大白话 + 生活比喻 + 面试坑点)
1.1 什么是「工具」?------ 大模型只是「嘴」,工具才是「手」
大模型本质上是一个只会根据上下文预测下一个词的概率机器。你问它「今天北京天气怎么样」,它可能一本正经地编一个温度------因为它的知识有截止时间,也没有联网、查库、算数的能力。
工具(Tool)就是给模型装上的「手」 :把「查天气」「算乘法」「搜网页」这些确定性能力包装成一个个接口,让模型在需要时「伸出手」调用,而不是瞎编。
生活比喻:把大模型想象成一个博学但被关在房间里的顾问,手上没有手机、没有计算器。你给它一部手机(工具),它才能在需要时打电话出去问天气、上网查资料。工具,就是递给这位顾问的那部手机。
1.2 一个工具到底长什么样?------ 三个关键属性
在 LangChain 里,一个工具本质上就是 一个函数 + 一段元信息。模型真正「看到」的是这三样:
| 属性 | 作用 | 例子 |
|---|---|---|
name |
工具名(模型靠它识别) | add、Get_Weather |
description |
工具是干嘛的(模型靠它决定要不要调) | "两数相加" |
args |
参数结构(JSON Schema) | {"a": "第一个整数", "b": "第二个整数"} |

面试常考坑点① :工具描述(description)写得好不好,直接决定模型会不会「用错工具」。描述太模糊(比如只写"计算"),模型在多工具场景下容易张冠李戴。描述要写清楚「什么情况下该用我」。
1.3 两种定义姿势
姿势一:@tool 装饰器(最常用,简单函数直接用)
python
from langchain_core.tools import tool
from typing_extensions import Annotated
@tool
def multiply(
a: Annotated[int, ..., "第一个整数"],
b: Annotated[int, ..., "第二个整数"]
) -> int:
"""两数相乘。当用户询问乘法计算时使用此工具。"""
return a * b
Annotated[int, ..., "描述"]:给参数加说明,LangChain 会自动提取成argsschema。- 函数 Docstring 自动变成
description。
姿势二:StructuredTool.from_function(函数没有 Docstring,或要精确控制时用)
python
from langchain_core.tools import StructuredTool
from pydantic import BaseModel, Field
class MultiplyInput(BaseModel):
a: int = Field(description="第一个整数")
b: int = Field(description="第二个整数")
def multiply(a: int, b: int) -> int:
return a * b # 注意:没写 Docstring
multiply_tool = StructuredTool.from_function(
func=multiply,
name="Calculator_Multiply", # 强行指定工具名
description="两数相乘", # 强行指定描述
args_schema=MultiplyInput # 用 Pydantic 强制声明参数
)
面试常考坑点② :StructuredTool.from_function 里如果不传 args_schema,工具参数就是空的 ------因为函数没有 Docstring 可解析。这会导致模型调用时不知道要传什么参数 。所以「没写 Docstring 的函数,一定要补 args_schema」。
1.4 调用闭环:模型「提需求」,你「跑腿」
这是最核心、最容易懵 的一张图。很多人以为 bind_tools 之后模型就「自动调用工具并返回结果」了------完全不是。
text
┌─────────────────────────────────────────────────────────────┐
│ 用户提问:"9乘6等于多少?5加3等于多少?" │
└───────────────────────────┬─────────────────────────────────┘
▼
① model_with_tools = model.bind_tools([add, multiply])
把工具「能力清单」塞给模型
▼
② ai_msg = model_with_tools.invoke(messages)
模型返回 AIMessage,里面只有 tool_calls(意图),内容还是空的!
tool_calls = [
{'name':'multiply','args':{'a':9,'b':6},'id':'call_xxx'},
{'name':'add', 'args':{'a':5,'b':3},'id':'call_yyy'},
]
▼
③ 你遍历 tool_calls,本地真正执行工具:
for tc in ai_msg.tool_calls:
tool_msg = tools_map[tc['name']].invoke(tc) # 真正算出 54、8
messages.append(tool_msg) # 拼成 ToolMessage 塞回历史
▼
④ final = model.invoke(messages) # 再把结果喂给模型
模型结合工具结果,生成最终自然语言回答
└─────────────────────────────────────────────────────────────┘

一句话总结闭环 :模型只负责「决定调用哪个工具、传什么参数」,执行永远是你本地代码做的,执行完再把结果喂回去。
面试常考坑点③(最高频) :ToolMessage 必须带 tool_call_id,且要和对应的 tool_calls 里的 id 一一对应。用 tool.invoke(tool_call) 会自动 帮你带上这个 id;但如果你手动 new ToolMessage(...) 却忘了传 tool_call_id,模型会报错或答非所问。
二、第二小时:实战(可跑通核心代码 + 排雷)
完整代码见 Gitee:
pracote-lang-chain--lang-graph/00_旧版程序_Legacy/test_17~20。博客只贴核心逻辑,全部已用 DeepSeek 跑通。
2.1 实战一:@tool 定义工具并查看内部结构
python
# test_17_tool_define.py(核心)
from typing_extensions import Annotated
from langchain_core.tools import tool
@tool
def multiply(
a: Annotated[int, ..., "第一个整数"],
b: Annotated[int, ..., "第二个整数"]
) -> int:
"""两数相乘。当用户询问乘法计算时使用此工具。"""
return a * b
print(f"工具名称: {multiply.name}") # multiply
print(f"工具描述: {multiply.description}") # 两数相乘。当用户询问...
print(f"参数结构: {multiply.args}") # {'a': {'title':..., 'description': '第一个整数'}, ...}
print(f"测试调用: {multiply.invoke({'a': 3, 'b': 4})}") # 12

要点 :工具本身就是一个对象,可以 .name .description .args 直接查看元信息,也可以像普通函数一样 .invoke() 直接调用------这在调试时特别好用。
面试坑点补充 :面试常被追问「tool.name 为什么要见名知意?」------因为除了日志可读,DeepSeek 这类模型在多工具竞争场景下主要靠 name + description 做选择,名字起得含糊(tool1、tool2)会显著降低选对工具的概率。
2.2 实战二:完整调用闭环(DeepSeek)
python
# test_18_tool_binding.py(核心,已用 deepseek-chat 跑通)
import os
from dotenv import load_dotenv
from langchain_openai import ChatOpenAI
from langchain_core.messages import HumanMessage
from langchain_core.tools import tool
load_dotenv()
@tool
def add(a: int, b: int) -> int:
"""两数相加"""
return a + b
@tool
def multiply(a: int, b: int) -> int:
"""两数相乘"""
return a * b
model = ChatOpenAI(
model="deepseek-chat", # DeepSeek 用 OpenAI 兼容接口
api_key=os.getenv("DEEPSEEK_API_KEY"),
base_url="https://api.deepseek.com" # 关键:换 base_url,不用翻墙
)
tools = [add, multiply]
model_with_tools = model.bind_tools(tools) # ① 绑定
messages = [HumanMessage(content="9乘6等于多少?5加3等于多少?")]
ai_msg = model_with_tools.invoke(messages) # ② 模型返回调用意图
messages.append(ai_msg)
tools_map = {"add": add, "multiply": multiply}
for tc in ai_msg.tool_calls: # ③ 本地执行
tool_msg = tools_map[tc["name"].lower()].invoke(tc)
messages.append(tool_msg)
final = model.invoke(messages) # ④ 生成最终答案
print(final.content)
# 输出:9乘6等于54,5加3等于8。
核心观察 :bind_tools 之后模型第一次返回的 ai_msg.content 是空的 ,真正的信息全在 ai_msg.tool_calls 里。所以你必须手动执行工具、手动把 ToolMessage 拼回历史,模型第二次调用才会吐出最终答案。
2.3 实战三:StructuredTool 三种进阶用法
python
# test_19_structured_tool.py(核心)
from typing import Tuple
from langchain_core.tools import StructuredTool
from pydantic import BaseModel, Field
# 用法1:直接包装现成函数(靠函数签名 + Docstring)
def add(a: int, b: int) -> int:
"""两数相加"""
return a + b
add_tool = StructuredTool.from_function(func=add)
# 用法2:无 Docstring 时,用 Pydantic 强制声明参数
class MultiplyInput(BaseModel):
a: int = Field(description="第一个整数")
b: int = Field(description="第二个整数")
def multiply(a: int, b: int) -> int:
return a * b # 无 Docstring
multiply_tool = StructuredTool.from_function(
func=multiply, name="Calculator_Multiply",
description="两数相乘", args_schema=MultiplyInput
)
# 用法3:content_and_artifact ------ 分离「给模型看的文本」和「给代码用的原始数据」
def get_weather(city: str) -> Tuple[str, dict]:
raw_data = {"city": city, "temp": 25, "humidity": 60}
content = f"{city}今天天气晴朗,气温 25 度。" # 给 LLM 看
return content, raw_data # 原始数据给代码用
weather_tool = StructuredTool.from_function(
func=get_weather, name="Get_Weather",
description="查询指定城市的天气",
response_format="content_and_artifact" # 核心配置
)
result = weather_tool.invoke({
"name": "Get_Weather", "args": {"city": "西安"},
"id": "call_123", "type": "tool_call" # id 必填,用于关联
})
print(result.content) # 西安今天天气晴朗,气温 25 度。
print(result.artifact) # {'city':'西安','temp':25,'humidity':60}
要点 :content_and_artifact 很实用------当工具返回的原始数据又大又乱 (比如一堆 JSON),你可以只把「一句话总结」发给模型,把原始数据留在 artifact 里给后续代码用,既省 token 又干净。
2.4 实战四:第三方工具 TavilySearch 联网搜索
python
# test_20_tavily_search.py(核心)
from langchain_openai import ChatOpenAI
from langchain_core.messages import HumanMessage
from langchain_tavily import TavilySearch
model = ChatOpenAI(
model="deepseek-chat",
api_key=os.getenv("DEEPSEEK_API_KEY"),
base_url="https://api.deepseek.com"
)
tool = TavilySearch(max_results=4) # 第三方工具,底层自动读 TAVILY_API_KEY
model_with_tools = model.bind_tools([tool])
messages = [HumanMessage("最近人工智能领域有什么最新的重磅新闻?")]
ai_msg = model_with_tools.invoke(messages) # 模型决定「去搜索」
messages.append(ai_msg)
for tc in ai_msg.tool_calls: # 本地执行搜索
tool_message = tool.invoke(tc)
messages.append(tool_message)
final = model_with_tools.invoke(messages) # 模型总结搜索结果
print(final.content)
要点 :第三方工具(TavilySearch)用起来和自定义工具完全一样的调用闭环 ------这就是 LangChain 工具抽象的价值:不管工具内部多复杂,对外都是「名字 + 参数 + invoke」。
三、踩坑排查(实战排雷点)
| 症状 | 根因 | 解决 |
|---|---|---|
KeyError: 'add' |
tools_map[tc["name"]] 用了大写 key,但工具名可能是小写 |
建 map 时统一 .lower(),或直接 tool.invoke(tc) 传整个 tool_call |
模型返回的 content 是空的 |
正常现象!工具调用时信息在 tool_calls,不在 content |
别慌,去读 ai_msg.tool_calls |
| 模型报错「tool_call_id 不匹配」 | 手动构造 ToolMessage 没带 tool_call_id |
用 tool.invoke(tool_call) 自动带 id,或手动传 tool_call_id=tc["id"] |
| 工具参数是空的,模型不知道传啥 | 函数没 Docstring,又没传 args_schema |
StructuredTool.from_function 时补 args_schema |
| 联网搜索没反应 | .env 里没配 TAVILY_API_KEY |
去 tavily.com 注册拿 key,写进 .env |
| 想用 DeepSeek 却连不上 | base_url 没改,默认指向 OpenAI |
ChatOpenAI(..., base_url="https://api.deepseek.com") |
DEEPSEEK_API_KEY 读不到 |
.env 没放对位置,或没 load_dotenv() |
确认 .env 与脚本同目录,脚本开头 load_dotenv() |
⚠️ 关键提醒:
.env文件务必加入.gitignore,千万别把 API Key 提交到 Gitee 公开仓库 (我的.gitignore已配好*.env忽略规则)。
四、本篇小结
- 工具 = 函数 + 元信息(name/description/args),给模型装上「手」。
- 定义:简单用
@tool,精确用StructuredTool.from_function。 - 闭环:
bind_tools→ 模型返回tool_calls(只有意图)→ 你本地invoke执行 → 拼ToolMessage喂回 → 模型出最终答案。 - 高级:
content_and_artifact分离展示与数据;第三方工具(Tavily)与自定义工具共用同一套闭环。
五、下一篇预告
搞懂了「工具」这个单体能力,下一篇(10)我们把它装进 Agent ------让模型自主决定调用哪个工具、调用几次、什么时候停,并理解 Agent 里的「消息上下文隔离」到底隔离了什么。
完整代码已上传 Gitee :test_17_tool_define.py / test_18_tool_binding.py / test_19_structured_tool.py / test_20_tavily_search.py