CLI de agentes na plataforma de agentes: do desenvolvimento à produção

1. Visão geral

O que você vai aprender

Neste codelab, você vai criar, testar e implantar um agente de IA pronto para produção usando a CLI do Agents e o Kit de Desenvolvimento de Agente (ADK). Você vai instalar as ferramentas e ter um agente ativo em execução no ambiente de execução do agente do Google Cloud em menos de uma hora.

O que você vai criar

Um agente de IA de suporte ao cliente que pode:

  • Responder perguntas usando linguagem natural
  • Chamar ferramentas personalizadas (consultas de clima e hora)
  • Ser testado localmente com feedback instantâneo
  • Ser avaliado automaticamente quanto à qualidade
  • Executar em produção no Google Cloud

Duas maneiras de usar a CLI Agents

A CLI do Agents é compatível com dois fluxos de trabalho:

🤖 Com um agente de programação (recomendado para iniciantes)

Deixe a IA te guiar! Instale habilidades na CLI do Gemini, no Antigravity, no Claude Code, no Cursor ou em qualquer outro agente de programação compatível. Eles vão ajudar você a criar o agente etapa por etapa.

👤 Modo manual (para desenvolvedores que preferem controle direto)

Execute comandos por conta própria no terminal. Você vai digitar cada comando e ver exatamente o que acontece.

Ao longo deste codelab, vamos mostrar as duas abordagens. Escolha o que mais combina com você!

O que é necessário

Obrigatório:

  • Python 3.11 ou mais recente
  • Gerenciador de pacotes uv
  • Node.js 18 ou mais recente (para habilidades de programação de agentes)
  • Projeto na nuvem do Google com o faturamento ativado
  • O SDK do Google Cloud está instalado

Opcional para desenvolvimento apenas local:

Pré-requisitos

Este codelab pressupõe que você tenha familiaridade com:

  • Usar um terminal/linha de comando
  • Conceitos básicos do Python
  • Princípios básicos do console do Google Cloud

Não é necessário ter experiência prévia com agentes de IA ou ADK.

2. Antes de começar

Configurar o Google Cloud

Criar ou selecionar um projeto

  1. Acesse o console do Google Cloud.
  2. Crie um projeto ou selecione um atual.
  3. Anote o ID do projeto, porque você vai precisar dele mais tarde.

Ativar APIs obrigatórias

Execute estes comandos no terminal (ou use o Console do Cloud):

gcloud services enable aiplatform.googleapis.com \
  run.googleapis.com \
  cloudtrace.googleapis.com \
  cloudbuild.googleapis.com

Isso permite:

  • Plataforma de agentes: para o modelo do Gemini e o ambiente de execução do agente
  • Cloud Run: opção de implantação alternativa
  • Cloud Trace: observabilidade e monitoramento
  • Cloud Build: automação de build

Autenticar

gcloud auth login
gcloud auth application-default login

Defina as variáveis de ambiente

export GOOGLE_CLOUD_PROJECT=YOUR_PROJECT_ID
export GOOGLE_CLOUD_LOCATION=us-central1

Substitua YOUR_PROJECT_ID pelo ID do projeto.

3. Instalar a CLI do Agents

🤖 Com um agente de programação

Se você estiver usando a CLI do Gemini, o Antigravity, o Claude Code, o Cursor ou qualquer outro agente de programação compatível:

uvx google-agents-cli setup

Isso instala:

  • A ferramenta de CLI do Agents globalmente
  • 7 habilidades que qualquer agente de programação compatível na sua máquina pode usar para ajudar você a criar agentes. As habilidades são instaladas uma vez e descobertas por todos os agentes que as oferecem.

