深入浅出 LangGraph —— 第6章：工具调用与ToolNode

📖 本章学习目标

• ✅ 理解 LLM 工具调用(Function Calling)的工作机制
• ✅ 掌握使用 tool() 函数定义类型安全的工具
• ✅ 学会使用 ToolNode 预构建节点简化工具集成
• ✅ 构建完整的 ReAct Agent(推理→行动→观察循环)
• ✅ 掌握工具调用的错误处理和超时机制
• ✅ 避免常见的工具设计陷阱和性能问题

---

一、工具调用：让 AI 能"动手"

1、什么是工具调用

大语言模型本身只能"说话"——接受文本输入,生成文本输出。工具调用(Tool Calling,也叫 Function Calling)让 LLM 能够:

• 🔍 搜索:调用搜索 API 获取实时信息
• 🧮 计算:调用计算工具处理数学问题
• 📁 操作文件:读写本地文件系统
• 🌐 调用 API:与第三方服务交互
• 🗄️ 查询数据库:获取结构化数据

工具调用就像给 AI 配备了"工具箱"。AI 本身是大脑,工具是手和脚,两者结合才能真正完成任务。

传统LLM vs 工具增强LLM对比:

2、工具调用流程

完整工作流程详解:

1. 用户输入:用户提出问题或任务
2. LLM推理:LLM分析问题,判断是否需要调用工具
3. 工具调用:如果需要,LLM生成工具调用请求(tool_calls)
4. 工具执行:ToolNode解析并执行工具,返回结果
5. 结果整合:工具结果作为消息返回给LLM
6. 最终回复:LLM基于工具结果生成最终回答

---

二、定义工具

1、使用 tool() 函数

LangChain 提供了 tool() 函数,结合 Zod 定义类型安全的工具:

步骤1:导入依赖

import { tool } from '@langchain/core/tools';
import { z } from 'zod';

步骤2:定义简单工具

// 定义一个天气查询工具
const getWeatherTool = tool(
  async ({ city }) => {
    // 实际项目中这里调用真实的天气 API
    const mockData: Record<string, string> = {
      '北京': '晴天,25°C,东南风3级',
      '上海': '多云,22°C,东风2级',
    };
    return mockData[city] ?? `暂无 ${city} 的天气数据`;
  },
  {
    name: 'get_weather',
    description: '获取指定城市的实时天气信息',
    schema: z.object({
      city: z.string().describe('城市名称,如:北京、上海'),
    }),
  }
);

tool(fn, config)第一参数是工具的执行函数,第二参数是配置

• name:工具名称(LLM 通过此名称调用工具,建议用下划线命名)
• description:工具描述(LLM 根据此描述决定何时调用该工具,要写清楚)
• schema:Zod 定义的参数结构,LLM 会按此格式传参
• describe():为每个参数添加说明,帮助 LLM 理解参数含义

重要原则:

1. name 必须唯一,只使用字母、数字和下划线
2. description 要详细说明工具的用途和适用场景
3. schema 要严格定义参数类型,提高LLM调用准确率

2、定义多参数工具

const calculatorTool = tool(
  async ({ operation, a, b }) => {
    switch (operation) {
      case 'add': return `${a + b}`;
      case 'subtract': return `${a - b}`;
      case 'multiply': return `${a * b}`;
      case 'divide':
        if (b === 0) return '错误:除数不能为零';
        return `${a / b}`;
      default:
        return '不支持的运算';
    }
  },
  {
    name: 'calculator',
    description: '执行基本的数学运算(加减乘除)',
    schema: z.object({
      operation: z.enum(['add', 'subtract', 'multiply', 'divide'])
        .describe('运算类型'),
      a: z.number().describe('第一个数字'),
      b: z.number().describe('第二个数字'),
    }),
  }
);

3、定义复杂工具

// 数据库查询工具
const databaseQueryTool = tool(
  async ({ table, filters, fields }) => {
    try {
      // 模拟数据库查询
      const results = await mockDatabase.query(table, filters, fields);
      return JSON.stringify(results, null, 2);
    } catch (error) {
      return `查询失败: ${error instanceof Error ? error.message : '未知错误'}`;
    }
  },
  {
    name: 'query_database',
    description: '查询数据库中的记录,支持过滤和字段选择',
    schema: z.object({
      table: z.enum(['users', 'orders', 'products'])
        .describe('要查询的表名'),
      filters: z.record(z.string(), z.any())
        .describe('过滤条件,key-value对')
        .optional(),
      fields: z.array(z.string())
        .describe('要返回的字段列表')
        .optional(),
    }),
  }
);

• 复杂工具可以包含可选参数(.optional())
• 内部做好错误捕获,返回错误描述而非抛出异常
• 返回JSON字符串便于LLM解析结构化数据
• z.enum限制可查询的表,防止SQL注入风险

