Quando uma ferramenta falha: como evitar que um agente repita uma ação

O problema: uma ação pode ocorrer sem que a confirmação chegue

Um agente que utiliza ferramentas pode iniciar uma operação noutro sistema e perder a ligação antes de receber uma resposta clara. A tarefa fica então numa situação ambígua: o agente não sabe se o sistema de destino aplicou a alteração, mas a falta de confirmação também não prova que não a tenha aplicado. Voltar a executar a mesma ação sem verificar o estado pode criar um duplicado ou aumentar o impacto.

Este problema é diferente de gerar uma resposta novamente. Numa conversa, uma repetição pode produzir texto diferente; quando uma ferramenta altera um registo, marca uma consulta ou modifica um ficheiro, a repetição pode produzir um segundo efeito externo. Por isso, o procedimento de recuperação deve começar por determinar o que aconteceu, e não por repetir automaticamente a instrução original.

Este guia propõe uma disciplina operacional, não uma garantia de que qualquer sistema possa ser recuperado. A capacidade de verificar, parar ou compensar depende das ferramentas concretas e das funcionalidades que estas documentam. Se não for possível observar o estado de destino, o agente deve tratar a incerteza como motivo para fazer uma pausa ou escalar o caso, e não como autorização para presumir.

Delimitar o fluxo antes de conceber a recuperação

Descreve a tarefa como uma sequência de passos concretos e identifica as ferramentas envolvidas. Para cada passo, regista se apenas lê informação, se escreve ou altera um estado, ou se pode produzir um efeito externo difícil de reverter. Esta classificação permite concentrar os controlos nos passos em que uma repetição pode ter consequências.

Não basta classificar uma ferramenta pelo nome. A mesma integração pode disponibilizar uma consulta e uma operação de escrita. Também não basta descrever a intenção geral do agente: «tratar de uma consulta» pode incluir procurar disponibilidade, criar uma marcação e enviar uma notificação. Cada operação pode ter um estado diferente e exigir uma decisão de recuperação distinta.

Identifica também que observação permite considerar cada passo concluído. Para atualizar um registo, por exemplo, pode ser necessário voltar a lê-lo e verificar os campos relevantes. Para uma marcação, talvez seja preciso consultar se existe uma consulta com os dados esperados. Para modificar código, pode ser possível verificar o conteúdo do ficheiro ou o estado da alteração. Estes são padrões de conceção: devem ser adaptados às capacidades reais de cada sistema.

Antes de permitir uma operação de escrita, define o âmbito: que entidade o agente pode alterar, que dados pode modificar e que ações estão fora das suas permissões. As permissões limitam os danos potenciais, mas não provam que uma ação anterior tenha sido bem-sucedida nem tornam segura uma repetição. A seleção de ferramentas deve manter separadas a autorização e o conhecimento do estado.

Classificar o estado antes de decidir

Após uma falha, regista a última observação fiável e classifica o passo interrompido. Uma taxonomia prática distingue quatro estados: a ação não foi iniciada; o resultado está confirmado; o resultado é incerto; ou a tarefa foi parcialmente concluída. A classificação deve basear-se na evidência disponível, não na explicação que o agente prefira apresentar.

«Não iniciada» significa que há evidência suficiente de que o passo não foi enviado ou não começou. «Confirmada» significa que uma resposta ou uma consulta posterior permite verificar o resultado esperado. «Incerta» significa que falta evidência para decidir se foi executada ou não. «Parcial» indica que alguns passos ou efeitos foram concluídos, enquanto outros continuam pendentes. Se houver dúvida entre duas categorias, mantém a classificação mais prudente e não transformes incerteza em confirmação.

A distinção é importante porque a ação adequada muda. Se o passo não começou, poderá ser possível iniciá-lo, sujeito às permissões e às regras do fluxo. Se estiver confirmado, não deve ser repetido apenas para obter uma resposta mais clara. Se for incerto, consulta primeiro o sistema de destino; se não houver uma consulta fiável, para ou escala o caso. Se o trabalho estiver parcialmente concluído, retoma apenas a partir de um estado verificado, tendo em conta os efeitos que já ocorreram.

