# Playbook: do Prompt ao Pipeline — os 5 Estágios de um Agente Confiável

Um agente não nasce confiável — ele é construído estágio a estágio, do prompt simples ao sistema operável com observabilidade, guardrails e auditoria. Este playbook mapeia cada estágio, o que você ganha, o que você arrisca, e quando parar de subir a escada. O gargalo não é o prompt; é o sistema em volta.

- URL: https://fernando.moretes.com/studies/playbook-do-prompt-ao-pipeline-maturidade-de-agente

- Markdown: https://fernando.moretes.com/studies/playbook-do-prompt-ao-pipeline-maturidade-de-agente/study.md?lang=pt

- Type: Playbook

- Domain: IA / Agentes

- Date: 2025-10-05

- Tags: agents, llm, genai, aws-bedrock, react, pipeline, observability, guardrails

- Reading time: 10 min

---

Todo mundo começa com um prompt. Poucos chegam a um agente que funciona em produção sem explodir o orçamento, travar em loop ou tomar ações que ninguém autorizou. O problema não é o modelo — é a ausência de estrutura ao redor dele.

## O que você vai conseguir decidir depois de ler isso

- Identificar em qual dos 5 estágios o seu sistema atual se encontra
- Saber exatamente o que adicionar para subir um estágio — e o que você arrisca ao fazer isso
- Entender por que o Estágio 4 (Verifier) é o divisor de águas entre 'parece certo' e 'está certo'
- Reconhecer os anti-padrões que matam agentes em produção antes de cometê-los
- Mapear os componentes de infraestrutura necessários em cada estágio no contexto AWS/Bedrock

## Referências de base deste playbook

- **Origem do padrão ReAct:** Yao et al., 2022 — Princeton / Google Brain
- **Referência de design de agentes:** Anthropic Engineering — Building Effective Agents (2024)
- **Plataforma de runtime:** Amazon Bedrock AgentCore (GA 2025)
- **Domínio de aplicação:** Agnóstico — padrão aplicável a qualquer LLM com tool use
- **Escopo do playbook:** Estágios 1–5: do prompt simples ao pipeline operável
- **Custo estimado de ignorar o Estágio 5:** Loops descontrolados podem gerar centenas de chamadas de API em minutos (estimativa baseada em casos públicos)

## O modelo mental que desbloqueia tudo: agente é um sistema, não uma chamada

A maioria dos times chega ao LLM com a mentalidade de uma API REST: você manda um input, recebe um output, fim. Isso funciona para o Estágio 1. O problema é que essa mentalidade persiste quando o sistema ganha ferramentas, loops e autonomia — e aí começa o acidente.

A virada conceitual é simples: **a partir do momento em que o LLM pode agir no mundo — chamar uma API, escrever em banco, enviar e-mail — você não tem mais um modelo de linguagem. Você tem um agente. E agentes são sistemas distribuídos com estado, efeitos colaterais e falhas não-determinísticas.**

Isso muda tudo. Um sistema distribuído precisa de:
- **Limites de execução** (stop rules, token budgets, max iterations)
- **Observabilidade** (traces, spans, métricas de custo por run)
- **Controle de privilégio** (o agente só pode fazer o que precisa fazer — não o que consegue fazer)
- **Verificação externa** (o fato de o LLM ter dito que a resposta está certa não significa que está)
- **Auditoria** (quem autorizou, o que foi executado, qual foi o output)

O ReAct paper de Yao et al. (2022) formalizou o loop Observe→Reason→Act como o núcleo de um agente. O que o paper não resolve — e nenhum paper resolve — é o que acontece quando esse loop roda em produção com dados reais, permissões reais e usuários reais. Esse é o trabalho de engenharia que os Estágios 3, 4 e 5 cobrem.

A Anthropic, no guia de agentes efetivos, coloca de forma direta: *'a complexidade adicional dos workflows agênticos vale a pena somente quando a tarefa requer flexibilidade ou raciocínio em múltiplos passos que fluxos fixos não conseguem entregar.'* Traduzindo: não suba a escada por vaidade técnica. Suba porque o problema exige.

## Os 5 Estágios — o que você adiciona, o que você ganha, o que você arrisca

