O agente parou no meio da tarefa. Talvez uma pessoa precise aprovar o próximo passo. Talvez o processo tenha reiniciado enquanto uma ferramenta atualizava um sistema externo. Quando o run volta, começar pelo prompt original parece simples, mas mistura trabalho concluído, trabalho pendente e efeitos cujo resultado ninguém confirmou.

Para pausar e retomar um agente de IA com segurança, persista uma fronteira de execução que o runtime possa explicar. Salve a intenção, o próximo passo, os pedidos pendentes, a aprovação e os recibos das ferramentas. Ao retomar, use a mesma identidade do run, valide a versão do estado e investigue qualquer efeito externo que possa ter acontecido antes da interrupção.

O guia de execução durável para agentes de IA cobre a escolha entre fila e workflow. Este texto trata de uma fronteira menor: o que significa pausar um run e quais provas são necessárias antes de continuar.

O código é ilustrativo. Não foi executado contra um SDK de agente neste repositório. Ele serve para tornar o contrato explícito e para orientar testes com o adapter escolhido.

Diagrama mostra um agente de IA pausando, salvando um checkpoint e retomando após verificar um efeito externo.

Resposta curta

  • Pause em uma transição que o runtime consiga gravar, não no meio de uma ação sem recibo.
  • Separe intenção do agente, progresso do runtime e consequência da ferramenta.
  • Retome um único run com posse exclusiva, estado versionado e aprovação ainda válida.
  • Se o efeito externo for incerto, observe o sistema antes de repetir a ação.

Pausar é diferente de cancelar ou tentar de novo?

Pausar preserva a possibilidade de continuar o mesmo run. Cancelar encerra a execução e pode exigir uma ação compensatória. Tentar de novo cria uma nova tentativa, que pode repetir uma decisão ou uma ferramenta. A documentação do OpenAI Agents SDK, "Run State" trata o estado serializável como a fronteira para interromper e retomar fluxos com participação humana.

Esses estados precisam aparecer no modelo do runtime. paused pode significar que a execução aguarda uma pessoa ou uma janela operacional. cancelled diz que o run não deve continuar. failed informa que a execução terminou com erro. running só deve voltar depois que o processo recuperou o checkpoint e obteve a posse do run.

Não transforme toda interrupção em retry. Se uma ferramenta criou um pedido, enviou uma mensagem ou alterou um registro, o processo local pode ter caído antes de receber a resposta. O nome da operação é diferente, mas o problema é o mesmo dos tool calls duplicados no fallback de LLM: o executor precisa saber se o efeito já existe.

O que um checkpoint de agente precisa guardar?

Um checkpoint útil guarda o estado necessário para decidir o próximo passo, e não apenas o histórico que o modelo viu. O Microsoft Agent Framework, "Checkpoints" descreve checkpoints que incluem o estado dos executores, mensagens pendentes, pedidos e respostas pendentes e estados compartilhados. Isso torna o checkpoint uma fronteira do workflow, não um arquivo de conversa.

Uma estrutura mínima pode ter estes campos:

Campo Para que serve
runId Impede que dois workers retomem a mesma execução sem coordenação.
stateVersion Permite rejeitar ou migrar um checkpoint antigo.
status Diferencia execução, pausa, aprovação, cancelamento e falha.
nextStep Indica a primeira transição ainda não confirmada.
pendingApproval Guarda o pedido e a representação do que foi aprovado.
toolReceipts Registra o resultado observado e os IDs externos criados.
updatedAt Ajuda a detectar posse abandonada e estado velho.

O transcript pode continuar armazenado para contexto e auditoria, mas não deve ser a única fonte para recuperação. Um resumo pode ajudar o modelo a decidir. Um recibo bruto ajuda o runtime a provar que uma chamada foi aceita, rejeitada, concluída ou ficou desconhecida.

O campo mais importante não é lastMessage. É nextStep acompanhado do que o runtime sabe sobre o efeito anterior. Uma mensagem pode ter sido gerada sem ser persistida. Uma chamada pode ter sido aceita sem sua resposta chegar. O checkpoint precisa preservar essa diferença para que a retomada não adivinhe.

Onde é seguro criar a fronteira de pausa?

Crie a fronteira depois de uma transição confirmada e antes de admitir a próxima ação. O Google Developers Blog, "Build long-running AI agents that pause, resume, and never lose context with ADK" mostra esse padrão com sessões persistentes e checkpoints associados ao estado do agente. A persistência precisa sobreviver ao processo que está executando o run.

