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

Fundamentos de harness

Timeout e cancelamento de agentes de IA: paradas limpas em tarefas longas

Como definir timeouts de agentes de IA em níveis e cancelar tarefas longas de forma limpa, sem registros meio escritos nos seus sistemas.

Capa tipográfica do Be Human com o título: Timeout e cancelamento de agentes de IA: paradas limpas em tarefas longas
Ilustração conceitual criada com IA · Be Human

Um timeout de agente de IA é um limite que interrompe uma tarefa quando ela demora demais, trava ou consome mais do que o orçamento permitido. Um timeout bem desenhado também define o que acontece depois: o agente deixa de iniciar trabalho novo, fecha ou marca as gravações que estavam em andamento, registra o motivo da parada e libera o que estava segurando. O objetivo é uma tarefa interrompida que deixa seus registros consistentes, e não uma que desaparece no meio de uma alteração.

Principais pontos

  • Defina timeouts em níveis (por chamada, por inatividade, prazo total da tarefa e orçamento), porque cada nível pega uma falha diferente.
  • Trate o cancelamento como uma sequência fixa: parar trabalho novo, fechar as gravações abertas, registrar o motivo e só então liberar recursos.
  • Dê a cada registro escrito pelo agente um estado controlado pelo harness, para que uma alteração interrompida apareça como pendente, desconhecida ou abandonada.
  • Só tente de novo com a mesma chave de idempotência ou depois de verificar o sistema de destino, para que uma requisição nunca vire dois registros.
  • Deixe o dono do resultado de negócio definir os limites e revise-os depois de cada incidente.

Por que um timeout é mais do que um cronômetro

Um timeout costuma ser descrito como um número: pare depois de certo tempo. Para um agente de negócio, o número importa menos do que aquilo que está em andamento quando o limite dispara. Um agente que está no meio da criação de um orçamento, da reserva de uma vaga de equipe e do envio de uma confirmação pode ser cortado depois das duas primeiras etapas. O cliente não recebe confirmação, o sistema de agenda mostra uma vaga que ninguém consegue ver no orçamento, e ninguém sabe qual etapa falhou. O problema não é que o agente rodou por tempo demais. O problema é que a parada nunca foi desenhada.

Tarefas longas tornam isso mais provável. Elas chamam várias ferramentas, esperam sistemas externos lentos e, às vezes, entram em loop quando uma ferramenta devolve um resultado inesperado. O harness, isto é, o código que cerca o modelo com ferramentas, permissões, registros e limites, é a camada que aplica cada parada. Se o harness não tem uma regra clara para o que significa parar, cada parada vira um palpite. Para uma introdução geral a essa camada, veja o que é harness de IA.

Os quatro níveis de timeout

Um único limite para a execução inteira é grosseiro demais. Ele corta uma etapa lenta mas saudável, ou deixa um loop travado rodar muito além do que alguém pretendia. Limites separados pegam falhas separadas:

  • Timeout de chamada: o tempo máximo de espera por uma chamada de ferramenta ou por uma resposta do modelo. Quando ele dispara, o harness trata aquela chamada como falha ou desconhecida, nunca como concluída.
  • Timeout por inatividade: o tempo máximo sem nenhum sinal de progresso, como um novo resultado de ferramenta ou um checkpoint salvo. Ele pega travamentos que um limite total só perceberia muito mais tarde.
  • Prazo da tarefa: o tempo máximo de relógio para a execução inteira, definido pela necessidade do negócio. Um orçamento que precisa estar pronto antes do corte de despacho tem prazo diferente de uma conciliação noturna.
  • Limite de orçamento: o número máximo de passos, chamadas de ferramenta ou tokens do modelo em uma execução. É a proteção contra loops e custo fora de controle, tratada com mais profundidade em limites de passos, tokens e tempo para agentes.

