Palestra de abertura para desenvolvedores do Next ‘26: depuração de agentes em grande escala

1. Introdução

Neste codelab, você vai aprender a depurar agentes de IA em execução no Google Cloud. Você vai implantar um agente simulador no tempo de execução do agente, usar o Cloud Observability para detectar problemas e usar o Gemini Cloud Assist e o Antigravity IDE para encontrar a causa raiz e corrigir erros em tempo real.

A premissa desta demonstração é que acabamos de adicionar ADK EventCompaction ao agente do simulador. Isso permite que o simulador resuma periodicamente o fluxo de trabalho usando o Gemini, reduzindo o contexto total enviado ao modelo a cada vez, o que melhora a qualidade da resposta e reduz os custos totais. Mas vamos descobrir que há um bug no nosso EventCompactionConfig, causando erros no agente. Este codelab mostra como encontrar esse tipo de problema e corrigi-lo rapidamente.

Atividades deste laboratório

• Implante o agente do simulador de maratona no Agent Runtime.
• Configure um alerta do Cloud Monitoring para detectar erros do agente.
• Investigue erros usando o Cloud Trace e o Gemini Cloud Assist.
• Identifique a causa raiz e corrija o agente usando o Antigravity e o MCP.

Observação: o Gemini Cloud Assist está em prévia particular. Não é necessário estar na lista de permissão para executar este codelab com o Cloud Assist. Todas as etapas do Cloud Assist estão isoladas em #8 (Opcional): use as investigações do Cloud Assist. Pule esta página se ainda não for possível acessar o Cloud Assist.

O que é necessário

• Um navegador da Web, como o Chrome.
• Uma Conta do Google
• Antigravity (compatível com Mac, Linux e Windows)
• Python 3.13+.
• uv (gerenciador de pacotes Python)

Duração estimada:45 minutos

Custo estimado:menos de US $5

2. Antes de começar

Criar um projeto do Google Cloud

1. No Console do Google Cloud, selecione ou crie um projeto na nuvem do Google Cloud.
2. Verifique se o faturamento está ativado para seu projeto do Cloud.

Configurar o ambiente

Abra o Antigravity e faça login. Em seguida, abra um Terminal pressionando cmd-shift-P (ou ctrl-shift-P) e digite "Create New Terminal".

1. No terminal, faça a autenticação com o Google Cloud:

gcloud auth login
gcloud auth application-default login

2. Defina o ID do projeto:

export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID
gcloud auth application-default set-quota-project $PROJECT_ID

Ativar APIs

Execute o comando a seguir para ativar as APIs do Cloud necessárias:

gcloud services enable \
 aiplatform.googleapis.com \
 logging.googleapis.com \
 apphub.googleapis.com \
 cloudtrace.googleapis.com \
 telemetry.googleapis.com

Se você estiver na lista de permissões do Gemini Cloud Assist (prévia particular), ative estas APIs extras:

gcloud services enable \
 geminicloudassist.googleapis.com \
 cloudaicompanion.googleapis.com

3. Configurar o agente do simulador

Nesta etapa, você vai clonar o repositório de demonstração e configurar as variáveis de ambiente do agente do simulador.

Clone o repositório

Clone o repositório next-26-keynotes e navegue até o diretório de demonstração:

git clone https://github.com/GoogleCloudPlatform/next-26-keynotes
cd next-26-keynotes/devkey/debugging-agents

Configurar variáveis de ambiente

O agente do simulador usa um arquivo .env para configuração.

Localize o arquivo sample.env no lado esquerdo da janela do Antigravity (Explorador):

Abra sample.env e atualize o campo GCP_PROJECT_ID com o ID do projeto do Google Cloud. O arquivo deve ser semelhante a este:

GCP_PROJECT_ID="YOUR_PROJECT_ID"
GCP_LOCATION="us-central1"
GOOGLE_GENAI_USE_VERTEXAI=TRUE
USE_VERTEXAI_SESSION_SERVICE=true
GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY=true
OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true
ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANS=false

Estamos ativando integrações do OpenTelemetry para capturar traces detalhados das chamadas de ferramentas e do fluxo de raciocínio do agente.

4. Implantar o agente do simulador no Agent Runtime

Agora, você vai implantar o agente no Agent Runtime usando o Kit de Desenvolvimento de Agente (ADK).

Instalar dependências

uv sync

Implantar no Agent Runtime

1. Execute o comando adk deploy. Esta etapa empacota e implanta seu agente no Google Cloud (tempo de execução do agente).

uv run adk deploy agent_engine \
    --project="$PROJECT_ID" \
    --region="us-central1" \
    --otel_to_cloud \
    --env_file="sample.env" \
    --adk_app_object=app \
    simulator_agent

Isso pode levar até 5 minutos. Você vai ver uma saída como esta:

✅ Created Agent Runtime:
projects/1234567890/locations/us-central1/reasoningEngines/9876543210...

Anote o ID do Agent Runtime gerado. Você vai precisar dele mais tarde.

2. Em um navegador da Web, abra o console do ambiente de execução do agente. Você vai ver o simulator_agent em execução no Agent Runtime, com a coleta de telemetria ativada.

