Agentes de IA em produção na AWS: identidade, política, avaliação e observabilidade com Amazon Bedrock AgentCore

Um agente de IA está pronto para produção quando cumpre quatro condições: cada chamada de ferramenta passa por identidade verificada e por política determinística fora do código do agente, a qualidade é medida a cada versão, cada passo deixa rastro auditável e existe um jeito testado de desligá-lo. No Amazon Bedrock AgentCore, essas condições ficam com Identity, Gateway e Policy, Evaluations e Observability, com o Runtime isolando cada sessão.

A demonstração prova que o modelo resolve a tarefa. A produção faz outras perguntas: em nome de quem o agente agiu, qual regra autorizou aquela chamada com aqueles parâmetros, como saber se a versão nova piorou, quanto custou a sessão e o que fazer de madrugada quando o agente começar a repetir a mesma ação. Este artigo é a sequência de Agentes de IA que fazem trabalho de verdade: o que é o Amazon Bedrock AgentCore, que explica o que é o AgentCore e onde ele se aplica por setor; aqui o foco é colocar o agente em produção, com Policy, avaliação por versão, observabilidade e desligamento.

O Policy e o Evaluations do AgentCore foram anunciados em prévia em 02/12/2025. O Policy chegou à disponibilidade geral em 03/03/2026 e o Evaluations, em 31/03/2026. As políticas temporais, escritas em Dogwood, vieram depois, anunciadas pela AWS em 06/08/2026. Regiões, cotas e limites seguem a documentação da AWS consultada em 15/10/2026.

Do piloto à produção: os requisitos que mudam

Os requisitos que separam piloto de produção são quase todos não funcionais. Eles precisam estar na definição de pronto antes de o primeiro usuário real entrar, porque cada um deles muda o desenho, e não só a configuração.

Para quem precisa manter o processamento no Brasil, a tabela de Regiões do AgentCore indicava, na revisão feita na atualização de 15/10/2026, Runtime em microVMs, Memory, Gateway, Identity, Observability, Policy e Evaluations disponíveis em South America (São Paulo). Duas exceções importam para este texto e aparecem nas seções seguintes: guardrails dentro de políticas e a inferência entre Regiões dos avaliadores prontos.

Execução isolada e identidade

AgentCore Runtime: a sessão como unidade de isolamento

No AgentCore Runtime, cada sessão de usuário roda em uma microVM dedicada, com CPU, memória e sistema de arquivos isolados; ao fim da sessão, a microVM é encerrada e a memória é sanitizada. A mesma documentação descreve dois tipos de computação: microVMs, serverless e cobradas por uso, com sessões de até 8 horas, e Instances, que rodam o agente em infraestrutura Amazon EC2 gerenciada pela AWS na sua conta, com sessões de até 14 dias. Para quem precisa ficar em sa-east-1, o detalhe decide: na revisão de 15/10/2026, a tabela de Regiões não listava Instances em South America (São Paulo); as microVMs, sim. O Runtime é agnóstico a framework e a modelo.

Três decisões de desenho saem daí:

• O runtimeSessionId é a fronteira de isolamento. Gere um identificador por conversa de um mesmo usuário e nunca o reaproveite entre usuários. Reaproveitar o identificador junta duas pessoas na mesma microVM.
• Versão é imutável; endpoint é ponteiro. Cada atualização do Runtime cria uma versão nova e imutável, e o endpoint DEFAULT acompanha sempre a mais recente, conforme a documentação de versões e endpoints. Em produção, use um endpoint próprio apontado para uma versão específica: promover e reverter passam a ser a troca de um ponteiro.
• Sessão aberta mantém o código antigo. A documentação de ciclo de vida registra que sessões existentes continuam com o artefato da época em que a microVM foi criada até terminarem. Uma reversão por causa de defeito precisa também encerrar as sessões em andamento.

AgentCore Identity: credencial fora do código do agente

O AgentCore Identity trata o agente como uma identidade de workload, com ARN próprio em um diretório central, e guarda tokens OAuth 2.0, credenciais de cliente e chaves de API em um token vault criptografado com chaves do AWS KMS. Segundo a página de recursos do Identity, há dois fluxos:

• Client credentials (2LO): o agente se autentica por conta própria, máquina a máquina, para tarefas que não dependem de um usuário.
• Authorization code (3LO): o agente age em nome do usuário, com consentimento explícito, para acessar dados daquele usuário em serviços externos.

No código, os decoradores @requires_access_token e @requires_api_key do SDK do AgentCore buscam e injetam a credencial no momento da chamada. Nenhum segredo fica em variável de ambiente, arquivo de configuração ou prompt.

AgentCore Gateway: um ponto único para as ferramentas

O AgentCore Gateway transforma APIs descritas em OpenAPI ou Smithy, funções AWS Lambda e serviços existentes em ferramentas compatíveis com MCP (Model Context Protocol), com autenticação de entrada e de saída no mesmo serviço e busca semântica de ferramentas. Para a operação, o ponto central é outro: se toda ferramenta passa pelo Gateway, existe um lugar só para autorizar, registrar e bloquear. Cada ferramenta vira uma ação com o formato <Target>___<ferramenta>, com três sublinhados, e é esse nome que as políticas referenciam.

