How to use tools

Prerequisites

This guide assumes familiarity with the following concepts:

• Chatbots
• Agents
• Chat history

This section will cover how to create conversational agents: chatbots that can interact with other systems and APIs using tools.

Setup

For this guide, we’ll be using an tool calling agent with a single tool for searching the web. The default will be powered by Tavily, but you can switch it out for any similar tool. The rest of this section will assume you’re using Tavily.

You’ll need to sign up for an account on the Tavily website, and install the following packages:

npm

npm i @langchain/openai langchain @langchain/core

yarn

yarn add @langchain/openai langchain @langchain/core

pnpm

pnpm add @langchain/openai langchain @langchain/core

import { TavilySearchResults } from "@langchain/community/tools/tavily_search";
import { ChatOpenAI } from "@langchain/openai";

const tools = [
  new TavilySearchResults({
    maxResults: 1,
  }),
];

const llm = new ChatOpenAI({
  model: "gpt-3.5-turbo-1106",
  temperature: 0,
});

To make our agent conversational, we must also choose a prompt with a placeholder for our chat history. Here’s an example:

import { ChatPromptTemplate } from "@langchain/core/prompts";

// Adapted from https://smith.langchain.com/hub/jacob/tool-calling-agent
const prompt = ChatPromptTemplate.fromMessages([
  [
    "system",
    "You are a helpful assistant. You may not need to use tools for every query - the user may just want to chat!",
  ],
  ["placeholder", "{messages}"],
  ["placeholder", "{agent_scratchpad}"],
]);

Great! Now let’s assemble our agent:

tip

As of langchain version 0.2.8, the createOpenAIToolsAgent function now supports OpenAI-formatted tools.

import { AgentExecutor, createToolCallingAgent } from "langchain/agents";

const agent = await createToolCallingAgent({
  llm,
  tools,
  prompt,
});

const agentExecutor = new AgentExecutor({ agent, tools });

Running the agent

Now that we’ve set up our agent, let’s try interacting with it! It can handle both trivial queries that require no lookup:

import { HumanMessage } from "@langchain/core/messages";

await agentExecutor.invoke({
  messages: [new HumanMessage("I'm Nemo!")],
});

{
  messages: [
    HumanMessage {
      lc_serializable: true,
      lc_kwargs: {
        content: "I'm Nemo!",
        additional_kwargs: {},
        response_metadata: {}
      },
      lc_namespace: [ "langchain_core", "messages" ],
      content: "I'm Nemo!",
      name: undefined,
      additional_kwargs: {},
      response_metadata: {}
    }
  ],
  output: "Hi Nemo! It's great to meet you. How can I assist you today?"
}

Or, it can use of the passed search tool to get up to date information if needed:

await agentExecutor.invoke({
  messages: [
    new HumanMessage(
      "What is the current conservation status of the Great Barrier Reef?"
    ),
  ],
});

{
  messages: [
    HumanMessage {
      lc_serializable: true,
      lc_kwargs: {
        content: "What is the current conservation status of the Great Barrier Reef?",
        additional_kwargs: {},
        response_metadata: {}
      },
      lc_namespace: [ "langchain_core", "messages" ],
      content: "What is the current conservation status of the Great Barrier Reef?",
      name: undefined,
      additional_kwargs: {},
      response_metadata: {}
    }
  ],
  output: "The Great Barrier Reef has recorded its highest amount of coral cover since the Australian Institute"... 688 more characters
}

Conversational responses

Because our prompt contains a placeholder for chat history messages, our agent can also take previous interactions into account and respond conversationally like a standard chatbot:

import { AIMessage } from "@langchain/core/messages";

await agentExecutor.invoke({
  messages: [
    new HumanMessage("I'm Nemo!"),
    new AIMessage("Hello Nemo! How can I assist you today?"),
    new HumanMessage("What is my name?"),
  ],
});

