Exa Websets 集成块全解析：在 AutoGPT Platform 中用低代码工作流构建持续化网络监控数据集合

Exa Websets 是 Exa 提供的一种「持久化网络搜索集合」：创建之后它会在后台持续评估新匹配的网页实体（公司、人物、文章、研究论文等），并按自定义条件与结构化工况（enrichment）为每个条目补齐数据。AutoGPT Platform 的 blocks 目录中提供了 11 个围绕 Webset 生命周期管理的可编排块（Create / Get / List / Update / Delete / Cancel / Status / Summary / Ready Check / Preview / Create Or Find），允许你在可视化 Agent 图中以积木方式完成「建集合 → 预检 → 等待就绪 → 拉取条目 → 处理 → 清理」的完整闭环。读完本文，你将掌握每个 Webset 管理块的输入输出契约、底层源码实现要点，以及它们在持续监控、线索挖掘、竞争情报等场景中的组合方法。

本文对应的原始文档为 docs/integrations/block-integrations/exa/websets.md，全部 11 个块的实现集中在 websets.py。

---

一、前置条件：Exa 认证与成本模型

所有 Webset 管理块都要求配置 Exa 集成凭据。从源码 _config.py 可以看出，整个 Exa 块族共用一个 Provider 配置：

# autogpt_platform/backend/backend/blocks/exa/_config.py
exa = (
    ProviderBuilder("exa")
    .with_description("Neural web search")
    .with_api_key("EXA_API_KEY", "Exa API Key")
    .with_webhook_manager(ExaWebhookManager)
    .with_base_cost(100, BlockCostType.COST_USD)
    .build()
)

由此可知三个关键事实：

1. 凭据环境变量名为 EXA_API_KEY，在 AutoGPT Platform 中添加 Exa 集成时即为该 API Key。
2. 按美元计费并折算为平台额度：with_base_cost(100, BlockCostType.COST_USD) 表示每 1 美元消耗约 100 额度（约 0.01 美元/额度）；一次普通搜索通常只消耗 1–2 额度。
3. 每个 Webset 块在调用 Exa API 后都会调用 merge_exa_cost(self, response)（定义于 helpers.py），若 Exa 响应中带有 cost_dollars.total，则将其合并进节点的 provider_cost 统计，便于在平台中核算真实成本；若 SDK 未暴露单次定价（例如部分 webset CRUD 接口），该调用会自动跳过，不会产生虚假费用。

依赖说明：块基于 exa_py 官方 SDK 的 Exa / AsyncExa 客户端实现（同步与异步两种写法在源码中并存），Webset 相关请求统一走 exa.websets.* 接口。

---

二、11 个 Webset 管理块一览

下表汇总了本文档覆盖的全部块及其职责，后续小节逐个详解：

块	职责	生命周期阶段
Exa Preview Webset	创建前预览查询如何被解释（实体识别、条件生成、可提取字段）	规划
Exa Create Webset	创建持久化集合，可选择等待首批结果	创建
Exa Create Or Find Webset	按 external_id 幂等创建/复用集合	创建
Exa Get Webset	按 ID 或 external ID 获取集合完整详情	查询
Exa List Websets	分页列出全部集合	查询
Exa Webset Status	轻量状态概览（不拉取完整数据）	监控
Exa Webset Summary	综合摘要（统计 + 样本 + 搜索/增强/监控汇总）	监控/报告
Exa Webset Ready Check	判断集合是否可进入下一步，支持条件分支	编排
Exa Update Webset	更新集合的 key-value metadata	变更
Exa Cancel Webset	取消集合上所有进行中的操作	变更
Exa Delete Webset	永久删除集合及其全部数据	清理

从源码结构看，绝大多数块被标记为 BlockCategory.SEARCH，唯一例外是 Exa Webset Ready Check 同时挂载了 BlockCategory.SEARCH 与 BlockCategory.LOGIC 两个类别（见 ExaWebsetReadyCheckBlock.__init__），这也是它被设计为「条件分支闸门」的源码依据。

---

三、创建与预检

