Agents CLI: Guia Definitivo da CLI que Transforma Seu Coding Agent em Especialista Google ADK

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/

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:

1. Um coding agent compatível — Claude Code, Codex CLI ou Google Antigravity instalado e funcionando
2. Conta Google Cloud — com um projeto ativo e billing habilitado (para deploy)
3. 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:

1. Cloud Trace — tracing distribuído para cada request ao agente
2. Cloud Logging — logs estruturados com contexto de sessão
3. BigQuery Agent Analytics — dataset para métricas de uso e performance
4. 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:

1. Trigger patterns — quando ativar a skill (ex: “deploy”, “avalie”, “scaffolde”)
2. Procedure — sequência de comandos gcloud/adk para executar
3. Validation — checks de pré e pós-execução
4. Error handling — o que fazer quando algo falha

Quando você pede “deploy meu agente”, o coding agent:

1. Reconhece o trigger → skill deploy
2. Lê o procedimento da skill
3. Executa os comandos gcloud/adk no terminal
4. Valida o resultado
5. 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:

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 — entenda o framework por baixo do Agents CLI
• Ciclo Build-Scale-Govern-Optimize — a filosofia do Agent Platform que o Agents CLI implementa
• Documentação oficial do Agents CLI — 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 para análises, guias e tutoriais sobre as ferramentas que estão moldando o futuro do desenvolvimento de software.