Instala y usa el Asistente para desarrolladores de la API de Google Ads

El Asistente para desarrolladores de la API de Google Ads aporta una profunda experiencia en el dominio de la API de Google Ads directamente a tu entorno de programación de IA. Usa instrucciones en lenguaje natural y comandos de barra integrados para crear consultas, generar código de bibliotecas cliente, ejecutar llamadas a la API de solo lectura, transmitir informes ad hoc y solucionar problemas de integraciones.

El asistente se creó para los frameworks de agentes Google Antigravity y Claude Code (v4.0.0) como un complemento modular. Utiliza contratos de AGENTS.md y CLAUDE.md, comandos de barra integrados y habilidades de dominio especializadas para mantener un contexto persistente, límites de seguridad sólidos y canalizaciones de validación automatizadas.

Requisitos previos

Antes de comenzar, asegúrate de tener lo siguiente:

  1. Acceso a la API de Google Ads:

  2. Software:

Comenzar

Sigue estos pasos para clonar el repositorio, ejecutar la secuencia de comandos de instalación específica de la plataforma, configurar tus credenciales y activar el complemento.

1. Clona el repositorio

Clona el repositorio en tu máquina local y navega al directorio del proyecto:

git clone https://github.com/googleads/google-ads-api-developer-assistant
cd google-ads-api-developer-assistant

2. Ejecuta la secuencia de comandos de instalación

Ejecuta la secuencia de comandos de instalación para tu plataforma de destino. De forma predeterminada, se incluye la biblioteca cliente de Python. De manera opcional, puedes incluir bibliotecas cliente adicionales (--php, --ruby, --java, --dotnet o --all).

Antigravity

Linux / macOS:

./install.sh agy
# Or include additional client libraries:
./install.sh agy --java --dotnet

Windows (PowerShell):

.\install.ps1 -Type agy
# Or include additional client libraries:
.\install.ps1 -Type agy -Java -Dotnet

Claude Code

Linux / macOS:

./install.sh claude
# Or include additional client libraries:
./install.sh claude --php --dotnet

Windows (PowerShell):

.\install.ps1 -Type claude
# Or include additional client libraries:
.\install.ps1 -Type claude -Php -Dotnet

3. Configura las credenciales

Asegúrate de que el archivo de configuración de la API (por ejemplo, google-ads.yaml, google_ads_php.ini o google_ads_config.rb) se encuentre en el directorio $HOME.

(Opcional) Para configurar un ID de cliente predeterminado, ingresa tu número de ID de cliente directamente en config/customer_id.txt (por ejemplo, 1234567890). También puedes inspeccionar o fijar tu versión de API activa en config/api_version.txt.

4. Activa el complemento

  • Antigravity: Reinicia tu sesión de host de Antigravity o agy para cargar el complemento.
  • Claude Code: En una sesión activa de Claude Code, ejecuta /reload-plugins o reinicia claude.

5. Interactúa con el Asistente

Puedes interactuar con el Asistente usando instrucciones en lenguaje natural o comandos de barra dedicados directamente en la terminal.

Características clave

  • Preguntas y respuestas en lenguaje natural y orientación conceptual: Haz preguntas sobre las funciones de la API de Google Ads, las reglas de arquitectura, las prácticas recomendadas o los recursos específicos. El Asistente fundamenta las respuestas en las definiciones oficiales de la API, en lugar de depender únicamente del entrenamiento general del LLM.

    • "¿Qué tipos de campañas están disponibles?"
    • "¿Cómo filtro por fecha en GAQL?"
    • "Explica la diferencia entre click_view y impression_view".
    • "¿Qué es un conjunto compartido y cómo lo uso?"
    • Comandos de barra de Claude Code: /explain, /step-by-step, /assistant-tutorial

  • Generación de código de biblioteca cliente fundamentado: Genera código idiomático y probado con las bibliotecas cliente oficiales de Google Ads (Python, Java, PHP, .NET y Ruby).

    • "Muéstrame las campañas con la mayor cantidad de conversiones en los últimos 30 días".
    • "Obtén todos los nombres de los grupos de anuncios habilitados para el cliente 123-456-7890".
    • "Escribe código para crear una campaña de máximo rendimiento". El código generado se guarda en el directorio saved/code/.

  • Validación programática de consultas de GAQL: Ejecuta y valida automáticamente consultas complejas en relación con los metadatos de la API, la compatibilidad de los campos, las reglas de cero impresiones y la segmentación por fecha antes de la ejecución.

    • Claude Code: /validate-gaql
    • Lenguaje natural: validate: SELECT campaign.id FROM campaign

  • Inspección de esquemas de objetos y Protobuf: Inspecciona de forma dinámica las estructuras de recursos, los campos anidados, los tipos de datos y los valores de enumeración para cualquier versión de API activa sin la sobrecarga de metadatos remotos.

    • Claude Code: /inspect-object <resource_or_enum>
    • Lenguaje natural: "Inspeccionar el recurso de la campaña"

  • Informes en vivo ad hoc y exportación a CSV: Solicita datos de rendimiento en inglés simple. El asistente crea, valida y ejecuta consultas de GAQL directamente en tu cuenta, y transmite tablas con formato en vivo a la terminal.

    • "Muestra las 5 palabras clave principales por costo del mes pasado para el cliente 123-456-7890".
    • "Guarda los resultados como un archivo CSV". (Se exporta a saved/csv/).

  • Ejecución directa de la API y seguridad de mutación: Ejecuta secuencias de comandos de solo lectura generadas directamente en un entorno virtual administrado.

    • Dile al Asistente: "Ejecuta el código" o "Ejecuta el script".
    • Mutate Safety: Por seguridad, las operaciones de mutación (crear, actualizar, borrar) se generan para saved/code/, pero el asistente nunca las ejecuta directamente. Revisarlas y ejecutarlas manualmente fuera del asistente

  • Diagnóstico avanzado y solución de problemas relacionados con las conversiones: Investiga las fallas en la carga de conversiones sin conexión, valida previamente los archivos de carga y genera informes de diagnóstico detallados.

    • Claude Code: /troubleshoot-conversions
    • Lenguaje natural: "Soluciona problemas relacionados con las conversiones del cliente 123-456-7890". (Los informes se guardan en saved/data/).

  • Asignación de la jerarquía de la cuenta de MCC: Recupera los IDs de cliente de las cuentas secundarias y asigna las jerarquías de cuentas en una cuenta de administrador.

    • Claude Code: /get-cids <manager_cid>
    • Lenguaje natural: "Obtén todos los IDs de cliente de la cuenta de administrador 123-456-7890"

  • Filtros y exclusiones de fichas de las campañas de máximo rendimiento: Genera árboles de particiones de productos y exclusiones de URLs de páginas web para los grupos de recursos.

    • Claude Code: /pmax-filter
    • Lenguaje natural: "Crea filtros de exclusión de páginas web para mi campaña de máximo rendimiento"

  • Contexto adicional de la base de código: Registra la lógica de tu aplicación y la arquitectura personalizada en el razonamiento del Asistente.

    • Linux / macOS:

      ./update.sh agy --context_dir /path/to/your/codebase