3.1 Exa Preview Webset —— 提交前先看清搜索将被如何理解

它是什么：在真正创建集合前，分析你的自然语言搜索查询，展示 Exa 将如何解释它——检测到的实体类型、自动生成的筛选条件、可用的增强列，以及改进建议。

核心输入：

输入	说明	类型	必填
query	待预览的搜索查询	str	是
entity_type	强制指定实体类型，不填则自动检测	"company" | "person" | "article" | "research_paper" | "custom" | "auto"	否
entity_description	自定义实体描述（entity_type 为 'custom' 时必填）	str	否

核心输出：preview（完整预览响应）、entity_type、entity_description、criteria、enrichment_columns、interpretation（查询将被如何处理的可读解释）、suggestions。

源码要点：ExaPreviewWebsetBlock 定义于 websets.py#L914。其实现值得注意：

• 平台为预览响应定义了镜像模型 PreviewWebsetModel / PreviewSearchModel / PreviewCriterionModel / PreviewEnrichmentModel（websets.py#L829 起），通过 from_sdk() 类方法把 SDK 响应转换成稳定模型。源码注释写明这是为了「响应稳定性」，避免 SDK 升级导致下游节点 schema 破裂。
• 块会程序化生成 interpretation 与 suggestions：例如无 criteria 时提示「考虑添加具体条件以缩小搜索范围」，无可用增强列时提示「请明确要提取哪些数据点」。

典型用途：查询优化、实体识别正确性校验、在提交前规划要提取的数据点。

3.2 Exa Create Webset —— 创建持久化搜索集合

它是什么：创建一个新的 Exa Webset（持久存储网络搜索结果集合），并可选等待首批结果返回。块 ID 为 0cda29ff-c549-4a19-8805-c982b7d4ec34。

工作原理：定义搜索查询、实体类型与可选匹配条件后，集合会对潜在匹配持续评估。支持范围搜索（仅在指定 import 或其它 webset 内搜索）、结构化数据增强（enrichment），以及基于关系的 hop 跳转搜索；可以选择等待首批结果，也可以立即返回交给异步流程处理。

核心输入（完整参数见源码 ExaCreateWebsetBlock.Input）：

输入	说明	类型	必填
search_query	搜索查询；若给出 URL 会被抓取并作为搜索上下文	str	是
search_count	尝试查找的条目数，实际可能因复杂度少于该值	int（默认 10，范围 1–1000）	否
search_entity_type	实体类型：company / person / article / research_paper / custom / auto（auto 时自动识别）	枚举	否
search_entity_description	自定义实体类型描述	str	否
search_criteria	逐条评估的匹配条件描述列表；缺省时自动从查询推断	List[str]	否
search_exclude_sources / search_exclude_types	从结果中排除的来源 ID 及对应类型（'import' / 'webset'）	List[str] / List	否
search_scope_sources / search_scope_types	将搜索范围限定到的来源 ID 及类型	List[str] / List	否
search_scope_relationships / search_scope_relationship_limits	hop 搜索的关系定义及每类相关实体的数量上限（与 scope 一一对应）	List[str] / List[int]	否
import_sources / import_types	导入来源 ID 及类型（'import' / 'webset'）	List[str] / List	否
enrichment_descriptions / enrichment_formats / enrichment_options / enrichment_metadata	对每个条目执行的增强任务描述、响应格式、选项标签、元数据	List	否
external_id	你自己的内部标识，用于后续引用	str	否
metadata	关联到该集合的键值对	Dict	否
wait_for_initial_results	是否等待初始搜索完成后再返回（默认 True）	bool	否
polling_timeout	最长等待秒数（默认 300，范围 1–600）	int	否

核心输出：webset（完整集合详情）、initial_item_count（等待模式下首批命中数）、completion_time（首次搜索完成耗时，秒）。