Na prática, há quatro momentos diferentes:

  1. O agente propôs uma ferramenta, mas ela ainda não foi enviada. Pause e grave a proposta como pendente.
  2. A ferramenta foi enviada e um recibo confirma o resultado. Grave o recibo e avance nextStep.
  3. A ferramenta foi enviada, mas o processo caiu antes do recibo. Marque o efeito como unknown e observe o sistema externo antes de decidir.
  4. A pessoa aprovou uma ação, mas o contexto mudou. Revalide a aprovação ou volte para revisão manual.

Um checkpoint no meio de uma função que combina chamada de modelo e efeito externo é uma fronteira fraca. Se o processo cair entre as duas partes, o runtime não consegue afirmar qual delas aconteceu. Separe preparação, commit e observação quando a operação puder criar um efeito difícil de desfazer.

Como representar pausa e retomada no runtime?

O runtime deve decidir se pode avançar; o modelo deve sugerir o próximo passo. O trecho abaixo representa essa divisão com tipos simples. Os nomes não são uma API de fornecedor e não pretendem substituir o contrato do seu executor.

type RunStatus =
  | "running"
  | "paused"
  | "waiting_for_approval"
  | "failed"
  | "cancelled"
  | "completed";

type ToolReceipt = {
  operationId: string;
  status: "committed" | "rejected" | "unknown";
  externalId?: string;
};

type AgentCheckpoint = {
  runId: string;
  stateVersion: number;
  status: RunStatus;
  nextStep: string;
  pendingApproval?: { inputHash: string; approvedBy?: string };
  toolReceipts: ToolReceipt[];
};

function canResume(checkpoint: AgentCheckpoint): boolean {
  return checkpoint.status === "paused" ||
    checkpoint.status === "waiting_for_approval";
}

O adapter de produção ainda precisa fazer a parte difícil: salvar o checkpoint de forma atômica, adquirir um lease ou outra forma de posse exclusiva e consultar os IDs externos antes de executar uma operação unknown. O tipo só deixa as decisões visíveis. Ele não cria idempotência por conta própria.

Como retomar depois de uma aprovação humana?

Retome a execução original quando o checkpoint contém a aprovação, o pedido aprovado e a identidade da sessão necessária. O OpenAI Agents SDK, "Sessions" recomenda manter a mesma sessão ao retomar um RunState; também descreve proteções para não persistir uma saída ambígua como se fosse definitiva.

A aprovação deve ser ligada ao que a pessoa realmente revisou. Guarde um hash ou uma representação canônica da entrada aprovada, além do identificador do revisor e da política aplicável quando isso fizer parte do seu sistema. Ao retomar, compare a entrada atual com a aprovada. Se o plano, destinatário, valor ou permissão mudou, peça aprovação outra vez.

Isso também separa duas perguntas que costumam ficar misturadas: "a execução pode continuar?" e "o efeito ainda está autorizado?". O primeiro pertence ao runtime. O segundo depende do estado atual, da política e da ferramenta. O guia sobre quando um agente deve pedir aprovação humana detalha a decisão de pedir revisão; aqui, a preocupação é não tratar uma aprovação velha como passe permanente.

Como lidar com um efeito externo desconhecido?

Não repita uma ferramenta quando o único fato conhecido é que o cliente não recebeu a resposta. A orientação da AWS, "Implement comprehensive state management and checkpoint-based recovery" liga recuperação segura a passos idempotentes, chaves de idempotência, escritas condicionais e deduplicação de eventos.

O caminho de retomada deve consultar a fonte externa com o operationId, quando essa consulta existir. Há três respostas úteis:

  • committed: o efeito foi encontrado. Registre o recibo e avance sem chamar a operação novamente.
  • not_found: o sistema confirma que o efeito não existe. Reavalie a política e execute com a mesma identidade de operação, se isso for seguro.
  • unknown: não há prova suficiente. Pare, marque a execução para revisão ou use uma ação de reconciliação definida pelo domínio.

Não use o transcript como recibo. Ele prova que o modelo pediu uma ação, mas não prova que o serviço externo a aceitou. Também não esconda unknown atrás de um resumo otimista. A observabilidade de agentes de código no CI usa a mesma fronteira: decisões e efeitos precisam ser distinguíveis no registro.