5. Configurar uma política de alertas

Para detectar erros de tempo de execução do agente automaticamente, crie um alerta com base em registros no console do Google Cloud.

1. Navegue até o console Cloud Monitoring - Alertas.

2. Clique em Editar canais de notificação. Role a tela para baixo até o tipo E-mail e crie um canal de notificação por e-mail para enviar ao seu e-mail pessoal. Clique em Salvar.

3. Volte ao painel de alertas e clique em Criar política.
4. No lado direito da tela, clique em Criar alerta com base em registros.

5. Você será redirecionado para a Análise de registros. Cole a consulta de registro a seguir, substituindo pelo ID do projeto.

resource.type="aiplatform.googleapis.com/ReasoningEngine"
logName="projects/<YOUR_PROJECT_ID>/logs/aiplatform.googleapis.com%2Freasoning_engine_stderr"
"ERROR"

Essa consulta de registro procura registros de Erro no agente do ambiente de execução do agente, em que "ReasoningEngine" é o nome da API subjacente do ambiente de execução do agente.

6. Selecione Executar consulta. Nenhum registro vai aparecer ainda, isso é esperado.
7. Clique em Ações na barra de ferramentas de resultados e em Criar alerta de registro.

8. Configure o alerta baseado em registros. Dê um nome ao alerta (qualquer um) e defina o nível de gravidade como Erro.

9. Clique em Próxima para acessar a seção "Definir frequência de notificação" (mantenha os padrões).

10. Em Quem deve ser notificado?, defina o alerta para acionar o canal de notificação por e-mail que você acabou de configurar (por exemplo, My Email).
11. Clique em Salvar.

6. Acionar o incidente

Agora que o agente está implantado e monitorado, vamos tentar invocar a simulação de maratona de uma forma que gere um erro.

1. No console do Google Cloud, navegue até o console do tempo de execução do agente.
2. Clique em simulator_agent.
3. Na barra de ferramentas da parte de cima, clique em Playground. Isso vai iniciar uma nova sessão com o agente do ADK.

4. Na janela de chat da sessão, digite Test Simulation e pressione Enter para enviar o comando.

Isso vai iniciar a simulação da maratona, rastreando milhares de corredores simulados ao longo do percurso planejado. Você vai encontrar várias chamadas de ferramentas para get_runner_telemetry e analyze_medical_risk, já que a simulação avalia várias "zonas" da corrida.

Após alguns minutos, o agente para de ser executado e retorna nenhuma resposta.

5. Em cerca de um minuto, você vai receber um e-mail na sua caixa de entrada alertando sobre um novo incidente no agente.

Clique em Ver incidente para abrir o console do Cloud Monitoring. Acesse a próxima página para investigar o problema no console.

7. Investigar o incidente no console

1. Confira o incidente no console do Cloud Monitoring. Você vai ver registros de erros do agente do simulador.

É difícil ver, nessa visualização, exatamente em que ponto o agente falhou. Para conferir as chamadas de ferramentas e o fluxo de raciocínio do agente, vamos examinar os traces dele.

2. Abra o console do ambiente de execução do agente novamente. Clique em simulator_agent e abra a guia Rastreamentos.

3. Clique no trace mais recente na lista. Em seguida, no canto superior direito, clique em Linha do tempo. Você vai ver uma visualização de rastreamento com "intervalos" individuais. Um intervalo representa uma chamada de modelo ou ferramenta no fluxo de trabalho do agente.

4. Clique no último período na visualização de trace. Ele precisa ser vermelho.
5. Clique em Stacktrace. Você vai encontrar registros de erros relacionados a uma chamada de modelo da API Gemini. Especificamente, um erro 400: Invalid Argument. Isso indica um problema no nível da solicitação com um payload que o agente do simulador enviou à API Gemini.

8. [Opcional] Usar o Cloud Assist Investigations para depurar

Siga estas etapas apenas se você estiver na lista de permissão da prévia particular do Gemini Cloud Assist. Caso contrário, avance para a próxima página.

1. No período com falha, clique em Registros e eventos. Encontre o registro "Exception" com o botão de brilho ao lado. Em seguida, clique em Investigar registro.

2. Isso inicia uma investigação do Cloud Assist em uma barra lateral no lado direito da tela. Isso leva cerca de 3 a 5 minutos.

3. Depois de concluída, abra a investigação.

4. Confira o resumo da investigação.

5. Role a tela para baixo e confira as Hipóteses. O Gemini Cloud Assist deveria ter identificado a linha específica do arquivo agent.py do agente do simulador que está gerando o erro 400 da API Gemini.

Vamos abrir o código-fonte do nosso agente e usar o Antigravity para encontrar a causa raiz do problema. Siga para a próxima página.

9. Usar o Antigravity para identificar a causa raiz e corrigir o problema

1. Reabra o Antigravity.
2. Abra o Gerenciador de agentes no canto superior direito da tela.

3. Verifique se o modelo está definido como Gemini 3 Flash e no modo Planejamento.

4. Insira o seguinte comando e pressione Enter.

