11 · 工具调用：让模型从”会说话”到”会动手”

本片目标：让模型在回答中”调用你提供的工具”——用 @tool 定义工具、bind_tools 让模型知道有工具可用、手动执行循环把结果塞回。全程不用 agent、不用 LangGraph、不用弃用包。 新增规定性：11（工具调用协议：tool_calls / ToolMessage + 手动执行循环） 数据字典：StructuredTool / ToolCall / ToolMessage / bind_tools（内部是 RunnableBinding）。 进程线程模型：一次工具问答 = 多次模型调用串行（声明 → 执行 → 再问），工具本身跑在主线程。 网络模型：模型调用是网络请求；工具若是本地函数则 0 网络，若是查外部 API 则多一次 HTTP。

1. 上集回顾

第 10 篇 RAG 能回答文档问题了。但有个天花板：

RAG 是”只读”的——模型从资料里找答案、念给你听。但”转正答辩还有几天？“这种问题，手册里没有现成答案，得算出来。

你当然可以写死：答案 = 答辩日 - 今天。但用户问法千变万化（“我 10 月 1 号答辩，来得及准备吗？”），写死永远跟不上。 真正的解法：让模型在回答时调用你写的函数——这就是工具调用（Tool Calling）。模型负责”理解问题 → 决定调哪个工具 → 填好参数”，你负责”执行函数 → 把结果喂回去 → 模型组织成答案”。 关键认知：工具 ≠ agent。agent 是”模型自主循环调用工具直到完成任务”的框架（LangGraph 那套）。工具调用是更底层的协议——bind_tools + 手动循环就能实现，完全不用 agent。

2. 数据字典：四个主角

2.1 `@tool` 装饰器（把函数变成工具）

from langchain_core.tools import tool
from datetime import date

@tool
def days_until(target_date: str) -> int:
    """计算今天到目标日期还有几天（YYYY-MM-DD 格式）。"""
    target = date.fromisoformat(target_date)
    return (target - date.today()).days

@tool 自动从函数签名 + docstring 生成三样东西（实测）：

属性	值	来源
`days_until.name`	`"days_until"`	函数名
`days_until.description`	`"计算今天到目标日期还有几天（YYYY-MM-DD 格式）。"`	docstring
`days_until.args`	`{'target_date': {'type': 'string'}}`	函数参数类型

为什么 docstring 必须写清楚：模型靠 description 决定”什么时候该用这个工具”。写”计算两个日期差几天”比写”算天数”好——模型理解得越准，调用越对。

2.2 `bind_tools`（让模型知道有工具可用）

model_with_tools = model.bind_tools([days_until])

内部结构（实测）：bind_tools 返回的是 _ChatModelBinding——它是 RunnableBinding 的子类，本质是**“原模型 + 额外参数”的绑定层**：

_ChatModelBinding (实测 MRO)
 └─ RunnableBinding → RunnableBindingBase → RunnableSerializable
      ├─ .bound = 原模型（ChatAnthropic）     ← 真正的模型还在里面
      └─ .kwargs = {"tools": [工具 schema]}    ← 绑定的工具存在这

它干了三件事：

把工具列表 [days_until] 转成模型厂商要的 tools schema（Anthropic/OpenAI 协议格式）；
存进 kwargs，每次请求自动带上；
返回一个”绑定后的模型”——invoke() 的返回类型不变，还是 AIMessage，只是这个 AIMessage 可能带 tool_calls 而不是普通文本。

bind_tools 返回一个绑定了工具 schema 的模型绑定。之后调用它，模型在需要时返回 tool_calls 而不是普通回答：

resp = model_with_tools.invoke("今天 2026-08-05，距离 2026-10-01 转正答辩还有几天？")
resp.tool_calls
# → [{'name': 'days_until', 'args': {'target_date': '2026-10-01'}, 'id': 'tool-...'}]

2.3 `ToolCall`（模型声明的数据结构）

字段	类型	说明
`name`	`str`	要调用的工具名（必须是你 bind 过的）
`args`	`dict`	参数（模型根据你的 schema 填的）
`id`	`str`	调用唯一标识（后面 `ToolMessage` 靠它配对）

