[LangChain] 学习笔记(09):工具(Tool)定义与调用闭环 · 理论+实战完整版

LangChain 学习笔记(09):工具(Tool)定义与调用闭环

📌 TL;DR(先看结论)

  1. 工具(Tool)就是「给大模型装上的手脚」 :大模型只会「说话」,不会「做事」。你用一个 Python 函数 + 一段描述,就把它包装成模型能识别、能调用的「工具」。模型判断该调用哪个工具时,只返回工具名 + 参数 (tool_calls),真正的执行还是你本地代码做的。
  2. 定义工具有两种主流姿势 :@tool 装饰器(简单函数直接用,靠 Docstring 自动生成参数描述)和 StructuredTool.from_function(没有 Docstring 或要精确控制时用 Pydantic 强制声明参数 schema)。一句话:简单用 @tool,精确用 StructuredTool。
  3. 调用闭环三步走(务必背下来) :① 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 会自动提取成 args schema。
  • 函数 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

相关推荐
个 人 练 习 生14 分钟前
C++:从零基础到深入了解vector的使用
开发语言·c++·经验分享·学习·程序人生·stl
Rabitebla2 小时前
【Linux操作系统】 文件篇(一):文件描述符与 Linux 文件管理机制
linux·网络·c++·笔记·学习
Flying Bear4 小时前
Keithley 2450 SourceMeter源表上位机开发笔记
笔记·单片机·嵌入式硬件
旖旎夜光4 小时前
【C++ 基础入门】智能指针:RAII、unique_ptr 与 shared_ptr 循环引用
c++·笔记·学习·智能指针
饮水桶_T5 小时前
Python 面向对象(十七)|继承、封装、多态 笔记
数据结构·笔记·算法
星恒随风6 小时前
MySQL 从零入门(十):MVCC、Undo Log 与 Read View 详解——InnoDB 如何实现事务隔离?
linux·数据库·笔记·sql·mysql
zdr尽职尽责7 小时前
终端工具凭空消失:Codex + GPT-6 的一次完整排障复盘
数据库·gpt·学习·ai
蒸蒸yyyyzwd8 小时前
计算机网络后端面试错题
笔记·学习
艾莉丝努力练剑9 小时前
【AI大模型接入SDK】C++的SessionManager 线程安全
java·开发语言·前端·c++·人工智能·学习·安全