Saída esperada (cortada):

 █▀█ █▀▀ █▀▀ █▄ █ ▀█▀ █▀   █▀▀ █  █
 █▀█ █▄█ ██▄ █ ▀█  █  ▄█   █▄▄ █▄ █

 Your coding agent just got an upgrade.

 1. Authentication
 ─────────────────
   ✓ Authenticated with Google Cloud

 2. CLI Installation
 ───────────────────
   ▸ uv tool install google-agents-cli
   ✓ Installed google-agents-cli

 3. Skills Installation
 ──────────────────────
   ▸ npx -y skills add https://github.com/google/agents-cli -y --all -g

   ◇  Found 7 skills
   ~/.agents/skills/google-agents-cli-adk-code
   ~/.agents/skills/google-agents-cli-deploy
   ~/.agents/skills/google-agents-cli-eval
   ~/.agents/skills/google-agents-cli-observability
   ~/.agents/skills/google-agents-cli-publish
   ~/.agents/skills/google-agents-cli-scaffold
   ~/.agents/skills/google-agents-cli-workflow

As habilidades são instaladas via skills (npx -y skills@latest) em ~/.agents/skills/ e capturadas automaticamente por todos os agentes de programação compatíveis na sua máquina.

👤 Modo manual

Se você preferir executar comandos diretamente:

uv tool install google-agents-cli

Verifique a instalação:

agents-cli --version

Resposta esperada:

agents-cli, version 0.1.2

4. Criar o projeto do agente

🤖 Com um agente de programação

Pergunte ao agente de programação:

"Crie um novo projeto de agente do ADK chamado customer-support-agent usando o modelo de protótipo"

O agente vai executar o comando de scaffolding e criar o projeto para você.

👤 Modo manual

Use o modo rápido para criar um projeto consistente que corresponda a este codelab:

agents-cli scaffold create customer-support-agent --prototype --yes

Isso cria um projeto básico de agente do ADK instantaneamente com todo o código necessário para este codelab.

Resposta esperada:

Agents CLI v0.1.2
> Verifying GCP credentials...
> ✓ Connected to project: YOUR_PROJECT_ID

✅ Success! Your agent project is ready.

📖 Documentation
   README:    cat customer-support-agent/README.md

💡 Tip
   Add a deployment target later with: agents-cli scaffold enhance

🚀 Get Started
   cd customer-support-agent && agents-cli install && agents-cli playground

Alternativa: modo interativo

Se quiser conhecer outros tipos de agentes, execute sem flags:

agents-cli scaffold create customer-support-agent

Você vai encontrar opções para:

  • adk: agente ReAct simples (escolha esta opção para o codelab)
  • adk_a2a: comunicação entre agentes
  • agentic_rag: perguntas e respostas sobre documentos com base em RAG

O que foi criado?

customer-support-agent/
├── app/
│   ├── agent.py              # Your agent code (main file)
│   ├── fast_api_app.py       # Development server (replaced when you add a deployment target)
│   └── app_utils/            # Utilities (telemetry, etc.)
├── tests/
│   ├── unit/                 # Unit tests
│   ├── integration/          # Integration tests
│   └── eval/                 # Evalsets and rubric config for `adk eval`
├── Dockerfile                # Container image (removed when you switch to Agent Runtime)
├── GEMINI.md                 # Coding-agent context for this project
├── pyproject.toml            # Project config & dependencies
├── README.md                 # Project documentation
└── .gitignore

5. Conhecer o código do agente 

cd customer-support-agent

Analisar o agente

Abra app/agent.py, onde seu agente está definido:

import datetime
from zoneinfo import ZoneInfo

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

import os
import google.auth

_, project_id = google.auth.default()
os.environ["GOOGLE_CLOUD_PROJECT"] = project_id
os.environ["GOOGLE_CLOUD_LOCATION"] = "global"
os.environ["GOOGLE_GENAI_USE_VERTEXAI"] = "True"


def get_weather(query: str) -> str:
    """Simulates a web search. Use it get information on weather.

    Args:
        query: A string containing the location to get weather information for.

    Returns:
        A string with the simulated weather information for the queried location.
    """
    if "sf" in query.lower() or "san francisco" in query.lower():
        return "It's 60 degrees and foggy."
    return "It's 90 degrees and sunny."


