# 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/blog/agentes-producao-bedrock-agentcore-risco-operacional - Markdown: https://fernando.moretes.com/blog/agentes-producao-bedrock-agentcore-risco-operacional/article.md?lang=pt - Published: 2026-05-25T14:38:00.000Z - Category: IA & Agentes - Tags: bedrock, agentcore, ai-agents, adr, financial-grade, guardrails, observability, aws - Reading time: 9 min - Source: [Building AI agents with Amazon Bedrock AgentCore](https://aws.amazon.com/blogs/machine-learning/) --- 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/latest/userguide/agents-core.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/latest/userguide/agents-core-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)