Decisão de arquitetura: autorizador OAuth ou IAM no Gateway. Com OAuth, o principal da política é um AgentCore::OAuthUser criado a partir do sub do JWT, e as claims do token (escopo, papel, nome de usuário) viram tags consultáveis na política. Com IAM, o principal é um AgentCore::IamEntity cujo id é o ARN de quem chamou, e não há tags, segundo os conceitos do Policy. Regra prática: se a permissão depende de quem é o usuário final, use OAuth; se quem chama é um serviço de backend com papel fixo, IAM resolve com menos peças.

Política determinística fora do código do agente

Instrução no prompt é sugestão; o modelo pode interpretá-la mal ou ser manipulado por um conteúdo malicioso. O Policy no AgentCore move a regra para fora do agente: você cria um policy engine, grava nele políticas determinísticas e o associa a um ou mais Gateways. O Gateway intercepta cada chamada de ferramenta e a avalia contra as políticas antes de liberar o acesso. A semântica é de negação por padrão, e um forbid sempre prevalece sobre um permit.

As políticas são escritas em Cedar, linguagem de autorização de código aberto criada pela AWS. O engine gera um schema a partir das definições das ferramentas do Gateway e valida cada política na criação: ação inexistente, tipo errado ou campo de contexto não declarado são recusados antes do deploy. Uma análise com raciocínio automatizado aponta políticas que sempre permitem ou sempre negam. Também é possível descrever a regra em linguagem natural, em inglês, e o serviço gera o Cedar, valida contra o schema e roda a mesma análise; o texto gerado continua precisando de revisão humana.

Exemplo em Cedar: reembolso com escopo e teto de valor

Um agente de atendimento com três ferramentas atrás do Gateway: emitir_reembolso, aprovar_reembolso e excluir_cadastro. As políticas abaixo seguem a sintaxe das páginas de escopo e de condições da documentação; nomes e valores são ilustrativos.

// A: reembolso de valor baixo, só para quem tem o escopo no token
permit (
    principal is AgentCore::OAuthUser,
    action == AgentCore::Action::"AtendimentoAPI___emitir_reembolso",
    resource == AgentCore::Gateway::"arn:aws:bedrock-agentcore:sa-east-1:111122223333:gateway/atendimento-gw-exemplo"
)
when {
    principal.hasTag("scope") &&
    principal.getTag("scope") like "*reembolso:escrever*" &&
    context.input.valorCentavos < 50000
};

// C: aprovação de reembolso, só para o papel de supervisor
permit (
    principal is AgentCore::OAuthUser,
    action == AgentCore::Action::"AtendimentoAPI___aprovar_reembolso",
    resource == AgentCore::Gateway::"arn:aws:bedrock-agentcore:sa-east-1:111122223333:gateway/atendimento-gw-exemplo"
)
when {
    principal.hasTag("role") &&
    principal.getTag("role") == "supervisor"
};

// excluir_cadastro não tem permit: fica negada por padrão

Quatro detalhes que evitam retrabalho:

• Valor monetário como inteiro em centavos. A documentação modela dinheiro em unidades menores inteiras nos exemplos, e as agregações das políticas temporais exigem inteiros. Declare o campo como integer no schema da ferramenta desde o início.
• Sem curinga em ação. Cedar não aceita ação com curinga. Para tratar um grupo de ferramentas com uma regra, agrupe-as em um mesmo target do Gateway e use action in AgentCore::Action::"NomeDoTarget".
• ARN específico é obrigatório quando a política nomeia ações específicas. Isso separa de fato os Gateways de homologação e de produção.
• Negar por omissão é mais seguro que negar por regra. Uma ferramenta sem permit já está bloqueada. Use forbid para subtrair de uma permissão existente, como um cliente bloqueado ou um parâmetro proibido.

Políticas temporais em Dogwood: aprovação antes da ação e limites por sessão

Cedar decide olhando só a solicitação atual. Regras que dependem do que já aconteceu na sessão são políticas temporais, que a AWS anunciou em 06/08/2026, junto com o limite de taxa no Gateway. Elas são escritas em Dogwood, nome usado na própria documentação da AWS: uma linguagem de código aberto que estende o modelo de autorização do Cedar com condições que consideram a sessão. Segundo o anúncio, o Dogwood é publicado como especificação e implementação de referência sob a licença Apache 2.0, e a sintaxe completa está no guia da linguagem Dogwood, para o qual a documentação aponta.

Políticas pontuais já escritas em Cedar continuam funcionando sem alteração; a condição temporal entra só onde a regra precisa considerar mais que a solicitação atual. Na revisão feita na atualização de 15/10/2026, a página de políticas temporais não marcava o recurso como prévia e listava South America (São Paulo) entre as Regiões com suporte. Os operadores cobrem os casos comuns: formerly within (um evento ocorreu na janela), since within (uma condição vale desde um evento âncora) e as agregações count e sum.