Cada nível deve ter seu próprio valor, e cada valor deve ter um motivo escrito ao lado. Um revisor que não entende por que um limite existe vai ignorá-lo ou afrouxá-lo sem compreender o risco.

O que um cancelamento limpo faz, em ordem

Cancelamento é diferente de queda. Em uma queda, o harness precisa adivinhar o que aconteceu. Um cancelamento limpo é um sinal que o agente consegue processar, seguido de uma sequência controlada pelo harness. A ordem importa, porque o agente não deve começar trabalho novo enquanto ainda está fechando o trabalho antigo.

  • Parar de iniciar novas chamadas de ferramenta e novas subtarefas assim que o sinal de cancelamento chegar.
  • Deixar terminar uma gravação já em andamento, se ela for curta e puder ser verificada. Se não puder ser verificada a tempo, marcá-la como desconhecida em vez de presumir o resultado.
  • Compensar qualquer alteração que tenha deixado o registro inconsistente, como uma atualização de status salva sem a nota correspondente.
  • Gravar um registro de encerramento com o motivo da parada, a última etapa confirmada e o estado de cada item em aberto.
  • Liberar travas, reservas e sessões que a execução estava segurando, e só então encerrar a execução.

A interrupção forçada deve ser o último recurso. Defina um período de tolerância de tamanho fixo e trate-o como parte do desenho. Um ponto de partida razoável é um período curto para gravações e um mais longo para etapas somente de leitura, porque uma leitura pode ser repetida com segurança e uma gravação talvez não possa. A distinção entre uma leitura interrompida e uma gravação interrompida é a que as equipes mais costumam pular.

Mantenha o trabalho pela metade visível, não escondido

O problema dos registros é o que torna um timeout perigoso. A maioria dos sistemas de negócio não tem o conceito de uma alteração iniciada, mas ainda não confirmada. O harness precisa acrescentar esse conceito. Dê a cada registro escrito pelo agente um campo de estado controlado pelo harness, com estados explícitos:

  • Pendente: o agente iniciou a alteração e ainda não tem confirmação do sistema de destino.
  • Efetivado: o sistema de destino confirmou a alteração, então o registro pode ser lido como definitivo.
  • Abandonado: a execução parou antes de a alteração ser confirmada, e uma pessoa ou uma execução posterior precisa decidir o próximo passo.
  • Desconhecido: uma chamada expirou e o agente não consegue saber se o efeito colateral aconteceu.

As novas tentativas exigem o mesmo cuidado. Uma chave de idempotência definida pelo provedor faz com que uma requisição repetida devolva o resultado original, em vez de criar um segundo registro. Vários provedores de API documentam esse padrão em suas referências. Quando o sistema de destino não oferece essa chave, o harness deve consultar o registro antes de tentar de novo. Ele nunca deve presumir que a primeira tentativa falhou só porque nenhuma resposta voltou.

Um plano de cancelamento que você consegue revisar

Escreva o plano antes da primeira execução longa e guarde-o junto às outras configurações do agente, para que um revisor consiga lê-lo sem ler código. Um plano utilizável responde a estas perguntas:

  • Quais ferramentas o agente pode chamar, e quais delas gravam dados em vez de apenas lê-los?
  • Para cada gravação, qual sistema e qual registro ela altera, e qual confirmação o harness espera receber de volta?
  • Quais são os quatro limites de cada tipo de tarefa e por que cada valor foi escolhido?
  • Quanto dura o período de tolerância, e o que acontece com uma gravação que não termina dentro dele?
  • Quem recebe um registro abandonado ou desconhecido, e em quanto tempo essa pessoa precisa agir?
  • O plano foi testado cancelando uma execução em cada etapa de gravação, e não apenas no final?

