# Playbook: Um Agente de IA de Produção na AWS em 7 Passos

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.

- URL: https://fernando.moretes.com/studies/playbook-agente-de-producao-na-aws-7-passos

- Markdown: https://fernando.moretes.com/studies/playbook-agente-de-producao-na-aws-7-passos/study.md?lang=pt

- Type: Playbook

- Domain: IA / Agentes

- Date: 2025-11-18

- Tags: agents, bedrock, agentcore, genai, aws, production, observability, guardrails

- Reading time: 11 min

---

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

- Qual topologia de loop usar para cada caso de uso (linear, reflection, plan-execute, multi-agente)
- Como definir ferramentas com escopo mínimo de IAM e allowlist explícita
- Por que o verifier nunca pode ser o próprio agente — e o que usar no lugar
- Como configurar stop rules com orçamento de iterações, tokens e custo
- Quais sinais de observabilidade coletar por iteração do loop
- Como estruturar guardrails e trilha de auditoria no Bedrock AgentCore

## 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
| Critério | 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:GetObject` em um bucket específico, não `s3:*`); (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), ou `FAIL_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, configure `maxIterations`; 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.

### 🌐 Trigger Layer

- API Gateway REST / WebSocket (edge)
- EventBridge Event / Schedule (messaging)
- SQS Async Queue (messaging)

### ⚙️ AgentCore Managed Zone

- AgentCore Runtime maxIterations / timeout / turns (ai)
- AgentCore Memory Session + Long-term (data)
- AgentCore Identity OAuth2 / IAM Role (security)
- AgentCore Gateway MCP / Schema Validation (network)
- AgentCore Observability Trace / Tokens / Latency (ai)

### 🤖 Model + Loop

- Bedrock Model Claude / Titan / Llama (ai)
- Stop Rule Check code-verifiable condition (compute)

### 🔧 Tools (Least Privilege)

- Tool Lambda IAM scoped / allowlist (compute)
- External API (via Gateway proxy) (external)

### ✅ Verifier Layer

- Deterministic Verifier Lambda / schema / invariants (compute)
- LLM Verifier Smaller model / eval prompt (ai)
- AgentCore Guardrail PII / topics / grounding (security)

### 📊 Observability + Audit

- CloudWatch Logs 90d retention / per-agent group (storage)
- X-Ray Traces per-iteration spans (storage)
- S3 Object Lock WORM audit trail (storage)
- CloudWatch Dashboard cost / iterations / p99 (frontend)

### Fluxos

- api_gw -> ac_runtime: invoca
- eventbridge -> ac_runtime: dispara
- sqs -> ac_runtime: enfileira
- ac_runtime -> ac_memory: lê/escreve sessão
- ac_runtime -> ac_identity: obtém credenciais
- ac_runtime -> bedrock_model: prompt + contexto
- bedrock_model -> ac_runtime: ação / resposta
- ac_runtime -> stop_rule: verifica a cada iteração
- stop_rule -> ac_runtime: CONTINUE / STOP
- ac_runtime -> ac_gateway: tool call (MCP)
- ac_gateway -> tool_lambda: executa (IAM scoped)
- ac_gateway -> tool_ext: proxy externo
- tool_lambda -> ac_gateway: resultado
- ac_gateway -> ac_runtime: tool result
- ac_runtime -> verifier_det: saída do agente
- ac_runtime -> verifier_llm: saída do agente
- verifier_det -> guardrail: PASS → guardrail
- verifier_llm -> guardrail: PASS → guardrail
- verifier_det -> ac_runtime: FAIL_SOFT → reitera
- ac_runtime -> ac_obs: trace por iteração
- ac_obs -> cw_logs: logs estruturados
- ac_obs -> xray: spans
- guardrail -> s3_audit: decisão auditada
- cw_logs -> cw_dash: métricas

> **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 produto.**

> **Minha perspectiva sênior: o que eu faço de verdade:** 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.

## Referências

- [AWS — Amazon Bedrock AgentCore (product page)](https://aws.amazon.com/bedrock/agentcore/)
- [AWS Docs — What is Amazon Bedrock AgentCore](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/what-is-bedrock-agentcore.html)
- [Anthropic Engineering — Building Effective Agents](https://www.anthropic.com/engineering/building-effective-agents)
- [AWS Docs — Observability for Amazon Bedrock AgentCore](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/observability.html)

## Fontes do caso

- [AWS — Amazon Bedrock AgentCore](https://aws.amazon.com/bedrock/agentcore/)
- [AWS docs — What is Bedrock AgentCore](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/what-is-bedrock-agentcore.html)
- [Anthropic — Building effective agents](https://www.anthropic.com/engineering/building-effective-agents)
- [AWS — Observability for Bedrock AgentCore](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/observability.html)