Erros de tools: como um agente se recupera e quando deve parar

Um erro é um resultado, mas não é o dado solicitado

Consultar um peso pode retornar 76 kg, informar que o registro está ausente ou falhar porque o armazenamento não pode ser lido. Os três casos retornam algo da função, mas só o primeiro contém o dado solicitado. Quando tudo chega como texto sem um estado explícito, o modelo precisa deduzir o que aconteceu pela redação.

Um erro esperado faz parte do domínio: uma data sem registro, um campo inexistente ou argumentos que não seguem o schema, o formato aceito da solicitação. Uma exceção inesperada é diferente: uma leitura ou gravação interrompida dentro do app. Separar esses casos permite corrigir uma solicitação sem tratar cada falha como uma queda do provedor.

O harness precisa distingui-los antes de chamar o modelo novamente. Uma frase que começa com “Erro” não constitui um contrato. Também não devemos classificar um texto salvo pelo usuário como falha por conter is_error: dados continuam sendo dados.

Um contrato que explica como se recuperar

A execução retorna duas partes: o conteúdo que o modelo verá e uma marca explícita de erro controlada pelo programa. O exemplo abaixo é um payload interno ilustrativo, não um campo obrigatório de todas as APIs. A mensagem permanece em espanhol, como no exemplo prático. Além do código estável not_found, descreve o alcance da falha e sugere um caminho de recuperação.

{
  "kind": "tool_error",
  "version": 1,
  "is_error": true,
  "error": "not_found",
  "message": "No hay registro para esa fecha. No implica que no haya registros en otras fechas.",
  "recovery": "choose_alternative",
  "recoverable": true
}

correct_arguments permite corrigir os argumentos; choose_alternative permite outra consulta quando há informação suficiente; stop_turn exige parar. São rótulos do contrato deste app. O modelo pode propor uma alternativa, mas o harness continua validando cada chamada e aplicando o limite de rodadas.

“Não há registro nessa data” não significa “não há registros”. Essa precisão impede que uma ausência local vire uma afirmação global. A marca de erro distingue o estado; a mensagem ajuda o modelo a raciocinar sobre o próximo passo.

A mesma falha em três provedores

Os adapters, as partes que traduzem o contrato local para cada API, preservam o identificador que conecta a chamada ao resultado. O formato externo muda; a decisão sobre a falha da execução permanece.

• Anthropic Messages: o bloco tool_result leva is_error: true e o conteúdo seguro da falha.
• Google Interactions: function_result também aceita is_error. Esta comparação se refere especificamente a Interactions.
• OpenAI Responses: function_call_output.output contém o JSON serializado do erro. Não adicionamos um is_error incompatível no nível superior.

A marca é preservada ao reproduzir um resultado já registrado. Ela não é deduzida novamente pelo texto. Um resultado recuperado do histórico mantém, assim, o mesmo significado que tinha na execução.

Onde colocar o try/catch

Validar antes de executar evita efeitos com argumentos inválidos. Depois, a captura de exceções deve envolver a execução real do handler, a função que realiza a operação. Capturar apenas a chamada ao provedor deixa as falhas locais de fora.

validate the tool name and arguments
if validation fails:
    return a marked error with recovery = correct_arguments

try:
    result = execute the handler
    return result with its explicit success or error status
catch an unexpected exception:
    if the tool only reads:
        return a safe error that allows an alternative
    else:
        stop the turn locally
        say that completion cannot be confirmed
        do not repeat the action automatically

Este pseudocódigo resume a decisão, não todo o ciclo. Falhas esperadas seguem o contrato normal; exceções viram mensagens seguras. A exceção original pode ajudar no diagnóstico local, mas não deve aparecer como confirmação de sucesso nem expor detalhes internos ao modelo. Uma falha local fatal também não recebe o rótulo “Erro do provedor”.

Uma conversa real com o Coach