def get_current_time(query: str) -> str:
    """Simulates getting the current time for a city.

    Args:
        city: The name of the city to get the current time for.

    Returns:
        A string with the current time information.
    """
    if "sf" in query.lower() or "san francisco" in query.lower():
        tz_identifier = "America/Los_Angeles"
    else:
        return f"Sorry, I don't have timezone information for query: {query}."

    tz = ZoneInfo(tz_identifier)
    now = datetime.datetime.now(tz)
    return f"The current time for query {query} is {now.strftime('%Y-%m-%d %H:%M:%S %Z%z')}"


root_agent = Agent(
    name="root_agent",
    model=Gemini(
        model="gemini-flash-latest",
        retry_options=types.HttpRetryOptions(attempts=3),
    ),
    instruction="You are a helpful AI assistant designed to provide accurate and useful information.",
    tools=[get_weather, get_current_time],
)

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

Principais conceitos

Ferramentas: funções Python que o agente pode chamar

  • get_weather(query): retorna o clima simulado (neblina e 15 °C em São Francisco, ensolarado e 32 °C em outros lugares)
  • get_current_time(query): retorna a hora atual (somente São Francisco neste stub)

Modelo: gemini-flash-latest é um alias que rastreia automaticamente a versão estável mais recente do Gemini Flash. Assim, esse código continua funcionando à medida que o Google lança novas versões. Para fixar um modelo específico, troque por algo como gemini-2.5-flash (estável) ou gemini-3-flash-preview (prévia).

App / root_agent: os projetos do ADK expõem um App de nível superior que envolve um root_agent. O playground, o adk eval e o Agent Runtime descobrem o agente usando esse objeto app.

Local =

"global": alguns modelos de prévia do Gemini são veiculados apenas pelo endpoint global. Por isso, o scaffold o define explicitamente.

Instrução: comando do sistema que molda o comportamento do agente.

6. Testar localmente com o playground

O ambiente de teste oferece uma interface de chat interativa para testes.

🤖 Com um agente de programação

Pergunte ao agente:

"Iniciar o playground do meu agente"

👤 Modo manual

Instale as dependências primeiro

agents-cli install

Isso executa uv sync nos bastidores, resolvendo e instalando as dependências do agente em um .venv local.

Iniciar o playground

agents-cli playground

Resposta esperada:

╭──────────────────────────────────────────────────────────────────────────────╮
│ Starting your agent playground...                                            │
│                                                                              │
│ Will be available at:  http://127.0.0.1:8080/dev-ui/?app=app                 │
╰──────────────────────────────────────────────────────────────────────────────╯
  ▸ uv run adk web . --host 127.0.0.1 --port 8080 --reload_agents
INFO:     Started server process
INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8080

Faça um teste

  1. Abra http://127.0.0.1:8080/dev-ui/?app=app no navegador.
  2. Tente estes comandos:
    • "Como está o tempo em São Francisco?"
    • "Qual é a previsão do tempo em Tóquio?"
    • "Que horas são em São Francisco?"

Veja como o agente:

  • Chama a ferramenta get_weather
  • Chama a ferramenta get_current_time
  • Combina resultados em respostas naturais

7. Executar na linha de comando

Teste seu agente sem abrir um navegador.

🤖 Com um agente de programação

Pergunte ao agente:

"Execute o agente com a consulta "Como está o tempo em Paris?""

👤 Modo manual

agents-cli run "What's the weather in San Francisco?"

Resposta esperada:

Using project root directory: /path/to/customer-support-agent
Local server started on port 18080 (PID 30008)
  Stop with: agents-cli run --stop-server