Continuando o exemplo, reembolsos acima do teto passam a exigir aprovação do supervisor para a mesma compra na última hora, e o agente fica limitado a um número de emissões por janela (teto, janela e limite são valores ilustrativos). A sintaxe segue os exemplos de políticas temporais da AWS:

// B: reembolso acima do teto exige escopo E aprovação da mesma compra na última hora
permit (
    principal is AgentCore::OAuthUser,
    action == AgentCore::Action::"AtendimentoAPI___emitir_reembolso",
    resource == AgentCore::Gateway::"arn:aws:bedrock-agentcore:sa-east-1:111122223333:gateway/atendimento-gw-exemplo"
)
when temporal {
    formerly within 1h AgentCore::Action::"AtendimentoAPI___aprovar_reembolso"::response{
        eventResource: resource,
        input.compraId: context.input.compraId
    }
}
when {
    principal.hasTag("scope") &&
    principal.getTag("scope") like "*reembolso:escrever*" &&
    context.input.valorCentavos >= 50000
};

// D: no máximo 3 emissões em qualquer janela de 1 hora da mesma sessão
forbid (
    principal,
    action == AgentCore::Action::"AtendimentoAPI___emitir_reembolso",
    resource == AgentCore::Gateway::"arn:aws:bedrock-agentcore:sa-east-1:111122223333:gateway/atendimento-gw-exemplo"
)
when temporal {
    exists (n: Long).
        (count for (t: Timepoint).
            where (formerly within 1h (AgentCore::Action::"AtendimentoAPI___emitir_reembolso"::request{ eventResource: resource } && tp(t)))) == n
        && n > 3
};

Um cuidado de lógica que vale para qualquer motor de autorização: permit se combina por "ou". Se a regra B fosse escrita em uma política separada da exigência de escopo, qualquer outra política que permitisse a ação liberaria o reembolso sem aprovação. Por isso escopo, faixa de valor e aprovação estão na mesma política, e a regra A cobre só a faixa abaixo do teto.

As armadilhas que a documentação registra para políticas temporais:

• A sessão de política é informada por quem chama, no cabeçalho x-amzn-bedrock-agentcore-policy-session-id. O Gateway não gera o identificador, e, se o engine tiver política temporal, solicitação sem ele falha na validação.
• Limite por count não é controle de segurança. Como quem chama controla o identificador da sessão, abrir uma sessão nova zera a contagem. Use a regra D para frear um agente em laço; o limite contra abuso fica em outra camada.
• A condição que cita a própria ação conta a solicitação atual. Na regra D, a contagem já inclui a emissão que está sendo autorizada; por isso n > 3 libera até três emissões por janela e nega a quarta.
• A ação prévia precisa ser permitida para virar evento response. Sem a política C, nenhuma aprovação seria registrada e a regra B nunca seria satisfeita.
• Alterar uma política temporal invalida as sessões abertas daquele engine, e a próxima solicitação recebe HTTP 409 ConflictException. O cliente precisa tratar o 409 como "abrir sessão nova", e fluxos de várias etapas recomeçam.
• Mesma conta e mesma Região. O Gateway e todos os targets precisam estar juntos, e o papel do Gateway precisa da permissão bedrock-agentcore:GetWorkloadAccessToken.
• Cotas: 20 políticas temporais por engine, 3 operadores temporais por política e janela máxima de 24 horas por condição, segundo a mesma página.

Sinais do Amazon Bedrock Guardrails dentro da política

Uma política também pode consultar o Amazon Bedrock Guardrails no momento da avaliação: ContentFilter (violência, ódio e outras categorias), PromptAttack (jailbreak, injeção de prompt, vazamento de prompt) e SensitiveInformation. O guardrail devolve uma pontuação de confiança, em valores discretos de 0,0 a 1,0 em passos de 0,2 segundo a documentação, e a política decide com ela. A documentação recomenda escrever a regra como permit com a comparação invertida: como a avaliação nega por padrão, um único permit que só vale enquanto a pontuação fica baixa concede e protege a ação ao mesmo tempo.

Sobre o limiar, a mesma página registra que, quando a política é gerada pelo serviço de autoria em linguagem natural sem limiar informado, o AgentCore aplica 0,4 para ataque de prompt e 0,2 para filtro de conteúdo e informação sensível. Política escrita à mão precisa declarar o valor. O exemplo usa 0,4 como ponto de partida; a calibração indicada pela documentação é rodar o engine em LOG_ONLY, rotular as decisões registradas e comparar precisão e recall em vários limiares.

// Registra a ocorrência só se o texto não tiver sinal de injeção de prompt
permit (
    principal is AgentCore::OAuthUser,
    action == AgentCore::Action::"AtendimentoAPI___registrar_ocorrencia",
    resource == AgentCore::Gateway::"arn:aws:bedrock-agentcore:us-east-1:111122223333:gateway/atendimento-gw-exemplo"
)
when guardrails {
    BedrockGuardrails::PromptAttack(["PROMPT_INJECTION"], [context.input.descricao])["PROMPT_INJECTION"]
        .confidenceScore.lessThanOrEqual(decimal("0.4"))
};

