Como entregar uma aplicação com agentes de IA no Google Cloud (GCP) usando gates de evidência

Caso de uso sanitizado

Um produto conversacional com fronteira de compilação protegida#

Considere uma aplicação conversacional em produção com superfície web pública, uma interface de programação de aplicações (API) apoiada por modelo, ferramentas externas e pesquisa privada no mesmo repositório de desenvolvimento. O primeiro risco da implantação (deploy) não é o modelo — é empacotar acidentalmente o que nunca deveria ser público.

O contexto de compilação começa com negação por padrão e um manifesto exato revisado. O contêiner recebe apenas arquivos necessários em execução; pesquisa, relatórios, scripts, credenciais e conteúdo pago ficam fora.

Depois que a fronteira de compilação exclui o material protegido, o fluxo de entrega pode acompanhar a mesma versão candidata da fonte ao tráfego.

Fluxo de entrega

Cinco fronteiras de evidência da alteração versionada (commit) ao tráfego#

Cada fronteira prova um fato e deixa aberta a próxima decisão. Mantenha a identidade do artefato enquanto as evidências avançam.

Um registro compacto de lançamento conecta as cinco fronteiras sem copiar conteúdo sensível.

Registro reutilizável de lançamento

Conecte artefato, revisão, decisão e resposta a incidentes#

Um registro compacto conecta o que foi construído, o que foi testado, quem decidiu e para onde o tráfego pode voltar. Guarde referências e vereditos em vez de copiar prompts ou respostas sensíveis para o registro de lançamento.

Os campos abaixo formam um contrato mínimo de trabalho, não uma exigência do provedor. Acrescente invariantes e regras de retenção do produto sem transformar o registro em um depósito de dados impossível de revisar.

steps:
  - name: gcr.io/cloud-builders/docker
    args: [build, -t, "${_IMAGE_URI}", .]
  - name: gcr.io/cloud-builders/docker
    args: [push, "${_IMAGE_URI}"]
  - name: gcr.io/google.com/cloudsdktool/cloud-sdk:slim
    entrypoint: gcloud
    args:
      - run
      - deploy
      - "${_SERVICE}"
      - --image
      - "${_IMAGE_URI}"
      - --region
      - "${_REGION}"
      - --no-traffic
      - --tag
      - candidate
      - --quiet
options:
  logging: CLOUD_LOGGING_ONLY

#!/usr/bin/env bash
set -euo pipefail

: "${SERVICE:?set SERVICE}"
: "${REGION:?set REGION}"
: "${PROJECT:?set PROJECT}"
: "${ACCOUNT:?set ACCOUNT}"
: "${CANDIDATE_URL:?set CANDIDATE_URL}"
: "${CANDIDATE_REVISION:?set CANDIDATE_REVISION}"
: "${PREVIOUS_REVISION:?set PREVIOUS_REVISION}"

rollback() {
  gcloud run services update-traffic "$SERVICE" \
    --region "$REGION" \
    --project "$PROJECT" \
    --account "$ACCOUNT" \
    --to-revisions "$PREVIOUS_REVISION=100" \
    --quiet
}
trap rollback ERR

probe() {
  local url="$1"
  local -a auth_header=()
  if [[ -n "${CANDIDATE_ID_TOKEN:-}" ]]; then
    auth_header=(-H "Authorization: Bearer $CANDIDATE_ID_TOKEN")
  fi
  curl --fail --silent --show-error "${auth_header[@]}" "$url"
}

# Set CANDIDATE_ID_TOKEN for an IAM-protected revision. Leave it unset only
# when these candidate endpoints are intentionally public.
probe "$CANDIDATE_URL/health"
probe "$CANDIDATE_URL/critical-journey"

gcloud run services update-traffic "$SERVICE" \
  --region "$REGION" \
  --project "$PROJECT" \
  --account "$ACCOUNT" \
  --to-revisions "$CANDIDATE_REVISION=100" \
  --quiet

trap - ERR

