AutoGPT 平台 Google Maps 搜索块（GoogleMapsSearchBlock）使用与实现详解

本指南以 AutoGPT 平台官方文档 Google Maps Search 为骨架，结合仓库内的块源码与测试逐层展开。你将完整掌握该块的输入输出契约、参数边界（半径上限 50,000 米、结果上限 60 条）、Google Places API 的底层调用链、凭据接入方式，以及如何把它编排进一个真实可运行的本地商户发现工作流。

一、这是什么块：一句话定位

Google Maps Search 是一个基于 Google Maps（Places）API 的本地商户/地点搜索块：给定搜索词（如 "restaurants in New York"）、搜索半径与 API 凭据，它会在指定地理范围内检索餐厅、商店、景点等 POI（Points of Interest），并把每家商户的名称、地址、电话、评分、评论数与官网链接整理成结构化数据输出。

在 AutoGPT 平台中，它归属 BlockCategory.SEARCH（搜索类块），是实现「把真实世界的线下商户数据带进 Agent 工作流」的最直接入口——从源码结构看，这也是块注册表中唯一的 Maps 类搜索块，块 ID 固定为 f47ac10b-58cc-4372-a567-0e02b2c3d479（见 google_maps.py）。

二、它做了什么：从文档功能描述说起

按官方文档，该块的功能是：使用 Google Maps 数据，在指定区域内搜索用户感兴趣的地点（餐厅、商店、景点等）。它承担了三件事：

1. 接收意图：读取搜索词（Query）、搜索半径（Radius）、返回条数上限（Max Results）；
2. 对接外部服务：携带 API Key 调用 Google Maps Places API 拉取候选地点；
3. 结构化输出：将 Google 返回的原始 JSON 规整为统一的 Place 记录（名称/地址/电话/评分/评论数/官网），供下游节点直接引用。

对应到源码，GoogleMapsSearchBlock.run() 只做了两件关键动作：把入参转发给 search_places() 完成 API 检索，再把每个结果逐条 yield 成 place 输出项（google_maps.py）：

async def run(self, input_data: Input, *, credentials: APIKeyCredentials, **kwargs):
    places = self.search_places(
        credentials.api_key,
        input_data.query,
        input_data.radius,
        input_data.max_results,
    )
    for place in places:
        yield "place", place

三、工作原理：一份简洁的调用链剖析

文档把块的工作机制概括为三步：接收输入 → 与 Google Maps API 通信获取相关地点 → 处理结果并作为结构化数据返回。结合源码，真实调用链比字面更具体（google_maps.py）：

run()
 └─ search_places(api_key, query, radius, max_results)
     ├─ googlemaps.Client(key=...)                     # 基于官方 googlemaps Python 客户端
     └─ _search_places(client, query, radius, max_results)
         ├─ client.places(query=..., radius=..., page_token=...)   # 第 1 步：关键词+半径搜索（返回摘要列表）
         ├─ client.place(place["place_id"])["result"]  # 第 2 步：逐条获取详情（补全电话/网站/评分）
         └─ 分页循环：读取 next_page_token 直到凑够 max_results 或没有下一页

两个值得注意的工程细节：

• 两段式抓取：client.places()（Text Search）先按关键词与半径给出候选，但列表项字段不全（缺少电话、网站等）；因此代码对每个 place_id 再调用 client.place()（Place Details）取回 formatted_phone_number、website、rating、user_ratings_total 等完整字段。这意味着一次块执行实际会消耗 1 次搜索请求 + N 次详情请求，属于 Google Maps 计费意义上的多次 API 调用。
• 分页拉取到上限为止：每次 places() 返回一页（默认约 20 条）并附带 next_page_token，循环会持续翻页直到累计结果达到 max_results，或响应中不再有下一页才停止（google_maps.py）。

四、输入参数详解（含默认值与边界）

文档给出的四路输入与源码中 SchemaField 声明的默认值、取值范围完全对应（google_maps.py）：

输入	类型	含义	源码中的边界与默认值
API Key	凭据（secret）	用于调用 Google Maps API 的密钥，属 google_maps 提供方、api_key 认证类型	须先在平台「凭据管理」中创建 Google Maps API Key
Query	string	本地商户搜索词，例如 "restaurants in New York"	必填，无默认值，字段占位符即 "e.g., 'restaurants in New York'"
Radius	int	搜索半径（米）	默认 5000，受 ge=1、le=50000 约束，最大 50,000 米（约 31 英里）
Max Results	int	最多返回多少个地点	默认 20，受 ge=1、le=60 约束，最大 60 条

以 pydantic ge/le 实现的范围校验意味着：一旦你在图形化界面里把 Radius 填到 50,001 或 Max Results 填到 61，平台会直接拒绝该输入——这一点对搭建可复用的 Agent 模板很重要，下游不应假设返回数量一定会等于 Max Results（实际可能因区域结果不足或配额而更少）。

五、输出结构：每个 Place 里到底有什么

文档将输出划分为 Place（地点信息）与 Error（错误消息）。Place 在源码中被建模为 pydantic BaseModel（google_maps.py），映射关系如下：

Place 字段	类型	含义	底层 Google 字段来源
Name	str	商户/地点名称	name
Address	str	完整地址	formatted_address
Phone	str	联系电话	formatted_phone_number
Rating	float	用户平均评分（满分 5）	rating（缺失时为 0）
Reviews	int	用户评论总数	user_ratings_total（缺失时为 0）
Website	str	官网地址（若有）	website（缺失时为空串）

