Playbook: do Prompt ao Pipeline, os 5 Estágios de um Agente Confiável
cerca de 10 min · áudio gerado ao tocar
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
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
| Estágio | Autonomia | Previsibilidade | Custo por run | Risco principal | O que leva ao próximo estágio |
|---|---|---|---|---|---|
| 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.
- Trigger · EventBridge / SQS
- Orquestrador · Step Functions
- Guardrails · Bedrock Guardrails
- Audit Log · CloudTrail + S3 Lock
- Alertas · CloudWatch Alarms
- Verifier · Determinístico / LLM-judge / Human gate
- Approval Gate · Ações irreversíveis
- Loop Controller · max_iter / timeout / budget
- Context Manager · Memória entre iterações
- Tool Executor · IAM least-privilege
- Tools · API / DB / Search / Code
- LLM · Bedrock / Claude / etc.
- Prompt · System + User + Examples
- Usuário / Sistema · Chamador
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,sessionIde 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
runIdde 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.
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
Segurança
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.
Confiabilidade
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.
Eficiência de 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.
Sustentabilidade
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.
Continue lendo
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
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.