ADR: Adotando Amazon Bedrock AgentCore em Produção

Contexto e Forças

O cenário que motivou esta decisão é recorrente em instituições financeiras: um time de produto quer expor um agente de IA para analistas internos — capaz de consultar dados de mercado via API, executar cálculos de risco em Lambda, recuperar contexto de documentos regulatórios via RAG e registrar cada ação em trilha de auditoria imutável. O MVP funcionou em dois sprints com LangChain + Claude via Bedrock. O problema apareceu na semana seguinte.

As forças que tornaram a decisão urgente foram cinco: (1) Gerenciamento de estado entre turnos — sessões de agentes financeiros duram minutos, não segundos; manter contexto de forma confiável em Lambda stateless é frágil. (2) Rastreabilidade regulatória — cada chamada de ferramenta, cada decisão do modelo, cada resposta precisa ser auditável com timestamp, identidade e payload completo, sem depender de logging ad-hoc. (3) Guardrails como contrato — em finanças, o agente não pode vazar PII, não pode recomendar produtos sem disclaimers, não pode executar ações irreversíveis sem confirmação humana. Implementar isso manualmente em cada agente é uma dívida técnica garantida. (4) Custo de tokens imprevisível — sem controle de orçamento por sessão, um loop de agente defeituoso pode consumir dezenas de dólares em minutos. (5) Portabilidade do runtime — a equipe de plataforma não quer manter um scheduler de agentes customizado; quer um contrato de SLA com a AWS.

A Decisão e o Raciocínio por Trás Dela

A decisão foi adotar Bedrock AgentCore como runtime primário de agentes, com Step Functions como orquestrador de workflows determinísticos adjacentes (aprovações, reconciliações, notificações). Essa não é uma decisão de tudo-ou-nada: AgentCore resolve o problema do loop de agente não-determinístico, enquanto Step Functions continua sendo a escolha certa para o processo de negócio determinístico que envolve o agente.

O argumento decisivo foi o AgentCore Gateway com suporte a OAuth2/OIDC por ferramenta. Em um ambiente financeiro, cada tool-call é uma ação com identidade: quem autorizou, qual escopo, com qual token. Implementar isso manualmente em LangChain significaria construir e manter um proxy de autorização — exatamente o tipo de infraestrutura que não gera valor de negócio mas gera incidentes de segurança quando negligenciada. O Gateway entrega isso como configuração declarativa, com throttling por ferramenta (ex.: máximo de 10 chamadas/sessão para a API de execução de ordens) e circuit breaker nativo.

O segundo argumento foi memória de sessão com TTL configurável. AgentCore Memory persiste o contexto de conversação em um store gerenciado, com TTL definível por sessão e criptografia KMS customer-managed key (CMK). Para conformidade com LGPD/GDPR, isso significa que posso configurar TTL de 24h para sessões de analistas e garantir que nenhum dado de sessão persista além do necessário — sem construir um pipeline de expiração customizado.

O trade-off de lock-in foi aceito conscientemente: a camada de tool-use (as funções Lambda que executam as ações reais) permanece completamente portável. Se precisarmos migrar o runtime no futuro, as ferramentas continuam funcionando.

Configuração Concreta: O Que Realmente Importa

Adotar AgentCore sem configurar corretamente os controles operacionais é pior do que não adotar — você ganha a falsa sensação de segurança sem os guardrails ativos. Aqui estão as configurações que fazem diferença real:

Guardrails como primeira linha: Configure contentPolicyConfig com HATE, INSULTS, SEXUAL, VIOLENCE todos em BLOCK, e sensitiveInformationPolicyConfig com filtros de PII para CREDIT_DEBIT_CARD_NUMBER, AWS_ACCESS_KEY, NAME e EMAIL em modo ANONYMIZE. Em ambiente financeiro, adicione topicPolicyConfig com tópicos negados explicitamente: "investment advice without disclaimer", "guaranteed returns". Isso não é paranoia — é o mínimo para passar em uma revisão de compliance.

AgentCore Memory com particionamento correto: A chave de partição da memória deve ser userId + sessionId, nunca apenas sessionId. Em ambientes multi-tenant, sessões de usuários diferentes com o mesmo sessionId colidiram em testes — um bug silencioso que vaza contexto entre usuários. Configure memoryConfiguration.enabledMemoryTypes com SESSION_SUMMARY para sessões longas, reduzindo o consumo de tokens de contexto em até 40% em sessões acima de 20 turnos.