O estado do agente não deve ser confundido com o estado do sistema externo. Um checkpoint pode guardar os passos que o fluxo tentou executar ou a resposta que recebeu, mas essa informação pode ficar desatualizada se outro processo alterar o destino ou se a confirmação se perder. O checkpoint ajuda a recuperar contexto; por si só, não prova qual é o estado atual.

Antes de repetir, consulta o destino e procura sinais de duplicação

A primeira pergunta operacional não é «posso chamar novamente a ferramenta?», mas sim «o que posso observar agora no sistema afetado?». Se houver uma consulta autorizada, procura o objeto ou a alteração relacionada com a tarefa usando os dados que a identificam. Verifica se os atributos relevantes coincidem e se já existe um resultado equivalente. Evita depender de um único sinal se este não permitir distinguir a operação atual de outras semelhantes.

Uma solicitação pode ter um identificador de operação ou uma referência própria da tarefa. Se o sistema documentar uma forma de consultar a operação ou reconhecer pedidos duplicados, segue esse mecanismo tal como está documentado. Não suponhas que todas as ferramentas aceitam uma chave de idempotência, que um identificador impede efeitos repetidos ou que um resultado com o mesmo texto corresponde necessariamente à mesma ação.

A deteção de duplicados exige critérios claros. Para atualizar um registo, compara o identificador do registo e os campos que se pretendia alterar. Para uma consulta, verifica os dados que distinguem essa marcação e o seu estado atual. Para uma alteração de código, inspeciona o ficheiro ou o estado da alteração antes de aplicar outra modificação. São exemplos de verificação, não descrições de funcionalidades garantidas de um fornecedor.

Se a consulta do estado não estiver disponível, devolver informação incompleta ou não permitir distinguir uma operação anterior, a incerteza mantém-se. Nesse caso, define uma condição de paragem. A falta de uma resposta verificável não deve transformar-se numa suposição favorável, sobretudo quando uma segunda execução pode criar um efeito adicional.

Escolher entre continuar, compensar, parar ou escalar

Continua quando o estado anterior for suficientemente conhecido, o passo pendente estiver dentro do âmbito autorizado e existir uma forma de verificar o resultado. Retomar significa avançar a partir do último estado confirmado, não reproduzir toda a sequência desde o início. Se o fluxo tiver vários passos, identifica quais estão confirmados e quais ainda não começaram, para evitar repetir trabalho que já produziu efeitos.

Uma compensação tenta corrigir um efeito confirmado através de uma ação diferente. Nem sempre é possível, e não equivale necessariamente a repor exatamente a situação inicial. Antes de a conceber, confirma que o sistema documenta essa operação, que a conta tem permissão para a executar e que a alteração não afetará um estado posterior. Se não conseguires confirmar estes requisitos, não a apresentes como uma reversão garantida.

Parar é uma decisão válida quando a ação seguinte pode agravar uma situação incerta, excede o âmbito autorizado ou não dispõe de verificação suficiente. É adequado escalar o caso para uma pessoa quando é necessário interpretar evidência ambígua, aprovar uma ação de maior impacto, avaliar uma compensação ou decidir como tratar uma alteração que não pode ser desfeita com segurança. A pausa deve preservar o contexto mínimo necessário para rever o caso.

Define antecipadamente as condições que exigem intervenção humana. Por exemplo: resultado de escrita incerto sem consulta ao destino; operação com consequências relevantes cuja repetição possa duplicar um efeito; compensação não documentada; permissão insuficiente para verificar; ou discrepância entre o estado guardado no fluxo e o sistema de destino. Ajusta estes limiares ao impacto e às obrigações do contexto, em vez de aplicar uma regra única a qualquer ação.

Exemplos práticos: marcação e alteração de código

Numa marcação de consulta, perder a resposta depois de enviar o pedido deixa em aberto a possibilidade de a consulta já existir. O agente deve consultar o estado da marcação com as capacidades realmente disponíveis e verificar se a consulta esperada aparece. Se encontrar um resultado correspondente, não deve criar outra marcação para resolver a falta de confirmação. Se não conseguir distinguir uma operação já realizada de outra ainda pendente, deve interromper a tentativa automática e pedir uma revisão de acordo com a política do serviço.

