LangGraph

1. Visão geral da conceção e problema sistémico

As tentativas de construir agentes robustos para produção utilizando simples ciclos while True em Python ou cadeias lineares esbarram rapidamente com limitações críticas de engenharia:

1. Ausência de persistência: Se o servidor reiniciar durante um processo agentic de 5 minutos, todo o estado atual e o progresso são irremediavelmente perdidos.
2. Incontrolabilidade do fluxo (Problema da Caixa Negra): É difícil prever quando o agente decidirá concluir a tarefa ou como forçá-lo a retroceder uma etapa em caso de erro de validação.
3. Impossibilidade de pausas prolongadas (Human-in-the-Loop): Pausar a execução do programa aguardando confirmação do usuário sem bloquear a memória do processo é extremamente complexo no código convencional.

LangGraph resolve esses problemas modelando sistemas agenticos como Grafos de Estado Orientados (Stateful Graphs). Qualquer processo complexo é decomposto em nós transparentes (Nodes), arestas de transição (Edges) e um único tipo de estado tipado (State), que é registrado atomicamente no banco de dados após cada passo.

2. Taxonomia arquitetural e modelo mental

A arquitetura LangGraph é construída em torno de quatro entidades principais:

• 1. Shared State (Estado Compartilhado): Interface estritamente tipada (via TypedDict ou Pydantic). Define o esquema de dados acessível a todos os nós. Para campos específicos, podem ser definidos redutores (Reducers), por exemplo, Annotated[list, add_messages], que automaticamente anexam novas mensagens em vez de sobrescrever o array.
• 2. Nodes (Nós do Grafo): Funções síncronas ou assíncronas comuns. Cada nó recebe o estado atual, executa cálculos (chamada ao modelo, execução de testes ou consulta ao BD) e retorna uma atualização parcial do estado (State Delta).
• 3. Edges & Conditional Edges (Arestas de Transição):
  • Arestas comuns: transição determinística do nó A para o nó B.
  • Arestas condicionais: uma função roteadora analisa a última saída do modelo e decide para onde direcionar o fluxo (por exemplo: se uma ferramenta foi chamada — ir para tools; se uma resposta final foi encontrada — ir para END).
• 4. Checkpointers (Checkpointers): Drivers de armazenamento de longo prazo (MemorySaver para testes, PostgresSaver / SqliteSaver para produção). Criam snapshots imutáveis em cada superstep.

3. Pipeline técnico e mecânica interna

A execução do grafo segue o modelo de paralelismo síncrono em massa (Bulk Synchronous Parallel, BSP):

1. State Initialization (Início da sessão): O grafo recebe a entrada inicial e um objeto de configuração com a chave thread_id. O checkpointer carrega o último estado salvo para essa thread.
2. Superstep Execution (Execução do superstep): Todos os nós ativos na fase atual são executados em paralelo. Cada nó lê um snapshot idêntico do estado e gera seu patch de atualização.
3. Reducer Aggregation & Checkpoint Commit (Agregação de estado via Reducer): Após a conclusão de todos os nós da fase, o sistema aplica os redutores às mudanças recebidas, forma um novo estado e registra-o atomicamente no banco de dados.
4. Edge Routing & Interrupt Inspection (Roteamento e verificação de pausas): As transições condicionais são avaliadas. Se o grafo encontrar um ponto de interrupção (interrupt_before), a execução é concluída com segurança, devolvendo o controle à aplicação externa.

4. Cenários práticos de engenharia em produção

01. Ciclo autônomo de desenvolvimento e correção de erros de código

Grafo com quatro nós:

• generate_code -> run_unit_tests -> evaluate_output.
• Se os testes passarem com sucesso — transição para create_pr.
• Se os testes falharem — uma aresta condicional retorna o estado para generate_code junto com o stacktrace do erro (com limite máximo de 5 iterações).

02. Processo financeiro Human-in-the-Loop

O agente analisa faturas conflitantes de clientes. Se o valor do reembolso for inferior a $100, o grafo executa o reembolso automaticamente através do nó execute_refund. Se o valor for superior — o grafo é interrompido (interrupt), gera um link para um formulário de aprovação para o gerente e retoma a operação apenas após receber um webhook humano.

03. Sistema multiagente "Supervisor — Especialistas"

O nó central Supervisor atua como roteador de alto nível. Dependendo do tipo de tarefa, ele alterna o contexto entre subgrafos especializados: ResearchSubgraph (busca na internet e análise) e DraftingSubgraph (geração de contratos), mantendo o controle sobre um único contexto corporativo.

5. Armadilhas, erros comuns e segurança

• Inchaço do Estado (State Bloat): Armazenar arquivos PDF gigabytes ou tabelas massivas no estado compartilhado faz com que cada checkpoint no PostgreSQL leve centenas de milissegundos. Guarde apenas metadados leves e URLs de artefatos no S3 dentro do estado.
• Recursion Limit Exceeded: Se as arestas condicionais não tiverem uma saída garantida do ciclo, a execução falhará com um erro de sistema atingindo o limite de profundidade (padrão de 25 passos). Sempre monitore o contador de tentativas diretamente no esquema do estado.
• Objetos não serializáveis no State: Tentar salvar descritores de arquivo abertos, conexões de banco de dados ou closures funcionais no estado resultará na falha do checkpointer ao tentar serializar para JSON/Pickle.