---

三、ToolNode：预构建工具节点

1、ToolNode 的作用

ToolNode 是 LangGraph 预构建的节点,它自动:

1. 解析 LLM 消息中的工具调用请求
2. 并行执行所有被调用的工具
3. 将工具结果包装成 ToolMessage 返回

import { ToolNode } from '@langchain/langgraph/prebuilt';

const tools = [getWeatherTool, calculatorTool];
const toolNode = new ToolNode(tools);

• ToolNode(tools):传入工具数组,创建工具执行节点
• ToolNode 自动处理工具调用的并发执行(多个工具同时调用时)
• 如果 LLM 没有调用工具,ToolNode 什么都不做

工作原理:

1. 接收包含tool_calls的AIMessage
2. 解析每个tool_call的名称和参数
3. 查找对应的工具并执行
4. 将结果封装为ToolMessage
5. 返回ToolMessage数组

2、构建完整的工具调用图

步骤1:绑定工具到模型

import { MessagesAnnotation, StateGraph } from '@langchain/langgraph';
import { ChatOpenAI } from '@langchain/openai';
import { HumanMessage, AIMessage } from '@langchain/core/messages';

const model = new ChatOpenAI({ model: 'gpt-4o-mini' });
// 将工具绑定到模型(告诉 LLM 有哪些工具可用)
const modelWithTools = model.bindTools(tools);

bindTools(tools)将工具列表绑定到模型，这会在系统层面告知LLM可用的工具及其schema。 LLM会根据问题决定是否调用工具以及调用哪个工具。必须在创建agent节点前完成绑定。

步骤2:定义Agent节点

// Agent 节点:调用绑定了工具的 LLM
async function agentNode(state: typeof MessagesAnnotation.State) {
  const response = await modelWithTools.invoke(state.messages);
  return { messages: [response] };
}

agentNode是核心推理节点,调用LLM生成回复。state.messages包含完整的对话历史，返回的{messages: [response]}会追加新消息到对话历史。 LLM可能返回普通AIMessage或带tool_calls的AIMessage。

步骤3:定义路由函数

// 路由函数:检查是否需要调用工具
function shouldUseTool(state: typeof MessagesAnnotation.State): string {
  const lastMsg = state.messages[state.messages.length - 1] as AIMessage;
  if (lastMsg.tool_calls && lastMsg.tool_calls.length > 0) {
    return 'tools';
  }
  return '__end__';
}

检查最后一条消息是否包含tool_calls字段，如果有工具调用,路由到’tools’节点执行,否则直接结束(‘end’)， 这是标准的工具调用路由模式。

步骤4:构建图

const agentGraph = new StateGraph(MessagesAnnotation)
  .addNode('agent', agentNode)
  .addNode('tools', toolNode)
  .addEdge('__start__', 'agent')
  .addConditionalEdges('agent', shouldUseTool)
  // 工具执行完后,把结果返回给 agent 继续推理
  .addEdge('tools', 'agent')
  .compile();

执行流程: start → agent → (有tool_calls?) → tools → agent → … → end

完整流程图:

---

四、ReAct Agent 完整实现

1、ReAct 模式解析

ReAct(Reasoning + Acting)是最经典的 Agent 模式:

ReAct 循环详解:

1. Reasoning(推理):LLM分析问题,决定下一步行动
2. Acting(行动):如果需要,调用工具执行具体任务
3. Observation(观察):获取工具执行结果
4. 循环:回到推理阶段,基于新信息继续决策
5. 终止:当LLM认为任务完成时,输出最终答案

2、带搜索功能的完整 ReAct Agent

步骤1:定义工具集

import * as dotenv from 'dotenv';
dotenv.config();

import { tool } from '@langchain/core/tools';
import { z } from 'zod';
import { ToolNode } from '@langchain/langgraph/prebuilt';
import { MessagesAnnotation, StateGraph } from '@langchain/langgraph';
import { ChatOpenAI } from '@langchain/openai';
import { HumanMessage, AIMessage } from '@langchain/core/messages';

// 工具1:网页搜索(模拟)
const searchTool = tool(
  async ({ query }) => {
    console.log(`🔍 正在搜索: ${query}`);
    return `搜索"${query}"的结果:这是模拟的搜索结果,包含相关信息...`;
  },
  {
    name: 'web_search',
    description: '搜索互联网获取最新信息,适用于需要实时数据的问题',
    schema: z.object({ query: z.string().describe('搜索关键词') }),
  }
);

// 工具2:代码执行(模拟)
const codeRunnerTool = tool(
  async ({ code }) => {
    console.log(`💻 执行代码: ${code}`);
    // 实际项目中这里可以对接真实的代码执行沙箱
    return `代码执行成功,输出:42`;
  },
  {
    name: 'run_code',
    description: '执行 JavaScript 代码片段并返回结果',
    schema: z.object({ code: z.string().describe('要执行的 JS 代码') }),
  }
);