[user]: What's the weather in San Francisco?
[root_agent]:
[tool_call: get_weather({"query": "San Francisco"})]
[tool_response: get_weather -> {"result": "It's 60 degrees and foggy."}]The weather in San Francisco is 60 degrees and foggy.

Session: fb30f7f7-147e-4697-8aaa-706d604589fa (resume with --session-id)

Nos bastidores, o run inicializa um adk api_server em segundo plano (mantido ativo por cerca de 30 minutos) para que as chamadas subsequentes sejam rápidas. Interrompa explicitamente com agents-cli run --stop-server. Retomar uma conversa multiturno com --session-id .

O comando run é perfeito para:

  • Testes rápidos durante o desenvolvimento
  • Scripting e automação
  • Pipelines de CI/CD

8. Avalie seu agente

As avaliações do ADK validam duas coisas independentes:

  1. Trajetória da ferramenta: o agente chamou as ferramentas certas com os argumentos corretos? Determinista, correspondência exata.
  2. Qualidade da resposta: a resposta final é relevante, útil e embasada nas saídas da ferramenta? Pontuado por um LLM que atua como um avaliador.

Você precisa dos dois. A pontuação da rubrica sozinha pode aprovar uma resposta inventada que parece boa, mas a trajetória sozinha não consegue dizer se o usuário recebeu uma resposta útil. O conjunto de avaliação do codelab exercita os dois.

Eles são gerados por dois arquivos:

  • tests/eval/evalsets/basic.evalset.json: as conversas a serem reproduzidas e as chamadas de função esperadas.
  • tests/eval/eval_config.json — quais métricas pontuar, os limites delas e a rubrica para o avaliador de LLM

Edite o evalset para incluir as chamadas de ferramenta esperadas

Substitua o conteúdo de tests/eval/evalsets/basic.evalset.json por:

{
  "eval_set_id": "basic_eval",
  "name": "Basic Agent Evaluation",
  "description": "Validates that the agent calls the right tools AND produces a quality response.",
  "eval_cases": [
    {
      "eval_id": "weather_san_francisco",
      "conversation": [
        {
          "user_content": {"parts": [{"text": "What's the weather like in San Francisco?"}], "role": "user"},
          "final_response": {"parts": [{"text": "The weather in San Francisco is 60 degrees and foggy."}], "role": "model"},
          "intermediate_data": {
            "tool_uses": [{"name": "get_weather", "args": {"query": "San Francisco"}}],
            "tool_responses": [],
            "intermediate_responses": []
          }
        }
      ],
      "session_input": {"app_name": "app", "user_id": "eval_user", "state": {}}
    },
    {
      "eval_id": "weather_tokyo",
      "conversation": [
        {
          "user_content": {"parts": [{"text": "What's the weather in Tokyo?"}], "role": "user"},
          "final_response": {"parts": [{"text": "The weather in Tokyo is 90 degrees and sunny."}], "role": "model"},
          "intermediate_data": {
            "tool_uses": [{"name": "get_weather", "args": {"query": "Tokyo"}}],
            "tool_responses": [],
            "intermediate_responses": []
          }
        }
      ],
      "session_input": {"app_name": "app", "user_id": "eval_user", "state": {}}
    },
    {
      "eval_id": "time_san_francisco",
      "conversation": [
        {
          "user_content": {"parts": [{"text": "What time is it in San Francisco?"}], "role": "user"},
          "intermediate_data": {
            "tool_uses": [{"name": "get_current_time", "args": {"query": "San Francisco"}}],
            "tool_responses": [],
            "intermediate_responses": []
          }
        }
      ],
      "session_input": {"app_name": "app", "user_id": "eval_user", "state": {}}
    }
  ]
}

O bloco intermediate_data.tool_uses é a trajetória esperada: quais ferramentas o agente deve chamar e com quais argumentos. A métrica de trajetória compara isso com o que realmente aconteceu durante a execução.

Edite a rubrica para pontuar as duas métricas

Substitua tests/eval/eval_config.json por:

