AIREITER编码智能体当然可以直接抓取 Google 开发者页面，但这意味着它还得自行处理页面结构、内容发现、去重和引用留存。Google Developer Knowledge API 将这些工作封装到了有明确文档的接口之后。对于需要将最新 Google 文档作为可审计上下文的智能体，它通常是更合适的默认选择。不过要注意：它覆盖的是经过整理的语料库，并不是整个 Google 开发者网站。
它负责检索，不负责执行操作
Google Developer Knowledge API 将 Google 的公开开发者文档以机器可读的形式提供出来。Google 在其 REST 参考文档中说明了文档搜索、完整文档获取、批量获取和带依据回答等能力。
这项服务为应用或智能体提供只读上下文。它不会授予私有 Cloud 项目访问权限，不能批准 IAM 变更、部署代码，也不会验证生成的命令是否安全。凡是写入操作，智能体仍然需要单独的凭据和策略关卡。
语料范围同样关键。Google 的 API 文档明确说明，其覆盖的是公开开发者文档，而不是整个互联网。它不能替代对任意 GitHub 仓库、Stack Overflow、私有运行手册或第三方库的搜索。Google 还指出，返回的 Markdown 由源 HTML 转换生成，因此不应把它视为渲染页面逐字节完全一致的副本。
最新的可用性和行为，请以官方 API 参考文档及发布说明为准。
Google Developer Knowledge API 能提供什么
REST 接口很精简，足以直接纳入智能体策略：
| 操作 | 返回内容 | 适用场景 |
|---|---|---|
SearchDocumentChunks | 匹配的文档片段及其父文档资源 | 查找证据和候选页面 |
GetDocument | 一篇完整的 Markdown 文档 | 为智能体补充页面上下文 |
BatchGetDocuments | 多篇完整文档 | 对比相关页面，或预热本地缓存 |
AnswerQuery | 附带支持性引用、基于语料的回答 | 回答范围明确的文档问题 |
搜索结果是片段，并不保证返回完整页面。结果中的 parent 资源可用于衔接 GetDocument 或 BatchGetDocuments。稳健的客户端应先按父文档对重复片段分组，再拉取页面；否则，同一页面可能占用多个检索名额，却没有带来多少额外上下文。
典型的资源名称遵循文档资源格式：
documents/docs.cloud.google.com/storage/docs/creating-buckets在处理搜索响应时，这种资源名格式很有用；但智能体应优先采用服务实际返回的 parent，而不是凭记忆自行拼接资源名称。
不同搜索模式，对应不同的证据要求
SearchDocumentChunks 是证据优先的模式。当智能体需要精确的标志位、参数、权限、版本说明或代码片段时，应使用它。调用方可以检查片段内容，保留其文档 URI，并自行决定是否继续获取完整页面。
GetDocument 和 BatchGetDocuments 属于上下文模式。搜索之后，如果答案取决于前置条件、警告信息、迁移说明，或单个片段未涵盖的相邻章节，就应使用它们。一个设计问题涉及多篇官方页面时，批量获取尤其有用。
AnswerQuery 则是综合回答模式。它适合处理范围明确的问题，例如“当前哪种 Google Cloud 方案符合这些约束条件？”，并要求答案基于语料库生成。但这不意味着可以不检查引用就接受一段流畅的回答。对于高风险代码改动，搜索加完整文档获取能为智能体留下更易审查的证据链。
认证方式要匹配调用方
实际可选的认证模式有三种，但它们分别适用于不同的调用方。
| 调用方 | 推荐起点 | 原因 |
|---|---|---|
| 本地 curl 或快速原型 | 受限 API 密钥 | 最快发出首个请求的方式 |
| 后端、Worker 或 Python 客户端 | Application Default Credentials (ADC) | 让凭据留在运行环境中，而不是写进源代码 |
| 交互式 MCP 客户端 | 主机支持时使用 OAuth；否则使用受限密钥 | 避免在用户工具间分发同一把长期密钥 |
快速上手时，先创建或选择一个 Google Cloud 项目，启用 developerknowledge.googleapis.com，然后创建一把仅限 Developer Knowledge API 使用的 API 密钥。不要把不受限制的密钥放进智能体提示词、代码仓库、客户端打包产物或调试日志。
启用服务的最小命令如下：
gcloud services enable developerknowledge.googleapis.com \
--project="$PROJECT_ID"对于托管应用，ADC 通常是更清晰的边界。Google 的 Python 客户端参考文档说明了如何发现环境中的凭据，以及如何使用同步和异步客户端。这样，身份由部署运行环境提供，应用本身无需从配置文本中解析密钥。
对于交互式智能体，OAuth 也很合适，因为授权连接的是用户，而不是一项共享的静态密钥。具体 OAuth 流程取决于 MCP 主机。客户端是否支持认证，需要与 API 本身的能力分开核实；一个能接收 MCP URL 的客户端，在请求头、密钥变量或令牌刷新方面未必采用相同的处理方式。
一套最小化检索流程
生产环境中的智能体应明确划分检索边界：
- 从问题中移除密钥和无关的仓库内容。
- 通过
SearchDocumentChunks搜索官方语料库。 - 按父文档资源对结果去重。
- 任务需要周边上下文时，获取最相关的完整文档。
- 保留返回的 URI、标题、时间戳或元数据，以及选用的摘录。
- 要求模型只能根据保留的证据作答。
- 智能体改动代码或基础设施前，运行测试和策略检查。
搜索 REST 端点见 Google 的 REST 参考文档：
GET https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks使用 API 密钥的简单请求示例如下：
curl --get \
'https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks' \
--data-urlencode 'query=Cloud Storage bucket retention policy' \
--data-urlencode 'pageSize=5' \
--data-urlencode "key=$DEVELOPERKNOWLEDGE_API_KEY"在硬编码解析器之前，应先对照最新的 REST 参考文档确认具体响应结构和字段名称。搜索会返回片段和父文档名称，而文档获取则使用这些名称。
应使用模拟或快照响应测试智能体对空结果、缺失 parent、分页、认证失败，以及配额或限流响应的处理。重试逻辑要放在模型提示词之外，采用有上限的退避策略，并在无法检索证据时提供清晰的降级方案。
该选直连 API、MCP，还是网页？
同一份文档来源可以通过三种方式使用：
| 场景 | 最佳路径 | 原因 |
|---|---|---|
| 服务需要可重复的检索和引用 | REST API 或客户端库 | 应用可以掌控解析、缓存和证据存储 |
| 编码助手需要按需获取 Google 上下文 | Developer Knowledge MCP server | 智能体无需自定义胶水代码即可调用搜索和检索工具 |
| 页面不在支持的语料库内 | 直接访问页面或使用独立来源连接器 | Developer Knowledge 语料库无法回答缺失来源中的内容 |
| 人工检查布局、导航或交互示例 | 浏览器/页面访问 | Markdown 检索不等于查看视觉页面 |
Google 的 MCP 文档将端点列为 https://developerknowledge.googleapis.com/mcp。MCP 是供智能体使用的适配层，不是另一套知识库。一个典型的远程服务器配置如下：
{
"mcpServers": {
"google-developer-knowledge": {
"serverUrl": "https://developerknowledge.googleapis.com/mcp",
"headers": {"x-goog-api-key": "${DEVELOPERKNOWLEDGE_API_KEY}"}
}
}
}请使用主机文档规定的密钥变量语法；不要假设字面量 ${...} 在所有环境中都能展开。上下文成本同样值得考虑：向每个任务暴露全部工具，会增加工具定义和决策开销。一位用户在讨论多服务器智能体配置时，准确表达了这一顾虑：
“与 skills 相比，MCP 非常消耗上下文——skills 在被调用前只占用几行文本。” — u/junlim，Reddit 讨论
这意味着应针对 Google 相关任务按需启用 Developer Knowledge MCP server，而不是彻底放弃它。处理 Firebase、Android、Google Cloud、Maps 或 Flutter 的智能体可以从该来源获益；编辑无关技术栈的智能体，则不应默认调用它。
哪些情况下 API 胜过抓取 Google 开发者文档
当以下大多数条件成立时，应该使用 API：
- 任务面向 Google 自有的开发者文档。
- 智能体需要可重复的搜索，而不是一次性抓取某个页面。
- 答案需要引用，或需要保留来源轨迹。
- 智能体必须区分相关片段和完整文档。
- 工作流需要结构化分页、批量操作或缓存。
- 页面改版后不应导致 HTML 解析器必须重写。
抓取仍然可能是正确的后备方案。当所需页面不在支持的语料库中、任务包含视觉交互，或必须关注精确渲染的 HTML 与导航状态时，就应使用抓取。在 API 不可用的故障处理期间，抓取也可以作为合理的临时探测手段，但不应在无声无息中演变成生产环境的检索契约。
| 决策因素 | Developer Knowledge API | 抓取开发者页面 |
|---|---|---|
| 内容发现 | 在其已索引语料库中由服务搜索 | 自行构建搜索，或从已知 URL 开始 |
| 输出 | 片段、文档资源和 Markdown | HTML 或渲染后的页面内容 |
| 引用流程 | 父资源和文档 URI 明确提供 | 应用必须自行提取和保存链接 |
| 布局维护 | 以 API 契约为边界 | 改版后选择器可能失效 |
| 覆盖范围 | 受支持的公开开发者语料库 | 任何可公开访问的页面，但受访问规则和 robots 规则限制 |
| 视觉保真度 | 并非目标 | 使用浏览器自动化时可保留渲染布局 |
| 智能体控制流 | 先搜索、再获取、后综合 | 通常是获取、解析、清理和推断 |
API 不保证每篇新发布页面都会立即可用。Google 的发布说明描述了索引更新，但智能体应将新鲜度视作需要核验的属性，而不能把它当成最新页面已被索引的证明。对于发布日迁移，应将返回的元数据与当前官方页面进行对比；证据缺失时应采取保守的拒绝策略。
我会部署的智能体策略
对于面向 Google 的编码智能体，我会采用以下路由规则：
- 精确实现细节：先调用
SearchDocumentChunks；如果片段缺少前置条件，再获取父文档。 - 跨页面设计问题：先搜索，再针对少量相关父文档调用
BatchGetDocuments。 - 简单解释性问题：使用
AnswerQuery，但要求响应中必须包含引用。 - 非 Google 或私有文档：路由到其他经过批准的连接器。
- 代码或基础设施写入：检索仅供参考；测试、IAM、审查和部署控制仍是强制要求。
在策略允许的范围内缓存完整文档，对重复搜索进行防抖，并记录来源 URI，而不是记录原始密钥或不必要的仓库上下文。要将获取到的 Markdown 视为不可信输入：来源具备权威性，不代表其中嵌入的每条指令都能安全地交给拥有写入工具的智能体执行。
尚未消失的取舍其实很直接：相较 HTML 抓取，API 为智能体提供了更干净、也更易审计的契约；代价是放弃浏览器所具备的覆盖范围和即时页面保真度。对于受支持的 Google 文档，应默认选择 API；然后将抓取或其他连接器保留为明确的后备路径，而非在后台混用两种方式。
Google Developer Knowledge API 常见问题
Developer Knowledge API 等同于 Google Search 吗？
不等同。它是在受支持 Google 开发者语料库上运行的文档检索服务，而不是通用 Web 搜索 API。它不会自动搜索私有文档、任意 GitHub 内容或所有与 Google 有关的页面。
我该使用 AnswerQuery 还是 SearchDocumentChunks？
如果需要范围明确、基于语料的解释，可使用 AnswerQuery。如果智能体需要可检查的证据、精确语法或来源链，应使用 SearchDocumentChunks；片段不足时，再获取父文档。
必须使用 API 密钥吗？
受限 API 密钥是最快的原型路径。后端客户端可以使用 ADC；交互式 MCP 集成则可在主机支持时使用 OAuth。不要认为某个客户端支持的认证方式，会自动得到其他客户端的支持。
智能体能否借助 API 部署 Google Cloud 资源？
不能。该 API 只提供文档上下文。部署仍需独立的工具、凭据、IAM 权限、审批和验证。
什么时候应该改用抓取？
当页面不在 API 语料库内、视觉布局很重要，或需要的页面尚未出现在索引中时，可使用抓取或浏览器连接器。应明确记录这一后备路径，避免智能体将抓取内容表述成由 API 支持的引用。
搜索会返回完整页面吗？
不会。搜索返回的是文档片段。当需要完整 Markdown 页面时，应将返回的父文档资源传给 GetDocument 或 BatchGetDocuments。