Avaliação automática de código com o sandbox do agente no GKE

1. Introdução

Neste codelab, você vai implantar o aplicativo Hackathon Judge no Google Kubernetes Engine (GKE) e usar o Kubernetes-sigs Agent Sandbox para executar cargas de trabalho de agentes com segurança.

A plataforma foi projetada para automatizar o processo de revisão, teste e classificação de projetos de hackathon usando agentes de LLM. Como a avaliação exige a análise de envios de código de participantes não confiáveis, um sandbox de execução segura é essencial para evitar injeção de código, escalonamento de privilégios ou abuso de recursos.

Atividades deste laboratório

  • Provisione os serviços de destino do Google Cloud e estabeleça as APIs de destino.
  • Inicialize o GKE Autopilot e instale os CRDs do Agent Sandbox, as configurações do cluster e o Sandbox Router.
  • Implante o gateway de sandbox, o modelo de reivindicação de sandbox e um WarmPool de sandbox.
  • Implante a API REST Backend, o agente de trabalho de julgamento do ADK e a interface do front-end do React.
  • Conecte o roteamento balanceado por carga externo e acesse a plataforma para executar fluxos de trabalho de avaliação seguros e em sandbox.

O que é necessário

  • Um navegador da Web, como o Chrome.
  • Ter um projeto do Google Cloud com o faturamento ativado.

Os recursos criados neste codelab custam menos de US $5 em cobranças totais de tempo de execução.

2. O problema: avaliar com segurança um código não confiável

Os hackathons são eventos de inovação rápidos em que os participantes criam e enviam projetos, muitas vezes incluindo código-fonte, para avaliação. Julgar manualmente esses envios leva muito tempo e exige muitos recursos. Usar agentes de IA para automatizar a avaliação é uma solução promissora, mas apresenta um desafio de segurança significativo: como executar com segurança um código fornecido pelo participante que pode ter bugs, ser mal-intencionado ou exigir muitos recursos?

Executar código não confiável diretamente na sua infraestrutura expõe você a riscos como:

  • Injeção de código: scripts maliciosos podem tentar acessar ou modificar dados sensíveis.
  • Escalonamento de privilégios: o código pode tentar obter acesso não autorizado a outros sistemas ou recursos de rede.
  • Abuso de recursos: código mal escrito ou ataques de negação de serviço podem consumir CPU, memória ou largura de banda de rede em excesso, afetando outras operações.

Para automatizar a avaliação de um hackathon com IA, precisamos de uma maneira de executar o código enviado em um ambiente completamente isolado do restante do nosso sistema e de outros envios.

3. A solução: GKE Agent Sandbox

O GKE Agent Sandbox é um recurso criado para esse desafio. Ele ajuda a gerenciar cargas de trabalho isoladas, com estado e de réplica única no GKE e é otimizado para casos de uso como tempos de execução de agentes de IA, em que o código não confiável precisa ser executado com segurança e eficiência.

Os principais benefícios do Agent Sandbox incluem:

  • Isolamento no nível do kernel: oferece isolamento forte no nível do kernel para código não confiável usando tecnologias como o gVisor, impedindo que o código acesse o sistema host ou outros contêineres.
  • Provisionamento em menos de um segundo: oferece provisionamento rápido de ambientes de sandbox (normalmente <1s), o que é fundamental para a avaliação de código sob demanda.
  • Extensibilidade nativa da nuvem: aproveita o poder do Kubernetes e a infraestrutura gerenciada do GKE.

Com o Agent Sandbox, podemos criar ambientes isolados e sob demanda para cada envio de hackathon. Em seguida, o agente de avaliação de IA pode instruir o sandbox de agente a executar testes, compilar código ou realizar outras etapas de avaliação nesse sandbox seguro sem arriscar a integridade da plataforma geral. Isso oferece uma maneira escalonável, segura e eficiente de automatizar a avaliação de hackathons.

4. Antes de começar

Iniciar o Cloud Shell

Clique no botão abaixo para iniciar o Google Cloud Shell, que vem pré-configurado com os utilitários de linha de comando de desenvolvedor e de nuvem necessários.