{
  "criteria": {
    "tool_trajectory_avg_score": 1.0,
    "rubric_based_final_response_quality_v1": {
      "threshold": 0.8,
      "judgeModelOptions": {"judgeModel": "gemini-flash-latest", "numSamples": 1},
      "rubrics": [
        {"rubricId": "relevance",     "rubricContent": {"textProperty": "The response directly addresses the user's query."}},
        {"rubricId": "helpfulness",   "rubricContent": {"textProperty": "The response is helpful and provides useful information."}},
        {"rubricId": "tool_grounded", "rubricContent": {"textProperty": "The response is grounded in the values returned by the tools (e.g. the exact temperature and weather condition) and does not invent details."}}
      ]
    }
  }
}

O que cada linha faz:

  • tool_trajectory_avg_score: 1.0: adiciona a métrica de trajetória com um limite estrito de 1,0 (cada chamada de ferramenta esperada precisa corresponder exatamente). A pontuação é calculada de forma determinística comparando os eventos function_call reais do agente com intermediate_data.tool_uses.
  • rubric_based_final_response_quality_v1: executa um LLM como juiz (gemini-flash-latest aqui) que pontua a resposta final em relação a cada rubrica em uma escala de 0 a 1 e, em seguida, calcula a média. O caso é aprovado quando a média atinge threshold (0,8). A rubrica tool_grounded pede explicitamente ao avaliador para penalizar respostas que contradizem ou inventam informações sobre a saída da ferramenta, uma defesa contra alucinações em camadas sobre a verificação de trajetória.

🤖 Com um agente de programação

Pergunte ao agente:

"Execute as avaliações do meu agente"

👤 Modo manual

agents-cli eval run --all

--all é executado a cada *.evalset.json em tests/eval/evalsets/. Para segmentar um, use --evalset tests/eval/evalsets/basic.evalset.json.

Saída esperada (cortada):

  ▸ uv run adk eval ./app tests/eval/evalsets/basic.evalset.json --config_file_path tests/eval/eval_config.json
INFO - google_llm.py - Sending out request, model: gemini-flash-latest, backend: GoogleLLMVariant.VERTEX_AI
INFO - local_eval_set_results_manager.py - Writing eval result to file: app/.adk/eval_history/app_basic_eval_<ts>.evalset_result.json
Using evaluation criteria: criteria={'tool_trajectory_avg_score': 1.0, 'rubric_based_final_response_quality_v1': BaseCriterion(threshold=0.8, ...)}
*********************************************************************
Eval Run Summary
basic_eval:
  Tests passed: 3
  Tests failed: 0

Os resultados por caso são gravados em app/.adk/eval_history/. Cada arquivo de resultado lista as pontuações por métrica para que você possa ver exatamente qual verificação foi aprovada ou reprovada.

Como ler um arquivo de resultados

Um caso aprovado em app/.adk/eval_history/app_basic_eval_.evalset_result.json é assim:

{
  "eval_id": "weather_san_francisco",
  "final_eval_status": 1,
  "overall_eval_metric_results": [
    {"metric_name": "tool_trajectory_avg_score",            "score": 1.0, "threshold": 1.0, "eval_status": 1},
    {"metric_name": "rubric_based_final_response_quality_v1","score": 1.0, "threshold": 0.8, "eval_status": 1}
  ]
}

Se o agente tivesse alucinado e chamado a ferramenta errada (ou nenhuma ferramenta), tool_trajectory_avg_score cairia para 0.0 e o caso falharia, mesmo que o texto final parecesse plausível. Essa é a propriedade que só a rubrica não pode oferecer.

Outras métricas disponíveis

O ADK envia vários avaliadores integrados que podem ser adicionados a criteria:

Métrica

O que ele verifica

tool_trajectory_avg_score

Chamadas de ferramentas de correspondência exata em relação à trajetória esperada

rubric_based_final_response_quality_v1

LLM Judge em relação à sua rubrica (resposta final)

rubric_based_tool_use_quality_v1

LLM Judge de acordo com a rubrica (uso de ferramentas)

final_response_match_v2

Juiz de LLM: a resposta final é semanticamente equivalente à esperada?

response_match_score

ROUGE-1 entre a resposta final real e a esperada

safety_v1

LLM Judge: segurança da resposta

hallucinations_v1

Juiz de LLM: a resposta é embasada no contexto fornecido

9. Adicionar implantação do Agent Runtime

O Agent Runtime é o ambiente de execução gerenciado e sem servidor do Google Cloud para agentes do ADK. Ele lida com escalonamento, infraestrutura e observabilidade de forma automática.

🤖 Com um agente de programação

Pergunte ao agente:

"Adicionar a implantação do ambiente de execução do agente ao meu projeto"

👤 Modo manual

agents-cli scaffold enhance --deployment-target agent_runtime --yes

Resposta esperada:

Agents CLI v0.1.2
Resolved project root to: /home/user/customer-support-agent

Generating templates for comparison...
  - Original template...
  - Enhanced template...

Comparing files...

Will auto-update (unchanged by you):
  ✓ README.md
  ✓ app/app_utils/telemetry.py

Skipping (your code):
  - app/agent.py

Files to add:
  + app/agent_runtime_app.py
  + deployment_metadata.json
  + tests/integration/test_agent_runtime_app.py

Files to remove:
  - Dockerfile
  - app/fast_api_app.py
  - tests/integration/test_server_e2e.py

Dependency changes:
  + Add: google-cloud-aiplatform[evaluation,agent-engines]>=1.130.0
  + Add: protobuf>=6.31.1,<7.0.0

📦 Creating backup before modification...
Backup created: /home/user/.agents-cli/backups/customer-support-agent_20260430_001940

  Updated: 2 files
  Added: 3 files
  Removed: 3 files

✅ Enhance complete!

O que mudou?

Adicionado em:

  • app/agent_runtime_app.py: wrapper do ambiente de execução do agente
  • deployment_metadata.json: rastreamento de implantação
  • Testes específicos do Agent Runtime

Removido:

  • Dockerfile: não é necessário (o ambiente de execução do agente é gerenciado)
  • fast_api_app.py: substituído pelo app Agent Runtime

Preserved:

  • app/agent.py: seu código de agente (sem alterações)

10. Implantar no Agent Runtime

Implante seu agente na infraestrutura gerenciada do Google Cloud.

Atualizar dependências

uv lock

🤖 Com um agente de programação

Pergunte ao agente:

"Implante meu agente no ambiente de execução do agente no projeto YOUR_PROJECT_ID, região us-central1"

👤 Modo manual

agents-cli deploy --project YOUR_PROJECT_ID --region us-central1

Resposta esperada:

Using project root directory: /home/user/customer-support-agent
  📦 Auto-generated requirements: app/app_utils/.requirements.txt

    ╔═══════════════════════════════════════════════════════════╗
    ║                                                           ║
    ║   🤖 DEPLOYING AGENT TO VERTEX AI AGENT ENGINE 🤖         ║
    ║                                                           ║
    ╚═══════════════════════════════════════════════════════════╝

📋 Deployment Parameters:
  Project: YOUR_PROJECT_ID
  Location: us-central1
  Display Name: customer-support-agent
  Min Instances: 1
  Max Instances: 10
  CPU: 4
  Memory: 8Gi
  Container Concurrency: 9

🌍 Environment Variables:
  AGENT_VERSION: 0.1.0
  GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY: true
  GOOGLE_CLOUD_REGION: us-central1
  NUM_WORKERS: 1
  OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT: true

INFO:root:Introspecting app.agent_runtime_app.agent_runtime via subprocess