A verificação também deve ter em conta que o estado pode mudar entre a consulta e a ação seguinte. Por isso, o fluxo não deve tratar uma observação antiga como uma garantia indefinida. Se a ferramenta oferecer uma referência de operação ou uma consulta de estado documentada, utiliza-a; caso contrário, limita as conclusões ao que foi efetivamente possível observar. Não afirmes ao utilizador que a marcação está confirmada se a evidência apenas mostrar que o agente tentou pedi-la.

Ao alterar código, o risco não se limita a repetir uma escrita no mesmo ficheiro. O conteúdo pode ter mudado desde o checkpoint, ou uma parte da tarefa pode ter sido aplicada enquanto outra ficou pendente. Antes de voltar a modificá-lo, inspeciona o estado atual e compara a alteração esperada com o resultado observável. Se a modificação já estiver presente, evita aplicá-la novamente às cegas. Se o estado for diferente ou não puder ser reconstruído, interrompe o fluxo para rever o que deve ser preservado e o que pode ser corrigido.

Nos três exemplos, o agente deve comunicar o resultado com precisão: tentativa realizada, efeito confirmado, resultado incerto ou intervenção necessária. A descrição do processo não deve transformar uma chamada emitida numa tarefa concluída.

Guardar contexto útil sem o confundir com o estado atual

Para retomar uma tarefa, não é necessário conservar indiscriminadamente toda a conversa. Guarda o estado operacional que permite reconhecer a tarefa e reconstruir as decisões: identificador ou referência da tarefa, se existir; passo atual; ferramenta e operação invocadas; última resposta observada; estado classificado; verificações realizadas e respetivo momento; efeitos confirmados; e motivo de qualquer pausa ou escalamento. Regista também o que está pendente e que limites de autorização se aplicam.

Evita guardar dados sensíveis que não sejam necessários para a recuperação. Define quem pode consultar o registo, durante quanto tempo é conservado e como é eliminado ou protegido de acordo com as regras do contexto. O período de conservação não deve ser inventado como um valor universal: depende dos requisitos de privacidade, auditoria e operação aplicáveis. Se o registo contiver dados pessoais ou detalhes dos sistemas, limita o seu âmbito e o acesso a ele.

A memória conversacional e um checkpoint de tarefa têm funções diferentes. A primeira pode ajudar a contextualizar o que o utilizador pediu; o segundo deve representar o estado operacional observado pelo fluxo. Nenhum deles substitui uma consulta ao sistema de destino quando a tarefa depende de um efeito externo que pode ter mudado. Trata a memória como uma indicação que orienta a recuperação, não como evidência suficiente de que o mundo externo continua igual.

Inclui marcas temporais ou a ordem das observações quando forem necessárias para interpretar o registo. Se outra pessoa ou processo puder alterar o sistema, uma leitura anterior pode ter ficado desatualizada. Ao retomar uma operação sensível, volta a verificar os dados relevantes em vez de presumir que o checkpoint continua válido.

Permissões e autonomia: limitar o que o passo de recuperação pode fazer

Concebe as permissões para que cada operação tenha o âmbito mínimo necessário. Se o agente só precisar de verificar um resultado, não pressuponhas que também deve poder alterar outros registos ou cancelar operações. Se uma compensação exigir uma permissão diferente, separa-a da consulta e define que condição autoriza a sua utilização. Assim, torna-se clara a diferença entre observar, agir e corrigir.

A recuperação não deve aumentar a autonomia apenas porque o fluxo falhou. Um agente que tinha permissão para efetuar uma alteração inicial não ganha automaticamente permissão para executar ações adicionais, revertê-la ou modificar objetos relacionados. Especifica que decisões são automáticas, quais exigem aprovação e que informação deve ser apresentada à pessoa para que esta possa decidir.

A aprovação humana deve referir-se a uma ação concreta e à respetiva evidência. Em vez de pedir uma autorização genérica para «resolver o problema», explica que estado foi observado, o que não pôde ser confirmado, que ação é proposta e que efeitos poderá ter. Se faltar informação essencial, o passo seguinte deve ser obtê-la ou parar, não pedir uma aprovação que esconda a incerteza.

