# ADR: Adotando Amazon Bedrock AgentCore em Produção Bedrock AgentCore promete reduzir o atrito operacional de agentes de IA em produção, mas adotar qualquer plataforma gerenciada de orquestração de agentes exige uma decisão arquitetural explícita. Neste ADR, documento as forças que me levaram a avaliar AgentCore, as alternativas consideradas e as consequências reais de cada caminho. - URL: https://fernando.moretes.com/studies/adr-agentes-producao-bedrock-agentcore-risco-operacional - Markdown: https://fernando.moretes.com/studies/adr-agentes-producao-bedrock-agentcore-risco-operacional/study.md?lang=pt - Type: Decisão (ADR) - Status: proposed - Date: 2026-05-25 - Tags: bedrock, agentcore, ai-agents, adr, financial-grade, guardrails, observability, aws - Reading time: 9 min --- Depois de 16 anos construindo plataformas financeiras sobre AWS, aprendi que a pergunta mais perigosa em arquitetura não é 'isso funciona?', é 'quem opera isso às 2h da manhã quando falha?' Bedrock AgentCore é a resposta da AWS para o problema de operacionalizar agentes de IA além do notebook: runtime gerenciado, memória, tool-use, guardrails e rastreabilidade em um único plano de controle. Este ADR documenta como cheguei à decisão de adotá-lo, ou não, em um ambiente financeiro regulado, e as consequências que você precisa internalizar antes de fazer o mesmo. ## Contexto e Forças ## 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. ## Opções Consideradas ### Opção A: LangChain/LangGraph auto-hospedado em EKS **Pros** - Controle total sobre o grafo de execução e lógica de retry - Portabilidade de modelo, troca de LLM sem mudança de plataforma - Ecossistema maduro de integrações e ferramentas da comunidade **Cons** - Responsabilidade operacional total: scaling, HA, patches, observabilidade - Guardrails e auditoria precisam ser construídos e mantidos pelo time - Gerenciamento de memória de sessão requer DynamoDB ou Redis customizados - Custo de engenharia alto para atingir paridade com features gerenciadas **Verdict:** Adequado para times com plataforma de IA madura; risco operacional alto para times menores ### Opção B: Bedrock Agents (geração anterior, sem AgentCore) **Pros** - Gerenciado pela AWS, sem infraestrutura de runtime para operar - Integração nativa com Knowledge Bases e Action Groups **Cons** - Observabilidade limitada: traces parciais, sem span-level detail nativo - Controle de orçamento por sessão ausente nativamente - Customização do loop de agente restrita ao que a AWS expõe **Verdict:** Boa opção para casos simples; limitações de observabilidade são bloqueadoras em finanças ### Opção C: Amazon Bedrock AgentCore **Pros** - Runtime gerenciado com memória de sessão persistente nativa (AgentCore Memory) - Guardrails configuráveis como política declarativa, não código inline - Rastreabilidade nativa via CloudTrail + X-Ray com span de tool-call - AgentCore Gateway para tool-use com OAuth2/OIDC e throttling por ferramenta - Controle de orçamento de tokens por sessão configurável **Cons** - Lock-in na plataforma AWS para o runtime de agentes - Customização do grafo de execução mais restrita que LangGraph - Serviço novo: surface de API ainda em evolução, quotas conservadoras - Custo de AgentCore Memory e Gateway adicionados ao custo de inferência **Verdict:** Decisão recomendada para ambientes financeiros regulados com time de plataforma enxuto ### Opção D: Step Functions + Lambda como orquestrador de agente **Pros** - Auditoria nativa via execution history do Step Functions - Retry, timeout e error handling declarativos e testáveis - Sem novo serviço para aprender, equipe já conhece o padrão **Cons** - Não é um runtime de agente: cada 'turno' exige nova execução ou uso de .waitForTaskToken - Memória de sessão e contexto de modelo precisam ser gerenciados externamente - Latência de cold-start e transição de estado pode ser perceptível em diálogos **Verdict:** Excelente para workflows determinísticos; inadequado como runtime de agente conversacional ## A Decisão e o Raciocínio por Trás Dela ## 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. ## Arquitetura de Agente Financeiro com Bedrock AgentCore Fluxo de execução de um agente de análise financeira: do analista ao AgentCore runtime, passando por guardrails, tool-use via Gateway, memória de sessão e observabilidade ### 🔐 AWS: Segurança & Entrada - API Gateway REST + Cognito JWT (edge) - Bedrock Guardrails PII filter + topic deny (security) ### 🤖 AWS: AgentCore Runtime - AgentCore Runtime Claude 3.5 Sonnet (ai) - AgentCore Memory TTL=24h, KMS CMK (storage) - AgentCore Gateway OAuth2/OIDC, throttle (security) ### ⚙️ AWS: Ferramentas (Tool-use) - Lambda: Market Data Bloomberg API proxy (compute) - Lambda: Risk Calc VaR engine (compute) - Knowledge Base OpenSearch + S3 (data) ### 📊 AWS: Observabilidade & Auditoria - X-Ray span por tool-call (external) - CloudTrail API audit log (storage) - CloudWatch SLO dashboards (external) ### Fluxos - analyst -> apigw: HTTPS + JWT - apigw -> guardrails: input validation - guardrails -> agentcore: prompt sanitizado - agentcore -> memory: read/write contexto - agentcore -> gateway: tool invocation - gateway -> lambda_market: OAuth2 token - gateway -> lambda_risk: OAuth2 token - gateway -> kb: RAG query - agentcore -> guardrails: output filter - agentcore -> xray: traces - apigw -> cloudtrail: API events - xray -> cw: métricas SLO ## Configuração Concreta: O Que Realmente Importa ## 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 ## 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. > **Consequências e Riscos Que Você Precisa Aceitar:** **Lock-in de runtime é real:** Se a AWS deprecar ou alterar significativamente a API do AgentCore, a migração exige reescrever a lógica de orquestração, não apenas as ferramentas. Mitigue mantendo as ferramentas (Lambda) completamente agnósticas ao runtime e documentando o contrato de interface em um ADR separado. **Quotas conservadoras em serviço novo:** AgentCore tem quotas de `concurrent agent sessions` que, em lançamento, eram significativamente menores que as quotas de Bedrock Agents tradicionais. Solicite aumento de quota *antes* do go-live, não depois. Um evento de pico sem quota adequada resulta em `ThrottlingException` que o cliente final vê como timeout. **Guardrails têm latência:** Cada passagem por Guardrails adiciona 100-300ms de latência. Em um agente com 10 turnos, isso é até 3 segundos adicionais de latência acumulada. Para casos de uso onde latência é crítica, avalie desabilitar guardrails de output em ferramentas internas (não expostas ao usuário final) e aplicar apenas no output final. **Memória não é gratuita:** AgentCore Memory cobra por armazenamento e por operação de leitura/escrita. Em sessões longas com `SESSION_SUMMARY` ativo, o custo de memória pode superar o custo de inferência para sessões curtas. Monitore `MemoryReadLatency` e `MemoryWriteLatency`, acima de 200ms indica pressão no store gerenciado. **Human-in-the-loop não é automático:** `requireConfirmation: ENABLED` no Gateway pausa a execução e aguarda confirmação via callback. Se o cliente não responder em `confirmationTimeout` (padrão: 300s), a sessão expira. Projete o UX para deixar isso claro ao usuário, sessões expiradas por timeout são a principal causa de reclamação em agentes financeiros. ## Números Reais de Referência - **~40%**: Redução de tokens com SESSION_SUMMARY. Em sessões com mais de 20 turnos, SESSION_SUMMARY reduz o contexto enviado ao modelo em ~40% vs. histórico completo - **100-300ms**: Latência adicionada por Guardrails por turno. Cada avaliação de Guardrail (input + output) adiciona 100-300ms; em 10 turnos, até 3s acumulados - **7 anos**: Retenção mínima de CloudTrail para conformidade financeira. S3 Object Lock em modo COMPLIANCE com 7 anos atende requisitos do Banco Central do Brasil e SEC para trilha de auditoria de agentes ## Avaliação Well-Architected - **security**: Guardrails declarativos com filtro de PII e tópicos negados; AgentCore Gateway com OAuth2/OIDC por ferramenta; KMS CMK para memória de sessão; CloudTrail com S3 Object Lock para auditoria imutável. IAM com condição `bedrock:AgentArnLike` para restringir quais agentes podem invocar quais ferramentas. - **reliability**: Retry automático com jitter no SDK Bedrock (max_attempts=3, mode=adaptive); circuit breaker nativo no AgentCore Gateway por ferramenta; timeout de sessão configurável evita sessões zumbi; quotas de concurrent sessions devem ser solicitadas antes do go-live. - **performance**: SESSION_SUMMARY reduz tokens de contexto em ~40% para sessões longas; desabilitar guardrails de output em ferramentas internas reduz latência acumulada; Knowledge Base com OpenSearch k-NN com HNSW e ef_search=512 para RAG de baixa latência. - **cost**: Budget AWS com alerta em 80% do limite mensal; alarme CloudWatch em invocações/hora por model-id; SESSION_SUMMARY reduz custo de inferência em sessões longas; monitorar custo de AgentCore Memory separadamente do custo de inferência. ## O Que Não Está no Blog da AWS ## 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. ## Anti-Padrões que Vi em Revisões de Arquitetura - Usar AgentCore sem configurar Guardrails porque "é ambiente interno", insiders são a principal fonte de incidentes de compliance em finanças - Armazenar o histórico completo de sessão na memória sem SESSION_SUMMARY, custo de tokens cresce linearmente com o número de turnos - Implementar lógica de negócio crítica dentro do system prompt do agente em vez de em ferramentas testáveis, prompts não têm testes unitários - Não solicitar aumento de quota de concurrent sessions antes do go-live: ThrottlingException em pico de uso é previsível e evitável - Assumir que o AgentCore Gateway substitui uma camada de autorização de negócio, o Gateway controla acesso à ferramenta, não a lógica de autorização dentro da ferramenta - Não implementar idempotência em Lambdas de ferramentas com efeitos colaterais, retries do runtime podem duplicar ações irreversíveis > **Nota do Curador:** Na prática, o que me convenceu a adotar AgentCore não foi nenhuma feature individual, foi o fato de que o **AgentCore Gateway com OAuth2/OIDC por ferramenta** resolve o problema de identidade de tool-call que eu estava prestes a construir manualmente, e que teria levado dois sprints e gerado dívida técnica permanente. A lição dura por trás disso: em ambientes financeiros, o custo de construir controles de segurança customizados não é o custo de desenvolvimento inicial, é o custo de manter, auditar e corrigir esses controles ao longo de anos. Quando um serviço gerenciado entrega o controle como configuração declarativa, a decisão de adotá-lo raramente é sobre feature parity; é sobre onde você quer alocar a atenção de engenharia da sua equipe. Minha recomendação: adote AgentCore para novos agentes em produção, mantenha as ferramentas portáveis, e invista o tempo economizado em observabilidade e testes de adversarial prompting. ## Veredicto: Adote com Controles Explícitos Bedrock AgentCore é a escolha certa para times financeiros que precisam colocar agentes de IA em produção sem construir e manter um runtime de orquestração customizado. A decisão não é binária, é sobre reconhecer que o valor do AgentCore está nos controles operacionais (Gateway, Guardrails, Memory com CMK), não apenas no runtime de execução. A condição para adoção é clara: configure Guardrails antes de qualquer teste com dados reais, implemente idempotência em todas as ferramentas com efeitos colaterais, solicite aumento de quota de concurrent sessions antes do go-live, e monitore TurnsPerSession e TokensPerSession como métricas de SLO de primeira classe. O lock-in é real mas gerenciável se as ferramentas forem mantidas portáveis. Para times que não têm capacidade de construir e operar um runtime de agentes customizado, que é a maioria: AgentCore é a decisão arquitetural correta em 2025. ## Referências - [Amazon Bedrock AgentCore: Developer Guide](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/what-is-bedrock-agentcore.html) - [Amazon Bedrock Guardrails: Configuration Reference](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails.html) - [Amazon Bedrock AgentCore Memory: Developer Guide](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/memory.html) - [Building AI agents with Amazon Bedrock AgentCore: AWS ML Blog](https://aws.amazon.com/blogs/machine-learning/) - [AWS Well-Architected Framework: Machine Learning Lens](https://docs.aws.amazon.com/wellarchitected/latest/machine-learning-lens/welcome.html) - [Idempotency for AWS Lambda: Powertools for AWS Lambda](https://docs.powertools.aws.dev/lambda/python/latest/utilities/idempotency/) - [Architecture Decision Records: Michael Nygard](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions) - [Amazon OpenSearch Service, k-NN Search with HNSW](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/knn.html) ## Fontes do caso - [Building AI agents with Amazon Bedrock AgentCore: AWS ML Blog](https://aws.amazon.com/blogs/machine-learning/) - [Amazon Bedrock AgentCore: Developer Guide](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/what-is-bedrock-agentcore.html) - [Amazon Bedrock Guardrails: Configuration Reference](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails.html) - [Amazon Bedrock AgentCore Memory: Developer Guide](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/memory.html)