langchain/tavily 版本演进与实战指南从 v1.0 到 v1.2 的搜索、提取、爬取与研究工具链【免费下载链接】langchainjsThe agent engineering platform项目地址: https://gitcode.com/GitHub_Trending/la/langchainjslangchain/tavily是 LangChain.js 生态中针对 Tavily 搜索引擎的官方集成包为 AI Agent 提供实时、准确、面向 LLM/RAG 优化的搜索能力。本文以 libs/providers/langchain-tavily/CHANGELOG.md 为脉络完整梳理该包从 v1.0.0 到 v1.2.0 的演进历程并结合 README.md 与src/目录下的全部源码逐一拆解TavilySearch、TavilyExtract、TavilyCrawl、TavilyMap、TavilyResearch、TavilyGetResearch六大工具的参数细节、调用方式与底层实现原理。读完本文你将能独立配置 API 密钥、组合使用全部六个工具搭建一个具备搜索、内容提取、站点爬取、深度研究与异步结果回收能力的 Agent 工具链并理解这些能力背后的版本设计意图。一、版本演进总览一条清晰的功能主线依据 CHANGELOG.mdlangchain/tavily自 v1.0.0 起经历了三个关键版本每个版本对应一次明确的能力升级版本类型核心变更1.0.0Major与 LangChain v1.0 兼容进入 1.x 稳定基线1.0.1Patch修复moduleResolution: node兼容性问题1.1.0Minor新增 Tavily Research深度研究端点1.2.0Minor新增 intent-based extraction为 extract 与 crawl 引入query和chunks_per_source参数从版本节奏可以看出v1.0.0 解决的是「能否稳定运行在 LangChain v1.0 之上」的基线问题v1.1.0 将能力从「实时检索」拓展到「异步深度研究」而 v1.2.0 则把重点放在「提取结果与用户意图的精准对齐」上。下文按时间顺序逐个展开。二、v1.0.0 与 v1.0.1LangChain v1.0 兼容与模块解析修复v1.0.0 是一个 Major 版本官方说明该版本「为与 LangChain v1.0 兼容而更新」对应 LangChain v1.0 发布说明中的整体迁移内容。从 package.json 可以看到该包当前的依赖基线peerDependencies要求langchain/core: ^1.0.0即强制要求宿主项目使用 LangChain v1.0 及以上的核心运行时dependencies仅声明zod: ^3.25.76 || ^4支持 Zod v3 与 v4 双版本降低与上层 Agent 框架的版本冲突概率engines.node: 20运行环境要求 Node.js 20 及以上。v1.0.1 是一个 Patch 修复针对的是moduleResolution: node即 TypeScript 经典的 node 解析策略下的兼容性问题。这一修复的意义在于并非所有项目都使用moduleResolution: bundler或node16/nodenext这类现代解析策略仍有许多存量项目沿用node策略而langchain/core内部通过相对路径引用类型定义如 tavily-extract.ts 中直接import { InferInteropZodOutput } from langchain/core/dist/utils/types/zod.js这种写法在node解析模式下需要包内导出结构与之匹配。该修复保证了两类解析策略下均能正常编译与运行。三、v1.1.0Tavily Research 端点——把「搜一下」升级为「研究一番」v1.1.0 引入的是 Tavily 的 research深度研究端点对应两个新工具TavilyResearch与TavilyGetResearch实现文件分别为 tavily-research.ts 和 tavily-get-research.ts。3.1 异步任务模型request_id 驱动的两段式调用与 search/extract 的同步请求不同research 端点采用异步队列模型TavilyResearch提交任务后立即返回一个排队响应TavilyResearchQueueResponse其中包含request_id真正的研究报告由 Tavily 侧的研究 Agent 异步产出之后通过TavilyGetResearch携带request_id主动拉取。这一设计让 Agent 可以在研究进行的同时继续执行其他任务而非阻塞等待。从 utils.ts 的类型定义可以还原完整的数据流TavilyResearchQueueResponse提交后立即返回含request_id、created_at、初始statuspending或in_progress、input、model等字段TavilyGetResearchResponse拉取完成态含request_id、created_at、completed_at、statuscompleted/pending/in_progress/failed、content字符串或结构化对象、sources来源列表、response_timeTavilyGetIncompleteResearchResponse当任务尚未完成时仅返回request_id、status、response_time三个字段。底层调用路径在 utils.tsTavilyResearchAPIWrapper.rawResults()向POST {apiBaseUrl}/research发起请求getResearch()则向GET {apiBaseUrl}/research/{request_id}发起请求——一写一读构成完整的两段式异步协议。3.2 TavilyResearch 参数详解TavilyResearch的输入 schematavily-research.ts与构造参数均支持以下配置参数类型默认值说明inputstring必填研究任务或问题描述modelmini \| pro \| autoautomini面向狭窄、边界清晰的问题做定向高效研究pro面向跨多子主题的复杂课题做多角度全面研究auto由 Tavily 根据任务复杂度自动选择outputSchemaJSON Schema 对象无定义研究输出的结构化形状必须含properties可含required支持嵌套对象与数组保证输出可预测、可校验streambooleanfalse为true时返回 Server-Sent EventsSSE流式输出citationFormatnumbered \| mla \| apa \| chicagonumbered报告引用的排版格式源码中值得注意的实现细节是构造参数与调用参数支持双层覆盖tavily-research.ts即this.model ?? model ?? auto——实例化时传入的值优先级最高其次才是 invoke 时的入参最后落到默认值。outputSchema在工具层通过递归的 Zod schemaoutputSchemaPropertySchema做了运行时校验支持object/string/integer/number/array五类字段类型并允许无限层级嵌套tavily-research.ts。3.3 流式研究SSE 的原生透传当stream: true时utils.ts 中的rawResults()会通过response.body.getReader()逐块读取响应体用async function*生成器产出Buffer数据块。TavilyResearch._call()拿到这个生成器后会将其包装为「纯AsyncIterable」仅暴露[Symbol.asyncIterator]再返回tavily-research.ts。这一包装是刻意的避免基类StructuredTool.call()因检测到AsyncGenerator存在.next()方法而把流内部消费掉从而将 SSE 流原样保留给调用方消费。3.4 TavilyGetResearch按 request_id 回收结果TavilyGetResearch的输入极简只有一个必填字段requestIdtavily-get-research.ts。_call()中会对响应做形状校验若返回对象缺失request_id或status字段则抛出「Invalid research response for request_id ...」错误tavily-get-research.ts。组合使用两工具的标准流程为import { TavilyResearch, TavilyGetResearch } from langchain/tavily; const research new TavilyResearch(); const queue await research.invoke({ input: Research the latest developments in AI, model: mini, // 可选默认 auto citationFormat: apa, // 可选默认 numbered }); console.log(queue.request_id); // 立即拿到任务 ID // 任务完成后回收结果 const getter new TavilyGetResearch(); const report await getter.invoke({ requestId: queue.request_id, }); console.log(report); // 含 content、sources、status 等四、v1.2.0Intent-Based Extraction——让提取结果对齐用户意图v1.2.0 的核心是intent-based extraction基于意图的提取官方变更说明明确为 extract 与 crawl 新增了query与chunks_per_source两个参数。在源码中这一能力体现在两个层面。4.1 TavilyExtract 的 query 参数提取内容的重排依据在 tavily-extract.ts 中TavilyExtractInput新增了query?: string字段注释为User intent query for reranking extracted content chunks用于对提取的内容块进行重排的用户意图查询构造参数TavilyExtractAPIRetrieverFields与 invoke 输入 schema 中均有同名query字段tavily-extract.ts。其工作机制是当query与urls同时提供时Tavily 会基于该意图查询对从各页面提取出的内容块进行相关性重排让「与用户关心的问题最相关」的内容优先返回。这在 RAG 场景中尤其有价值——例如提取一份长文档时直接告诉 Tavily「你正在调研关于内容分块策略的部分」得到的raw_content排序就会贴合研究重点。_call()中同样实现了构造参数优先的合并逻辑this.query ?? querytavily-extract.ts且底层请求通过TavilyExtractAPIWrapper.rawResults()提交给POST {apiBaseUrl}/extractutils.ts。import { TavilyExtract } from langchain/tavily; const tool new TavilyExtract({ extractDepth: advanced, // 可选basic | advanced // query: Llama 3 context window size, // 也可在构造时指定 }); const results await tool.invoke({ urls: [https://en.wikipedia.org/wiki/Llama_(language_model)], query: What is the context window size of Llama 3?, // 意图查询驱动内容重排 }); console.log(results);4.2 chunks_per_source每个来源返回的内容块数量chunks_per_source控制从每个来源取回的内容块数量。在 utils.ts 的TavilySearchParamsBase中该参数注释为「每个来源检索的 content 块数每块最长 500 字符仅在 search depth 为 advanced 时可用默认 3」。而在 search 工具侧它同样以chunksPerSource暴露在构造参数中tavily-search.ts并随请求透传给 API。对于 crawl 场景从源码看 tavily-crawl.ts 在构造rawResults请求体时固定携带chunksPerSource: 3同时TavilyCrawlParams类型中也声明了同名可选字段utils.ts默认 3。也就是说crawl 请求默认对每个抓取页面取回 3 块内容块长度上限 500 字符这既控制了返回体体积也保证了页面正文的完整性。4.3 无结果时的智能建议可读性设计v1.2.0 的另一个可见改进体现在工具的错误提示上。三个「结果型」工具search/extract/crawl/map在返回空结果时都会生成针对性建议例如TavilySearch会建议「移除time_range参数」「改用 advanced 深度」「尝试 general topic」tavily-search.tsTavilyExtract会建议改用advanced提取深度tavily-extract.tscrawl/map 则会建议补充selectPaths、selectDomains或excludeDomains过滤条件tavily-crawl.ts。所有错误均以{ error: string }形态返回而非直接抛出方便 Agent 将错误信息纳入自身推理。五、六大工具完整 API 速查除前文详述的 extract 与 research 外包内还有 search、crawl、map 三个工具全部导出在 index.ts。以下为每个工具的完整参数与调用示例。5.1 TavilySearch面向 LLM/RAG 优化的搜索构造参数tavily-search.ts包括参数类型默认值说明maxResultsnumber5最大返回条数searchDepthbasic \| advancedbasic搜索深度复杂/冷门查询建议 advancedtopicgeneral \| news \| financegeneral搜索主题分类timeRangeday \| week \| month \| year无时间范围过滤includeAnswerbooleanfalse附带 LLM 生成的短答案includeRawContentboolean \| markdown \| textfalse附带清洗后的原始 HTML/正文text会增加延迟includeImages/includeImageDescriptionsbooleanfalse附带图片及图片描述includeDomains/excludeDomainsstring[]无域名的包含/排除过滤chunksPerSourcenumber3每来源内容块数仅 advanced 深度生效includeFavicon/includeUsagebooleanfalse附带 favicon / 用量信息countrystring无全小写国家名过滤autoParametersbooleanfalse让 Tavily 依据查询自动决定最优参数仅构造时可设import { TavilySearch } from langchain/tavily; const tool new TavilySearch({ maxResults: 5, topic: general, includeAnswer: false, includeRawContent: false, includeImages: false, searchDepth: basic, }); const results await tool.invoke({ query: what is the current weather in SF?, }); console.log(results);_call()中的关键实现是「实例值优先」的合并策略this.includeDomains ?? includeDomains即构造时配置优先于调用时入参tavily-search.ts。5.2 TavilyExtractURL 批量内容提取输入为urls必填字符串数组extractDepthincludeImagesquerytavily-extract.ts。构造参数额外支持formatmarkdown \| text默认 markdown、includeFavicon、includeUsage。响应体TavilyExtractResponse由三部分组成results每项含url、raw_content、可选的images、failed_results处理失败的 URL 及错误原因、response_timeutils.ts。当全部 URL 均失败时工具也会返回错误信息与建议tavily-extract.ts。import { TavilyExtract } from langchain/tavily; const tool new TavilyExtract({ extractDepth: basic, includeImages: false, }); const results await tool.invoke({ urls: [https://en.wikipedia.org/wiki/Lionel_Messi], }); console.log(results);5.3 TavilyCrawl结构化站点爬取TavilyCrawl从指定 base URL 出发采用BFS广度优先策略爬取整站深度指从根 URL 出发的链接跳数与 URL 目录结构无关tavily-crawl.ts。爬取范围由四个维度控制广度maxDepth最大跳数默认 3、maxBreadth每层最多页面数默认 50总量limit最多抓取页数默认 100聚焦instructions自然语言指令如Python SDK、selectPaths/selectDomains正则白名单、excludePaths/excludeDomains正则黑名单、categories预定义类别共 22 种如Documentation、Blogs、Community、Pricing、Careers等边界allowExternal是否允许跨域跟随链接。调用时categories会经Array.from(new Set(...))去重tavily-crawl.ts请求体固定携带chunksPerSource: 3。import { TavilyCrawl } from langchain/tavily; const tool new TavilyCrawl({ extractDepth: basic, format: markdown, maxDepth: 3, maxBreadth: 50, limit: 100, includeImages: false, allowExternal: false, }); const results await tool.invoke({ url: https://docs.tavily.com/, instructions: Find information about the LangChain integration., }); console.log(results);5.4 TavilyMap站点地图生成TavilyMap与TavilyCrawl共享同一套范围控制参数maxDepth/maxBreadth/limit/instructions/selectPaths/selectDomains/excludePaths/excludeDomains/allowExternal/categories但输出不同响应TavilyMapResponse的results是URL 字符串数组而非提取内容utils.ts适合先摸清站点结构、再决定后续抓取或提取哪些页面的两段式工作流。import { TavilyMap } from langchain/tavily; const tool new TavilyMap({ maxDepth: 3, maxBreadth: 50, limit: 100, allowExternal: false, }); const results await tool.invoke({ url: https://docs.tavily.com/, }); console.log(results); // { base_url, results: string[], response_time }六、底层实现原理六个工具共享的基建所有工具最终都依赖 utils.ts 中的 API Wrapper 体系理解它们有助于排查请求层面的问题。6.1 鉴权与端点路由BaseTavilyAPIWrapper构造时从构造参数或环境变量TAVILY_API_KEY读取密钥getEnvironmentVariable(TAVILY_API_KEY)缺失时直接抛错默认 base URL 为https://api.tavily.comutils.ts。五个子类分别对应五个 REST 端点Wrapper 类端点TavilySearchAPIWrapperPOST /searchTavilyExtractAPIWrapperPOST /extractTavilyCrawlAPIWrapperPOST /crawlTavilyMapAPIWrapperPOST /mapTavilyResearchAPIWrapperPOST /research、GET /research/{request_id}所有 POST 请求统一携带Authorization: Bearer key并在 JSON 请求体中附加client_source: langchain-js标记utils.ts便于 Tavily 侧识别客户端来源。6.2 camelCase → snake_case 自动转换工具层暴露给开发者的是 TypeScript 惯例的 camelCase 参数如maxResults、chunksPerSource、includeRawContent而 REST API 期望 snake_case如max_results、chunks_per_source、include_raw_content。convertCamelToSnakeCase()在发送前完成统一转换同时自动丢弃值为undefined的字段utils.ts避免把空参数序列化进请求体。6.3 错误透传各 Wrapper 在响应非 OK 时从响应体detail.error中提取服务端错误信息统一抛出Error {status}: {message}如 utils.ts工具层再将其捕获为{ error: string }返回。七、安装、鉴权与验证安装要求 Node.js ≥ 20宿主需已安装langchain/core^1.0.0npm install langchain/tavily鉴权有两种方式任选其一// 方式一环境变量推荐避免密钥写死在代码中 process.env.TAVILY_API_KEY YOUR_API_KEY; // 方式二构造时显式传入 const tool new TavilySearch({ tavilyApiKey: YOUR_API_KEY });所有工具继承StructuredTool因此可直接放入任何支持 LangChain 工具的 Agent/链中。仓库内的测试用例可作参考单元测试如 search.test.ts、extract.test.ts、research.test.ts验证参数合并与错误处理逻辑集成测试*.int.test.ts如 search.int.test.ts则需要在真实TAVILY_API_KEY下运行pnpm test:intpackage.json。八、总结一条从检索到研究的 Agent 工具链回顾 CHANGELOG 的版本轨迹langchain/tavily的能力演进遵循一条清晰的产品逻辑v1.0 建立 LangChain v1.0 兼容基线 → v1.0.1 扩大兼容面 → v1.1.0 引入异步深度研究TavilyResearchTavilyGetResearch让 Agent 从「快速查证」升级为「深度调研」 → v1.2.0 通过 intent-based extractionquery重排 chunks_per_source分块让提取与爬取结果贴合用户真实意图。实际落地时这六个工具天然构成一套完整的 Agent 数据采集流水线用TavilySearch发现线索 → 用TavilyExtract定点提取关键页面 → 用TavilyMap摸清站点结构 → 用TavilyCrawl批量抓取 → 用TavilyResearch提交深度研究任务 → 用TavilyGetResearch异步回收结构化报告。本文所述参数、端点与源码路径均可在当前仓库的 libs/providers/langchain-tavily 目录下逐一核对。【免费下载链接】langchainjsThe agent engineering platform项目地址: https://gitcode.com/GitHub_Trending/la/langchainjs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
@langchain/tavily 版本演进与实战指南：从 v1.0 到 v1.2 的搜索、提取、爬取与研究工具链
langchain/tavily 版本演进与实战指南从 v1.0 到 v1.2 的搜索、提取、爬取与研究工具链【免费下载链接】langchainjsThe agent engineering platform项目地址: https://gitcode.com/GitHub_Trending/la/langchainjslangchain/tavily是 LangChain.js 生态中针对 Tavily 搜索引擎的官方集成包为 AI Agent 提供实时、准确、面向 LLM/RAG 优化的搜索能力。本文以 libs/providers/langchain-tavily/CHANGELOG.md 为脉络完整梳理该包从 v1.0.0 到 v1.2.0 的演进历程并结合 README.md 与src/目录下的全部源码逐一拆解TavilySearch、TavilyExtract、TavilyCrawl、TavilyMap、TavilyResearch、TavilyGetResearch六大工具的参数细节、调用方式与底层实现原理。读完本文你将能独立配置 API 密钥、组合使用全部六个工具搭建一个具备搜索、内容提取、站点爬取、深度研究与异步结果回收能力的 Agent 工具链并理解这些能力背后的版本设计意图。一、版本演进总览一条清晰的功能主线依据 CHANGELOG.mdlangchain/tavily自 v1.0.0 起经历了三个关键版本每个版本对应一次明确的能力升级版本类型核心变更1.0.0Major与 LangChain v1.0 兼容进入 1.x 稳定基线1.0.1Patch修复moduleResolution: node兼容性问题1.1.0Minor新增 Tavily Research深度研究端点1.2.0Minor新增 intent-based extraction为 extract 与 crawl 引入query和chunks_per_source参数从版本节奏可以看出v1.0.0 解决的是「能否稳定运行在 LangChain v1.0 之上」的基线问题v1.1.0 将能力从「实时检索」拓展到「异步深度研究」而 v1.2.0 则把重点放在「提取结果与用户意图的精准对齐」上。下文按时间顺序逐个展开。二、v1.0.0 与 v1.0.1LangChain v1.0 兼容与模块解析修复v1.0.0 是一个 Major 版本官方说明该版本「为与 LangChain v1.0 兼容而更新」对应 LangChain v1.0 发布说明中的整体迁移内容。从 package.json 可以看到该包当前的依赖基线peerDependencies要求langchain/core: ^1.0.0即强制要求宿主项目使用 LangChain v1.0 及以上的核心运行时dependencies仅声明zod: ^3.25.76 || ^4支持 Zod v3 与 v4 双版本降低与上层 Agent 框架的版本冲突概率engines.node: 20运行环境要求 Node.js 20 及以上。v1.0.1 是一个 Patch 修复针对的是moduleResolution: node即 TypeScript 经典的 node 解析策略下的兼容性问题。这一修复的意义在于并非所有项目都使用moduleResolution: bundler或node16/nodenext这类现代解析策略仍有许多存量项目沿用node策略而langchain/core内部通过相对路径引用类型定义如 tavily-extract.ts 中直接import { InferInteropZodOutput } from langchain/core/dist/utils/types/zod.js这种写法在node解析模式下需要包内导出结构与之匹配。该修复保证了两类解析策略下均能正常编译与运行。三、v1.1.0Tavily Research 端点——把「搜一下」升级为「研究一番」v1.1.0 引入的是 Tavily 的 research深度研究端点对应两个新工具TavilyResearch与TavilyGetResearch实现文件分别为 tavily-research.ts 和 tavily-get-research.ts。3.1 异步任务模型request_id 驱动的两段式调用与 search/extract 的同步请求不同research 端点采用异步队列模型TavilyResearch提交任务后立即返回一个排队响应TavilyResearchQueueResponse其中包含request_id真正的研究报告由 Tavily 侧的研究 Agent 异步产出之后通过TavilyGetResearch携带request_id主动拉取。这一设计让 Agent 可以在研究进行的同时继续执行其他任务而非阻塞等待。从 utils.ts 的类型定义可以还原完整的数据流TavilyResearchQueueResponse提交后立即返回含request_id、created_at、初始statuspending或in_progress、input、model等字段TavilyGetResearchResponse拉取完成态含request_id、created_at、completed_at、statuscompleted/pending/in_progress/failed、content字符串或结构化对象、sources来源列表、response_timeTavilyGetIncompleteResearchResponse当任务尚未完成时仅返回request_id、status、response_time三个字段。底层调用路径在 utils.tsTavilyResearchAPIWrapper.rawResults()向POST {apiBaseUrl}/research发起请求getResearch()则向GET {apiBaseUrl}/research/{request_id}发起请求——一写一读构成完整的两段式异步协议。3.2 TavilyResearch 参数详解TavilyResearch的输入 schematavily-research.ts与构造参数均支持以下配置参数类型默认值说明inputstring必填研究任务或问题描述modelmini \| pro \| autoautomini面向狭窄、边界清晰的问题做定向高效研究pro面向跨多子主题的复杂课题做多角度全面研究auto由 Tavily 根据任务复杂度自动选择outputSchemaJSON Schema 对象无定义研究输出的结构化形状必须含properties可含required支持嵌套对象与数组保证输出可预测、可校验streambooleanfalse为true时返回 Server-Sent EventsSSE流式输出citationFormatnumbered \| mla \| apa \| chicagonumbered报告引用的排版格式源码中值得注意的实现细节是构造参数与调用参数支持双层覆盖tavily-research.ts即this.model ?? model ?? auto——实例化时传入的值优先级最高其次才是 invoke 时的入参最后落到默认值。outputSchema在工具层通过递归的 Zod schemaoutputSchemaPropertySchema做了运行时校验支持object/string/integer/number/array五类字段类型并允许无限层级嵌套tavily-research.ts。3.3 流式研究SSE 的原生透传当stream: true时utils.ts 中的rawResults()会通过response.body.getReader()逐块读取响应体用async function*生成器产出Buffer数据块。TavilyResearch._call()拿到这个生成器后会将其包装为「纯AsyncIterable」仅暴露[Symbol.asyncIterator]再返回tavily-research.ts。这一包装是刻意的避免基类StructuredTool.call()因检测到AsyncGenerator存在.next()方法而把流内部消费掉从而将 SSE 流原样保留给调用方消费。3.4 TavilyGetResearch按 request_id 回收结果TavilyGetResearch的输入极简只有一个必填字段requestIdtavily-get-research.ts。_call()中会对响应做形状校验若返回对象缺失request_id或status字段则抛出「Invalid research response for request_id ...」错误tavily-get-research.ts。组合使用两工具的标准流程为import { TavilyResearch, TavilyGetResearch } from langchain/tavily; const research new TavilyResearch(); const queue await research.invoke({ input: Research the latest developments in AI, model: mini, // 可选默认 auto citationFormat: apa, // 可选默认 numbered }); console.log(queue.request_id); // 立即拿到任务 ID // 任务完成后回收结果 const getter new TavilyGetResearch(); const report await getter.invoke({ requestId: queue.request_id, }); console.log(report); // 含 content、sources、status 等四、v1.2.0Intent-Based Extraction——让提取结果对齐用户意图v1.2.0 的核心是intent-based extraction基于意图的提取官方变更说明明确为 extract 与 crawl 新增了query与chunks_per_source两个参数。在源码中这一能力体现在两个层面。4.1 TavilyExtract 的 query 参数提取内容的重排依据在 tavily-extract.ts 中TavilyExtractInput新增了query?: string字段注释为User intent query for reranking extracted content chunks用于对提取的内容块进行重排的用户意图查询构造参数TavilyExtractAPIRetrieverFields与 invoke 输入 schema 中均有同名query字段tavily-extract.ts。其工作机制是当query与urls同时提供时Tavily 会基于该意图查询对从各页面提取出的内容块进行相关性重排让「与用户关心的问题最相关」的内容优先返回。这在 RAG 场景中尤其有价值——例如提取一份长文档时直接告诉 Tavily「你正在调研关于内容分块策略的部分」得到的raw_content排序就会贴合研究重点。_call()中同样实现了构造参数优先的合并逻辑this.query ?? querytavily-extract.ts且底层请求通过TavilyExtractAPIWrapper.rawResults()提交给POST {apiBaseUrl}/extractutils.ts。import { TavilyExtract } from langchain/tavily; const tool new TavilyExtract({ extractDepth: advanced, // 可选basic | advanced // query: Llama 3 context window size, // 也可在构造时指定 }); const results await tool.invoke({ urls: [https://en.wikipedia.org/wiki/Llama_(language_model)], query: What is the context window size of Llama 3?, // 意图查询驱动内容重排 }); console.log(results);4.2 chunks_per_source每个来源返回的内容块数量chunks_per_source控制从每个来源取回的内容块数量。在 utils.ts 的TavilySearchParamsBase中该参数注释为「每个来源检索的 content 块数每块最长 500 字符仅在 search depth 为 advanced 时可用默认 3」。而在 search 工具侧它同样以chunksPerSource暴露在构造参数中tavily-search.ts并随请求透传给 API。对于 crawl 场景从源码看 tavily-crawl.ts 在构造rawResults请求体时固定携带chunksPerSource: 3同时TavilyCrawlParams类型中也声明了同名可选字段utils.ts默认 3。也就是说crawl 请求默认对每个抓取页面取回 3 块内容块长度上限 500 字符这既控制了返回体体积也保证了页面正文的完整性。4.3 无结果时的智能建议可读性设计v1.2.0 的另一个可见改进体现在工具的错误提示上。三个「结果型」工具search/extract/crawl/map在返回空结果时都会生成针对性建议例如TavilySearch会建议「移除time_range参数」「改用 advanced 深度」「尝试 general topic」tavily-search.tsTavilyExtract会建议改用advanced提取深度tavily-extract.tscrawl/map 则会建议补充selectPaths、selectDomains或excludeDomains过滤条件tavily-crawl.ts。所有错误均以{ error: string }形态返回而非直接抛出方便 Agent 将错误信息纳入自身推理。五、六大工具完整 API 速查除前文详述的 extract 与 research 外包内还有 search、crawl、map 三个工具全部导出在 index.ts。以下为每个工具的完整参数与调用示例。5.1 TavilySearch面向 LLM/RAG 优化的搜索构造参数tavily-search.ts包括参数类型默认值说明maxResultsnumber5最大返回条数searchDepthbasic \| advancedbasic搜索深度复杂/冷门查询建议 advancedtopicgeneral \| news \| financegeneral搜索主题分类timeRangeday \| week \| month \| year无时间范围过滤includeAnswerbooleanfalse附带 LLM 生成的短答案includeRawContentboolean \| markdown \| textfalse附带清洗后的原始 HTML/正文text会增加延迟includeImages/includeImageDescriptionsbooleanfalse附带图片及图片描述includeDomains/excludeDomainsstring[]无域名的包含/排除过滤chunksPerSourcenumber3每来源内容块数仅 advanced 深度生效includeFavicon/includeUsagebooleanfalse附带 favicon / 用量信息countrystring无全小写国家名过滤autoParametersbooleanfalse让 Tavily 依据查询自动决定最优参数仅构造时可设import { TavilySearch } from langchain/tavily; const tool new TavilySearch({ maxResults: 5, topic: general, includeAnswer: false, includeRawContent: false, includeImages: false, searchDepth: basic, }); const results await tool.invoke({ query: what is the current weather in SF?, }); console.log(results);_call()中的关键实现是「实例值优先」的合并策略this.includeDomains ?? includeDomains即构造时配置优先于调用时入参tavily-search.ts。5.2 TavilyExtractURL 批量内容提取输入为urls必填字符串数组extractDepthincludeImagesquerytavily-extract.ts。构造参数额外支持formatmarkdown \| text默认 markdown、includeFavicon、includeUsage。响应体TavilyExtractResponse由三部分组成results每项含url、raw_content、可选的images、failed_results处理失败的 URL 及错误原因、response_timeutils.ts。当全部 URL 均失败时工具也会返回错误信息与建议tavily-extract.ts。import { TavilyExtract } from langchain/tavily; const tool new TavilyExtract({ extractDepth: basic, includeImages: false, }); const results await tool.invoke({ urls: [https://en.wikipedia.org/wiki/Lionel_Messi], }); console.log(results);5.3 TavilyCrawl结构化站点爬取TavilyCrawl从指定 base URL 出发采用BFS广度优先策略爬取整站深度指从根 URL 出发的链接跳数与 URL 目录结构无关tavily-crawl.ts。爬取范围由四个维度控制广度maxDepth最大跳数默认 3、maxBreadth每层最多页面数默认 50总量limit最多抓取页数默认 100聚焦instructions自然语言指令如Python SDK、selectPaths/selectDomains正则白名单、excludePaths/excludeDomains正则黑名单、categories预定义类别共 22 种如Documentation、Blogs、Community、Pricing、Careers等边界allowExternal是否允许跨域跟随链接。调用时categories会经Array.from(new Set(...))去重tavily-crawl.ts请求体固定携带chunksPerSource: 3。import { TavilyCrawl } from langchain/tavily; const tool new TavilyCrawl({ extractDepth: basic, format: markdown, maxDepth: 3, maxBreadth: 50, limit: 100, includeImages: false, allowExternal: false, }); const results await tool.invoke({ url: https://docs.tavily.com/, instructions: Find information about the LangChain integration., }); console.log(results);5.4 TavilyMap站点地图生成TavilyMap与TavilyCrawl共享同一套范围控制参数maxDepth/maxBreadth/limit/instructions/selectPaths/selectDomains/excludePaths/excludeDomains/allowExternal/categories但输出不同响应TavilyMapResponse的results是URL 字符串数组而非提取内容utils.ts适合先摸清站点结构、再决定后续抓取或提取哪些页面的两段式工作流。import { TavilyMap } from langchain/tavily; const tool new TavilyMap({ maxDepth: 3, maxBreadth: 50, limit: 100, allowExternal: false, }); const results await tool.invoke({ url: https://docs.tavily.com/, }); console.log(results); // { base_url, results: string[], response_time }六、底层实现原理六个工具共享的基建所有工具最终都依赖 utils.ts 中的 API Wrapper 体系理解它们有助于排查请求层面的问题。6.1 鉴权与端点路由BaseTavilyAPIWrapper构造时从构造参数或环境变量TAVILY_API_KEY读取密钥getEnvironmentVariable(TAVILY_API_KEY)缺失时直接抛错默认 base URL 为https://api.tavily.comutils.ts。五个子类分别对应五个 REST 端点Wrapper 类端点TavilySearchAPIWrapperPOST /searchTavilyExtractAPIWrapperPOST /extractTavilyCrawlAPIWrapperPOST /crawlTavilyMapAPIWrapperPOST /mapTavilyResearchAPIWrapperPOST /research、GET /research/{request_id}所有 POST 请求统一携带Authorization: Bearer key并在 JSON 请求体中附加client_source: langchain-js标记utils.ts便于 Tavily 侧识别客户端来源。6.2 camelCase → snake_case 自动转换工具层暴露给开发者的是 TypeScript 惯例的 camelCase 参数如maxResults、chunksPerSource、includeRawContent而 REST API 期望 snake_case如max_results、chunks_per_source、include_raw_content。convertCamelToSnakeCase()在发送前完成统一转换同时自动丢弃值为undefined的字段utils.ts避免把空参数序列化进请求体。6.3 错误透传各 Wrapper 在响应非 OK 时从响应体detail.error中提取服务端错误信息统一抛出Error {status}: {message}如 utils.ts工具层再将其捕获为{ error: string }返回。七、安装、鉴权与验证安装要求 Node.js ≥ 20宿主需已安装langchain/core^1.0.0npm install langchain/tavily鉴权有两种方式任选其一// 方式一环境变量推荐避免密钥写死在代码中 process.env.TAVILY_API_KEY YOUR_API_KEY; // 方式二构造时显式传入 const tool new TavilySearch({ tavilyApiKey: YOUR_API_KEY });所有工具继承StructuredTool因此可直接放入任何支持 LangChain 工具的 Agent/链中。仓库内的测试用例可作参考单元测试如 search.test.ts、extract.test.ts、research.test.ts验证参数合并与错误处理逻辑集成测试*.int.test.ts如 search.int.test.ts则需要在真实TAVILY_API_KEY下运行pnpm test:intpackage.json。八、总结一条从检索到研究的 Agent 工具链回顾 CHANGELOG 的版本轨迹langchain/tavily的能力演进遵循一条清晰的产品逻辑v1.0 建立 LangChain v1.0 兼容基线 → v1.0.1 扩大兼容面 → v1.1.0 引入异步深度研究TavilyResearchTavilyGetResearch让 Agent 从「快速查证」升级为「深度调研」 → v1.2.0 通过 intent-based extractionquery重排 chunks_per_source分块让提取与爬取结果贴合用户真实意图。实际落地时这六个工具天然构成一套完整的 Agent 数据采集流水线用TavilySearch发现线索 → 用TavilyExtract定点提取关键页面 → 用TavilyMap摸清站点结构 → 用TavilyCrawl批量抓取 → 用TavilyResearch提交深度研究任务 → 用TavilyGetResearch异步回收结构化报告。本文所述参数、端点与源码路径均可在当前仓库的 libs/providers/langchain-tavily 目录下逐一核对。【免费下载链接】langchainjsThe agent engineering platform项目地址: https://gitcode.com/GitHub_Trending/la/langchainjs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
