Implantar um agente do ADK no Agent Runtime usando a CLI Agents

1. Visão geral

Este laboratório faz parte do curso 5-Day AI Agents: Intensive Vibe Coding Course with Google do Kaggle. Você pode encontrar outros codelabs e recursos disponíveis no site do evento.

Neste codelab, você vai fazer a transição de um agente do ADK 2.0 de um ambiente de desenvolvimento local para uma implantação de nível de produção. Você vai usar agents-cli para empacotar, verificar e hospedar seu fluxo de trabalho baseado em gráficos no Agent Runtime no Google Cloud.

Para conhecer esse processo de implantação, você vai criar um protótipo local do agente de despesas ambientais do zero antes de implantá-lo na nuvem. Para saber mais sobre como projetar a lógica principal desse agente, consulte os codelabs básicos no site do evento do Kaggle. O agente de despesas ambientais simplifica o relatório de despesas dos funcionários, aprovando instantaneamente as reivindicações padrão e sinalizando despesas maiores para revisão humana. Em segundo plano, ele usa um fluxo de trabalho baseado em gráficos do ADK 2.0 para coordenar essas aprovações automatizadas e etapas de análise de risco.

O que você vai aprender

• Como preparar seu projeto local do agente de despesas ambientais para hospedagem na nuvem.
• Como criar os descritores de implantação e wrappers de produção necessários.
• Como executar simulações e implantar seu código diretamente no Agent Runtime.
• Como monitorar os traces de execução do agente de produção usando o Cloud Trace.

O que é necessário

• Um projeto ativo do Google Cloud com o faturamento ativado.
• O SDK do gcloud instalado e autenticado.
• O gerenciador de pacotes uv instalado.
• O IDE do Google Antigravity instalado.

Pré-requisitos

Este codelab pressupõe que você esteja familiarizado com:

• Navegar no sistema usando um terminal.
• Conceitos básicos de desenvolvimento em Python.
• Conceitos básicos do Google Cloud.

2. Configurar o ambiente do Google Cloud

Antes da implantação, configure seu projeto na nuvem do Google Cloud e ative as APIs necessárias.

👉 Comando do Antigravity:

Help me set up my Google Cloud environment. Connect to my project
`YOUR_PROJECT_ID` in the global region, authenticate, and enable the necessary
generative platform APIs (aiplatform.googleapis.com, cloudtrace.googleapis.com,
cloudbuild.googleapis.com, agentregistry.googleapis.com).

Quando o Antigravity executa esse comando, ele propõe e executa os comandos de terminal gcloud necessários para configurar o projeto e ativar os serviços. Durante a etapa de autenticação, o Antigravity mostra um URL de autorização no terminal. Clique no link para fazer login pelo navegador da Web e conceder acesso. Depois de concluir o login do navegador, o Antigravity vai retomar a execução para definir as variáveis de ambiente do projeto e ativar as APIs necessárias.

Observação: se este for um novo projeto, o gcloud poderá solicitar que você ative a API Service Usage primeiro. Siga o link fornecido no terminal para ativá-lo no console do Cloud, se solicitado.

3. Configurar a CLI de agentes e as habilidades do ADK

Para que o Antigravity crie e implante agentes do ADK, ele precisa do conjunto de habilidades do ADK. Essas são referências agrupadas para a API do ADK, a estrutura do projeto, o fluxo de trabalho de implantação agents-cli e a avaliação. A instalação do conjunto de ferramentas agents-cli também instala essas habilidades no agente de programação, equipando-o para gerenciar todo o ciclo de vida do agente, desde o scaffolding local até a implantação na nuvem.

👉 Copie e cole o comando a seguir no Antigravity:

Install the agents-cli toolchain and its ADK skills so you can help me build
an ADK agent. Run "uvx google-agents-cli setup", then confirm with
"agents-cli info" and tell me which skills are now available.

Quando o Antigravity executa esse comando, ele executa uvx google-agents-cli setup no terminal para instalar a CLI e as habilidades complementares. Em seguida, ele executa agents-cli info para verificar a instalação e lista as habilidades de domínio recém-instaladas (como google-agents-cli-deploy e google-agents-cli-workflow) diretamente no chat.

Observação para usuários do Antigravity:durante este codelab, o Antigravity pode gerar planos de implementação ou mostrar pop-ups antes de executar comandos ou escrever código. Analise e aprove esses planos ou pop-ups para permitir que o Antigravity prossiga com as tarefas.