O ARN do exemplo está em us-east-1 de propósito: na tabela de Regiões da página de guardrails em políticas, South America (São Paulo) aparecia sem suporte a esse recurso na revisão feita na atualização de 15/10/2026, enquanto as políticas temporais apareciam disponíveis. Se a residência no Brasil é requisito, o filtro de conteúdo fica na aplicação, com a API ApplyGuardrail, ou na própria ferramenta. Lembre também que o guardrail não é determinístico: o mesmo texto pode pontuar diferente em chamadas distintas, enquanto a política, dado o mesmo contexto, decide sempre igual.

Implantação em LOG_ONLY e trilha das decisões

O engine tem dois modos de aplicação: LOG_ONLY, que avalia e registra sem bloquear, e ENFORCE, que bloqueia. O caminho seguro é publicar em LOG_ONLY, observar a métrica LogOnlyDecisionFlips (decisões que mudariam ao promover a política) e só então passar para ENFORCE.

Cada decisão vira evidência. No namespace AWS/Bedrock-AgentCore do CloudWatch saem por padrão métricas como AllowDecisions, DenyDecisions e NoDeterminingPolicies, com dimensões por engine, política, Gateway e ferramenta. Com rastros ativados no Gateway, cada span no grupo de logs aws/spans traz aws.agentcore.policy.authorization_decision e aws.agentcore.policy.determining_policies, ou seja, a decisão e as políticas que a determinaram, segundo a referência de observabilidade do Policy.

Proteja a própria política. A documentação alerta que quem tem bedrock-agentcore:UpdateGateway pode trocar o modo para LOG_ONLY ou remover o engine do Gateway, e não há chave de condição separada para o campo de modo. Essa permissão fica restrita ao papel do pipeline de implantação, com alarme sobre a chamada no AWS CloudTrail.

Avaliar antes e depois de publicar

Trocar o modelo, editar o prompt de sistema ou incluir uma ferramenta muda o comportamento do agente de formas que um teste unitário não pega. O AgentCore Evaluations pontua rastros do agente, hospedado ou não no Runtime, em três tipos de avaliação:

• Online: amostra sessões reais de produção, por percentual ou por filtro, e acompanha a tendência de qualidade.
• Sob demanda: avalia rastros ou spans específicos; serve para teste em tempo de build e para investigar uma conversa reclamada.
• Em lote: roda avaliadores sobre muitas sessões em um job assíncrono; serve para linha de base, comparação antes e depois de uma mudança e regressão sobre um conjunto curado.

Os avaliadores trabalham em três níveis. No nível de sessão, Goal success rate mede se o usuário atingiu o objetivo. No nível de rastro, avaliadores como Correctness, Faithfulness e Helpfulness olham cada resposta. No nível de ferramenta, Tool selection accuracy e Tool parameter accuracy medem se o agente escolheu a ferramenta certa e preencheu os parâmetros corretamente. Os avaliadores prontos usam LLM como juiz, com modelo e prompt que não podem ser alterados. Para critério próprio, há avaliadores customizados com LLM como juiz (seu modelo, suas instruções, sua escala) e avaliadores por código em uma função AWS Lambda, para checagens determinísticas.

Cenários de regressão por versão do agente

O recurso que transforma avaliação em portão de publicação é a avaliação com ground truth: Builtin.Correctness compara a resposta com expectedResponse; Builtin.GoalSuccessRate verifica uma lista de assertions em linguagem natural; e Builtin.TrajectoryExactOrderMatch, Builtin.TrajectoryInOrderMatch e Builtin.TrajectoryAnyOrderMatch comparam a sequência de ferramentas chamadas com expectedTrajectory, com pontuação programática, sem chamada a modelo.

# Cenário de regressão "reembolso acima do teto, sem aprovação", contra a versão candidata.
# A sessão foi gerada por um script que conversa com o endpoint de homologação.
# A documentação orienta esperar de 2 a 5 minutos pela telemetria no CloudWatch antes de avaliar.
# Use os nomes de ferramenta exatamente como aparecem no rastro do agente.
agentcore run eval \
  --runtime atendimento \
  --session-id "$SESSAO_CENARIO_REEMBOLSO_ALTO" \
  --evaluator Builtin.GoalSuccessRate Builtin.TrajectoryInOrderMatch \
  --assertion "O agente consultou a compra antes de propor o reembolso" \
  --assertion "O agente informou que o valor exige aprovação de um supervisor" \
  --assertion "Sem aprovação registrada, o agente informou que o reembolso aguarda aprovação" \
  --expected-trajectory "consultar_compra,escalar_para_humano" \
  --output resultado-versao-candidata.json

As flags seguem os exemplos do CLI do AgentCore na mesma página de avaliação com ground truth: --assertion se repete uma vez por afirmação, --expected-trajectory recebe os nomes das ferramentas separados por vírgula e --expected-response alimenta o Builtin.Correctness. Pela API, o mesmo conteúdo vai no campo evaluationReferenceInputs da chamada Evaluate, com assertions e expectedTrajectory.toolNames no contexto da sessão. A trajetória usa TrajectoryInOrderMatch, que aceita ferramentas extras entre as esperadas; uma tentativa de emitir_reembolso no meio do caminho não reprova o cenário, mas aparece como negação no DenyDecisions da política. Quando qualquer chamada fora do roteiro deve reprovar, o avaliador certo é o TrajectoryExactOrderMatch.

