Tools

---
title: 工具
---

import ToolReturnValuesPy from '/snippets/javascript/code-samples/tool-return-values-py.mdx';
import ToolReturnValuesJs from '/snippets/javascript/code-samples/tool-return-values-js.mdx';
import ToolReturnObjectPy from '/snippets/javascript/code-samples/tool-return-object-py.mdx';
import ToolReturnObjectJs from '/snippets/javascript/code-samples/tool-return-object-js.mdx';
import ToolReturnCommandPy from '/snippets/javascript/code-samples/tool-return-command-py.mdx';
import ToolReturnCommandJs from '/snippets/javascript/code-samples/tool-return-command-js.mdx';
import ToolReturnDirectPy from '/snippets/javascript/code-samples/tool-return-direct-py.mdx';
import ToolReturnDirectJs from '/snippets/javascript/code-samples/tool-return-direct-js.mdx';
import ToolUpdateStatePy from '/snippets/javascript/code-samples/tool-update-state-py.mdx';
import ToolErrorHandlingPy from '/snippets/javascript/code-samples/tool-error-handling-py.mdx';
import ToolErrorHandlingJs from '/snippets/javascript/code-samples/tool-error-handling-js.mdx';
import ToolRuntimeContextThreadJs from '/snippets/javascript/code-samples/tool-runtime-context-thread-js.mdx';
import ToolRuntimeContextThreadPy from '/snippets/javascript/code-samples/tool-runtime-context-thread-py.mdx';

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

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

