You are viewing the v1 docs for LangChain, which is currently under active development. Learn more.

​
Overview

Tools are components that Agents call to perform actions. They extend a model’s capabilities beyond text by letting it interact with the world through well-defined inputs and outputs.

​
Creating tools

​
Basic tool definition

The simplest way to create a tool is by importing the tool function from the langchain package. You can use zod to define the tool’s input schema: 
import { z } from "zod"
import { tool } from "langchain"

const searchDatabase = tool(
  ({ query, limit }) => {
    return `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")
    })
  }
);
Alternatively, you can define the schema property as a JSON schema object: 
const searchDatabase = tool(
  (input) => {
    const { query, limit } = input as { query: string, limit: number }
    return `Found ${limit} results for '${query}'`
  },
  {
    name: "search_database",
    description: "Search the customer database for records matching the query.",
    schema: {
      type: "object",
      properties: {
        query: { type: "string", description: "Search terms to look for" },
        limit: { type: "number", description: "Maximum number of results to return" }
      },
      required: ["query", "limit"]
    }
  }
);

​
Using tools with agents

Agents go beyond simple tool binding by adding reasoning loops, state management, and multi-step execution.
To see examples of how to use tools with agents, see Agents.

​
Advanced tool patterns

​
ToolNode

ToolNode is a prebuilt LangGraph component that handles tool calls within an agent’s workflow. It works seamlessly with createAgent(), offering advanced tool execution control, built in parallelism, and error handling.

​
Configuration options

ToolNode accepts the following parameters: 
import { ToolNode } from "langchain"

const toolNode = new ToolNode([searchDatabase, calculate], {
  name: "tools",
  tags: ["tool-execution"],
  handleToolErrors: true
})
​
tools
A list of LangChain tool objects.
​
handleToolErrors
Controls how tool execution failures are handled. Can be:
  • boolean
    • ((error: unknown, toolCall: ToolCall) => ToolMessage | undefined)
See Error handling strategies below for details. Default: true

​
Error handling strategies

ToolNode provides built-in error handling for tool execution through its handleToolErrors property. To customize the error handling behavior, you can configure handleToolErrors to either be a boolean or a custom error handler function:
  • true: Catch all errors and return a ToolMessage with the default error template containing the exception details. (default)
  • false: Disable error handling entirely, allowing exceptions to propagate.
  • ((error: unknown, toolCall: ToolCall) => ToolMessage | undefined): Catch all errors and return a ToolMessage with the result of calling the function with the exception.
Examples of how to use the different error handling strategies: 
const toolNode = new ToolNode([my_tool], {
  handleToolErrors: true
})

const toolNode = new ToolNode([my_tool], {
  handleToolErrors: (error, toolCall) => {
    return new ToolMessage({
      content: "I encountered an issue. Please try rephrasing your request.",
      tool_call_id: toolCall.id
    })
  }
})

​
Using with createAgent()

Pass a configured ToolNode directly to createAgent(): 
import { z } from "zod"
import { ChatOpenAI } from "@langchain/openai"
import { ToolNode, createAgent } from "langchain"

const searchDatabase = tool(
  ({ query }) => {
    return `Results for: ${query}`
  },
  {
    name: "search_database",
    description: "Search the database.",
    schema: z.object({
      query: z.string().describe("The query to search the database with")
    })
  }
);

const sendEmail = tool(
  ({ to, subject, body }) => {
    return `Email sent to ${to}`
  },
  {
    name: "send_email",
    description: "Send an email.",
    schema: z.object({
      to: z.string().describe("The email address to send the email to"),
      subject: z.string().describe("The subject of the email"),
      body: z.string().describe("The body of the email")
    })
  }
);

// Configure ToolNode with custom error handling
const toolNode = new ToolNode([searchDatabase, sendEmail], {
  name: "email_tools",
  handleToolErrors: (error, toolCall) => {
    return new ToolMessage({
      content: "I encountered an issue. Please try rephrasing your request.",
      tool_call_id: toolCall.id
    });
  }
});

// Create agent with the configured ToolNode
const agent = createAgent({
  model: new ChatOpenAI({ model: "gpt-5" }),
  tools: toolNode,  // Pass ToolNode instead of tools list
  prompt: "You are a helpful email assistant."
});

// The agent will use your custom ToolNode configuration
const result = await agent.invoke({
  messages: [
    { role: "user", content: "Search for John and email him" }
  ]
})
When you pass a ToolNode to createAgent(), the agent uses your exact configuration including error handling, custom names, and tags. This is useful when you need fine-grained control over tool execution behavior.

​
Accessing runtime context inside a tool

runtime: The execution environment of your agent, containing immutable configuration and contextual data that persists throughout the agent’s execution (e.g., user IDs, session details, or application-specific configuration).
Tools can access an agent’s runtime context through the config parameter: 
import { z } from "zod"
import { ChatOpenAI } from "@langchain/openai"
import { ToolNode, 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-4o" }),
  tools: [getUserName],
  contextSchema,
})

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

​
Accessing long-term memory inside a tool

store: LangChain’s persistence layer. An agent’s long-term memory store, e.g. user-specific or application-specific data stored across conversations.
You can initialize an InMemoryStore to store long-term memory: 
import { z } from "zod";
import { createAgent, InMemoryStore } from "langchain";
import { ChatOpenAI } from "@langchain/openai";

const store = new InMemoryStore();

const getUserInfo = tool(
  ({ user_id }) => {
    return store.get(["users"], user_id)
  },
  {
    name: "get_user_info",
    description: "Look up user info.",
    schema: z.object({
      user_id: z.string()
    })
  }
);

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

​
Updating long-term memory inside a tool

To update long-term memory, you can use the .put() method of InMemoryStore. A complete example of persistent memory across sessions: 
import { z } from "zod";
import { createAgent, tool, InMemoryStore } from "langchain";
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 ({ name, age, email }) => {
    console.log("save_user_info", name, age, email);
    await store.put(["users"], name, { name, age, email });
    return "Successfully saved user info.";
  },
  {
    name: "save_user_info",
    description: "Save user info.",
    schema: z.object({
      name: z.string(),
      age: z.number(),
      email: z.string(),
    }),
  }
);

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

// First session: save user info
await agent.invoke({
  messages: [
    {
      role: "user",
      content:
        "Save the following user: userid: abc123, name: Foo, age: 25, email: foo@langchain.dev",
    },
  ],
});

// Second session: get user info
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