Introduzione all'Assistente per sviluppatori dell'API Google Ads v3.0.0

Mercoledì 10 giugno 2026

Siamo lieti di annunciare il rilascio della versione 3.0.0 dell'assistente per sviluppatori dell'API Google Ads. Questa release principale segna un traguardo significativo nell'evoluzione dell'assistente, concentrandosi sulla modernizzazione dell'architettura, su una maggiore affidabilità e su un design più modulare.

Con questa release, stiamo eseguendo la migrazione dell'assistente al framework dell'agente Antigravity di Google e la transizione a un'architettura basata sulle skill. Queste modifiche rendono l'assistente più affidabile, più facile da gestire e riducono l'utilizzo dei token.

Novità della versione 3.0.0

1. Basato sul framework Antigravity

L'assistente per sviluppatori dell'API Google Ads è stato migrato da gemini-cli al framework dell'agente Antigravity (v3.0.0). Questo upgrade del framework di base fornisce un ambiente di esecuzione più strutturato e affidabile. Inoltre, la struttura delle directory e dei file del progetto è stata aggiornata per essere completamente compatibile con Antigravity.

Il supporto per gemini-cli terminerà il 18 giugno 2026, come descritto in questo annuncio sul blog di Google.

2. Un'architettura modulare basata sulle competenze

Abbiamo trasferito le funzionalità principali dell'assistente nelle Skill. Anziché fare affidamento su istruzioni ampie e non strutturate in un file di contesto, l'assistente ora carica dinamicamente directory di strumenti specializzati e testati (skill) quando necessario. In questo modo si riducono drasticamente le "allucinazioni" e si garantisce che le attività vengano eseguite utilizzando procedure precise e verificate.

Gli aggiornamenti principali di questa transizione modulare includono:

  • Convalida GAQL (validate_gaql): spostata in una skill dedicata. Ora include controlli statici avanzati delle query per i segmenti di date, i filtri di un solo giorno click_view e i limiti change_status.
  • Risolvi i problemi relativi alle conversioni (troubleshoot_conversions): sostituisce il precedente conversions_support_package. Consolida tutti gli script di riepilogo del caricamento e della risoluzione dei problemi di conversione, nonché i test, in un'unica directory di skill coesa.
  • Comandi strutturati (explain e step_by_step): convertiti in skill per applicare layout coerenti e strutturati per le spiegazioni.
  • Nuova mappatura degli account (get_cids_under_mcc): una nuova skill per recuperare tutti gli account bambino in un account amministratore (Centro clienti).
  • Nuova ispezione degli oggetti (inspect_object): una nuova skill per cercare dinamicamente i messaggi Protobuf e gli enum, per garantire che l'assistente utilizzi sempre le strutture corrette.
  • Nuovo filtro per le schede di Performance Max (pmax_listing_filter): una nuova skill per standardizzare le modifiche all'albero delle esclusioni delle pagine web dei gruppi di schede per le campagne Performance Max.

3. Maggiore coerenza e rigore

Abbiamo introdotto regole e requisiti più severi per garantire la generazione di codice di alta qualità e la convalida delle query:

  • Controllo delle versioni dell'API esplicito: le skill critiche come get_cids_under_mcc, validate_gaql e troubleshoot_conversions ora richiedono un argomento api_version esplicito, eliminando l'ambiguità.
  • Regole GAQL rigorose:
    • È stata aggiunta una regola a AGENTS.md per impedire l'utilizzo di funzioni di aggregazione SQL (come SUM, COUNT e AVG) nelle query GAQL, in quanto non sono supportate.
    • È stata aggiunta una regola per controllare prima le note di rilascio del sito per sviluppatori dell'API Google Ads per la versione corrente dell'API, in modo da garantire che l'assistente utilizzi la documentazione aggiornata.
    • Configurazione semplificata: AGENTS.md è stato semplificato, il che ha portato a una finestra di contesto iniziale più piccola. La documentazione sulle conversioni duplicate è stata rimossa a favore delle competenze di pubblicità programmatica.

4. Miglioramenti della Developer Experience (DX)

Abbiamo apportato diversi miglioramenti per rendere il ciclo di sviluppo più rapido e fluido:

  • Ambiente virtuale persistente (.venv): l'ambiente virtuale non viene più eliminato al termine di una sessione. All'avvio, l'assistente controlla la versione di Python del sistema e ricrea .venv solo se è disponibile una versione più recente di Python.
  • Memorizzazione nella cache intelligente della versione dell'API: l'assistente ora memorizza nella cache la versione corrente dell'API Google Ads con un TTL di 19 ore, riducendo il tempo di avvio ed evitando controlli di rete ridondanti.
  • Debug migliorato con log persistenti: i messaggi di log ora includono i timestamp di data e ora. Il file di log viene scritto nella directory .agents/ e non viene più reimpostato a ogni esecuzione, conservando la cronologia per la risoluzione dei problemi.

Perché dovresti eseguire l'upgrade?

L'upgrade alla versione 3.0.0 riguarda principalmente l'affidabilità e la struttura. Passando al framework Antigravity e modularizzando le funzionalità in Skill, abbiamo reso l'assistente più prevedibile ed efficiente dal punto di vista delle risorse.

Se vuoi un avvio più rapido, una convalida GAQL più affidabile e un'esperienza di risoluzione dei problemi più efficace, ti consigliamo di eseguire l'upgrade alla versione 3.0.0.

Inizia

Prima installazione

  1. Installa Antigravity CLI: segui le istruzioni riportate all'indirizzo https://antigravity.google/.
  2. Clona l'assistente: 
    git clone https://github.com/googleads/google-ads-api-developer-assistant.git
  3. Esegui lo script di installazione:
    • Linux/macOS: esegui ./install.sh (per impostazione predefinita, supporta Python; utilizza flag come --php o --ruby per altri linguaggi).
    • Windows: apri PowerShell ed esegui .\install.ps1.

Esegui l'upgrade dalla versione 2.x

  1. Copia qualsiasi codice o dato personalizzato da saved/ in una posizione sicura all'esterno della directory del progetto.
  2. Elimina il clone locale dell'assistente.
  3. Clona il repository:
git clone https://github.com/googleads/google-ads-api-developer-assistant.git
  1. Esegui lo script di installazione (install.sh o install.ps1) per inizializzare il nuovo ambiente Antigravity.

Bob Hancock, team API Google Ads

Etichette: google-ads-api, release