LangChain 中的工具Tools 是扩展智能体Agent能力的核心组件能让智能体实现实时数据获取、代码执行、外部数据库查询、现实世界操作等功能。底层来看工具是具有明确输入输出的可调用函数会被传递给大语言模型Chat Model由模型根据对话上下文决定何时调用、传入哪些参数。本文将从工具创建、自定义配置、运行时上下文访问、ToolNode 工作流、预构建工具等维度全面讲解 LangChain 工具的使用。一、创建工具 ️LangChain 提供了极简的工具创建方式核心是tool装饰器同时支持基础定义、自定义属性、高级模式三种创建层级满足不同场景需求。1.1 基础工具定义这是创建工具的最简方式通过tool装饰普通Python函数即可类型注解是必选的用于定义工具的输入模式函数的文档字符串docstring会自动作为工具的描述帮助大语言模型理解工具的用途。代码示例详解from langchain.tools import tool # 导入工具装饰器 tool # 装饰器将普通函数转为LangChain工具 def search_database(query: str, limit: int 10) - str: 搜索客户数据库中匹配查询条件的记录 Args: query: 搜索关键词 limit: 返回结果的最大数量默认10条 # 实际场景中可替换为真实的数据库查询逻辑 return fFound {limit} results for {query}关键要点类型注解query: str/limit: int/- strLangChain 会根据注解生成工具的输入/输出Schema模型会依据Schema传递参数docstring必须清晰、简洁明确工具的功能和参数含义这是模型判断是否调用该工具的核心依据函数返回值建议为字符串类型方便模型直接解析使用。1.2 自定义工具属性默认情况下工具的名称为函数名、描述为docstringLangChain 支持手动覆盖这两个属性让工具的定义更贴合业务场景。1自定义工具名称通过tool(自定义名称)的方式指定适用于函数名过于简洁、无法体现工具功能的场景。tool(web_search) # 自定义工具名称为web_search替代默认的search def search(query: str) - str: 搜索网络上的信息 return fResults for: {query} print(search.name) # 输出web_search验证自定义名称生效2自定义工具描述通过tool的description参数手动指定描述优先级高于docstring可让模型更精准地理解工具用途比如明确「何时使用该工具」。# 自定义名称为calculator描述为「执行算术计算所有数学问题都用这个工具」 tool(calculator, descriptionPerforms arithmetic calculations. Use this for any math problems.) def calc(expression: str) - str: 解析数学表达式 return str(eval(expression)) # 执行表达式计算实际场景建议增加安全校验核心作用自定义描述可以直接给模型下达「使用指令」比如上述示例中明确Use this for any math problems模型会在遇到数学问题时主动调用该计算器工具。1.3 高级模式定义复杂输入当工具需要复杂的输入参数比如多参数、可选参数、枚举值、参数校验时可通过Pydantic 模型或JSON Schema定义输入模式再通过args_schema参数传递给tool装饰器是生产环境的推荐方式。代码示例详解Pydantic 模型最常用from pydantic import BaseModel, Field # Pydantic核心库用于定义数据模型 from typing import Literal # 用于定义枚举类型参数 # 第一步定义Pydantic模型描述工具的输入参数 class WeatherInput(BaseModel): 天气查询工具的输入参数模型 # 城市名/经纬度Field描述参数含义模型会自动校验参数类型 location: str Field(descriptionCity name or coordinates) # 枚举值仅支持celsius摄氏度/fahrenheit华氏度默认摄氏度 units: Literal[celsius, fahrenheit] Field( defaultcelsius, descriptionTemperature unit preference ) # 是否包含5天预报布尔值默认不包含 include_forecast: bool Field( defaultFalse, descriptionInclude 5-day forecast ) # 第二步将模型传入args_schema创建工具 tool(args_schemaWeatherInput) def get_weather(location: str, units: str celsius, include_forecast: bool False) - str: 获取当前天气可选返回5天预报 # 模拟天气查询逻辑实际场景替换为真实的天气API调用 temp 22 if units celsius else 72 result fCurrent weather in {location}: {temp} degrees {units[0].upper()} # 如果需要预报追加预报信息 if include_forecast: result /nNext 5 days: Sunny return resultPydantic 模型的核心价值参数校验自动校验输入参数的类型、枚举值比如units只能传celsius/fahrenheit避免无效参数清晰的参数描述通过Field为每个参数添加描述模型能精准理解参数含义默认值配置支持为参数设置默认值简化工具调用复杂参数扩展可定义嵌套模型、列表、字典等复杂参数满足各类业务场景。1.4 保留参数名称 ⚠️LangChain 规定了两个保留参数名不能作为工具的自定义参数否则会触发运行时错误这是开发中需要避免的坑。保留参数名用途config内部用于传递RunnableConfig配置包含回调、标签、元数据等runtime用于传递ToolRuntime对象实现状态、上下文、持久化存储的访问注意如果需要访问运行时信息如对话状态、用户上下文直接使用ToolRuntime参数即可无需手动定义config/runtime。二、访问运行时上下文 工具的核心能力之一是访问运行时的上下文信息比如对话历史、用户ID、持久化偏好让工具能根据不同的场景和用户返回个性化结果。LangChain 提供ToolRuntime参数实现上下文访问该参数会自动注入到工具中且对大语言模型隐藏不会出现在工具的输入Schema中只需在工具函数中声明即可使用。ToolRuntime包含6大核心组件覆盖短/长期记忆、实时流、配置等所有运行时信息如下表所示组件类型描述典型使用场景State短期记忆当前对话的可变数据仅在本次对话有效访问对话历史、统计工具调用次数、存储临时用户偏好Context不可变配置调用工具时传入的固定配置本次对话全程不变基于用户ID获取个人信息、会话ID关联业务数据Store长期记忆跨对话的持久化存储数据在未来会话中仍有效保存用户长期偏好、维护知识库、存储历史操作记录Stream Writer实时流输出工具执行过程中发送实时更新为长耗时操作提供进度反馈如「正在查询数据」「数据查询完成」Config执行配置工具的执行配置信息访问回调函数、标签、元数据实现日志追踪Tool Call ID唯一标识本次工具调用的唯一ID日志关联、多工具调用的溯源、模型调用与工具调用的关联2.1 短期记忆StateState 是当前对话的临时内存生命周期与对话一致对话结束后数据销毁包含对话消息历史、自定义字段如计数器、临时偏好等。1访问State读取对话信息通过runtime.state访问核心是读取对话消息历史和自定义字段代码示例附带详细解析from langchain.tools import tool, ToolRuntime # 导入ToolRuntime from langchain.messages import HumanMessage # 导入人类消息类型用于筛选 tool def get_last_user_message(runtime: ToolRuntime) - str: 获取用户的最新一条消息 # 从runtime.state中读取对话消息列表key固定为messages messages runtime.state[messages] # 倒序遍历消息找到最后一条人类消息排除模型/工具消息 for message in reversed(messages): if isinstance(message, HumanMessage): return message.content # 无人类消息时的兜底返回 return No user messages found # 访问自定义State字段如用户临时偏好 tool def get_user_preference( pref_name: str, # 模型可见的参数要获取的偏好名称 runtime: ToolRuntime # 模型隐藏的参数运行时上下文 ) - str: 获取用户的临时偏好值 # 从state中读取自定义字段user_preferences不存在则返回空字典 preferences runtime.state.get(user_preferences, {}) # 返回指定偏好值不存在则返回Not set return preferences.get(pref_name, Not set)关键要点runtime.state是一个字典内置messages字段存储对话历史也可自定义任意字段ToolRuntime参数对模型隐藏上述示例中模型仅能看到pref_name参数无需传递runtime消息类型区分LangChain 会将消息分为HumanMessage人类、AIMessage模型、ToolMessage工具等可通过类型筛选指定来源的消息。2更新State修改对话信息通过langgraph.types.Command对象更新State返回Command(update{字段: 新值})即可实现自定义字段的修改适用于工具需要向对话中写入临时数据的场景。from langgraph.types import Command # 导入Command对象 from langchain.tools import tool tool def set_user_name(new_name: str) - Command: 将用户名写入对话的短期记忆State # 返回Command对象update参数指定要修改的State字段和新值 return Command(update{user_name: new_name})并发冲突处理如果多个工具并行调用且修改同一个State字段建议为字段定义Reducer归约器用于解决冲突比如取最新值、合并值。2.2 不可变上下文ContextContext 是调用工具时传入的固定配置具有不可变性本次对话中无法修改适用于存储用户ID、会话ID、应用级配置等无需变动的信息通过runtime.context访问。代码示例详解用户账户信息查询from dataclasses import dataclass # 用于定义简单的上下文模型 from langchain_openai import ChatOpenAI # 导入OpenAI大模型 from langchain.agents import create_agent # 导入智能体创建函数 from langchain.tools import tool, ToolRuntime # 模拟用户数据库实际场景替换为真实的数据库/缓存 USER_DATABASE { user123: {name: Alice Johnson, account_type: Premium, balance: 5000, email: aliceexample.com}, user456: {name: Bob Smith, account_type: Standard, balance: 1200, email: bobexample.com} } # 第一步定义上下文模型使用dataclass简化定义也可使用Pydantic模型 dataclass class UserContext: user_id: str # 上下文仅包含用户ID不可变 # 第二步创建工具通过ToolRuntime[UserContext]指定上下文类型 tool def get_account_info(runtime: ToolRuntime[UserContext]) - str: 获取当前用户的账户信息 # 从runtime.context中读取用户ID user_id runtime.context.user_id # 根据用户ID查询数据库 if user_id in USER_DATABASE: user USER_DATABASE[user_id] return f账户持有人{user[name]}/n账户类型{user[account_type]}/n账户余额${user[balance]} return 用户不存在 # 第三步创建智能体指定上下文模型 model ChatOpenAI(modelgpt-4.1) # 初始化大模型 agent create_agent( modelmodel, tools[get_account_info], # 绑定工具 context_schemaUserContext, # 指定上下文模型 system_prompt你是一个金融助理负责查询用户的账户信息 ) # 第四步调用智能体传入具体的上下文用户IDuser123 result agent.invoke( {messages: [{role: user, content: 我的账户余额是多少}]}, contextUserContext(user_iduser123) # 传入不可变上下文 )核心价值Context 实现了用户信息与工具的解耦工具无需硬编码用户ID而是通过上下文获取让工具具有通用性可复用在不同用户的对话中。2.3 长期记忆StoreStore 是跨对话的持久化存储基于BaseStore实现数据不会随对话结束而销毁适用于保存用户长期偏好、知识库、历史操作记录等通过runtime.store访问。LangChain 提供了多种Store实现开发环境InMemoryStore内存存储重启后数据丢失生产环境PostgresStorePostgreSQL、RedisStoreRedis等持久化存储推荐。Store 采用「命名空间/键」 的双层模式组织数据避免键冲突格式为store.get((命名空间,), 键)/store.put((命名空间,), 键, 值)。代码示例详解用户信息的持久化增查from typing import Any # 用于定义任意类型的参数 from langgraph.store.memory import InMemoryStore # 导入内存存储开发用 from langchain.agents import create_agent from langchain.tools import tool, ToolRuntime # 1. 读取持久化的用户信息 tool def get_user_info(user_id: str, runtime: ToolRuntime) - str: 根据用户ID查询持久化的用户信息 # 从runtime中获取store实例 store runtime.store # 从命名空间users中读取指定user_id的信息格式get((命名空间,), 键) user_info store.get((users,), user_id) # 存在则返回值否则返回未知用户 return str(user_info.value) if user_info else Unknown user # 2. 保存用户信息到持久化存储 tool def save_user_info(user_id: str, user_info: dict[str, Any], runtime: ToolRuntime) - str: 将用户信息保存到持久化存储 store runtime.store # 向命名空间users中写入键值对格式put((命名空间,), 键, 值) store.put((users,), user_id, user_info) return 用户信息保存成功 # 3. 初始化Store开发用InMemoryStore生产替换为PostgresStore store InMemoryStore() # 4. 创建智能体绑定Store和工具 agent create_agent( modelmodel, # 需提前初始化大模型如ChatOpenAI tools[get_user_info, save_user_info], storestore # 传入持久化存储实例 ) # 5. 第一次会话保存用户信息跨会话有效 agent.invoke({ messages: [{role: user, content: 保存用户信息useridabc123nameFooage25emailfoolangchain.dev}] }) # 6. 第二次会话查询已保存的用户信息即使重启程序持久化存储仍能读取 agent.invoke({ messages: [{role: user, content: 查询用户ID为abc123的信息}] })输出结果以下是用户ID为abc123的信息 - 姓名Foo - 年龄25 - 邮箱foolangchain.dev生产环境注意务必替换InMemoryStore为持久化存储如PostgresStore否则重启应用后数据会全部丢失。2.4 实时流输出Stream WriterStream Writer 用于在工具执行过程中发送实时更新适用于长耗时的工具操作如大数据查询、文件生成、API调用为用户提供进度反馈提升交互体验通过runtime.stream_writer使用。代码示例详解from langchain.tools import tool, ToolRuntime tool def get_weather(city: str, runtime: ToolRuntime) - str: 查询指定城市的天气 # 获取流写入器实例 writer runtime.stream_writer # 发送实时进度更新可多次调用 writer(f正在查询{city}的天气数据...) writer(f已获取{city}的天气原始数据正在解析...) # 模拟天气查询逻辑 return f{city}的天气晴25℃微风注意使用runtime.stream_writer的工具必须在LangGraph的执行上下文中调用否则会触发错误。三、ToolNodeLangGraph 工作流中的工具执行 ToolNode是LangGraph提供的预构建节点专门用于在工作流中执行工具自动处理并行工具执行、错误处理、状态注入等复杂逻辑是实现自定义工作流的核心组件。如果需要对工具执行进行细粒度的控制如自定义执行顺序、条件路由建议使用ToolNode替代create_agent它是智能体工具执行的底层构建块。3.1 基础使用核心步骤创建工具 → 初始化ToolNode→ 将ToolNode添加到LangGraph的状态图中。代码示例详解from langchain.tools import tool from langgraph.prebuilt import ToolNode # 导入ToolNode from langgraph.graph import StateGraph, MessagesState, START, END # 导入状态图相关组件 # 1. 创建两个基础工具 tool def search(query: str) - str: 搜索网络信息 return f搜索结果{query} tool def calculator(expression: str) - str: 执行数学计算 return str(eval(expression)) # 2. 初始化ToolNode传入需要执行的工具列表 tool_node ToolNode([search, calculator]) # 3. 创建LangGraph状态图指定状态类型为MessagesState消息状态 builder StateGraph(MessagesState) # 4. 将ToolNode添加到状态图中节点名称为tools builder.add_node(tools, tool_node) # 5. 后续可添加其他节点如LLM节点、定义节点间的边执行顺序 # ... add other nodes and edgesMessagesStateLangGraph的内置状态类型核心字段为messages用于存储对话历史是最常用的状态类型。3.2 错误处理ToolNode支持灵活的错误处理配置通过handle_tool_errors参数实现可设置为布尔值、自定义错误信息、自定义错误处理函数、指定异常类型满足不同的错误处理需求。代码示例所有错误处理方式from langgraph.prebuilt import ToolNode # 方式1默认行为 → 捕获工具调用错误重新抛出工具执行错误 tool_node ToolNode(tools) # 方式2捕获所有错误向LLM返回默认错误信息 tool_node ToolNode(tools, handle_tool_errorsTrue) # 方式3捕获所有错误返回自定义错误信息 tool_node ToolNode(tools, handle_tool_errors工具执行失败请稍后重试) # 方式4自定义错误处理函数针对不同异常返回个性化信息 def handle_error(e: ValueError) - str: 自定义错误处理函数参数为异常对象返回字符串 return f输入参数无效{e} tool_node ToolNode(tools, handle_tool_errorshandle_error) # 方式5仅捕获指定类型的异常如ValueError、TypeError tool_node ToolNode(tools, handle_tool_errors(ValueError, TypeError))3.3 条件路由tools_condition通过tools_condition可实现基于LLM是否调用工具的条件路由让工作流根据模型的决策自动选择「执行工具」或「结束对话」是实现智能体「思考-执行」循环的核心。代码示例详解from langgraph.prebuilt import ToolNode, tools_condition # 导入tools_condition路由函数 from langgraph.graph import StateGraph, MessagesState, START, END # 假设已定义call_llmLLM节点和tools工具列表 tool_node ToolNode(tools) builder StateGraph(MessagesState) # 1. 添加LLM节点和ToolNode节点 builder.add_node(llm, call_llm) # llm节点模型思考决定是否调用工具 builder.add_node(tools, tool_node) # tools节点执行工具 # 2. 定义执行流开始 → LLM节点 builder.add_edge(START, llm) # 3. 条件路由LLM节点执行后根据是否调用工具决定下一步 # - 模型决定调用工具 → 跳转到tools节点 # - 模型无需调用工具 → 结束对话END builder.add_conditional_edges(llm, tools_condition) # 4. 工具执行后回到LLM节点继续思考形成「思考-执行」循环 builder.add_edge(tools, llm) # 5. 编译状态图生成可执行的工作流 graph builder.compile()核心逻辑实现了智能体的经典循环 → LLM思考 → 判断是否调用工具 → 工具执行 → 回到LLM继续思考直到无需调用工具结束对话。3.4 状态注入ToolNode会自动将LangGraph的全局状态注入到工具的ToolRuntime中工具可通过runtime.state直接访问工作流的全局状态无需额外配置实现了工具与工作流状态的无缝对接。代码示例from langchain.tools import tool, ToolRuntime from langgraph.prebuilt import ToolNode # 创建工具访问工作流的全局消息状态 tool def get_message_count(runtime: ToolRuntime) - str: 获取对话中的消息总数 # 直接访问LangGraph的全局状态messages messages runtime.state[messages] return f当前对话共有{len(messages)}条消息 # 初始化ToolNode工具自动获取全局状态 tool_node ToolNode([get_message_count])四、预构建工具与服务端工具 LangChain 提供了丰富的预构建工具和服务端工具无需手动开发即可直接使用大幅提升开发效率。4.1 预构建工具Prebuilt toolsLangChain 内置了大量针对常见任务的预构建工具/工具集Toolkits覆盖网络搜索、代码解释、数据库访问、文件操作、API调用等场景可直接集成到智能体中无需编写自定义逻辑。典型预构建工具分类搜索类Bing Search、Google Search、DuckDuckGo Search代码类Code Interpreter代码解释器、Python REPL数据库类SQL Database ToolkitMySQL/PostgreSQL/SQLite文件类CSV Tool、PDF Tool、Excel Tool其他Email Tool、Slack Tool、GitHub Tool。使用方式直接从langchain.tools或langchain.agents.toolkits导入绑定到智能体即可示例from langchain.tools import DuckDuckGoSearchRun from langchain.agents import create_agent # 初始化预构建的搜索工具 search_tool DuckDuckGoSearchRun() # 绑定到智能体 agent create_agent(model, tools[search_tool], system_prompt你是一个智能搜索助手)4.2 服务端工具Server-side tool use部分大语言模型如GPT-4、Claude内置了服务端工具由模型提供商部署和执行如网络搜索、代码解释器、函数调用等无需开发者定义或托管工具逻辑只需在调用模型时启用工具调用功能即可。核心特点无需开发工具逻辑模型直接在服务端执行支持实时数据获取如GPT-4的网络搜索需遵循模型提供商的工具调用规范。使用方式参考对应模型的LangChain集成文档启用工具调用功能即可如OpenAI的enable_function_calling。五、核心开发要点总结 类型注解必选工具函数的输入/输出必须添加类型注解LangChain 基于注解生成Schemadocstring清晰工具的描述docstring/自定义description是模型判断是否调用的核心需明确功能和使用场景避免保留参数不要使用config/runtime作为工具参数避免运行时错误上下文分层使用短期数据用State、不可变配置用Context、长期数据用Store生产环境持久化Store 务必使用PostgresStore等持久化实现避免InMemoryStore的数据丢失ToolNode 用于自定义工作流需要细粒度控制工具执行时使用ToolNode替代create_agent错误处理不可少生产环境中为ToolNode配置自定义错误处理提升系统鲁棒性优先使用预构建工具常见任务直接使用LangChain的预构建工具减少重复开发。这里给大家精心整理了一份全面的AI大模型学习资源包括AI大模型全套学习路线图从入门到实战、精品AI大模型学习书籍手册、视频教程、实战学习、面试题等资料免费分享扫码免费领取全部内容1. 成长路线图学习规划要学习一门新的技术作为新手一定要先学习成长路线图方向不对努力白费。这里我们为新手和想要进一步提升的专业人士准备了一份详细的学习成长路线图和规划。可以说是最科学最系统的学习成长路线。2. 大模型经典PDF书籍书籍和学习文档资料是学习大模型过程中必不可少的我们精选了一系列深入探讨大模型技术的书籍和学习文档它们由领域内的顶尖专家撰写内容全面、深入、详尽为你学习大模型提供坚实的理论基础。书籍含电子版PDF3. 大模型视频教程对于很多自学或者没有基础的同学来说书籍这些纯文字类的学习教材会觉得比较晦涩难以理解因此我们提供了丰富的大模型视频教程以动态、形象的方式展示技术概念帮助你更快、更轻松地掌握核心知识。4. 2026行业报告行业分析主要包括对不同行业的现状、趋势、问题、机会等进行系统地调研和评估以了解哪些行业更适合引入大模型的技术和应用以及在哪些方面可以发挥大模型的优势。5. 大模型项目实战学以致用当你的理论知识积累到一定程度就需要通过项目实战在实际操作中检验和巩固你所学到的知识同时为你找工作和职业发展打下坚实的基础。6. 大模型面试题面试不仅是技术的较量更需要充分的准备。在你已经掌握了大模型技术之后就需要开始准备面试我们将提供精心整理的大模型面试题库涵盖当前面试中可能遇到的各种技术问题让你在面试中游刃有余。7. 资料领取全套内容免费抱走学 AI 不用再找第二份不管你是 0 基础想入门 AI 大模型还是有基础想冲刺大厂、了解行业趋势这份资料都能满足你现在只需按照提示操作就能免费领取扫码免费领取全部内容