1. **Estágio 1 — Prompt Simples** — **O que é:** Uma chamada ao LLM. Input → Output. Sem ferramentas, sem loop, sem memória.

**O que você adiciona:** Um prompt bem estruturado (system prompt, exemplos, instrução clara de formato).

**O que você ganha:** Velocidade de iteração máxima. Custo previsível. Zero efeitos colaterais. Ideal para classificação, sumarização, extração de entidades, geração de rascunhos.

**O que você arrisca:** Nada além de uma resposta ruim. O risco é de qualidade, não de integridade do sistema.

**Quando parar aqui:** Se o problema cabe em uma chamada com contexto suficiente, pare aqui. Sério. A maioria dos casos de uso de enterprise cabe neste estágio com prompt engineering cuidadoso.

2. **Estágio 2 — Prompt + Ferramentas (Tool Use)** — **O que é:** O LLM pode chamar funções externas (APIs, buscas, calculadoras, banco de dados). Aqui nasce o agente.

**O que você adiciona:** Definição de tools (schemas JSON), executor de tools, tratamento de erros de tool call.

**O que você ganha:** O modelo passa a agir no mundo. Consultas em tempo real, execução de código, integração com sistemas externos.

**O que você arrisca:** **Escalada de privilégio.** O agente tem as permissões da identidade que executa as tools. Se essa identidade tem acesso de escrita em produção, o agente também tem. Princípio do menor privilégio é obrigatório aqui — não opcional.

**Regra prática:** Cada tool deve ter uma IAM role separada com escopo mínimo. No Bedrock AgentCore, use resource-based policies por tool.

3. **Estágio 3 — Loop (ReAct: Observe → Reason → Act → Repeat)** — **O que é:** O agente itera. Ele observa o resultado de uma ação, raciocina sobre o próximo passo, age novamente. Isso é o padrão ReAct de Yao et al. (2022).

**O que você adiciona:** Loop de execução, gerenciamento de contexto entre iterações, critério de parada (stop rule).

**O que você ganha:** Capacidade de resolver problemas em múltiplos passos. O agente pode corrigir erros intermediários, explorar caminhos alternativos, decompor tarefas complexas.

**O que você arrisca:** **Perda de previsibilidade.** Sem stop rules explícitas, o agente pode loopar indefinidamente. Sem budget de tokens, o custo escala de forma não-linear. Sem limite de iterações, uma tarefa simples pode virar uma corrida de 200 chamadas de API.

**Stop rules obrigatórias:**
1.

4. **Estágio 4 — Verifier (Verificação Externa)** — **O que é:** Um componente separado — pode ser outro LLM call, uma função determinística, ou um conjunto de regras — que valida o output do agente antes de ele ser entregue ou antes de uma ação irreversível ser executada.

**O que você adiciona:** Verifier independente, critérios de validação explícitos, gate de aprovação para ações de alto impacto.

**O que você ganha:** A separação entre *'o agente acredita que está certo'* e *'o output passou em critérios verificáveis'*. Isso é o divisor de águas para produção. Um agente sem verifier é um sistema que confia em si mesmo — e LLMs são notoriamente confiantes mesmo quando erram.

**O que você arrisca:** Latência adicional. Custo adicional (se o verifier for outro LLM). Complexidade de manutenção dos critérios de validação.

5. **Estágio 5 — Pipeline (Sistema Operável)** — **O que é:** O agente vira um sistema que você opera. Tem trigger (evento, schedule, webhook), observabilidade completa, guardrails, orçamento de custo, auditoria e runbook de incidentes.

**O que você adiciona:** Trigger mechanism, distributed tracing (spans por iteração e por tool call), cost tracking por run, guardrails de input/output, audit log imutável, alertas de anomalia, runbook.

**O que você ganha:** Um sistema que você consegue debugar, monitorar, cobrar, auditar e escalar. Sem isso, você tem um protótipo em produção — não um produto.

**O que você arrisca:** Complexidade operacional significativa. Um pipeline mal instrumentado é pior que nenhum pipeline — você tem a falsa sensação de controle.

## Por que o Estágio 4 é o mais subestimado

