Checkpoints para agentes de IA: retomar a partir do estado verificado
Guia prático para fazer checkpoints de agentes de IA de longa duração no harness, para que um sucessor retome do estado verificado e não do zero.

Para fazer checkpoint de um agente de IA de longa duração, faça o harness gravar um registro estruturado fora do modelo: o objetivo e seu teste de aceitação, os passos concluídos com evidência, os itens em aberto e cada ação externa já executada. Um sucessor só deve retomar a partir desse registro depois de conferir as entradas verificadas nos sistemas reais. Feito assim, um modelo mais capaz continua no último passo verificado, em vez de repetir dias de trabalho ou confiar no resumo que o agente anterior escreveu sobre o próprio progresso.
Principais pontos
- Um checkpoint é um registro que o sucessor consegue verificar, não um resumo que o agente escreveu sobre o próprio progresso.
- Guarde o objetivo, os passos concluídos, as evidências, os itens em aberto e os efeitos externos em um armazenamento que o harness controla, fora do contexto do modelo.
- Registre resultados lidos de ferramentas e sistemas de registro, e marque como não verificado tudo o que o agente apenas afirmou.
- Dê a cada ação externa uma chave ou uma intenção registrada, para que uma nova tentativa não repita um pagamento, uma mensagem ou uma exclusão.
- Permita que um sucessor retome somente depois de conferir o checkpoint nos sistemas reais e de confirmar que os limites de aprovação continuam valendo.
O que um checkpoint precisa conter
Uma tarefa de vários dias gera muito mais estado do que uma transcrição de conversa consegue sustentar com segurança. Um checkpoint útil responde a cinco perguntas: qual é o objetivo e como o sucesso será testado, quais passos estão concluídos, que evidência mostra que cada um está concluído, o que ainda está aberto e quais ações externas já aconteceram. Se alguma dessas respostas existe apenas na conversa, o sucessor precisa reconstruí-la, e é na reconstrução que as tarefas longas começam a desviar.
Mantenha o registro em arquivos ou em um banco de dados que o harness controla, e não na memória do modelo. A memória do modelo está ligada a uma sessão e, muitas vezes, a uma versão específica do modelo. Já o registro do harness sobrevive à troca de modelo. Isso importa porque um dos motivos mais comuns para fazer checkpoint é passar o trabalho a um modelo mais forte depois. A diferença entre memória e histórico de conversa é tratada em outro texto da nossa linha editorial.
Separe o estado verificado das afirmações
Um agente que diz 'a importação está concluída' fez uma afirmação. O checkpoint deve guardar essa afirmação ao lado da evidência que a sustenta: a contagem de linhas lida de volta no destino, o hash do arquivo de saída ou o status devolvido pelo sistema de registro. Uma afirmação sem evidência é marcada como não verificada, e o sucessor trata os itens não verificados como trabalho a conferir, e não como fatos a repetir.
Na prática, cada entrada do registro deve cair em um destes grupos:
- Leituras de um sistema de registro, com o identificador e o valor devolvido.
- Resultados de scripts de validação ou testes, guardados como resultados e não como texto.
- Aprovações humanas, com quem aprovou, o escopo aprovado e a ação que a aprovação cobre.
- Declarações do agente, guardadas como não verificadas até que uma checagem as confirme.
Essa estrutura também acelera a revisão. Quem revisa vê de relance quais partes do trabalho estão comprovadas e quais ainda são apenas afirmações.
Como escrever um checkpoint, passo a passo
Escreva o checkpoint enquanto o trabalho acontece, e não no fim da sessão. A sequência a seguir funciona para a maioria dos harnesses:
- Congele o objetivo e o teste de aceitação no registro antes do primeiro passo.
- Depois de cada passo que altere o estado externo ou produza evidência, grave a saída e a evidência na mesma operação.
- Registre cada ação externa com seu identificador e com a informação de que ela pode ou não ser repetida com segurança.
- Escreva os itens em aberto como próximas ações específicas, cada uma indicando a entrada de que precisa e a aprovação que exige, se houver.
- Salve cada checkpoint em um local versionado e anote qual versão do harness e qual modelo o produziram.
- Antes de a sessão terminar ou pausar, leia o checkpoint de volta e confirme que ele ainda corresponde ao estado atual dos sistemas que descreve.
A última etapa é a mais esquecida. Um checkpoint que nunca foi relido é apenas um palpite sobre o que foi salvo.
Cenário ilustrativo: conciliação de notas fiscais em três dias
Cenário ilustrativo: uma equipe de operações financeiras pede a um agente que cruze notas de fornecedores com as mercadorias recebidas ao longo de alguns dias. No primeiro dia, o agente exporta as notas em aberto e grava um checkpoint com o identificador da exportação e o conjunto de notas, verificado por uma contagem relida do arquivo exportado. No segundo dia, ele cruza parte do conjunto e sinaliza divergências. O checkpoint lista cada nota cruzada com a versão da regra usada e cada nota sinalizada com o motivo. Depois, a sessão para ao atingir o limite de uso, e o harness grava o checkpoint no momento da parada, em vez de perder a última hora de trabalho.
No terceiro dia, um modelo mais forte assume. Ele lê o checkpoint antes de tudo, consulta de novo as notas em aberto, confirma que a exportação ainda bate com a contagem guardada e continua a partir do primeiro item não cruzado. Não exporta nem cruza de novo as notas que o registro mostra como verificadas. Quem revisa consegue ver exatamente onde ocorreu a passagem e por quê.
Torne as ações externas seguras para retomar
O ponto mais arriscado de uma retomada raramente é o raciocínio. São os efeitos colaterais. Se a sessão anterior enviou um e-mail ao fornecedor ou criou um pagamento antes de parar, um sucessor que repete o plano pode executar a ação de novo. A proteção padrão é a idempotência: cada requisição carrega uma chave única, para que o provedor devolva o resultado original em vez de executar duas vezes. A Stripe documenta esse padrão em seu guia de requisições idempotentes, e a mesma disciplina vale para qualquer ferramenta, inclusive as que não têm chave nativa.
Para ferramentas sem esse recurso, o próprio harness pode aplicar o padrão:
- Registre a intenção de chamar a ferramenta antes da chamada, para que uma queda no meio do caminho seja detectável.
- Derive a chave da ação a partir do identificador do checkpoint e do passo, para que o mesmo passo sempre gere a mesma chave.
- Na retomada, consulte a ação no registro antes de qualquer nova tentativa.
Os limites de sessão são a outra metade disso. Limites de passos, tokens e tempo para agentes fazem a execução parar em um ponto previsível, o que dá ao harness um momento limpo para gravar o checkpoint.
Como uma operação gerenciada mantém os checkpoints atualizados
A Be Human trata os checkpoints como parte do harness, e não como um complemento. Em um projeto, primeiro definimos o papel do agente, sua memória, suas ferramentas e seus limites de aprovação, e só então escrevemos a estrutura do checkpoint para combinar com eles. Depois, a operação gerenciada mantém o registro funcionando ao longo do tempo: o monitoramento sinaliza sessões que terminaram sem uma releitura do checkpoint, a revisão de permissões confirma que uma sessão retomada continua com apenas o acesso que seu papel exige, e as melhorias controladas alteram o formato do checkpoint por meio de versões liberadas, para que os registros antigos continuem legíveis.
Decidindo quando um sucessor pode retomar
A retomada deve passar por um portão. Antes de o sucessor continuar, o harness deve confirmar que o checkpoint não mudou desde que foi gravado, reler os sistemas de registro por trás de cada item verificado do qual os próximos passos dependem e checar se o teste de aceitação ainda se aplica. Tudo o que falhar volta para não verificado. Ações de consequência, como pagamentos, mensagens a clientes ou exclusões, ainda exigem a aprovação prevista nos limites, mesmo que a sessão anterior a tivesse, porque o escopo pode ter mudado enquanto o trabalho estava pausado.
Para um padrão mais amplo do que conta como concluído, veja a definição de pronto para agentes de IA. Para acompanhar como o próprio harness muda entre as sessões, veja o versionamento de harness de IA.
O diagnóstico gratuito de IA da Be Human pode ajudar você a encontrar a primeira tarefa que vale a pena entregar a um agente.
Perguntas frequentes
Com que frequência um agente deve gravar um checkpoint? Grave um após cada passo que altere o estado externo ou produza evidência, e de novo em cada parada natural, como um limite de uso ou uma aprovação pendente. Esperar até o fim da sessão significa que uma queda apaga todo o trabalho dela. Gravações pequenas e frequentes custam pouco comparadas ao esforço de refazer um dia inteiro de resultados.
Um modelo mais capaz consegue retomar sem checkpoint? Ele consegue reconstruir parte do estado a partir dos sistemas a que tem acesso, mas não sabe quais ações externas já aconteceram, a menos que o registro diga isso. Um modelo mais forte também pode escolher um plano diferente, o que torna as decisões anteriores difíceis de auditar. O checkpoint torna a passagem explícita e revisável.
Qual é a diferença entre checkpoint e log? O log registra tudo o que aconteceu, em ordem, o que é útil para investigação e análise de incidentes. O checkpoint registra o estado verificado atual e o que ainda falta, que é o que um sucessor precisa para continuar. Mantenha os dois e trate o log como dado de observabilidade, conforme descrito na introdução à observabilidade do OpenTelemetry.
Fazer checkpoints substitui a revisão humana? Não. Os checkpoints tornam a revisão prática, porque mostram o que foi verificado e o que foi apenas afirmado. Os limites de aprovação continuam decidindo quais ações exigem uma pessoa, e quem revisa deve focar nos itens em aberto e nas entradas não verificadas, em vez de reler a transcrição inteira.
Seu próximo passo
Descubra primeiro onde um agente de IA cabe na sua empresa.
Faça o diagnóstico gratuito de IA da Be Human. Algumas perguntas sobre o seu trabalho mostram qual tarefa entregar primeiro a um agente, o que ele precisa saber e onde uma pessoa aprova.
Orientação editorial Be Human. Exemplos são ilustrativos, salvo atribuição explícita. Fontes oferecem contexto; a implementação depende do seu processo.


