Google Agents CLI

🧠 O que é o Google Agents CLI

O Google Agents CLI (agents-cli) não é um coding assistant. É um toolkit que injeta conhecimento especializado em qualquer coding assistant (Claude Code, Antigravity, Codex, Cursor, etc.) para que ele saiba construir, avaliar e deployar agentes de IA no Google Cloud.

Em vez de você aprender cada CLI e serviço do GCP (Cloud Build, IAM, Artifact Registry, Cloud Run, Agent Runtime...), o agents-cli dá ao seu assistente as skills e comandos para fazer tudo isso sozinho.

Funciona com

🏗️ Arquitetura e ecossistema

┌──────────────────────────────────────────────────────┐
│  Seu Coding Assistant (Claude Code, Antigravity…)     │
│  + 7 skills do agents-cli injetadas                   │
├──────────────────────────────────────────────────────┤
│  agents-cli (CLI Python)                               │
│  scaffold │ eval │ deploy │ publish │ observe         │
├──────────────────────────────────────────────────────┤
│  Google Cloud                                          │
│  Agent Runtime │ Cloud Run │ GKE │ Vertex AI Eval     │
│  Gemini Enterprise │ A2A Protocol │ ADK Web           │
└──────────────────────────────────────────────────────┘

Stack Google para agentes

📦 Instalação — passo a passo

1 Pré-requisitos

# Python 3.11+
python3 --version   # Deve mostrar ≥ 3.11

# Node.js (para skills)
node --version      # Deve mostrar ≥ 18

2 Instalar o uv (gerenciador de pacotes)

curl -LsSf https://astral.sh/uv/install.sh | sh

3 Instalar o agents-cli + skills

export PATH="$HOME/.local/bin:$PATH"
uvx google-agents-cli setup

4 Verificar

agents-cli --version

🏗️ Scaffold — criando seu primeiro agente

O comando scaffold gera um projeto Python completo com estrutura padronizada ADK, testes, eval boilerplate, e configuração de deploy.

Criar projeto novo

cd ~/projetos
agents-cli scaffold create meu-agente --agent adk --yes

Tipos de agentes disponíveis

Flags úteis

📂 Estrutura do projeto gerado

🔨 Build — como escrever o código do agente

O arquivo principal é app/agent.py. O template padrão vem com um agente ReAct simples (clima + hora).

Exemplo do template gerado

from google.adk.agents import Agent
from google.adk.apps import App
from google.adk.models import Gemini

# Ferramenta: busca clima (mock)
def get_weather(query: str) -> str:
    if "san francisco" in query.lower():
        return "It's 60 degrees and foggy."
    return "It's 90 degrees and sunny."

# Ferramenta: hora atual
def get_current_time(query: str) -> str:
    # ... lógica de timezone ...

# Agente principal
root_agent = Agent(
    name="root_agent",
    model=Gemini(model="gemini-flash-latest"),
    instruction="You are a helpful AI assistant...",
    tools=[get_weather, get_current_time],
)

app = App(root_agent=root_agent, name="app")

Anatomia de um Agent ADK

🎮 Playground — testando localmente

cd meu-agente
agents-cli install    # Instala dependências
agents-cli playground  # Sobe servidor local

O playground oferece:

• Chat UI — interface web para conversar com o agente
• Hot reload — edite agent.py e recarrega automaticamente
• Debug tools — inspecione chamadas de ferramenta, traces, estado

🎯 Avaliação — o Quality Flywheel

O diferencial mais impressionante do agents-cli: um pipeline de avaliação automatizada que melhora seu agente continuamente.

O ciclo de avaliação

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│ 1. Dataset    │ ──▶ │ 2. Generate   │ ──▶ │ 3. Grade      │
│ synthesize    │     │ (rodar agente) │     │ (avaliar)     │
└──────────────┘     └──────────────┘     └──────────────┘
                                                │
┌──────────────┐     ┌──────────────┐           │
│ 5. Optimize   │ ◀── │ 4. Analyze    │ ◀─────────┘
│ (auto-tune)   │     │ (padrões falha)│
└──────────────┘     └──────────────┘

Comandos

Dataset padrão gerado

// tests/eval/datasets/basic-dataset.json
{
  "eval_cases": [
    {
      "eval_case_id": "greeting",
      "prompt": {
        "role": "user",
        "parts": [{"text": "Hello, what can you help me with?"}]
      }
    },
    {
      "eval_case_id": "weather_query",
      "prompt": {
        "role": "user",
        "parts": [{"text": "What's the weather like in San Francisco?"}]
      }
    }
  ]
}

🚀 Deploy — subindo para o Google Cloud

Autenticação

gcloud auth login --update-adc
gcloud config set project SEU_PROJECT_ID

Deploy

cd meu-agente
agents-cli deploy                          # Agent Runtime (padrão)
agents-cli deploy --deployment-target cloud_run  # Cloud Run
agents-cli deploy --deployment-target gke        # Kubernetes

O que acontece por trás

1. Empacota o código do agente
2. Sobe para o Artifact Registry (container)
3. Cria/deploya no Agent Runtime (serviço gerenciado)
4. Retorna URL pública do agente

Publicar no Gemini Enterprise

agents-cli publish gemini-enterprise

Registra o agente no catálogo corporativo com endpoint A2A, documentação e metadados.

CI/CD Automatizado

agents-cli scaffold enhance     # Adiciona CI/CD ao projeto existente
agents-cli infra cicd           # Provisiona pipeline + staging/prod

🎓 Sistema de Skills

As 7 skills são arquivos Markdown que ensinam seu coding assistant a dominar cada fase do ciclo de vida de um agente.

Fluxo de uso das skills

📋 Referência completa de comandos

🆚 Comparação: agents-cli vs Hermes Agent

🧪 Exemplo prático — Audio Summarizer

Agente real criado nesta VPS durante o tutorial. Resumindo:

# 1. Scaffold
cd ~/projetos
agents-cli scaffold create audiosummarizer --agent adk --yes

# 2. Instalar deps
cd audiosummarizer && agents-cli install

# 3. Ver estrutura
ls -la
# agents-cli-manifest.yaml  pyproject.toml  GEMINI.md
# app/  tests/  deployment/

# 4. Info do projeto
agents-cli info
# Project:        audiosummarizer
# Deployment:     agent_runtime
# Agent dir:      app
# Region:         us-east1
# A2A:            yes

# 5. Playground (local, sem GCP)
agents-cli playground
# → http://127.0.0.1:8080/dev-ui/?app=app

Dataset de teste

# tests/eval/datasets/basic-dataset.json
{
  "eval_cases": [
    {"eval_case_id": "greeting", "prompt": "Hello..."},
    {"eval_case_id": "weather_query", "prompt": "What's the weather..."}
  ]
}

O projeto está em ~/projetos/audiosummarizer/ nesta VPS para referência.

🔗 Links oficiais

📦 GitHub — google/agents-cli

📖 Documentação oficial

📦 PyPI — google-agents-cli

🎥 Vídeo demo no YouTube

🔧 Agent Development Kit (ADK)

Instalado na VPS A em 29/06/2026 · agents-cli v0.6.1 · Projeto exemplo: ~/projetos/audiosummarizer