Skip to main content

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

ClassPackagePY supportVersion
TavilyMap@langchain/tavily✅NPM - Version

​
Tool features

Returns artifactNative asyncReturn dataPricing
❌✅list of discovered URLs1,000 free credits / month

​
Setup

The integration lives in the @langchain/tavily package, which you can install as shown below: 
npm install @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.4",
  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 events = await agent.stream(
  { messages: [["human", userInput]] },
  { streamMode: "values" },
);

for await (const event of events) {
  const lastMsg = event.messages[event.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
Connect these docs to Claude, VSCode, and more via MCP for real-time answers.
Edit this page on GitHub or file an issue.