!function(){function t(t){document.documentElement.setAttribute("data-theme",t)}var e=function(){var t=null;try{t=new URLSearchParams(window.location.search).get("docusaurus-theme")}catch(t){}return t}()||function(){var t=null;try{t=localStorage.getItem("theme")}catch(t){}return t}();t(null!==e?e:"light")}(),document.documentElement.setAttribute("data-announcement-bar-initially-dismissed",function(){try{return"true"===localStorage.getItem("docusaurus.announcement.dismiss")}catch(t){}return!1}())

[Skip to main content](#__docusaurus_skipToContent_fallback)

LangChain v0.2 is coming soon! Preview the new docs [here](/v0.2/docs/introduction/).

[

![🦜️🔗 Langchain](/v0.1/img/brand/wordmark.png)![🦜️🔗 Langchain](/v0.1/img/brand/wordmark-dark.png)

](/v0.1/)[Docs](/v0.1/docs/get_started/introduction/)[Use cases](/v0.1/docs/use_cases/)[Integrations](/v0.1/docs/integrations/platforms/)[API Reference](https://api.js.langchain.com)

[More](#)

*   [People](/v0.1/docs/people/)
*   [Community](/v0.1/docs/community/)
*   [Tutorials](/v0.1/docs/additional_resources/tutorials/)
*   [Contributing](/v0.1/docs/contributing/)

[v0.1](#)

*   [v0.2](https://js.langchain.com/v0.2/docs/introduction)
*   [v0.1](/v0.1/docs/get_started/introduction/)

[🦜🔗](#)

*   [LangSmith](https://smith.langchain.com)
*   [LangSmith Docs](https://docs.smith.langchain.com)
*   [LangChain Hub](https://smith.langchain.com/hub)
*   [LangServe](https://github.com/langchain-ai/langserve)
*   [Python Docs](https://python.langchain.com/)

[Chat](https://chatjs.langchain.com)[](https://github.com/langchain-ai/langchainjs)

Search

*   [Get started](/v0.1/docs/get_started/)
    
    *   [Introduction](/v0.1/docs/get_started/introduction/)
    *   [Installation](/v0.1/docs/get_started/installation/)
    *   [Quickstart](/v0.1/docs/get_started/quickstart/)
*   [LangChain Expression Language](/v0.1/docs/expression_language/)
    
    *   [Get started](/v0.1/docs/expression_language/get_started/)
    *   [Why use LCEL?](/v0.1/docs/expression_language/why/)
    *   [Interface](/v0.1/docs/expression_language/interface/)
    *   [Streaming](/v0.1/docs/expression_language/streaming/)
    *   [How to](/v0.1/docs/expression_language/how_to/routing/)
        
    *   [Cookbook](/v0.1/docs/expression_language/cookbook/)
        
    *   [LangChain Expression Language (LCEL)](/v0.1/docs/expression_language/)
*   [Modules](/v0.1/docs/modules/)
    
    *   [Model I/O](/v0.1/docs/modules/model_io/)
        
        *   [Quickstart](/v0.1/docs/modules/model_io/quick_start/)
        *   [Concepts](/v0.1/docs/modules/model_io/concepts/)
        *   [Prompts](/v0.1/docs/modules/model_io/prompts/)
            
        *   [LLMs](/v0.1/docs/modules/model_io/llms/)
            
        *   [Chat Models](/v0.1/docs/modules/model_io/chat/)
            
            *   [Quick Start](/v0.1/docs/modules/model_io/chat/quick_start/)
            *   [Streaming](/v0.1/docs/modules/model_io/chat/streaming/)
            *   [Caching](/v0.1/docs/modules/model_io/chat/caching/)
            *   [Custom chat models](/v0.1/docs/modules/model_io/chat/custom_chat/)
            *   [Tracking token usage](/v0.1/docs/modules/model_io/chat/token_usage_tracking/)
            *   [Cancelling requests](/v0.1/docs/modules/model_io/chat/cancelling_requests/)
            *   [Dealing with API Errors](/v0.1/docs/modules/model_io/chat/dealing_with_api_errors/)
            *   [Dealing with rate limits](/v0.1/docs/modules/model_io/chat/dealing_with_rate_limits/)
            *   [Tool/function calling](/v0.1/docs/modules/model_io/chat/function_calling/)
            *   [Response metadata](/v0.1/docs/modules/model_io/chat/response_metadata/)
            *   [Subscribing to events](/v0.1/docs/modules/model_io/chat/subscribing_events/)
            *   [Adding a timeout](/v0.1/docs/modules/model_io/chat/timeouts/)
        *   [Model I/O](/v0.1/docs/modules/model_io/)
        *   [Output Parsers](/v0.1/docs/modules/model_io/output_parsers/)
            
    *   [Retrieval](/v0.1/docs/modules/data_connection/)
        
    *   [Chains](/v0.1/docs/modules/chains/)
    *   [Agents](/v0.1/docs/modules/agents/)
        
    *   [More](/v0.1/docs/modules/memory/)
        
*   [Security](/v0.1/docs/security/)
*   [Guides](/v0.1/docs/guides/)
    
*   [Ecosystem](/v0.1/docs/ecosystem/)
    
*   [LangGraph](/v0.1/docs/langgraph/)
*   * * *
    

*   [](/v0.1/)
*   [Modules](/v0.1/docs/modules/)
*   [Model I/O](/v0.1/docs/modules/model_io/)
*   [Chat Models](/v0.1/docs/modules/model_io/chat/)
*   Tool/function calling

On this page

Tool/function calling
=====================

Tool calling allows a model to respond to a given prompt by generating output that matches a user-defined schema. While the name implies that the model is performing some action, this is actually not the case! The model is merely coming up with the arguments to a tool, and actually running a [tool](/v0.1/docs/modules/agents/tools/) (or not) is up to the user. For example, if you want to [extract output matching some schema](/v0.1/docs/use_cases/extraction/) from unstructured text, you could give the model an “extraction” tool that takes parameters matching the desired schema, then treat the generated output as your final result. If you actually do want to execute called tools, you can use the [Tool Calling Agent](/v0.1/docs/modules/agents/agent_types/tool_calling/).

Note that [not all chat models](/v0.1/docs/integrations/chat/) support tool calling currently.

A [tool call object](https://api.js.langchain.com/types/langchain_core_messages_tool.ToolCall.html) includes a `name`, `arguments` option, and an optional `id`.

Many LLM providers, including [Anthropic](/v0.1/docs/integrations/chat/anthropic/), [Google Vertex](/v0.1/docs/integrations/chat/google_vertex_ai/), [Mistral](/v0.1/docs/integrations/chat/mistral/), [OpenAI](/v0.1/docs/integrations/chat/openai/), and others, support variants of a tool calling feature. These features typically allow requests to the LLM to include available tools and their schemas, and for responses to include calls to these tools.

For instance, given a search engine tool, an LLM might handle a query by first calling the search engine tool by generated required parameters in the right format. The system calling the LLM can receive these generated parameters and use them to execute the tool, then the output to the LLM to inform its response. LangChain includes a suite of [built-in tools](/v0.1/docs/integrations/tools/) and supports several methods for defining your own [custom tools](/v0.1/docs/modules/agents/tools/dynamic/). Tool-calling is extremely useful for building [tool-using chains and agents](/v0.1/docs/use_cases/tool_use/), and for getting structured outputs from models more generally.

Providers adopt different conventions for formatting tool schemas and tool calls. For instance, Anthropic returns tool calls as parsed structures within a larger content block:

    [  {    "text": "<thinking>\nI should use a tool.\n</thinking>",    "type": "text"  },  {    "id": "id_value",    "input": { "arg_name": "arg_value" },    "name": "tool_name",    "type": "tool_use"  }]

whereas OpenAI separates tool calls into a distinct parameter, with arguments as JSON strings:

    {  "tool_calls": [    {      "id": "id_value",      "function": {        "arguments": "{\"arg_name\": \"arg_value\"}",        "name": "tool_name"      },      "type": "function"    }  ]}

LangChain implements standard interfaces for defining tools, passing them to LLMs, and representing tool calls.

Passing tools to LLMs[​](#passing-tools-to-llms "Direct link to Passing tools to LLMs")
---------------------------------------------------------------------------------------

Chat models that support tool calling features implement a [`.bindTools()`](https://api.js.langchain.com/classes/langchain_core_language_models_chat_models.BaseChatModel.html#bindTools) method, which receives a list of LangChain [tool objects](https://api.js.langchain.com/classes/langchain_core_tools.StructuredTool.html) and binds them to the chat model in its expected format. Subsequent invocations of the chat model will include tool schemas in its calls to the LLM.

Let’s walk through a few examples. You can use any [tool calling model](/v0.1/docs/integrations/chat/)!

### Pick your chat model:

*   Anthropic
*   OpenAI
*   MistralAI
*   FireworksAI

#### Install dependencies

tip

See [this section for general instructions on installing integration packages](/docs/get_started/installation#installing-integration-packages).

*   npm
*   yarn
*   pnpm

    npm i @langchain/anthropic @langchain/core

    yarn add @langchain/anthropic @langchain/core

    pnpm add @langchain/anthropic @langchain/core

#### Add environment variables

    ANTHROPIC_API_KEY=your-api-key

#### Instantiate the model

    import { ChatAnthropic } from "@langchain/anthropic";const llm = new ChatAnthropic({  model: "claude-3-sonnet-20240229",  temperature: 0});

#### Install dependencies

tip

See [this section for general instructions on installing integration packages](/docs/get_started/installation#installing-integration-packages).

*   npm
*   yarn
*   pnpm

    npm i @langchain/openai @langchain/core

    yarn add @langchain/openai @langchain/core

    pnpm add @langchain/openai @langchain/core

#### Add environment variables

    OPENAI_API_KEY=your-api-key

#### Instantiate the model

    import { ChatOpenAI } from "@langchain/openai";const llm = new ChatOpenAI({  model: "gpt-3.5-turbo-0125",  temperature: 0});

#### Install dependencies

tip

See [this section for general instructions on installing integration packages](/docs/get_started/installation#installing-integration-packages).

*   npm
*   yarn
*   pnpm

    npm i @langchain/mistralai @langchain/core

    yarn add @langchain/mistralai @langchain/core

    pnpm add @langchain/mistralai @langchain/core

#### Add environment variables

    MISTRAL_API_KEY=your-api-key

#### Instantiate the model

    import { ChatMistralAI } from "@langchain/mistralai";const llm = new ChatMistralAI({  model: "mistral-large-latest",  temperature: 0});

#### Install dependencies

tip

See [this section for general instructions on installing integration packages](/docs/get_started/installation#installing-integration-packages).

*   npm
*   yarn
*   pnpm

    npm i @langchain/community @langchain/core

    yarn add @langchain/community @langchain/core

    pnpm add @langchain/community @langchain/core

#### Add environment variables

    FIREWORKS_API_KEY=your-api-key

#### Instantiate the model

    import { ChatFireworks } from "@langchain/community/chat_models/fireworks";const llm = new ChatFireworks({  model: "accounts/fireworks/models/firefunction-v1",  temperature: 0});

A number of models implement helper methods that will take care of formatting and binding different function-like objects to the model. Let’s take a look at how we might take the following Zod function schema and get different models to invoke it:

    import { z } from "zod";/** * Note that the descriptions here are crucial, as they will be passed along * to the model along with the class name. */const calculatorSchema = z.object({  operation: z    .enum(["add", "subtract", "multiply", "divide"])    .describe("The type of operation to execute."),  number1: z.number().describe("The first number to operate on."),  number2: z.number().describe("The second number to operate on."),});

We can use the `.bindTools()` method to handle the conversion from LangChain tool to our model provider’s specific format and bind it to the model (i.e., passing it in each time the model is invoked). Let’s create a `DynamicStructuredTool` implementing a tool based on the above schema, then bind it to the model:

    import { ChatOpenAI } from "@langchain/openai";import { DynamicStructuredTool } from "@langchain/core/tools";const calculatorTool = new DynamicStructuredTool({  name: "calculator",  description: "Can perform mathematical operations.",  schema: calculatorSchema,  func: async ({ operation, number1, number2 }) => {    // Functions must return strings    if (operation === "add") {      return `${number1 + number2}`;    } else if (operation === "subtract") {      return `${number1 - number2}`;    } else if (operation === "multiply") {      return `${number1 * number2}`;    } else if (operation === "divide") {      return `${number1 / number2}`;    } else {      throw new Error("Invalid operation.");    }  },});const llmWithTools = llm.bindTools([calculatorTool]);

Now, let’s invoke it! We expect the model to use the calculator to answer the question:

    const res = await llmWithTools.invoke("What is 3 * 12");console.log(res.tool_calls);

    [  {    name: "calculator",    args: { operation: "multiply", number1: 3, number2: 12 },    id: "call_Ri9s27J17B224FEHrFGkLdxH"  }]

tip

See a LangSmith trace for the above [here](https://smith.langchain.com/public/14e4b50c-c6cf-4c53-b3ef-da550edb6d66/r).

We can see that the response message contains a `tool_calls` field when the model decides to call the tool. This will be in LangChain’s standardized format.

The `.tool_calls` attribute should contain valid tool calls. Note that on occasion, model providers may output malformed tool calls (e.g., arguments that are not valid JSON). When parsing fails in these cases, the message will contain instances of of [InvalidToolCall](https://api.js.langchain.com/types/langchain_core_messages_tool.InvalidToolCall.html) objects in the `.invalid_tool_calls` attribute. An `InvalidToolCall` can have a name, string arguments, identifier, and error message.

### Streaming[​](#streaming "Direct link to Streaming")

When tools are called in a streaming context, [message chunks](https://api.js.langchain.com/classes/langchain_core_messages.BaseMessageChunk.html) will be populated with [tool call chunk](https://api.js.langchain.com/types/langchain_core_messages_tool.ToolCallChunk.html) objects in a list via the `.tool_call_chunks` attribute. A `ToolCallChunk` includes optional string fields for the tool `name`, `args`, and `id`, and includes an optional integer field `index` that can be used to join chunks together. Fields are optional because portions of a tool call may be streamed across different chunks (e.g., a chunk that includes a substring of the arguments may have null values for the tool name and id).

Because message chunks inherit from their parent message class, an [AIMessageChunk](https://api.js.langchain.com/classes/langchain_core_messages.AIMessageChunk.html) with tool call chunks will also include `.tool_calls` and `.invalid_tool_calls` fields. These fields are parsed best-effort from the message’s tool call chunks.

Note that not all providers currently support streaming for tool calls. If this is the case for your specific provider, the model will yield a single chunk with the entire call when you call `.stream()`.

    const stream = await llmWithTools.stream("What is 308 / 29");for await (const chunk of stream) {  console.log(chunk.tool_call_chunks);}

    [  {    name: "calculator",    args: "",    id: "call_rGqPR1ivppYUeBb0iSAF8HGP",    index: 0  }][ { name: undefined, args: '{"', id: undefined, index: 0 } ][ { name: undefined, args: "operation", id: undefined, index: 0 } ][ { name: undefined, args: '":"', id: undefined, index: 0 } ][ { name: undefined, args: "divide", id: undefined, index: 0 } ][ { name: undefined, args: '","', id: undefined, index: 0 } ][ { name: undefined, args: "number", id: undefined, index: 0 } ][ { name: undefined, args: "1", id: undefined, index: 0 } ][ { name: undefined, args: '":', id: undefined, index: 0 } ][ { name: undefined, args: "308", id: undefined, index: 0 } ][ { name: undefined, args: ',"', id: undefined, index: 0 } ][ { name: undefined, args: "number", id: undefined, index: 0 } ][ { name: undefined, args: "2", id: undefined, index: 0 } ][ { name: undefined, args: '":', id: undefined, index: 0 } ][ { name: undefined, args: "29", id: undefined, index: 0 } ][ { name: undefined, args: "}", id: undefined, index: 0 } ][]

Note that using the `concat` method on message chunks will merge their corresponding tool call chunks. This is the principle by which LangChain’s various [tool output parsers](/v0.1/docs/modules/model_io/output_parsers/types/openai_tools/) support streaming.

For example, below we accumulate tool call chunks:

    const streamWithAccumulation = await llmWithTools.stream(  "What is 32993 - 2339");let final;for await (const chunk of streamWithAccumulation) {  if (!final) {    final = chunk;  } else {    final = final.concat(chunk);  }}console.log(final.tool_calls);

    [  {    name: "calculator",    args: { operation: "subtract", number1: 32993, number2: 2339 },    id: "call_WMhL5X0fMBBZPNeyUZY53Xuw"  }]

Few shotting with tools[​](#few-shotting-with-tools "Direct link to Few shotting with tools")
---------------------------------------------------------------------------------------------

You can give the model examples of how you would like tools to be called in order to guide generation by inputting manufactured tool call turns. For example, given the above calculator tool, we could define a new operator, `🦜`. Let’s see what happens when we use it naively:

    const res = await llmWithTools.invoke("What is 3 🦜 12");console.log(res.content);console.log(res.tool_calls);

    It seems like you've used an emoji (🦜) in your expression, which I'm not familiar with in a mathematical context. Could you clarify what operation you meant by using the parrot emoji? For example, did you mean addition, subtraction, multiplication, or division?[]

It doesn’t quite know how to interpret `🦜` as an operation. Now, let’s try giving it an example in the form of a manufactured messages to steer it towards `divide`:

    import { HumanMessage, AIMessage, ToolMessage } from "@langchain/core/messages";const res = await llmWithTools.invoke([  new HumanMessage("What is 333382 🦜 1932?"),  new AIMessage({    content: "",    tool_calls: [      {        id: "12345",        name: "calulator",        args: {          number1: 333382,          number2: 1932,          operation: "divide",        },      },    ],  }),  new ToolMessage({    tool_call_id: "12345",    content: "The answer is 172.558.",  }),  new AIMessage("The answer is 172.558."),  new HumanMessage("What is 3 🦜 12"),]);console.log(res.tool_calls);

    [  {    name: "calculator",    args: { operation: "divide", number1: 3, number2: 12 },    id: "call_BDuJv8QkDZ7N7Wsd6v5VDeVa"  }]

Next steps[​](#next-steps "Direct link to Next steps")
------------------------------------------------------

*   **Agents**: For more on how to execute tasks with these populated parameters, check out the [Tool Calling Agent](/v0.1/docs/modules/agents/agent_types/tool_calling/).
*   **Structured output chains**: Some models have constructors that handle creating a structured output chain for you ([OpenAI](/v0.1/docs/integrations/chat/openai/#withstructuredoutput--), [Mistral](/v0.1/docs/integrations/chat/mistral/#withstructuredoutput--)).
*   **Tool use**: See how to construct chains and agents that actually call the invoked tools in [these guides](/v0.1/docs/use_cases/tool_use/).

* * *

#### Help us out by providing feedback on this documentation page:

[

Previous

Dealing with rate limits

](/v0.1/docs/modules/model_io/chat/dealing_with_rate_limits/)[

Next

Response metadata

](/v0.1/docs/modules/model_io/chat/response_metadata/)

*   [Passing tools to LLMs](#passing-tools-to-llms)
    *   [Streaming](#streaming)
*   [Few shotting with tools](#few-shotting-with-tools)
*   [Next steps](#next-steps)

Community

*   [Discord](https://discord.gg/cU2adEyC7w)
*   [Twitter](https://twitter.com/LangChainAI)

GitHub

*   [Python](https://github.com/langchain-ai/langchain)
*   [JS/TS](https://github.com/langchain-ai/langchainjs)

More

*   [Homepage](https://langchain.com)
*   [Blog](https://blog.langchain.dev)

Copyright © 2024 LangChain, Inc.