Why is the Simulator Agent failing to run in Agent Engine? 
We just added Events Compaction to the agent - could that be the cause? Search the ADK Python GitHub repository for relevant GitHub issues. https://github.com/google/adk-python/issues  - including issues that have been closed. 

For instance, you could query: is:issue eventscompactionconfig does not trigger summarization

Also look closely at the EventsCompactionConfig in agent.py.    

O Antigravity vai examinar o código em agent.py e pesquisar problemas relevantes no GitHub:

A causa principal do erro 400 da API Gemini é que estamos excedendo o limite de tokens de contexto de entrada do Gemini 3 Flash, que é de aproximadamente 1 milhão. Isso acontece porque não estamos acionando o EventCompaction com frequência suficiente para resumir de forma eficaz as respostas enormes das chamadas de função da ferramenta Agentes do simulador.

Para corrigir isso, o Antigravity precisa sugerir a adição de um parâmetro token_threshold ao EventsCompactionConfig para compactar periodicamente o contexto em cada invocação quando atingirmos um determinado número de tokens.

Isso está alinhado com a correção sugerida neste problema do GitHub.

Aplicar a correção a agent.py.

Valide se você vê algo semelhante a isto:

app = App(
    name="simulator_agent",
    root_agent=root_agent,
    events_compaction_config=EventsCompactionConfig(
        compaction_interval=3,
        overlap_size=1,
        summarizer=summarizer,
        token_threshold=200000,
        event_retention_size=2,
    ),
)

É importante definir token_threshold e event_retention_size.

10. Reimplantar e validar a correção

Agora que aplicamos a correção token_threshold ao EventCompactionConfig do agente do ADK, podemos reimplantar o agente do simulador no tempo de execução do agente.

1. Abra o Antigravity > Novo terminal.
2. Definir variáveis de ambiente. O AGENT_RUNTIME_ID precisa ser o nome do recurso completo do seu simulator_agent. Ele pode ser encontrado no console do ambiente de execução do agente, na lista de agentes.

export AGENT_RUNTIME_ID="projects/x/locations/us-central1/reasoningEngines/x"
export PROJECT_ID="your-project-id"

3. Implante o agente novamente:

uv run adk deploy agent_engine \
    --project="$PROJECT_ID" \
    --region="us-central1" \
    --otel_to_cloud \
    --agent_engine_id="$AGENT_RUNTIME_ID" \
    --env_file="sample.env" \
    --adk_app_object=app \
    simulator_agent

Esse processo levará alguns minutos. Se tudo der certo, você vai ver:

✅ Updated agent engine: projects/xxx/locations/us-central1/reasoningEngines/...
Cleaning up the temp folder: simulator_agent_tmp...

4. Abra o console do ambiente de execução do agente. Abra o simulator_agent novamente. Clique em Playground.
5. Insira o mesmo comando: Test Simulation e pressione Enter.
6. A simulação completa do backend do Marathon leva alguns minutos para ser executada. Várias chamadas de ferramentas vão aparecer. Você vai receber uma resposta como esta:

Isso indica que o simulador foi executado com sucesso. ✅

7. Abra a visualização de rastreamento dessa sessão do ADK.
8. Todos os intervalos "azuis" vão aparecer, sem erros em vermelho. Observe como a contagem total de tokens das sessões excede o limite de 1 milhão de tokens de contexto da API Gemini. Não tem problema, porque agora EventCompaction é executado com frequência suficiente em cada invocação para evitar o limite geral de contexto para chamadas de modelo individuais.

🎊 Viva! Corrigimos o erro no agente do simulador.

11. Limpar

Para evitar cobranças na sua conta do Google Cloud, exclua os recursos criados durante este codelab.

Excluir o app do Agent Runtime

É possível excluir a instância do Reasoning Engine pelo console ou usando o comando gcloud (se você tiver o nome do recurso). Para simplificar, use o console:

1. Acesse a página Agent Runtime.
2. Selecione simulator_agent –> clique no botão de três pontos no lado direito.
3. Clique em Excluir.

Excluir a política do Cloud Monitoring

1. Acesse o console do Cloud Monitoring -> Alertas.
2. Role a tela para baixo até Políticas e clique no botão de três pontos para Excluir a política.

12. 🎊 Parabéns!

Parabéns! Você acabou de depurar um agente de IA no Google Cloud.

O que você aprendeu

• Como implantar agentes no Agent Runtime.
• Como detectar erros usando alertas do Cloud Monitoring.
• Como analisar incidentes ativos usando o Cloud Logging e a visualização de rastreamento do tempo de execução do agente.
• Como investigar falhas usando o Gemini Cloud Assist.
• Como usar o Antigravity para identificar a causa raiz e corrigir bugs do agente.
• Como ajustar Compactação de eventos do ADK para processar turnos longos e pesados de ferramentas do agente.

Próximas etapas

• Saiba mais sobre o Agent Runtime.
• Saiba mais sobre o Kit de Desenvolvimento de Agente.
• Saiba mais sobre Alertas no Cloud Monitoring.
• Saiba mais sobre o Gemini Cloud Assist.