AutoGPT Platform Tavily Search 块详解：Web 检索、LLM 就绪上下文与成本追踪

Tavily Search 是 AutoGPT Platform 图形化 Agent 编排器中内置的搜索块，通过 Tavily 的 AI-native 搜索 API 完成实时网页检索。本文以 search.md 文档为主线，结合该块在仓库中的完整源码实现，逐项讲解其全部输入/输出参数、底层调用链、运行原理与计费逻辑，帮助你把它接入研究自动化、有据可依的问答（Grounded Q&A）以及新闻与市场监控等实际工作流中。

Tavily Search 在 AutoGPT Platform 中的定位

AutoGPT Platform 的核心构建单元是 Block（块）。Tavily 相关块位于 blocks/tavily 目录下，除本文聚焦的 Search 块外，还有 Extract（网页内容抽取）、Crawl（网页抓取） 和 Map（站点结构发现）。其中 Search 块承担的是"搜索"这一步：把查询发给 Tavily，取回带相关性评分与内容摘要的排序结果。

Search 块的类定义是 TavilySearchBlock，位于 search.py。它的 Block id 是 363bb641-2147-47a0-9aaf-caae26b06dcb，归属 BlockCategory.SEARCH（搜索类别），块描述为 "Searches the web using Tavily's AI-native search API"，与文档中的定义完全对应。

工作原理：从查询到"LLM 就绪上下文"

文档《How it works》部分概括了三层能力，源码则揭示了其完整执行链路：

1. 发起真实 API 调用：块内部通过官方 tavily Python SDK 的 AsyncTavilyClient 异步发起搜索请求，见 _search。这一私有方法刻意独立出来，就是为了在测试中通过 mock 拦截，便于离线验证。
2. 返回排序结果与评分摘要：Tavily 对结果做相关性排序，每条结果带 relevance score 和与查询相关的 content 片段。
3. 组装多种输出形态：原始 results 列表逐条产出 result；可选产出 LLM 综合生成的 answer；同时总是产出 context——将结果格式化为 Markdown 字符串，可直接喂给 LLM 块。

请求参数如何映射到 Tavily SDK

块在 run 中把图形化输入整理成 SDK 关键字参数 sdk_kwargs：

sdk_kwargs = {
    "query": input_data.query,
    "topic": input_data.topic.value,
    "search_depth": input_data.search_depth.value,
    "max_results": input_data.max_results,
    "include_answer": input_data.include_answer,
    "include_raw_content": input_data.include_raw_content,
    "include_usage": True,          # 让 API 返回真实 credit 消耗，供成本追踪使用
}
# time_range / include_domains / exclude_domains 仅在非空时才附带

注意两个细节：

• time_range 声明为可空（None），为空时不传给 API，表示不做时间过滤。
• include_domains 与 exclude_domains 只在列表非空时才写入 sdk_kwargs。
• include_usage: True 始终开启，是为了拿到 API 返回的 usage 报告，把"实际花费"而不是"预估花费"上报给平台的成本追踪系统（见下文成本部分）。

异常处理

一旦搜索抛错，块的 run 会捕获所有异常并包装为 BlockExecutionError，消息为 Search failed: {e}，同时携带块名与块 id。这是 Platform 侧统一的块级错误协议，出错后错误会在编排 UI 中定位到具体节点。

context 输出的确切格式

context 字符串由所有结果按如下模板拼接（中间用空行分隔）后产出：

Title
content-snippet

即 "{title}\n{content}"，见 search.py。因此把 context 接到 LLM 块上时，模型收到的是一份带链接 Markdown 的干净摘要文本，无需再处理 JSON 结构。

输入参数详解

输入	说明	类型	是否必填	默认值 / 约束（源码佐证）
query	搜索查询词	str	是	无默认
topic	搜索类别：general / news / finance	"general" | "news" | "finance"	否	general
search_depth	搜索深度：basic / fast / ultra-fast（1 credit）或 advanced（2 credits）	"basic" | "advanced" | "fast" | "ultra-fast"	否	basic
max_results	返回结果的最大条数	int	否	5，范围 1 <= x <= 20
time_range	仅返回发布在此时间窗内的结果	"day" | "week" | "month" | "year"	否	None（不限）
include_domains	限定只在这些域名内搜索	List[str]	否	空列表
exclude_domains	排除这些域名的结果	List[str]	否	空列表
include_answer	基于结果生成 LLM 版答案	bool	否	True
include_raw_content	为每条结果附带完整网页正文	bool	否	False

上表在文档基础上补齐了默认值与取值范围，全部可以从块的 Input schema 中核实：

• max_results 通过 ge=1、le=20 在 Schema 层直接约束了 1～20 的有效区间；
• 枚举类型的合法取值由 _api.py 中的 TavilySearchDepth（basic/advanced/fast/ultra-fast）、TavilyTopic（general/news/finance）、TavilyTimeRange（day/week/month/year）三个 Enum 定义，文档表格即来自这些枚举；
• topic、search_depth、max_results、time_range、exclude_domains、include_raw_content 在 Schema 上标为 advanced=True，即编辑器 UI 中默认收起、属于高级选项。

输出参数详解

