AutoGPT Platform Apollo 集成指南：用 Search Organizations 块精准检索 B2B 企业数据

本指南围绕 AutoGPT Platform 内置的 Apollo 集成 —— Search Organizations（组织搜索）块展开，讲解如何基于 Apollo 的 B2B 企业数据库按员工规模、总部位置、行业关键词与企业名称等条件检索公司，并将其用于市场调研、外呼销售线索名单构建与竞品情报分析等实战流程。读完本文，你将掌握该块全部输入/输出参数的语义与默认值、底层 API 调用与分页原理，以及如何把它与同目录下的 People / Person 块衔接成完整的获客自动化 Agent。

一、块定位：从文档与源码看它在平台中的位置

Apollo 是一套面向销售与营销的 B2B 数据库服务，AutoGPT Platform 通过一组 block 把它的查询能力封装成了可视化工作流中的节点。本文讨论的组织搜索块负责"从 Apollo 数据库中检索公司信息"——这是对 organization.md 描述功能的一一展开。

在开源仓库中，该功能的注册与实现位于 apollo 块目录：

文件	职责
organization.py	定义 SearchOrganizationsBlock 的输入/输出 Schema 与执行逻辑
models.py	SearchOrganizationsRequest、SearchOrganizationsResponse、Organization 等 Pydantic 模型
_api.py	ApolloClient，负责真实 HTTP 请求与分页处理
_auth.py	API Key 凭据类型定义
_config.py	Provider 注册元信息（名称为 apollo，支持 api_key 认证）

从代码可以看到，该块在初始化时被标记为 BlockCategory.SEARCH 搜索类别，块的稳定 ID 为 3d71270d-599e-4148-9b95-71b35d2f44f0（见 organization.py）。Apollo 相关集成同目录下还有检索联系人的 people.py、person.py，对应文档为 people.md 与 person.md，可相互配合使用。

二、Search Organizations 输入参数详解

块的全部筛选条件由 organization.py 中 SearchOrganizationsBlock.Input 的 7 个参数与凭据字段构成。下表汇总了参数语义、类型、必填性与代码中的默认值：

输入	说明	类型	必填	源码默认值
organization_num_employees_range	公司员工人数范围，可按规模筛选企业；可添加多个区间以扩大命中面	List[int]	否	[0, 1000000]
organization_locations	公司总部所在地，支持城市、美国州与国别	List[str]	否	[]
organizations_not_locations	按总部所在地排除公司，用于回避不理想的开发/开拓区域	List[str]	否	[]
q_organization_keyword_tags	按行业关键词过滤，如 mining 只返回与矿业相关的公司	List[str]	否	[]
q_organization_name	按公司名精确/部分匹配过滤	str	否	""
organization_ids	限定返回指定 Apollo 组织 ID 的公司	List[str]	否	[]
max_results	最大返回条数	int	否	100（约束 1 <= x <= 50000）
credentials	Apollo API Key 凭据	凭据对象	是	—

注：文档表格中将员工区间字段标注为 List[int]，同时描述中提到"每个区间的上下界用逗号分隔"，而源码中的实际类型为整数列表、默认值为 [0, 1000000]，即用一组边界数字表达范围。在多范围叠加时，可依据这一边界语义扩展命中集合。

1. 员工规模区间：organization_num_employees_range

用于按公司 headcount 做"规模带"筛选。可添加多个区间扩大结果范围（文档中强调"adding multiple ranges expands results"）。若不填写，按代码默认值为 [0, 1000000]，即对规模不设实际限制。

2. 总部位置：organization_locations 与排除项 organizations_not_locations

两个位置参数都以公司总部所在地为准。文档强调两个关键行为：

• 即使公司在多地有办公室，搜索/排除仍基于总部。例如搜索 chicago，而某公司总部在 Boston，即使其他条件都吻合也不会出现在结果中；
• organizations_not_locations 用于明确排除区域，例如填入 ireland，则所有总部在爱尔兰的公司都会被剔除——这对限定"不开发区域"（undesirable territory）非常实用。

注意在组织搜索块中排除参数的实际字段名是复数 organizations_not_locations（模型定义见 models.py），而 organization_locations 的描述文字里以单数形式 organization_not_locations 指引用户，配置时请以块面板中实际字段名为准。

3. 关键词与公司名：q_organization_keyword_tags、q_organization_name

• 关键词标签 q_organization_keyword_tags：筛选与公司存在关联标签的企业，例如 mining 只返回与矿业行业有关的公司；
• 公司名 q_organization_name：支持部分匹配。若输入的公司名无法命中记录，即使其他条件全部满足，该公司也不会出现在结果中。文档给出的判别例子：输入 marketing 时，NY Marketing Unlimited 符合条件，而 NY Market Analysis 不符合——也就是说名字必须真正包含所给词元，而非任意子串。

4. 按 ID 精确圈定：organization_ids

每条公司在 Apollo 数据库中都有唯一 organization_id。该参数用于把结果限定到你已知的公司 ID 集合；需要获取 ID 时，可先调用本端点并从返回的 organization_id 字段中读取（首次返回的 organizations 输出即携带完整组织对象）。

5. 结果数量上限：max_results

不填则默认返回 100 条（default=100），源码还以 ge=1、le=50000 约束了合法取值范围，并将该参数标记为 advanced=True（在块 UI 中归于"高级"折叠区）。注意 max_results 只参与客户端收尾与分页循环，不随请求体发送给 Apollo（见下文请求构造）。

三、输出结构：error / organizations / organization

块的输出 Schema 定义在 organization.py：

输出	说明	类型
organizations	搜索到的全部组织（数组）	List[Organization]
organization	逐个流式吐出的组织对象	Organization
error	搜索失败时的错误信息	str