🚀 Creating agent: customer-support-agent (this can take 5-10 minutes)...
INFO:vertexai_genai.agentengines:Using agent framework: google-adk
   Operation: projects/.../locations/us-central1/reasoningEngines/.../operations/...

[... deployment in progress for ~5–10 minutes ...]

INFO:root:Agent Runtime ID written to deployment_metadata.json

✅ Deployment successful!
Agent Runtime ID: projects/.../locations/us-central1/reasoningEngines/XXXXXXXXXXXXXXXXXX
Service Account: service-XXXXXXXXX@gcp-sa-aiplatform-re.iam.gserviceaccount.com

📊 Open Console Playground: https://console.cloud.google.com/vertex-ai/agents/agent-engines/locations/us-central1/agent-engines/XXXXXXXXXXXXXXXXXX/playground?project=YOUR_PROJECT_ID

O que aconteceu?

Ambiente de execução do agente:

  • Empacotou seu código automaticamente
  • Enviado para o Google Cloud
  • Infraestrutura gerenciada provisionada (4 CPUs, 8 Gi de memória)
  • Escalonamento automático configurado (1 a 10 instâncias)
  • Telemetria e observabilidade ativadas

Tempo de implantação: 5 a 10 minutos (configuração única; as reimplantações subsequentes são mais rápidas)

11. Testar e monitorar o agente implantado

Seu agente agora está sendo executado no Agent Runtime. Vamos testar e conhecer o monitoramento integrado.

Teste seu agente

Opção 1: Console Playground (mais fácil)

A saída de agents-cli deploy imprime um link do Console Playground no formato:

https://console.cloud.google.com/vertex-ai/agents/agent-engines/locations/<REGION>/agent-engines/<RUNTIME_ID>/playground?project=<PROJECT_ID>

(O Agent Runtime é o nome do produto. O recurso do GCP subjacente é um Vertex AI Agent Engine. Por isso, o caminho do URL inclui vertex-ai/agents/agent-engines.) Clique no link para:

  1. fazer login no console do Google Cloud
  2. Conferir o agente implantado com uma interface de chat interativa
  3. Consultas de teste, como "Qual é a previsão do tempo em São Francisco?"
  4. Ver chamadas e respostas de ferramentas em tempo real

O Console Playground é a maneira mais fácil de verificar sua implantação.

Opção 2: agents-cli run –url

O mesmo comando agents-cli run usado localmente também consulta os agentes implantados:

RUNTIME_ID=$(jq -r .remote_agent_runtime_id deployment_metadata.json)
agents-cli run \
  --url "https://us-central1-aiplatform.googleapis.com/v1/${RUNTIME_ID}" \
  --mode adk \
  "What's the weather in San Francisco?"

O --mode adk fala o protocolo ADK SSE (o agente implantado expõe :streamQuery). O agents-cli anexa automaticamente um token de acesso do Google das suas credenciais ativas do gcloud.

Opção 3: SDK do Agent Engine (Python)

Para acesso programático em Python, use o módulo Agent Engine do SDK da Vertex AI (vertexai.agent_engines):

import vertexai
from vertexai import agent_engines

vertexai.init(project="YOUR_PROJECT_ID", location="us-central1")

# remote_agent_runtime_id from deployment_metadata.json (full resource name)
remote_agent = agent_engines.get(
    "projects/.../locations/us-central1/reasoningEngines/..."
)

session = remote_agent.create_session(user_id="user-1")
for event in remote_agent.stream_query(
    user_id="user-1",
    session_id=session["id"],
    message="What's the weather in San Francisco?",
):
    print(event)

Monitore seu agente

O Agent Runtime inclui observabilidade integrada pelas ferramentas de monitoramento do Google Cloud:

Cloud Trace: rastreamento de solicitações

  1. Acesse Console do Cloud > Explorador de rastreamentos.
  2. Selecionar o projeto
  3. Filtrar intervalos pelo atributo service.name = customer-support-agent
  4. Detalhar um rastreamento para ver a inferência do modelo, as chamadas de ferramentas e a latência de ponta a ponta

