Construindo um Fluxo de Trabalho Confiável com LangGraph: Planejar-Executar-Validação (PEV)

A maioria dos exemplos de agentes LangGraph para na frase "olá mundo". Um planejador básico, um executor que chama uma ferramenta de busca e um resultado final impresso. Isso é bom para uma demonstração, mas no momento em que você tenta implementar um agente autônomo em produção, você imediatamente se depara com os mesmos quatro problemas:

1. Como posso evitar que um agente alucine silenciosamente detalhes ausentes entre as etapas?
2. Como posso construir um loop de autocorreção que capture saídas ruins de ferramentas antes que elas contaminem a resposta final?
3. Como posso otimizar custos para não usar modelos de raciocínio caros para simples tarefas administrativas?
4. Como posso integrar com segurança essa camada de orquestração com dados e capacidades empresariais?

Eu passei um tempo resolvendo todos esses problemas em um ambiente de produção real - uma plataforma de ciências da vida regulamentada automatizando fluxos de trabalho científicos sobre dezenas de milhões de registros de pesquisa - e empacotei o resultado como um modelo que qualquer um pode usar: langgraph-plan-execute-validate.

Este post explica as decisões por trás de cada parte.

O que é PEV e por que precisa de um modelo de produção?

O padrão padrão LangGraph de Planejar e Executar tem dois nós: Planejar e Executar. A diferença entre esse rápido início de dois nós e um serviço confiável e implantável é significativa.

Em produção, a qualidade da execução não é binária. Um agente pode tecnicamente completar uma etapa enquanto produz uma saída que é incompleta, alucinatória ou que falta um detalhe crítico. Sem um portão de qualidade, essas falhas se propagam silenciosamente para a próxima etapa.

Você precisa:

• Um Validador estruturado para pontuar saídas
• Um Roteador determinístico para lidar com tentativas e replanejamento
• Uma Trilha de Auditoria para depurar o que realmente aconteceu
• Uma estratégia de múltiplos modelos custo-efetiva

O modelo fornece tudo isso interconectado e funcionando imediatamente.

A Arquitetura

O gráfico adiciona dois nós ao padrão padrão: um Validador que pontua cada saída de etapa e um Roteador (Python puro, sem LLM) que decide o que acontece a seguir.

INÍCIO
  │
planejador ◄──────────────────────────────────────── (replanejar)
  │
executor ◄─────────────────────────────── (tentar novamente)
  │
validador
  │
roteador ─── pontuação ≥ limite, mais etapas ──► executor (próxima etapa)
         ─── pontuação ≥ limite, última etapa ──► FIM (completo)
         ─── pontuação < limite, tentativas restantes ──► executor (tentar novamente)
         ─── pontuação < limite, tentativas esgotadas ──► planejador (replanejar)
         ─── todos os limites esgotados           ──► FIM (falhou)

Visão Geral do Sistema

Máquina de Estados

Problema 1: Falhas Silenciosas em Fluxos de Trabalho de 2 Nós

A abordagem ingênua é passar a saída do Executor diretamente para a próxima etapa. Se a Etapa 1 retornar "Não consegui encontrar os dados", o Executor muitas vezes simplesmente passa para a Etapa 2, alucinado pelo contexto ausente.

O modelo resolve isso introduzindo um terceiro nó: um Validador estruturado que pontua cada saída de etapa (0.0–1.0) em relação à intenção original.

cfg = PEVConfig(
    # Portão de qualidade
    pass_threshold = 0.80,    # pontuação >= isso -> etapa passa
    # Guardas de Loop
    max_retries  = 2,         # tentativas por etapa antes de escalar para replanejamento
    max_replans  = 1,         # ciclos completos de replanejamento antes de marcar como falhado
)

Se a pontuação estiver abaixo do pass_threshold, o sistema não avança - ele se recupera. O validador produz uma saída estruturada com uma pontuação numérica e uma explicação de uma frase, que é injetada no prompt da próxima tentativa.

Problema 2: Tentativas Automáticas e Replanejamento

Quando uma execução falha na validação, lançar uma exceção ou falhar toda a execução é frágil. O LLM precisa de uma chance de se corrigir.

O modelo usa um nó Roteador em Python puro que implementa uma lógica de recuperação determinística. Quando uma etapa pontua abaixo do limite, o Roteador injeta o feedback do Validador diretamente no próximo prompt e aciona uma nova tentativa:

# O Roteador decide como se recuperar - sem LLM envolvido
if score >= cfg.pass_threshold:
    next_idx = idx + 1
    if next_idx >= len(plan):
        return {"status
Contexto Triplo Up
Empresas brasileiras que utilizam agentes de IA podem se beneficiar de um fluxo de trabalho estruturado que minimiza falhas e otimiza custos. A implementação de um sistema de validação e recuperação pode aumentar a confiabilidade dos serviços automatizados, essencial em setores regulados.