Tavily Search

Tavily is a search engine built specifically for AI agents (LLMs), delivering real-time, accurate, and factual results at speed. Tavily offers two key endpoints, one of which being Search, which provides search results tailored for LLMs and RAG.

This guide provides a quick overview for getting started with the Tavily tool. For a complete breakdown of the Tavily tool, you can find more detailed documentation in the API reference.

Overview

Integration details

Class	Package	PY support	Version
TavilySearch	@langchain/tavily	✅

Setup

The integration lives in the @langchain/tavily package, which you can install as shown below:

npm

npm install @langchain/tavily @langchain/core

Credentials

Set up an API key here and set it as an environment variable named TAVILY_API_KEY.

process.env.TAVILY_API_KEY = "YOUR_API_KEY"

It’s also helpful (but not needed) to set up LangSmith for best-in-class observability:

process.env.LANGSMITH_TRACING="true"
process.env.LANGSMITH_API_KEY="your-api-key"

Instantiation

You can import and instantiate an instance of the TavilySearch tool like this:

import { TavilySearch } from "@langchain/tavily";

const tool = new TavilySearch({
  maxResults: 5,
  topic: "general",
  // includeAnswer: false,
  // includeRawContent: false,
  // includeImages: false,
  // includeImageDescriptions: false,
  // searchDepth: "basic",
  // timeRange: "day",
  // includeDomains: [],
  // excludeDomains: [],
});

Invocation

Invoke directly with args

The Tavily search tool accepts the following arguments during invocation:

• query (required): A natural language search query

• The following arguments can also be set during invocation : includeImages, searchDepth , timeRange, includeDomains, excludeDomains, includeImages.

• For reliability and performance reasons, certain parameters that affect response size cannot be modified during invocation: includeAnswer and includeRawContent. These limitations prevent unexpected context window issues and ensure consistent results.

await tool.invoke({
  query: "what is the current weather in SF?"
});

Invoke with ToolCall

We can also invoke the tool with a model-generated ToolCall, in which case a @[ToolMessage] will be returned:

// This is usually generated by a model, but we'll create a tool call directly for demo purposes.
const modelGeneratedToolCall = {
  args: {
    query: "what is the current weather in SF?"
  },
  id: "1",
  name: tool.name,
  type: "tool_call",
}

await tool.invoke(modelGeneratedToolCall)

Chaining

We can use our tool in a chain by first binding it to a tool-calling model and then calling it:

// @lc-docs-hide-cell

import { ChatOpenAI } from "@langchain/openai"

const llm = new ChatOpenAI({
  model: "gpt-4o",
  temperature: 0,
})

import { HumanMessage } from "@langchain/core/messages";
import { ChatPromptTemplate } from "@langchain/core/prompts";
import { RunnableLambda } from "@langchain/core/runnables";

const prompt = ChatPromptTemplate.fromMessages(
  [
    ["system", "You are a helpful assistant."],
    ["placeholder", "{messages}"],
  ]
)

const llmWithTools = llm.bindTools([tool]);

const chain = prompt.pipe(llmWithTools);

const toolChain = RunnableLambda.from(
  async (userInput: string, config) => {
    const humanMessage = new HumanMessage(userInput,);
    const aiMsg = await chain.invoke({
      messages: [new HumanMessage(userInput)],
    }, config);
    const toolMsgs = await tool.batch(aiMsg.tool_calls, config);
    return chain.invoke({
      messages: [humanMessage, aiMsg, ...toolMsgs],
    }, config);
  }
);

const toolChainResult = await toolChain.invoke("what is the current weather in sf?");

const { tool_calls, content } = toolChainResult;

console.log("AIMessage", JSON.stringify({
  tool_calls,
  content,
}, null, 2));

Agents

For guides on how to use LangChain tools in agents, see the LangGraph.js docs.

---

API reference

For detailed documentation of all Tavily Search API features and configurations head to the API reference:

docs.tavily.com/documentation/api-reference/endpoint/search

Related

Tool docs

---

Edit the source of this page on GitHub.

Connect these docs programmatically to Claude, VSCode, and more via MCP for real-time answers.