AutoGPT Platform Apollo People 模块实战：用 Search People 块精准挖掘 B2B 联系人线索

导读

本文围绕 Apollo People 模块文档 展开，深入讲解 AutoGPT Platform 内置的 Search People（搜索联系人）块：如何在 AutoGPT 可视化编排平台上，基于职位头衔、职级、地点、公司等条件检索 Apollo 的 B2B 联系人数据库。阅读完本文将掌握：Search People 块的完整输入参数语义与合法取值、enrich_info 邮件富化模式的底层实现与费用机制、平台内的计费规则，以及面向销售拓客、招聘、ABM（目标客户营销）等场景的实战配置配方。全文结合仓库源码与计费配置逐条印证，确保事实可追溯、参数可落地。

Search People 块定位：Apollo 集成族谱中的"线索入口"

在 AutoGPT Platform 的集成块生态中，Apollo 相关功能由一组协同块构成，均位于 backend/blocks/apollo/ 目录：

• Search People（搜索人）：按人维度多条件检索，是大部分销售线索流程的入口——本模块文档即 people.md 所讲述的核心；
• Search Organizations（搜索公司）：先按公司（组织）维度筛选目标企业，见 organization.md，对应实现 organization.py；
• Get Person Detail（获取人详情）：以 ID 或姓名/公司/域名/邮箱等字段做单人多维富化，见 person.md，对应实现 person.py。

Search People 块的类别为搜索类（BlockCategory.SEARCH），注册 ID 为 c2adb3aa-5aae-488d-8a6e-4eb8c23e2ed6，在源码 people.py 中定义。它面向"先定人、后触达"的使用方式：典型流程是先通过该块找到目标人群，再把结果传给 Get Person Detail 等下游块或销售自动化逻辑，用于销售与营销中的线索发现。

工作原理：一条请求如何变成联系人列表

Search People 块的执行链路清晰可循，核心实现在 people.py 与 _api.py：

1. 构造请求模型：块的 run 方法把界面输入（person_titles、person_seniorities、organization_locations 等全部过滤条件）序列化为 SearchPeopleRequest（数据模型定义见 models.py）；
2. 调用 Apollo HTTP API：ApolloClient.search_people() 向 https://api.apollo.io/api/v1/mixed_people/search 发起 POST 请求（见 _api.py），通过 x-api-key 请求头携带凭据；
3. 解析并处理分页：响应按 SearchPeopleResponse 解析（models.py）。客户端会自动翻页累积结果，直到达到 max_results 上限或翻完所有页（默认每页 100 条），最终返回不超过 max_results 条 Contact；
4. 统计上报：执行结束后通过 NodeExecutionStats 上报返回条数（provider_cost = len(people)，单位 items），作为后续计费的依据（people.py）。

从源码结构可以推断：块本身不直接调用第三方 SDK，而是经统一的 Requests 工具封装走 HTTP POST，并把 "max_results" 在发送前剔除、交由客户端自行分页控制——这是仓库为了统一控制结果数量上限所做的一层设计。

输入参数全解：语义、合法取值与组合技巧

Search People 块的全部筛选条件均为可选（只需配置 Apollo API Key 凭据），多条件之间按 Apollo 的规则叠加生效。下表完整列出 people.md 中的参数，并结合 models.py 中的源码补充默认值、约束与占位符信息：