O método que recomendo, por versão do agente:

1. Cenários nascem de requisito. Cada regra de negócio vira pelo menos um cenário de caminho feliz e um de recusa, rastreável até o critério de aceitação que o originou.
2. Cada cenário tem assertions e trajetória esperada. A assertion mede o resultado; a trajetória mede o caminho. Um agente que acerta a resposta pulando a consulta obrigatória falha na trajetória.
3. A versão candidata roda no endpoint de homologação contra o conjunto inteiro, e o resultado é comparado com o da versão em produção. Promover significa reapontar o endpoint de produção só quando não houver regressão nos cenários críticos.
4. Todo incidente vira cenário. A conversa que gerou a reclamação entra no conjunto com a assertion que teria barrado o defeito.
5. Em produção, a avaliação online continua sobre uma amostra de sessões. Avaliadores customizados que dependem de ground truth não rodam na avaliação online, porque o tráfego real não tem resposta esperada; ali entram os avaliadores sem referência.

Ponto de LGPD: os avaliadores prontos usam inferência entre Regiões. Segundo a documentação de inferência entre Regiões do Evaluations, os dados ficam armazenados na Região de origem, mas prompts e resultados podem ser processados em outra Região da mesma geografia; a alternativa indicada para evitar isso são os avaliadores customizados. Se o rastro contém dado pessoal, essa transferência entra no mapeamento de dados antes de ligar a avaliação online.

Da spec no Kiro ao cenário de regressão

Quando o agente é desenvolvido com o Kiro, a IA agêntica da AWS para desenvolvimento de software, os critérios de aceitação já existem antes do código, em .kiro/specs/<feature>/requirements.md, escritos na notação EARS descrita na página de Feature Specs. O trabalho que falta é numerar cada critério e ligar cada um a pelo menos um cenário. O desenho completo da spec está em specs no Kiro.

## Requisito 2: reembolso acima do teto

**User story:** Como cliente, quero solicitar o reembolso de uma compra de
valor alto, para receber o valor depois da análise de um supervisor.

### Critérios de aceitação
1. WHEN o cliente solicita reembolso de uma compra, THE SYSTEM SHALL
   consultar a compra antes de propor qualquer valor.
2. WHEN o valor da compra é igual ou maior que o teto, THE SYSTEM SHALL
   informar que o reembolso exige aprovação de um supervisor e escalar o
   atendimento para uma pessoa.
3. IF não houver aprovação registrada para a compra, THEN THE SYSTEM SHALL
   informar que o reembolso aguarda aprovação.

Cada critério vira uma assertion, e o caminho esperado vira a trajetória. O arquivo do cenário segue um formato do próprio time, versionado ao lado da spec; o script de avaliação o lê e monta a chamada do agentcore run eval mostrada acima:

{
  "id": "req-2-reembolso-acima-do-teto",
  "spec": ".kiro/specs/atendimento-reembolso/requirements.md",
  "criterios": ["2.1", "2.2", "2.3"],
  "roteiro": ["Quero o reembolso da compra 4821."],
  "assertions": [
    "O agente consultou a compra antes de propor o reembolso",
    "O agente informou que o valor exige aprovação de um supervisor",
    "Sem aprovação registrada, o agente informou que o reembolso aguarda aprovação"
  ],
  "expectedTrajectory": ["consultar_compra", "escalar_para_humano"]
}

Para que nenhum critério fique sem cenário, um hook do Kiro confere a cobertura sempre que o agente salva a spec ou um cenário. É uma ação de comando: roda localmente, devolve resultado objetivo e não consome créditos, segundo as boas práticas de hooks. O formato do arquivo e o gatilho PostFileSave seguem a documentação de hooks do Kiro:

{
  "version": "v1",
  "hooks": [{
    "name": "Cobertura de cenários de regressão",
    "description": "Todo critério de aceitação da spec precisa de pelo menos um cenário",
    "trigger": "PostFileSave",
    "matcher": "(requirements\\.md|avaliacao/cenarios/.*\\.json)$",
    "action": { "type": "command", "command": "node scripts/cobertura-cenarios.mjs" },
    "timeout": 30
  }]
}

Três decisões estão por trás desse desenho:

• O hook confere cobertura; a avaliação roda no pipeline. A avaliação precisa de uma sessão real no endpoint de homologação e da telemetria já ingerida no CloudWatch, e os avaliadores com LLM como juiz chamam um modelo a cada execução. Isso não cabe no salvamento de um arquivo. O script do hook só cruza os números dos critérios com o campo criterios dos cenários e lista o que falta.
• A mesma checagem roda no CI. Gatilhos de arquivo do Kiro respondem só a mudanças feitas pelo agente, segundo a página de tipos de hook; edição manual no editor não dispara o hook. O pipeline repete o script antes de rodar os cenários, com o mesmo resultado para qualquer autor da mudança. Os padrões para levar o Kiro ao pipeline estão em Kiro CLI no pipeline.
• A spec é a fonte; o cenário é derivado. Critério novo ou alterado na spec reprova a cobertura até ganhar cenário, e o incidente que vira cenário também vira critério na spec. Assim a regressão e o requisito não se separam com o tempo. Os gatilhos e códigos de saída dos hooks estão detalhados em hooks no Kiro.