源码要点（websets.py#L108 起）：块把原本嵌套的搜索/增强参数拍平成 search_* / enrichment_* 前缀字段，便于可视化配置；运行时再组装为 CreateWebsetParameters(search=..., imports=..., enrichments=..., external_id=..., metadata=...)。实体枚举 SearchEntityType 与 EnrichmentFormat 都定义在本文件顶部。当 wait_for_initial_results=True 且有搜索参数时，会调用 exa.websets.wait_until_idle(id=..., timeout=polling_timeout, poll_interval=5)，并以 5 秒为间隔轮询；条目数取各 search 的 progress.found 之和。

注意块参数校验约束：search_count 被限制在 1–1000，polling_timeout 在 1–600 秒内——超出范围的配置会被块 schema 直接拒绝。

典型用途：销售线索挖掘（按条件持续找公司/人物）、竞争情报跟踪、按主题整理文章/论文的研究资料库。

3.3 Exa Create Or Find Webset —— 幂等创建，重试安全

它是什么：按 external_id 返回已存在的集合，否则新建（幂等操作）。块 ID 为 214542b6-3603-4bea-bc07-f51c2871cbd9。

核心输入：

输入	说明	类型	必填
external_id	外部标识，用于查找或创建	str	是
search_query	搜索查询（仅新建时使用）	str	否
search_count	首批查找的条目数（默认 10，范围 1–1000）	int	否
metadata	关联到集合的键值对	Dict	否

核心输出：webset、was_created（True=新建，False=已存在）。

实现细节（websets.py#L428）：块用 AsyncExa 先执行 websets.get(id=external_id)，若抛出 httpx.HTTPStatusError 且状态码为 404 才走创建分支并输出 was_created=True；其它 HTTP 错误则继续向上抛。这一模式完美支撑了重试安全：工作流无论重跑多少次都不会产生重复集合。

---

四、查询与巡检

4.1 Exa Get Webset —— 取回完整集合配置

它是什么：按 ID 或 external ID 获取单个集合的详细信息，包括当前状态、已配置的搜索、增强与监控。块 ID 为 6ab8e12a-132c-41bf-b5f3-d662620fa832。

核心输入：webset_id（集合 ID 或 external ID，str，必填）。

核心输出：

输出	说明	类型
webset_id	集合唯一标识	str
status	集合状态	str
external_id	外部标识	str
searches	已执行的搜索	List[Dict]
enrichments	已应用的增强	List[Dict]
monitors	已配置的监控	List[Dict]
metadata	关联键值对	Dict
created_at / updated_at	创建/更新时间	str

实现细节：源码把 SDK 返回的 searches/enrichments/monitors 通过 model_dump(by_alias=True, exclude_none=True) 序列化。平台侧 Webset 输出模型刻意将这三类字段声明为 List[dict]，源码注释明确说明是为了防止 UI 因嵌套对象崩溃。适合在执行其它操作前核对集合配置。

4.2 Exa List Websets —— 分页浏览全部集合

它是什么：分页返回你的全部集合，供浏览发现或构建管理界面。块 ID 为 1dcd8fd6-c13f-4e6f-bd4c-654428fa4757。

核心输入：

输入	说明	类型	必填
trigger	触发用占位，值会被忽略	Any	否
cursor	分页游标	str	否
limit	返回条数（默认 25，范围 1–100）	int	否

核心输出：websets（集合列表）、has_more（是否还有下一页）、next_cursor（下一页游标）。

实现细节：trigger 字段的设计值得注意——它用于在图中强制驱动该块执行，但其值完全被忽略（源码描述即「Trigger for the webset, value is ignored!」）。分页通过游标令牌完成，循环时把上一轮输出的 next_cursor 喂回 cursor 即可遍历全部集合。

4.3 Exa Webset Status —— 轻量状态快照

它是什么：不拉取完整条目数据，仅返回轻量状态概览，含 items / searches / enrichments / monitors 数量与当前处理状态。块 ID 为 47cc3cd8-840f-4ec4-8d40-fcaba75fbe1a。

核心输入：webset_id（str，必填）。

核心输出：

