> ## Documentation Index
> Fetch the complete documentation index at: https://nvd-54.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 工具

工具扩展了[智能体](/oss/javascript/langchain/agents)的能力——让它们能够获取实时数据、执行代码、查询外部数据库并在现实世界中执行操作。

在底层，工具是具有明确定义的输入和输出的可调用函数，会被传递给[聊天模型](/oss/javascript/langchain/models)。模型根据对话上下文决定何时调用工具以及提供什么输入参数。

<Tip>
  有关模型如何处理工具调用的详情，请参阅[工具调用](/oss/javascript/langchain/models#tool-calling)。使用 [LangSmith](https://smith.langchain.com?utm_source=docs\&utm_medium=cta\&utm_campaign=langsmith-signup\&utm_content=oss-langchain-tools) 追踪工具调用和调试错误——按照[追踪快速入门](/langsmith/trace-with-langchain)进行设置。
</Tip>

## 创建工具

### 基础工具定义

创建工具最简单的方式是从 `langchain` 包导入 `tool` 函数。你可以使用 [zod](https://zod.dev/) 来定义工具的输入模式：

```ts theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import * as z from "zod"
import { tool } from "langchain"

const searchDatabase = tool(
  ({ query, limit }) => `Found ${limit} results for '${query}'`,
  {
    name: "search_database",
    description: "Search the customer database for records matching the query.",
    schema: z.object({
      query: z.string().describe("Search terms to look for"),
      limit: z.number().describe("Maximum number of results to return"),
    }),
  }
);
```

<Note>
  **服务端工具使用：** 某些聊天模型具有内置工具（网络搜索、代码解释器），这些工具在服务端执行。请参阅[服务端工具使用](#server-side-tool-use)了解详情。
</Note>

<Warning>
  工具名称首选 `snake_case`（例如 `web_search` 而不是 `Web Search`）。某些模型提供商对包含空格或特殊字符的名称有问题或会报错。坚持使用字母数字字符、下划线和连字符有助于提高跨提供商的兼容性。
</Warning>

## 访问上下文

当工具可以访问对话历史、用户数据和持久记忆等运行时信息时，它们最为强大。本节介绍如何从工具中访问和更新这些信息。

### 上下文

上下文提供在调用时传递的不可变配置数据。用于用户 ID、会话详情或在对话期间不应更改的应用特定设置。

工具可以通过 `config` 参数访问智能体的运行时上下文：

```ts theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import * as z from "zod"
import { ChatOpenAI } from "@langchain/openai"
import { createAgent } from "langchain"

const getUserName = tool(
  (_, config) => {
    return config.context.user_name
  },
  {
    name: "get_user_name",
    description: "Get the user's name.",
    schema: z.object({}),
  }
);

const contextSchema = z.object({
  user_name: z.string(),
});

const agent = createAgent({
  model: new ChatOpenAI({ model: "gpt-5.4" }),
  tools: [getUserName],
  contextSchema,
});

const result = await agent.invoke(
  {
    messages: [{ role: "user", content: "What is my name?" }]
  },
  {
    context: { user_name: "John Smith" }
  }
);
```

### 长期记忆（Store）

[`BaseStore`](https://reference.langchain.com/javascript/langchain-core/stores/BaseStore) 提供跨对话持久化的存储。与状态（短期记忆）不同，保存到存储的数据在未来的会话中仍然可用。

通过 `config.store` 访问存储。存储使用命名空间/键模式来组织数据：

```ts expandable theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import * as z from "zod";
import { createAgent, tool } from "langchain";
import { InMemoryStore } from "@langchain/langgraph";
import { ChatOpenAI } from "@langchain/openai";

const store = new InMemoryStore();

// 访问记忆
const getUserInfo = tool(
  async ({ user_id }) => {
    const value = await store.get(["users"], user_id);
    console.log("get_user_info", user_id, value);
    return value;
  },
  {
    name: "get_user_info",
    description: "Look up user info.",
    schema: z.object({
      user_id: z.string(),
    }),
  }
);

// 更新记忆
const saveUserInfo = tool(
  async ({ user_id, name, age, email }) => {
    console.log("save_user_info", user_id, name, age, email);
    await store.put(["users"], user_id, { name, age, email });
    return "Successfully saved user info.";
  },
  {
    name: "save_user_info",
    description: "Save user info.",
    schema: z.object({
      user_id: z.string(),
      name: z.string(),
      age: z.number(),
      email: z.string(),
    }),
  }
);

const agent = createAgent({
  model: new ChatOpenAI({ model: "gpt-5.4" }),
  tools: [getUserInfo, saveUserInfo],
  store,
});

// 第一次会话：保存用户信息
await agent.invoke({
  messages: [
    {
      role: "user",
      content: "Save the following user: userid: abc123, name: Foo, age: 25, email: foo@langchain.dev",
    },
  ],
});

// 第二次会话：获取用户信息
const result = await agent.invoke({
  messages: [
    { role: "user", content: "Get user info for user with id 'abc123'" },
  ],
});

console.log(result);
// 以下是 ID 为 "abc123" 的用户信息：
// - 姓名: Foo
// - 年龄: 25
// - 邮箱: foo@langchain.dev
```

### 流式写入器

在工具执行期间流式传输实时更新。这对于在长时间运行的操作中向用户提供进度反馈很有用。

使用 `config.writer` 来发送自定义更新：

```ts theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import * as z from "zod";
import { tool, ToolRuntime } from "langchain";

const getWeather = tool(
  ({ city }, config: ToolRuntime) => {
    const writer = config.writer;

    // 在工具执行时流式传输自定义更新
    if (writer) {
      writer(`正在查找城市数据: ${city}`);
      writer(`已获取城市数据: ${city}`);
    }

    return `It's always sunny in ${city}!`;
  },
  {
    name: "get_weather",
    description: "Get weather for a given city.",
    schema: z.object({
      city: z.string(),
    }),
  }
);
```

### 执行信息

通过 `runtime.execution_info` 从工具内部访问线程 ID、运行 ID 和重试状态：

```ts theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import { tool } from "langchain";
import * as z from "zod";

const logExecutionContext = tool(
  async (_input, runtime) => {
    const info = runtime.executionInfo;
    console.log(`线程: ${info.threadId}, 运行: ${info.runId}`);  // [!code highlight]
    console.log(`尝试次数: ${info.nodeAttempt}`);
    return "done";
  },
  {
    name: "log_execution_context",
    description: "Log execution identity information.",
    schema: z.object({}),
  }
);
```

<Note>
  需要 `deepagents>=1.9.0`（或 `@langchain/langgraph>=1.2.8`）。
</Note>

### 服务器信息

当你的工具在 LangGraph Server 上运行时，通过 `runtime.server_info` 访问助手 ID、图 ID 和已认证的用户：

```ts theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import { tool } from "langchain";
import * as z from "zod";

const getAssistantScopedData = tool(
  async (_input, runtime) => {
    const server = runtime.serverInfo;
    if (server != null) {
      console.log(`助手: ${server.assistantId}, 图: ${server.graphId}`);  // [!code highlight]
      if (server.user != null) {
        console.log(`用户: ${server.user.identity}`);  // [!code highlight]
      }
    }
    return "done";
  },
  {
    name: "get_assistant_scoped_data",
    description: "Fetch data scoped to the current assistant.",
    schema: z.object({}),
  }
);
```

当工具不在 LangGraph Server 上运行时，`serverInfo` 为 `null`。

<Note>
  需要 `deepagents>=1.9.0`（或 `@langchain/langgraph>=1.2.8`）。
</Note>

## 工具执行

在 LangChain 中，工具由智能体使用（例如通过 [`create_agent`](https://reference.langchain.com/javascript/langchain/index/createAgent)），工具错误处理通过[中间件](/oss/javascript/langchain/middleware)配置。

对于 LangGraph 工作流，工具执行由 [`ToolNode`](https://reference.langchain.com/javascript/langchain-langgraph/prebuilt/ToolNode) 处理。请参阅 [ToolNode](/oss/javascript/langgraph/workflows-agents#toolnode)。

### 工具返回值

你可以为工具选择不同的返回值：

* 返回 `string` 用于人类可读的结果。
* 返回 `object` 用于模型应解析的结构化结果。
* 返回 `Command` 并带有可选消息，当你需要写入状态时使用。

#### 返回字符串

当工具应该提供纯文本供模型在下一个响应中读取和使用时，返回字符串。

```ts theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import { tool } from "langchain";
import * as z from "zod";

const getWeather = tool(({ city }) => `It is currently sunny in ${city}.`, {
  name: "get_weather",
  description: "Get weather for a city.",
  schema: z.object({ city: z.string() }),
});
```

行为：

* 返回值被转换为 `ToolMessage`。
* 模型看到该文本并决定下一步操作。
* 除非模型或另一个工具稍后执行，否则不会更改智能体状态字段。

当结果自然是人类可读的文本时使用此方式。

#### 返回对象

当你的工具产生模型应检查的结构化数据时，返回对象（例如 `dict`）。

```ts theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import { tool } from "langchain";
import * as z from "zod";

const getWeatherData = tool(
  ({ city }) => ({
    city,
    temperature_c: 22,
    conditions: "sunny",
  }),
  {
    name: "get_weather_data",
    description: "Get structured weather data for a city.",
    schema: z.object({ city: z.string() }),
  },
);
```

行为：

* 对象被序列化并作为工具输出发送回去。
* 模型可以读取特定字段并对其进行推理。
* 与字符串返回一样，这不会直接更新图状态。

当下游推理从显式字段（而非自由格式文本）中受益时使用此方式。

#### 返回 Command

当工具需要更新图状态（例如设置用户偏好或应用状态）时，返回 [`Command`](https://reference.langchain.com/javascript/langchain-langgraph/index/Command)。
你可以返回带有或不带有 `ToolMessage` 的 `Command`。
如果模型需要看到工具成功执行（例如确认偏好更改），在更新中包含一个 `ToolMessage`，使用 `runtime.tool_call_id` 作为 `tool_call_id` 参数。

```ts theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import { tool, ToolMessage, type ToolRuntime } from "langchain";
import { Command } from "@langchain/langgraph";
import * as z from "zod";

const setLanguage = tool(
  async ({ language }, config: ToolRuntime) => {
    return new Command({
      update: {
        preferredLanguage: language,
        messages: [
          new ToolMessage({
            content: `Language set to ${language}.`,
            tool_call_id: config.toolCallId,
          }),
        ],
      },
    });
  },
  {
    name: "set_language",
    description: "Set the preferred response language.",
    schema: z.object({ language: z.string() }),
  },
);
```

行为：

* 命令使用 `update` 更新状态。
* 更新的状态在同一运行的后续步骤中可用。
* 对可能被并行工具调用更新的字段使用归约器。

当工具不仅返回数据，还要修改智能体状态时使用此方式。

### 错误处理

使用 LangChain 智能体[中间件](/oss/javascript/langchain/middleware)处理工具错误，重试失败的工具调用或返回自定义错误消息：

<CodeGroup>
  ```ts Google theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  import { createAgent, createMiddleware, ToolMessage } from "langchain";

  const handleToolErrors = createMiddleware({
    name: "HandleToolErrors",
    wrapToolCall: async (request, handler) => {
      try {
        return await handler(request);
      } catch (error) {
        return new ToolMessage({
          content: `Tool error: Please check your input and try again. (${error})`,
          tool_call_id: request.toolCall.id!,
        });
      }
    },
  });

  const agent = createAgent({
    model: "google-genai:gemini-3.1-pro-preview",
    tools: [],
    middleware: [handleToolErrors],
  });
  ```

  ```ts OpenAI theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  import { createAgent, createMiddleware, ToolMessage } from "langchain";

  const handleToolErrors = createMiddleware({
    name: "HandleToolErrors",
    wrapToolCall: async (request, handler) => {
      try {
        return await handler(request);
      } catch (error) {
        return new ToolMessage({
          content: `Tool error: Please check your input and try again. (${error})`,
          tool_call_id: request.toolCall.id!,
        });
      }
    },
  });

  const agent = createAgent({
    model: "openai:gpt-5.4",
    tools: [],
    middleware: [handleToolErrors],
  });
  ```

  ```ts Anthropic theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  import { createAgent, createMiddleware, ToolMessage } from "langchain";

  const handleToolErrors = createMiddleware({
    name: "HandleToolErrors",
    wrapToolCall: async (request, handler) => {
      try {
        return await handler(request);
      } catch (error) {
        return new ToolMessage({
          content: `Tool error: Please check your input and try again. (${error})`,
          tool_call_id: request.toolCall.id!,
        });
      }
    },
  });

  const agent = createAgent({
    model: "anthropic:claude-sonnet-4-6",
    tools: [],
    middleware: [handleToolErrors],
  });
  ```

  ```ts OpenRouter theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  import { createAgent, createMiddleware, ToolMessage } from "langchain";

  const handleToolErrors = createMiddleware({
    name: "HandleToolErrors",
    wrapToolCall: async (request, handler) => {
      try {
        return await handler(request);
      } catch (error) {
        return new ToolMessage({
          content: `Tool error: Please check your input and try again. (${error})`,
          tool_call_id: request.toolCall.id!,
        });
      }
    },
  });

  const agent = createAgent({
    model: "openrouter:anthropic/claude-sonnet-4-6",
    tools: [],
    middleware: [handleToolErrors],
  });
  ```

  ```ts Fireworks theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  import { createAgent, createMiddleware, ToolMessage } from "langchain";

  const handleToolErrors = createMiddleware({
    name: "HandleToolErrors",
    wrapToolCall: async (request, handler) => {
      try {
        return await handler(request);
      } catch (error) {
        return new ToolMessage({
          content: `Tool error: Please check your input and try again. (${error})`,
          tool_call_id: request.toolCall.id!,
        });
      }
    },
  });

  const agent = createAgent({
    model: "fireworks:accounts/fireworks/models/qwen3p5-397b-a17b",
    tools: [],
    middleware: [handleToolErrors],
  });
  ```

  ```ts Baseten theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  import { createAgent, createMiddleware, ToolMessage } from "langchain";

  const handleToolErrors = createMiddleware({
    name: "HandleToolErrors",
    wrapToolCall: async (request, handler) => {
      try {
        return await handler(request);
      } catch (error) {
        return new ToolMessage({
          content: `Tool error: Please check your input and try again. (${error})`,
          tool_call_id: request.toolCall.id!,
        });
      }
    },
  });

  const agent = createAgent({
    model: "baseten:zai-org/GLM-5",
    tools: [],
    middleware: [handleToolErrors],
  });
  ```

  ```ts Ollama theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  import { createAgent, createMiddleware, ToolMessage } from "langchain";

  const handleToolErrors = createMiddleware({
    name: "HandleToolErrors",
    wrapToolCall: async (request, handler) => {
      try {
        return await handler(request);
      } catch (error) {
        return new ToolMessage({
          content: `Tool error: Please check your input and try again. (${error})`,
          tool_call_id: request.toolCall.id!,
        });
      }
    },
  });

  const agent = createAgent({
    model: "ollama:devstral-2",
    tools: [],
    middleware: [handleToolErrors],
  });
  ```
</CodeGroup>

### 状态注入

工具可以通过 [`ToolRuntime`](https://reference.langchain.com/javascript/langchain/index/Runtime) 访问当前图状态：

有关从工具访问状态、上下文和长期记忆的更多详情，请参阅[访问上下文](#access-context)。

## 预构建工具

LangChain 提供了大量预构建工具和工具包，用于网络搜索、代码解释、数据库访问等常见任务。这些即用型工具可以直接集成到你的智能体中，无需编写自定义代码。

请参阅[工具和工具包](/oss/javascript/integrations/tools)集成页面获取按类别组织的完整可用工具列表。

## 服务端工具使用

某些聊天模型具有由模型提供商在服务端执行的内置工具。这些工具包括网络搜索和代码解释器等功能，不需要你定义或托管工具逻辑。

请参阅各个[聊天模型集成页面](/oss/javascript/integrations/providers)和[工具调用文档](/oss/javascript/langchain/models#server-side-tool-use)了解启用和使用这些内置工具的详情。

***

<div className="source-links">
  <Callout icon="terminal-2">
    [连接这些文档](/use-these-docs)到 Claude、VSCode 等，通过 MCP 获取实时答案。
  </Callout>

  <Callout icon="edit">
    [在 GitHub 上编辑此页面](https://github.com/langchain-ai/docs/edit/main/src/oss/langchain/tools.mdx)或[提交 Issue](https://github.com/langchain-ai/docs/issues/new/choose)。
  </Callout>
</div>