Times que chegam ao Estágio 3 geralmente ficam animados. O loop funciona. O agente resolve problemas em múltiplos passos. As demos são impressionantes. E aí vai direto para o Estágio 5 — instrumentação, pipeline, deploy.

O problema: eles pularam o Estágio 4.

Sem um verifier externo, o sistema confia na auto-avaliação do LLM. E LLMs são otimistas por design — eles foram treinados para produzir respostas coerentes e confiantes. Um modelo que diz *'verifiquei e o resultado está correto'* não é equivalente a um sistema que verificou de forma independente.

A Anthropic documenta isso explicitamente: em pipelines agênticos, erros se acumulam. Um erro no passo 3 de um processo de 10 passos pode se propagar e amplificar nos passos seguintes. O verifier quebra essa propagação.

Na prática, o verifier mais simples que funciona é uma função determinística: *'o output tem todos os campos obrigatórios? Os valores estão dentro dos ranges esperados? O JSON é válido?'* Isso não é glamouroso, mas captura a maioria dos erros de produção.

Para casos de maior risco — ações financeiras, comunicações externas, modificações de dados — o verifier precisa ser um gate humano ou um segundo modelo com prompt adversarial (*'encontre os erros nesta resposta'*). O custo de um segundo LLM call é trivial comparado ao custo de uma ação incorreta em produção.

Uma heurística que uso: **se você não consegue escrever os critérios do verifier antes de construir o agente, você não entende o problema bem o suficiente para automatizá-lo.**

## Matriz de maturidade por estágio
| Critério | Estágio | Autonomia | Previsibilidade | Custo por run | Risco principal |
| --- | --- | --- | --- | --- | --- |
| 1 — Prompt | Nenhuma | Alta | Fixo e previsível | Qualidade do output | Ferramentas + schemas |
| 2 — Prompt + Tools | Baixa (1 ciclo) | Alta | Baixo + custo de tools | Escalada de privilégio | Loop + stop rules |
| 3 — Loop (ReAct) | Média (multi-step) | Média | Variável (risco de explosão) | Loop infinito, custo descontrolado | Verifier externo |
| 4 — Verifier | Média-alta | Alta (com gates) | Médio + custo do verifier | Falso positivo no verifier | Observabilidade + guardrails + auditoria |
| 5 — Pipeline | Alta (operável) | Alta (com alertas) | Alto (infra + observabilidade) | Complexidade operacional, falsa sensação de controle | — (topo da escada) |

## A Escada: do Prompt ao Pipeline

Cada estágio adiciona componentes ao redor do LLM. O modelo em si não muda — o sistema ao redor dele é que evolui. Leia de baixo para cima: cada camada pressupõe a anterior.

### 🟦 Estágio 5 — Pipeline Operável / Operable Pipeline

- Trigger EventBridge / SQS (messaging)
- Orquestrador Step Functions (compute)
- Guardrails Bedrock Guardrails (security)
- Audit Log CloudTrail + S3 Lock (storage)
- Alertas CloudWatch Alarms (compute)

### 🟩 Estágio 4 — Verifier / Verifier

- Verifier Determinístico / LLM-judge / Human gate (ai)
- Approval Gate Ações irreversíveis (security)

### 🟨 Estágio 3 — Loop ReAct / ReAct Loop

- Loop Controller max_iter / timeout / budget (compute)
- Context Manager Memória entre iterações (data)

### 🟧 Estágio 2 — Tool Use / Tool Use

- Tool Executor IAM least-privilege (compute)
- Tools API / DB / Search / Code (external)

### 🟥 Estágio 1 — LLM Core / LLM Core

- LLM Bedrock / Claude / etc. (ai)
- Prompt System + User + Examples (data)

### 👤 Usuário / User

- Usuário / Sistema Chamador (user)

### Fluxos

- user -> trigger: dispara
- trigger -> orchestrator: inicia run
- orchestrator -> guardrails: filtra input
- guardrails -> loop: input limpo
- loop -> llm: itera
- prompt -> llm: contexto
- llm -> tool_exec: tool call
- tool_exec -> tools: executa
- tools -> tool_exec: resultado
- tool_exec -> context: salva estado
- context -> loop: próxima iteração
- loop -> verifier: output candidato
- verifier -> gate: ação irreversível?
- gate -> orchestrator: aprovado / rejeitado
- verifier -> orchestrator: output validado
- orchestrator -> audit: log imutável
- orchestrator -> alerts: métricas
- orchestrator -> user: resposta final