注意：模型只”声明”要调工具，不执行。执行是你的责任——这就是”手动”的含义。

2.4 `ToolMessage`（工具执行结果回传）

from langchain_core.messages import ToolMessage

messages.append(ToolMessage(
    content=str(result),      # 执行结果（必须是字符串）
    tool_call_id=tc["id"],    # ← 必须匹配 tool_calls 里的 id！
    name=tc["name"],
))

tool_call_id 是配对的钥匙：模型靠它知道”这个结果是对应我刚才哪次调用”。

3. 手动执行循环（核心代码）

def run_with_tools(question: str):
    messages = [("human", question)]
    model_calls = 0
    for turn in range(3):                  # 最多 3 轮，防死循环
        resp = model_with_tools.invoke(messages)
        model_calls += 1
        messages.append(resp)

        if not resp.tool_calls:            # 模型不再要工具 → 回答完成
            return resp.content, model_calls

        for tc in resp.tool_calls:         # 手动执行每个工具
            result = days_until.invoke(tc["args"])
            messages.append(ToolMessage(
                content=str(result),
                tool_call_id=tc["id"],
                name=tc["name"],
            ))
    return "（达到最大轮数，手动中断）", model_calls

answer, n = run_with_tools("今天 2026-08-05，还有几天到 2026-10-01 的转正答辩？")
# → "还有 57 天。"（模型算的，不是编的）共 2 次模型调用

循环三步（和记忆的”取历史→拼消息→写回”一样是固定骨架）：

用户问题 → 模型(带工具) → 返回 tool_calls？
    ├─ 否 → 这就是最终回答 ✅
    └─ 是 → 手动执行工具 → ToolMessage 塞回 → 再问模型（回到起点）

为什么不是 agent：循环是你写的 for，不是框架自动的。你控制轮数上限（防死循环）、决定执行哪些工具（白名单）、处理失败（try/except）。主动权在你——这正是本系列”不用 agent 也能做生产级”的哲学。

3.5 工具消息必须留在历史里（关键认知）

第 2 次调用前，messages 里实际装着什么（实测，2026-08）：

[human]  "今天 2026-08-05，还有几天到 2026-10-01 的转正答辩？"   ← 你最初的问题
[ai]     AIMessage(tool_calls=[{name: days_until, args: {...}, id: tool-6b0...}])  ← 模型第 1 次的"我要调工具"声明
[tool]   ToolMessage(content="56", tool_call_id=tool-6b0..., name=days_until)  ← 工具执行结果

为什么这三条缺一不可：模型第 2 次请求时，它看到的完整对话就是上面这三连。它靠：

AIMessage.tool_calls 里的 id 记住”我上次说要调 days_until 这个工具”；
ToolMessage.tool_call_id 认出”这个 56 就是那次调用的结果”；
两者配对后，它才能组织出最终回答：“还有 56 天。”

如果不把工具消息加进历史（比如只把结果 56 直接当新消息发），模型会”失忆”——它不知道这个 56 是干嘛的，甚至可能当成用户说的话。工具调用循环 = 记忆在”一轮对话内部”的微缩版（呼应第 06 篇）：模型声明 → 执行结果 → 最终回答，都是同一条消息链上的环节，必须全部保留。

配对失败会怎样：如果 ToolMessage.tool_call_id 对不上任何 tool_calls 里的 id，模型会报错或把工具结果当无效输入。所以 tool_call_id 一定要从 tc["id"] 原样抄过来，不能自己编。

4. 关键方法

方法	签名	说明
`@tool`	装饰器	函数 → StructuredTool（name/description/args 自动生成）
`tool.invoke(args)`	`(dict) -> Any`	直接执行工具（测试用）
`model.bind_tools(tools)`	`(list) -> _ChatModelBinding`	绑定工具 schema 到模型（内部 = RunnableBinding，`invoke` 仍返回 AIMessage）
`resp.tool_calls`	`-> list[ToolCall]`	模型的工具声明（name/args/id）
`ToolMessage(content, tool_call_id, name)`	构造	回传执行结果（`tool_call_id` 必须匹配 `tool_calls` 里的 id）

