Ir para conteúdo
be-human.ai
← Voltar ao blog

Fundamentos de harness

Tarefas longas de agentes de IA com checkpoints: retomar sem repetir

Como checkpoints permitem retomar tarefas longas de agentes de IA após uma falha: estado salvo, reenvios seguros e aprovações que continuam válidas.

Capa tipográfica do Be Human com o título: Tarefas longas de agentes de IA com checkpoints: retomar sem repetir
Ilustração conceitual criada com IA · Be Human

Uma tarefa longa de agente de IA pode ser retomada depois de uma falha quando o harness salva um checkpoint após cada etapa verificada e recomeça a partir do último checkpoint válido, e não da primeira etapa. O checkpoint registra o que terminou, qual evidência confirmou cada etapa e quais aprovações ainda cobrem a próxima ação. A retomada só é segura quando toda ação que toca um sistema externo é registrada como intenção antes de ser enviada, para que a execução reiniciada consiga saber se aquela ação já aconteceu.

Principais pontos

  • Um checkpoint é um registro estruturado do progresso verificado, não uma cópia do histórico do chat.
  • Salve o estado após cada etapa que altere algo fora do agente, e confira o resultado antes de salvá-lo.
  • Registre a intenção antes de cada ação externa para que uma execução retomada consiga diferenciar “não enviado” de “enviado, mas a confirmação se perdeu”.
  • Guarde as aprovações junto com o checkpoint, incluindo escopo e validade, para que a execução retomada não peça de novo nem presuma permissão demais.
  • Simule a falha de propósito, parando uma execução de teste em cada fronteira de etapa, antes de confiar na retomada com trabalho real.

Por que tarefas longas de agentes falham no meio

Uma tarefa que roda por dias enfrenta condições que nunca aparecem em um chat isolado. Um provedor expira o tempo de resposta, um limite de requisições fica ativo por um tempo, um token de acesso vence, uma ferramenta devolve um erro que o agente interpreta mal, ou um servidor reinicia durante uma implantação. Cada uma dessas situações é comum, e um sistema bem construído já espera por elas. O dano vem de reiniciar sem saber o que já aconteceu. Repetir uma busca custa pouco. Repetir um pagamento, enviar uma segunda mensagem a um cliente ou criar um registro duplicado de fatura é outra história, e pode levar tempo até alguém notar, geralmente quando perguntar por que existem dois.

O problema não é apenas a falha, mas a conclusão parcial. Uma etapa pode alterar um registro e falhar antes que o agente anote que a mudança aconteceu. As orientações de engenharia da Anthropic sobre harnesses de longa duração apontam exatamente isso: o progresso precisa viver em artefatos duráveis fora do contexto do modelo, para que cada nova sessão comece de um estado conhecido, e não de um resumo que o modelo reconstrói. O checkpoint é a versão operacional dessa ideia, escrita de um jeito que a sua equipe consegue auditar.

O que um checkpoint deve conter

Um checkpoint útil é pequeno, estruturado e legível por uma pessoa. Ele deve conter estes campos:

  • O identificador da execução e a versão do objetivo sob o qual a execução começou.
  • As etapas concluídas, cada uma com identificador, resumo curto do resultado e o registro que foi alterado.
  • A evidência de cada etapa concluída, como a referência de registro devolvida pelo sistema ou o resultado de uma verificação.
  • A etapa pendente e o status de intenção: não iniciada, enviando ou confirmada.
  • As aprovações concedidas para a etapa pendente, com escopo, quem as concedeu e a data de validade.
  • As versões do modelo, do prompt e das definições de ferramentas em uso quando cada etapa começou.
  • O orçamento consumido até agora em passos, chamadas de ferramentas e tempo decorrido, medido contra os limites definidos.

Não inclua a transcrição completa. Ela é grande, em grande parte não verificada e convida a próxima sessão a rediscutir decisões que já estavam resolvidas. Um checkpoint estruturado pode ser validado pelo harness antes de o agente lê-lo, que é o mesmo princípio por trás das saídas estruturadas que o harness consegue validar. Se o checkpoint falhar na validação, a execução deve parar, e não improvisar.

O procedimento de retomada, passo a passo

Use sempre a mesma ordem quando uma execução reiniciar. Cada item é uma barreira. Se uma falhar, a execução para e escala para revisão, com o checkpoint anexado, em vez de continuar.

  • Carregue o checkpoint mais recente e rejeite-o se a verificação de esquema falhar ou se o identificador da execução não corresponder à tarefa.
  • Confirme que as versões de ferramenta e de prompt registradas no checkpoint ainda existem. Se uma definição mudou, envie a execução para revisão em vez de adotar a nova versão em silêncio.
  • Leia o estado atual de todo sistema que a etapa pendente toca. Use o registro do próprio sistema, não a memória que o agente tem dele.
  • Se a etapa pendente estiver marcada como enviando, procure se a ação já aconteceu usando a referência gravada no momento da intenção.
  • Verifique se a aprovação da etapa pendente ainda existe, se está dentro do escopo e se não venceu.
  • Envie a ação com sua chave de idempotência, ou execute a nova tentativa baseada em busca caso o sistema não ofereça chave.
  • Verifique o resultado contra o critério de sucesso e grave o próximo checkpoint antes de qualquer outra ação.

A ordem importa. Ler o estado atual antes de tentar de novo impede o agente de agir sobre um retrato desatualizado, e conferir as aprovações antes do envio impede que a retomada amplie, sem alarde, uma permissão concedida para um lote anterior.

Idempotência é o que impede trabalho duplicado