Cenário ilustrativo: o agente de uma empresa de serviços cria um orçamento, reserva uma vaga de equipe e depois envia um e-mail ao cliente. O timeout de chamada dispara enquanto a reserva da vaga ainda está pendente. Pelo plano, o harness marca a reserva como desconhecida, consulta o sistema de agenda em busca de uma vaga correspondente na próxima execução e coloca o item na fila da operação, com a referência do orçamento e a última etapa confirmada. Nenhum e-mail ao cliente sai até que uma pessoa confirme a vaga.

Esse mesmo cenário mostra por que o rastro da execução importa. Rastros e spans, conceitos básicos de observabilidade, dão a cada execução interrompida um registro de onde ela parou, que é a primeira informação de que um operador precisa quando um registro parece errado.

Como a Be Human trata timeouts em operações gerenciadas

A Be Human desenha os níveis de timeout, a sequência de cancelamento e os estados dos registros como parte do harness, antes de o agente lidar com trabalho real. Em operações gerenciadas, essas configurações continuam em revisão depois do lançamento. Isso inclui o monitoramento de execuções travadas e canceladas, verificações recorrentes de que os campos de estado ainda batem com os sistemas de destino, revisões de permissão quando o comportamento de uma ferramenta muda e ajustes controlados quando um limite se mostra errado. Cada mudança é registrada com o motivo, para que a equipe veja qual limite mudou, quando e por quê.

Quem define os limites, e com que frequência eles devem mudar?

Os limites pertencem à pessoa que responde pelo resultado, e não apenas ao engenheiro que escreve a configuração. Um responsável financeiro deve decidir até que hora uma conciliação pode rodar e o que precisa acontecer antes que um registro de pagamento seja tocado. Um responsável de operações deve decidir por quanto tempo um trabalho parado pode ficar esperando antes de chegar a uma pessoa. Os engenheiros traduzem essas decisões em configurações e mantêm os motivos ao lado delas. Revise os limites depois de qualquer incidente e também em uma agenda regular, compatível com a velocidade com que o fluxo de trabalho muda.

Comece conservador. Um orçamento curto e um gatilho claro de revisão humana são mais fáceis de afrouxar depois do que uma execução longa que já gravou registros incompletos. A questão mais ampla de quando um loop deve parar e escalar é tratada em condições de parada para agentes de IA, e vale resolvê-la junto com os níveis de timeout.

Se você quer descobrir qual é a primeira tarefa que vale entregar a um agente, e quais regras de timeout essa tarefa exigiria, faça o diagnóstico gratuito de IA da Be Human.

Perguntas frequentes

Quanto deve durar um timeout de agente de IA? Não existe um valor universal. Defina cada nível a partir da necessidade do negócio: por quanto tempo um cliente ou um prazo pode esperar, quanto tempo uma etapa saudável costuma levar e quanto uma execução travada pode custar. Escreva o motivo ao lado de cada valor para que um revisor possa contestá-lo.

Timeout é a mesma coisa que cancelamento? Não. O timeout é o gatilho, a condição que indica que uma execução demorou demais ou parou de progredir. O cancelamento é a resposta controlada: parar o trabalho novo, fechar ou marcar as gravações abertas, registrar o motivo e liberar recursos. Um sistema pode sofrer timeout sem cancelar de forma limpa, e essa é a falha de que trata este artigo.

O que deve acontecer com uma gravação que foi interrompida? Depende do sistema de destino e de a alteração poder ser verificada. Gravações curtas e confirmáveis podem terminar dentro do período de tolerância. Tudo que não puder ser confirmado deve ser marcado como desconhecido ou abandonado e encaminhado a uma pessoa identificada, com a última etapa confirmada anexada, em vez de ser repetido às cegas ou deixado sem registro.

Um agente pode retomar depois de um timeout em vez de começar do zero? Muitas vezes, sim, se a execução salvou checkpoints verificados antes da parada. Retome apenas a partir de estados que o harness consegue confirmar e consulte o sistema de destino de novo antes de repetir qualquer gravação. A abordagem é descrita em checkpoints para agentes de IA de longa duração.

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 →