Ativar APIs

Execute o comando a seguir no Cloud Shell para ativar todas as APIs do Cloud necessárias para executar a plataforma:

gcloud services enable \
  container.googleapis.com \
  artifactregistry.googleapis.com \
  cloudbuild.googleapis.com \
  pubsub.googleapis.com \
  aiplatform.googleapis.com \
  cloudresourcemanager.googleapis.com \
  iam.googleapis.com \
  bigquery.googleapis.com \
  bigqueryconnection.googleapis.com

Por que ativamos essas APIs:os serviços do Google Cloud são desativados por padrão para evitar acesso e cobranças indevidas. Ativamos essas APIs específicas para ativar a orquestração de contêineres (GKE), o armazenamento seguro de contêineres (Artifact Registry), o empacotamento de build sem servidor (Cloud Build), as filas de mensagens confiáveis (Pub/Sub), os serviços de modelos de IA (Vertex AI), a configuração de projetos (Cloud Resource Manager e IAM), a análise de dados sem servidor (BigQuery) e as vinculações de IA no nível do banco de dados (conexão do BigQuery).

5. Configurar a infraestrutura

Nesta etapa, você vai clonar o repositório de código e executar o script de configuração automatizada para implantar a arquitetura de nuvem de destino e os componentes do cluster de referência.

Clone o repositório

Clone o repositório que contém todos os serviços de aplicativos, scripts de configuração e declarações de manifesto do Kubernetes:

git clone --depth 1 --filter=blob:none --sparse https://github.com/GoogleCloudPlatform/devrel-demos.git
cd devrel-demos
git sparse-checkout set codelabs/ai-toolkit-lab-2/hackathon-judge
cd codelabs/ai-toolkit-lab-2/hackathon-judge

Executar script de implantação

A configuração básica dos recursos de nuvem, modelos de banco de dados e políticas de cluster do Kubernetes de referência é automatizada pelo script deploy.sh.

Execute o script:

./deploy.sh

Siga as solicitações do shell interativo para fornecer configurações como o ID do projeto ativo e a região de destino. O script gera automaticamente uma configuração .env local, vincula recursos, compila imagens de contêiner e registra a infraestrutura de referência do GKE.

Estas são as operações de destino realizadas pelo script:

1. Configuração do ambiente

O script cria um arquivo de configuração .env para armazenar parâmetros de variáveis do GKE, Pub/Sub, BigQuery e do projeto. A origem desse arquivo preenche dinamicamente todas as definições de manifesto do Kubernetes subsequentes.

Por que configuramos esse arquivo de ambiente:o arquivo .env centraliza os parâmetros de configuração, garantindo que os manifestos do GKE que aplicamos manualmente nas etapas subsequentes usem configurações regionais, nomes de projetos e recursos idênticos, separando estritamente a configuração ambiental do código-fonte.

2. Configuração da CLI do Google Cloud e do projeto de destino

O script verifica se os utilitários gcloud, bq, kubectl e envsubst estão instalados, confere o estado de autenticação e bloqueia os destinos de configuração ativos no seu projeto na nuvem do Google Cloud.

Por que segmentamos o projeto ativo:definir o projeto de destino ativo impede que os comandos da CLI afetem outros projetos na sua conta e realiza verificações de autenticação pré-voo, garantindo que os comandos de configuração não falhem no meio da implantação devido a credenciais inválidas.

3. Como ativar as APIs do Cloud de destino do Google Cloud

O script realiza uma verificação idempotente para verificar e ativar as APIs de serviço do Google Cloud de destino (GKE, Artifact Registry, Cloud Build, Pub/Sub, Vertex AI, BigQuery e IAM).

Por que ativamos as APIs do Google Cloud:os serviços gerenciados na nuvem precisam ser ativados antes que os endpoints possam ser acessados ou que os recursos possam ser criados. A ativação no início prepara o gateway de API regional do GCP para processar comandos de provisionamento de recursos subsequentes.

4. Provisionamento do repositório do Docker no Artifact Registry

O script provisiona um repositório de contêineres Docker chamado hackathon-judge-repo no local de destino selecionado.

