Retomada de Agentes, Explicada: Sessões, Turnos, Pausas e Reconexões no TrueForge

Retomar um agente não é uma operação única. Sistemas de produção devem distinguir entre reconectar um fluxo, continuar um fluxo de trabalho pausado e recuperar um efeito colateral externo incerto.

“Retomar” oculta três problemas de recuperação diferentes

Agentes de longa duração falham em mais pontos do que uma API convencional de solicitação-resposta. Um navegador pode se desconectar enquanto o servidor continua trabalhando. Um fluxo de trabalho pode parar intencionalmente porque uma pessoa, uma ferramenta do lado do cliente ou um fluxo OAuth precisa fornecer uma entrada. Uma API downstream pode expirar após confirmar uma mutação. Todas as três situações podem ser descritas como “retomar”, mas exigem estados, evidências e regras de segurança diferentes.

O primeiro é a recuperação de transporte: reconectar a um fluxo ainda em execução sem duplicar eventos. O segundo é a continuação do fluxo de trabalho: criar uma nova unidade de trabalho que responde a uma pausa registrada. O terceiro é a recuperação de efeito: estabelecer se uma operação externa foi confirmada antes de decidir se deve tentar novamente, compensar ou parar. Tratar isso como um mecanismo único cria o tipo mais perigoso de erro de confiabilidade — aquele que parece bem-sucedido enquanto repete ou ignora uma ação do mundo real.

Os três ramos terminam deliberadamente em ações diferentes. Uma sequência de fluxo repara a observação, uma referência de ação necessária continua o fluxo de trabalho e um ID de operação suporta a reconciliação; substituir um identificador por outro cria duplicatas ou conclusões falsas.

Comece com a hierarquia do TrueForge

O TrueForge documenta uma hierarquia de Agente → Sessão → Turno → Evento → Delta. Um agente é uma definição reutilizável. Uma sessão representa um problema ou conversa e persiste entre turnos. Um turno é um ciclo de solicitação e execução que é executado até terminar ou pausar. Eventos descrevem o que aconteceu durante aquele turno. Alguns eventos de mensagem produzem deltas durante o streaming; listagens de eventos persistidos retornam o evento mesclado em vez de cada fragmento em tempo real.

Essa hierarquia é importante porque cada camada responde a uma pergunta de recuperação diferente. A definição do agente estabelece o modelo configurado, instruções, ferramentas e limites. A sessão fornece continuidade conversacional durável. O turno fornece um limite de execução com um estado terminal. Eventos expõem as evidências ordenadas necessárias para reconstruir uma visualização do cliente. Deltas otimizam a experiência em tempo real, mas não são fatos de negócios duráveis separados.

O TrueForge permite que apenas um turno seja executado em uma sessão por vez. Os turnos são encadeados automaticamente, para que a aplicação não precise reenviar o histórico completo a cada solicitação. Criar um novo turno enquanto outro ainda está em execução cancela o turno ativo. Esse comportamento é útil, mas significa que uma interface de usuário não deve traduzir cada clique impaciente em um novo turno sem uma decisão de produto explícita.

A reconexão de transporte não é a continuação do fluxo de trabalho

Um turno em tempo real usa um fluxo de Eventos Enviados pelo Servidor (SSE). Cada item transmitido carrega um identificador de sequência que o cliente pode reter. Se a conexão cair, o cliente pode se inscrever novamente após o último número de sequência processado. O servidor pode então reproduzir eventos posteriores do mesmo turno em execução. Um cliente correto armazena eventos por ID de evento e mescla deltas em seu evento de mensagem base, para que a retransmissão não duplique a saída visível.

Isso é a reconexão de transporte. O turno original não foi pausado para uma decisão de negócios; apenas a conexão de rede foi interrompida. O servidor pode continuar executando enquanto o cliente está ausente. Portanto, uma interface de usuário que se reconecta pergunta: “Quais eventos deste turno existente eu ainda não renderizei?”. Ela não deve criar outro turno ou reemitir a instrução original do usuário.

Assim que um turno termina, seus eventos persistidos podem ser lidos novamente para reconstruir o histórico consolidado. Isso é a reprodução de evidências, não a reexecução do modelo e das ferramentas. A distinção é importante para a análise de incidentes: a mesma sequência armazenada deve produzir a mesma visualização reconstruída, mas uma tentativa de executar a tarefa novamente pode encontrar modelos, ferramentas, credenciais e estados externos diferentes.

A figura separa a hierarquia durável da mecânica de entrega. Deltas pertencem ao fluxo em tempo real e são mesclados em eventos base, enquanto sessões, turnos encadeados, estados terminais e eventos persistidos fornecem o registro consolidado usado após a reconexão ou reinicialização.

Pausas são estados de tempo de execução explícitos

Um turno pode terminar com ações necessárias em vez de uma resposta final. O TrueForge documenta três casos importantes: uma ferramenta bloqueada precisa de aprovação, uma ferramenta do lado do cliente precisa de uma resposta ou um servidor MCP precisa de autorização. O estado terminal do turno identifica os itens pendentes. A aplicação os satisfaz criando um novo turno contendo a aprovação correspondente, a resposta da ferramenta ou a continuação da autenticação.

Esta é uma continuação de fluxo de trabalho, não uma reconexão de stream. O turno pausado já foi resolvido. O próximo turno preserva a continuidade causal ao referenciar a ação pendente e ao encadear o histórico da sessão. Um único turno pode apresentar mais de um item pendente, incluindo pausas de threads de subagentes paralelos; portanto, os clientes devem coletar o conjunto completo de ações necessárias em vez de presumir que existe apenas uma.

Para pausas de aprovação e resposta, o evento de origem vincula o item pendente à mensagem do modelo que propôs a chamada de ferramenta. Esse link permite que o aplicativo mostre ao revisor o nome da ferramenta e os argumentos que criaram o ponto de verificação. É também a base para verificar se a continuação responde à chamada pretendida, em vez de uma visualmente semelhante.

Construa um contrato de retomada

‍