!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

*   [Use cases](/v0.1/docs/use_cases/)
    
    *   [SQL](/v0.1/docs/use_cases/sql/)
        
    *   [Chatbots](/v0.1/docs/use_cases/chatbots/)
        
    *   [Extraction](/v0.1/docs/use_cases/extraction/)
        
    *   [Query Analysis](/v0.1/docs/use_cases/query_analysis/)
        
    *   [Q&A with RAG](/v0.1/docs/use_cases/question_answering/)
        
    *   [Tool use](/v0.1/docs/use_cases/tool_use/)
        
        *   [Quickstart](/v0.1/docs/use_cases/tool_use/quickstart/)
        *   [Agents](/v0.1/docs/use_cases/tool_use/agents/)
        *   [Choosing between multiple tools](/v0.1/docs/use_cases/tool_use/multiple_tools/)
        *   [Parallel tool use](/v0.1/docs/use_cases/tool_use/parallel/)
        *   [Tool error handling](/v0.1/docs/use_cases/tool_use/tool_error_handling/)
        *   [Human-in-the-loop](/v0.1/docs/use_cases/tool_use/human_in_the_loop/)
    *   [Interacting with APIs](/v0.1/docs/use_cases/api/)
    *   [Tabular Question Answering](/v0.1/docs/use_cases/tabular/)
    *   [Graphs](/v0.1/docs/use_cases/graph/)
        
    *   [Summarization](/v0.1/docs/use_cases/summarization/)
    *   [Agent Simulations](/v0.1/docs/use_cases/agent_simulations/)
        
    *   [Autonomous Agents](/v0.1/docs/use_cases/autonomous_agents/)
        
    *   [Code Understanding](/v0.1/docs/use_cases/code_understanding/)
    *   [Audio/Video Structured Extraction](/v0.1/docs/use_cases/media/)

*   [](/v0.1/)
*   [Use cases](/v0.1/docs/use_cases/)
*   [Tool use](/v0.1/docs/use_cases/tool_use/)
*   Quickstart

On this page

Quickstart
==========

In this guide, we will go over the basic ways to create Chains and Agents that call Tools. Tools can be just about anything — APIs, functions, databases, etc. Tools allow us to extend the capabilities of a model beyond just outputting text/messages. The key to using models with tools is correctly prompting a model and parsing its response so that it chooses the right tools and provides the right inputs for them.