输入参数	说明	类型	必填
person_titles	目标人群的职位头衔。命中规则为"或"：只要匹配你添加的任一头衔即纳入结果，添加越多越扩大搜索。同时返回包含相同关键词的非精确匹配职位（如搜 marketing manager 可能返回 content marketing manager）。建议与 person_seniorities 组合使用，实现"职能 × 职级"双维度定位	List[str]	否
person_locations	人所在的居住地，支持城市、美国州名与国家名。注意与组织所在地的区别（见下文）	List[str]	否
person_seniorities	人当前任职的汇报级别，仅支持下列枚举值：owner、founder、c_suite、partner、vp、head、director、manager、senior、entry、intern（枚举定义见 models.py，注意源码类名拼写为 SenorityLevels）。语义同样为"或"，但只按当前职位判断：某人曾是 Director、现为 VP，则不会出现在 Director 结果中	List[枚举值]	否
organization_locations	人当前雇主总部的所在地，支持城市、州、国家。Apollo 以公司总部为唯一判定基准：例如公司总部在波士顿，即使员工在芝加哥办公，搜 chicago 也不会命中该公司员工。想按个人所在地搜索请改用 person_locations	List[str]	否
q_organization_domains	雇主域名（当前雇主或历史雇主均可），不加 www.、@ 等符号，支持多个域名跨公司搜索，示例：apollo.io、microsoft.com	List[str]	否
contact_email_statuses	期望的邮箱状态，枚举值：verified（已验证）、unverified、likely_to_engage（高互动意愿）、unavailable（不可用），对应 models.py 中 ContactEmailStatuses。可加多个以扩大结果	List[枚举值]	否
organization_ids	雇主在 Apollo 数据库中的唯一 ID，可多个。获取方式：调用 Organization Search（搜索公司）端点并读取返回结果中的 organization_id 字段	List[str]	否
organization_num_employees_range	公司员工人数区间，用于按企业规模过滤。每个区间是一个字符串，上下界仅用逗号分隔（如 "100,500"），可加多个区间扩大结果	List[int]	否
q_keywords	用于过滤结果的自由关键词字符串	str	否
max_results	最大返回条数。块级默认值 25，上限 500（源码 people.py 约束 ge=1, le=500），上限用于防止超额调用造成失控花费	int	否
enrich_info	是否对联系人做详细富化（含真实邮箱地址），开启后搜索成本翻倍	bool	否

提示：SearchPeopleRequest 模型层默认的 max_results 为 100、per_page 为 100（见 models.py），而块界面层把 max_results 的默认收敛到 25、封顶 500。在 AutoGPT 画布上配置时，以块界面默认的 25 / 上限 500 为准，这是平台为"防止超额消费"（prevent overspending）特意收窄的护栏。

组合语义速查：哪些参数容易混淆

• 个人所在地 vs 组织所在地：person_locations 关注人住哪；organization_locations 关注其雇主总部在哪。前者用于"在旧金山找销售总监"（人在旧金山），后者用于"找总部在旧金山的公司里的销售总监"。
• 头衔 vs 职级：person_titles 决定"做什么"（职能关键词，非精确匹配），person_seniorities 决定"在哪一层"（枚举、仅看现任）。官方推荐二者组合以获得精准画像。
• 员工规模区间：尽管块界面类型是 List[int]，但语义上每个区间需以"下界,上界"逗号分隔的字符串形式表达，如 1,50 表示 1~50 人的公司。

输出结果与数据模型

块的输出定义见 people.md 及源码 people.py：

输出	说明	类型
people	找到的联系人列表	List[Dict[str, Any]]（内部实际为 Contact 结构）
error	搜索失败时的错误信息	str

每条 people 元素是对应 Apollo Contact 的字段映射（完整模型在 models.py），关键字段举例：name/first_name/last_name、title、headline、organization_name、organization_id、person_id、email、email_status、linkedin_url、photo_url、present_raw_address、city/state/country、phone_numbers、contact_emails、employment_history、extrapolated_email_confidence（外推邮箱置信度）、is_likely_to_engage（是否高互动意愿）、intent_strength 等，并包含与 Salesforce、HubSpot 等 CRM 的关联字段（salesforce_id、hubspot_vid 等）。未富化时部分字段（尤其 email）可能为空，这正是启用 enrich_info 的意义所在。

enrich_info 邮件富化：代码级的"补全而非覆盖"

这是 Search People 块最重要的进阶开关。people.md 说明：开启 enrich_info 可获取含已验证邮箱在内的详细联系方式，但会消耗更多积分。仓库源码把这一过程刻画得更完整：

• 开启后，块对每个命中的联系人调用 Apollo 的 /people/match 端点，并附加 reveal_personal_emails=true 参数以尽量揭示个人邮箱（见 _api.py）；
• 富化与搜索并发执行（asyncio.gather）；
• 每个联系人的富化结果通过 merge_contact_data() 合并回原数据，合并策略是只补缺不覆盖——仅当原值为空字符串、空列表或 None 时才用富化值填充（people.py）；
• 富化对个别联系人失败时优雅降级：该联系人保留原始搜索数据，不影响整体结果返回（people.py）。

因此在编排流程时，即使开启富化，也不必担心单个失败拖垮整条链路；若富化后仍拿不到邮箱，则继续将联系人交给 Get Person Detail 块做第二轮单点富化（该块亦调用 /people/match，见 person.py）。

凭据配置：Apollo API Key 如何接入

Search People 块需要绑定 Apollo 凭据，其字段类型是 ApolloCredentialsInput——一个固定 provider 为 apollo、类型为 api_key 的凭据输入（见 _auth.py）。也就是说，配置步骤非常轻：

