跳到主要内容
Open on GitHub

工具

先决条件

概述​

LangChain 中的工具（tool）抽象将一个 Python 函数（function）与一个模式（schema）关联起来，该模式定义了函数的名称（name）、描述（description）和预期参数（expected arguments）。

工具（Tools）可以传递给支持工具调用的聊天模型，允许模型请求执行具有特定输入的特定函数。

关键概念​

  • 工具是一种封装函数及其模式的方式，以便可以将其传递给聊天模型。
  • 使用@tool装饰器创建工具，该装饰器简化了工具创建过程，支持以下功能：
    • 自动推断工具的名称、描述和预期参数，同时支持自定义。
    • 定义返回工件（例如图像、数据框等）的工具
    • 使用注入的工具参数从模式（从而从模型）中隐藏输入参数。

工具接口​

工具接口在BaseTool类中定义，该类是Runnable 接口的一个子类。

与工具模式对应的关键属性

  • name：工具的名称。
  • description：工具功能的描述。
  • args：返回工具参数的 JSON 模式的属性。

执行与工具关联的函数的关键方法

  • invoke：使用给定参数调用工具。
  • ainvoke：使用给定参数异步调用工具。用于Langchain 异步编程。

使用@tool装饰器创建工具​

创建工具的推荐方式是使用@tool装饰器。此装饰器旨在简化工具创建过程，并应在大多数情况下使用。定义函数后，可以使用@tool对其进行装饰以创建实现工具接口的工具。

from langchain_core.tools import tool

@tool
def multiply(a: int, b: int) -> int:
   """Multiply two numbers."""
   return a * b
API 参考：tool

有关如何创建工具的更多详细信息，请参阅如何创建自定义工具指南。

注意

LangChain 还有其他几种创建工具的方式；例如，通过子类化BaseTool类或使用StructuredTool。这些方法在如何创建自定义工具指南中有所展示，但我们通常建议在大多数情况下使用@tool装饰器。

直接使用工具​

定义工具后，可以通过调用函数直接使用它。例如，要使用上面定义的multiply工具：

multiply.invoke({"a": 2, "b": 3})

检查​

您还可以检查工具的模式和其他属性

print(multiply.name) # multiply
print(multiply.description) # Multiply two numbers.
print(multiply.args) 
# {
# 'type': 'object', 
# 'properties': {'a': {'type': 'integer'}, 'b': {'type': 'integer'}}, 
# 'required': ['a', 'b']
# }
注意

如果您正在使用预构建的 LangChain 或 LangGraph 组件，例如 create_react_agent，您可能不需要直接与工具交互。然而，了解如何使用它们对于调试和测试很有价值。此外，在构建自定义 LangGraph 工作流时，您可能会发现需要直接使用工具。

配置模式​

@tool装饰器提供了额外的选项来配置工具的模式（例如，修改名称、描述或解析函数的文档字符串以推断模式）。

有关更多详细信息，请参阅@tool 的 API 参考，并查阅如何创建自定义工具指南以获取示例。

工具工件​

工具是模型可以调用的实用程序，其输出旨在反馈给模型。然而，有时工具执行的工件我们希望能够供链或代理中的下游组件访问，但又不想将其暴露给模型本身。例如，如果一个工具返回一个自定义对象、一个数据框或一张图片，我们可能希望将此输出的一些元数据传递给模型，而无需将实际输出传递给模型。同时，我们可能希望能够在其他地方（例如在下游工具中）访问这个完整的输出。

@tool(response_format="content_and_artifact")
def some_tool(...) -> Tuple[str, Any]:
    """Tool that does something."""
    ...
    return 'Message for chat model', some_artifact

有关更多详细信息，请参阅如何从工具返回工件。

特殊类型注解​

在工具的函数签名中可以使用许多特殊类型注解来配置工具的运行时行为。

以下类型注解将从工具的模式中移除参数。这对于不应暴露给模型且模型不应控制的参数很有用。

  • InjectedToolArg：值应在运行时使用.invoke或.ainvoke手动注入。
  • RunnableConfig：将 RunnableConfig 对象传递给工具。
  • InjectedState：将 LangGraph 图的整体状态传递给工具。
  • InjectedStore：将 LangGraph 存储对象传递给工具。

您还可以使用带有字符串字面量的Annotated类型，为相应参数提供描述，该描述将在工具的模式中公开。

  • Annotated[..., "字符串字面量"] -- 为将在工具模式中公开的参数添加描述。

InjectedToolArg​

在某些情况下，某些参数需要在运行时传递给工具，但不应由模型本身生成。为此，我们使用InjectedToolArg注解，它允许将某些参数从工具的模式中隐藏。

例如，如果一个工具需要在运行时动态注入user_id，它可以这样构造：

from langchain_core.tools import tool, InjectedToolArg

@tool
def user_specific_tool(input_data: str, user_id: InjectedToolArg) -> str:
    """Tool that processes input data."""
    return f"User {user_id} processed {input_data}"
API 参考：tool | InjectedToolArg

使用InjectedToolArg注解user_id参数会告诉 LangChain，该参数不应作为工具模式的一部分公开。

有关如何使用InjectedToolArg的更多详细信息，请参阅如何将运行时值传递给工具。

RunnableConfig​

您可以使用RunnableConfig对象将自定义运行时值传递给工具。

如果您需要从工具内部访问RunnableConfig对象。这可以通过在工具的函数签名中使用RunnableConfig注解来完成。

from langchain_core.runnables import RunnableConfig

@tool
async def some_func(..., config: RunnableConfig) -> ...:
    """Tool that does something."""
    # do something with config
    ...

await some_func.ainvoke(..., config={"configurable": {"value": "some_value"}})
API 参考：RunnableConfig

config将不会成为工具模式的一部分，并将在运行时注入适当的值。

注意

您可能需要访问config对象才能手动将其传播到子类。如果您在异步环境中使用 Python 3.9 / 3.10，并且需要手动将config对象传播到子调用，则会发生这种情况。

请阅读传播 RunnableConfig以了解如何手动将RunnableConfig向下传播到调用链（或升级到 Python 3.11，这将不再是问题）。

InjectedState​

更多详细信息请参阅InjectedState文档。

InjectedStore​

更多详细信息请参阅InjectedStore文档。

最佳实践​

设计供模型使用的工具时，请记住以下几点：

  • 命名良好、文档正确且类型提示适当的工具更容易被模型使用。
  • 设计简单且范围狭窄的工具，因为它们更容易被模型正确使用。
  • 使用支持工具调用API的聊天模型来利用工具。

工具包​

LangChain 有工具包（toolkits）的概念。这是一个非常薄的抽象层，将设计用于特定任务的工具组合在一起。

接口​

所有工具包都公开了一个get_tools方法，该方法返回一个工具列表。因此，您可以：

# Initialize a toolkit
toolkit = ExampleToolkit(...)

# Get list of tools
tools = toolkit.get_tools()

有关更多信息，请参阅以下资源：