O Assistente para desenvolvedores da API Google Ads traz a experiência do domínio da API Google Ads diretamente para o ambiente de codificação de IA. Use comandos de linguagem natural e comandos de barra integrados para criar consultas, gerar código de biblioteca de cliente, executar chamadas de API somente leitura, transmitir relatórios ad hoc e resolver problemas de integrações.

O Assistente foi criado para as estruturas de agente Google Antigravity e Claude Code (v4.0.0) como um plug-in modular. Ele usa contratos AGENTS.md e CLAUDE.md, comandos de barra integrados e habilidades de domínio especializadas para manter o contexto persistente, limites de segurança robustos e pipelines de validação automatizados.

Pré-requisitos

Antes de começar, certifique-se de ter:

1. Acesso à API Google Ads :

   • Um token de desenvolvedor da API Google Ads.
   • Um arquivo de configuração do Google Ads configurado com seu token de desenvolvedor, credenciais do OAuth 2.0 e ID do cliente, localizado no seu diretório inicial (por exemplo, google-ads.yaml para Python). Consulte o guia de configuração da biblioteca de cliente.
   • Familiaridade com os conceitos e a autenticação da API Google Ads.

2. Software :

   • Python 3.10 ou mais recente instalado e no PATH do sistema. O Python é usado para executar o código gerado e executar sidecars de validação local.
   • Plataforma de agente de host:
     • Ferramenta de linha de comando do Google Antigravity (agy) ou
     • Ferramenta de linha de comando do Claude Code (claude com Node.js 18 ou mais recente).
   • Git instalado no PATH do sistema.

Primeiros passos

Siga estas etapas para clonar o repositório, executar o script de instalação específico da plataforma, configurar suas credenciais e ativar o plug-in.

1. Clonar o repositório

Clone o repositório na sua máquina local e navegue até o diretório do projeto:

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

2. Executar o script de instalação

Execute o script de instalação da plataforma segmentada. Por padrão, a biblioteca de cliente do Python está incluída. Opcionalmente, você pode incluir outras bibliotecas de cliente (--php, --ruby, --java, --dotnet ou --all).

3. Configurar credenciais

Verifique se o arquivo de configuração da API (por exemplo, google-ads.yaml, google_ads_php.ini ou google_ads_config.rb) está no diretório $HOME.

(Opcional) Para configurar um ID do cliente padrão, insira o número do ID do cliente diretamente em config/customer_id.txt (por exemplo, 1234567890). Você também pode inspecionar ou fixar a versão ativa da API em config/api_version.txt.

4. Ativar o plug-in

• Antigravity:reinicie a sessão do host do Antigravity / agy para carregar o plug-in.
• Claude Code:em uma sessão ativa do Claude Code, execute /reload-plugins ou reinicie claude.

5. Interagir com o Assistente

Você pode interagir com o Assistente usando comandos de linguagem natural ou comandos de barra dedicados diretamente no terminal.

Principais recursos

• Perguntas e respostas em linguagem natural e orientação conceitual: faça perguntas sobre os recursos da API Google Ads, regras arquitetônicas ou recursos específicos. O Assistente fundamenta as respostas em definições oficiais da API, em vez de se basear apenas no treinamento geral do LLM.

  • "Quais são os tipos de campanha disponíveis?"
  • "Como faço para filtrar por data no GAQL?"
  • "Explique a diferença entre click_view e impression_view."
  • "O que é um conjunto compartilhado e como faço para usá-lo?"
  • Comandos de barra do Claude Code: /explain, /step-by-step, /assistant-tutorial

• Geração de código de biblioteca de cliente fundamentada:gere código testado e idiomático usando as bibliotecas de cliente oficiais do Google Ads (Python, Java, PHP, .NET e Ruby).

  • "Mostre as campanhas com mais conversões nos últimos 30 dias."
  • "Receba todos os nomes de grupos de anúncios ativados para o cliente 123-456-7890."
  • "Escreva um código para criar uma campanha Performance Max." O código gerado é salvo no diretório saved/code/.

• Validação programática de consultas GAQL:execute e valide automaticamente consultas complexas em relação a metadados da API, compatibilidade de campos, regras de impressão zero e segmentação por data antes da execução.

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

• Inspeção de esquema de objeto e Protobuf:inspecione dinamicamente estruturas de recursos, campos aninhados, tipos de dados e valores de enumeração para qualquer versão ativa da API sem sobrecarga de metadados remotos.

  • Claude Code: /inspect-object <resource_or_enum>
  • Linguagem natural: "Inspecionar recurso de campanha"

• Relatórios ad hoc em tempo real e exportação de CSV:peça dados de performance em inglês simples. O Assistente cria, valida e executa consultas GAQL diretamente na sua conta, transmitindo tabelas formatadas em tempo real para o terminal.

  • "Mostre as cinco principais palavras-chave por custo no mês passado para o cliente 123-456-7890."
  • "Salve os resultados como um arquivo CSV." (Exporta para saved/csv/).

• Execução direta da API e segurança de mutação:execute scripts somente leitura gerados diretamente em um ambiente virtual gerenciado.

  • Basta dizer ao Assistente: "Execute o código" ou "Execute o script".
  • Segurança de mutação:para segurança, as operações de mutação (criar, atualizar, excluir) são geradas para saved/code/, mas nunca são executadas diretamente pelo assistente. Revise e execute-as manualmente fora do assistente.

• Diagnóstico avançado e solução de problemas de conversão:investigue falhas de upload de conversão off-line, pré-valide arquivos de upload e gere relatórios de diagnóstico detalhados.

  • Claude Code: /troubleshoot-conversions
  • Linguagem natural: "Resolver problemas de conversões para o cliente 123-456-7890." (Relatórios salvos em saved/data/).

• Mapeamento da hierarquia de contas da MCC:recupere os IDs de clientes de subcontas e mapeie as hierarquias de contas em uma conta de administrador.

  • Claude Code: /get-cids <manager_cid>
  • Linguagem natural: "Receber todos os IDs de clientes de clientes no administrador 123-456-7890"

• Filtros e exclusões de informações do produto da Performance Max:gere árvores de partição de produtos e exclusões de URL de página da Web para grupos de recursos.

  • Claude Code: /pmax-filter
  • Linguagem natural: "Criar filtros de exclusão de página da Web para minha campanha Performance Max"

• Contexto adicional da base de código:registre a lógica do aplicativo e a arquitetura personalizada no raciocínio do Assistente.

  • 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

Referência de comandos de barra do Claude Code

Ao usar o Claude Code, os seguintes comandos de barra integrados estão disponíveis. No Google Antigravity, invoque esses mesmos recursos usando comandos de linguagem natural ou nomes de ferramentas de habilidades, como validate_gaql e inspect_object, conforme descrito em Principais recursos:

Manutenção e atualizações

Para atualizar o repositório, a instalação do plug-in e as bibliotecas de cliente:

Desinstalação

Para desinstalar o plug-in do assistente:

Comunidade e suporte

• Problemas do GitHub: relate bugs, sugira recursos ou peça ajuda na guia "Problemas" do repositório.
• Discord: participe da discussão no canal #ads-api-ai-tools no servidor do Discord da Comunidade de publicidade e medição do Google.
• Feedback: compartilhe seu feedback neste formulário de pesquisa.

Diretrizes de colaboração

As contribuições são bem-vindas. Consulte o arquivo CONTRIBUTING.md no repositório do GitHub para conferir as diretrizes.