Tavily 是一个专门为 AI 代理（LLM）构建的搜索引擎，提供实时、准确和真实的结果。Tavily 提供 地图 端点，可遍历网站并返回发现的 URL 列表，而不提取页面内容，这非常适合理解网站结构或在大型网站上定位特定页面。

概述

集成详情

工具特性

设置

该集成位于 @langchain/tavily 包中，您可以按以下方式安装：

npm install @langchain/tavily @langchain/core

yarn add @langchain/tavily @langchain/core

pnpm add @langchain/tavily @langchain/core

凭据

设置 Tavily API 密钥 并将其设置为名为 TAVILY_API_KEY.

process.env.TAVILY_API_KEY = "YOUR_API_KEY"

设置 LangSmith 也很好（但不是必需的），用于最佳可观测性：

process.env.LANGSMITH_TRACING="true"
process.env.LANGSMITH_API_KEY="your-api-key"

实例化

该工具在实例化期间接受以下参数：

• - maxDepth （可选，数字）：从起始 URL 的最大跳转次数。默认为 3.
• - maxBreadth （可选，数字）：每层返回的最大 URL 数量。默认为 50.
• - limit （可选，数字）：返回的最大 URL 总数。默认为 100.
• - instructions （可选，字符串）：指导地图遍历的自然语言指令。
• - selectPaths （可选，字符串[]）：仅包含包含这些路径正则表达式的 URL。
• - selectDomains （可选，字符串[]）：仅包含来自这些域正则表达式的 URL。
• - excludePaths （可选，字符串[]）：跳过包含这些路径正则表达式的 URL。
• - excludeDomains （可选，字符串[]）：跳过来自这些域正则表达式的 URL。
• - allowExternal （可选，布尔值）：允许地图跟随外部链接。

如需查看可用参数的完整概述，请参阅 Tavily 地图 API 文档.

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

调用

使用参数直接调用

Tavily 地图工具在调用期间接受以下参数：

• - url （必填）：要开始映射的起始 URL。
• - 以下参数也可以在调用期间设置： instructions, selectPaths, selectDomains, excludePaths, excludeDomains, allowExternal.

注意：可选参数可供代理动态设置。如果您在实例化期间设置了参数，然后使用不同的值调用工具，工具将使用您在调用期间传递的值。

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
}

使用 ToolCall 调用

我们也可以使用模型生成的 ToolCall来调用工具，在这种情况下 ToolMessage 将被返回：

// 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));

在代理中使用

我们可以将地图工具直接与 LangChain 代理一起使用，通过将其传递给 createAgent。代理可以动态设置 url, instructions, and the path/domain filters to discover the URLs it needs.

// @lc-docs-hide-cell


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

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

有关所有 Tavily Map API 功能和配置的详细文档，请访问 API 参考： docs.tavily.com/documentation/api-reference/endpoint/map