# Agents CLI: Guia Definitivo da CLI que Transforma Seu Coding Agent em Especialista Google ADK > Guia completo do Agents CLI — instale no Claude Code, Codex ou Antigravity e ganhe 7 skills para scaffold, deploy, evaluate e monitor agentes no Agent Platform. Source: https://agentify.ia.br/blog/agents-cli-google/ > **TL;DR — O Agents CLI é uma CLI open-source do Google que se instala no seu coding agent (Claude Code, Codex, Antigravity) e injeta 7 skills especializadas para scaffold, evaluate, deploy, monitor, register, secure e iterate agentes ADK. Você descreve o que quer em plain English, o coding agent faz o resto. Zero context-switch. Tudo do editor.** ## Overview: O que é o Agents CLI Imagine que seu coding agent — Claude Code, Codex CLI, Google Antigravity — acordasse amanhã sabendo tudo sobre o Agent Development Kit (ADK), o Agent Platform, Cloud Trace, AutoRaters e o Agent Registry. Não sabendo “em teoria”. Sabendo executar. Scaffold, deploy, evaluate, monitor. Tudo. É exatamente isso que o **Agents CLI** faz. ### O conceito O Agents CLI não é mais uma CLI que você opera manualmente no terminal. É uma CLI que **se instala dentro do seu coding agent** e expõe 7 skills especializadas. Quando você pede “crie um agente de atendimento ao cliente com ADK”, o coding agent já sabe como fazer — porque o Agents CLI injetou o conhecimento. A proposta: **descreva o que quer em plain English (ou português mesmo) e o coding agent cuida do scaffold, evaluate, deploy e monitor**. Sem sair do editor. Sem abrir console. Sem copiar comandos de documentação. ### O diferencial Existem dezenas de CLIs no ecossistema de agentes. O que torna o Agents CLI diferente é o público-alvo: não é para humanos operarem diretamente — é para **coding agents operarem em seu nome**. Você nunca precisa aprender a sintaxe. Você nunca precisa lembrar flags. Você conversa com seu coding agent, e ele usa as skills por baixo. ### Compatibilidade O Agents CLI funciona com qualquer coding agent que suporte extensibilidade: - **Claude Code** — via instalação de skills/extensões - **Codex CLI** — via sistema de plugins - **Google Antigravity** — integração nativa - **Qualquer coding agent** com suporte a instruções externas ### Open-source e gratuito O Agents CLI é **open-source** e **gratuito**. Você paga apenas pelos recursos de infraestrutura que usar no Google Cloud (compute, storage, etc.) — a CLI em si não tem custo. 🔗 **Documentação oficial:** [https://google.github.io/agents-cli/guide/getting-started/](https://google.github.io/agents-cli/guide/getting-started/) --- ## Tutorial: Instalando e Usando o Agents CLI Vamos do zero ao agente em produção. Passo a passo, sem enrolação. ### Pré-requisitos Antes de começar, você precisa de: - **Um coding agent compatível** — Claude Code, Codex CLI ou Google Antigravity instalado e funcionando - **Conta Google Cloud** — com um projeto ativo e billing habilitado (para deploy) - **gcloud CLI configurado** — autenticado e com projeto default setado ``` # Verificar se gcloud está configurado gcloud auth list gcloud config get-value project ``` Se o gcloud não estiver configurado, rode: ``` gcloud auth login gcloud config set project SEU_PROJETO_ID ``` ### Passo 1: Instalação A instalação é diferente para cada coding agent, mas igualmente simples. #### Claude Code ``` # Instalar o Agents CLI como extensão no Claude Code claude code --install-skill agents-cli # Ou via configuração manual echo '{"skills": ["google/agents-cli"]}' >> ~/.claude/skills.json ``` #### Codex CLI ``` # Instalar via plugin system do Codex codex plugin install @google/agents-cli # Verificar instalação codex plugin list ``` #### Google Antigravity ``` # Integração nativa — basta atualizar antigravity update # O Agents CLI já vem incluído nas versões recentes antigravity skills list ``` Após a instalação, seu coding agent ganha **7 skills novas** automaticamente. Você pode verificar pedindo ao agent: ``` "Liste as skills do Agents CLI disponíveis" ``` O agent vai responder com: scaffold, evaluate, deploy, monitor, register, secure e iterate. ### Passo 2: Scaffold de um Novo Agente Aqui é onde a mágica começa. Ao invés de criar manualmente a estrutura de projeto, você **descreve o que quer**. No seu coding agent, diga: ``` "Crie um agente de atendimento ao cliente com ADK. Ele deve responder perguntas sobre pedidos, processar devoluções e escalar para humanos quando necessário." ``` O Agents CLI (via skill `scaffold`) vai gerar: ``` customer-support-agent/ ├── agent.py ← Lógica principal do agente ├── tools/ │ ├── order_lookup.py ← Tool para consultar pedidos │ ├── return_process.py ← Tool para processar devoluções │ └── escalation.py ← Tool para escalar para humano ├── prompts/ │ └── system.txt ← System prompt otimizado ├── config/ │ ├── agent.yaml ← Configuração ADK │ └── deploy.yaml ← Configuração de deploy ├── eval/ │ ├── test_cases.json ← Casos de teste iniciais │ └── eval_config.yaml ← Configuração dos AutoRaters ├── requirements.txt └── README.md ``` Não é um template genérico. O scaffold é **contextualizado** pela descrição que você deu. As tools já têm a estrutura correta, o system prompt já menciona os casos de uso, e os test cases já cobrem os cenários descritos. Você pode iterar imediatamente: ``` "Adicione uma tool para consultar status de entrega via API dos Correios" ``` E o coding agent atualiza o projeto mantendo a coerência. ### Passo 3: Evaluate com AutoRaters Antes de colocar em produção, você precisa avaliar se o agente funciona bem. O Agents CLI integra os **AutoRaters** — os mesmos sistemas de avaliação usados internamente pelo Google e DeepMind. Peça ao coding agent: ``` "Avalie o agente de atendimento ao cliente. Rode os AutoRaters contra os casos de teste." ``` O ciclo de avaliação segue 5 etapas: #### 1. Prepare Data O Agents CLI prepara os dados de teste. Se você não tem casos prontos, ele gera automaticamente baseado na descrição do agente: ``` "Gere 20 casos de teste para o agente, cobrindo happy paths e edge cases" ``` #### 2. Inference Roda o agente contra cada caso de teste e captura as respostas completas (incluindo chain-of-thought, tool calls e outputs). #### 3. Grade Os AutoRaters avaliam cada resposta em múltiplas dimensões: - **Correção factual** — a resposta está certa? - **Aderência à instrução** — seguiu o system prompt? - **Qualidade da tool use** — usou as tools certas, na ordem certa? - **Safety** — não gerou conteúdo problemático? - **Tone** — manteve o tom esperado? #### 4. Analyze Agrega os resultados e identifica padrões de falha: ``` 📊 Resultados da Avaliação: - Correção: 92% (18/20 cases passed) - Tool Use: 85% (17/20 correct tool selection) - Safety: 100% (0 violations) - Tone: 95% (19/20 on-brand) ⚠️ Falhas concentradas em: - Casos de devolução com múltiplos itens (2 falhas) - Consulta de pedido com ID inválido (1 falha) ``` #### 5. Optimize Com base nas falhas identificadas, o coding agent sugere (e implementa) melhorias: ``` "Otimize o agente para lidar melhor com devoluções de múltiplos itens" ``` O Agents CLI ajusta o system prompt, melhora a tool de devoluções e re-roda a avaliação para confirmar a melhoria. ### Passo 4: Deploy para Agent Runtime Chegou a hora de ir para produção. O deploy com Agents CLI é um comando — mas um comando inteligente. Peça ao coding agent: ``` "Faça deploy do agente de atendimento para produção" ``` #### Dry Run primeiro (sempre) O Agents CLI **sempre** faz um dry run antes do deploy real: ``` 🔍 Dry Run — Deploy Preview: Target: Agent Runtime (us-central1) Project: meu-projeto-gcp Agent: customer-support-agent v1.0.0 Resources que serão criados: - Cloud Run service: customer-support-agent - Cloud Trace: auto-configured - Cloud Logging: auto-configured - BigQuery dataset: agent_analytics - Agent Registry entry: customer-support-agent Estimated cost: ~$0.03/1000 requests (compute only) Proceed with deploy? [waiting for confirmation] ``` Só depois da sua confirmação o deploy acontece: ``` "Sim, pode deployar" ``` #### O que acontece no deploy O Agents CLI não apenas faz deploy do código. Ele configura **automaticamente**: - **Cloud Trace** — tracing distribuído para cada request ao agente - **Cloud Logging** — logs estruturados com contexto de sessão - **BigQuery Agent Analytics** — dataset para métricas de uso e performance - **Agent Registry** — registro do agente para discovery por outros serviços ``` ✅ Deploy concluído! Endpoint: https://customer-support-agent-xyz.run.app Registry: projects/meu-projeto/agents/customer-support-agent Dashboard: https://console.cloud.google.com/agent-analytics/... Observabilidade ativa: - Trace: ✅ - Logging: ✅ - Analytics: ✅ ``` ### Passo 5: Monitor em Produção Com o agente em produção, o Agents CLI mantém a observabilidade ativa por padrão. #### Observabilidade automática Você não precisa configurar nada. No momento do deploy, o Agents CLI já conectou: - **Cloud Trace** — cada interação do agente gera um trace completo (latência por step, tool calls, LLM calls) - **Cloud Logging** — logs estruturados com session_id, user_id, intent_detected, tools_used - **BigQuery Agent Analytics** — tabela de eventos para análise custom #### Consultar métricas via coding agent ``` "Como está o agente de atendimento nas últimas 24h?" ``` O coding agent consulta o BigQuery e responde: ``` 📊 Customer Support Agent — Últimas 24h: Requests: 1,847 Latência média: 2.3s (P99: 4.8s) Taxa de sucesso: 96.2% Escalações para humano: 12.4% Tool errors: 0.8% Top intents: 1. Consulta de pedido (43%) 2. Status de entrega (28%) 3. Devolução (18%) 4. Outros (11%) ``` #### Alertas e dashboards O Agents CLI configura alertas básicos automaticamente: - **Error rate > 5%** — alerta imediato - **Latência P99 > 10s** — alerta de performance - **Tool failure rate > 3%** — alerta de integração Você pode customizar pedindo ao coding agent: ``` "Adicione um alerta quando a taxa de escalação para humano passar de 20%" ``` --- ## Deep Dive: As 7 Skills do Agents CLI O tutorial mostrou o fluxo ponta a ponta. Aqui vamos olhar cada skill individualmente — o que ela resolve, como pensa, e onde brilha (ou não). ### 1. scaffold — O ponto de partida A `scaffold` traduz uma descrição em linguagem natural numa estrutura de projeto ADK completa. Não estamos falando de um `mkdir` glorificado: ela interpreta requisitos, cria tools coerentes com o que você descreveu, gera system prompt contextualizado, monta configuração de deploy e já entrega test cases iniciais para avaliação. O detalhe que faz diferença: se você descreve “um agente de triagem que classifica tickets em P1/P2/P3”, as tools geradas já têm a lógica de classificação, não apenas stubs vazios. ``` "Scaffold um agente de triagem de suporte técnico que classifica tickets em P1/P2/P3, extrai informações relevantes e roteia para o time correto" ``` Mesmo que você já tenha código parcial, a scaffold complementa o que falta sem sobrescrever o existente. Na prática, funciona como um par que monta a infraestrutura enquanto você foca na lógica de negócio. ### 2. evaluate — O gatekeeper antes do deploy Ninguém deveria deployar um agente sem antes responder: “ele funciona?” A `evaluate` roda os AutoRaters do Google/DeepMind contra o agente — os mesmos sistemas usados internamente para avaliar modelos. O ciclo é denso: gera ou usa test cases existentes, executa inference do agente contra cada caso, aplica AutoRaters multi-dimensionais (correção, safety, tone, tool use), produz relatório com métricas agregadas e identifica padrões de falha com sugestões de correção. ``` "Avalie o agente com foco em safety e correção factual. Use os 50 test cases do diretório eval/" ``` Uma observação prática: rode avaliações não só antes do deploy, mas depois de qualquer mudança significativa no prompt ou nas tools. O que parece uma alteração inofensiva às vezes quebra edge cases que estavam passando. ### 3. deploy — Um comando, toda a infra A skill que mais encurta distância entre “funciona no meu laptop” e “funciona em produção”. Ela valida o projeto (lint, type check, dependency check), faz dry run mostrando exatamente o que será criado, executa o deploy para Cloud Run via Agent Runtime e configura Cloud Trace, Cloud Logging e BigQuery automaticamente. ``` "Deploy o agente para produção em us-east1. Use a configuração de staging para dry run primeiro." ``` Dois detalhes importantes. Primeiro: ela chama `register` e `secure` internamente, então você não precisa lembrar de fazer essas etapas separadamente. Segundo: o dry run é obrigatório — não existe “deploy direto” sem preview. ### 4. monitor — Olhos no agente 24/7 Depois do deploy, `monitor` vira a skill do dia-a-dia. Ela configura dashboards no Cloud Monitoring, cria alertas baseados em thresholds, consulta BigQuery Agent Analytics sob demanda, gera relatórios de performance periódicos e identifica degradação de qualidade em produção. ``` "Mostre as métricas do agente na última semana. Destaque qualquer degradação vs semana anterior." ``` O uso mais valioso não é ver métricas bonitas — é pegar degradações silenciosas. Um agente pode manter 95% de sucesso geral e estar falhando em 40% de um intent específico. O `monitor` conectado ao BigQuery revela isso. ### 5. register — Tornando o agente descobrível Agentes que existem isolados são úteis. Agentes que outros serviços podem descobrir e consumir são mais úteis. A `register` cria uma entrada no Agent Registry com metadata completo: capabilities, inputs/outputs, protocolos suportados, versionamento semântico e documentação de API gerada automaticamente. ``` "Registre o agente no Agent Registry com versão 1.2.0. Ele aceita requests JSON e retorna markdown." ``` Na prática, a skill `deploy` já chama `register` internamente. O uso manual faz sentido quando você precisa atualizar metadata sem redeployar — por exemplo, marcar uma versão como deprecated ou atualizar a descrição de capabilities. ### 6. secure — A camada que você não pode esquecer Expor um agente para usuários externos sem segurança configurada é pedir problemas. A `secure` resolve isso: configura Agent Gateway como proxy de segurança, ativa Model Armor para filtrar inputs/outputs perigosos, configura mTLS para comunicação entre serviços, define rate limiting e quotas, aplica políticas de acesso (IAM) e audita conformidade. ``` "Configure segurança para o agente de atendimento. Rate limit de 100 req/min por usuário, Model Armor ativo para PII detection." ``` A skill `deploy` aplica segurança básica por padrão. A `secure` serve para ir além: quando seu agente lida com dados sensíveis, quando é exposto publicamente, ou quando compliance exige configurações específicas. ### 7. iterate — Melhoria contínua com evidência A última skill fecha o ciclo. Em vez de melhorar o agente no escuro, `iterate` puxa logs de falhas recentes do Cloud Logging, agrupa por padrão (mesmo tipo de input, mesma tool, mesmo intent), propõe correções específicas, implementa no código, re-avalia com AutoRaters e faz deploy da versão corrigida. ``` "O agente está falhando em perguntas sobre política de cancelamento. Itere para melhorar." ``` É a diferença entre “acho que o agente precisa de ajuste” e “o agente falhou 12 vezes neste pattern, aqui está a correção testada”. Use quando o monitor apontar degradação, ou como prática regular — toda sexta-feira, por exemplo. --- ### Como Funciona Por Baixo O Agents CLI não é mágico — é bem arquitetado. Quando você instala o Agents CLI no seu coding agent, ele injeta **instruções estruturadas** que o agent passa a entender. Cada skill é um conjunto de: - **Trigger patterns** — quando ativar a skill (ex: “deploy”, “avalie”, “scaffolde”) - **Procedure** — sequência de comandos gcloud/adk para executar - **Validation** — checks de pré e pós-execução - **Error handling** — o que fazer quando algo falha Quando você pede “deploy meu agente”, o coding agent: - Reconhece o trigger → skill `deploy` - Lê o procedimento da skill - Executa os comandos gcloud/adk no terminal - Valida o resultado - Reporta sucesso ou falha com contexto A tradução é transparente. Se quiser ver exatamente o que está acontecendo: ``` "Mostre os comandos que o deploy vai executar antes de rodar" ``` E o coding agent lista: ``` # Comandos que serão executados pela skill deploy: gcloud run deploy customer-support-agent \ --source . \ --region us-central1 \ --allow-unauthenticated \ --set-env-vars="AGENT_VERSION=1.0.0" gcloud agent-platform register \ --agent-id customer-support-agent \ --version 1.0.0 \ --capabilities "text-generation,tool-use" bq mk --dataset agent_analytics gcloud logging sinks create agent-logs \ bigquery.googleapis.com/projects/meu-projeto/datasets/agent_analytics ``` Nenhuma caixa preta. --- ## Avaliação: Spider Chart Avaliamos o Agents CLI em 8 eixos relevantes para uma CLI de desenvolvimento de agentes: Eixo Score Justificativa Facilidade de Início 9/10 Instala em 1 minuto, zero config adicional necessária Integração com Coding Agents 10/10 Funciona em Claude Code, Codex e Antigravity nativamente Produção/Deploy 9/10 One-command deploy com observabilidade auto-configurada Avaliação/Testing 9/10 AutoRaters de nível Google/DeepMind integrados Governança 8/10 Agent Gateway + Model Armor configurados automaticamente Documentação 7/10 Recém-lançado, documentação em crescimento ativo Flexibilidade 7/10 Focado em GCP/ADK — não é genérico multi-cloud Comunidade 6/10 Projeto novo, comunidade ainda em formação ### Score Geral: 8.1/10 O Agents CLI acerta onde importa: **a experiência de desenvolvimento**. O fluxo “descreva → scaffold → evaluate → deploy → monitor” é o mais fluido que existe hoje para agentes ADK. Os pontos fracos — documentação e comunidade — são temporais. O projeto é novo. A limitação de flexibilidade (GCP-only) é arquitetural e provavelmente permanente, mas se você já está no ecossistema Google, isso não é um problema; é coerência. --- ## Prós e Contras ### ✅ Prós **Zero context-switch** — Tudo acontece no seu editor. Sem console do GCP, sem navegar documentação, sem copiar comandos. O coding agent é a interface para tudo. **Lifecycle completo em 7 skills** — Do scaffold ao monitor, passando por evaluate, deploy, register, secure e iterate. Cada etapa crítica do desenvolvimento de agentes tem uma skill dedicada. **AutoRaters sem custo adicional** — Os mesmos sistemas de avaliação usados internamente pelo Google e DeepMind, de graça. Honestamente, isso sozinho já justifica instalar o Agents CLI — a alternativa é construir sua própria pipeline de avaliação do zero. **Agnóstico de coding agent** — Claude Code, Codex, Antigravity — funciona em todos. Você não fica preso a um editor. **Observabilidade que vem de fábrica** — Cloud Trace, Cloud Logging e BigQuery Agent Analytics configurados no deploy. Quantos projetos seus estão em produção sem observabilidade porque “ia configurar depois”? **Dry run obrigatório** — Toda operação destrutiva mostra preview antes de executar. Parece óbvio, mas a quantidade de CLIs que não fazem isso é impressionante. **Open-source** — Código aberto, sem licença proprietária, sem vendor lock na ferramenta em si. ### ❌ Contras **GCP only. Ponto.** — Se você usa AWS ou Azure, o Agents CLI não vai te ajudar diretamente. Não existe plano anunciado para suportar AWS Bedrock Agents, Azure AI Agent Service ou outras plataformas. **Projeto novo, arestas esperadas** — Como todo lançamento recente, prepare-se para bugs ocasionais, breaking changes e gaps de funcionalidade. Nada que impeça o uso, mas calibre expectativas. **Documentação rasa em cenários avançados** — O básico está coberto. Cenários de edge case, configurações não-standard, debugging complexo? Você vai ter que experimentar. A comunidade ainda não produziu volume significativo de conteúdo auxiliar. **Exige gcloud configurado** — Se sua máquina de dev não tem gcloud setup, é um pré-requisito antes de qualquer skill funcionar. Não é complexo, mas pode travar quem está testando rápido. ### Veredicto **Para quem já usa GCP + ADK: instale hoje.** A redução de fricção é grande. O que antes levava horas de configuração manual agora acontece em minutos, conversando com seu coding agent. **Para quem usa outro cloud: vale estudar o modelo.** A ideia de CLI que injeta skills em coding agents é poderosa independente do vendor. O padrão vai se espalhar. --- ## Quando Usar o Agents CLI ### ✅ Use quando: - **Você já usa Google Cloud** como cloud principal - **Quer deploy rápido** de agentes ADK sem configuração manual - **Sua equipe usa coding agents** (Claude Code, Codex, Antigravity) no dia-a-dia - **Precisa de avaliação** rigorosa com AutoRaters antes de ir para produção - **Quer observabilidade** sem configurar manualmente Trace/Logging/Analytics - **Está começando com ADK** e quer o caminho mais rápido do zero ao deploy - **Tem múltiplos agentes** e quer padronizar o fluxo de desenvolvimento ### ❌ NÃO use quando: - **Sua stack é AWS ou Azure** — o Agents CLI não suporta outros clouds - **Seus agentes não são ADK** — se usa LangChain, CrewAI, AutoGen puro, o Agents CLI não é o tool certo - **Precisa de multi-cloud** — deployar o mesmo agente em GCP + AWS não é suportado - **Não usa coding agents** — se você prefere operar CLIs diretamente, use o gcloud + adk CLI padrão - **Quer controle granular** sobre cada flag de deploy — o Agents CLI abstrai muita coisa, o que pode incomodar quem quer controlar tudo manualmente --- ## Próximos Passos Se o Agents CLI te interessou, esses conteúdos complementam: - **[Guia Definitivo do Google ADK](/blog/google-adk)** — entenda o framework por baixo do Agents CLI - **[Ciclo Build-Scale-Govern-Optimize](/blog/ciclo-build-scale-govern-optimize)** — a filosofia do Agent Platform que o Agents CLI implementa - **[Documentação oficial do Agents CLI](https://google.github.io/agents-cli/guide/getting-started/)** — referência técnica completa ### Experimente hoje O caminho mais rápido: ``` # 1. Instale no seu coding agent (exemplo: Claude Code) claude code --install-skill agents-cli # 2. Peça para scaffoldar um agente simples # "Crie um agente que responde perguntas sobre meu produto" # 3. Avalie # "Rode os AutoRaters contra o agente" # 4. Se passou, deploy # "Deploy para produção" ``` Em menos de 30 minutos você vai do zero ao agente em produção com observabilidade completa. Sem exagero — o gargalo é decidir o que o agente faz, não configurar infra. --- *Quer acompanhar as novidades do ecossistema de agentes AI? Acesse [ft.ia.br](https://ft.ia.br) para análises, guias e tutoriais sobre as ferramentas que estão moldando o futuro do desenvolvimento de software.* -->