*定义若干个工具，每个工具都有清晰的name、description和schema。description详细说明适用场景,帮助LLM正确选择工具（实际项目中应该替换为真实的API调用）。

步骤2:组装ReAct Agent

// 所有可用工具的数组
const allTools = [searchTool, calculatorTool, codeRunnerTool];
// 绑定工具后的LLM实例
const reactModel = new ChatOpenAI({ model: 'gpt-4o-mini' })
  .bindTools(allTools);

// 推理节点,调用LLM
async function reactAgentNode(state: typeof MessagesAnnotation.State) {
  const response = await reactModel.invoke(state.messages);
  return { messages: [response] };
}

// 路由函数,检查是否有tool_calls
function reactRouter(state: typeof MessagesAnnotation.State): string {
  const last = state.messages[state.messages.length - 1] as AIMessage;
  return last.tool_calls?.length ? 'tools' : '__end__';
}

步骤3:构建并运行

const reactGraph = new StateGraph(MessagesAnnotation)
  .addNode('agent', reactAgentNode)
  .addNode('tools', new ToolNode(allTools))
  .addEdge('__start__', 'agent')
  .addConditionalEdges('agent', reactRouter)
  .addEdge('tools', 'agent')
  .compile();

async function main() {
  const result = await reactGraph.invoke({
    messages: [new HumanMessage('请搜索一下 LangGraph 的最新版本,然后计算 123 × 456')],
  });
  
  const finalMsg = result.messages[result.messages.length - 1] as AIMessage;
  console.log('\n🤖 最终回复:\n', finalMsg.content);
}

main().catch(console.error);

留意上述构建图时的节点和边，tools节点运行后会连接agent节点，实现调用工具后重新推理，这是标准的ReAct Agent实现模式。

运行结果示例:

🔍 正在搜索: LangGraph latest version
💻 执行代码: 123 * 456

🤖 最终回复:
LangGraph 的最新版本是 0.2.0。
123 × 456 = 56088

执行过程追踪:

---

五、工具错误处理

1、工具级别的错误处理

工具的调用可能会发生异常。在工具内部捕获错误并返回错误描述字符串(而非抛出异常)，LLM 收到错误信息后,可以决定换一种方式处理。如果工具抛出异常,ToolNode 默认会让其传播,导致图失败。

const robustSearchTool = tool(
  async ({ query }) => {
    try {
      const result = await realSearchAPI(query);
      return result;
    } catch (error) {
      // 工具返回错误描述,让 LLM 知道工具失败了
      return `搜索失败:${error instanceof Error ? error.message : '未知错误'}。请尝试其他方式。`;
    }
  },
  { 
    name: 'search', 
    description: '搜索网络信息', 
    schema: z.object({ query: z.string() }) 
  }
);

错误处理策略:

1. 捕获所有异常,转换为友好提示
2. 提供重试建议
3. 保持返回类型为string

2、ToolNode 的错误回退配置

import { ToolNode } from '@langchain/langgraph/prebuilt';

// 配置错误处理:工具失败时返回错误消息而非抛出异常
const safeToolNode = new ToolNode(tools, {
  handleToolErrors: true, // 默认为 true:工具错误被捕获并作为 ToolMessage 返回
});

handleToolErrors这是为true（默认）,会在工具执行异常时,返回包含错误信息的 ToolMessage。LLM 收到错误 ToolMessage 后,可以重试或换策略。设为 false 则错误会直接抛出,让图整体失败。

两种模式对比:

• true: 容错性强,LLM可自行处理错误
• false: 严格模式,适合关键任务需要立即失败的场景

3、超时控制

工具的调用可能还会发生超时，我们不能让工具一直处于调用状态，因此通常需要在工具超时调用时取消调用或做其它的容错处理。

生产环境必须设置超时,防止工具长时间挂起。

const timeoutSearchTool = tool(
  async ({ query }) => {
    //  AbortController:浏览器/Node.js标准的取消请求机制
    const controller = new AbortController();
    // setTimeout设置5秒超时, 超时时触发abort,捕获AbortError
    const timeoutId = setTimeout(() => controller.abort(), 5000);
    
    try {
      const response = await fetch(`https://api.search.com?q=${query}`, {
        signal: controller.signal,
      });
      // 走到这里说明没有超时，取消超时限制
      clearTimeout(timeoutId);
      return await response.text();
    } catch (error) {
      if (error.name === 'AbortError') {
        return '搜索超时,请稍后重试';
      }
      return `搜索失败: ${error.message}`;
    }
  },
  {
    name: 'timeout_search',
    description: '带超时控制的搜索工具',
    schema: z.object({ query: z.string() }),
  }
);