Por que criamos um repositório do Artifact Registry:os clusters do GKE exigem acesso seguro a registros de contêineres particulares na mesma rede regional para extrair imagens de aplicativos rapidamente. O Artifact Registry oferece um host seguro e particular para catalogar, verificar e armazenar imagens de contêiner do Docker.

5. Provisionamento do cluster do GKE Autopilot

O script provisiona um cluster do Autopilot do Google Kubernetes Engine (GKE) chamado hackathon-judge-cluster.

Por que implantamos um cluster do GKE Autopilot:o GKE Autopilot gerencia automaticamente o provisionamento, o escalonamento, o monitoramento de integridade e os upgrades de segurança do SO do host. Ela oferece uma plataforma de contêineres de nível de produção para orquestrar nossos serviços permanentes e agenda dinamicamente sandboxes de trabalho seguros sob demanda.

6. Configurar tópicos e assinaturas do Pub/Sub

O script provisiona os tópicos de mensagens (judging-tasks e judging-results) com as assinaturas correspondentes de worker e API.

Por que implantamos tópicos e assinaturas do Pub/Sub:avaliar envios de código é um processo lento e que exige muitos recursos. Usar uma arquitetura de fila de mensagens desacopla a API síncrona voltada ao usuário dos nós de worker. O back-end da API envia jobs para o tópico judging-tasks, e os agentes de worker extraem tarefas à medida que elas ficam disponíveis, evitando o bloqueio da API e oferecendo recursos de nova tentativa automática.

7. Configurar conjuntos de dados, tabelas e conexões de IA do BigQuery

O script cria o conjunto de dados hackathon_judge, aplica esquemas estruturais de banco de dados SQL, carrega registros de inicialização e concede as funções necessárias de IA e armazenamento à conta de serviço de conexão do BigQuery ML.

8. Como acionar builds de contêineres usando o Cloud Build

O script aciona a definição cloudbuild.yaml para compilar nossa interface do React, o servidor Go REST, o worker do ADK Python e o sandbox do FastAPI, empacotando-os em imagens de contêiner isoladas marcadas com o SHA de commit do Git do repositório ativo e salvando-as no Artifact Registry.

9. Registrar definições de recursos personalizados (CRDs) do sandbox do agente

O script baixa e registra as mais recentes definições de recursos personalizados (CRDs, na sigla em inglês) do sandbox do agente do Kubernetes-sigs (manifest.yaml e extensions.yaml) para estender os recursos principais do GKE.

Por que instalamos a infraestrutura do Agent Sandbox:os clusters padrão do Kubernetes não têm suporte para alocar sandboxes protegidos sob demanda. O registro de CRDs do Agent Sandbox estende o plano de controle do GKE, permitindo que o Kubernetes orquestre nativamente microrrecipientes em sandbox seguros usando recursos personalizados (como SandboxTemplates e SandboxClaims).

10. Configurar namespaces, contas de serviço e Identidade da carga de trabalho

O script provisiona o namespace hackathon-judge, registra contas de serviço do Kubernetes (KSAs) e estabelece mapeamentos de Identidade da carga de trabalho para conceder aos pods do GKE permissões de destino do Google Cloud.

11. Como implantar o roteador do sandbox

O script aplica o manifesto k8s/sandbox_router.yaml, iniciando a implantação e o serviço do roteador de sandbox e aguardando que eles atinjam um status íntegro.

Por que implantamos o roteador de sandbox:o roteador de sandbox é o gateway central interno do plano de controle. Ele expõe uma API simples que o agente de trabalho de julgamento do ADK chama para reivindicar, acessar ou liberar sandboxes seguros, gerenciando mapeamentos de roteamento e abstraindo a alocação de pods no nível do cluster da lógica do aplicativo.

6. Configurar o gateway, as declarações e o WarmPool do sandbox do agente

Nesta etapa, você vai configurar manualmente o gateway de rede especializado do Sandbox, registrar o modelo de reivindicação do Sandbox e implantar o WarmPool do Sandbox para ativar o sandbox de latência ultrabaixa.

Variáveis de ambiente de origem

