Checkpoints em tarefas longas de agente de IA: retomar sem refazer

Um checkpoint é um registro salvo e verificável de uma etapa concluída em uma tarefa longa de agente, gravado antes de a etapa seguinte começar. Quando uma execução falha no meio, o agente recomeça a partir do checkpoint mais recente que passou na verificação. Assim, o trabalho concluído não é repetido e o trabalho pendente não é pulado. As decisões de projeto são três: onde os checkpoints ficam, o que cada um registra e como o reinício decide o que já está feito.

Principais pontos

• Posicione checkpoints após etapas caras de repetir, que alterem sistemas externos ao agente ou que gerem saídas usadas pelas etapas seguintes.
• Registre o que um reinício precisa: entradas, saídas, status, IDs de referência externos, versões e a próxima ação.
• Torne toda escrita externa segura para repetir, com uma chave estável, e registre a intenção antes de cada chamada.
• Ao retomar, verifique o mundo externo antes de tentar novamente qualquer etapa que possa já ter produzido efeito.
• Teste a retomada interrompendo execuções reais em cada checkpoint e comparando o resultado com uma execução sem interrupção.

Por que tarefas longas de agente quebram no meio

Uma tarefa que roda por dias toca em muitos pontos que podem falhar de forma independente: uma API de modelo que passa a devolver erros, uma ferramenta que estoura o tempo limite, um documento de origem que muda enquanto o agente trabalha, uma implantação que reconfigura uma conexão ou uma máquina que reinicia. A maioria dessas falhas é temporária. O risco real está no que o agente faz em seguida. Sem checkpoints, o reinício tem duas saídas, e ambas são ruins. Ele pode começar do zero, o que repete trabalho e pode enviar a mesma mensagem ao cliente duas vezes ou criar registros duplicados. Ou pode tentar continuar a partir do que lembra do próprio progresso, o que abre espaço para etapas puladas cujos resultados nunca foram salvos.

Limites de requisição são um gatilho comum. Uma execução limitada tarde na sequência não deve forçar a repetição de todas as etapas anteriores. Para o lado do controle de tráfego desse problema, veja Limites de taxa de API em agentes de IA depois de mapear onde sua tarefa gasta mais tempo.

Onde colocar os checkpoints?

Nem toda etapa precisa de um. Colocar checkpoint em tudo aumenta armazenamento, carga de revisão e ruído, e torna o registro mais difícil de ler. Coloque um checkpoint numa etapa quando pelo menos uma destas condições for verdadeira:

• A etapa é cara em tempo, dinheiro ou chamadas de modelo, e repeti-la seria perceptível.
• A etapa altera algo fora do agente, como um registro em um sistema de referência, uma mensagem a um cliente ou um arquivo numa pasta compartilhada.
• As etapas seguintes dependem da saída dela, então um resultado errado passaria silenciosamente para o restante da execução.
• A etapa fecha uma fase que uma pessoa pode revisar ou aprovar antes de o trabalho continuar.

Etapas baratas, somente leitura e determinísticas podem ficar dentro do limite do checkpoint anterior. Se repeti-las custa quase nada e produz o mesmo resultado, deixe-as de fora.

Cenário ilustrativo: um distribuidor de peças pede a um agente que concilie um mês de notas de fornecedores com os pedidos de compra. A tarefa tem quatro fases: coletar notas de uma caixa de e-mail, extrair os itens, cruzá-los com os pedidos de compra e lançar as divergências em uma fila contábil. Os checkpoints ficam após a extração, após o cruzamento e após cada lote de divergências lançadas. A coleta é barata de repetir e somente leitura, então não precisa de checkpoint próprio.

O que cada checkpoint deve registrar?

Um checkpoint só é útil se o reinício puder confiar nele. No mínimo, cada um deve conter:

• Um identificador da tarefa e um identificador da etapa, para que o checkpoint não se vincule à execução errada.
• Um status: verificado, falhou ou em andamento. O reinício só deve confiar em checkpoints verificados.
• Um ponteiro para a saída, guardado fora do contexto do modelo, como um caminho de arquivo ou a referência de uma linha. Guarde o artefato em si, não um resumo dele.
• As versões que o produziram: versão das instruções, versão do esquema das ferramentas e identificador do modelo. Se o modelo mudar entre checkpoints, você precisa saber em qual versão cada etapa rodou.
• Para cada ação externa, o ID de referência do fornecedor e a chave de idempotência enviada.
• A próxima ação, escrita como uma frase simples.
• Um carimbo de tempo e uma impressão digital das entradas, para que a retomada detecte quando o material de origem mudou.

Vários desses campos se sobrepõem a uma trilha de auditoria, e os dois devem ser desenhados juntos. Os campos da trilha de auditoria que toda ação precisa ter mostram essa sobreposição. Mantenha os checkpoints pequenos o bastante para serem lidos. Um checkpoint que armazena a conversa inteira é difícil de inspecionar e tende a levar instruções desatualizadas para a etapa seguinte.

Como tornar toda escrita segura para repetir

A retomada só é segura se repetir uma etapa não alterar duas vezes o mundo externo. A abordagem comum é a chave de idempotência: um identificador estável, derivado da tarefa e da etapa, enviado com cada escrita externa. Se a mesma requisição chegar de novo, uma API bem construída devolve o resultado original em vez de executar a ação outra vez. A Stripe documenta esse padrão para a própria API, e a disciplina vale a pena mesmo quando suas ferramentas não oferecem isso nativamente.

Quando um fornecedor não tem suporte a idempotência, registre a intenção primeiro. Antes de chamar o sistema externo, o agente grava uma linha dizendo que vai criar um registro sob determinada chave. Depois da chamada, registra o resultado. Na retomada, se existir uma intenção sem resultado correspondente, o agente deve consultar essa chave no sistema externo antes de decidir se tenta de novo. Arriscar um palpite nesse ponto é a causa mais comum de lançamentos duplicados.