Quando o agente pode passar muito tempo aguardando, o RemoteCode é a ferramenta que uso para manter sessões e contexto de agentes visíveis. Isso descreve meu uso da ferramenta, não um teste de desempenho deste artigo.

Como escolher onde guardar o estado?

Guarde o checkpoint em armazenamento durável, privado e acessível ao worker que vai retomar o run. Uma memória local funciona apenas enquanto o mesmo processo continua vivo. O artigo do Google sobre agentes longos usa armazenamento de sessão persistente porque o processo pode reiniciar ou ficar ocioso entre duas etapas.

O Microsoft Agent Framework, "Checkpoints" também trata o armazenamento como uma fronteira de confiança. Proteja leitura e escrita, valide o formato antes de desserializar e não aceite checkpoints fornecidos por uma fonte não confiável. Um snapshot que contém objetos ou instruções inesperadas pode virar um problema de segurança no momento da retomada.

Separe responsabilidades conforme o volume e o risco:

Dado Armazenamento e regra
Estado atual Banco ou store transacional com controle de versão e posse.
Recibos de ferramentas Registro durável, consultável pelo operationId.
Contexto do modelo Sessão ou resumo compacto, com retenção definida.
Eventos de auditoria Log append-only com redaction de segredos.

Não escolha Redis, SQLite, um workflow gerenciado ou um banco relacional só porque o nome aparece na documentação de um fornecedor. A decisão depende de durabilidade, concorrência, retenção, recuperação e do nível de controle que o executor precisa.

Como testar uma retomada sem duplicar trabalho?

Teste a interrupção nos limites em que o estado pode divergir. A documentação do OpenAI Agents SDK, "Testing" é uma referência para testar runs e respostas de agentes; para este caso, o fixture também precisa controlar o armazenamento e o executor falso.

Um conjunto mínimo deve verificar:

Interrupção Resultado esperado
Antes de enviar a ferramenta A retomada envia uma única operação pendente.
Depois de a ferramenta confirmar A retomada usa o recibo e não envia de novo.
Depois do envio, antes do recibo A retomada consulta o efeito antes de decidir.
Enquanto aguarda aprovação A retomada conserva o pedido e valida sua entrada.
Depois de o estado mudar de versão O runtime migra ou rejeita o checkpoint de forma explícita.
Dois workers tentam retomar Um obtém a posse; o outro não executa o run.
O usuário cancela durante a pausa O run termina como cancelled e não volta a running.

Mate o processo em cada ponto, restaure o estado e verifique os efeitos no fake executor. Depois repita com uma resposta diferente do modelo. Se a conclusão depende de o modelo escolher exatamente a mesma ferramenta, o teste está reproduzindo o prompt, não provando a segurança da retomada.

Perguntas frequentes

Pausar um agente salva o histórico completo da conversa?

Não necessariamente. Um checkpoint precisa conter o estado necessário para o runtime continuar, enquanto o histórico pode ter outra política de retenção. O OpenAI Agents SDK, "Run State" separa snapshot serializável, itens gerados, contexto e interrupções. Salve o que a próxima decisão precisa e preserve o transcript conforme sua política.

Posso retomar o agente em outro processo?

Sim, desde que o estado esteja em armazenamento compartilhado e o novo processo consiga reidratar o contexto exigido. A identidade do run precisa ter posse exclusiva durante a retomada. Se o SDK depender da mesma sessão ou de um identificador de conversa, mantenha esse vínculo; se o estado estiver ambíguo, pare e faça reparo manual.

Checkpointing garante que uma tool call só aconteça uma vez?

Não. O checkpoint informa o que foi persistido, mas a ferramenta precisa reconhecer a operação e consultar seus próprios efeitos. A orientação da AWS para recuperação baseada em checkpoints recomenda idempotência e deduplicação porque uma retomada pode reencontrar uma janela em que a chamada foi aceita, mas o resultado não foi gravado.

Conclusão

Uma retomada segura não tenta reconstruir o passado a partir do prompt. Ela carrega um checkpoint que o runtime consegue explicar, conserva a intenção e o próximo passo, e consulta as consequências antes de repetir qualquer ação.

O desenho pode começar pequeno: status explícito, runId, nextStep, versão do estado e recibos de ferramentas. Depois, adicione posse exclusiva, revalidação de aprovação, migração de schema, retenção e testes de interrupção. O ponto que não deve ser adiado é a fronteira de responsabilidade: o runtime decide o progresso, e a ferramenta responde pelo efeito que deixa no mundo.

Fontes consultadas