> ## Documentation Index
> Fetch the complete documentation index at: https://docs.langchain.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Tavily search integration

> Integrate with the Tavily search tool using LangChain JavaScript.

[Tavily's Search API](https://tavily.com/) 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](https://python.langchain.com/docs/integrations/tools/tavily_search) |                                             Downloads                                             |                                             Version                                            |
| :----------------------------------------------------------------------------------------- | :--------------------------------------------------------------------- | :------------------------------------------------------------------------------: | :-----------------------------------------------------------------------------------------------: | :--------------------------------------------------------------------------------------------: |
| [`TavilySearch`](https://reference.langchain.com/javascript/langchain-tavily/TavilySearch) | [`@langchain/tavily`](https://www.npmjs.com/package/@langchain/tavily) |                                         ✅                                        | ![NPM - Downloads](https://img.shields.io/npm/dm/@langchain/tavily?style=flat-square\&label=%20&) | ![NPM - Version](https://img.shields.io/npm/v/@langchain/tavily?style=flat-square\&label=%20&) |

### Tool features

| [Returns artifact](/oss/javascript/langchain/tools) | 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:

<CodeGroup>
  ```bash npm theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  npm install @langchain/tavily @langchain/core
  ```

  ```bash yarn theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  yarn add @langchain/tavily @langchain/core
  ```

  ```bash pnpm theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  pnpm add @langchain/tavily @langchain/core
  ```
</CodeGroup>

### Credentials

[Set up a Tavily API key](https://app.tavily.com) and set it as an environment variable named `TAVILY_API_KEY`.

```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
process.env.TAVILY_API_KEY = "YOUR_API_KEY"
```

It's also helpful (but not needed) to set up [LangSmith](https://smith.langchain.com?utm_source=docs\&utm_medium=cta\&utm_campaign=langsmith-signup\&utm_content=oss-javascript-integrations-tools-tavily_search) for best-in-class observability:

```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
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](https://docs.tavily.com/documentation/api-reference/endpoint/search).

```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
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](/oss/javascript/langchain/tools)

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.

```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
await tool.invoke({ query: "What happened at the last wimbledon" });
```

### [Invoke with ToolCall](/oss/javascript/langchain/tools)

We can also invoke the tool with a model-generated `ToolCall`, in which case a [`ToolMessage`](https://reference.langchain.com/javascript/langchain-core/messages/ToolMessage) will be returned:

```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
// 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));
```

```json theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{"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"] }`.

```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
// @lc-docs-hide-cell
import { ChatOpenAI } from "@langchain/openai";

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

```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
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](https://docs.tavily.com/documentation/api-reference/endpoint/search)

***

<div className="source-links">
  <Callout icon="terminal-2">
    [Connect these docs](/use-these-docs) to Claude, VSCode, and more via MCP for real-time answers.
  </Callout>

  <Callout icon="edit">
    [Edit this page on GitHub](https://github.com/langchain-ai/docs/edit/main/src/oss/javascript/integrations/tools/tavily_search.mdx) or [file an issue](https://github.com/langchain-ai/docs/issues/new/choose).
  </Callout>
</div>