run 方法先调用 ApolloClient.search_organizations(...)，随后把每条结果通过 yield "organization", organization 逐个产出，最后再一次性产出 yield "organizations", organizations（见 organization.py）。这意味着在可视化画布上，你既可以连接"逐条处理"的迭代分支（例如对每家公司做一次下游动作），也可以直接拿到整个数组做后续合并/去重/入库。搜索成功时还会按返回条数记录 provider_cost（成本统计维度为 items），用于平台内的执行成本核算。

四、底层实现：请求、鉴权与分页原理

该块并非简单地转发一次请求，其实现包含值得了解的三个层次：

1. 请求体构造与凭据序列化

run 会把输入转换为 SearchOrganizationsRequest 再传给客户端。所有请求模型继承自自定义 BaseModel，其 model_dump() 默认剔除 credentials 字段并忽略未显式设置的项（exclude_none/exclude_unset/exclude_defaults 均开启，见 models.py），确保发送给 Apollo 的 JSON 干净、不含内部状态。

请求模型除了块面板暴露的筛选参数外，还包含分页控制字段 page（默认 1）与 per_page（默认 100），见 models.py。

2. 鉴权方式

ApolloClient 将 API Key 放入请求头 x-api-key（见 _api.py）。凭据类型即 APIKeyCredentials，Provider 声明为 apollo（见 _auth.py）。也就是说，在 AutoGPT Platform 的集成设置中为 Apollo 配置一个 API Key 即可启用本块。块的 SDK 注册信息由 _config.py 提供，其显示描述为 "Sales intelligence and prospecting"，认证方式为 api_key。

3. 请求端点与自动分页

组织的检索走 Apollo 的 POST https://api.apollo.io/api/v1/mixed_companies/search 接口（API_URL 定义见 _api.py）。客户端会读取响应中的 pagination（page、total_pages、total_entries 等，见 models.py），并在以下条件同时满足时自动翻页直到取够 max_results：

• max_results 已设置，且小于服务端 total_entries；
• 当前已收集条数仍小于 max_results；
• 当前页小于 total_pages，且本页仍有返回内容。

实现细节见 _api.py。每翻一页只追加"还缺多少条就补多少条"的数据（organizations[: max_results - len(organizations)]），最终返回前再做一次 [: max_results] 截断，因此 max_results 是实际生效的硬性上限。

五、返回的对象长什么样：Organization 字段画像

每条公司记录都会被解析为 Organization Pydantic 模型（见 models.py），其字段覆盖了从基本档案到销售信号的完整画像：

• 标识与域名：id（Apollo 组织 ID）、name、primary_domain、website_url、founded_year；
• 社媒与外部档案：linkedin_url、twitter_url、facebook_url、angellist_url、logo_url、chrunchbase_url；
• 联系方式：phone、sanitized_phone 以及结构化对象 primary_phone（含 number、source、sanitized_number）；
• 规模与公开市场信息：alexa_ranking、languages、publicly_traded_symbol（如 GOOGL）、publicly_traded_exchange（如 NASDAQ）；
• 归属与意图信号：owned_by_organization_id、intent_strength、show_intent、has_intent_signal_account、intent_signal_account。

得益于 extra="allow" 的配置，Apollo 后续追加的自定义字段也不会导致解析失败——未知键会被宽容保留而非抛错，这对长尾数据的健壮性很有帮助。

块测试中用一个包含上述全量字段的 Google 示例对象做断言（见 organization.py），可以把它当作"输出 JSON 长什么样"的最直观样例来理解。

六、典型应用：三个即插即用的实战场景

原文档给出该块的三个核心用途：

1. 市场调研（Market Research）：按行业关键词、员工规模、总部地区等条件圈定目标市场内的公司集合，做结构化分析；
2. 销售线索名单构建（Lead List Building）：为外呼销售活动生成精确的目标公司清单——先按"行业 + 规模 + 地区"锁定 Account，是典型 ABM（Account-Based Marketing）的起点；
3. 竞品情报（Competitive Intelligence）：用 q_organization_name、q_organization_keyword_tags 检索同赛道相似公司，研究其规模、融资/上市状态与公开资料。

更进一步，从同目录块的编排方式可以推断一个完整获客流：Search Organizations 输出 organization（逐条）→ 用其 name/domain/id 驱动 People 搜索块，找到该公司中的目标决策人 → 用 Person 块做联系人补全。三个文档模块正好对应"圈公司 → 找人 → 补全联系人"的销售漏斗自动化。使用该块时建议注意以下约束：

• 位置类筛选（包含与排除）均以总部为判定基准，存在多办公点或需按办公点筛选时需自行评估适用性；
• q_organization_name 部分匹配语义是"名称包含给定词元"，规划筛选词时不要假设任意子串都会命中；
• 为控制配额与执行成本，建议显式设置合理的 max_results 而非依赖默认 100 条上限；上限封顶 50000 条，超大抓取需评估耗时与分页带来的 API 调用量。

七、小结与延伸阅读

Search Organizations 块把 Apollo 的 B2B 公司数据库"搬"进了 AutoGPT Platform 的拖拽画布：通过 7 个筛选参数即可组合出规模、地区、行业、名称、ID 多维度查询，底层由 ApolloClient 自动完成分页拉取，并以"逐条 + 整表"双输出形态喂给下游逻辑。想深入验证，可直接阅读上述源码文件，或在画布中连接一个输出到日志节点的简单 Agent，先观察一次真实返回的对象结构。

更多相关文档：

• Apollo 联系人搜索（People Search）
• Apollo 联系人补全（Person Enrichment）
• 集成实现源码：autogpt_platform/backend/backend/blocks/apollo/