Teste exploratório de 4 de outubro de 2026 na versão web 1.51.0 do Gymnasia, com OpenAI gpt-6-luna. As datas e os pesos eram fictícios. Ler medidas permite consultar o peso salvo de um dia sem alterar registros.

Usuário, tradução: consulte o peso de 2020-01-02. Se não existir, consulte 2020-01-01. Não crie nem altere dados.

Coach, tradução: Falta o registro de 2020-01-02. Em 2020-01-01 há um peso salvo: 76 kg.

A solicitação foi abreviada aqui. As requisições reais mostraram a sequência completa: read_measurement para o dia 2, erro marcado com choose_alternative, leitura do dia 1 e resposta final. Verificamos o conteúdo enviado ao provedor, além do texto visível.

Para uma data ausente, o formato antigo produziu “Você não tem medidas registradas para 2020-01-02”. O contrato novo produziu “Não há um registro de medidas para 2020-01-02. Isso não permite saber se há registros em outras datas”. São traduções das respostas em espanhol. A mensagem nova também era mais precisa: essa comparação não isola o efeito da marca nem prova que todos os modelos melhoram. O valor do contrato é tornar explícita a decisão do programa, mesmo quando um modelo já interpreta o texto corretamente.

Uma gravação incerta muda a decisão

Uma leitura pode ser repetida sem criar um registro. Uma gravação interrompida pode ter terminado antes da falha na confirmação. “Falhou” nem sempre significa “não fez nada”. Repetir por padrão pode duplicar uma ação.

Na mesma sessão, provocamos uma falha controlada na persistência de um peso fictício. O modelo era real; a falha de armazenamento foi injetada para QA. O Coach exibiu esta mensagem, traduzida do espanhol:

O Gymnasia não consegue confirmar se a ação foi concluída. Para evitar duplicá-la, não a repetiu. Confira seus dados antes de solicitá-la novamente.

Houve uma única requisição ao modelo, nenhuma rodada adicional e nenhuma repetição automática. O registro de 2020-01-03 não existia após recarregar. Removemos a injeção e uma gravação posterior de 2020-01-04, com 77,4 kg, foi salva e pôde ser lida após recarregar. Isso verifica a recuperação do armazenamento nesse cenário; não prova que toda gravação com falha deixe os dados intactos.

A mensagem conservadora continua necessária quando o efeito é incerto. Se uma ação precisa permitir novas tentativas seguras, exige uma estratégia adicional, como uma identidade estável e um registro durável do resultado. Alterar a mensagem de erro não oferece essa garantia.

Testes que protegem esse contrato

Testes determinísticos verificam o contrato sem depender de como um modelo responde naquele dia. A QA real acrescenta evidência de comportamento, mas não substitui esses limites.

• Contrato: argumentos inválidos retornam um erro marcado sem executar o handler; um texto de usuário parecido com erro continua sendo um resultado válido.
• Integração com provedores falsos: OpenAI, Anthropic e Google recebem o formato correto; uma chamada corrigida persiste uma única medição.
• Regressão de gravações: uma exceção com network timeout não aciona novas tentativas de transporte nem confirma sucesso.
• Persistência: a reprodução preserva o estado do resultado; recarregar distingue o registro confirmado daquele que não foi salvo.

A entrega passou em 933 testes Vitest, 11 do armazenamento de desenvolvimento e 3 de limites móveis, além da verificação de tipos e dos E2E com provedores falsos. O teste exploratório descrito aqui foi feito na web com um único modelo. Não é uma prova em dispositivo nativo nem uma avaliação estatística dos três provedores.

Construir um agente, passo a passo

Este artigo faz parte da série sobre construir um agente e seu harness a partir de um app de academia. Os capítulos anteriores explicam como declarar tools, validar chamadas e fechar o ciclo; este acrescenta uma decisão que deve ficar no programa: quando uma falha permite continuar e quando exige parar.

Veja o índice da série e a implementação do Gymnasia usada como exemplo prático.