Repetições devem seguir uma política escrita, não o julgamento do modelo no momento da falha. Defina quais erros podem ser repetidos, quantas tentativas são permitidas e quando o agente deve parar e escalar. A política de repetição para agentes de IA sem duplicidades detalha essas decisões.

Como o agente retoma sem repetir ou pular?

A retomada deve seguir o mesmo procedimento todas as vezes, para que uma pessoa que revise uma execução falha consiga prever o que aconteceu. Uma sequência viável tem esta forma:

• Carregue o checkpoint verificado mais recente e ignore tudo o que foi gravado depois dele.
• Compare a impressão digital das entradas guardada com a origem atual. Se a origem mudou, pare e encaminhe a decisão a uma pessoa, em vez de continuar em silêncio.
• Confira cada intenção de escrita registrada após esse checkpoint contra o sistema externo antes de tentar novamente.
• Confirme que as versões de instruções e de ferramentas batem com o checkpoint, ou registre a mudança explicitamente.
• Continue a partir da etapa indicada no campo de próxima ação, e grave um novo checkpoint só depois que essa etapa passar na verificação.
• Se a mesma etapa falhar de novo na retomada, pare e escale, em vez de repetir indefinidamente.

O último ponto é o mais importante. Uma retomada que falha sempre do mesmo jeito é um loop, não uma recuperação. As condições de parada que realmente funcionam mostram como limitar esse comportamento antes que ele consuma um dia de trabalho.

Como testar se os checkpoints funcionam de verdade?

Um checkpoint que nunca foi interrompido é apenas uma hipótese. Teste antes que a primeira execução longa dependa dele, usando uma cópia de homologação da tarefa e uma entrada pequena que represente casos reais:

• Execute a tarefa até o fim, sem interrupções, e salve as saídas finais como referência.
• Execute de novo e pare deliberadamente após cada checkpoint.
• Retome cada execução interrompida e compare as saídas e os efeitos externos com a referência.
• Injete um tempo limite logo após uma escrita externa e confirme que o reinício não cria duplicidade.
• Corrompa um checkpoint de propósito e confirme que o agente se recusa a retomar a partir dele.

Compare resultados, não transcrições. A redação gerada varia entre execuções, então compare campos estruturados, contagens de registros e IDs de referência externos. Os rastros e registros de cada execução mostram onde a retomada começou, e os conceitos de observabilidade ajudam a ler esses rastros. Um conjunto de testes montado a partir de casos reais passados torna a comparação significativa, porque testa as etapas que de fato causam problemas.

Como a Be Human trata isso e por onde começar

A Be Human projeta e opera a infraestrutura de agentes que torna os checkpoints possíveis. Numa primeira etapa, as posições dos checkpoints, os campos de registro, a abordagem de idempotência e os limites de aprovação são escritos na definição do papel, para que cada reinício siga regras que a empresa aceitou antecipadamente. A operação gerenciada mantém essas regras funcionando ao longo do tempo. Isso inclui monitorar as gravações de checkpoint e os eventos de retomada, revisar as permissões que uma tarefa longa detém, tratar incidentes quando uma execução para de forma inesperada e ajustar a posição dos checkpoints quando ferramentas ou modelos mudam. A empresa decide quais etapas precisam de aprovação humana. A Be Human garante que o agente pare nessas etapas e deixe um registro que uma pessoa consiga ler.

Um ponto de partida prático é listar as tarefas longas que sua equipe já executa à mão ou com um script frágil. Para cada uma, marque as etapas que são caras, tocam um sistema externo ou são conferidas por alguém antes de o trabalho continuar. Essas marcações formam um primeiro mapa de checkpoints. Depois, escolha uma tarefa com critério de sucesso claro e permissões limitadas, e rode-a em modo de observação antes que ela escreva qualquer coisa. Teste um agente de IA em modo de observação explica como reunir essa evidência antes de dar autoridade ao agente. Faça o diagnóstico gratuito de IA da Be Human para descobrir a primeira tarefa longa que vale entregar a um agente.

Perguntas frequentes

Com que frequência uma tarefa longa de agente deve gravar um checkpoint? Grave checkpoints nas fronteiras que você definiu, e não em um intervalo fixo de tempo. Um temporizador pode capturar uma escrita pela metade, enquanto um checkpoint de fronteira só é gravado depois que a etapa passa na verificação. Um sinal de atividade por tempo só vale a pena para uma etapa isolada que pode rodar por muito mais tempo que o normal.

A memória do modelo pode substituir os checkpoints? Não. A memória do modelo não é um registro confiável de quais ações externas foram concluídas, e pode se perder quando uma sessão termina ou um modelo muda. Os checkpoints guardam o estado verificado em sistemas que você controla, então um reinício consulta fatos em vez de reconstruí-los a partir de uma conversa.

O que acontece se os dados de origem mudarem entre dois checkpoints? O agente deve comparar a impressão digital das entradas guardada antes de retomar. Se a origem mudou, a ação segura é parar e enviar a decisão a uma pessoa, porque continuar poderia misturar resultados de duas versões diferentes dos mesmos dados.

Os checkpoints adicionam custo operacional relevante? Eles acrescentam algum armazenamento, algumas gravações extras e uma etapa de verificação em cada fronteira. Na maioria das tarefas longas, esse custo é pequeno comparado com repetir um dia de trabalho ou limpar registros externos duplicados, e fica mais fácil de avaliar quando você mede o custo de uma única retomada no seu próprio fluxo de trabalho.

Orientação editorial Be Human. Exemplos são ilustrativos, salvo atribuição explícita. Fontes oferecem contexto; a implementação depende do seu processo.