{
  messages: [
    HumanMessage {
      lc_serializable: true,
      lc_kwargs: {
        content: "I'm Nemo!",
        additional_kwargs: {},
        response_metadata: {}
      },
      lc_namespace: [ "langchain_core", "messages" ],
      content: "I'm Nemo!",
      name: undefined,
      additional_kwargs: {},
      response_metadata: {}
    },
    AIMessage {
      lc_serializable: true,
      lc_kwargs: {
        content: "Hello Nemo! How can I assist you today?",
        tool_calls: [],
        invalid_tool_calls: [],
        additional_kwargs: {},
        response_metadata: {}
      },
      lc_namespace: [ "langchain_core", "messages" ],
      content: "Hello Nemo! How can I assist you today?",
      name: undefined,
      additional_kwargs: {},
      response_metadata: {},
      tool_calls: [],
      invalid_tool_calls: [],
      usage_metadata: undefined
    },
    HumanMessage {
      lc_serializable: true,
      lc_kwargs: {
        content: "What is my name?",
        additional_kwargs: {},
        response_metadata: {}
      },
      lc_namespace: [ "langchain_core", "messages" ],
      content: "What is my name?",
      name: undefined,
      additional_kwargs: {},
      response_metadata: {}
    }
  ],
  output: "Your name is Nemo!"
}

If preferred, you can also wrap the agent executor in a RunnableWithMessageHistory class to internally manage history messages. Let’s redeclare it this way:

const agent2 = await createToolCallingAgent({
  llm,
  tools,
  prompt,
});

const agentExecutor2 = new AgentExecutor({ agent: agent2, tools });

Then, because our agent executor has multiple outputs, we also have to set the outputMessagesKey property when initializing the wrapper:

import { ChatMessageHistory } from "langchain/stores/message/in_memory";
import { RunnableWithMessageHistory } from "@langchain/core/runnables";

const demoEphemeralChatMessageHistory = new ChatMessageHistory();

const conversationalAgentExecutor = new RunnableWithMessageHistory({
  runnable: agentExecutor2,
  getMessageHistory: (_sessionId) => demoEphemeralChatMessageHistory,
  inputMessagesKey: "messages",
  outputMessagesKey: "output",
});

await conversationalAgentExecutor.invoke(
  { messages: [new HumanMessage("I'm Nemo!")] },
  { configurable: { sessionId: "unused" } }
);

{
  messages: [
    HumanMessage {
      lc_serializable: true,
      lc_kwargs: {
        content: "I'm Nemo!",
        additional_kwargs: {},
        response_metadata: {}
      },
      lc_namespace: [ "langchain_core", "messages" ],
      content: "I'm Nemo!",
      name: undefined,
      additional_kwargs: {},
      response_metadata: {}
    }
  ],
  output: "Hi Nemo! It's great to meet you. How can I assist you today?"
}

await conversationalAgentExecutor.invoke(
  { messages: [new HumanMessage("What is my name?")] },
  { configurable: { sessionId: "unused" } }
);

{
  messages: [
    HumanMessage {
      lc_serializable: true,
      lc_kwargs: {
        content: "I'm Nemo!",
        additional_kwargs: {},
        response_metadata: {}
      },
      lc_namespace: [ "langchain_core", "messages" ],
      content: "I'm Nemo!",
      name: undefined,
      additional_kwargs: {},
      response_metadata: {}
    },
    AIMessage {
      lc_serializable: true,
      lc_kwargs: {
        content: "Hi Nemo! It's great to meet you. How can I assist you today?",
        tool_calls: [],
        invalid_tool_calls: [],
        additional_kwargs: {},
        response_metadata: {}
      },
      lc_namespace: [ "langchain_core", "messages" ],
      content: "Hi Nemo! It's great to meet you. How can I assist you today?",
      name: undefined,
      additional_kwargs: {},
      response_metadata: {},
      tool_calls: [],
      invalid_tool_calls: [],
      usage_metadata: undefined
    },
    HumanMessage {
      lc_serializable: true,
      lc_kwargs: {
        content: "What is my name?",
        additional_kwargs: {},
        response_metadata: {}
      },
      lc_namespace: [ "langchain_core", "messages" ],
      content: "What is my name?",
      name: undefined,
      additional_kwargs: {},
      response_metadata: {}
    }
  ],
  output: "Your name is Nemo!"
}

Next steps

You’ve now learned how to create chatbots with tool-use capabilities.

For more, check out the other guides in this section, including how to add history to your chatbots.