Cloud Logging: registros de aplicativos

  1. Acesse Console do Cloud > Explorador de registros.
  2. Usar consulta: resource.type="aiplatform.googleapis.com/ReasoningEngine"
  3. Adicionar resource.labels.reasoning_engine_id="" ao escopo deste agente
  4. Ver solicitações, respostas, execução de ferramentas e erros do agente

Cloud Monitoring: métricas e painéis

  1. Acesse Console do Cloud > Metrics Explorer.
  2. Filtrar por tipo de recurso aiplatform.googleapis.com/ReasoningEngine
  3. Métricas úteis: request_count, request_latencies, instance_count

12. Opcional: publicar no Gemini Enterprise

Disponibilize seu agente no Gemini Enterprise para sua organização.

🤖 Com um agente de programação

Pergunte ao agente:

"Publique meu agente no Gemini Enterprise"

👤 Modo manual

Liste os apps do Gemini Enterprise no seu projeto para ter um ID de app como destino:

agents-cli publish gemini-enterprise --list

Em seguida, registre o agente implantado. O comando lê automaticamente o ID do ambiente de execução do agente em deployment_metadata.json:

agents-cli publish gemini-enterprise \
  --gemini-enterprise-app-id "projects/PROJECT_NUMBER/locations/global/collections/default_collection/engines/YOUR_APP_ID" \
  --display-name "Customer Support Agent" \
  --description "Answers weather and time questions" \
  --tool-description "Use this tool to ask the customer support agent."

Isso disponibiliza seu agente:

  • No mercado de agentes do Gemini Enterprise
  • Para usuários na sua organização
  • Com gerenciamento e governança centralizados

Para mais detalhes, consulte a documentação de publicação.

13. Limpar

Para evitar cobranças, limpe os recursos criados.

Excluir o agente

Acesse o nome do recurso do ambiente de execução do agente em deployment_metadata.json:

jq -r .remote_agent_runtime_id deployment_metadata.json

Excluir usando o SDK do Agent Engine (Python)

import vertexai
from vertexai import agent_engines

vertexai.init(project="YOUR_PROJECT_ID", location="us-central1")

# Full resource name from deployment_metadata.json
remote_agent = agent_engines.get(
    "projects/.../locations/us-central1/reasoningEngines/..."
)

# force=True also deletes any child sessions
remote_agent.delete(force=True)
print("✅ Deleted successfully")

Ou pela API REST (curl):

RUNTIME_ID=$(jq -r .remote_agent_runtime_id deployment_metadata.json)
curl -X DELETE \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://us-central1-aiplatform.googleapis.com/v1beta1/${RUNTIME_ID}?force=true"

14. Parabéns!

🎉 Você conseguiu! Você criou, testou e implantou um agente de IA do zero.

O que você aprendeu

  • Duas maneiras de usar a CLI Agents (com um agente de programação ou manualmente)
  • Como criar projetos de agente com agents-cli scaffold
  • Como criar agentes com ferramentas personalizadas
  • Como testar localmente com o playground
  • Executar avaliações automatizadas
  • Implantação no Agent Runtime (infraestrutura gerenciada)
  • Monitoramento com o Cloud Trace e o Logging
  • Práticas recomendadas de produção

O que você criou

Um agente de IA pronto para produção com:

  • Processamento de linguagem natural (Gemini)
  • Integração de ferramentas personalizadas
  • Avaliações de qualidade
  • Implantação de escalonamento automático
  • Observabilidade integrada

Próximas etapas

Amplie seu agente:

  • Adicionar mais ferramentas (consultas de banco de dados, chamadas de API)
  • Implementar a RAG com a pesquisa vetorial
  • Adicionar conversas com vários turnos
  • Ativar a comunicação A2A (agente para agente)

Saiba mais:

Participe da comunidade: