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

# Tavily 地图集成

> 通过LangChain JavaScript与Tavily地图工具集成。

[Tavily](https://tavily.com/) 是专为 AI 智能体（LLM）构建的搜索引擎，能够快速提供实时、准确且事实性的结果。Tavily 提供一个 [Map](https://docs.tavily.com/documentation/api-reference/endpoint/map) 端点，该端点遍历网站并返回发现的 URL 列表，但不提取页面内容，非常适合了解网站结构或在大型网站上定位特定页面。

## 概述

### 集成细节

| 类 | 包 | [PY 支持](https://langchain-docs-zh.mintlify.site/langchain/oss/python/integrations/tools/tavily_map.md) | 下载量 | 版本 |
| :- | :- | :-: | :-: | :-: |
| [`TavilyMap`](https://reference.langchain.com/javascript/langchain-tavily/TavilyMap) | [`@langchain/tavily`](https://www.npmjs.com/package/@langchain/tavily) | ✅ | ![NPM - 下载量](https://img.shields.io/npm/dm/@langchain/tavily?style=flat-square\&label=%20&) | ![NPM - 版本](https://img.shields.io/npm/v/@langchain/tavily?style=flat-square\&label=%20&) |

### 工具特性

| [返回工件](https://langchain-docs-zh.mintlify.site/langchain/oss/langchain/tools.md) | 原生异步 | 返回数据 | 定价 |
| :-: | :-: | :-: | :-: |
| ❌ | ✅ | 发现的 URL 列表 | 每月 1,000 个免费信用额度 |

## 设置

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

```bash npm theme={null}
npm install @langchain/tavily @langchain/core
```

```bash yarn theme={null}
yarn add @langchain/tavily @langchain/core
```

```bash pnpm theme={null}
pnpm add @langchain/tavily @langchain/core
```

### 凭证

[设置 Tavily API 密钥](https://app.tavily.com) 并将其设置为名为 `TAVILY_API_KEY` 的环境变量。

```typescript theme={null}
process.env.TAVILY_API_KEY = "YOUR_API_KEY"
```

设置 [LangSmith](https://smith.langchain.com)（虽然不是必需的，但有助于实现最佳级别的可观察性）也非常有帮助：

```typescript theme={null}
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 Map API 文档](https://docs.tavily.com/documentation/api-reference/endpoint/map)。

```typescript theme={null}
import { TavilyMap } from "@langchain/tavily";

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

## 调用

### [使用参数直接调用](https://langchain-docs-zh.mintlify.site/langchain/oss/langchain/tools.md)

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

* `url` (必需): 用于开始映射的基 URL。
* 以下参数也可以在调用期间设置: `instructions`, `selectPaths`, `selectDomains`, `excludePaths`, `excludeDomains`, `allowExternal`。

注意：可选参数可用于智能体动态设置。如果您在实例化期间设置了一个参数，然后在调用工具时使用不同的值，工具将使用您在调用期间传递的值。

```typescript theme={null}
await tool.invoke({ url: "https://docs.tavily.com" });
```

```json theme={null}
{
  "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 调用](https://langchain-docs-zh.mintlify.site/langchain/oss/langchain/tools.md)

我们也可以使用模型生成的 `ToolCall` 调用该工具，此时将返回一个 @\[`ToolMessage`]：

```typescript theme={null}
// 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));
```

## 在智能体中使用

我们可以通过将其传递给 `createAgent` 直接使用地图工具与 LangChain 智能体。智能体可以动态设置 `url`, `instructions` 和路径/域过滤器来发现所需的 URL。

```typescript theme={null}
// @lc-docs-hide-cell
import { ChatOpenAI } from "@langchain/openai";

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

```typescript theme={null}
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 参考

有关 Tavily Map API 所有特性和配置的详细文档，请访问 API 参考：[docs.tavily.com/documentation/api-reference/endpoint/map](https://docs.tavily.com/documentation/api-reference/endpoint/map)

***

> 官方原文：[src/oss/javascript/integrations/tools/tavily\_map.mdx](https://github.com/langchain-ai/docs/blob/main/src/oss/javascript/integrations/tools/tavily_map.mdx) · 非官方翻译，译文由 AI 生成，以英文原文为准。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.