Observabilidade

O AgentCore Observability emite telemetria em formato compatível com OpenTelemetry e grava métricas, spans e logs no Amazon CloudWatch, com painéis para contagem de sessões, latência, duração, uso de tokens e taxa de erro. Três detalhes de configuração: a visualização de métricas, spans e rastros exige ativar uma vez o CloudWatch Transaction Search; spans e logs de alguns recursos, como memória e ferramentas, precisam ser ligados explicitamente; e o código do agente pode ser instrumentado para spans e métricas próprios. Agentes hospedados fora do Runtime também podem enviar telemetria. Os fundamentos de CloudWatch, X-Ray e OpenTelemetry estão no post sobre observabilidade na AWS.

Painel não é objetivo de serviço. Para agente, o SLO precisa medir o que o usuário percebe e o que a operação precisa saber:

Modelar o escalonamento como uma ferramenta do Gateway (escalar_para_humano) tem um efeito colateral útil: ele passa a aparecer no rastro e nas métricas de decisão como qualquer outra ação, sem instrumentação extra. A meta de cada indicador é decisão de negócio e deve ser registrada junto com o motivo; um pico de negações, por exemplo, pode indicar tanto ataque quanto uma política mal calibrada depois de uma mudança de ferramenta.

Conteúdo e dado pessoal: Amazon Bedrock Guardrails

O Amazon Bedrock Guardrails aplica salvaguardas configuráveis à entrada e à saída do modelo: filtros de conteúdo (incluindo ataque de prompt), tópicos negados, filtros de palavras, filtros de informação sensível, verificação de fundamentação contextual e verificações de Automated Reasoning. Ele funciona junto da chamada ao modelo, informando o ID e a versão do guardrail, ou de forma independente, pela API ApplyGuardrail. Em agentes que usam RAG, a verificação de fundamentação contextual detecta resposta que se afasta da fonte recuperada ou que não responde à pergunta; o desenho completo está no post sobre RAG na AWS.

Para dado pessoal brasileiro, a lista de tipos de PII prontos do filtro de informação sensível traz categorias gerais (nome, e-mail, telefone, endereço) e identificadores específicos de Estados Unidos, Canadá e Reino Unido. CPF e CNPJ entram por expressão regular customizada, com ação de bloquear, mascarar ou só detectar. O padrão de CNPJ já precisa aceitar letras: segundo as perguntas e respostas da Receita Federal sobre o CNPJ alfanumérico, as 12 primeiras posições passam a aceitar números e letras maiúsculas de A a Z, e os dois dígitos verificadores continuam calculados pelo módulo 11. O primeiro CNPJ nesse formato foi gerado em 31/07/2026, e os numéricos continuam válidos.

"sensitiveInformationPolicyConfig": {
  "piiEntitiesConfig": [
    { "type": "EMAIL", "action": "ANONYMIZE" },
    { "type": "PHONE", "action": "ANONYMIZE" }
  ],
  "regexesConfig": [
    {
      "name": "cpf",
      "description": "CPF com ou sem pontuação",
      "pattern": "[0-9]{3}\\.?[0-9]{3}\\.?[0-9]{3}-?[0-9]{2}",
      "action": "ANONYMIZE"
    },
    {
      "name": "cnpj",
      "description": "CNPJ numérico ou alfanumérico, com ou sem pontuação",
      "pattern": "[0-9A-Z]{2}\\.?[0-9A-Z]{3}\\.?[0-9A-Z]{3}/?[0-9A-Z]{4}-?[0-9]{2}",
      "action": "ANONYMIZE"
    }
  ]
}

Antes de confiar nesse filtro em um agente, considere três limites documentados:

• Argumentos e resultados de ferramenta ficam de fora. O filtro de informação sensível avalia texto, mas não os argumentos que o modelo gera para uma chamada de ferramenta, nem o resultado que a aplicação devolve ao modelo, nem as definições das ferramentas. Em agente, esse é justamente o caminho do dado. A proteção desses campos fica na ferramenta, que valida a própria entrada, ou na política do Gateway, que enxerga context.input de cada chamada.
• Log de invocação guarda o original. Com o log de invocação do modelo ativado, o campo de entrada no CloudWatch Logs mantém a solicitação sem máscara. A documentação indica a proteção de dados do CloudWatch Logs para mascarar ali.
• Regex sem lookaround e com falso positivo. A documentação registra que a regex customizada não aceita lookaround e que o padrão tem de 1 a 500 caracteres. Os padrões acima usam só classes explícitas, como [0-9], em vez de atalhos como \d, para não depender de sintaxe que a página não detalha. Sem lookaround, não há como exigir fronteira de número: o padrão de CPF casa qualquer sequência de 11 dígitos, inclusive dentro de um CNPJ sem pontuação, e o de CNPJ casa códigos internos de 14 caracteres maiúsculos que terminem em dois dígitos. Teste na janela de teste do console com textos reais do domínio antes de escolher entre mascarar e bloquear.