Dica de cota:se você ficar sem cota durante os testes ou o desenvolvimento, mude o modelo no Antigravity para outro disponível.

4. Criar o projeto do agente

Com o ambiente de nuvem configurado e as habilidades da CLI instaladas, você está pronto para gerar a base de código local do agente. Nesta etapa, você usa o Antigravity para criar um protótipo totalmente funcional do agente de despesas ambientais compatível com o ADK 2.0.

Observação para usuários do curso de 5 dias de agentes de IA do Kaggle: se você concluiu o codelab do agente de despesas ambientais do Vibecode para o dia 4 e prefere implantar sua base de código de agente personalizado, pule esta etapa de estrutura e acesse a próxima.

👉 Comando do Antigravity:

Use Agents CLI to build a local prototype for an ambient expense agent that
streamlines employee expense reporting by instantly approving standard claims
while flagging larger expenses for review. Ensure the graph workflow is
compatible with ADK 2.0 and includes an `auto_approve` node that automatically
approves expenses under $100, and a `review_agent` node that triggers a
human-in-the-loop pause (`RequestInput`) for expenses of $100 or more.

Quando o Antigravity executa esse comando, ele aproveita as habilidades de estrutura recém-instaladas para executar agents-cli scaffold create expense-agent --adk no terminal. Em seguida, ele verifica e ajusta o código do protótipo gerado para garantir que o expense-agent implemente corretamente o $100 limite de aprovação automática e o fluxo de revisão humana no fluxo de trabalho de gráfico do Kit de Desenvolvimento de Agente (ADK).

5. Preparar para a implantação de produção

O Agent Runtime é um serviço totalmente gerenciado do Google Cloud que permite implantar, gerenciar e dimensionar agentes de IA em produção. O Agent Runtime processa as complexidades operacionais da hospedagem, oferecendo um ambiente com estado e recursos como gerenciamento de sessões, memória de longo prazo e sandboxes de execução de código seguro.

Por que implantar no Agent Runtime?

Ao criar agentes localmente com o Antigravity, o agente é executado na máquina local em relação ao localhost. Embora seja ótimo para prototipagem rápida, os agentes locais param de ser executados no momento em que você fecha o laptop.

A implantação do agente no Agent Runtime move o fluxo de trabalho para um ambiente do Google Cloud totalmente gerenciado e sempre ativo. Isso estabelece um endpoint de back-end seguro e ativo que permanece ativo 24 horas por dia, 7 dias por semana. No próximo codelab, você criará uma interface web que se conecta diretamente a esse endpoint na nuvem, fornecendo ao seu agente uma URL pública.

Além disso, o Agent Runtime oferece uma infraestrutura dedicada otimizada especificamente para agentes de IA, oferecendo recursos integrados, como:

• Execução com estado gerenciado:gerenciamento de sessões integrado e persistência de memória de longo prazo em turnos de conversação.
• Sandbox seguro:executa com segurança chamadas de ferramentas dinâmicas e código gerado pelo agente em ambientes isolados.
• Observabilidade empresarial:telemetria pronta para uso transmitida diretamente para o Cloud Trace e o Cloud Logging.

Para hospedar o agente no Agent Runtime, é necessário melhorar o diretório do projeto local com descritores de produção, esquemas e wrappers de endpoint.

👉 Comando do Antigravity:

Scaffold the production deployment files for Agent Runtime.

Quando o Antigravity executa esse comando, ele executa agents-cli scaffold enhance --deployment-target agent_runtime --yes na raiz do projeto. Esse comando verifica o diretório e gera automaticamente:

• app/agent_runtime_app.py: o wrapper de serviço de nível de produção.
• deployment_metadata.json: o esquema de layout usado pelo Agent Runtime para criar recursos.

A lógica principal do agente em app/agent.py permanece completamente intacta e preservada.

6. Empacotamento e verificação local

Antes de iniciar um upload para a nuvem, bloqueie os pacotes e execute uma simulação local para identificar possíveis conflitos de dependência.

👉 Comando do Antigravity:

Lock my python dependencies and run a dry-run deployment to check for any
configuration or dependency issues.

Quando o Antigravity executa esse comando, ele primeiro executa uv lock no terminal para gerar um arquivo de bloqueio determinístico, garantindo versões de biblioteca consistentes na nuvem. Em seguida, ele executa agents-cli deploy --dry-run para verificar a validade da configuração e visualizar as etapas de implantação sem provisionar recursos de nuvem. Você pode revisar a saída da simulação no terminal para confirmar se todos os arquivos e configurações estão corretos.