Antes de aplicar modelos que exigem variáveis de ambiente, execute o script setup-env.sh para analisar e exportar todas as variáveis necessárias para o shell:

source ./setup-env.sh

Aplicar o gateway do sandbox

Implante o gateway especificamente configurado para rotear o tráfego do sandbox:

kubectl apply -f k8s/sandbox-gateway.yaml

Por que implantamos o Sandbox Gateway:ele atua como o controlador de entrada seguro e de alta performance dedicado exclusivamente ao roteamento de sandbox. Ela isola a rede do sandbox, fornecendo um destino local seguro que permite que os agentes de worker se comuniquem com os sandboxes reivindicados sem expor endpoints externamente.

Aplicar modelo de reivindicação de sandbox

Use envsubst para preencher a definição do modelo de sandbox com suas variáveis de ambiente ativas e aplique-o:

source ./setup-env.sh
envsubst < k8s/sandbox-claim-template.yaml | kubectl apply -f -

Por que implantamos o modelo de reivindicação da sandbox:o modelo de reivindicação da sandbox funciona como a configuração do blueprint que define o ambiente. Ele especifica a imagem do contêiner a ser executada (pré-empacotada com ferramentas de desenvolvedor), parâmetros de ambiente (ID do projeto do GCP), portas e limites de recursos (metas de CPU/memória). Ele configura o GKE para executar essas instâncias de contêiner usando o gVisor (tempo de execução do gvisor), garantindo que o código de participantes não confiáveis seja executado em uma camada extra de isolamento de virtualização do kernel.

Aplicar WarmPool do sandbox

Aplique o Sandbox WarmPool para pré-inicializar os sandboxes em execução:

kubectl apply -f k8s/sandbox-warmpool.yaml

Verifique se as instâncias de espera do pool quente foram iniciadas:

kubectl get pods -n hackathon-judge -l app=sandbox

Por que implantamos o WarmPool do Sandbox:o provisionamento, o agendamento, a extração de imagens e a inicialização de novos pods de contêiner sob demanda introduzem uma sobrecarga de inicialização substancial (tempos de inicialização a frio de mais de 30 segundos). O Sandbox WarmPool mantém um pool de espera de pods de sandbox ativos e pré-aquecidos (cinco réplicas por padrão). Quando o agente de trabalho solicita um ambiente de avaliação, o roteador da sandbox aloca imediatamente um pod pré-aquecido em execução, reduzindo os atrasos de inicialização para velocidades inferiores a um segundo.

7. Implantar componentes de aplicativos

Com a infraestrutura de sandbox segura totalmente ativa, agora você vai implantar a API de back-end central, o agente de trabalho, a interface da Web React e o mapeamento do gateway de entrada.

Implantar back-end

Implante o back-end da API REST do orquestrador:

source ./setup-env.sh
envsubst < k8s/backend.yaml | kubectl apply -f -

Implantar agente

Implante o agente de worker de avaliação do ADK:

source ./setup-env.sh
envsubst < k8s/agent.yaml | kubectl apply -f -

Implante o front-end

Implante a interface interativa do usuário da Web:

source ./setup-env.sh
envsubst < k8s/frontend.yaml | kubectl apply -f -

Configurar o gateway e o roteamento externos

Implante o gateway principal e as rotas HTTP de entrada que mapeiam o tráfego de clientes externos:

kubectl apply -f k8s/gateway.yaml

