Google Ads API Developer Assistant v3.0.0 简介

2026 年 6 月 10 日，星期三

我们很高兴地宣布，Google Ads API 开发者助理 v3.0.0 现已发布。这一重大版本标志着 Google 助理发展历程中的一个重要里程碑，重点在于架构现代化、可靠性提升和更模块化的设计。

在此版本中，我们将把助理迁移到 Google Antigravity 智能体框架，并过渡到基于技能的架构。这些更改使 Google 助理更加强大、更易于维护，并减少了 token 使用量。

v3.0.0 有哪些新变化？

1. 由 Antigravity 框架提供支持

Google Ads API 开发者助理已从 gemini-cli 迁移到 Antigravity 智能体框架 (v3.0.0)。此次底层框架升级提供了更结构化、更可靠的执行环境。与此同时，项目的目录和文件结构也已更新，以便完全支持 Antigravity。

如这篇 Google 博客公告中所述，对 gemini-cli 的支持将于 2026 年 6 月 18 日终止。

2. 基于技能的模块化架构

我们已将 Google 助理的核心功能转换为技能。现在，助理不再依赖于上下文文件中宽泛、非结构化的指令，而是根据需要动态加载经过测试的专用工具目录（技能）。这可以显著减少“幻觉”，并确保按照精确、经过验证的程序执行任务。

此次模块化转型中的重要更新包括：

  • GAQL 验证 (validate_gaql)：已移至专用技能。现在，它包含针对日期细分、click_view 单日过滤条件和 change_status 边界的增强型静态查询检查。
  • 排查转化问题 (troubleshoot_conversions)：取代了旧版 conversions_support_package。它将所有转化问题排查和上传摘要脚本以及测试整合到一个统一的技能目录中。
  • 结构化命令（explain 和 step_by_step）：转换为技能，以强制执行一致、结构化的说明布局。
  • 新账号映射 (get_cids_under_mcc)：一项新技能，用于检索经理账号 (MCC) 下的所有子账号。
  • 新对象检查 (inspect_object)：一项新技能，可动态查找 Protobuf 消息和枚举，帮助确保 Google 助理始终使用正确的结构。
  • 新的效果最大化广告系列产品信息过滤条件 (pmax_listing_filter)：一项新技能，用于标准化效果最大化广告系列的产品信息组网页排除树修改。

3. 增强一致性和严谨性

我们引入了更严格的规则和要求，以帮助确保高质量的代码生成和查询验证：

  • 显式 API 版本控制：get_cids_under_mcc、validate_gaql 和 troubleshoot_conversions 等关键技能现在需要显式 api_version 实参，从而消除歧义。
  • 严格的 GAQL 规则：
    • 向 AGENTS.md 添加了一条规则，以防止在 GAQL 查询中使用 SQL 聚合函数（例如 SUM、COUNT 和 AVG），因为这些函数不受支持。
    • 添加了一条规则，要求首先查看 Google Ads API 开发者网站版本说明，了解当前 API 版本，以确保助理使用最新文档。
    • 配置简化：AGENTS.md 已经过简化，初始上下文窗口更小。重复的转换文档已被移除，取而代之的是程序化技能。

4. 开发者体验 (DX) 改进

我们对开发流程进行了多项改进，让您的开发过程更快速、更顺畅：

  • 永久性虚拟环境 (.venv)：虚拟环境在会话结束时不再删除。启动时，助理会检查系统的 Python 版本；只有在有更新的 Python 版本可用时，它才会重新构建 .venv。
  • 智能 API 版本缓存：助理现在会缓存当前的 Google Ads API 版本，TTL 为 19 小时，从而避免冗余网络检查，缩短启动时间。
  • 通过持久性日志更好地进行调试：日志消息现在包含日期时间戳。日志文件会写入 .agents/ 目录，并且每次运行时不再重置，从而保留历史记录以供排查问题。

为什么要升级？

升级到 v3.0.0 主要涉及可靠性和结构。通过改用 Antigravity 框架并将功能模块化为技能，我们让 Google 助理变得更可预测，资源效率也更高。

如果您希望获得更快的启动速度、更可靠的 GAQL 验证和更强大的问题排查体验，我们建议您升级到 v3.0.0。

开始

首次安装

  1. 安装 Antigravity CLI：按照 https://antigravity.google/ 上的说明操作。
  2. 克隆助理： 
    git clone https://github.com/googleads/google-ads-api-developer-assistant.git
  3. 运行安装脚本：
    • Linux/macOS：运行 ./install.sh（默认支持 Python，对于其他语言，请使用 --php 或 --ruby 等标志）。
    • Windows：打开 PowerShell 并运行 .\install.ps1。

从 v2.x 升级

  1. 将所有自定义代码或数据从 saved/ 复制到项目目录之外的安全位置。
  2. 删除 Google 助理的本地克隆。
  3. 克隆代码库：
git clone https://github.com/googleads/google-ads-api-developer-assistant.git
  1. 运行安装脚本（install.sh 或 install.ps1）以初始化新的 Antigravity 环境。

Bob Hancock，Google Ads API 团队

标签： google-ads-api、 release