Custo e desligamento

O custo de um agente cresce com o número de passos, porque cada passo é uma chamada nova ao modelo com contexto maior. O controle é em camadas, da mais barata à mais drástica:

1. Limite de passos e de tokens no código do agente. Teto de iterações do laço de raciocínio, configurado no framework, e maxTokens por chamada. Ao atingir o teto, o agente encerra com resumo parcial ou escala para uma pessoa, em vez de falhar em silêncio.
2. Ciclo de vida da sessão no Runtime. Os padrões são 900 segundos de ociosidade e 28.800 segundos de vida máxima por microVM, conforme a documentação de ciclo de vida. Ajuste ao uso real.
3. Orçamento na política. A agregação sum de uma política temporal mantém um total acumulado abaixo de um limite por sessão, sobre um campo inteiro da ferramenta. Vale a mesma ressalva do count: é freio de comportamento dentro de uma sessão cooperativa.
4. Alocação por agente. Um application inference profile por agente, com tags de alocação de custo, separa o gasto de inferência no Cost Explorer e no CUR e permite showback por produto.
5. Kill-switch em três níveis: uma flag na aplicação lida antes de cada chamada ao modelo; uma política forbid no engine para a ferramenta afetada ou para todas; e o encerramento das sessões do Runtime.

lifecycleConfiguration={
    'idleRuntimeSessionTimeout': 600,   # encerra a microVM após 10 minutos ociosa
    'maxLifetime': 7200                 # teto de 2 horas por microVM
}
# idleRuntimeSessionTimeout precisa ser menor ou igual a maxLifetime

A conta de custo por unidade, os perfis de inferência com política IAM que impede chamada fora do perfil e o contador atômico de orçamento antes da chamada estão detalhados no post sobre FinOps de IA generativa na AWS. Lá também está o motivo pelo qual alerta de fatura não substitui limite no código: os dados de orçamento e de anomalia chegam com horas de atraso.

Runbook de incidente de agente

Incidente de agente tem uma particularidade: ele age enquanto você investiga. A ordem abaixo prioriza parar a ação, depois reverter e só então diagnosticar.

1. Detectar. Alarmes sobre pico de DenyDecisions, queda na avaliação online, tokens por hora acima do esperado e reclamação de usuário entram no mesmo canal de plantão.
2. Conter pela política. Uma política forbid para a ferramenta afetada, ou a política de emergência que nega todas as chamadas no Gateway. A análise automatizada aponta uma política que sempre nega; para a de emergência, a criação assume essa constatação de forma explícita. A criação é assíncrona: aguarde o estado ativo antes de dar a contenção por feita.
3. Encerrar sessões em andamento com StopRuntimeSession, porque sessões abertas mantêm o código da versão em que nasceram.
4. Reverter a versão reapontando o endpoint de produção para a versão anterior, que é imutável e já foi avaliada.
5. Preservar a evidência. Spans em aws/spans, logs do Runtime e decisões de política ficam no CloudWatch; confira a retenção dos grupos de logs, exporte o intervalo do incidente e registre a linha do tempo.
6. Comunicar. Clientes e áreas afetadas recebem a informação pelo canal combinado. Se houve incidente de segurança com dado pessoal que possa gerar risco ou dano relevante aos titulares, o Regulamento de Comunicação de Incidente de Segurança da ANPD (Resolução CD/ANPD nº 15/2024) fixa prazo de três dias úteis para comunicar a ANPD e os titulares e exige manter o registro do incidente por no mínimo cinco anos.
7. Aprender. A conversa do incidente vira cenário de regressão, a regra que faltou vira política, e só depois disso a ferramenta volta a ser permitida.

# 1. Conter: política de emergência que nega todas as chamadas de ferramenta
aws bedrock-agentcore-control create-policy \
  --policy-engine-id "$MOTOR_ID" \
  --name EmergenciaNegaTudo \
  --validation-mode IGNORE_ALL_FINDINGS \
  --definition '{"policy":{"statement":"forbid (principal, action, resource);"}}'
# A resposta é 202 (CREATING): acompanhe até o estado ativo

# 2. Encerrar uma sessão em andamento no endpoint de produção
aws bedrock-agentcore stop-runtime-session \
  --agent-runtime-arn "$AGENTE_ARN" \
  --qualifier producao \
  --runtime-session-id "$SESSAO_ID"

# 3. Reverter: endpoint de produção volta para a versão anterior
aws bedrock-agentcore-control update-agent-runtime-endpoint \
  --agent-runtime-id "$AGENTE_ID" \
  --endpoint-name producao \
  --agent-runtime-version "$VERSAO_ANTERIOR"

Ensaie o runbook em homologação com o mesmo papel IAM que o plantão vai usar. Permissão que falta no meio de um incidente custa mais caro que qualquer ajuste feito com calma.

Checklist de prontidão para produção