{
  "artifact": "image@sha256:<digest>",
  "candidate_revision": "service-00042-abc",
  "previous_revision": "service-00041-xyz",
  "evidence_uri": "<immutable-evidence-reference>",
  "verdict": "PROMOTE",
  "rollback_target": "service-00041-xyz"
}

O registro identifica o que pode ser promovido; identidades de serviço e tratamento de segredos limitam o que a candidata pode acessar.

Identidade e segredos

Mantenha credenciais fora da fonte e do artefato#

Use identidades de serviço dedicadas com o mínimo de papéis necessários para compilação, registro e execução. Guarde segredos no Secret Manager e vincule-os em tempo de execução; não grave valores na imagem nem nos registros da compilação.

Separe a autoridade humana de publicação da identidade usada em execução. Uma aplicação capaz de chamar um modelo não precisa modificar a própria infraestrutura.

Com o acesso delimitado, os testes de prontidão podem exercitar a revisão exata, ainda sem tráfego, que poderá ser promovida.

Prontidão sem tráfego

Teste a revisão que será promovida#

Uma implantação bem-sucedida prova que o Cloud Run aceitou uma revisão, não que o produto funciona. Teste saúde, rotas públicas, fronteiras de autenticação, dependências de modelo e ferramentas, telemetria e jornadas críticas na candidata.

Para um sistema com agentes, inclua uma jornada determinística e outra aberta avaliada. Guarde os identificadores da revisão e do artefato junto do veredito.

Passar na prontidão permite decidir sobre o tráfego, mas somente um sinal de reversão predefinido torna a decisão reversível.

Tráfego e reversão

Torne a promoção reversível#

Revisões do Cloud Run são imutáveis e permitem migrar o tráfego. Assim, você pode testar uma revisão marcada, liberar a nova versão gradualmente e, se houver problema, devolver o tráfego à última revisão estável conhecida.

Defina antes o sinal de reversão: taxa de erro, latência, violação de política, jornada de negócio quebrada ou falha no fluxo de evidências. Se a observabilidade estiver quebrada, HOLD é mais seguro que uma liberação cega.

As etapas aprovadas agora precisam de limites explícitos para que o status verde não seja confundido com prova de toda a jornada do produto.

Checklist operacional

Antes de migrar tráfego#

Preencha os itens para um único identificador de imagem e uma única revisão candidata. Misturar evidências de compilações diferentes rompe a cadeia.

• ✓O contexto de compilação corresponde ao manifesto revisado.
• ✓Dependências e imagem base estão fixadas e auditadas.
• ✓Nenhum segredo ou conteúdo protegido entra no artefato.
• ✓Testes, avaliações, segurança e localização passam.
• ✓O identificador imutável da imagem está ligado à alteração versionada e é usado na implantação.
• ✓A revisão candidata fica sem tráfego durante os testes de prontidão.
• ✓Rotas e jornadas críticas passam nessa revisão.
• ✓Papéis da conta de serviço seguem o menor privilégio.
• ✓Segredos entram em tempo de execução e não aparecem em registros.
• ✓Revisão conhecida e comando de reversão estão registrados.
• ✓A migração tem responsável e sinal de parada.
• ✓O teste pós-promoção está pronto para o domínio público.

Só então a implantação produz uma candidata cuja promoção tem evidências, responsável e caminho conhecido de retorno.

Conclusão

A implantação cria uma candidata; a evidência a promove#

Uma compilação bem-sucedida e uma revisão saudável no Cloud Run provam que existe um artefato e que o contêiner inicia. Não provam que o agente conclui a jornada de negócio, respeita permissões ou deve receber tráfego de produção. A promoção é uma decisão separada.

Mantenha exata a fronteira de compilação, vincule o identificador da imagem à mudança, implante a candidata sem tráfego, exercite jornadas críticas determinísticas e avaliadas e registre responsável e sinal de reversão. Mova o tráfego somente quando essa evidência estiver completa. Se observabilidade ou recuperação estiver ausente, HOLD é o resultado operacional correto.