El Asistente para desarrolladores de la API de Google Ads incorpora una profunda experiencia en el dominio de la API de Google Ads directamente en tu entorno de codificación de IA. Usa mensajes 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 Google Antigravity y Claude Code (v4.0.0) como un complemento modular. Usa contratos 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:

   • Un token de desarrollador de la API de Google Ads.
   • Un archivo de configuración de Google Ads configurado con tu token de desarrollador, credenciales de OAuth 2.0 y el ID de cliente, ubicado en tu directorio principal (por ejemplo, google-ads.yaml para Python). Consulta la guía de configuración de la biblioteca cliente.
   • Familiaridad con los conceptos y la autenticación de la API de Google Ads

2. Software:

   • Python 3.10 o una versión posterior instalada y en la ruta de acceso del sistema. (Python se usa para ejecutar el código generado y los sidecars de validación local).
   • Agent Platform del host:
     • Herramienta de línea de comandos de Google Antigravity (agy), o
     • Herramienta de línea de comandos de Claude Code (claude con Node.js 18+).
   • Git instalado en la ruta de acceso del sistema

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).

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 coloque en tu directorio $HOME.

(Opcional) Para configurar un ID de cliente predeterminado, ingresa el 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 mensajes 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 o los recursos específicos. El Asistente basa las respuestas en las 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 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 probado con 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."
  • "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 GAQL: Ejecuta y valida automáticamente consultas complejas en comparación 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 objetos y esquemas de 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: "Inspeccionar recurso de campaña"

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

  • "Muéstrame 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.

  • Solo dile al Asistente: "Ejecutar el código" o "Ejecutar 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ísalas y ejecútalas de forma manual fuera del asistente.

• Diagnóstico avanzado y solución de problemas de conversiones: Investiga las fallas 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: "Solucionar problemas de conversiones para el cliente 123-456-7890" (Informes guardados en saved/data/).

• Asignación de jerarquía de cuentas de MCC: 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: "Obtener todos los IDs de cliente de cliente en el administrador 123-456-7890"

• Filtros y exclusiones de fichas de campaña de máximo rendimiento: Genera árboles de partición de productos y exclusiones de URL de páginas web para grupos de recursos.

  • Claude Code: /pmax-filter
  • Lenguaje natural: "Crear 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: bash ./update.sh agy --context_dir /path/to/your/codebase # Or for Claude Code: ./update.sh claude --context_dir /path/to/your/codebase
  • Windows (PowerShell): 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 mensajes en lenguaje natural o nombres de herramientas de habilidades como validate_gaql y inspect_object, como se describe en Características clave:

Mantenimiento y actualizaciones

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

Desinstalación

Para desinstalar el complemento del asistente, haz lo siguiente:

Comunidad y asistencia

• Problemas de GitHub: Informa errores, sugiere funciones o solicita ayuda en la pestaña Issues del repositorio.
• Discord: Únete a la conversación en el canal #ads-api-ai-tools del servidor de Discord de la comunidad de Google Advertising and Measurement.
• Comentarios: Comparte tus comentarios a través de este formulario de encuesta.

Lineamientos para las contribuciones

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