Gateway com throttling por ferramenta: Defina rateLimit separado para cada Action Group. A API de execução de ordens deve ter maxRequestsPerSession: 5 e requireConfirmation: ENABLED. A API de consulta de dados de mercado pode ter maxRequestsPerSession: 50. Sem essa granularidade, um loop de agente defeituoso pode executar dezenas de ordens antes de ser detectado — um cenário que já vi acontecer em produção com frameworks sem controle de tool-use.

Budget de tokens por sessão: Configure sessionConfiguration.maxTokens com um valor conservador inicial — recomendo 50.000 tokens para sessões de análise típicas. Monitore o percentil 95 de consumo por sessão no CloudWatch e ajuste. Um agente que entra em loop de raciocínio pode consumir 200k+ tokens em uma única sessão sem esse controle.

Observabilidade: O Que Medir e Como

Agentes de IA têm um perfil de observabilidade diferente de APIs tradicionais. Latência de p99 é menos útil do que distribuição de turnos por sessão e taxa de tool-call failure por ferramenta. Aqui está o modelo de observabilidade que implementei:

Métricas de negócio de agente (via CloudWatch custom metrics com namespace FinancialAgent):

• TurnsPerSession — histograma; alertar se p95 > 15 turnos (indica loop ou prompt mal calibrado)
• TokensPerSession — histograma; alertar se p95 > 40k tokens
• ToolCallFailureRate por ToolName — contador; SLO de < 1% de falha para ferramentas críticas
• GuardrailInterventionRate — contador; pico indica tentativa de jailbreak ou prompt injection

Traces com X-Ray: AgentCore emite spans para cada invocação de ferramenta com atributos bedrock.agent.toolName, bedrock.agent.sessionId e bedrock.agent.turnCount. Configure um grupo de trace com filtro annotation.bedrock.agent.toolName = "ExecuteOrder" e alarme em latência > 2s — execução de ordens acima disso indica problema na API downstream.

CloudTrail para auditoria regulatória: Cada InvokeAgent API call é registrada com o ARN do chamador, o sessionId e o inputText (truncado). Para conformidade, configure um S3 bucket com Object Lock em modo COMPLIANCE e retenção de 7 anos para os logs de CloudTrail do AgentCore. Isso é o mínimo para atender requisitos de auditoria do Banco Central do Brasil e SEC.

Alarme de anomalia de custo: Configure um AWS Budget com alerta em 80% do budget mensal de Bedrock, com ação de SNS. Adicione um segundo alarme no CloudWatch em bedrock:InvokeModel com model-id=anthropic.claude-3-5-sonnet e threshold de 1000 invocações/hora — acima disso, algo está errado.

O Que Não Está no Blog da AWS

Blogs de lançamento de serviços AWS são excelentes para mostrar o happy path. O que eles raramente cobrem são os casos de borda que você só descobre em produção. Aqui estão os três que me custaram mais tempo:

Idempotência de tool-call não é garantida pelo runtime. Se o AgentCore tentar invocar uma ferramenta e receber um timeout, ele pode tentar novamente — e sua Lambda pode ser invocada duas vezes para a mesma ação. Para ferramentas idempotentes (consultas), isso é inofensivo. Para ferramentas com efeitos colaterais (execução de ordens, envio de e-mails), você precisa implementar idempotência na Lambda usando um idempotencyToken derivado do sessionId + turnId + toolName. Sem isso, duplicação de ordens é uma questão de quando, não se.

O modelo pode ignorar requireConfirmation em certas formulações de prompt. Testei isso: se o system prompt instrui o agente a "ser proativo e executar ações sem pedir confirmação desnecessária", o modelo pode racionalizar que uma ação específica não precisa de confirmação mesmo com o flag ativo. A defesa correta é dupla: o flag no Gateway e uma instrução explícita no system prompt sobre quando confirmação é obrigatória. Nunca confie apenas em uma camada.

AgentCore não tem suporte nativo a multi-agente ainda. Se sua arquitetura requer um agente supervisor delegando para agentes especializados (padrão de orquestração multi-agente), você precisará implementar a lógica de delegação manualmente — tipicamente com um agente que chama outros agentes via tool-use, onde cada "ferramenta" é na verdade uma invocação de outro AgentCore. Funciona, mas a rastreabilidade entre sessões requer correlação manual de sessionId via X-Ray.