Ferramentas idempotentes e conscientes dos efeitos colaterais

Um cliente de IA pode tentar novamente uma ferramenta após um tempo limite ou uma conexão interrompida. Sua ferramenta pode ser executada duas vezes quando o usuário pretendia apenas uma.

Uma ferramenta é idempotente quando chamá-la novamente com a mesma entrada não altera mais nada. A segunda chamada é, com segurança, uma operação sem efeito.

Ferramentas puras de leitura, como buscar um registro, já são idempotentes. Repeti-las apenas retorna a mesma resposta, sem causar danos.

Uma ferramenta que cria algo ou cobra dinheiro é perigosa para repetir. Uma nova tentativa cega pode adicionar uma linha duplicada ou cobrar duas vezes.

Peça ao chamador uma chave de idempotência. Se essa chave já tiver sido processada, retorne o resultado armazenado em vez de agir novamente.

Um upsert grava ou atualiza usando um identificador estável; portanto, executá-lo duas vezes deixa uma linha, não duas. Ele incorpora as novas tentativas a um único estado.

Informe na descrição da ferramenta se ela altera dados. O modelo toma decisões melhores quando sabe que uma chamada é destrutiva.

Mantenha uma ferramenta de consulta e uma ferramenta de alteração distintas, em vez de uma que às vezes escreve. Limites claros reduzem alterações acidentais.

Sempre que possível, retorne a mesma saída para a mesma entrada. Resultados previsíveis ajudam os clientes a armazenar em cache e a raciocinar sobre sua ferramenta.

Antes de uma escrita, confirme o estado atual do destino. Se a alteração já tiver sido aplicada, informe sucesso sem refazê-la.

Se uma ferramenta tocar em várias linhas, execute-as em uma única transação. Assim, uma nova tentativa aplica tudo ou desfaz tudo, nunca apenas uma parte.

Torne as escritas idempotentes usando chaves ou upserts, declare os efeitos colaterais, separe leituras de escritas e use transações. A seguir: versionamento. ♻️