# Or for Claude Code:
./update.sh claude --context_dir /path/to/your/codebase

    • Windows (PowerShell):

      .\update.ps1 -Type agy -ContextDir C:\path\to\your\codebase

Referencia de los comandos de barra de Claude Code

Cuando usas Claude Code, están disponibles los siguientes comandos de barra integrados. En Google Antigravity, invoca estas mismas capacidades con instrucciones en lenguaje natural o nombres de herramientas de habilidades, como validate_gaql y inspect_object, como se describe en Funciones clave:

Comando de barra Objetivo Ejemplo
/validate-gaql Valida la sintaxis, la compatibilidad y las reglas de GAQL. /validate-gaql
/inspect-object Inspecciona los campos, los tipos y las enumeraciones de Protobuf. /inspect-object Campaign
/get-cids Resuelve las jerarquías de MCC y los CIDs de clientes. /get-cids 1234567890
/troubleshoot-conversions Ejecuta diagnósticos de carga de conversiones sin conexión. /troubleshoot-conversions
/pmax-filter Genera filtros y exclusiones de fichas de las campañas de máximo rendimiento. /pmax-filter
/explain Proporciona una explicación estructurada en 4 partes. /explain shared set
/step-by-step Formula un plan de ejecución de tareas de varias fases. /step-by-step upload conversions
/assistant-tutorial Ejecuta una guía interactiva de 11 pasos. /assistant-tutorial

Mantenimiento y actualizaciones

Para actualizar el repositorio, la instalación de complementos y las bibliotecas cliente, haz lo siguiente:

Antigravity

Linux / macOS:

./update.sh agy          # Update Antigravity plugin
./update.sh agy --all    # Include all client libraries

Windows (PowerShell):

.\update.ps1 -Type agy
.\update.ps1 -Type agy -All

Claude Code

Linux / macOS:

./update.sh claude       # Update Claude Code plugin
./update.sh claude --all # Include all client libraries

Windows (PowerShell):

.\update.ps1 -Type claude
.\update.ps1 -Type claude -All

Desinstalación

Para desinstalar el complemento del asistente, haz lo siguiente:

Antigravity

Linux / macOS:

rm -rf ~/.gemini/config/plugins/google-ads-api-developer-assistant

Windows (PowerShell):

Remove-Item -Recurse -Force `
  "$HOME\.gemini\config\plugins\google-ads-api-developer-assistant"

Luego, reinicia la sesión de host de Antigravity.

Claude Code

En una sesión activa de Claude Code, haz lo siguiente:

/plugin uninstall google-ads-api-developer-assistant@google-ads-assistant-local

O desde la terminal:

claude plugin uninstall \
  google-ads-api-developer-assistant@google-ads-assistant-local

(Opcional) Quita el registro del mercado local:

claude plugin marketplace remove google-ads-assistant-local

Comunidad y asistencia

Lineamientos de contribución

Agradecemos tus contribuciones. Consulta el archivo CONTRIBUTING.md en el repositorio de GitHub para obtener instrucciones.

Anterior
¿Qué es el Asistente para desarrolladores de la API de Google Ads?