输出	说明	类型
webset_id	集合标识	str
status	当前状态（idle / running / paused 等）	str
item_count	集合内条目总数	int
search_count	已执行的搜索数	int
enrichment_count	已配置增强数	int
monitor_count	已配置监控数	int
last_updated	最后更新时间	str
is_processing	是否有操作正在运行	bool

实现细节：源码底层其实调用 websets.get() 但只提取统计字段；item_count 由各搜索的 progress.found 累加估算；is_processing 的判定是 status in ["running", "pending"]。适合做低成本的心跳轮询与健康检查。

4.4 Exa Webset Summary —— 综合报告

它是什么：生成集合的综合摘要：统计信息、样本条目、搜索与增强的详细分解。块 ID 为 9eff1710-a49b-490e-b486-197bf8b23c61。

核心输入：

输入	说明	类型	必填
webset_id	集合 ID 或 external ID	str	是
include_sample_items	是否包含样本条目（默认 True）	bool	否
sample_size	样本条数（默认 3，范围 0–10）	int	否
include_search_details	是否包含搜索详情	bool	否
include_enrichment_details	是否包含增强详情	bool	否

核心输出：webset_id、status、entity_type、total_items、sample_items、search_summary（含总搜索数/已完成/命中总数/前三条 query）、enrichment_summary、monitor_summary、statistics（总操作数、是否处理中、有无监控、每搜索平均条目数）、created_at、updated_at。

实现细节（websets.py#L1136）：摘要模型 SearchSummaryModel / EnrichmentSummaryModel / MonitorSummaryModel / WebsetStatisticsModel 均为独立 Pydantic 模型。样本条目通过 websets.items.list(webset_id=..., limit=sample_size) 获取；monitor 的 next_run 取所有监控 next_run_at 的最小值；enrichment 类型由 format 去重、标题截断 50 字符。可用开关按需裁剪摘要内容，以平衡信息完整度与响应体积。适合做管理层汇报与质量抽查。

4.5 Exa Webset Ready Check —— 条件分支闸门

它是什么：判断集合是否已「就绪」（无运行中操作，且可选地达到最小条目数），并给出下一步建议，用于条件化工作流分支。块 ID 为 faf9f0f3-e659-4264-b33b-284a02166bec。

核心输入：

输入	说明	类型	必填
webset_id	待检查集合	str	是
min_items	判定就绪所需的最小条目数（默认 1，≥0）	int	否

核心输出：

输出	说明	类型
is_ready	集合空闲且条目达到阈值时为 True	bool
status	当前集合状态	str
item_count	集合内条目数	int
has_searches / has_enrichments	是否已配置搜索/增强	bool
recommendation	建议动作（ready_to_process、waiting_for_results、needs_search 等）	str

实现细节：is_ready = (status == "idle") and (item_count >= min_items)。建议生成逻辑是一个有优先级的决策链（websets.py#L1407）：

未配置搜索            → needs_search
状态为 running/pending → waiting_for_results
条目不足              → insufficient_items
未配置增强            → ready_to_enrich
其余                  → ready_to_process

结合条件分支节点即可实现：数据不足时挂起等待、数据充足时才触发下游处理；min_items 是控制「最少积累多少条再开工」的关键旋钮。

---

五、变更与生命周期管理

5.1 Exa Update Webset —— 更新元数据

它是什么：更新现有集合的 metadata（键值对），可用于组织、打标签或加注释。块 ID 为 89ccd99a-3c2b-4fbf-9e25-0ffa398d0314。

核心输入：

输入	说明	类型	必填
webset_id	集合 ID 或 external ID	str	是
metadata	新键值对；设为 null 即清空全部元数据	Dict	否

核心输出：webset_id、status、external_id、metadata（更新后的元数据）、updated_at。

语义说明：源码 ExaUpdateWebsetBlock.run 只有在 metadata is not None 时才构造更新 payload——这也印证了「置 null 清空」这一特殊语义。该操作不会影响集合已有的 items、searches 或 enrichments，是纯粹的打标/注解操作。适合项目关联、工作流状态标记等场景。

5.2 Exa Cancel Webset —— 紧急刹车