5. 进程线程模型

run_with_tools("还有几天到转正答辩？")
  ├─ 模型调用 #1（网络阻塞 1~3s）→ 返回 tool_calls
  ├─ days_until.invoke(...)（本地纯计算，~0ms）    ← 工具执行在主线程
  ├─ 模型调用 #2（网络阻塞 1~3s）→ 返回最终回答

每次工具调用 = 多一次模型往返。1 个工具 = 2 次模型调用，延迟 ≈ 2 倍单次问答。
工具是本地函数 → 主线程直接跑；工具查外部 API → 也是网络阻塞（和模型调用同性质）。
高并发下多个工具调用可并行（RunnableParallel，第 12 篇讲），但要注意工具是否有副作用（如写库）。

6. 网络模型

用户 → POST /v1/messages（带 tools schema + 问题）
     ← tool_calls: {name: days_until, args: {...}}
  → 本地执行 days_until（0 网络）
用户 → POST /v1/messages（历史 + ToolMessage 结果）
     ← 最终回答

本质：工具调用是两次标准模型请求。第一次请求里多带了一份”工具说明书”（schema），模型选择要不要用；第二次请求把工具结果当普通消息发给模型。没有新协议。

7. 验证：跑起来

配套代码 code/11_tools.py（七幕）：

@tool 定义工具，打印 name/description/args（看工具的数据字典）；
bind_tools 后问一个需要算日期的问题，看模型返回 tool_calls 的结构；
手动执行循环：模型声明 → 执行 → ToolMessage 塞回 → 最终回答；
工具 vs RAG 分工对比；
多工具：两个工具（days_until/days_since），看模型按语义选哪个；
失败重试：multiply 触发安全限制报错，看模型自我纠正；
边界。

cd enterprise-rag-course\code
python 11_tools.py

预期输出（节选，实测）：

===== ① @tool =====
工具名: days_until
参数 schema: {'target_date': {'title': 'Target Date', 'type': 'string'}}

===== ② bind_tools =====
tool_calls[0]:
  name = days_until
  args = {'target_date': '2026-10-01'}
  id   = tool-05d72c1bdf4b472595132cd5b7b1067d

===== ③ 手动循环 =====
  [执行工具] days_until({'target_date': '2026-10-01'}) → 57
模型最终回答: 距离 2026-10-01 的转正答辩还有 57 天。
共 2 次模型调用 ← 工具让模型'动手算'，而不是瞎编数字

7.5 进阶：多工具与失败重试

多工具：模型自己选

bind_tools 接受多个工具，模型按问题语义挑对的：

@tool
def days_until(target_date: str) -> int:
    """计算今天到目标日期还有几天（YYYY-MM-DD 格式）。"""
    ...

@tool
def days_since(start_date: str) -> int:
    """计算今天到指定日期已经过了多少天（YYYY-MM-DD 格式，用于倒推已用时）。"""
    ...

multi_model = model.bind_tools([days_until, days_since])

r = multi_model.invoke("入职 2026-06-01，到今天培训了多少天？")
r.tool_calls   # → [{'name': 'days_since', 'args': {'start_date': '2026-06-01'}, 'id': '...'}]
# 模型选了 days_since（算已过天数），不是 days_until（算未来天数）——描述写清楚它就能选对

实测：两个工具描述都写清楚用途，模型问”培训了多少天”就选 days_since，问”还有几天答辩”就选 days_until。工具描述（docstring）是模型选工具的”说明书”——描述含糊，模型就会选错。

失败重试：工具报错，模型自我纠正

工具抛异常不中断对话——把错误信息作为 ToolMessage 塞回去，模型自己调整：

@tool
def multiply(a: float, b: float) -> float:
    """乘法运算。结果绝对值超过 1 亿时报错（模拟生产安全限制）。"""
    result = a * b
    if abs(result) > 100_000_000:
        raise ValueError("结果超出允许范围（1 亿），请缩小数值或换个算法")
    return result

