Playbook: Um Agente de IA de Produção na AWS em 7 Passos
Ouvir estudo
gerado ao ouvirGerado apenas no primeiro play
Com tecnologia Amazon Polly + OmniVoice
Noventa por cento dos agentes de IA morrem no notebook. Este playbook cobre os 7 passos que separam um protótipo funcional de um agente confiável em produção na AWS — do trigger ao guardrail, passando por topologia de loop, ferramentas com menor privilégio, verifier externo e orçamento de execução. Opinioso, concreto e baseado nas primitivas reais do Amazon Bedrock AgentCore.
Construir um agente que funciona no notebook é fácil. Colocar esse agente em produção — com custo controlado, rastreabilidade, segurança e parada garantida — é onde a maioria das equipes para. Este playbook é o mapa dos 7 passos que você precisa percorrer, na ordem certa, com as decisões certas.
TL;DR — O que você vai conseguir decidir depois de ler isso
Contexto do Playbook
- Tipo
- Playbook prescritivo — agnóstico de empresa, baseado em AWS
- Plataforma principal
- Amazon Bedrock AgentCore (Runtime, Gateway, Memory, Identity, Observability)
- Modelos cobertos
- Qualquer modelo via Bedrock (Claude, Titan, Llama, etc.)
- Padrão de referência
- Anthropic 'Building Effective Agents' + primitivas AgentCore
- Onde 90% para
- Passagem do notebook para produção: sem orçamento, sem verifier, sem observabilidade
- Pré-requisito mínimo
- Conta AWS, acesso ao Bedrock habilitado, IAM básico configurado
O modelo mental que desbloqueia tudo: o agente é um loop com orçamento
A diferença entre um agente de notebook e um agente de produção não é o modelo — é a estrutura ao redor do loop. Um agente, na sua essência, é um ciclo: o modelo observa o estado atual, decide uma ação, executa via ferramenta, observa o resultado, e decide se termina ou itera. Esse ciclo pode rodar uma vez ou mil vezes. Em produção, você precisa saber exatamente quantas vezes ele vai rodar, quanto vai custar, e como você vai saber que ele terminou corretamente.
A Anthropic descreve isso com precisão no 'Building Effective Agents': a maioria dos sistemas agênticos bem-sucedidos não é um agente autônomo complexo — é um conjunto de fluxos de trabalho aumentados com LLM onde a autonomia é aplicada cirurgicamente. O erro mais comum é dar ao agente mais autonomia do que o problema exige. Um pipeline linear com uma chamada de ferramenta resolve 70% dos casos. O loop com reflection resolve mais 20%. Multi-agente com orquestração é para os 10% restantes — e cobra um preço alto em complexidade e custo.
O Amazon Bedrock AgentCore materializa esse modelo mental em primitivas concretas: o Runtime executa o loop; o Gateway gerencia o acesso às ferramentas com controle de protocolo (MCP); o Memory persiste estado entre sessões; o Identity gerencia credenciais e permissões do agente; a Observability rastreia cada iteração. Quando você estrutura seu agente em torno dessas cinco primitivas, você está forçando as perguntas certas antes de escrever código.
Topologias de Loop de Agente — Quando Usar Cada Uma
| Topologia | Estrutura | Custo relativo | Latência | Complexidade ops | |
|---|---|---|---|---|---|
| Linear (pipeline) | Prompt → Tool → Resposta (1 iteração) | $ (mínimo) | Baixa | Mínima | Tarefa bem definida, saída previsível |
| Reflection | Gera → Critica → Refina (N iterações) | $$ (2–4x linear) | Média | Baixa | Qualidade de saída importa mais que velocidade |
| Plan-Execute | Plano → Sub-tarefas → Execução sequencial | $$$ (3–6x linear) | Alta | Média | Tarefas longas com dependências entre passos |
| Multi-agente | Orquestrador + N agentes especializados | $$$$ (mais alto) | Alta / variável | Alta | Paralelismo real; domínios isolados por segurança |
Por que o verifier externo não é opcional
O erro de arquitetura mais frequente que vejo em agentes de produção é o agente avaliando sua própria saída. Isso é equivalente a pedir para um desenvolvedor fazer o code review do próprio PR sem nenhum revisor externo — funciona às vezes, falha sistematicamente quando importa.
Um verifier externo é qualquer mecanismo que avalia a saída do agente sem usar o mesmo modelo com o mesmo contexto. As opções práticas são: (1) um segundo modelo menor e mais barato com um prompt de avaliação focado; (2) uma função Lambda determinística que valida schema, range, ou invariantes de negócio; (3) um conjunto de testes unitários executados como ferramenta; (4) um humano no loop para casos de alto risco. O Bedrock AgentCore suporta esse padrão nativamente via Guardrails configuráveis que interceptam saídas antes de retornar ao caller.
A regra prática: se a falha do agente tem consequência financeira, legal ou de segurança, o verifier deve ser determinístico (código, não LLM). Se a falha é de qualidade de conteúdo, um segundo LLM com prompt de avaliação é suficiente. Nunca use o mesmo modelo, o mesmo prompt, e o mesmo contexto para gerar e verificar — você está apenas amplificando o viés original.
Os 7 Passos: Do Notebook à Produção
- 1
Passo 1 — Defina o TRIGGER com precisão cirúrgica
Antes de qualquer código, responda: o que inicia este agente? As três classes são: (a) Evento — S3 PutObject, SQS message, EventBridge rule; (b) API síncrona — chamada HTTP via API Gateway com resposta esperada em < 30s; (c) Agenda — EventBridge Scheduler para tarefas periódicas. Documente o payload exato do trigger, o SLA de resposta esperado, e se o caller espera resposta síncrona ou aceita async com callback. Isso determina se você usa Lambda (< 15 min), ECS Fargate (longa duração), ou o AgentCore Runtime diretamente. Testável: você consegue disparar o agente manualmente com um payload sintético e verificar que ele inicia? Se não, o trigger não está definido.
- 2
Passo 2 — Escolha a TOPOLOGIA do loop (use a tabela de comparação)
Use a tabela de comparação acima. A regra de ouro: comece sempre com o mais simples que resolve o problema. Se linear resolve, não implemente reflection. Se um agente único resolve, não implemente multi-agente. Documente a topologia escolhida e o motivo — isso vai ser questionado em code review e em post-mortems. Para o AgentCore, a topologia determina como você configura o AgentCore Runtime: número de turnos máximos, se memory está habilitada (para reflection e plan-execute você precisa de session memory), e se você vai usar sub-agentes. Testável: você consegue desenhar o loop em um diagrama de sequência com no máximo 5 caixas? Se não, está complexo demais.
- 3
Passo 3 — Defina FERRAMENTAS com menor privilégio
Cada ferramenta que o agente pode chamar é uma superfície de ataque. Use o AgentCore Gateway com protocolo MCP para registrar ferramentas com escopo explícito. Para cada ferramenta, defina: (1) IAM role dedicada para o agente — nunca AdministratorAccess, nunca PowerUser; (2) Allowlist explícita de ações permitidas (ex:
s3:GetObjectem um bucket específico, nãos3:*); (3) Schema de input/output validado — o AgentCore Gateway valida o schema antes de executar; (4) Timeout por ferramenta — defina no Gateway, não confie no timeout do Lambda downstream. Regra prática: se você não consegue listar em 3 linhas o que a ferramenta faz e o que ela não pode fazer, o escopo está largo demais. - 4
Passo 4 — Implemente um VERIFIER externo
O verifier avalia a saída do agente antes de ela ser entregue ao caller ou persistida. Implemente como: (a) Lambda determinística para validação de schema e invariantes de negócio (custo: centavos, latência: < 100ms); (b) Segundo modelo Bedrock com prompt de avaliação focado para qualidade de conteúdo (use um modelo menor — Claude Haiku ou similar); (c) Guardrail do AgentCore para filtragem de conteúdo, PII, e tópicos proibidos — configure via console ou IaC (CDK/Terraform). O verifier deve retornar:
PASS,FAIL_HARD(para o loop, retorna erro ao caller), ouFAIL_SOFT(itera novamente com feedback). Documente qual classe de falha aciona cada resposta. Testável: injete uma saída deliberadamente incorreta e confirme que o verifier a rejeita com o código de erro correto. - 5
Passo 5 — Configure STOP RULES e orçamento de execução
Um agente sem stop rules é um processo sem
ulimit— vai consumir recursos até o timeout da infraestrutura, que é o pior lugar para parar. Defina explicitamente: (1) Máximo de iterações — no AgentCore Runtime, configuremaxIterations; comece conservador (5–10) e ajuste com dados; (2) Timeout total — configure no nível do Runtime E no Lambda/Fargate que o hospeda; use o menor dos dois; (3) Teto de tokens — estime o custo por iteração, multiplique pelo máximo de iterações, defina um teto em tokens de input+output; o AgentCore expõe métricas de tokens por invocação; (4) Teto de custo — use AWS Budgets com alerta em 80% do teto mensal esperado para o agente; (5) Condição de parada verificável por código — a condição de término deve ser testável sem chamar o LLM (ex: - 6
Passo 6 — Implemente OBSERVABILIDADE do loop
Você não pode operar o que não consegue observar. Para agentes, observabilidade tem uma dimensão extra: você precisa de visibilidade por iteração, não apenas por invocação. O AgentCore Observability emite traces estruturados com: número da iteração, tokens consumidos, ferramenta chamada, latência da ferramenta, decisão do modelo (continuar/parar), e resultado do verifier. Configure: (1) CloudWatch Logs com log group dedicado por agente, retenção de 90 dias mínimo para auditoria; (2) X-Ray trace habilitado no AgentCore Runtime — cada iteração do loop aparece como um span filho; (3) Métricas customizadas via CloudWatch EMF:
agent.iterations_per_invocation,agent.tokens_per_invocation,agent.tool_call_latency_ms,agent.verifier_fail_rate; (4) Dashboard CloudWatch - 7
Passo 7 — Configure GUARDRAILS e trilha de auditoria
Guardrails não são opcionais em produção — são o contrato entre o agente e o negócio. No AgentCore, configure: (1) Content filtering — defina categorias proibidas (violência, PII, dados financeiros não autorizados) com threshold por categoria; (2) Topic denial — lista explícita de tópicos que o agente não deve abordar, independente do prompt do usuário; (3) Grounding check — para agentes RAG, valide que a resposta está ancorada nas fontes recuperadas (AgentCore suporta isso nativamente); (4) Sensitive information redaction — configure redação automática de PII antes de logar (LGPD/GDPR compliance); (5) Audit trail imutável — use S3 com Object Lock (WORM) para armazenar logs de decisão do agente; configure CloudTrail para capturar todas as chamadas à API do AgentCore.
O que o AgentCore resolve que você não quer construir do zero
Antes do AgentCore, montar a infraestrutura ao redor de um agente Bedrock exigia: uma camada de session management manual (DynamoDB + lógica de contexto), integração de ferramentas via Lambda com tratamento de erros customizado, observabilidade montada à mão com X-Ray SDK, e gerenciamento de credenciais do agente via Secrets Manager com rotação manual. Cada uma dessas peças é resolvível individualmente — o problema é que elas precisam funcionar juntas de forma coerente sob carga, com falhas parciais, e com rastreabilidade entre camadas.
O AgentCore oferece cinco primitivas gerenciadas que eliminam esse trabalho de plataforma: Runtime (execução do loop com controle de turnos, session memory integrada, e integração nativa com modelos Bedrock); Gateway (proxy de ferramentas com suporte a MCP, validação de schema, e controle de acesso por ferramenta); Memory (memória de sessão e memória de longo prazo com vetorização automática); Identity (credenciais OAuth 2.0 gerenciadas para o agente, sem segredos hardcoded); Observability (traces estruturados por iteração, métricas de tokens, e integração com CloudWatch e X-Ray).
O trade-off honesto: você ganha velocidade de implementação e consistência operacional, mas aceita acoplamento com a AWS e os limites de configuração do serviço gerenciado. Para equipes pequenas ou projetos com prazo, o AgentCore é a escolha certa. Para plataformas de agentes em grande escala com requisitos muito específicos de customização, pode valer a pena construir sobre as primitivas mais baixas do Bedrock. Mas esse é um problema de 1% das equipes.
Arquitetura de Referência: Agente de Produção com AgentCore
Fluxo completo de uma invocação: do trigger externo ao resultado auditado, passando pelo loop com verifier e stop rules. As cinco primitivas do AgentCore são destacadas como zona gerenciada.
- API Gateway · REST / WebSocket
- EventBridge · Event / Schedule
- SQS · Async Queue
- AgentCore Runtime · maxIterations / timeout / turns
- AgentCore Memory · Session + Long-term
- AgentCore Identity · OAuth2 / IAM Role
- AgentCore Gateway · MCP / Schema Validation
- AgentCore Observability · Trace / Tokens / Latency
- Bedrock Model · Claude / Titan / Llama
- Stop Rule Check · code-verifiable condition
- Tool Lambda · IAM scoped / allowlist
- External API · (via Gateway proxy)
- Deterministic Verifier · Lambda / schema / invariants
- LLM Verifier · Smaller model / eval prompt
- AgentCore Guardrail · PII / topics / grounding
- CloudWatch Logs · 90d retention / per-agent group
- X-Ray Traces · per-iteration spans
- S3 Object Lock · WORM audit trail
- CloudWatch Dashboard · cost / iterations / p99
Anti-padrões que vão te morder em produção
1. Loop sem orçamento: Agente configurado sem maxIterations e sem timeout explícito. Em produção, um prompt ambíguo pode fazer o agente iterar indefinidamente até o timeout do Lambda (15 min) ou do Fargate — gerando custo de tokens sem resultado útil e sem alarme. Sempre defina maxIterations no Runtime e um timeout independente na infraestrutura de hospedagem.
2. Verifier = o próprio agente: Usar o mesmo modelo com o mesmo contexto para gerar e avaliar a saída é o anti-padrão mais comum. O modelo vai confirmar sua própria saída quase sempre — você criou um sistema de auto-validação com viés positivo sistemático. Use um segundo modelo menor, uma Lambda determinística, ou um guardrail configurado.
3. Ferramenta com privilégio excessivo: Uma tool com s3: ou dynamodb: transforma o agente em um vetor de ataque. Se o modelo for induzido (prompt injection via dado externo) a chamar a ferramenta com parâmetros maliciosos, o dano é proporcional ao privilégio. Aplique IAM com resource ARN específico e condition keys. Use o AgentCore Gateway para validar o schema do input antes de executar.
4. Observabilidade só no nível de invocação: Logar apenas o input e o output final esconde o que aconteceu dentro do loop. Quando um agente falha após 8 iterações, você precisa saber o que aconteceu na iteração 5. Configure traces por iteração desde o início — retroativamente é muito mais caro.
5. Multi-agente como primeira escolha: Multi-agente multiplica a complexidade de debugging, o custo de tokens, e a superfície de falha. Comece simples. Promova para multi-agente apenas quando um agente único demonstravelmente não resolve.
Regra de Bolso
Se o agente não tem orçamento, não tem verifier externo, e não tem trace por iteração, ele não está em produção — está em staging com tráfego real. Ou mais curto: **sem stop rule + sem verifier + sem trace por iteração = protótipo, não
Depois de trabalhar com sistemas financeiros onde uma ação incorreta tem consequência real e imediata, desenvolvi um reflexo: nunca confio em um agente que não consigo auditar iteração por iteração. Não é paranoia — é a mesma disciplina que aplicamos a qualquer sistema que toma decisões com efeito colateral. Na prática, quando começo um novo agente, faço três perguntas antes de escrever qualquer código: (1) O que acontece se o agente iterar 10x mais do que o esperado? (2) Quem valida que a saída está correta — e esse validador é independente do gerador? (3) Se esse agente for comprometido por prompt injection, qual é o raio de explosão máximo com as permissões que ele tem? Se eu não consigo responder as três em 5 minutos, o design não está maduro o suficiente para começar a implementar. Sobre o AgentCore especificamente: é genuinamente útil para equipes que não querem montar a camada de plataforma do zero. O Gateway com MCP é a peça que mais me impressionou — resolver o problema de registro e validação de ferramentas de forma padronizada é algo que eu via equipes reimplementando de formas diferentes em cada projeto. O trade-off de acoplamento com AWS é real, mas para a maioria dos casos de uso empresariais, já estamos profundamente acoplados de qualquer forma. O que eu não faço: não uso multi-agente até ter evidência concreta de que um agente único não resolve. A complexidade de debugging de sistemas multi-agente em produção é substancialmente maior — e a maioria dos problemas que eu vejo sendo resolvidos com multi-agente poderiam ser resolvidos com um agente único e ferramentas bem definidas.
Veredicto
A maioria dos agentes de IA não falha porque o modelo é ruim — falha porque a infraestrutura ao redor do loop não foi projetada. Um agente de produção é um sistema distribuído com um componente não-determinístico no centro: ele precisa de orçamento, de verificação externa, de observabilidade por iteração, e de guardrails antes de tocar tráfego real. O Amazon Bedrock AgentCore oferece as primitivas certas para montar essa estrutura sem reinventar plataforma. Os 7 passos deste playbook são a sequência mínima para ir do notebook à produção com responsabilidade. Pule qualquer um deles e você está operando um protótipo com tráfego real — e a diferença vai aparecer no pior momento possível.
Post-mortems, ADRs e deep dives de arquitetura no seu email — do jeito que um arquiteto lê.
Sem spam · cancele quando quiser
Pergunte ao Fernando sobre isto
Receba uma resposta focada sobre este estudo do meu assistente de IA, baseada no meu trabalho.
Participe da conversa
Entre para comentar
Confirme seu e-mail para participar — você também recebe a newsletter. Sem senha.