一个有意思的实现细节是：代码使用了 place_details.get(field, 默认值) 而非直接下标访问，因此即使 Google 未返回电话或网站，输出仍是一条结构完整、字段为空的 Place，不会因字段缺失而中断整条流（google_maps.py）。

关于 Error 输出：官方文档明确说明错误分支用于描述「搜索过程中出现的任何问题」。需要注意的是，从 google_maps.py 的 Output schema 看，块本身只显式声明了 place 一个输出字段——当 API Key 无效、配额耗尽或网络异常时，底层 googlemaps 客户端抛出的异常会按平台执行引擎的统一异常/错误路径上报给工作流，这也是为什么在构建下游分支时建议把「失败/Error 通道」作为独立的异常出口来处理。

六、凭据接入：google_maps 提供方是怎么注册的

Google Maps 搜索块的凭据不是普通字符串输入，而是平台内的「受管凭据对象」。块声明处使用了 CredentialsMetaInput[Literal[ProviderName.GOOGLE_MAPS], Literal["api_key"]] 类型，并在 CredentialsField 中注明 "Google Maps API Key"。

• GOOGLE_MAPS = "google_maps" 定义于 providers.py 的 ProviderName 枚举；
• 由于该提供方尚无独立 _config.py，它的元数据由静态注册表 _static_provider_configs.py 提供："google_maps": ("Places, directions, geocoding", ("api_key",))，即显示名描述为「地点、路线、地理编码」，且只支持 api_key 一种认证方式；
• 该配置在块自动加载（blocks/__init__.py 的 rglob("*.py")）阶段由 ProviderBuilder(...).build() 写入 AutoRegistry，因此前端集成面板中能看到 "Google Maps" 提供方并要求用户填入 API Key。

实践上，你需要在 Google Cloud Console 中创建密钥并启用 Places API（Text Search + Place Details 能力），然后在 AutoGPT 平台的凭据管理中添加该 Key，随后在画布中把块的「API Key」输入接到这一凭据即可。

七、成本追踪机制（源码级佐证）

该块是平台成本统计体系的一个典型案例。在 run() 中，每完成一次检索就调用一次 merge_stats()：

self.merge_stats(NodeExecutionStats(
    provider_cost=float(len(places)), provider_cost_type="items"
))

含义是：provider_cost 直接等于本次返回的地点条数，成本计量单位为 items（按条计数，而非美元金额）。对应测试 block_cost_tracking_test.py 覆盖了两个断言方向：

1. mock 返回 4 个地点 → provider_cost == 4.0，provider_cost_type == "items"；
2. mock 返回空列表 → provider_cost == 0.0。

这为「Agent 跑一次会花多少条额度」提供了可预期的换算规则，也便于你在平台上对比不同块的成本计费口径差异。

八、典型使用场景与工作流编排

文档给出的使用场景是旅行规划：输入 "family-friendly restaurants in Paris" 之类的查询、以酒店为中心的搜索半径，快速得到候选餐厅的评分、联系方式和官网以便预订。

结合 AutoGPT 平台的块生态，一个可直接落地的画布编排建议如下：

1. 起点（触发）：用户消息块或定时块，携带目标城市/关键词；
2. Google Maps Search：Query = "{city} 的推荐景点/餐厅"（可由上一块的输出动态拼接），Radius 设为 5000（酒店周边 5 公里），Max Results 设为 10；
3. 下游处理：把每个 Place 接到文本块/邮件块生成推荐清单；Website 可再接网页抓取块获取菜单或营业时间；
4. 错误兜底：把异常出口接到通知块，提示「Google Maps 查询失败，请检查 API Key 或配额」。

需要注意数据流是逐条 yield：上游一次查询产出 N 个 place，下游若想「聚合为一份列表」需要借助平台的列表聚合/循环处理能力，而不是假设单次执行只产出一条结果。

九、注意事项与边界（建议收藏）

• Radius 上限 50,000 米（约 31 英里）、Max Results 上限 60 是代码级硬限制，超过会被输入校验拒绝；
• 结果条数是尽力而为：受 Google 返回总量与分页页数影响，实际输出可能少于 Max Results；
• API 依赖：块的可用性完全取决于 Google Maps Places API（Text Search + Place Details）；需要在 Google Cloud 启用对应 API，并对 API Key 使用有配额/费用预期；
• 电话与网站可为空：输出模型使用 .get(field, 默认值) 兜底，下游逻辑应容忍空字符串；
• 计费口径：块按「返回地点条数」上报成本（provider_cost_type="items"），用于平台内部额度统计，不等同于 Google 账单金额。

十、深入阅读

• 块官方文档：docs/integrations/block-integrations/google_maps.md
• 块实现源码（输入/输出 schema、Google 调用链、分页逻辑）：google_maps.py
• 提供方枚举定义：GOOGLE_MAPS = "google_maps" 见 providers.py
• 提供方静态注册（含支持认证类型 api_key）：_static_provider_configs.py
• 成本追踪测试：block_cost_tracking_test.py
• 平台内其他按条计费块的成本测试对比：同一测试文件中的 TTS、SmartLead 用例

若你希望将商户搜索结果与更多第三方能力（如邮件、表格、网页抓取、LLM 摘要）串联，建议先通读 Block SDK 指南 与集成功能总览，理解块输入/输出与凭据模型后再上手搭建复杂工作流。