Setup[​](#setup "Direct link to Setup")
---------------------------------------

We’ll use OpenAI for this guide, and will need to install its partner package:

tip

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

*   npm
*   Yarn
*   pnpm

    npm install @langchain/openai

    yarn add @langchain/openai

    pnpm add @langchain/openai

You'll need to sign up for an OpenAI key and set it as an environment variable named `OPENAI_API_KEY`.

We'll also use the popular validation library [Zod](https://zod.dev) to define our tool schemas. It's already a dependency of `langchain`, but you can install it explicitly like this too:

*   npm
*   Yarn
*   pnpm

    npm install zod

    yarn add zod

    pnpm add zod

Create a tool[​](#create-a-tool "Direct link to Create a tool")
---------------------------------------------------------------

First, we need to create a tool to call. For this example, we will create a custom tool from a function. For more information on creating custom tools, please see [this guide](/v0.1/docs/modules/agents/tools/).

    import { z } from "zod";import { DynamicStructuredTool } from "@langchain/core/tools";const multiplyTool = new DynamicStructuredTool({  name: "multiply",  description: "Multiply two integers together.",  schema: z.object({    firstInt: z.number(),    secondInt: z.number(),  }),  func: async ({ firstInt, secondInt }) => {    return (firstInt * secondInt).toString();  },});await multiplyTool.invoke({ firstInt: 4, secondInt: 5 });

    20

Chains[​](#chains "Direct link to Chains")
------------------------------------------

If we know that we only need to use a tool a fixed number of times, we can create a chain for doing so. Let’s create a simple chain that just multiplies user-specified numbers.

### Function calling[​](#function-calling "Direct link to Function calling")

One of the most reliable ways to use tools with LLMs is with function calling APIs (also sometimes called tool calling or parallel function calling). This only works with models that explicitly support function calling, like OpenAI models.

First we’ll define our model:

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

Next we’ll convert our LangChain Tool to the format an OpenAI function accepts, [JSONSchema](https://json-schema.org/), and bind this as the tools argument to be passed to all ChatOpenAI calls. Since we only have a single Tool and in this initial chain we want to make sure it’s always used, we’ll also specify `tool_choice`. See the [OpenAI chat API reference](https://platform.openai.com/docs/api-reference/chat/create#chat-create-tool_choice) for more on these parameters.

    import { convertToOpenAITool } from "@langchain/core/utils/function_calling";const formattedTools = [convertToOpenAITool(multiplyTool)];

    [  {    "type": "function",    "function": {      "name": "multiply",      "description": "Multiply two integers together.",      "parameters": {        "type": "object",        "properties": {          "firstInt": {            "type": "number"          },          "secondInt": {            "type": "number"          }        },        "required": [          "firstInt",          "secondInt"        ],        "additionalProperties": false,        "$schema": "http://json-schema.org/draft-07/schema#"      }    }  }]

    const modelWithTools = model.bind({  tools: formattedTools,  // We specify tool_choice to enforce that the 'multiply' function is called by the model.  tool_choice: {    type: "function",    function: { name: "multiply" },  },});

Now we’ll compose out tool-calling model with a [`JsonOutputToolsParser`](https://api.js.langchain.com/classes/langchain_output_parsers.JsonOutputToolsParser.html), a built-in LangChain output parser that converts an OpenAI function-calling response to a list of `{"type": "TOOL_NAME", "args": {...}}` objects with the tools to invoke and arguments to invoke them with.

    import { JsonOutputToolsParser } from "langchain/output_parsers";const chain = modelWithTools.pipe(new JsonOutputToolsParser());await chain.invoke("What's 4 times 23?");

    [ { type: 'multiply', args: { firstInt: 4, secondInt: 23 } } ]

Since we know we’re always invoking the `multiply` tool, we can simplify our output a bit to return only the args for the `multiply` tool using the JsonOutputKeyToolsParser. To further simplify we’ll specify `returnSingle: true`, so that instead of a list of tool invocations our output parser returns only the first tool invocation.

    import { JsonOutputKeyToolsParser } from "langchain/output_parsers";const chain2 = modelWithTools.pipe(  new JsonOutputKeyToolsParser({ keyName: "multiply", returnSingle: true }));await chain2.invoke("What's 4 times 23?");

    { firstInt: 4, secondInt: 23 }

### Invoking the tool[​](#invoking-the-tool "Direct link to Invoking the tool")

Great! We’re able to generate tool invocations. But what if we want to actually call the tool with the LLM-generated args? To do that we just need to pass them to the tool:

info

You can see a LangSmith trace of this example [here](https://smith.langchain.com/public/4ac83d6a-4db9-467b-bb68-75b4efd1809f/r)

    import { RunnableSequence } from "@langchain/core/runnables";const chain3 = RunnableSequence.from([  modelWithTools,  new JsonOutputKeyToolsParser({ keyName: "multiply", returnSingle: true }),  multiplyTool,]);await chain3.invoke("What's 4 times 23?");

    92

And there we have our answer!

Agents[​](#agents "Direct link to Agents")
------------------------------------------

Chains are great when we know the specific sequence of tool usage needed for any user input. But for certain use cases, how many times we use tools depends on the input. In these cases, we want to let the model itself decide how many times to use tools and in what order. That's where [Agents](/v0.1/docs/modules/agents/) come in!

LangChain comes with a number of built-in agents that are optimized for different use cases. Read about [all the available agent types](/v0.1/docs/modules/agents/agent_types/) here.

For this example, let’s try out the OpenAI tools agent, which makes use of the new OpenAI tool-calling API (this is only available in the latest OpenAI models, and differs from function-calling in that the model can return multiple function invocations at once).

Keep in mind that some agents only support single-argument tools - for these agents, you will need to use a `DynamicTool` instead and parse the input string yourself.

    import { pull } from "langchain/hub";import { AgentExecutor, createOpenAIToolsAgent } from "langchain/agents";import { ChatOpenAI } from "@langchain/openai";import type { ChatPromptTemplate } from "@langchain/core/prompts";// Get the prompt to use - you can modify this!// You can also see the full prompt at:// https://smith.langchain.com/hub/hwchase17/openai-tools-agentconst prompt = await pull<ChatPromptTemplate>("hwchase17/openai-tools-agent");

Agents can also choose between multiple tools to solve a problem. To learn how to build Chains that use multiple tools, check out the [Chains with multiple tools](/v0.1/docs/use_cases/tool_use/multiple_tools/) guide.

    import { z } from "zod";import { DynamicStructuredTool } from "@langchain/core/tools";const addTool = new DynamicStructuredTool({  name: "add",  description: "Add two integers together.",  schema: z.object({    firstInt: z.number(),    secondInt: z.number(),  }),  func: async ({ firstInt, secondInt }) => {    return (firstInt + secondInt).toString();  },});const multiplyTool = new DynamicStructuredTool({  name: "multiply",  description: "Multiply two integers together.",  schema: z.object({    firstInt: z.number(),    secondInt: z.number(),  }),  func: async ({ firstInt, secondInt }) => {    return (firstInt * secondInt).toString();  },});const exponentiateTool = new DynamicStructuredTool({  name: "exponentiate",  description: "Exponentiate the base to the exponent power.",  schema: z.object({    base: z.number(),    exponent: z.number(),  }),  func: async ({ base, exponent }) => {    return (base ** exponent).toString();  },});const model = new ChatOpenAI({  model: "gpt-3.5-turbo-1106",  temperature: 0,});const tools = [addTool, multiplyTool, exponentiateTool];const agent = await createOpenAIToolsAgent({  llm: model,  tools,  prompt,});const agentExecutor = new AgentExecutor({  agent,  tools,  verbose: true,});

With an agent, we can ask questions that require arbitrarily-many uses of our tools:

info

You can see a LangSmith trace of this example [here](https://smith.langchain.com/public/fc11cacc-f467-4c39-a46e-8bfefa37b1f9/r)

    await agentExecutor.invoke({  input:    "Take 3 to the fifth power and multiply that by the sum of twelve and three, then square the whole result",});

    > Entering new AgentExecutor chain...Invoking: `exponentiate` with `{'base': 3, 'exponent': 5}`243Invoking: `add` with `{'first_int': 12, 'second_int': 3}`15Invoking: `multiply` with `{'first_int': 243, 'second_int': 15}`3645Invoking: `exponentiate` with `{'base': 3645, 'exponent': 2}`13286025The result of taking 3 to the fifth power and multiplying that by the sum of twelve and three, then squaring the whole result is 13,286,025.> Finished chain.

    {  input: 'Take 3 to the fifth power and multiply that by the sum of twelve and three, then square the whole result',  output: 'The result of taking 3 to the fifth power and multiplying that by the sum of twelve and three, then squaring the whole result is 13,286,025.'}

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

Here we’ve gone over the basic ways to use Tools with Chains and Agents. We recommend the following sections to explore next:

*   [Agents](/v0.1/docs/modules/agents/): Everything related to Agents.
*   [Choosing between multiple tools](/v0.1/docs/use_cases/tool_use/multiple_tools/): How to make tool chains that select from multiple tools.
*   [Parallel tool use](/v0.1/docs/use_cases/tool_use/parallel/): How to make tool chains that invoke multiple tools at once.

* * *

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

[

Previous

Tool use

](/v0.1/docs/use_cases/tool_use/)[

Next

Agents

](/v0.1/docs/use_cases/tool_use/agents/)

*   [Setup](#setup)
*   [Create a tool](#create-a-tool)
*   [Chains](#chains)
    *   [Function calling](#function-calling)
    *   [Invoking the tool](#invoking-the-tool)
*   [Agents](#agents)
*   [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.