Phase 15 - Lesson 12

Agentes de Longa Execução em Segundo Plano: Execução Durável

Agentes de longo horizonte em produção não rodam em while True. Cada chamada de LLM se torna uma atividade com checkpoint, tentativa (retry) e reprodução (replay). A integração do SDK de Agentes da OpenAI do Temporal entrou em GA em março de 2026. O Claude Code Routines (Anthropic) executa invocações agendadas do Claude Code sem um processo local persistente. As sessões pausam em entradas humanas, sobrevivem a deploys e retomam a partir do último checkpoint identificado por thread_id. Por trás dessa nova ergonomia há um padrão antigo — orquestração de fluxo de trabalho (workflow) — com uma nova entrada: chamadas de LLM como atividades não-determinísticas que devem ser reproduzidas de forma determinística na recuperação.

Type: Aprender Languages: Python (stdlib, máquina de estado mínima de execução durável) Prerequisites: Phase 15 · 10 (Permission modes), Phase 15 · 01 (Long-horizon agents) Time: ~60 minutos

O Problema

Considere um agente que roda por quatro horas. Ele chama três ferramentas, solicita entrada do usuário duas vezes e faz quarenta chamadas de LLM. Na metade do caminho, a máquina hospedeira onde ele está rodando reinicia. O que acontece?

• Em um loop while True ingênuo: tudo é perdido. A execução reinicia do zero. As três chamadas de ferramentas (com efeitos colaterais reais) são executadas novamente. O usuário é solicitado novamente para coisas que já aprovou. Quarenta chamadas de LLM são cobradas de novo.
• Com execução durável: a execução retoma a partir do checkpoint mais recente. Atividades já concluídas não são reexecutadas; seus resultados são reproduzidos a partir do log durável. O usuário não precisa reaprovar coisas que já aprovou. As chamadas de LLM já feitas não são cobradas novamente.

Este é o mesmo padrão que sistemas de orquestração de fluxo de trabalho vêm entregando há uma década (Temporal, Cadence, Cherami do Uber). O que há de novo é que as chamadas de LLM agora são um tipo de atividade — não-determinística, cara, com efeitos colaterais — e elas se encaixam perfeitamente nesse padrão.

O tema recorrente da lição: a confiabilidade de longo horizonte decai (a METR observa uma "degradação de 35 minutos" — a taxa de sucesso cai de forma aproximadamente quadrática em relação ao horizonte). A execução durável permite execuções mais longas do que o perfil de confiabilidade suporta, o que é uma nova maneira de falhar com segurança se o design estiver correto, e de forma insegura se o design estiver errado.

O Conceito

Atividades, fluxos de trabalho (workflows) e reprodução (replay)

• Workflow: código de orquestração determinístico. Define a sequência de atividades, as ramificações, as esperas. Deve ser determinístico para que possa ser reproduzido a partir do log de eventos sem divergências inesperadas.
• Activity: uma unidade de trabalho não-determinística e que potencialmente pode falhar. Chamada de LLM, chamada de ferramenta, escrita de arquivo, requisição HTTP. Cada atividade é registrada com suas entradas e (uma vez concluída) suas saídas.
• Log de eventos: o armazenamento durável de suporte. Cada início, conclusão, falha e tentativa de atividade, bem como cada decisão do fluxo de trabalho, são registrados.
• Replay: na recuperação, o código do fluxo de trabalho é reexecutado do início; cada atividade que já foi concluída retorna seu resultado registrado sem ser executada novamente. Apenas as atividades que não haviam sido concluídas são executadas de fato.

Essa estrutura é semelhante à forma como o React renderiza novamente a partir de um DOM virtual, ou como o Git reconstrói uma árvore de trabalho a partir de commits. O determinismo no orquestrador é o que torna a durabilidade barata.

Por que as chamadas de LLM se encaixam no padrão

Chamadas de LLM são:

• Não-determinísticas (temperatura > 0; mesmo com temperatura 0 há desvios entre versões do modelo).
• Caras (dinheiro e latência).
• Potencialmente sujeitas a falhas (limites de taxa, timeouts).
• Geradoras de efeitos colaterais (se invocarem ferramentas).

Este é exatamente o perfil de uma atividade. Envolver cada chamada de LLM como uma atividade fornece retentativas com backoff exponencial, checkpointing entre reinicializações e um rastreamento reproduzível para depuração.

Checkpoints identificados por thread_id