输出	说明	类型
error	搜索失败时的错误信息	str
results	搜索结果列表	List[TavilySearchResult]
result	单条搜索结果（列表逐条产出）	TavilySearchResult
answer	基于搜索结果生成的 LLM 版答案	str
context	格式化后的搜索结果文本，可直接供 LLM 使用	str

每条结果 TavilySearchResult 的结构由 _api.py 定义，共五个字段：

字段	含义
title	结果页面标题
url	结果页面 URL
content	从页面抽取的、与查询相关的内容片段
score	与查询的相关性评分（0–1）
raw_content	页面完整正文（仅当开启 include_raw_content 时才存在，否则为 null）

results 与 result 两个输出同时存在：先整体产出一次 results 列表，再通过 for result in results: yield "result", result 逐条产出 result。这样下游既可以直接消费列表做批处理，也可以逐条驱动"循环式"节点。只有当 API 返回了 answer 字段时，块才会产出 answer（见 search.py）。

典型使用场景

文档给出了三类与 AutoGPT Platform 图形化编排高度契合的场景：

研究自动化（Research Automation）：对某个主题拉取当前的、按相关性排序的资料来源，然后把 context 输出直接接到 LLM 块上做总结或综合。这是最贴合块设计的用法——context 本身就是为 LLM 准备的 Markdown 文本，中间无需解析 JSON。

有据可依的问答（Grounded Q&A）：开启 include_answer（默认即为 True），让 Tavily 基于实时检索结果生成一条带出处的简明答案，适合需要"最新事实"的聊天机器人或 Agent，避免模型仅凭训练语料作答而过时。

新闻与市场监控（News & Market Monitoring）：把 topic 设为 news 或 finance，再用 time_range 收紧到 day/week/month/year 等较近时间窗，用于跟踪突发动态、公告或行情信息。也可叠加 include_domains / exclude_domains 把来源限定/排除到特定站点。

成本与计费：真实用量优先，预案兜底

文档提到 basic/fast/ultra-fast 搜索消耗 1 credit、advanced 消耗 2 credits。从源码看，块遵循"以 API usage 报告的真实消耗为准，缺失时才退回文档档位预估"的原则：

• 请求时始终带 include_usage: True；
• _api.py 的 credits_from_response(response, estimate) 先读取 response["usage"]["credits"]，若其为有效数值则直接采用；否则退回调用方传入的 estimate；
• 在 run 中，estimate 按档位给出：advanced 为 2、其余为 1；
• 每次执行的 credit 数乘以 CREDIT_USD = 0.008（即按量付费下 1 个 Tavily credit 合 0.008 美元，见 _api.py），得到美元成本后写入 NodeExecutionStats(provider_cost=..., provider_cost_type="cost_usd")，交由平台在 data/model.py 定义的执行统计体系中进行计费核算。

Provider 层面的定价约定在 _config.py 中：Tavily provider 的基础成本单位配置为 1000, BlockCostType.COST_USD，注释说明其换算遵循"1000 平台 credit 对应 1 美元"的约定（与 firecrawl 等其他搜索 provider 保持一致），并把计费方式描述为 "AI-native web search, extract, crawl and map"。也就是说，一个块的每次真实执行成本会进入平台侧的信用扣费与账单对账流程，而不是"白嫖"外部 API。

凭据配置：TAVILY_API_KEY

该块属于需要 API Key 的集成。其凭据由 _config.py 中的 ProviderBuilder("tavily") 统一管理，环境变量名为 TAVILY_API_KEY。在块的 Input schema 中，credentials 是必填项，描述为 "The Tavily integration requires an API Key."——也就是说，运行该块前你必须先在 Platform 中为该集成配置有效的 Tavily API Key，运行时通过 AsyncTavilyClient(api_key=credentials.api_key.get_secret_value()) 读取（见 search.py），密钥在模型层以 secret 形式隔离。

结合源码的验证示例与延伸阅读

块内置了可离线运行的测试样例，定义在 search.py：

• 测试输入为 query="What is AutoGPT?"、max_results=1，并注入测试凭据；
• 期望输出断言包括：results 为长度 1 的列表、单条 result 的 url 为 https://agpt.co、answer 恰好为 "AutoGPT is a platform for building AI agents."、context 中包含 "AutoGPT"；
• 同时通过 test_mock 对 _search 方法进行 mock，模拟 API 返回含 usage.credits = 1 的响应——这也再次印证了成本读取路径（真实 usage → credits_from_response）是设计上的一等公民。

若希望了解更多，可继续阅读同目录下的 extract.md、crawl.md 与 map.md，它们分别覆盖"抓取指定 URL 的内容""站点深度抓取"与"先梳理站点 URL 结构再决定抓什么"等相邻能力；而将 context 接到 LLM 的用法，可参考平台文档中关于 LLM 块与块编排的说明（如 agent-blocks.md）。

---

综上，Tavily Search 块的价值在于把"外部实时搜索"收敛成一个输入/输出都高度结构化的编排节点：输入侧用 topic、time_range、域名白/黑名单和 search_depth 精确圈定检索范围，输出侧同时给出结构化结果、逐条结果与 LLM 就绪的 context，并把每次真实花费精确回传平台计费。在 AutoGPT Platform 的可视化画布上，从搜索到 LLM 总结再到后续动作，通常只需将它与其他块串联即可完成一个端到端的实时信息处理 Agent。