O Assistente de desenvolvedor da API Google Ads traz experiência profunda no domínio da API Google Ads diretamente para seu ambiente de programaçã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 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 especializadas no domínio para manter um 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 projeto do Google Cloud com níveis de acesso do Explorer, Básico ou Standard. Para verificar os níveis de acesso do seu projeto ou solicitar um nível adequado, consulte Níveis de acesso à API.
   • Um arquivo de configuração do Google Ads configurado com suas credenciais OAuth 2.0 e ID do cliente, localizado no seu diretório inicial. Consulte o guia de configuração da biblioteca de cliente.
   • Familiaridade com os conceitos e a autenticação da API Google Ads.

2. Software:

   • O Python 3.10 ou uma versão 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 do agente 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).
   • O Git está 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. Execute o script de instalação

Execute o script de instalação para sua plataforma segmentada. Por padrão, a biblioteca de cliente Python é incluída. 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 de cliente padrão, insira o número do ID diretamente em config/customer_id.txt (por exemplo, 1234567890). Também é possível inspecionar ou fixar sua 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 Google Assistente

É possível interagir com o Google Assistente usando comandos em linguagem natural ou comandos de barra dedicados diretamente no terminal.

Principais recursos

• Perguntas e respostas em linguagem natural:faça perguntas sobre recursos, práticas recomendadas ou recursos específicos da API Google Ads.

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

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

• Geração de código de biblioteca de cliente embasada:gere código testado e idiomático usando 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:faça um teste a seco e valide automaticamente consultas complexas em relação a metadados da API, compatibilidade de campos, regras de zero impressão 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 de API ativa 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 Google Assistente cria, valida e executa consultas da GAQL diretamente na sua conta, transmitindo tabelas formatadas ao vivo 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 de API e segurança de mutação:execute scripts somente leitura gerados diretamente em um ambiente virtual gerenciado.

  • Basta dizer ao Google Assistente: "Execute o código" ou "Execute o script".
  • Segurança de mutação:para garantir a 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 manualmente fora do assistente.

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

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

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

  • Claude Code:/get-cids <manager_cid>
  • Linguagem natural:"Receba todos os IDs de cliente do cliente no gerente 123-456-7890"

• Filtros e exclusões de produtos anunciados das campanhas Performance Max:gere árvores de partição de produtos e exclusões de URL de páginas da Web para grupos de recursos.

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

• Contexto adicional da base de código:registre a lógica do aplicativo e a arquitetura personalizada no raciocínio do Google 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 habilidade, como validate_gaql e inspect_object, conforme descrito em Principais recursos:

Manutenção e atualizações

Para atualizar o repositório, a instalação de plug-ins 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 sua opinião neste formulário de pesquisa.

Diretrizes de contribuição

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