Por que implantamos o gateway de entrada externa:o gateway externo expõe nossos serviços usando a API Kubernetes Gateway. Ele provisiona um endereço IP público com balanceamento de carga e mapeia rotas com base em regras de caminho, direcionando solicitações de API em /api/* para o back-end do Go e mapeando todo o outro tráfego da Web do cliente (/) para o front-end do React, protegendo o acesso público ao cluster.

Verificar lançamentos

Bloqueie a execução do shell e aguarde até que todas as três implantações de serviços principais atinjam um status de lançamento íntegro e pronto:

kubectl rollout status deployment/backend -n hackathon-judge --timeout=300s
kubectl rollout status deployment/agent -n hackathon-judge --timeout=300s
kubectl rollout status deployment/frontend -n hackathon-judge --timeout=300s

8. Verificar e usar o aplicativo

Acessar a IU

Extraia o endereço IP público externo do gateway do balanceador de carga principal recém-provisionado:

Para acompanhar o status do provisionamento em tempo real, execute o comando com a flag de observação (-w) e aguarde até que um endereço IP público seja preenchido no campo ADDRESS:

kubectl get gateway -n hackathon-judge hackathon-judge-gateway -w

Quando o provisionamento for concluído, você vai ver uma saída semelhante a esta:

NAME                      CLASS    ADDRESS          PROGRAMMED   AGE
hackathon-judge-gateway   gke-l7   34.120.120.120   True         3m

Quando um endereço IP público válido aparecer na coluna ADDRESS e o status PROGRAMMED for True, pressione Ctrl+C para interromper a observação.

Por que recebemos o status do gateway:a API Gateway processa a entrada pública. A verificação do status do gateway retorna o endereço IP externo público e balanceado por carga alocado pelo balanceador de carga global externo do Google Cloud ao nosso cluster, que representa o endereço público da nossa plataforma.

Abra o endereço IP público alocado no navegador para carregar o painel do juiz do Hackathon.

Enviar tarefas

  • Use a interface de front-end para navegar até o painel e selecione a hackathon.

Painel

  • Em qualquer um dos projetos, clique em Run Agent para iniciar a avaliação do projeto inteiro pelo agente de acordo com a rubrica.

Projetos

Assista o início do Sandbox

Monitore os pods ativos no namespace hackathon-judge para ver um pod de sandbox reivindicado e provisionado dinamicamente para execução de julgamento:

kubectl get pods -n hackathon-judge -w

Confira os registros do pod do agente de worker para acompanhar a lógica de avaliação do ADK etapa por etapa:

kubectl logs -l app=agent -n hackathon-judge

Por que inspecionamos os registros do agente:a inspeção dos registros do agente do worker mostra as etapas internas detalhadas do pipeline de avaliação em tempo real. É possível rastrear o agente do ADK buscando a tarefa, solicitando um contêiner de sandbox, executando destinos de compilação, analisando relatórios com o Gemini e publicando quadros de visão geral.

9. (Opcional) Como funciona

Arquitetura da sandbox do agente

Embora as funções de IA do BigQuery sejam incríveis para avaliar envios baseados em texto e declarações de README, julgar um projeto de engenharia exige compilar código, instalar bibliotecas de terceiros e executar conjuntos de testes reais.

A execução de código de usuário bruto apresenta riscos de segurança enormes, incluindo comprometimento do host, invasões de contêineres e acesso não autorizado a recursos. A estrutura do GKE Agent Sandbox mitiga esses riscos ao orquestrar cargas de trabalho isoladas do sandbox usando a virtualização do gVisor (runsc).

Fluxo de interação do sistema

O diagrama abaixo mostra como os vários elementos do nosso sistema orientado a eventos se comunicam durante uma execução de avaliação segura em sandbox:

Como as ferramentas e os componentes engajados funcionam juntos

  • Interface de front-end do React: expõe uma interface interativa em que os usuários configuram modelos de critérios, registram equipes, enviam URLs de projetos e analisam os quadros de pontuação finalizados, incluindo discrepâncias completas de arquivos e comentários de engenharia.
  • API de back-end REST em Go: gerencia endpoints globais de API. Ele armazena configurações de projeto no BigQuery e envia jobs de avaliação para o Pub/Sub para separar pipelines de execução computacional pesados.
  • Google Pub/Sub: o agente orientado a mensagens que mantém as mensagens de tarefas em fila com segurança, orquestrando a comunicação de forma assíncrona entre a API e as instâncias de worker ativas.
  • Worker do ADK do Python (agente supervisor): um worker em segundo plano que extrai tarefas do Pub/Sub. Ele usa o Kit de Desenvolvimento de Agente (ADK) do Google para iniciar um agente supervisor de alto nível, que é instruído a orquestrar a avaliação. O supervisor invoca a ferramenta principal, evaluate_repository, para delegar testes de comando brutos profundos.
  • Roteador e gateway do Sandbox (plano de controle do GKE): um gateway de controle interno que registra definições de recursos personalizados (CRDs, na sigla em inglês) padrão do Sandbox (SandboxClaims, SandboxTemplates). Ele coordena as redes do GKE para alocar e proteger pods, retornando fluxos de conexão aos clientes de trabalho.
  • Sandbox WarmPool: para evitar longos tempos de inicialização de contêineres do GKE ("inicializações a frio" de mais de 30 segundos), o WarmPool mantém pods de espera ativos. Quando uma sandbox é reivindicada, o roteador a mapeia imediatamente em menos de um segundo e programa a reciclagem após a liberação.
  • Isolamento do gVisor (runsc): um kernel virtual do espaço do usuário que atua como um limite de sandbox seguro. Ele intercepta chamadas de sistema do espaço do contêiner para kernels de nós do GKE, garantindo que comandos brutos perigosos (como scripts de sistema ou configurações de pacotes) sejam executados em isolamento absoluto de virtualização.
  • Tempo de execução do sandbox do FastAPI: um servidor de API Python leve em execução no contêiner do sandbox. Ele expõe endpoints seguros (/execute, /upload, /download) que permitem que ferramentas de trabalho externas manipulem arquivos e acionem tarefas de shell.
  • CLI do Gemini (@google/gemini-cli): um script de agente autônomo instalado na caixa de areia. Quando acionado com a flag de ambiente de desenvolvimento (--yolo), ele usa uma planilha de instruções de classificação rigorosa (prompt.md) e uma definição de critérios (criteria.md) para:
    • Analise dinamicamente a hierarquia da base de código usando ferramentas como tree ou ripgrep.
    • Instalar requisitos automaticamente (com comandos como npm install, pip install, go build).
    • Execute testes de desenvolvimento reais (como npm test ou pytest) para verificar a funcionalidade.
    • Chame os modelos da Vertex AI (usando as credenciais de vinculação da identidade da carga de trabalho do contêiner) para avaliar a lógica do arquivo, fazer uma verificação cruzada das declarações em relação ao README, detectar recursos fantasmas, registrar problemas de qualidade e escrever um relatório estruturado de scorecard para evaluation.json.
  • Ambientes de desenvolvimento padrão: agrupam node, npm, yarn, pnpm, python, pip, uv, go, gh, git, tree, ripgrep e playwright na imagem do contêiner da sandbox, oferecendo ao subagente autônomo um espaço de trabalho de teste completo.

10. Limpeza

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

./destroy.sh

Por que limpamos os recursos:o Google Cloud cobra com base em um modelo de utilização de recursos. Recursos ativos, como clusters do GKE Autopilot, balanceadores de carga de rede e discos permanentes, geram cobranças contínuas, mesmo quando estão inativos. A execução desta etapa exclui o namespace do cluster para limpar os objetos do Kubernetes e exclui o próprio host do cluster do GKE Autopilot para encerrar imediatamente todas as cobranças de faturamento subjacentes.

11. Parabéns

Parabéns! Você implantou o aplicativo Hackathon Judge com o sandbox do agente no GKE.

Você implementou uma plataforma de IA moderna e segura orientada a eventos capaz de testar e avaliar envios de bases de código não confiáveis em restrições de segurança isoladas e em contêineres.

O que você aprendeu

  • Infraestrutura do GKE: como provisionar o GKE Autopilot e serviços compatíveis do Google Cloud, como Pub/Sub e BigQuery.
  • Configuração do Sandbox do agente: como configurar definições de recursos personalizados, SandboxTemplates, SandboxClaims e WarmPools de alta performance do Sandbox.
  • Implantação de microsserviços: como configurar vinculações de identidade da carga de trabalho e implantar uma arquitetura de microsserviços de vários componentes (Frontend React, REST Go, Worker ADK Agent e Isolated Sandbox).
  • Sandbox seguro: como usar contêineres virtualizados do gVisor para executar comandos de terceiros não confiáveis com segurança em nós do GKE.

Próximas etapas

Documentos de referência