# 手动循环里包一层 try/except：
for tc in resp.tool_calls:
    try:
        content = str(multiply.invoke(tc["args"]))
    except ValueError as e:
        content = f"工具执行失败: {e}"   # ← 错误也走 ToolMessage
    messages.append(ToolMessage(content=content, tool_call_id=tc["id"], name=tc["name"]))

实测（问”123456 × 789012 =？“，结果超 1 亿触发报错）：

工具报错: 结果超出允许范围（1 亿），请缩小数值或换个算法
模型收到错误后: 抱歉，无法直接计算，因为计算结果超出了允许的范围（1 亿）。
  不过我可以帮您分析一下：123456 是 6 位数...

要点：错误信息要说清楚问题 + 给可操作的纠正建议（“请缩小数值”）。模型靠这句决定下一步——信息含糊，它只会重复同样的错误。

8. 边界

工具声明要花 token——工具 schema 每次请求都带上，工具越多、描述越长越贵。
模型可能调错参数——args 是模型猜的。生产环境要在执行前校验（args 类型检查），失败就返回错误信息给模型让它重试。
工具结果也进上下文——工具返回超长内容会爆上下文，工具函数要控制返回长度。
安全红线——别让模型调有副作用的工具（删除、写库、发邮件）。生产用白名单：只 bind 你允许的工具，且工具内部做权限校验。
tool_calls 为空的回答——模型不一定每次都调工具，它可能直接回答。这是正常行为，你的循环要能处理”没有 tool_calls”的情况（就是上面的 if not resp.tool_calls）。

9. 未完待续

模型现在能”动手”了——但这引出一个生产级问题：

一次工具问答 = 多次模型调用（1 工具 = 2 次）。如果 100 个用户同时这么问，每个请求都阻塞 1~3 秒，你的服务扛得住吗？

这就是第 12 篇：并发与网络模型——把 LangChain 的调度机制（线程池、事件循环、HTTP 连接）彻底拆开看。 → 12 · 并发与网络模型

RAG 教程

小林学 LangChain

11 · 工具调用：让模型从"会说话"到"会动手"

11 · 工具调用：让模型从”会说话”到”会动手”

1. 上集回顾

2. 数据字典：四个主角

2.1 `@tool` 装饰器（把函数变成工具）

2.2 `bind_tools`（让模型知道有工具可用）

2.3 `ToolCall`（模型声明的数据结构）

2.4 `ToolMessage`（工具执行结果回传）

3. 手动执行循环（核心代码）

3.5 工具消息必须留在历史里（关键认知）

4. 关键方法

5. 进程线程模型

6. 网络模型

7. 验证：跑起来

7.5 进阶：多工具与失败重试

多工具：模型自己选

失败重试：工具报错，模型自我纠正

8. 边界

推荐资料（延伸阅读）

9. 未完待续

​11 · 工具调用：让模型从”会说话”到”会动手”

​1. 上集回顾

​2. 数据字典：四个主角

​2.1 @tool 装饰器（把函数变成工具）

​2.2 bind_tools（让模型知道有工具可用）

​2.3 ToolCall（模型声明的数据结构）

​2.4 ToolMessage（工具执行结果回传）

​3. 手动执行循环（核心代码）

​3.5 工具消息必须留在历史里（关键认知）

​4. 关键方法

​5. 进程线程模型

​6. 网络模型

​7. 验证：跑起来

​7.5 进阶：多工具与失败重试

​多工具：模型自己选

​失败重试：工具报错，模型自我纠正

​8. 边界

​推荐资料（延伸阅读）

​9. 未完待续

11 · 工具调用：让模型从”会说话”到”会动手”

1. 上集回顾

2. 数据字典：四个主角

2.1 `@tool` 装饰器（把函数变成工具）

2.2 `bind_tools`（让模型知道有工具可用）

2.3 `ToolCall`（模型声明的数据结构）

2.4 `ToolMessage`（工具执行结果回传）

3. 手动执行循环（核心代码）

3.5 工具消息必须留在历史里（关键认知）

4. 关键方法

5. 进程线程模型

6. 网络模型

7. 验证：跑起来

7.5 进阶：多工具与失败重试

多工具：模型自己选

失败重试：工具报错，模型自我纠正

8. 边界

推荐资料（延伸阅读）

9. 未完待续