## O que o Bedrock AgentCore resolve — e o que ele não resolve

O Amazon Bedrock AgentCore (GA 2025) é a aposta da AWS para resolver a infraestrutura dos Estágios 2 a 5 de forma gerenciada. Vale entender o que ele entrega e onde você ainda precisa trabalhar.

**O que o AgentCore resolve:**
- **Gerenciamento de sessão e memória:** contexto persistente entre iterações sem você gerenciar o DynamoDB por baixo
- **Tool execution runtime:** executor gerenciado com retry, timeout e logging automático de tool calls
- **Integração com Bedrock Guardrails:** filtragem de input/output nativa, incluindo detecção de PII e tópicos proibidos
- **Observabilidade básica:** traces de execução integrados ao CloudWatch, com `agentId`, `sessionId` e spans por tool call
- **Controle de acesso:** integração com IAM para definir quais tools o agente pode chamar

**O que o AgentCore NÃO resolve — e você precisa construir:**
- **Verifier externo (Estágio 4):** o AgentCore não tem um componente nativo de verificação independente. Você implementa isso como uma Lambda ou Step Functions state antes de retornar o output
- **Approval gates para ações irreversíveis:** precisa de integração manual com SNS/SES para notificação humana ou Step Functions com `.waitForTaskToken`
- **Cost tracking granular por run:** o AgentCore loga tokens, mas agregar custo por `runId` de negócio requer instrumentação customizada
- **Stop rules de negócio:** `max_iterations` é configurável, mas lógica de parada baseada em critérios de negócio (ex: *'pare se o resultado já é bom o suficiente'*) é responsabilidade sua
- **Audit log imutável:** CloudTrail captura chamadas de API, mas um audit log de negócio com o raciocínio do agente requer gravação explícita em S3 com Object Lock

A conclusão prática: o AgentCore reduz significativamente o trabalho de chegar ao Estágio 3. Ele não substitui a engenharia dos Estágios 4 e 5. Use-o como acelerador, não como solução completa.

> **Anti-padrões que matam agentes em produção:** **1. Subir para o Estágio 3 sem stop rules.** O loop funciona na demo porque a demo tem 3 iterações. Em produção, com dados reais e edge cases, o agente pode iterar 50 vezes antes de você perceber. Defina `max_iterations`, `max_tokens_total` e `timeout` antes de habilitar o loop.

**2. Dar ao agente as permissões do desenvolvedor.** O executor de tools roda com as credenciais de quem configurou. Se você testou com sua IAM role de admin, o agente tem acesso de admin. Crie uma role dedicada com escopo mínimo antes do primeiro deploy.

**3. Pular o Estágio 4 e ir direto para o 5.** Instrumentação não substitui verificação. Você pode ter traces perfeitos de um agente que está produzindo outputs incorretos com confiança.

**4. Usar o mesmo agente para leitura e escrita.** Separe agentes de consulta (read-only) de agentes de ação (write). Isso limita o raio de explosão de um comportamento inesperado.

**5. Não ter runbook de incidente.** Quando o agente travar em produção às 2h da manhã, você precisa saber como parar a execução, como reverter ações, e quem notificar. Documente isso antes do go-live.

**6. Confiar no 'eu verifiquei' do próprio LLM.** Self-verification em LLMs é notoriamente não-confiável. O modelo que gerou o output não deve ser o único a avaliá-lo.

> **Regra de bolso:** **'Se você não consegue descrever o critério de parada e o critério de sucesso antes de construir, você não está pronto para o próximo estágio.'**

Critério de parada = quando o agente deve parar (stop rules, budget, timeout).
Critério de sucesso = como você sabe que o output está correto (verifier criteria).

Sem os dois escritos explicitamente, você está construindo no escuro.