它是什么：取消集合上所有正在进行的操作（搜索、增强）。块 ID 为 e40a6420-1db8-47bb-b00a-0e6aecd74176。

核心输入：webset_id（str，必填）。

核心输出：error、webset_id、status（取消后的状态）、external_id、success。

语义说明：取消后集合回到空闲状态，进行中的操作被停止；取消前已处理的条目会被保留。典型场景是停止不再需要的长耗时操作、修改配置前先取消、或出错后先停机再以修正参数重启。

5.3 Exa Delete Webset —— 不可逆的清理

它是什么：永久删除一个集合及其全部 items、searches、enrichments、monitors。块 ID 为 aa6994a2-e986-421f-8d4c-7671d3be7b7e。

核心输入：webset_id（Exa 生成的 ID 或你的 external_id，str，必填）。

核心输出：error、webset_id、external_id、status、success。

重要提示：此操作无法撤销。适合清理不再需要的集合与测试数据、删除过期数据、或移除闲置集合以避免不必要的存储成本。源码通过 exa.websets.delete(id=...) 实现，并固定返回 success: "true"。

---

六、结合其它 Webset 系列块的完整编排建议

Webset 管理块只是该集成的一半——要搭建完整管线，建议把 docs/integrations/block-integrations/exa/ 目录下的其它系列文档配合阅读：

• websets_search.md：向已有集合追加搜索、监控条目流动；
• websets_enrichment.md：为集合条目补充结构化字段；
• websets_polling.md：Exa Wait For Search / Wait For Enrichment / Wait For Webset，把异步操作变成阻塞调用；
• websets_items.md：读写集合中的条目数据；
• websets_monitor.md：定时增量监控；
• websets_import_export.md：集合数据导入导出。

一个典型的高价值组合模式如下：

1. Exa Preview Webset 先用示例 query 验证 Exa 的实体识别与条件生成是否符合预期；
2. Exa Create Or Find Webset（配合稳定 external_id）保证幂等创建，重试不产生脏数据；
3. Exa Webset Ready Check / Exa Wait For Webset 作为分支闸门与等待点，确认首批结果到齐；
4. 随后用 Exa Webset Items 与 Enrichment 系列块处理数据，配合 Exa Webset Status / Summary 周期性巡检；
5. 下线时按需 Exa Update Webset（打标归档）→ Exa Cancel Webset（停掉长任务）→ Exa Delete Webset（彻底清理）。

从源码类别也可以看到这种分层是有意为之：CRUD/查询块归属 SEARCH 类别保证在图谱中易于检索，而 Ready Check 额外归属 LOGIC 类别，意味着它天然应被用作条件节点。

---

七、开发与调试速查

对想深入源码的读者，以下位置值得精读：

• websets.py：全部 11 个块类、Webset 输出模型、镜像 Preview 模型、枚举定义、每个块的 __init__（含唯一块 ID）；
• helpers.py：merge_exa_cost / extract_exa_cost_usd 的成本归集逻辑，解释了为何不同块对成本处理方式不同；
• _config.py：Exa Provider 的统一凭据与计费折算。

调试时的常见检查点：

• 凭据：所有块都会在执行前校验 EXA_API_KEY；
• ID 参数：webset_id 字段同时接受 Exa 生成 ID 与自定义 external_id（源码 placeholder 统一为 webset-id-or-external-id），两者混用是常见配置错误来源；
• 参数范围：超过 schema 约束（如 limit > 100、polling_timeout > 600、sample_size > 10）的输入会被块 schema 直接拒绝；
• wait_until_idle 轮询：Create Webset 的等待模式以 5 秒间隔轮询直至空闲，注意 polling_timeout 上限为 600 秒；
• 错误分支：Create Or Find 依赖 404 语义区分「存在/不存在」，若上游代理改写状态码会导致幂等逻辑失效。

以上就是 Exa Websets 全系列管理块从创建、查询、监控到清理的完整使用指南。结合源码理解每个块的底层调用后，你就能在 AutoGPT Platform 中组合出可重试、可观测、成本可控的持续化网络监控 Agent。