Checkpoints em tarefas longas de agentes: arquivos de progresso, passos idempotentes e retomada

Objetivo

Fazer com que qualquer interrupção de uma tarefa longa custe no máximo um passo de trabalho e nenhum efeito colateral duplicado, seja a interrupção uma falha de processo, uma janela de contexto que precisou ser reiniciada ou uma transferência para outro agente.

Pré-requisitos

Uma tarefa que possa ser descrita como uma sequência de passos com critérios de conclusão observáveis, um local para gravar arquivos que sobreviva à interrupção e sistemas externos cujas operações de escrita aceitem uma chave de idempotência ou permitam consultar o que já aconteceu.

Passos

1. Antes do primeiro efeito colateral, grave um arquivo de plano: passos numerados, a verificação de conclusão de cada um ("o arquivo existe e é interpretado sem erro", "o registro 4711 tem status enviado", "suíte de testes verde") e as entradas de que os passos dependem.
2. Mantenha ao lado dele um arquivo de progresso e atualize-o depois de cada passo concluído, não antes: número do passo, timestamp, a evidência da conclusão (um hash, um identificador, o status de saída de um comando) e tudo o que o próximo passo precisa e que foi descoberto neste.
3. Dê a cada escrita externa uma chave de idempotência derivada da tarefa e do passo, de modo que uma requisição repetida após uma falha seja reconhecida pelo receptor em vez de executada duas vezes; quando o receptor não tiver esse mecanismo, consulte primeiro se o efeito existe e pule a escrita caso ele já esteja presente.
4. Faça cada passo poder ser reiniciado isoladamente: ele lê suas entradas de arquivos ou identificadores, nunca da conversa, e tolera a saída parcial deixada por uma tentativa anterior (sobrescrever ou limpar, nunca acrescentar às cegas).
5. Na retomada, leia o plano e o arquivo de progresso, verifique a evidência do último passo registrado contra o estado real (o registro realmente foi enviado, o arquivo realmente é interpretado sem erro) e continue a partir do primeiro passo não verificado. Nunca confie apenas no arquivo de progresso; verifique e só então prossiga.
6. Registre no arquivo de progresso as decisões tomadas ao longo do caminho, com o motivo, para que uma execução retomada não as reabra, e registre explicitamente as incógnitas em aberto, para que não sejam confundidas com questões já resolvidas.
7. Ao final, escreva o resumo final a partir do arquivo de progresso, que a essa altura contém todos os passos com evidências; depois arquive os dois arquivos com o identificador da execução.

Resultado esperado

Uma execução interrompida em qualquer ponto pode ser retomada, pelo mesmo agente ou por outro, apenas a partir dos arquivos; repete no máximo o passo que estava em andamento e não produz nenhum efeito externo duplicado.

Limites e base de verificação

Um protocolo proposto. Ele pressupõe passos com conclusão verificável; um trabalho cujo único artefato é compreensão (ler, explorar) precisa de uma nota escrita como evidência, o que é uma verificação mais fraca. A idempotência depende de o sistema receptor respeitar a chave.

Efeitos não consultáveis: registre primeiro a intenção

Para um passo cujo efeito não pode ser consultado depois (uma mensagem enviada, um webhook entregue a terceiros, um pagamento capturado sem endpoint de consulta), inverta a ordem do passo 2: grave um registro de intenção com a chave de idempotência reservada antes do efeito, execute o efeito e só então grave o registro de conclusão. Uma execução retomada que encontre uma intenção sem conclusão sabe que o efeito pode ou não ter ocorrido; ela deve perguntar ao receptor usando a mesma chave, ou entregar o passo a uma pessoa, em vez de repeti-lo. Grave os dois registros de forma atômica (arquivo temporário e depois renomeação), para que uma falha durante a gravação não deixe um arquivo de progresso pela metade.