Tavily search integration

Integrate with the Tavily search tool using LangChain JavaScript.

Tavily’s Search API is a search engine built specifically for AI agents (LLMs), delivering real-time, accurate, and factual results at speed.

Overview

Integration details

Class	Package	PY support	Downloads	Version
TavilySearch	@langchain/tavily	✅

Tool features

Returns artifact	Native async	Return data	Pricing
❌	✅	title, URL, content snippet, raw_content, answer, images	1,000 free searches / month

Setup

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

npm

npm install @langchain/tavily @langchain/core

yarn add @langchain/tavily @langchain/core

pnpm add @langchain/tavily @langchain/core

Credentials

Set up a Tavily API key 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

The tool accepts various parameters during instantiation:

• maxResults (optional, number): Maximum number of search results to return. Default is 5.
• topic (optional, string): Category of the search. Can be "general", "news", or "finance". Default is "general".
• includeAnswer (optional, boolean): Include an answer to the original query in the results. Default is false.
• includeRawContent (optional, boolean | "markdown" | "text"): Include cleaned and parsed content of each search result. Default is false.
• includeImages (optional, boolean): Include a list of query-related images in the response. Default is false.
• includeImageDescriptions (optional, boolean): Include descriptive text for each image. Default is false.
• searchDepth (optional, string): Depth of the search, either "basic" or "advanced". Default is "basic".
• timeRange (optional, string): Time range from the current date to filter results — "day", "week", "month", or "year". Default is undefined.
• includeDomains (optional, string[]): Domains to specifically include. Default is [].
• excludeDomains (optional, string[]): Domains to specifically exclude. Default is [].

For a comprehensive overview of the available parameters, refer to the Tavily Search API documentation.

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.
• 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.

NOTE: The optional arguments are available for agents to dynamically set. If you set an argument during instantiation and then invoke the tool with a different value, the tool will use the value you passed during invocation.

await tool.invoke({ query: "What happened at the last wimbledon" });

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: "euro 2024 host nation" },
  id: "1",
  name: tool.name,
  type: "tool_call",
};

const toolMsg = await tool.invoke(modelGeneratedToolCall);

// The content is a JSON string of results
console.log(toolMsg.content.slice(0, 400));

{"query": "euro 2024 host nation", "follow_up_questions": null, "answer": null, "images": [], "results": [{"title": "UEFA Euro 2024 - Wikipedia", "url": "https://en.wikipedia.org/wiki/UEFA_Euro_2024", "content": "Tournament details Host country Germany Dates 14 June – 14 July Teams 24 Venue(s) 10 (in 10 host cities) Final positions Champions Spain (4th title) Runners-up England Tournament statisti

Use within an agent

We can use the search tool directly with a LangChain agent by passing it to createAgent. The agent can dynamically set parameters like includeDomains, searchDepth, and timeRange as part of its tool call.

In the example below, when we ask the agent to find “What nation hosted Euro 2024? Include only wikipedia sources.” the agent will dynamically set the arguments and invoke the Tavily search tool with { query: "Euro 2024 host nation", includeDomains: ["wikipedia.org"] }.

// @lc-docs-hide-cell
import { ChatOpenAI } from "@langchain/openai";

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

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

// Initialize Tavily Search Tool
const tavilySearchTool = new TavilySearch({
  maxResults: 5,
  topic: "general",
});

const agent = createAgent({
  model: llm,
  tools: [tavilySearchTool],
});

const userInput = "What nation hosted Euro 2024? Include only wikipedia sources.";

const stream = await agent.streamEvents(
  { messages: [["human", userInput]] },
  { version: "v3" },
);

for await (const snapshot of stream.values) {
  const lastMsg = snapshot.messages[snapshot.messages.length - 1];
  if (lastMsg.tool_calls?.length) {
    console.dir(lastMsg.tool_calls, { depth: null });
  } else if (lastMsg.content) {
    console.log(lastMsg.content);
  }
}

---

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

---

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

Edit this page on GitHub or file an issue.