1. 项目概述LangChain.js 工具链的实战价值如果你正在用LangChain.js构建AI应用大概率会遇到一个核心痛点大语言模型LLM本身就像一个知识渊博但“手无寸铁”的顾问。它能和你聊得天花乱坠但当你需要它查一下数据库里的用户订单、调用一次天气API或者分析你刚上传的PDF文件时它只能两手一摊告诉你“这超出了我的能力范围”。这就是“工具”Tools这个组件要解决的问题。简单来说工具就是赋予LLM“动手能力”的扩展插件。通过将外部函数、API或数据源封装成工具LLM就能在推理过程中自主调用它们从而完成更复杂、更落地的任务。比如用户问“我上周的订单发货了吗”Agent智能体可以自动调用“查询订单数据库”的工具获取真实数据后再组织语言回答而不是凭空编造一个物流单号。这次我们不谈理论直接进入实战。我将以一个贴近实际开发的场景为主线带你从零开始在LangChain.js中定义、集成并使用工具最终构建一个能真正“干活”的智能体。整个过程会涉及工具的核心概念、多种集成方式、错误处理以及我踩过的一些坑。无论你是想做一个能查天气的聊天机器人还是一个能分析公司文档的智能助手掌握工具的使用都是必经之路。你会发现当LLM学会了使用工具整个应用的边界就被极大地拓宽了。2. 核心概念与设计思路拆解在动手写代码之前我们必须把几个关键概念和它们之间的关系理清楚。这能帮你理解LangChain.js设计工具链的哲学避免后续开发中“知其然不知其所以然”。2.1 工具Tool、智能体Agent与执行器Executor的关系你可以把这三者想象成一个高效的“特种作战小组”。工具是小组里的各种专家装备狙击枪搜索工具、破门锤数据库工具、无人机API调用工具。每件装备都有非常明确、单一的功能。智能体Agent则是这个小组的指挥官它的核心能力是“思考”和“决策”。指挥官自己不直接操作装备但它接收任务用户问题分析局势理解问题然后决定下一步该让哪位队员调用哪个工具去做什么。执行器Executor是整个小组的作战流程协调员。它负责反复执行“指挥官思考 - 下达指令 - 队员执行 - 反馈结果 - 指挥官再思考”这个循环直到任务完成为止。在LangChain.js中这种关系被抽象得非常清晰。你首先需要定义独立的工具函数。然后你将一组工具和一个大语言模型LLM实例“喂”给一个特定的Agent类型如ReActAgent或PlanAndExecuteAgent。最后你使用AgentExecutor来运行这个Agent。这个执行器会处理所有底层的迭代、工具调用的解析、结果收集以及处理可能出现的错误或中断比如用户说“停下”。2.2 工具的本质一个标准化的函数接口LangChain.js对“工具”有一个非常严格的定义。它不是一个随便的函数。一个合法的工具必须是一个实现了特定接口的对象这个接口主要包含两个部分name: 工具的唯一标识符。LLM会根据这个名称来决定调用哪个工具。名称应该简洁、具描述性如search、calculator。description: 工具的详细描述。这是最关键的部分LLM完全依靠这段描述来理解工具的用途、输入格式和输出内容。描述写得好不好直接决定了LLM能否正确使用它。func(或call): 工具的实际执行函数。它接收一个字符串类型的输入参数执行逻辑并返回一个字符串类型的结果。为什么要把输入输出都强制规定为字符串这是为了适配LLM的文本交互本质。LLM理解和生成的都是文本。所以无论你的工具内部逻辑多复杂可能是查询数据库返回一个JSON对象也可能是调用API返回一个二进制图片在工具的边界上都需要做一次“序列化”和“反序列化”。输入时LLM给出的指令是文本你需要从中解析出参数输出时你需要将复杂的结果转换成LLM能理解的描述性文本。2.3 方案选型内置工具 vs. 自定义工具LangChain.js社区提供了大量现成的内置工具比如SerpAPI谷歌搜索、Calculator计算器、WikipediaQueryRun维基百科查询等。对于常见需求优先使用内置工具是最高效的选择因为它们通常经过良好测试并且描述写得非常规范。但是实际业务中90%的需求都需要自定义工具。因为你的业务逻辑、你的数据库、你的内部API是独一无二的。因此本次实战的重点将放在自定义工具上。我们将学习两种主流的创建方式使用DynamicTool类进行快速封装以及继承Tool基类实现更精细的控制。理解这两种方式你就能应对几乎所有将现有功能接入LangChain的需求。3. 实战准备构建一个多功能智能助手场景为了不让例子过于抽象我们设定一个具体的实战场景构建一个“个人办公智能助手”。我们希望这个助手能帮我们做三件事查询指定城市的最新天气模拟调用外部API。在本地一个模拟的待办事项列表中添加任务模拟操作内存数据。对一段文本进行简单的情绪分析模拟调用一个本地计算函数。这个场景虽小但涵盖了调用外部HTTP服务、操作内部数据状态和执行计算逻辑这三种最常见的工具类型非常有代表性。3.1 环境搭建与基础依赖首先确保你有一个Node.js项目版本建议16。初始化项目并安装核心依赖npm init -y npm install langchain langchain/core我们还需要一个LLM提供商。这里为了演示方便我们使用OpenAI的模型。你需要准备一个OPENAI_API_KEY。npm install langchain/openai创建一个名为agent-demo.js的文件我们先引入必要的模块并初始化LLM。import { ChatOpenAI } from langchain/openai; import { DynamicTool, Tool } from langchain/core/tools; import { AgentExecutor, createReactAgent } from langchain/agents; import { pull } from langchain/hub; import { PromptTemplate } from langchain/core/prompts; // 1. 初始化LLM。使用gpt-3.5-turbo在成本与效果间取得平衡。 const llm new ChatOpenAI({ modelName: gpt-3.5-turbo, temperature: 0, // 设置为0使输出更确定更适合工具调用 openAIApiKey: process.env.OPENAI_API_KEY, }); // 一个模拟的待办事项列表用于演示工具如何操作“状态” let todoList [完成项目周报, 预约牙医];注意将temperature设为0对于工具调用场景非常重要。这能显著降低LLM输出的随机性让它更稳定地生成格式正确的工具调用指令减少解析失败的概率。在实际生产环境中你需要通过环境变量来管理API密钥不要像示例中这样硬编码。3.2 自定义工具一天气查询工具DynamicTool我们将使用DynamicTool来快速创建天气查询工具。DynamicTool允许你直接提供一个函数和描述它帮你处理剩下的封装工作。这非常适合快速原型开发。// 2. 创建天气查询工具 const weatherTool new DynamicTool({ name: get_weather, description: 根据提供的城市名称查询该城市的当前天气情况。输入应该是一个纯粹的城市名例如“北京”或“New York”。, func: async (input) { console.log([天气工具] 正在查询城市: ${input}); // 模拟调用天气API。真实场景下这里会是 fetch(‘https://api.weather.com/...‘) // 这里我们模拟一个简单的响应。 const mockWeatherData { Beijing: 晴气温 22°C北风2级, New York: 多云气温 18°C东南风1级, London: 小雨气温 12°C西风3级, }; const weather mockWeatherData[input] || 未找到城市“${input}”的天气信息请检查城市名是否正确。; return 城市【${input}】的天气是${weather}; }, });关键点解析描述description我特意在描述中明确了输入格式“输入应该是一个纯粹的城市名”。这相当于给LLM的“使用说明书”能极大提高它传入正确参数的几率。函数func函数接收一个字符串input。在实际项目中你需要在这里解析input可能是一个城市名构造HTTP请求调用真实的天气API如OpenWeatherMap然后处理JSON响应最后将最关键的信息提取并格式化成一段自然的文本描述返回。返回给LLM的应该是它易于理解和利用的文本而不是原始的JSON。3.3 自定义工具二待办事项管理工具继承Tool类对于需要更复杂控制比如访问构造函数参数、维护内部状态的工具继承Tool基类是更好的选择。我们来创建一个可以添加待办事项的工具。// 3. 创建待办事项管理工具通过继承 class AddTodoTool extends Tool { static lc_name() { return AddTodoTool; } // 工具名称 get name() { return add_todo; } // 工具描述 get description() { return 将一个待办事项添加到全局列表中。输入是要添加的任务内容例如“下午三点开会”。; } // 核心执行方法 async _call(arg) { console.log([待办工具] 接收到输入: ${arg}); // 简单的输入校验 if (!arg || arg.trim().length 0) { return 错误任务内容不能为空。; } const task arg.trim(); todoList.push(task); // 操作外部的状态 return 成功添加待办事项“${task}”。当前所有待办事项${todoList.join(“, “)}; } } const todoTool new AddTodoTool();与DynamicTool的对比结构化通过类来组织代码更清晰尤其当工具逻辑复杂时。状态管理_call方法中可以方便地访问类属性或外部状态如我们操作的全局todoList变量。这在工具需要维护连接池、缓存或配置时非常有用。生命周期你可以在构造函数或_call方法中加入更复杂的初始化、清理或日志逻辑。3.4 自定义工具三情绪分析工具函数封装DynamicTool我们再创建一个纯粹的计算型工具它不调用外部API也不修改状态只对输入文本进行处理。// 4. 创建情绪分析工具 // 先定义一个普通的工具函数 const analyzeSentiment (text) { const positiveWords [好, 开心, 喜欢, 优秀, 感谢, 棒]; const negativeWords [差, 糟糕, 难过, 讨厌, 失望, 慢]; let score 0; const words text.split(/\W/); words.forEach(word { if (positiveWords.includes(word)) score 1; if (negativeWords.includes(word)) score - 1; }); if (score 0) return “积极”; if (score 0) return “消极”; return “中性”; }; // 再用DynamicTool包装它 const sentimentTool new DynamicTool({ name: “analyze_sentiment”, description: “分析一段文本的情绪倾向积极、消极或中性。输入是一段完整的文本。”, func: async (input) { const result analyzeSentiment(input); return 文本“${input.substring(0, 30)}...”的情绪分析结果为【${result}】。; }, });这个例子展示了如何将已有的业务函数快速接入LangChain生态。你只需要编写一个适配层func将字符串输入转换成函数参数再将结果格式化成字符串输出。4. 智能体集成与执行流程详解工具准备好了现在需要让LLM学会使用它们。我们将使用LangChain.js中强大且流行的ReAct代理框架。4.1 创建ReAct智能体ReActReasoning Acting是一种让LLM在“思考”和“行动”间交替进行的范式。LangChain.js提供了createReactAgent这个工厂函数来简化创建过程。// 5. 从LangChain Hub拉取一个优化过的ReAct提示词模板 // 你也可以自己定义但Hub上的模板通常经过充分测试。 const prompt await pull(“hwchase17/react”); // 6. 创建ReAct智能体 const agent await createReactAgent({ llm, tools: [weatherTool, todoTool, sentimentTool], // 传入我们定义的三个工具 prompt, });为什么从Hub拉取提示词ReAct代理的核心之一是其提示词模板这个模板包含了指导LLM如何思考、如何格式化工具调用指令的详细说明。自己从头编写一个稳定可用的模板非常复杂。LangChain Hub是一个社区共享的提示词库hwchase17/react是一个经过广泛验证的标准ReAct模板能省去大量调试时间。4.2 配置与运行AgentExecutor智能体Agent本身只负责生成“思考”和“行动”的文本指令我们需要一个执行器Executor来解析这些指令、调用对应的工具、并把结果返回给Agent进行下一轮思考。// 7. 创建代理执行器 const executor new AgentExecutor({ agent, tools: [weatherTool, todoTool, sentimentTool], // 必须再次传入工具 verbose: true, // 开启详细日志对调试至关重要 }); // 8. 运行智能体 try { const input “请先查询一下伦敦的天气然后帮我把‘学习LangChain工具使用’添加到待办列表。”; console.log(\n用户提问${input}); const result await executor.invoke({ input }); console.log(\n最终结果${result.output}); console.log(当前待办列表, todoList); } catch (error) { console.error(“执行过程中出错”, error); }关键配置解析verbose: true这是开发阶段最重要的选项。开启后你会在控制台看到完整的思维链LLM的思考过程、它决定调用哪个工具、调用的参数是什么、工具返回的结果是什么。这是排查工具调用问题不可或缺的信息。重复传入tools你可能注意到了我们在创建agent和executor时都传入了tools数组。给agent是让它知道有哪些工具可用给executor是让它拥有实际调用这些工具的能力。两者缺一不可。错误处理一定要用try...catch包裹executor.invoke。工具调用可能因为网络、API限制、参数错误等多种原因失败良好的错误处理能保证应用不会意外崩溃。4.3 执行过程深度剖析当你运行上述代码并观察verbose日志时你会看到类似下面的过程已简化用户提问请先查询一下伦敦的天气然后帮我把‘学习LangChain工具使用’添加到待办列表。 [思考] 用户提出了两个请求1. 查询伦敦天气2. 添加待办事项。我需要按顺序使用工具。 [行动] 我将使用 get_weather 工具。 [工具调用] Action: get_weather Action Input: “London” [工具结果] 城市【London】的天气是小雨气温 12°C西风3级。 [思考] 我已经完成了天气查询。现在需要添加待办事项。 [行动] 我将使用 add_todo 工具。 [工具调用] Action: add_todo Action Input: “学习LangChain工具使用” [工具结果] 成功添加待办事项“学习LangChain工具使用”。当前所有待办事项完成项目周报 预约牙医 学习LangChain工具使用。 [思考] 两个任务都已完成我可以给出最终回答了。 最终结果已为您查询到伦敦的天气为小雨气温12°C西风3级。同时已成功将“学习LangChain工具使用”添加到您的待办事项列表中。这个过程完美展示了ReAct代理的“思考-行动”循环。LLM并没有被一次性告知所有步骤而是像人一样一步步规划、执行、观察结果、再规划下一步。5. 高级技巧与常见问题排查掌握了基础用法后我们来看看如何提升工具的可靠性和处理那些让人头疼的边界情况。5.1 如何编写高质量的工具描述工具描述是LLM能否正确使用工具的决定性因素。糟糕的描述会导致LLM张冠李戴或参数错误。反面教材description: “一个工具。”或description: “获取数据。”优秀实践明确功能清晰说明工具是干什么的。指定输入格式明确告诉LLM应该传入什么。是“一个城市名”还是“一个YYYY-MM-DD格式的日期”或是“一个英文关键词”。说明输出简要说明工具会返回什么信息让LLM对结果有预期。举例说明如果输入格式复杂最好提供例子。// 好的描述示例 const goodDescription 在公司的产品数据库中根据产品ID查询详细信息。 输入必须是一个有效的产品ID字符串例如“PROD-10023”或“SKU-778901”。 工具将返回产品的名称、库存状态和价格。 如果ID不存在将返回“未找到该产品”。 ;5.2 处理复杂参数与结构化输入有时工具需要多个参数比如一个“订餐工具”需要“菜品名”和“数量”。让LLM把一个句子解析成两个参数比较困难。有两种主流解决方案方案一在工具函数内部解析让LLM传入一段自然语言在工具的func方法里用代码或另一个小LLM调用进行解析。func: async (input) { // 假设 input 是 “我要两份鱼香肉丝” // 在这里编写解析逻辑提取“鱼香肉丝”和“2” // ... }这种方式灵活但增加了工具内部的复杂性。方案二使用StructuredTool推荐LangChain提供了StructuredTool它允许你定义一个Zod Schema来严格规范输入参数的结构。LLM会生成符合这个Schema的JSON。import { z } from “zod”; import { StructuredTool } from “langchain/core/tools”; const orderSchema z.object({ dishName: z.string().describe(“菜品的名称”), quantity: z.number().describe(“订购的数量”), }); class OrderTool extends StructuredTool { schema orderSchema; // … name, description async _call(arg) { // 这里的 arg 已经是一个解析好的对象如 { dishName: “鱼香肉丝”, quantity: 2 } const { dishName, quantity } arg; return 成功订购 ${quantity} 份【${dishName}】。; } }StructuredTool是处理复杂参数更优雅、更可靠的方式能显著减少参数解析错误。5.3 常见错误与调试清单在开发过程中你肯定会遇到工具调用失败的情况。下面是一个快速排查清单问题现象可能原因解决方案Agent一直“思考”不调用工具1. 工具描述不清晰LLM不理解何时使用。2. Prompt模板不匹配或有问题。3. LLM temperature 过高输出不稳定。1. 重写工具描述确保清晰、有例子。2. 检查并确保使用正确的Prompt如从Hub拉取。3. 将LLM的temperature设为0。Agent调用了错误的工具工具名称或描述相似导致LLM混淆。1. 给工具起更具区分度的名字。2. 在描述中强调该工具的独特用途。工具调用参数格式错误LLM没有按照描述中指定的格式生成输入。1. 在工具描述中极其明确地指定输入格式并举例。2. 考虑使用StructuredTool。工具函数执行时报错如网络错误工具内部代码有bug或依赖服务不可用。1. 在工具的func方法内部添加完善的try-catch。2. 返回清晰的错误信息给LLM如“网络请求失败请稍后再试”。Agent陷入无限循环Agent得到一个工具结果后无法做出正确决策反复调用同一工具。1. 检查工具返回的结果是否清晰、完整能否为LLM的下一步决策提供足够信息。2. 在AgentExecutor中设置maxIterations参数例如maxIterations: 10来强制终止。一个重要的调试技巧当遇到诡异的问题时把verbose模式打开仔细阅读LLM的“思考”过程和工具调用记录。十有八九你能从中找到线索——可能是LLM误解了你的问题也可能是工具返回的结果让它困惑了。5.4 性能与成本考量工具调用意味着额外的外部请求或计算会增加延迟和成本。超时设置为可能耗时的工具如网络请求设置超时避免整个Agent被卡住。限制迭代次数通过AgentExecutor的maxIterations参数默认15限制最大思考步数防止复杂任务消耗过多Token。选择性提供工具不要一股脑把所有工具都丢给每一个Agent。根据具体的任务场景只提供必要的工具子集这能减少LLM的困惑并降低它错误调用无关工具的几率。缓存对于查询类工具如天气、百科如果数据更新不频繁可以考虑在工具层或应用层添加缓存机制避免重复调用。工具的使用是LangChain.js从“玩具”走向“应用”的关键一步。它打破了LLM的封闭世界让其能够与真实的数据和系统交互。从定义好一个描述清晰的工具开始到构建出能自主完成多步任务的智能体这个过程充满了挑战但当你看到AI能准确地调用你编写的函数并解决问题时那种成就感也是巨大的。记住好的工具设计始于清晰的描述和稳健的函数实现多观察verbose日志它能告诉你LLM眼中的世界是什么样的。
