Skip to main content
工具扩展了 代理 的功能——让它们能够获取实时数据、执行代码、查询外部数据库以及在现实世界中采取行动。 在底层，工具是具有定义明确的输入和输出的可调用函数，它们被传递给 聊天模型。模型根据对话上下文决定何时调用工具，以及提供什么输入参数。
有关模型如何处理工具调用的详细信息，请参阅 工具调用。

​
创建工具

​
基本工具定义

创建工具的最简单方法是从 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-4.1" }),
  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-4.1" }),
  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);
// Here is the user info for user with ID "abc123":
// - Name: Foo
// - Age: 25
// - Email: 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(),
    }),
  }
);

​
ToolNode

ToolNode 是一个预构建节点，用于在 LangGraph 工作流中执行工具。它自动处理并行工具执行、错误处理和状态注入。
对于需要对工具执行模式进行细粒度控制的自定义工作流，请使用 ToolNode 而不是 @[create_agent]。它是支持代理工具执行的构建块。

​
基本用法

import { ToolNode } from "@langchain/langgraph/prebuilt";
import { tool } from "@langchain/core/tools";
import * as z from "zod";

const search = tool(
  ({ query }) => `Results for: ${query}`,
  {
    name: "search",
    description: "Search for information.",
    schema: z.object({ query: z.string() }),
  }
);

const calculator = tool(
  ({ expression }) => String(eval(expression)),
  {
    name: "calculator",
    description: "Evaluate a math expression.",
    schema: z.object({ expression: z.string() }),
  }
);

// 使用你的工具创建 ToolNode
const toolNode = new ToolNode([search, calculator]);

​
错误处理

配置如何处理工具错误。请参阅 ToolNode API 参考以获取所有选项。 
import { ToolNode } from "@langchain/langgraph/prebuilt";

// 默认行为
const toolNode = new ToolNode(tools);

// 捕获所有错误
const toolNode = new ToolNode(tools, { handleToolErrors: true });

// 自定义错误消息
const toolNode = new ToolNode(tools, {
  handleToolErrors: "Something went wrong, please try again."
});

​
使用 tools_condition 路由

使用 @[tools_condition] 根据 LLM 是否进行工具调用来进行条件路由： 
import { ToolNode, toolsCondition } from "@langchain/langgraph/prebuilt";
import { StateGraph, MessagesAnnotation } from "@langchain/langgraph";

const builder = new StateGraph(MessagesAnnotation)
  .addNode("llm", callLlm)
  .addNode("tools", new ToolNode(tools))
  .addEdge("__start__", "llm")
  .addConditionalEdges("llm", toolsCondition)  // 路由到 "tools" 或 "__end__"
  .addEdge("tools", "llm");

const graph = builder.compile();

​
状态注入

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

​
预构建工具

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

​
服务器端工具使用

一些聊天模型具有内置工具，这些工具由模型提供商在服务器端执行。这些包括网络搜索和代码解释器等功能，不需要你定义或托管工具逻辑。 有关启用和使用这些内置工具的详细信息，请参阅各个 聊天模型集成页面 和 工具调用文档。
在 GitHub 上编辑此页面 或 提交 issue.
通过 MCP 将 这些文档 连接到 Claude、VSCode 等，以获得实时解答。