> ## 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 map integration

> Integrate with the Tavily map tool using LangChain JavaScript.

[Tavily](https://tavily.com/) is a search engine built specifically for AI agents (LLMs), delivering real-time, accurate, and factual results at speed. Tavily offers a [Map](https://docs.tavily.com/documentation/api-reference/endpoint/map) endpoint that traverses websites and returns a list of discovered URLs without extracting page content, which is ideal for understanding site structure or locating specific pages on a large site.

## Overview

### Integration details

| Class                                                                                | Package                                                                | [PY support](https://python.langchain.com/docs/integrations/tools/tavily_map) |                                             Downloads                                             |                                             Version                                            |
| :----------------------------------------------------------------------------------- | :--------------------------------------------------------------------- | :---------------------------------------------------------------------------: | :-----------------------------------------------------------------------------------------------: | :--------------------------------------------------------------------------------------------: |
| [`TavilyMap`](https://reference.langchain.com/javascript/langchain-tavily/TavilyMap) | [`@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          |
| :-------------------------------------------------: | :----------: | :---------------------: | :------------------------: |
|                          ❌                          |       ✅      | list of discovered URLs | 1,000 free credits / 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_map) 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 the following parameters during instantiation:

* `maxDepth` (optional, number): Maximum number of hops from the starting URL. Default is `3`.
* `maxBreadth` (optional, number): Maximum number of URLs returned per level. Default is `50`.
* `limit` (optional, number): Maximum total number of URLs to return. Default is `100`.
* `instructions` (optional, string): Natural-language instructions that guide the map traversal.
* `selectPaths` (optional, string\[]): Only include URLs containing these path regexes.
* `selectDomains` (optional, string\[]): Only include URLs from these domain regexes.
* `excludePaths` (optional, string\[]): Skip URLs containing these path regexes.
* `excludeDomains` (optional, string\[]): Skip URLs from these domain regexes.
* `allowExternal` (optional, boolean): Allow the map to follow external links.

For a comprehensive overview of the available parameters, refer to the [Tavily Map API documentation](https://docs.tavily.com/documentation/api-reference/endpoint/map).

```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import { TavilyMap } from "@langchain/tavily";

const tool = new TavilyMap({
  maxDepth: 3,
  maxBreadth: 50,
  // limit: 100,
  // allowExternal: false,
});
```

## Invocation

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

The Tavily map tool accepts the following arguments during invocation:

* `url` (required): The base URL to start mapping from.
* The following arguments can also be set during invocation: `instructions`, `selectPaths`, `selectDomains`, `excludePaths`, `excludeDomains`, `allowExternal`.

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({ url: "https://docs.tavily.com" });
```

```json theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
  "base_url": "https://docs.tavily.com",
  "results": [
    "https://docs.tavily.com/",
    "https://docs.tavily.com/changelog",
    "https://docs.tavily.com/welcome",
    "https://docs.tavily.com/documentation/mcp",
    "https://docs.tavily.com/documentation/about",
  ],
  "response_time": 0.07
}
```

### [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: {
    url: "https://docs.tavily.com",
    instructions: "Find API reference pages",
  },
  id: "1",
  name: tool.name,
  type: "tool_call",
};

const toolMsg = await tool.invoke(modelGeneratedToolCall);

console.log(toolMsg.content.slice(0, 400));
```

## Use within an agent

We can use the map tool directly with a LangChain agent by passing it to `createAgent`. The agent can dynamically set `url`, `instructions`, and the path/domain filters to discover the URLs it needs.

```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 { TavilyMap } from "@langchain/tavily";
import { createAgent } from "langchain";

const tavilyMapTool = new TavilyMap({
  maxDepth: 2,
  maxBreadth: 20,
  limit: 30,
});

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

const userInput = "Map https://docs.tavily.com and list URLs that look like API reference pages.";

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 Map API features and configurations head to the API reference: [docs.tavily.com/documentation/api-reference/endpoint/map](https://docs.tavily.com/documentation/api-reference/endpoint/map)

***

<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_map.mdx) or [file an issue](https://github.com/langchain-ai/docs/issues/new/choose).
  </Callout>
</div>