As permissões reduzem o conjunto de ações possíveis; não resolvem, por si só, falhas parciais. Mantém separadas as barreiras de âmbito, os mecanismos de consulta e as regras de recuperação. Um desenho fiável precisa dos três elementos sempre que a tarefa possa produzir alterações externas.

Testar falhas reproduzíveis antes da implementação

Os testes devem simular não só erros da ferramenta, mas também a separação entre execução e confirmação. Um caso importante é aquele em que o sistema de destino aplica uma alteração, mas o agente não recebe a resposta. O teste verifica se o fluxo consulta o destino ou para, em vez de repetir automaticamente. Se o ambiente de teste não conseguir reproduzir esse comportamento, documenta a limitação e verifica, pelo menos, a política de incerteza com respostas ambíguas controladas.

Inclui confirmações tardias. Por exemplo, o agente pode fazer uma pausa e começar uma verificação enquanto a resposta da operação original chega mais tarde. Verifica se essa resposta tardia atualiza o estado de forma coerente e não desencadeia uma segunda execução. Testa também o caso oposto: a primeira operação não foi realizada e o fluxo obtém evidência suficiente para iniciar o passo pendente de acordo com as suas regras.

Acrescenta cenários com duplicados, estado parcial, consulta ao destino indisponível, permissões insuficientes e compensação não documentada. Para cada um, define o resultado esperado antes de executar o teste: que ações o agente pode realizar, quais deve evitar, o que deve registar e quando deve escalar. Um teste que apenas verifica se o agente responde não demonstra que a recuperação seja segura.

Utiliza resultados verificáveis. Conta quantas operações de escrita foram executadas, verifica o estado final no sistema de destino, identifica duplicados e revê se ocorreram efeitos fora do âmbito autorizado. Avalia separadamente a tarefa original e a recuperação: o facto de o utilizador acabar por obter um resultado não basta para demonstrar que o fluxo evitou uma repetição ou respeitou os seus limites.

Repete os testes quando mudarem as ferramentas, as permissões, a política de retoma ou o formato dos checkpoints. Regista as versões e as condições relevantes para que os resultados possam ser reproduzidos. Não interpretes um teste aprovado como garantia perante qualquer falha futura: demonstra apenas o comportamento observado nos cenários definidos.

Avaliar o fluxo e preparar a implementação

Avalia a recuperação através de várias medidas, e não de uma única etiqueta de sucesso. Analisa quantas vezes uma operação de escrita foi repetida, quantos resultados finais foram confirmados, quantos casos foram corretamente interrompidos e quantas ações excederam as permissões. Inclui uma revisão dos escalamentos para determinar se continham contexto suficiente e se foram ativados perante as condições previstas.

Interpreta as métricas em conjunto com os casos de teste e o impacto possível. Uma baixa taxa de repetição não prova que o sistema seja seguro se também deixou passar tarefas ambíguas sem as detetar. Um estado final correto também não basta se tiver sido alcançado através de uma ação duplicada ou de uma compensação não autorizada. Define antecipadamente que resultados são aceitáveis e que falhas impedem a implementação.

Antes de ativar ações de maior impacto, ensaia o procedimento com operações de baixo risco ou num ambiente de teste adequado. Confirma que as consultas de estado funcionam, que as permissões são suficientes para verificar sem serem excessivas para agir, que os registos permitem reconstruir o que aconteceu e que as pausas chegam a uma pessoa capaz de decidir. Se alguma dependência não estiver disponível, limita o âmbito da automatização em vez de presumir que o agente conseguirá resolver a situação.

As fontes disponíveis incluem documentação sobre resolução de problemas de utilização de ferramentas e orientações gerais sobre gestão de incidentes e recuperação de desastres. Por si só, não estabelecem como uma integração concreta se comporta perante a perda de uma resposta, se permite detetar duplicados ou se uma operação pode ser revertida. Estes pontos devem ser verificados para cada sistema antes de transformar uma recomendação de conceção numa instrução operacional.

Continue a explorar

Correções e transparência

Se encontrar informação incorreta ou desatualizada, envie-nos a página e a fonte que devemos rever.