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 modelo pede uma operação.
Por exemplo, consultar o peso de uma data.
- O harness valida o pedido.
Verifica se a função existe e se os argumentos são permitidos.
- O harness executa a função.
Obtém o dado ou detecta por que a operação falhou.
- 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 aconteceu | O que é permitido depois | Nome 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 resultado | Como a falha é enviada | Ligação com a chamada |
|---|---|---|
OpenAI Responsesfunction_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 Messagestool_result | O bloco contém is_error: true e o conteúdo do erro em content. | tool_use_id |
Google Interactionsfunction_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 modelA 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.