Skip to main content

工具

¥Tools

Prerequisites

概述​

¥Overview

LangChain 中的工具抽象将 TypeScript 函数与定义函数名称、描述和输入的模式相关联。

¥The tool abstraction in LangChain associates a TypeScript function with a schema that defines the function's name, description and input.

可以将支持 工具调用 的工具传递给 聊天模型，从而使模型能够请求使用特定输入执行特定函数。

¥Tools can be passed to chat models that support tool calling allowing the model to request the execution of a specific function with specific inputs.

关键概念​

¥Key concepts

  • 工具是一种封装函数及其模式的方法，以便将其传递给聊天模型。

    ¥Tools are a way to encapsulate a function and its schema in a way that can be passed to a chat model.

  • 使用 tool 函数创建工具，该函数简化了工具创建过程，并支持以下功能：

    ¥Create tools using the tool function, which simplifies the process of tool creation, supporting the following:

    • 定义返回结果（例如图片等）的工具

      ¥Defining tools that return artifacts (e.g. images, etc.)

    • 使用注入的工具参数从架构（以及模型）中隐藏输入参数。

      ¥Hiding input arguments from the schema (and hence from the model) using injected tool arguments.

工具接口​

¥Tool interface

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

¥The tool interface is defined in the StructuredTool class which is a subclass of the Runnable Interface.

与工具架构对应的关键属性：

¥The key attributes that correspond to the tool's schema:

  • 名称：工具的名称。

    ¥name: The name of the tool.

  • 描述：工具功能描述。

    ¥description: A description of what the tool does.

  • args:返回工具参数的 JSON 模式的属性。

    ¥args: Property that returns the JSON schema for the tool's arguments.

执行与工具相关的功能的关键方法：

¥The key methods to execute the function associated with the tool:

  • 调用：使用给定的参数调用工具。

    ¥invoke: Invokes the tool with the given arguments.

使用 tool 函数创建工具​

¥Create tools using the tool function

创建工具的推荐方法是使用 tool 函数。此函数旨在简化工具创建过程，在大多数情况下都应使用。

¥The recommended way to create tools is using the tool function. This function is designed to simplify the process of tool creation and should be used in most cases.

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

const multiply = tool(
  ({ a, b }: { a: number; b: number }): number => {
    /**

     * Multiply two numbers.
     */
    return a * b;
  },
  {
    name: "multiply",
    description: "Multiply two numbers",
    schema: z.object({
      a: z.number(),
      b: z.number(),
    }),
  }
);

有关如何创建支持向量字段的搜索索引的更多详细信息，请参阅文档：

¥For more details on how to create tools, see the how to create custom tools guide.

note

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

¥LangChain has a few other ways to create tools; e.g., by sub-classing the StructuredTool class or by using StructuredTool. These methods are shown in the how to create custom tools guide, but we generally recommend using the tool function for most cases.

直接使用该工具​

¥Use the tool directly

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

¥Once you have defined a tool, you can use it directly by calling the function. For example, to use the multiply tool defined above:

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

检查​

¥Inspect

你还可以检查该工具的模式和其他属性：

¥You can also inspect the tool's schema and other properties:

console.log(multiply.name); // multiply
console.log(multiply.description); // Multiply two numbers.
note

如果你使用的是预构建的 LangChain 或 LangGraph 组件（例如 createReactAgent），则可能无需直接与工具交互。但是，了解如何使用它们对于调试和测试非常有帮助。此外，在构建自定义 LangGraph 工作流时，你可能需要直接使用工具。

¥If you're using pre-built LangChain or LangGraph components like createReactAgent,you might not need to interact with tools directly. However, understanding how to use them can be valuable for debugging and testing. Additionally, when building custom LangGraph workflows, you may find it necessary to work with tools directly.

配置模式​

¥Configuring the schema

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

¥The tool function offers additional options to configure the schema of the tool (e.g., modify name, description or parse the function's doc-string to infer the schema).

请参阅 工具的 API 参考 了解更多详情，并查看 如何创建自定义工具 指南中的示例。

¥Please see the API reference for tool for more details and review the how to create custom tools guide for examples.

工具构件​

¥Tool artifacts

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

¥Tools are utilities that can be called by a model, and whose outputs are designed to be fed back to a model. Sometimes, however, there are artifacts of a tool's execution that we want to make accessible to downstream components in our chain or agent, but that we don't want to expose to the model itself. For example if a tool returns a custom object, a dataframe or an image, we may want to pass some metadata about this output to the model without passing the actual output to the model. At the same time, we may want to be able to access this full output elsewhere, for example in downstream tools.

const someTool = tool(({ ... }) => {
    // do something
}, {
  // ... tool schema args
  // Set the returnType to "content_and_artifact"
  responseFormat: "content_and_artifact"
});

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

¥See how to return artifacts from tools for more details.

RunnableConfig​

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

¥You can use the RunnableConfig object to pass custom run time values to tools.

如果你需要从工具内部访问 RunnableConfig 对象。这可以通过在工具的函数签名中使用 RunnableConfig 来实现。

¥If you need to access the RunnableConfig object from within a tool. This can be done by using the RunnableConfig in the tool's function signature.

import { RunnableConfig } from "@langchain/core/runnables";

const someTool = tool(
    async (args: any, config: RunnableConfig): Promise<[string, any]> => {
        /**

         * Tool that does something.
         */
    },
    {
        name: "some_tool",
        description: "Tool that does something",
        schema: z.object({ ... }),
        returnType: "content_and_artifact"
    }
);


await someTool.invoke(..., { configurable: { value: "some_value" } });

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

¥The config will not be part of the tool's schema and will be injected at runtime with appropriate values.

最佳实践​

¥Best practices

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

¥When designing tools to be used by models, keep the following in mind:

  • 命名规范、文档正确且类型提示正确的工具更易于模型使用。

    ¥Tools that are well-named, correctly-documented and properly type-hinted are easier for models to use.

  • 设计简单且范围狭窄的工具，因为它们更容易被模型正确使用。

    ¥Design simple and narrowly scoped tools, as they are easier for models to use correctly.

  • 使用支持 tool-calling API 的聊天模型来充分利用工具。

    ¥Use chat models that support tool-calling APIs to take advantage of tools.

工具包​

¥Toolkits

LangChain 拥有工具包的概念。这是一个非常精简的抽象，它将旨在一起用于特定任务的工具组合在一起。

¥LangChain has a concept of toolkits. This a very thin abstraction that groups tools together that are designed to be used together for specific tasks.

接口​

¥Interface

所有工具包都公开一个 getTools 方法，该方法返回一个工具列表。因此，你可以执行以下操作：

¥All Toolkits expose a getTools method which returns a list of tools. You can therefore do:

// Initialize a toolkit
const toolkit = new ExampleTookit(...)

// Get list of tools
const tools = toolkit.getTools()

¥Related resources

查看以下资源了解更多信息：

¥See the following resources for more information: