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

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

A tool retornou algo, mas o que aconteceu?

O usuário pergunta “Quanto eu pesava ontem?”. O modelo não sabe o peso: precisa pedir uma consulta aos registros do app. Essa consulta pode encontrar 76 kg, verificar que não há peso registrado naquele dia ou falhar porque não é possível ler o armazenamento.

São três situações diferentes. Um dado encontrado permite responder. Um registro ausente permite explicar o que falta e, talvez, buscar uma referência. Uma falha de armazenamento impede saber o que havia. Uma mensagem genérica como “Erro” não comunica essa diferença.

Para entender onde a falha ocorre, comece pelo ciclo. O modelo propõe uma tool call, um pedido com o nome da função e seus argumentos. Enquanto espera o resultado, ele deixa de gerar a resposta. A execução acontece depois, no harness.

O ciclo de uma tool em quatro etapas
  1. O modelo pede uma operação.

    Por exemplo, consultar o peso de uma data.

  2. O harness valida o pedido.

    Verifica se a função existe e se os argumentos são permitidos.

  3. O harness executa a função.

    Obtém o dado ou detecta por que a operação falhou.

  4. O modelo recebe o resultado.

    Se a continuação for permitida, responde ao usuário ou propõe outra tool call.

Devolver o resultado não executa a função novamente. O modelo continua a partir do que o harness acabou de fazer. Se a falha exige interromper o turno, o harness mostra um aviso e não pede outra resposta ao modelo.

Um resultado deve dizer o que aconteceu e o que é permitido

Um contrato de erros é um acordo sobre como comunicar as falhas. Ele separa três perguntas: a operação falhou, por quê e o que pode acontecer depois? A marca de erro responde à primeira; um código e uma mensagem explicam a causa; uma regra de recuperação limita a continuação.

A marca é criada pelo programa que executou a operação. Ela não é deduzida procurando a palavra “erro” no conteúdo recuperado. O texto de uma nota pertence aos dados do usuário; o estado da consulta descreve se o app conseguiu lê-la.

O Gymnasia usa três nomes para suas regras de recuperação. Você não precisa conhecê-los antes: cada um representa uma decisão concreta do harness.

O que aconteceuO que é permitido depoisNome no contrato
Os argumentos não têm o formato aceito.O modelo pode corrigi-los. A operação ainda não foi executada.correct_arguments
Uma consulta não encontra o registro solicitado.O modelo pode propor outra consulta útil dentro do pedido do usuário. Cada nova chamada é validada.choose_alternative
O programa decide que não pode continuar com segurança.O harness interrompe o turno. O modelo não recebe permissão para continuar chamando tools.stop_turn

O JSON a seguir mostra o contrato interno de um registro ausente. Observe que ele permite outra consulta, mas a mensagem só afirma que falta o dado daquela data. A mensagem permanece em espanhol, como no exemplo prático:

{
  "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
}

is_error identifica a falha, error permite reconhecer sua causa sem interpretar uma frase e recovery indica o próximo passo permitido. recoverable: true significa que é possível continuar por aquela via, não que qualquer ação possa ser repetida. kind e version identificam o formato.

Esse JSON é uma decisão do aplicativo. Não é um campo de saída obrigatório nem um schema de saída comum a todos os provedores. O schema de entrada, que define os argumentos aceitos por uma tool, responde a outra pergunta: se o pedido é válido antes da execução.

Responder quando falta o peso de um mês atrás

O Coach ajuda a consultar a evolução do peso. Uma pergunta natural seria “Quanto eu pesava há um mês?”. Para transformar essa expressão em uma data, o harness precisa fornecer uma referência temporal confiável. No exemplo a seguir, consideramos essa etapa resolvida e supomos que não há peso para o dia solicitado.

Usuário: Quanto eu pesava há um mês?

Coach: Você não tem um peso registrado naquele dia. No dia anterior, registrou 76 kg.

É um exemplo ilustrativo. Ele mostra como o agente poderia ajudar: recebe um erro de registro ausente e, se o harness permite continuar, consulta o dia anterior como referência. O usuário não precisa escrever instruções sobre como lidar com uma falha.

A resposta precisa distinguir as datas. Os 76 kg não respondem exatamente ao dia pedido: pertencem ao dia anterior. Se também não encontra uma referência útil, o agente avisa. Consultar outra data não permite inventar um peso nem modificar registros.

O teste real do Gymnasia verificou uma sequência mais limitada: consultar um dia sem peso e depois outro dia indicado expressamente no pedido de teste. Ele confirmou a recuperação por uma segunda leitura, mas não demonstra que o Coach busque sozinho o dia mais próximo para qualquer pergunta relativa.

Enviar o mesmo estado a três APIs

O harness decide o que aconteceu antes de preparar o próximo pedido ao provedor. Depois, um adapter, a parte que traduz o resultado para o formato de cada API, preserva essa decisão. Ele também conserva o identificador da chamada, que associa a resposta à operação solicitada pelo modelo.

Leia a tabela da esquerda para a direita: onde o resultado é enviado, como a falha é comunicada e qual campo a conecta ao pedido.

API e resultadoComo a falha é enviadaLigação com a chamada
OpenAI Responses
function_call_output
O JSON do erro é serializado dentro de output. Não se acrescenta um is_error no nível superior desse objeto.call_id
Anthropic Messages
tool_result
O bloco contém is_error: true e o conteúdo do erro em content.tool_use_id
Google Interactions
function_result
O resultado contém is_error: true e o conteúdo do erro em result.call_id

O formato aceito pela API muda, mas o significado do resultado permanece. O erro da operação nasce no app; o provedor o entrega ao modelo. A comparação com o Google se refere a Interactions.

Capturar a falha onde a operação é executada

A validação verifica os argumentos antes de chamar o handler, a função que realiza o trabalho. Por exemplo, rejeita uma data com formato incorreto antes de consultar o armazenamento. Mesmo depois de validar o pedido, ainda podem ocorrer erros durante a execução dessa função.

Uma ausência prevista, como um dia sem peso, é devolvida pelo contrato normal. Uma exceção inesperada interrompe a execução, por exemplo quando o armazenamento deixa de responder. O bloco que captura essas exceções precisa envolver a operação local; capturar apenas o pedido a OpenAI, Anthropic ou Google deixaria essa falha de fora.

Este pseudocódigo resume o comportamento verificado no Gymnasia. Uma exceção inesperada ao salvar interrompe o turno diretamente. A próxima seção explica uma opção de projeto que permite verificar o salvamento antes de decidir parar.

check the tool name and the accepted argument shape
if the request is invalid:
    return a marked error that allows argument correction

try to execute the operation
if it returns an expected error:
    apply its recovery rule
if an unexpected exception interrupts a read:
    return a safe, marked error
if an unexpected exception interrupts a save:
    stop the turn locally
    do not repeat the save or request another model response

if continuation is allowed:
    send the result and its status to the model

A diferença está no efeito da operação. Uma leitura que falha não adiciona dados. Um salvamento interrompido pode ter alterado o registro antes de perder a confirmação. Por isso essa implementação não o repete automaticamente.

Suponha que o provedor entregou corretamente um pedido para registrar uma refeição, mas o armazenamento do app falhou. Chamar isso de “Erro do provedor” apontaria para a parte errada: o problema surgiu depois de receber o pedido, durante a execução local.

O desenvolvedor pode precisar da exceção original para investigar. O modelo precisa saber qual operação não pôde ser confirmada e quais verificações são permitidas. O usuário precisa de uma resposta útil: a refeição foi salva, ou é necessário revisar o registro porque não foi possível verificar. Nomes de arquivos e caminhos internos não ajudam nessa decisão.

Verificar uma refeição antes de salvá-la novamente

Registrar uma refeição adiciona suas calorias, proteínas, carboidratos e gorduras ao total do dia. Se uma refeição consumida uma vez é registrada duas vezes, o total conta duas porções. O erro pode fazer parecer que o usuário ultrapassou suas metas de macros.

Imagine que ele pede “Registre meu almoço: 200 g de arroz cozido e 150 g de frango”. O app tenta salvar, mas não recebe uma confirmação. Pode ter falhado antes de adicionar a refeição ou depois disso. O aviso de erro, sozinho, não permite distinguir esses casos.

Um harness pode ser projetado para permitir uma consulta somente de leitura antes de decidir que precisa parar. O modelo pede para verificar o que foi salvo, sem adicionar outra refeição. A consulta precisa identificar essa ação específica: encontrar arroz com frango no registro não basta se já havia uma refeição parecida.

A verificação tem três resultados possíveis:

Foi salva

Há evidências de que essa refeição foi registrada. O Coach pode dizer “Registrei sua refeição”. Não precisa contar ao usuário a falha técnica que já foi resolvida.

Não foi salva

Há evidências suficientes de que a ação não foi concluída. O harness pode permitir terminar o salvamento pendente, seguindo suas regras e evitando duplicações.

Ainda não se sabe

A consulta falha ou não fornece evidências suficientes. O turno é interrompido com um aviso: “Não consigo confirmar se a refeição foi salva. Confira seu registro antes de adicioná-la novamente”.

Essa recuperação é uma opção de projeto, não o caminho seguido no teste do Gymnasia. Naquele teste, uma exceção ao salvar interrompeu o turno sem pedir outra consulta ao modelo. Se a verificação for incorporada, precisa acontecer antes de aplicar stop_turn. Depois que a parada é determinada, o modelo não pode ignorá-la.

Um modelo capaz pode escolher uma boa verificação. O harness precisa oferecer as permissões e as evidências que a tornem confiável. Pedir apenas “não duplique refeições” não permite saber se o salvamento anterior aconteceu.

Testar as decisões, além da resposta

Os testes de base são deterministas: substituem o modelo por respostas conhecidas e verificam o que o harness permite executar. Assim, uma mudança na redação do modelo não esconde um erro do programa.

  • Antes da execução: argumentos inválidos produzem um erro corrigível e o handler não é chamado.
  • Ao devolver o resultado: uma consulta bem-sucedida continua correta mesmo que o texto encontrado mencione um erro.
  • Em cada adapter: os três provedores recebem o formato esperado e o resultado fica associado à chamada correta.
  • Ao salvar: uma exceção local não confirma sucesso nem dispara um segundo salvamento automático.
  • Ao conservar resultados: salvar e recuperar um resultado mantém seu estado de sucesso ou erro, sem deduzi-lo novamente pelo texto.

Se a consulta de verificação for implementada, precisará de testes próprios: refeição realmente salva, ausência comprovada e resultado ambíguo. Também é preciso incluir duas refeições parecidas para verificar que não sejam confundidas.

O teste com um modelo real acrescenta outra verificação: se o agente usa o resultado para continuar a conversa. No Gymnasia, foram observadas uma consulta sem registro seguida de outra leitura e uma parada diante de uma falha de salvamento simulada. Depois, o app foi recarregado para verificar os dados, em vez de confiar apenas na resposta visível.

Isso não prova que uma marca de erro sempre melhore o modelo. Em uma comparação, o modelo também entendeu a ausência com o texto antigo. O valor demonstrado do contrato é que o programa reconhece o estado e aplica uma regra explícita sem depender daquela interpretação.

Alcance do teste e evidências

A QA foi realizada na versão web do Gymnasia com OpenAI e dados fictícios. O pedido de leitura indicava expressamente a data alternativa. A falha de salvamento foi provocada em um peso, não em uma refeição: não houve outro pedido ao modelo nem repetição automática, e o registro não existia após recarregar. Depois de retirar a falha, um salvamento posterior persistiu corretamente. Os testes com provedores falsos cobrem os três formatos; essa sessão real não equivale a um teste nativo nem a uma avaliação de todos os modelos. O relatório de verificação conserva os detalhes e as instruções para reproduzi-la.

Construir um agente, passo a passo

Este artigo pertence a uma série sobre como construir um agente e seu harness usando um app de academia como exemplo. Depois de declarar e validar as tools, é preciso decidir como continuar quando algo falha: entregar um resultado que explique o que aconteceu, permitir somente a recuperação adequada e confirmar os efeitos antes de repeti-los.

O padrão também serve para registrar um pedido ou criar uma reserva. O domínio muda, mas continua sendo o programa que conhece o resultado da execução e controla o que pode acontecer depois.

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

Continuar lendo

Últimos posts -->

Você viu esses projetos?

Gymnasia

Gymnasia Gymnasia
Expo
React Native
TypeScript
OpenAI
Anthropic

App de fitness com dois agentes que são executados integralmente no dispositivo, sem backend, de forma que os dados do usuário nunca saem do celular. Um coach conversacional BYOK com tools locais e system prompt remoto com fallback offline, e um estimador de refeições que tira os macronutrientes de uma foto do prato, com leitura de códigos de barras contra o OpenFoodFacts.

LangGraph Deep Researcher

LangGraph Deep Researcher LangGraph Deep Researcher
Python
LangGraph
FastAPI
React
TypeScript
Docker

Sistema multiagente de pesquisa construído com LangGraph. Um supervisor decompõe sua pergunta em tópicos e lança subagentes de busca em paralelo; cada um comprime seus achados antes de repassá-los a um agente redator que escreve o relatório final em markdown com suas fontes. Streaming ao vivo por WebSockets, modelo configurável por papel e chaves de API próprias que nunca são armazenadas no servidor.

Tau

Tau Tau
Python
LangChain

Sistema multiagente de tutoria para estudantes do ensino médio, com um agente por disciplina e material de curso elaborado e validado por uma equipe de professores. Chegou a ser usado com alunos reais em um colégio privado na Espanha e em uma escola de ensino médio na Colômbia.

Ver todos os projetos -->
>_ Disponível para projetos

Tem um projeto com IA?

Vamos conversar.

maximofn@gmail.com

Especialista em Machine Learning e Inteligência Artificial. Desenvolvo soluções com IA generativa, agentes inteligentes e modelos personalizados.

Quer assistir alguma palestra?

Últimas palestras -->

Quer melhorar com essas dicas?

Últimos tips -->

Use isso localmente

Os espaços do Hugging Face nos permitem executar modelos com demos muito simples, mas e se a demo quebrar? Ou se o usuário a deletar? Por isso, criei contêineres docker com alguns espaços interessantes, para poder usá-los localmente, aconteça o que acontecer. Na verdade, se você clicar em qualquer botão de visualização de projeto, ele pode levá-lo a um espaço que não funciona.

Flow edit

Flow edit Flow edit

Edite imagens com este modelo de Flow. Baseado em SD3 ou FLUX, você pode editar qualquer imagem e gerar novas

FLUX.1-RealismLora

FLUX.1-RealismLora FLUX.1-RealismLora
Ver todos os contêineres -->
>_ Disponível para projetos

Tem um projeto com IA?

Vamos conversar.

maximofn@gmail.com

Especialista em Machine Learning e Inteligência Artificial. Desenvolvo soluções com IA generativa, agentes inteligentes e modelos personalizados.

Você quer treinar seu modelo com esses datasets?

short-jokes-dataset

HuggingFace

Dataset com piadas em inglês

Uso: Fine-tuning de modelos de geração de texto humorístico

231K linhas 2 colunas 45 MB
Ver no HuggingFace →

opus100

HuggingFace

Dataset com traduções de inglês para espanhol

Uso: Treinamento de modelos de tradução inglês-espanhol

1M linhas 2 colunas 210 MB
Ver no HuggingFace →

netflix_titles

HuggingFace

Dataset com filmes e séries da Netflix

Uso: Análise de catálogo Netflix e sistemas de recomendação

8.8K linhas 12 colunas 3.5 MB
Ver no HuggingFace →
Ver mais datasets -->