1. 前往 Apollo 后台申请 API Key；
2. 在 AutoGPT Platform 的集成/凭据管理中添加 API Key 类型的凭据，provider 选择 Apollo；
3. 在画布中打开 Search People 块，将凭据绑定到 credentials 输入。

Apollo 的 provider 元数据在 _config.py 中注册，描述为 "Sales intelligence and prospecting"，支持认证类型 api_key。实际请求时，Key 通过 x-api-key 头传给 Apollo（_api.py），请求本身对 Key 做机密处理（源码中使用 SecretStr 承载）。

费用与积分机制：为什么文档强调"成本翻倍"

AutoGPT Platform 对 Apollo 块按返回记录条数计费，规则集中在 block_cost_config.py，与文档"成本翻倍"的表述一致：

• Search People（关闭富化）：cost_amount = 1，cost_type = ITEMS——每条返回的联系人计 1 积分；
• Search People（开启富化）：cost_amount = 2——因 Apollo 侧需要额外付费获取邮箱富化数据，每条计 2 积分，即文档所述的"搜索成本翻倍"；
• Search Organizations / Get Person Detail：分别按 1 积分/条（组织）与 1 积分/次计费。

这解释了设计上的两个护栏：max_results 块级上限 500 与默认 25，正是为了防止"开富化后全量拉取"造成积分与预算失控。在实战中建议先用小 max_results 试探结果质量，再放大批量抓取，并将 enrich_info 只作用于最终进入外呼/邮件序列的高意向线索。

典型应用场景与参数配方

文档明确给出了三类典型场景，下面结合参数语义给出可直接套用的配方（所有条件按需组合）：

1. Prospecting（外销拓客）——在目标公司里找决策人：

   • q_organization_domains = ["targetcompany.com"]；
   • person_titles = ["CEO", "VP Sales"] 或仅用 person_seniorities = ["c_suite", "vp", "director"]；
   • person_locations 限定主攻市场（国家/州/城市）；
   • contact_email_statuses = ["verified", "likely_to_engage"] 提升触达质量；
   • enrich_info = true 拉取真实邮箱，随后交给外呼/邮件环节。

2. Recruiting（招聘寻源）——按特定头衔与经验找人：

   • person_titles = ["Staff Engineer", "Principal Engineer"] 组合 person_seniorities = ["senior"]；
   • organization_ids 或 q_organization_domains 锁定竞对/目标公司，用于定向猎聘。

3. ABM Campaigns（目标客户营销）——围绕重点账户构建联系名单：

   • 用 organization_locations、organization_num_employees_range（如 "500,5000"）圈定企业画像；
   • 用 person_titles + person_seniorities 锁定采购关键角色；
   • 产出 people 列表导入营销自动化流程。

在 AutoGPT 画布中的完整编排示例

一个典型"公司 → 决策人 → 富化 → 输出"链路可这样搭建（均为现有块的组合，无须修改仓库代码）：

1. Search Organizations 块（见 organization.md）：按行业关键词、人员规模、总部所在地找出目标公司，输出 organization_ids；
2. Search People 块：将上一步的 organization_ids 接入 organization_ids 输入，配置目标职级与地区，max_results 设为 100，enrich_info 暂关以控制成本，先做初步圈定；
3. Get Person Detail 块（见 person.md）：对 2 中 email 为空的高意向联系人（可用 person_id 精确匹配）做二次富化补全邮箱；
4. 下游按需接入数据转换、存储或通知块，形成完整线索管线。

该链路中每个块的输入输出都以 Contact/Organization 结构化数据传递，方便被下游块直接消费。

本文依据的仓库资源

• 模块文档：docs/integrations/block-integrations/apollo/people.md（本文主骨架）、organization.md、person.md
• 块实现与输入输出 schema：autogpt_platform/backend/backend/blocks/apollo/people.py
• HTTP 客户端与分页/富化逻辑：autogpt_platform/backend/backend/blocks/apollo/_api.py
• 请求/响应数据模型与枚举（含拼写为 SenorityLevels 的职级枚举）：autogpt_platform/backend/backend/blocks/apollo/models.py
• 凭据接入与 Provider 注册：autogpt_platform/backend/backend/blocks/apollo/_auth.py、_config.py
• 计费配置（1/2 积分每条的规则出处）：autogpt_platform/backend/backend/data/block_cost_config.py