工具 - Docs by LangChain

工具扩展了智能体的能力——让它们能够获取实时数据、执行代码、查询外部数据库并在现实世界中执行操作。在底层，工具是具有明确定义的输入和输出的可调用函数，会被传递给聊天模型。模型根据对话上下文决定何时调用工具以及提供什么输入参数。

有关模型如何处理工具调用的详情，请参阅工具调用。使用 LangSmith 追踪工具调用和调试错误——按照追踪快速入门进行设置。

创建工具

基础工具定义

创建工具最简单的方式是从 langchain 包导入 tool 函数。你可以使用 zod 来定义工具的输入模式：

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"),
    }),
  }
);

服务端工具使用： 某些聊天模型具有内置工具（网络搜索、代码解释器），这些工具在服务端执行。请参阅服务端工具使用了解详情。

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

访问上下文

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

上下文

上下文提供在调用时传递的不可变配置数据。用于用户 ID、会话详情或在对话期间不应更改的应用特定设置。工具可以通过 config 参数访问智能体的运行时上下文：

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 提供跨对话持久化的存储。与状态（短期记忆）不同，保存到存储的数据在未来的会话中仍然可用。通过 config.store 访问存储。存储使用命名空间/键模式来组织数据：

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 来发送自定义更新：

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 和重试状态：

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}`);
    console.log(`尝试次数: ${info.nodeAttempt}`);
    return "done";
  },
  {
    name: "log_execution_context",
    description: "Log execution identity information.",
    schema: z.object({}),
  }
);

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

服务器信息

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

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}`);
      if (server.user != null) {
        console.log(`用户: ${server.user.identity}`);
      }
    }
    return "done";
  },
  {
    name: "get_assistant_scoped_data",
    description: "Fetch data scoped to the current assistant.",
    schema: z.object({}),
  }
);

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

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

工具执行

在 LangChain 中，工具由智能体使用（例如通过 create_agent），工具错误处理通过中间件配置。对于 LangGraph 工作流，工具执行由 ToolNode 处理。请参阅 ToolNode。

工具返回值

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

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

返回字符串

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

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）。

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。你可以返回带有或不带有 ToolMessage 的 Command。如果模型需要看到工具成功执行（例如确认偏好更改），在更新中包含一个 ToolMessage，使用 runtime.tool_call_id 作为 tool_call_id 参数。

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 智能体中间件处理工具错误，重试失败的工具调用或返回自定义错误消息：

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],
});

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],
});

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],
});

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],
});

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],
});

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],
});

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],
});

状态注入

工具可以通过 ToolRuntime 访问当前图状态：有关从工具访问状态、上下文和长期记忆的更多详情，请参阅访问上下文。

预构建工具

LangChain 提供了大量预构建工具和工具包，用于网络搜索、代码解释、数据库访问等常见任务。这些即用型工具可以直接集成到你的智能体中，无需编写自定义代码。请参阅工具和工具包集成页面获取按类别组织的完整可用工具列表。

服务端工具使用

某些聊天模型具有由模型提供商在服务端执行的内置工具。这些工具包括网络搜索和代码解释器等功能，不需要你定义或托管工具逻辑。请参阅各个聊天模型集成页面和工具调用文档了解启用和使用这些内置工具的详情。

连接这些文档到 Claude、VSCode 等，通过 MCP 获取实时答案。

在 GitHub 上编辑此页面或提交 Issue。

Get started

Core components

Middleware

Frontend

Advanced usage

Agent development

Deploy with LangSmith

工具

创建工具

基础工具定义

访问上下文

上下文

长期记忆（Store）

流式写入器

执行信息

服务器信息

工具执行

工具返回值

返回字符串

返回对象

返回 Command

错误处理

状态注入

预构建工具

服务端工具使用

​创建工具

​基础工具定义

​访问上下文

​上下文

​长期记忆（Store）

​流式写入器

​执行信息

​服务器信息

​工具执行

​工具返回值

​返回字符串

​返回对象

​返回 Command

​错误处理

​状态注入

​预构建工具

​服务端工具使用

创建工具

基础工具定义

访问上下文

上下文

长期记忆（Store）

流式写入器

执行信息

服务器信息

工具执行

工具返回值

返回字符串

返回对象

返回 Command

错误处理

状态注入

预构建工具

服务端工具使用