1. Identidade: autorizador de entrada definido (OAuth ou IAM) e credenciais de saída no token vault do AgentCore Identity, nenhuma no código.
2. Sessão: um runtimeSessionId por conversa, nunca compartilhado entre usuários, e ciclo de vida ajustado.
3. Gateway único: toda ferramenta do agente passa pelo AgentCore Gateway.
4. Política: engine associado em ENFORCE, toda ferramenta com permit explícito e escopo de parâmetro, valores monetários em inteiro.
5. Ação sensível com aprovação: regra temporal que exige aprovação registrada antes da ação irreversível, com a ferramenta de aprovação restrita a um papel humano.
6. Proteção da política: UpdateGateway restrito ao pipeline, com alarme no CloudTrail.
7. Regressão: conjunto de cenários com assertions e trajetória esperada, cada um ligado a um critério de aceitação, com cobertura conferida e rodado a cada versão candidata.
8. Avaliação online: amostragem de sessões de produção com alarme de queda, e o tratamento de dados entre Regiões registrado no mapeamento de dados.
9. Observabilidade: Transaction Search ativo, rastros do Gateway ligados, SLO de conclusão, latência e escalonamento com meta escrita.
10. Guardrails: filtros de conteúdo e de PII com regex para CPF e CNPJ, validação de dado pessoal nos argumentos das ferramentas e proteção de dados nos logs de invocação.
11. Custo: limite de passos e de tokens, perfil de inferência por agente com tags ativas e flag de desligamento testada.
12. Runbook ensaiado: política de emergência, encerramento de sessão e reversão de versão executados em homologação, com o papel do plantão.

Levar um agente do piloto à produção é decisão de desenho, com identidade, política, avaliação, observabilidade e desligamento definidos antes do primeiro usuário real. Cada regra de negócio fica em três lugares que se conferem entre si: o critério de aceitação da spec, a política no Gateway e o cenário de regressão. O padrão de software house com specs e agentes no AgentCore está em um dos projetos do catálogo, e a governança da IA usada para escrever o código está em governança de IA no código.

Para o código do agente, escrito com specs e hooks, veja a adoção do Kiro com a RFX ou pratique o fluxo no seu repositório na oficina Kiro na Prática.

Perguntas frequentes

O que muda de um agente de IA de demonstração para um agente em produção?

Na demonstração, a pergunta é se o modelo resolve a tarefa. Em produção, entram requisitos não funcionais: identidade do usuário e do agente, autorização por ferramenta fora do código do agente, isolamento de sessão, avaliação de qualidade a cada versão, rastro auditável de cada passo, custo por sessão e um jeito testado de reverter e de desligar o agente. No Amazon Bedrock AgentCore, essas funções ficam com Runtime, Identity, Gateway, Policy, Evaluations e Observability.

O que é o Policy no Amazon Bedrock AgentCore?

É o recurso que guarda políticas determinísticas em um policy engine associado a um AgentCore Gateway. O Gateway intercepta cada chamada de ferramenta do agente e a avalia contra as políticas antes de liberar o acesso, com negação por padrão e forbid prevalecendo sobre permit. As políticas são escritas em Cedar ou em Dogwood, e cada decisão gera métricas e rastros no Amazon CloudWatch. O Policy ficou disponível de forma geral em 03/03/2026, segundo o anúncio da AWS.

Cedar ou Dogwood: em qual linguagem escrever as políticas do AgentCore?

Regras que dependem só da solicitação atual (quem chama, qual ferramenta, quais parâmetros) cabem em Cedar. Regras que dependem do histórico da sessão (aprovação prévia, limite de execuções, total acumulado) são políticas temporais e exigem Dogwood, linguagem de código aberto que estende o modelo de autorização do Cedar e aceita todas as políticas Cedar existentes, segundo a documentação da AWS. As políticas temporais foram anunciadas pela AWS em 06/08/2026.

Como avaliar um agente de IA antes de publicar uma versão nova?

Mantenha um conjunto de cenários de regressão com resultado esperado e rode a versão candidata contra ele antes de promovê-la. No AgentCore Evaluations, use assertions com o avaliador Builtin.GoalSuccessRate, resposta esperada com Builtin.Correctness e sequência esperada de ferramentas com os avaliadores de trajetória, que pontuam sem chamar um modelo. Em produção, a avaliação online amostra sessões reais de forma contínua.

Como desligar um agente de IA em produção sem novo deploy?

Em três camadas. Na política, uma regra forbid para a ferramenta afetada, ou para todas, bloqueia as chamadas no Gateway. No Runtime, a API StopRuntimeSession encerra sessões em andamento e o endpoint de produção pode voltar a apontar para a versão anterior, que é imutável. Na aplicação, uma flag verificada antes de cada chamada ao modelo impede novo consumo. Teste os três antes de precisar deles.

Sobre o autor

Rodrigo Araújo

Arquiteto de Soluções, IA e Cloud | RFX Tecnologia

Arquiteto de Soluções, IA e Cloud na RFX Tecnologia, lidera projetos de migração, FinOps e IA aplicada na nuvem para empresas do Nordeste e de todo o Brasil. É também o idealizador da Jornada de Inovação AWS em João Pessoa, encontro que aproxima donos de negócio da região das aplicações reais de cloud e inteligência artificial.