<Tip>
有关模型如何处理工具调用的详细信息，请参阅[工具调用](/oss/javascript/langchain/models#tool-calling)。使用 [LangSmith](https://smith.langchain.com) 追踪工具调用和调试错误。请按照[追踪快速入门](/langsmith/trace-with-langchain)进行设置。

我们建议您同时设置 [LangSmith Engine](/langsmith/engine)，它可以监控您的追踪、检测问题并提出修复建议。
</Tip>

## 创建工具

### 基本工具定义



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

```ts
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、会话详情或应用程序特定设置等在对话过程中不应更改的信息。

虽然 thread_id（通过 config={"configurable": {"thread_id": ...}} 传递）界定对话：消息历史和检查点，但 context 携带的是你的工具和中间件在调用时读取的每次运行数据。在生产环境中，你通常同时传递两者：每个对话一个稳定的 thread_id，以及每次调用时传递一个 context 对象。

工具可以通过 config 参数访问智能体的运行时上下文。将 context 与 thread_id 一起传递，以便对话在多轮次间得以持久化：

长期记忆 (存储)

@[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.5" }),
  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(`Looking up data for city: ${city}`);
      writer(`Acquired data for city: ${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(`Thread: ${info.threadId}, Run: ${info.runId}`);
    console.log(`Attempt: ${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(`Assistant: ${server.assistantId}, Graph: ${server.graphId}`);
      if (server.user != null) {
        console.log(`User: ${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] 处理。有关 Graph API 的使用，包括工具如何访问当前图状态和运行作用域上下文，请参阅 ToolNode。

工具返回值

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

返回 string 以提供人类可读的结果。
返回 object 以提供模型应解析的结构化结果。
返回带有可选消息的 Command，以便在需要写入状态时使用。

返回字符串

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

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

当结果是自然可读文本时使用此方法。

返回对象

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

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

当后续推理受益于显式字段而不是自由形式文本时，使用此方法。

返回多模态内容

工具不限于纯文本。当模型支持多模态工具结果时，工具可以返回标准内容块，以便模型在一个工具结果中接收文本、图像和其他媒体。

import { tool } from "langchain";
import { z } from "zod";

const captureScreenshot = tool(
  async () => [
    { type: "text", text: "Screenshot of the current page:" },
    { type: "image", url: "https://example.com/page.png" },
  ],
  {
    name: "capture_screenshot",
    description: "Capture a screenshot of the current page.",
    schema: z.object({}),
  }
);

行为：

返回值被转换为具有多模态 content 的 ToolMessage。
工具运行后，使用 message.content_blocks 读取规范化的块列表。
模型必须支持你返回的模态。在返回图像、音频或视频之前，请检查你的模型能力。

有关块类型和提供商特定要求，请参阅多模态消息。返回图像或混合内容的 MCP 工具以相同方式转换；请参阅多模态工具内容。

返回 Command

当工具需要更新图状态（例如设置用户偏好或应用程序状态）时，返回 @[Command]。你可以返回带有或不带有 ToolMessage 的 Command。如果模型需要看到工具成功（例如，确认偏好已更改），请在更新中包含一个 ToolMessage，并使用 runtime.tool_call_id 作为 tool_call_id 参数。行为：

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

当工具不仅返回数据，而且还改变智能体状态时，使用此方法。

直接从工具返回

在工具上设置直接返回，以短路智能体循环：智能体立即将工具的输出返回给调用者，而无需将其发送回模型进行进一步处理。 ::> 行为：

工具正常执行，其输出被包装在 ToolMessage 中。
智能体停止循环并直接返回工具的输出作为最终响应，绕过任何额外的模型调用。
如果模型在单一轮次中调用多个工具，只有当所有被调用的工具都设置了 return_direct=True 时，return_direct 才会生效。

在以下情况下使用此方法：

工具的输出是完整、可直接展示给用户的答案（例如，返回可直接显示的结果的查找）。
当不需要额外推理时，你想避免额外的模型调用。
你需要确定性的、未修改的输出——模型无法对工具结果进行重述、总结或操作。

由于模型不处理工具的输出，return_direct=True 不适用于结果需要进一步推理、总结或与其他工具调用链接的工具。

错误处理

使用 LangChain 智能体中间件处理工具错误，以重试失败的工具调用或返回自定义错误消息： python :::

状态注入

工具通过 @[ToolRuntime] 访问图状态。有关状态、上下文、存储和流式 API 的信息，请参阅访问上下文。有关从工具访问状态、上下文和长期记忆的更多详细信息，请参阅访问上下文。

动态工具选择

使用动态工具，智能体可用的工具集是在运行时修改的，而不是预先全部定义好的。并非每个工具都适用于每种情况。工具过多可能会使模型不堪重负（上下文过载）并增加错误；工具过少则限制了能力。动态工具选择使得能够根据认证状态、用户权限、功能标志或对话阶段来调整可用的工具集。根据工具是否预先已知，有两种方法：

过滤预注册的工具
运行时工具注册

当所有可能的工具在智能体创建时都已知，你可以预先注册它们，并根据状态、权限或上下文动态过滤哪些工具暴露给模型。

状态
存储
运行时上下文

仅在达到特定对话里程碑后才启用高级工具：

import { createMiddleware, tool } from "langchain";
import { createDeepAgent } from "deepagents";

const stateBasedTools = createMiddleware({
    name: "StateBasedTools",
    wrapModelCall: (request, handler) => {
        // 从状态读取：检查认证和对话长度
        const state = request.state as typeof request.state & {
            authenticated?: boolean;
        };
        const isAuthenticated = state.authenticated ?? false;
        const messageCount = state.messages.length;

        let filteredTools = request.tools;

        // 仅在认证后启用敏感工具
        if (!isAuthenticated) {
            filteredTools = request.tools.filter(
                (t: any) => typeof t.name === "string" && t.name.startsWith("public_"),
            );
        } else if (messageCount < 5) {
            filteredTools = request.tools.filter(
                (t: any) => typeof t.name === "string" && t.name !== "advanced_search",
            );
        }

        return handler({ ...request, tools: filteredTools });
    },
});

const agent = await createDeepAgent({
    model: "claude-sonnet-4-6",
    tools: tools,
    middleware: [stateBasedTools] as any,
});

根据存储中的用户偏好或功能标志过滤工具：

import { createMiddleware } from "langchain";
import { createDeepAgent, StoreBackend } from "deepagents";
import * as z from "zod";
import { InMemoryStore } from "@langchain/langgraph";

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

const storeBasedTools = createMiddleware({
  name: "StoreBasedTools",
  contextSchema,
  wrapModelCall: async (request, handler) => {
    const userId =
      (request.runtime?.context as { userId?: string } | undefined)?.userId ??
        "user-123";

    // 从存储读取：获取用户启用的功能
    const runtimeStore = request.runtime?.store as InMemoryStore | undefined;
    const rawFlags = (await runtimeStore?.get(
      ["features"],
      userId as string,
    )) as unknown;
    const featureFlags = rawFlags as FeatureFlags | undefined;

    let filteredTools = request.tools;

    if (featureFlags) {
      const enabledFeatures = featureFlags.enabledTools || [];
      filteredTools = request.tools.filter((t) =>
        enabledFeatures.includes(t.name as string)
      );
    }

    return handler({ ...request, tools: filteredTools });
  },
});

const agent = await createDeepAgent({
  model: "claude-sonnet-4-6",
  backend: new StoreBackend(),
  store,
  checkpointer,
  tools,
  middleware: [storeBasedTools] as any,
});

根据运行时上下文中的用户权限过滤工具：

import * as z from "zod";
import { createMiddleware } from "langchain";
import { createDeepAgent } from "deepagents";

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

const contextBasedTools = createMiddleware({
  name: "ContextBasedTools",
  contextSchema,
  wrapModelCall: (request, handler) => {
    // 从运行时上下文读取：获取用户角色
    const userRole = request.runtime.context.userRole;

    let filteredTools = request.tools;

    if (userRole === "admin") {
      // 管理员获得所有工具
    } else if (userRole === "editor") {
      filteredTools = request.tools.filter((t) => t.name !== "delete_data");
    } else {
      filteredTools = request.tools.filter(
        (t) => (t.name as string).startsWith("read_"),
      );
    }

    return handler({ ...request, tools: filteredTools });
  },
});

const agent = await createDeepAgent({
  model: "claude-sonnet-4-6",
  store,
  checkpointer,
  tools,
  middleware: [contextBasedTools] as any,
});

这种方法在以下情况最为适用：

所有可能的工具在编译/启动时都已知
你想根据权限、功能标志或对话状态进行过滤
工具是静态的，但其可用性是动态的

更多示例请参阅动态选择工具。

当工具在运行时被发现或创建（例如，从 MCP 服务器加载、基于用户数据生成或从远程注册表获取）时，你需要同时注册这些工具并动态处理它们的执行。这需要两个中间件钩子：

wrap_model_call - 将动态工具添加到请求中
wrap_tool_call - 处理动态添加的工具的执行

import { createAgent, createMiddleware, tool } from "langchain";
import * as z from "zod";

// 一个将在运行时动态添加的工具
const calculateTip = tool(
  ({ billAmount, tipPercentage = 20 }) => {
    const tip = billAmount * (tipPercentage / 100);
    return `Tip: $${tip.toFixed(2)}, Total: $${(billAmount + tip).toFixed(2)}`;
  },
  {
    name: "calculate_tip",
    description: "Calculate the tip amount for a bill",
    schema: z.object({
      billAmount: z.number().describe("The bill amount"),
      tipPercentage: z.number().default(20).describe("Tip percentage"),
    }),
  }
);

const dynamicToolMiddleware = createMiddleware({
  name: "DynamicToolMiddleware",
  wrapModelCall: (request, handler) => {
    // 将动态工具添加到请求
    // 这可以从 MCP 服务器、数据库等加载
    return handler({
      ...request,
      tools: [...request.tools, calculateTip],
    });
  },
  wrapToolCall: (request, handler) => {
    // 处理动态工具的执行
    if (request.toolCall.name === "calculate_tip") {
      return handler({ ...request, tool: calculateTip });
    }
    return handler(request);
  },
});

const agent = createAgent({
  model: "gpt-5.5",
  tools: [getWeather], // 这里只注册静态工具
  middleware: [dynamicToolMiddleware],
});

// 现在智能体可以使用 getWeather 和 calculateTip 了
const result = await agent.invoke({
  messages: [{ role: "user", content: "Calculate a 20% tip on $85" }],
});

这种方法在以下情况最为适用：

工具在运行时被发现（例如，来自 MCP 服务器）
工具基于用户数据或配置动态生成
你正在与外部工具注册表集成

对于运行时注册的工具，wrap_tool_call 钩子是必需的，因为智能体需要知道如何执行最初不在工具列表中的工具。没有它，智能体将不知道如何调用动态添加的工具。

无头工具

某些工具应该在用户应用程序运行的地方（通常是浏览器）运行，而不是在服务器进程内部运行。无头工具是你在服务器上用智能体注册的工具定义，包括名称、描述和参数模式。实现仅在客户端注册，并在短暂的中断/恢复握手后执行。这与普通工具（其函数体在服务器上运行）和服务器端工具使用（模型提供商远程执行内置工具）不同。

何时使用无头工具

当工作依赖于仅存在于客户端的环境、设备或 UI 时，使用它们。例如：

浏览器 API： 地理位置、IndexedDB、剪贴板、Canvas 2D、文件选择器、电池 API 等。
隐私和本地性： 数据保留在设备上（例如，IndexedDB 中的本地“内存”）。
延迟： 对于纯本地操作，无需额外的服务器往返。
结构化、安全的操作： 优先使用许多小型、类型化的工具（例如，每个 Canvas 图元一个工具），而不是向 eval 发送任意代码。

模式如何工作

在两种运行时中，模型看到一个它可以调用的普通工具，但实际执行发生在服务器进程之外。

定义工具，使用 langchain 中的 tool({ name, description, schema })，仅包含元数据和验证，没有服务器端运行器。
附加真实行为，使用 .implement(async (args) => { ... })，它返回一个无头工具实现（定义 + execute 函数）。
注册步骤 1 中的定义到 createAgent 或你的图，这样模型就能在正常的工具调用循环中看到该工具。
传递步骤 2 中的实现到你的流式钩子的 tools 选项。

将工具定义（tool({ name, description, schema })）和实现（.implement(...)）放在单独的模块中。从你的服务器智能体和前端导入共享的定义文件，这样名称和模式保持一致；将仅限客户端的执行逻辑放在实现模块中，服务器永远不会加载它们。

当模型为这些工具发出工具调用时，运行会中断，而不是在本地执行工具。你的应用程序可以检查载荷，在正确的环境中（例如浏览器、另一个服务或人工审查步骤）执行操作，然后用工具结果恢复图。当你使用支持的 JS SDK 钩子时，它们可以检测无头工具中断，运行匹配的客户端实现，并为你提交恢复命令。使用可选的 onTool 回调来观察生命周期事件（start、success、error），以便为 UI 反馈（如加载指示器或提示信息）提供支持。

无头工具前端模式

查看一个使用 useStream 在客户端执行的仅包含模式工具的端到端示例。

预构建工具

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

服务器端工具使用

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

---

<div className="source-links">
<Callout icon="terminal-2">
    [Connect these docs](/use-these-docs) to Claude, VSCode, and more via MCP for real-time answers.
</Callout>
<Callout icon="edit">
    [Edit this page on GitHub](https://github.com/langchain-ai/docs/edit/main/src/oss/langchain/tools.mdx) or [file an issue](https://github.com/langchain-ai/docs/issues/new/choose).
</Callout>
</div>

Get started

Core components

Middleware

Frontend

Advanced usage

Agent development

Production

访问上下文

上下文

长期记忆 (存储)

流写入器

执行信息

服务器信息

工具执行

工具返回值

返回字符串

返回对象

返回多模态内容

返回 Command

直接从工具返回

错误处理

状态注入

动态工具选择

无头工具

何时使用无头工具

模式如何工作

无头工具前端模式

预构建工具

服务器端工具使用

​访问上下文

​上下文

​长期记忆 (存储)

​流写入器

​执行信息

​服务器信息

​工具执行

​工具返回值

​返回字符串

​返回对象

​返回多模态内容

​返回 Command

​直接从工具返回

​错误处理

​状态注入

​动态工具选择

​无头工具

​何时使用无头工具

​模式如何工作

无头工具前端模式

​预构建工具

​服务器端工具使用

访问上下文

上下文

长期记忆 (存储)

流写入器

执行信息

服务器信息

工具执行

工具返回值

返回字符串

返回对象

返回多模态内容

返回 Command

直接从工具返回

错误处理

状态注入

动态工具选择

无头工具

何时使用无头工具

模式如何工作

预构建工具

服务器端工具使用