7. Implantar no Agent Runtime

Implante o agente de despesas ambientais no Agent Runtime.

👉 Comando do Antigravity:

Deploy this agent to Agent Runtime.

Quando o Antigravity executa esse comando, ele ativa a habilidade google-agents-cli-deploy e executa agents-cli deploy --project YOUR_PROJECT_ID --region us-west1. O processo de empacotamento, upload e provisionamento do Agent Runtime geralmente leva de 5 a 10 minutos. O Antigravity vai monitorar o progresso da implantação no terminal e, quando concluído, vai mostrar o URL do endpoint ativo.

💡 Dica profissional (gerenciar janelas de tempo limite) : se você preferir não bloquear o terminal durante implantações longas, instrua o Antigravity a usar a flag --no-wait para iniciar a implantação de forma assíncrona e verificar o progresso mais tarde usando agents-cli deploy --status.

Se você tiver problemas para implantar o agente, use uma região diferente. A ferramenta de escolha de região do Google Cloud pode ajudar você a determinar a melhor região para seu projeto com base na latência, no preço e na pegada de carbono.

8. Testar o agente

Depois que o agente for implantado, você poderá verificar se ele aprova automaticamente pequenas despesas e sinaliza corretamente uma verificação humana para despesas maiores.

👉 Peça ao Antigravity para verificar o mecanismo implantado ativo:

Test my deployed Agent Runtime engine with two test cases: first a standard
meal expense of $50 to verify automatic approval, and second, a client dinner
expense of $150 to verify that the human-in-the-loop pause is triggered.

Observação:quando o Antigravity executa esse comando de teste no endpoint ativo, se ele encontrar erros de implantação ou execução, ele vai tentar depurar o problema automaticamente, aplicar as correções de código necessárias e reimplantar o agente para você.

Como alternativa, você pode testar o agente manualmente usando a visualização do Playground do console do Cloud. Para abrir o Playground:

1. No console do Google Cloud, use o menu de navegação para selecionar Agent Platform > Implantações.
2. Selecione o agente implantado na lista de implantações.
3. Clique no botão Playground para abrir a interface de chat de teste interativa.

👉 Para testar a aprovação automática(<$100), cole o seguinte payload JSON na caixa de chat:

{"data": {"amount": 50.0, "submitter": "[e-mail]", "category": "meals", "description": "Lunch", "date": "2026-06-04"}}

Você vai receber uma resposta JSON mostrando a saída do nó auto_approve com o status "aprovado".

👉 Para testar o fluxo humano no loop (HITL), cole o seguinte payload JSON.

{"data": {"amount": 150.0, "submitter": "[e-mail]", "category": "meals", "description": "Client dinner", "date": "2026-06-04"}}

Isso vai acionar o review_agent, emitir o alerta de aviso e pausar a execução, gerando um RequestInput (humano no loop) pedindo aprovação.

9. Monitorar e observar o agente de produção

Com o Agent Runtime, a telemetria é conectada automaticamente. Cada interação, chamada de modelo e execução de ferramenta transmite registros e intervalos em tempo real para o projeto.

1. Inspecionar traces: abra o console do Cloud Trace para auditar mapas de transações ativas, latências de modelos e etapas de execução de ferramentas.
2. Registros de auditoria: use o Cloud Logging para inspecionar a saída padrão em tempo real e os traces de pilha de diagnóstico.

3. Análise agregada: se a flag --bq-analytics foi ativada durante a estrutura, consulte os registros no BigQuery usando SQL para conferir as taxas de aprovação e as tendências de turnos de conversação.

A consulta SQL a seguir fornece um exemplo para calcular as taxas de aprovação. Você pode pedir ao Antigravity para personalizar essa consulta para seu projeto específico e conjunto de dados do BigQuery:

SELECT
  COUNTIF(REGEXP_CONTAINS(response_text, r'(?i)approved')) AS approved_count,
  COUNTIF(REGEXP_CONTAINS(response_text, r'(?i)rejected')) AS rejected_count,
  COUNT(1) AS total_processed,
  SAFE_DIVIDE(COUNTIF(REGEXP_CONTAINS(response_text, r'(?i)approved')), COUNT(1)) AS approval_ratio