Uma chave de idempotência é um valor único anexado a uma requisição, para que o sistema receptor reconheça uma repetição e devolva o resultado original em vez de executar a ação de novo. A documentação da Stripe sobre requisições idempotentes é um exemplo público e claro desse padrão, e a mesma lógica vale para os sistemas internos em que o agente escreve. Quando o sistema oferece chaves, o harness deve gerar uma por ação e armazená-la no checkpoint antes de fazer a chamada.

Nem todo sistema de negócio oferece chaves, então o harness precisa de um plano B. Antes de enviar, o agente grava uma entrada de intenção com uma referência que ele mesmo gerou, como um identificador de mensagem do lado do cliente, um número de rascunho ou um campo de memorando único. Após uma falha, uma intenção pendente sem confirmação dispara uma busca por essa referência no sistema de destino. O agente só tenta de novo se a busca não encontrar nada. A regra é simples de enunciar e fácil de ignorar sob pressão de prazo: registrar a intenção leva segundos, enquanto desfazer uma duplicata depois que ela foi enviada pode tomar o tempo de alguém por um dia inteiro.

Cenário ilustrativo: uma conciliação de faturas em três dias

Cenário ilustrativo, não é um caso de cliente: um responsável de operações pede a um agente que concilie faturas de fornecedores com pedidos de compra ao longo de três dias e envie um resumo das exceções para a equipe financeira ao fim de cada dia. No segundo dia, a execução falha depois que o resumo de exceções é enviado, mas antes de a confirmação ser registrada. O checkpoint mostra aquele envio como enviando.

Na retomada, o harness procura no registro de e-mails enviados a referência gravada no momento da intenção, encontra a mensagem e marca a etapa como confirmada. Ele pula o envio e continua conciliando as faturas restantes. A aprovação para os resumos de exceções cobria apenas o lote do segundo dia, então, quando a execução chega ao envio do terceiro dia, o harness pausa e pede uma nova aprovação, como a fronteira exige. A equipe financeira recebe um resumo por dia, e o responsável de operações consegue ver no histórico de checkpoints exatamente onde a execução foi retomada e por que pausou.

Como a Be Human opera checkpoints em operações gerenciadas

Na abordagem gerenciada da Be Human, a primeira etapa define o papel único que o agente desempenha, a memória e as ferramentas de que ele precisa, os limites de aprovação e um critério de sucesso observável. O formato do checkpoint é escrito nessa definição, e não deixado para depois, para que a equipe saiba quais campos existem e quem pode lê-los. A operação contínua cobre depois as partes que mudam com o tempo: monitoramento dos eventos de retomada e das buscas que falharam, revisão de permissões quando uma ferramenta ou uma conta muda, resposta a incidentes quando uma retomada escala, e alterações controladas no esquema do checkpoint, cada uma registrada para que a equipe veja o que mudou e por quê. O serviço é remoto e disponível em inglês e em português.

Simule a falha antes de confiar nela

Teste a retomada da mesma forma que testaria um backup. Em um ambiente de teste, pare uma execução em cada fronteira de etapa, reinicie-a e compare o estado final com o de uma execução limpa que nunca falhou. Conte as duplicatas nos sistemas de destino, e não apenas se o agente informa sucesso, porque um agente pode descrever uma execução limpa enquanto uma segunda mensagem está parada em uma caixa de saída. Repita o exercício após cada mudança nas definições de ferramentas ou no esquema do checkpoint.

Acompanhe esses testes com condições de parada claras, para que uma execução que retome em um estado inesperado pare em vez de entrar em loop. O artigo sobre condições de parada para agentes de IA explica quando interromper e escalar. Etapas que continuam falhando depois do limite de novas tentativas devem ir para uma área de espera com o checkpoint anexado, e não de volta à fila, como descrito em filas de tarefas para agentes de IA. Se ainda não está claro qual dos seus processos é o primeiro que vale entregar a um agente, o diagnóstico gratuito de IA da Be Human pode ajudar a identificar essa primeira tarefa.

Perguntas frequentes

Um checkpoint substitui a memória do agente? Não. A memória guarda fatos e preferências duráveis que valem entre tarefas, enquanto o checkpoint guarda o estado de uma única execução. Mantenha os dois separados, para que uma mudança na memória não altere silenciosamente a forma como uma etapa concluída foi registrada.

O que acontece se um checkpoint for danificado? O harness deve rejeitá-lo quando a verificação de esquema falhar e parar, em vez de adivinhar. As gravações devem ser versionadas e apenas de acréscimo, para que o checkpoint válido anterior continue disponível, e a retomada deve partir dele e conciliar com os sistemas atuais antes de continuar.

Uma execução retomada pode usar uma versão mais nova de modelo ou de ferramenta? Somente depois que o harness verificar a mudança. Um modelo mais novo pode interpretar a etapa pendente de forma diferente, então o procedimento de retomada deve comparar as versões registradas com as atuais e enviar qualquer mudança para revisão, de preferência depois de ela passar por uma liberação gradual em trabalhos de menor risco.

Quem deve aprovar a retomada depois de uma falha que mexeu com dinheiro ou com clientes? A aprovação deve vir do responsável por aquela fronteira, e não automaticamente da pessoa que iniciou a execução. A aprovação deve declarar o que cobre depois da retomada, e uma aprovação vencida deve fazer a execução pausar até que alguém a renove.

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.

Menos tarefas. Mais espaço para você.

Traga o trabalho para o qual falta tempo.

Agende uma conversa e teste 7 dias grátis um agente de IA personalizado ↗Ou faça o diagnóstico gratuito de IA →