Skip to main content
Alpha 版本提示: 本文档涵盖的是 v1-alpha 版本。内容尚不完整,且可能随时变更。如需查阅最新稳定版本,请参阅 v0 版本的 LangChain Python 文档LangChain JavaScript 文档
许多人工智能应用程序通过自然语言与用户交互。然而,某些用例要求模型能够直接与外部系统(例如 API、数据库或文件系统)进行交互,并使用结构化输入。 工具是代理调用以执行操作的组件。它们通过允许模型通过明确定义的输入和输出与外部世界交互,从而扩展了模型的能力。工具封装了一个可调用函数及其输入模式。这些工具可以传递给兼容的聊天模型,使模型能够决定是否调用某个工具以及使用哪些参数。在这种情况下,工具调用使模型能够生成符合指定输入模式的请求。

创建工具

基本工具定义

创建工具最简单的方法是使用 @tool 装饰器。默认情况下,函数的文档字符串将成为工具的描述,帮助模型理解何时使用该工具:
类型提示是必需的,因为它们定义了工具的输入模式。文档字符串应信息丰富且简洁,以帮助模型理解工具的目的。

自定义工具属性

自定义工具名称

默认情况下,工具名称来自函数名称。当您需要更具描述性的名称时,请覆盖它:

自定义工具描述

覆盖自动生成的工具描述,以便为模型提供更清晰的指导:

高级模式定义

使用 Pydantic 模型或 JSON 模式定义复杂输入:

与代理一起使用工具

代理通过添加推理循环、状态管理和多步执行,超越了简单的工具绑定。
要查看如何与代理一起使用工具的示例,请参阅 代理

高级工具模式

ToolNode

ToolNode 是一个预构建的 LangGraph 组件,用于处理代理工作流中的工具调用。它与 create_agent() 无缝协作,提供高级工具执行控制、内置并行性和错误处理。

配置选项

ToolNode 接受以下参数:
required
此节点可以执行的工具列表。可以包括:
  • LangChain @tool 装饰的函数
  • 具有适当类型提示和文档字符串的可调用对象(例如函数)
控制如何处理工具执行失败。 可以是:
  • bool
  • str
  • Callable[..., str]
  • type[Exception]
  • tuple[type[Exception], ...]
默认值:内部 _default_handle_tool_errors

错误处理策略

ToolNode 通过其 handle_tool_errors 属性提供内置的工具执行错误处理。 要自定义错误处理行为,您可以将 handle_tool_errors 配置为布尔值、字符串、可调用对象、异常类型或异常类型的元组:
  • True:捕获所有错误并返回包含异常详细信息的默认错误模板的 ToolMessage。
  • str:捕获所有错误并返回包含此自定义错误消息字符串的 ToolMessage。
  • type[Exception]:仅捕获指定类型的异常并返回其默认错误消息。
  • tuple[type[Exception], ...]:仅捕获指定类型的异常并返回它们的默认错误消息。
  • Callable[..., str]:捕获与可调用对象签名匹配的异常并返回调用它时的字符串结果。
  • False:完全禁用错误处理,允许异常传播。
handle_tool_errors 默认为可调用对象 _default_handle_tool_errors,该对象:
  • 捕获工具调用错误 ToolInvocationError(由于模型提供的无效参数)并返回描述性错误消息
  • 忽略工具执行错误(它们将使用模板字符串 TOOL_CALL_ERROR_TEMPLATE = "错误: {error}\n 请修复您的错误。" 重新引发)
使用不同错误处理策略的示例:

与 create_agent() 一起使用

建议您在阅读本节之前先熟悉 create_agent()阅读有关代理的更多信息
将配置好的 ToolNode 直接传递给 create_agent()
当您将 ToolNode 传递给 create_agent() 时,代理将使用您的确切配置,包括错误处理、自定义名称和标签。当您需要对工具执行行为进行细粒度控制时,这非常有用。

状态、上下文和内存

state:代理在其执行过程中维护状态 - 这包括消息、自定义字段以及您的工具需要跟踪的任何数据。状态在图中流动,并且可以被工具访问和修改。
InjectedState:一种注解,允许工具在不向 LLM 暴露的情况下访问当前图状态。这使得工具可以读取诸如消息历史或自定义状态字段之类的信息,同时保持工具模式的简洁性。
工具可以使用 InjectedState 注解访问当前图状态:
状态注入的参数对模型隐藏。在上面的示例中,模型仅在工具模式中看到 pref_name - preferences 包含在请求中。
Command:工具可以使用的一种特殊返回类型,用于更新代理的状态或控制图的执行流程。工具不仅可以返回数据,还可以返回 Command 来修改状态或将代理定向到特定节点。
使用返回 Command 的工具更新代理状态:
runtime:您的代理的执行环境,包含在代理执行过程中持续存在的不可变配置和上下文数据(例如,用户 ID、会话详细信息或应用程序特定配置)。
工具可以通过 get_runtime 访问代理的运行时上下文:
store:LangChain 的持久层。代理的长期记忆存储,例如跨对话存储的用户特定或应用程序特定数据。
工具可以通过 get_store 访问代理的存储:
要更新长期记忆,您可以使用 InMemoryStore.put() 方法。以下是一个跨会话的持久内存完整示例: