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 amplia 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 biblioteca 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 de Google Antigravity y Claude Code (v4.0.0) como un complemento modular. Usa 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. Consulta ¿Qué es el Asistente para desarrolladores de la API de Google Ads? para obtener una descripción general de su arquitectura y diseño.

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 activa de la API 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 tu 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 definiciones oficiales de la API, en lugar de depender únicamente del entrenamiento general del LLM.

    • "¿Cuáles son los tipos de campaña disponibles?"
    • "¿Cómo filtro por fecha en GAQL?"
    • "Explica la diferencia entre click_view e 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 fundamentada: Genera código idiomático probado con las bibliotecas cliente oficiales de Google Ads (Python, Java, PHP, .NET y Ruby).

    • "Muéstrame las campañas con más conversiones en los últimos 30 días".
    • "Get all enabled ad group names for customer 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 de forma automática una prueba de validación de consultas complejas con los metadatos de la API, la compatibilidad de 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 activa de la API sin sobrecarga de metadatos remotos.

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

  • Informes en vivo ad hoc y exportación a CSV: Solicita datos de rendimiento en lenguaje natural. El asistente construye, 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 con el costo más alto 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 la secuencia de comandos".
    • Seguridad de mutación: Por seguridad, las operaciones de mutación (crear, actualizar, borrar) se generan en saved/code/, pero el asistente nunca las ejecuta directamente. Revísalos y ejecútalos de forma manual fuera del asistente.

  • Diagnóstico avanzado y solución de problemas de conversiones: Investiga los errores de 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 de conversiones para el cliente 123-456-7890". (Los informes se guardan en saved/data/).

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

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

  • Filtros y exclusiones de fichas de campañas de máximo rendimiento: Genera árboles de partición 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áx. rendimiento"

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

    • 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 las cuentas de administrador y los CID de los 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 campañas de máximo rendimiento. /pmax-filter
/explain Ofrece 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 explicación interactiva de 11 pasos. /assistant-tutorial

Mantenimiento y actualizaciones

Para actualizar el repositorio, la instalación del complemento 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 de 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 tu 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 de Marketplace local:

claude plugin marketplace remove google-ads-assistant-local

Comunidad y asistencia

Lineamientos para las contribuciones

¡Agradecemos tus contribuciones! Consulta el archivo CONTRIBUTING.md en el repositorio de GitHub para obtener lineamientos.

Próximos pasos

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