> **Minha perspectiva — o que eu faço na prática:** Depois de trabalhar com sistemas de grau financeiro onde um output incorreto tem consequência real, desenvolvi uma postura clara: **eu trato agentes como sistemas de alto risco desde o Estágio 2 — não a partir do momento em que algo der errado.**

Na prática, isso significa:

**Nunca subo para o Estágio 3 sem ter as stop rules documentadas e testadas.** Não é burocracia — é a diferença entre um run de $0,50 e um run de $500. Já vi loops que consumiram orçamentos mensais em horas porque alguém assumiu que 'o modelo vai parar quando terminar'.

**Implemento o verifier antes de habilitar ações de escrita.** Mesmo que seja um verifier simples — validação de JSON schema, checklist de campos obrigatórios — ele precisa existir antes de qualquer tool que modifica estado. O custo de um segundo LLM call para verificação é trivial; o custo de reverter uma ação incorreta em produção não é.

**Para sistemas financeiros ou com dados sensíveis, o Estágio 4 inclui obrigatoriamente um human-in-the-loop para ações acima de um threshold.** Não importa quão bom seja o agente — há decisões que precisam de assinatura humana. Isso não é limitação técnica; é governança.

**Meu critério para recomendar o Bedrock AgentCore:** se você precisa chegar ao Estágio 3 rapidamente e tem um time pequeno, o AgentCore vale o lock-in. Ele resolve a plumbing de sessão, memória e tool execution. Mas se você tem requisitos de auditoria regulatória ou precisa de portabilidade entre clouds, construa o runtime você mesmo sobre primitivas (Lambda + DynamoDB + SQS) — você terá mais controle sobre o que vai para o audit log.

**O insight que mais muda a conversa com stakeholders:** mostrar a escada de estágios como um mapa de maturidade, não como uma lista de features. Quando o CTO vê que 'agente confiável' é Estágio 5 e que pular estágios tem custos concretos, a conversa sobre timeline e recursos fica muito mais honesta.

## Lentes do Well-Architected por estágio

- **security**: Estágio 2 obriga least-privilege por tool. Estágio 5 exige audit log imutável e guardrails de input/output. Nunca compartilhe credenciais entre tools com escopos diferentes.
- **reliability**: Stop rules (Estágio 3) e verifier (Estágio 4) são os principais mecanismos de confiabilidade. Sem eles, o sistema não tem como detectar ou conter falhas em cascata.
- **performance**: Cada estágio adiciona latência. Meça P95 de latência por estágio. O verifier de LLM-judge pode adicionar 2-5s — avalie se o caso de uso tolera isso.
- **sustainability**: Loops desnecessários consomem energia e geram custo sem valor. Stop rules e critérios de sucesso bem definidos reduzem iterações desperdiçadas.

## Conclusão

A escada de 5 estágios não é uma progressão linear obrigatória — é um mapa de decisão. A maioria dos problemas de enterprise não precisa chegar ao Estágio 5. O que todos os problemas precisam é que você saiba em qual estágio está e por quê.

O erro mais caro não é ficar no Estágio 1 quando o problema exige o Estágio 3. O erro mais caro é subir para o Estágio 3 sem as stop rules do Estágio 3, ou para o Estágio 5 sem o verifier do Estágio 4. Você acumula autonomia sem acumular controle — e aí o sistema não falha de forma previsível; ele falha de forma surpreendente.

**O gargalo não é o prompt. Nunca foi. O gargalo é o sistema em volta — e esse sistema você constrói estágio a estágio, com intenção, ou não constrói.**

## Referências

- [Anthropic Engineering — Building Effective Agents](https://www.anthropic.com/engineering/building-effective-agents)
- [Yao et al. — ReAct: Synergizing Reasoning and Acting in Language Models (2022)](https://arxiv.org/abs/2210.03629)
- [AWS — Amazon Bedrock AgentCore](https://aws.amazon.com/bedrock/agentcore/)

## Fontes do caso

- [Anthropic — Building effective agents](https://www.anthropic.com/engineering/building-effective-agents)
- [Yao et al. — ReAct](https://arxiv.org/abs/2210.03629)
- [AWS — Amazon Bedrock AgentCore](https://aws.amazon.com/bedrock/agentcore/)