---

六、最佳实践和踩坑指南

💡 实践 1:工具描述要精准

❌ 模糊的描述:

{ description: '获取信息' }  // LLM 不知道该什么时候用

✅ 精准的描述:

{
  description: '搜索互联网获取实时信息。当用户询问最新事件、' +
               '当前数据或需要查证的事实时使用。不适用于通用知识问题。'
}

原因:描述是 LLM 决定是否调用工具的唯一依据,越精准工具利用率越高。

💡 实践 2:工具幂等性设计

✅ 确保工具可以安全重试:

// 查询操作天然幂等,多次调用结果相同
const queryTool = tool(async ({ id }) => await db.find(id), { ... });

// 写入操作需要额外处理幂等性
const createTool = tool(
  async ({ key, value }) => await db.upsert(key, value), // 用 upsert 代替 insert
  { ... }
);

原因:LLM可能会重复调用同一工具,幂等性保证不会产生副作用。

💡 实践 3:工具命名规范

❌ 不好的命名:

{ name: 'Get Weather Data' }  // 包含空格
{ name: '查询数据库' }         // 中文命名

✅ 推荐的命名:

{ name: 'get_weather' }       // 小写+下划线
{ name: 'query_database' }    // 语义清晰

原因:某些LLM对工具名有特殊字符要求,统一使用小写+下划线最安全。

⚠️ 常见问题

问题	现象	解决方案
工具名使用空格或特殊字符	LLM 调用工具失败	工具名只使用字母、数字和下划线
忘记 bindTools	LLM 不会调用工具,直接文字回复	使用 model.bindTools(tools) 创建带工具的模型
tools → agent 边缺失	工具执行后图意外结束	确保工具节点有边连回 agent 节点
工具返回非字符串	ToolMessage 解析错误	工具函数必须返回 string 或 Promise<string>
工具描述不清晰	LLM不调用或误调用工具	详细描述工具用途、参数、适用场景
未设置超时	工具长时间挂起,图卡死	所有外部API调用必须设置超时
工具内部抛异常	整个图崩溃	工具内捕获异常,返回错误描述字符串

---

📝 本章小结

核心知识点回顾

知识点	关键要点	应用场景
tool() 函数	Zod schema + 执行函数	定义所有自定义工具
bindTools()	将工具绑定到模型	使 LLM 感知并能调用工具
ToolNode	预构建工具执行节点	大多数工具调用场景
ReAct 循环	agent → tools → agent	构建能"行动"的 Agent
错误处理	工具内捕获 or handleToolErrors	生产级 Agent 必须处理
超时控制	AbortController	防止工具长时间挂起
幂等性设计	工具可安全重试	提高系统鲁棒性

🎯 动手练习

练习 1:创建文件操作工具

• 目标:创建读取、写入本地文件的工具
• 要求:
  1. 使用 Node.js fs 模块实现read_file和write_file工具
  2. 工具需要处理文件不存在、权限不足等错误
  3. 添加文件大小限制(防止读取过大文件)
• 验收标准:
  • Agent 能读取指定文件内容
  • Agent 能修改文件并保存
  • 错误情况返回友好提示

练习 2:集成真实搜索 API

• 目标:将 SerpAPI 或 Tavily API 集成为真实搜索工具
• 要求:
  1. 注册SerpAPI/Tavily账号获取API Key
  2. 实现带超时控制的搜索工具
  3. 处理API限流(429错误)
• 验收标准:
  • Agent 能搜索并引用真实网络信息
  • 超时和限流有正确处理
  • 返回结果包含来源链接

练习 3:工具调用追踪

• 目标:记录每次工具调用的名称、参数、耗时和结果
• 要求:
  1. 在 State 中添加 toolCallHistory 字段
  2. 创建中间件节点记录每次工具调用
  3. 最终输出包含完整的调用历史
• 验收标准:
  • 每次工具调用后,历史记录自动追加
  • 包含工具名、参数、耗时、结果摘要
  • 可用于调试和审计

练习 4:多工具协同任务

• 目标:实现需要多个工具协作的复杂任务
• 要求:
  1. 创建weather(天气)、location(地理位置)、recommendation(推荐)三个工具
  2. 用户问:“推荐北京明天适合的户外活动”
  3. Agent自动调用多个工具获取信息并综合回答
• 验收标准:
  • 自动调用location获取北京坐标
  • 调用weather获取明天天气
  • 基于天气推荐合适活动
  • 最多3轮工具调用完成任务

📚 延伸阅读

• LangGraph ToolNode 文档
• LangChain Tools 指南
• ReAct 论文原文
• Function Calling 最佳实践

---

下一章:第7章 —— 持久化与检查点机制