Tavily map integration

Tavily is a search engine built specifically for AI agents (LLMs), delivering real-time, accurate, and factual results at speed. Tavily offers a 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	Downloads	Version
TavilyMap	@langchain/tavily	✅

Tool features

Setup

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

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

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

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

Invocation

Invoke directly with args

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.

await tool.invoke({ url: "https://docs.tavily.com" });

{
  "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

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: {
    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.

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

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

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