LangGraph, Microsoft Agent Framework, Cloudflare Durable Objects e Claude Code Routines convergiram para o mesmo formato de API: um thread_id (ou equivalente) identifica a sessão; cada transição de estado persiste em um backend (PostgreSQL como padrão, SQLite para desenvolvimento, Redis para cache); a retomada lê o checkpoint mais recente.

A escolha do backend importa:

• PostgreSQL: durável, consultável, sobrevive a deploys. Padrão no LangGraph.
• SQLite: apenas para desenvolvimento local; perde dados entre diferentes hosts.
• Redis: rápido, mas efêmero, a menos que AOF/snapshot esteja configurado.
• Cloudflare Durable Objects: distribuído de forma transparente; escopado por uma chave única; sobrevive por horas ou semanas.

Entrada humana como um estado de primeira classe

O padrão propor-depois-confirmar (Lição 15) exige um estado durável de "aguardando humano". O fluxo de trabalho pausa, a fila externa retém a requisição pendente e uma aprovação retoma exatamente a partir desse ponto. Sem durabilidade, isso é feito com base no melhor esforço; com ela, uma aprovação que chega no dia seguinte faz o fluxo de trabalho retomar pela manhã de onde parou.

A degradação de 35 minutos

A METR observou que todas as classes de agentes avaliadas mostram uma queda na confiabilidade após cerca de 35 minutos de operação contínua. Dobrar a duração da tarefa aproximadamente quadruplica a taxa de falha. A execução durável não resolve isso; ela apenas permite que você rode por mais tempo do que o perfil de confiabilidade suporta. O padrão seguro é combinar durabilidade com checkpoints que exigem uma nova validação humana (HITL) ao retomar, e com chaves de desligamento por orçamento (Lição 13) que limitam o processamento total, independentemente do tempo real decorrido.

Quando a execução durável é a resposta errada

• Execuções menores que alguns minutos sem entrada humana. O custo operacional (overhead) é maior que o benefício.
• Recuperação de informações estritamente de leitura.
• Tarefas onde a correção exige processamento de ponta a ponta dentro de uma única janela de contexto (algumas tarefas de raciocínio; algumas gerações em uma única etapa).

Use O Que Aprendeu

code/main.py implementa um motor mínimo de execução durável usando apenas a biblioteca padrão do Python. Ele suporta:

• Decorador @activity que registra entradas e saídas em um log de eventos em formato JSON.
• Uma função de fluxo de trabalho (workflow) que sequencia atividades.
• Uma função run_or_replay(workflow, event_log) que reproduz atividades concluídas sem reexecutá-las.

O script principal simula um fluxo de trabalho de três atividades, falha na metade do caminho e mostra (a) uma retentativa ingênua que reexecuta tudo versus (b) uma reprodução que executa apenas a atividade que estava faltando.

Coloque Em Produção

outputs/skill-durable-execution-review.md analisa uma proposta de deploy de agente de longa execução para verificar se a estrutura de execução durável está correta: atividades, determinismo, backend de checkpoint, estado de entrada humana e política de validação humana (HITL) ao retomar.

Exercícios

1. Execute code/main.py. Observe a diferença no número de execuções de atividades entre a retentativa ingênua e a reprodução. Altere o ponto de falha e mostre que o número de reproduções muda de acordo.

2. Converta o motor de demonstração para usar thread_id de forma explícita. Simule duas sessões simultâneas compartilhando o motor e confirme que seus logs de eventos não colidem.

3. Escolha uma atividade no motor de demonstração. Introduza um comportamento não-determinístico (uma marcação de tempo/timestamp real dentro de uma decisão do fluxo de trabalho). Demonstre a divergência na reprodução. Explique como motores reais lidam com isso (registro de efeitos colaterais, APIs como Workflow.now()).

4. Leia o post do LangChain "Runtime behind production deep agents". Liste todos os estados persistidos pelo runtime e indique qual modo de falha cada um deles cobre.

5. Projete uma política de checkpoints para uma tarefa de programação autônoma de 6 horas. Onde você define os checkpoints? Como seria a retomada após uma falha? O que exigiria uma nova validação humana (HITL)?

Termos-Chave

Leituras Adicionais

• Anthropic — Claude Code Agent SDK: agent loop — orçamento, turnos e semântica de retomada.
• Microsoft — Agent Framework: human-in-the-loop and checkpointing — formato de RequestInfoEvent.
• LangChain — The Runtime Behind Production Deep Agents — requisitos concretos de tempo de execução.
• OpenAI Agents SDK + Temporal integration (Trigger.dev announcement) — formato de atividade para chamadas de LLM.
• Anthropic — Measuring agent autonomy in practice — referência sobre a degradação de 35 minutos.