FROM
  `[YOUR_PROJECT_ID].[YOUR_DATASET_ID].v_agent_response`
WHERE
  agent = 'expense_processor';

10. (Opcional) Verificar o registro no Agent Registry

Para permitir que outros serviços, desenvolvedores ou agentes da sua organização descubram e consumam seu agente de despesas com segurança, ele precisa ser registrado no Agent Registry empresarial (Gemini Enterprise).

Como você implantou o agente no Agent Runtime, ele é registrado automaticamente no Agent Registry. Todas as atualizações ou exclusões futuras do agente no Agent Runtime também serão sincronizadas automaticamente com o Agent Registry.

👉 Peça ao Antigravity para verificar o registro automático do agente:

Verify that my deployed expense agent is automatically registered in the Gemini
Enterprise Agent Registry.

Quando o Antigravity executa esse comando, ele executa agents-cli publish gemini-enterprise --list no terminal. Isso consulta o Agent Registry e lista todos os agentes do Gemini Enterprise registrados no projeto, permitindo que você confirme se o agente de despesas ambientais está ativo e detectável em toda a organização.

11. Limpar

Participantes do curso do Kaggle: se você estiver concluindo este laboratório como parte do curso 5-Day AI Agents do Kaggle e planeja continuar para o próximo laboratório (Vibecode e implantar um front-end para um agente do ADK) para criar o cliente de front-end e a integração do Pub/Sub, não exclua o agente implantado. Você vai precisar dessa infraestrutura em nuvem ativa para o próximo laboratório.

Para evitar cobranças contínuas na sua conta do Google Cloud, desligue e limpe os recursos implantados quando terminar.

👉 Comando do Antigravity:

Clean up all my deployed cloud resources. Use the Agent Runtime ID from
deployment_metadata.json to delete the engine from Vertex AI, remove the local
deployment_metadata.json file, and delete the container image repository from
Artifact Registry.

Quando o Antigravity executa esse comando, ele automatiza todo o processo de limpeza de recursos:

1. Excluir o agente implantado: ele lê deployment_metadata.json para receber o ID do Agent Runtime remoto e, em seguida, exclui programaticamente a instância do mecanismo ativo da Vertex AI.
2. Limpar o espaço de trabalho local: remove o arquivo deployment_metadata.json desatualizado da raiz do projeto.
3. Limpar o Artifact Registry: executa gcloud artifacts docker images delete para remover as imagens de contêiner criadas do Artifact Registry, liberando espaço de armazenamento na nuvem.

12. Parabéns

Parabéns! Você implantou e verificou um agente de despesas ambientais de nível de produção no Google Cloud.

O que você aprendeu

• Configuração do Google Cloud: configurou as credenciais do projeto e ativou as APIs da plataforma necessárias.
• Ferramentas e habilidades: instalou o agents-cli e carregou as habilidades complementares do ADK no Antigravity.
• Estrutura de produção: gerou a estrutura do Agent Runtime para um agente do ADK 2.0.
• Verificação local: criou arquivos de bloqueio determinísticos (uv lock) e executou verificações de simulação.
• Implantação na nuvem: hospedou o agente ao vivo na infraestrutura gerenciada do Agent Runtime.
• Observabilidade e análise: rastreou a execução no Cloud Trace e analisou a telemetria no BigQuery.
• Descoberta empresarial: verificou o registro automático no Agent Registry empresarial.

A seguir

• Realizar análises do BigQuery: consulte os registros de telemetria do agente no BigQuery para analisar as taxas de aprovação e as tendências de turnos de conversação ao longo do tempo.
• Codelab do Vibecode to Live: use o Google Antigravity para desenvolver um cliente de front-end no Cloud Run e conectá-lo diretamente ao endpoint de back-end do Agent Runtime ativo.

Ganhe o selo de agentes de IA de 5 dias do Kaggle 🎉

Concluiu este laboratório como parte do curso 5-Day AI Agents: Intensive Vibe Coding Course with Google do Kaggle? Resgate seu selo de conclusão:

Receber o selo de agentes de IA de 5 dias

Referências

• Documentação do Kit de Desenvolvimento de Agente (ADK)
• Ambientes de execução da plataforma de agentes do Gemini Enterprise
• Guia de referência da CLI de agentes (agents-cli)
• Visão geral do Agent Registry do Gemini Enterprise
• Documentação do Google Cloud Trace