Instalar e usar o Assistente de desenvolvedor da API Google Ads

O Assistente para Desenvolvedores da API Google Ads traz um conhecimento profundo do 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 os frameworks 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 um contexto persistente, limites de segurança robustos e pipelines de validação automatizados. Consulte O que é o Assistente para Desenvolvedores da API Google Ads? para uma visão geral da arquitetura e do design.

Pré-requisitos

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

  1. Acesso à API Google Ads:

  2. Software:

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 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 de destino. Por padrão, a biblioteca de cliente do Python está incluída. Se quiser, inclua outras bibliotecas de cliente (--php, --ruby, --java, --dotnet ou --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. 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 de cliente 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

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 de arquitetura, práticas recomendadas ou recursos específicos. O assistente baseia as respostas em definições oficiais de API, em vez de depender apenas do treinamento geral do 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 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."
    • "Get all enabled ad group names for customer 123-456-7890."
    • "Escreva um código para criar uma campanha Performance Max." O código gerado é salvo no diretório saved/code/.

  • Validador de consulta programático da GAQL:faça simulações 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 esquemas de objetos e Protobuf:inspecione dinamicamente estruturas de recursos, campos aninhados, tipos de dados e valores de tipo enumerado para qualquer versão de API ativa sem sobrecarga de metadados remotos.

    • Claude Code:/inspect-object <resource_or_enum>
    • Linguagem natural:"Inspecionar recurso da 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ções para saved/csv/).

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

    • Diga ao Assistente: "Executar o código" ou "Executar 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-os 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: "Resolver problemas de conversões do cliente 123-456-7890." Os relatórios são salvos em saved/data/.

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

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

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

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

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

    • 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

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:

Comando de barra Finalidade Exemplo
/validate-gaql Valida a sintaxe, a compatibilidade e as regras da GAQL. /validate-gaql
/inspect-object Inspeciona campos, tipos e tipos enumerados do Protobuf. /inspect-object Campaign
/get-cids Resolve hierarquias de contas de administrador e CIDs de clientes. /get-cids 1234567890
/troubleshoot-conversions Executa diagnósticos de upload de conversões off-line. /troubleshoot-conversions
/pmax-filter Gera filtros e exclusões de listagem de campanhas PMax. /pmax-filter
/explain Oferece uma explicação estruturada em quatro partes. /explain shared set
/step-by-step Formular um plano de execução de tarefas em várias fases. /step-by-step upload conversions
/assistant-tutorial Executa um tutorial interativo de 11 etapas. /assistant-tutorial

Manutenção e atualizações

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

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

Desinstalação

Para desinstalar o plug-in do assistente:

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"

Em seguida, reinicie a sessão do host do Antigravity.

Claude Code

Em uma sessão ativa do Claude Code:

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

Ou no terminal:

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

(Opcional) Remova o registro do marketplace local:

claude plugin marketplace remove google-ads-assistant-local

Comunidade e suporte

Diretrizes de contribuição

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

Próximas etapas

Anterior
O que é o Assistente para desenvolvedores da API Google Ads?