Tratamento de erros de ferramentas e resultados parciais em um loop de agente

O que é

Três desfechos exigem três resultados diferentes. Um erro de protocolo (ferramenta desconhecida, argumentos inválidos, servidor inacessível) é uma falha da própria chamada; o Model Context Protocol os reporta como erros JSON-RPC. Um erro de execução da ferramenta (a API upstream retornou 500, o arquivo não existe, a consulta excedeu o tempo limite) é um resultado válido que informa que a operação falhou; o MCP o devolve no resultado com isError: true, e a documentação de tool use do fornecedor descreve o flag equivalente is_error: true em um bloco tool_result, após o qual o modelo incorpora o erro ao seu próximo passo. Um resultado parcial (7 de 10 arquivos processados, a primeira página de uma busca, um lote com duas linhas rejeitadas) é um sucesso cujo conteúdo precisa dizer o que está faltando.

Por que importa

Um agente age com base no que o resultado da ferramenta diz. Uma exceção que nunca chega ao modelo gera uma resposta confiante construída sobre nada. Um erro sem detalhes gera novas tentativas cegas da mesma chamada. Um resultado parcial reportado como completo gera uma tarefa marcada como concluída com linhas perdidas em silêncio.

Como aplicar

• Nunca deixe uma exceção escapar da ferramenta; capture-a e devolva um resultado de erro com um tipo de erro estável, a mensagem e, quando for conhecido, se uma nova tentativa pode ajudar (não para um 404, sim para um timeout).
• Para resultados parciais, devolva a parte bem-sucedida junto com uma lista explícita do que falhou e por quê, além de um cursor ou identificador para continuar.
• Mantenha o texto do erro curto e factual; sem stack traces nem saída do serviço upstream, que poderiam conter instruções injetadas.
• Imponha os limites de novas tentativas no loop, e não por instrução: a mesma ferramenta com os mesmos argumentos após um erro é permitida um número fixo de vezes; depois disso, o loop devolve o controle com um resumo.
• Torne as ferramentas de escrita idempotentes ou dê a elas uma chave de idempotência, para que uma nova tentativa após uma falha ambígua não duplique o efeito.
• Diferencie "sem resultados" de "erro": uma busca vazia é um resultado válido e completo.
• Registre em log todo resultado de erro com o ID da execução; o padrão dos erros é o relatório de usabilidade da ferramenta.

Armadilhas

Retornar null ou uma string vazia em caso de falha. Mapear toda falha para uma única mensagem genérica. Deixar o modelo decidir quantas vezes tentar de novo. Levantar um erro de protocolo para uma condição de negócio ("pedido não encontrado" é um resultado, não uma chamada malformada). Expor resultados parciais apenas em um log que o modelo nunca vê.