Errores de tools: cómo un agente se recupera y cuándo debe parar

Errores de tools: cómo un agente se recupera y cuándo debe parar

La tool devuelve algo, pero ¿qué ocurrió?

El usuario pregunta «¿Cuánto pesaba ayer?». El modelo no conoce el peso: necesita pedir una consulta a los registros de la app. Esa consulta puede encontrar 76 kg, comprobar que no hay peso para ese día o fallar porque el almacenamiento no se puede leer.

Son tres situaciones distintas. Un dato encontrado permite responder. Un registro ausente permite explicar qué falta y, quizá, buscar una referencia. Un fallo de almacenamiento impide saber qué había. Un mensaje genérico como «Error» no comunica esa diferencia.

Para situar el fallo, primero hay que entender el ciclo. El modelo propone una tool call, una petición con el nombre de la función y sus argumentos. Mientras espera su resultado, deja de generar la respuesta. La ejecución ocurre después, en el harness.

El ciclo de una tool en cuatro pasos
  1. El modelo pide una operación.

    Por ejemplo, consultar el peso de una fecha.

  2. El harness valida la petición.

    Comprueba que la función exista y que sus argumentos estén permitidos.

  3. El harness ejecuta la función.

    Obtiene el dato o detecta por qué la operación falló.

  4. El modelo recibe el resultado.

    Si se permite continuar, responde al usuario o propone otra tool call.

Devolver el resultado no vuelve a ejecutar la función. El modelo continúa a partir de lo que el harness acaba de hacer. Si el fallo exige detener el turno, el harness muestra un aviso y no pide otra respuesta al modelo.

Un resultado debe decir qué pasó y qué se permite hacer

Un contrato de errores es un acuerdo sobre cómo comunicar los fallos. Separa tres preguntas: ¿falló la operación?, ¿por qué?, ¿qué se puede hacer después? La marca de error responde a la primera; un código y un mensaje explican la causa; una regla de recuperación limita la continuación.

La marca la crea el programa que ejecutó la operación. No se obtiene buscando la palabra «error» dentro del contenido recuperado. El texto de una nota pertenece a los datos del usuario; el estado de la consulta describe si la app consiguió leerla.

Gymnasia utiliza tres nombres para las reglas de recuperación. No hace falta conocerlos de antemano: cada uno representa una decisión concreta del harness.

Qué ocurrióQué se permite despuésNombre en el contrato
Los argumentos no tienen la forma aceptada.El modelo puede corregirlos. La operación aún no se ha ejecutado.correct_arguments
Una consulta no encuentra el registro solicitado.El modelo puede proponer otra consulta útil dentro de la petición del usuario. Cada nueva llamada se valida.choose_alternative
El programa decide que no puede continuar con garantías.El harness detiene el turno. El modelo no recibe permiso para seguir llamando tools.stop_turn

El siguiente JSON muestra el contrato interno de un registro ausente. Fíjate en que permite otra consulta, pero el mensaje solo afirma que falta el dato de esa fecha:

{
  "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 el fallo, error permite reconocer su causa sin interpretar una frase y recovery indica el siguiente paso permitido. recoverable: true significa que se puede continuar por esa vía, no que se pueda repetir cualquier acción. kind y version identifican el formato.

Este JSON es una decisión de la aplicación. No es un campo de salida obligatorio ni un schema común a todos los proveedores. El schema de entrada, que define los argumentos aceptados por una tool, resuelve otra pregunta: si la petición es válida antes de ejecutarla.

Responder cuando falta el peso de hace un mes

Coach ayuda a consultar la evolución del peso. Una pregunta natural sería «¿Cuánto pesaba hace un mes?». Para convertir esa expresión en una fecha, el harness debe proporcionar una referencia temporal fiable. En el ejemplo siguiente damos por resuelto ese paso y suponemos que no hay un peso para el día solicitado.

Usuario: ¿Cuánto pesaba hace un mes?

Coach: No tienes un peso apuntado para ese día. El día anterior registraste 76 kg.

Es un ejemplo ilustrativo. Muestra cómo podría ayudar el agente: recibe un error de registro ausente y, si el harness permite continuar, consulta el día anterior como referencia. No necesita que el usuario escriba instrucciones sobre cómo manejar un fallo.

La respuesta debe distinguir las fechas. Los 76 kg no contestan exactamente al día pedido: pertenecen al día anterior. Si tampoco encuentra una referencia útil, lo dice. Buscar otra fecha no permite inventar un peso ni modificar registros.

La prueba real de Gymnasia comprobó una secuencia más acotada: consultar un día sin peso y después otro día indicado expresamente en la petición de prueba. Verificó la recuperación mediante una segunda lectura, pero no demuestra que Coach busque por sí solo el día más cercano ante cualquier pregunta relativa.

Enviar el mismo estado a tres APIs

El harness decide qué ocurrió antes de preparar la siguiente petición al proveedor. Después, un adapter, la pieza que traduce el resultado al formato de cada API, conserva esa decisión. También conserva el identificador de la llamada: sirve para asociar la respuesta con la operación que pidió el modelo.

La tabla se lee de izquierda a derecha: dónde se envía el resultado, cómo se comunica el fallo y qué campo lo enlaza con su petición.

API y resultadoCómo se envía el falloEnlace con la llamada
OpenAI Responses
function_call_output
El JSON del error se serializa dentro de output. No se añade un is_error en el nivel superior de ese objeto.call_id
Anthropic Messages
tool_result
El bloque lleva is_error: true y el contenido del error en content.tool_use_id
Google Interactions
function_result
El resultado lleva is_error: true y el contenido del error en result.call_id

Cambia el formato que acepta la API, no el significado del resultado. El error de la operación nace en la app; el proveedor lo entrega al modelo. La comparación de Google se refiere a Interactions.

Capturar el fallo donde se ejecuta la operación

La validación comprueba los argumentos antes de llamar al handler, la función que realiza el trabajo. Por ejemplo, rechaza una fecha con un formato incorrecto antes de consultar el almacenamiento. Una vez validada la petición, todavía pueden ocurrir errores al ejecutar esa función.

Una ausencia prevista, como un día sin peso, se devuelve por el contrato normal. Una excepción inesperada interrumpe la ejecución, por ejemplo cuando el almacenamiento deja de responder. El bloque que captura esas excepciones debe rodear la operación local; capturar solo la petición a OpenAI, Anthropic o Google dejaría ese fallo fuera.

Este pseudocódigo resume el comportamiento comprobado en Gymnasia. Una excepción inesperada al guardar detiene el turno directamente. La sección siguiente explica una opción de diseño que permite verificar el guardado antes de decidir la parada.

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

La diferencia está en el efecto de la operación. Una lectura fallida no añade datos. Un guardado interrumpido puede haber cambiado el registro antes de perder la confirmación. Por eso esta implementación no lo repite automáticamente.

Supongamos que el proveedor entregó correctamente una petición de guardar una comida, pero falló el almacenamiento de la app. Llamarlo «Error del proveedor» señalaría la parte equivocada: el problema apareció después de recibir la petición, al ejecutarla localmente.

El desarrollador puede necesitar la excepción original para investigar. El modelo necesita saber qué operación no se pudo confirmar y qué comprobaciones están permitidas. El usuario necesita una respuesta útil: la comida quedó guardada, o hace falta revisar el registro porque no se pudo comprobar. Nombres de archivos y rutas internas no ayudan a tomar esa decisión.

Comprobar una comida antes de volver a guardarla

Apuntar una comida añade sus calorías, proteínas, carbohidratos y grasas al total del día. Si se apunta dos veces lo que el usuario comió una vez, los totales cuentan dos raciones. El error puede hacerle creer que ha superado sus objetivos de macros.

Imagina que pide «Apunta mi comida: 200 g de arroz cocido y 150 g de pollo». La app intenta guardarla, pero no obtiene una confirmación. Puede haber fallado antes de añadirla o después de hacerlo. El aviso de error, por sí solo, no permite distinguir esos casos.

Un harness puede diseñarse para permitir una consulta de solo lectura antes de decidir que debe parar. El modelo pide comprobar qué quedó guardado, sin añadir otra comida. La consulta debe identificar esta acción concreta: encontrar arroz con pollo en el registro no basta si ya había una comida parecida.

La comprobación tiene tres desenlaces posibles:

Se guardó

Hay pruebas de que esta comida quedó registrada. Coach puede responder «He apuntado tu comida». No necesita contar al usuario el fallo técnico ya resuelto.

No se guardó

Hay pruebas suficientes de que la acción no se completó. El harness puede permitir terminar el guardado pendiente, siguiendo sus reglas y evitando duplicados.

Sigue sin saberse

La consulta falla o no da pruebas suficientes. Se para y se avisa: «No puedo confirmar si se guardó la comida. Comprueba tu registro antes de volver a añadirla».

Esta recuperación es una opción de diseño, no el recorrido de la prueba de Gymnasia. En esa prueba, una excepción de guardado detuvo el turno sin pedir otra consulta al modelo. Si se incorpora la verificación, tiene que ocurrir antes de aplicar stop_turn. Una vez ordenada la parada, el modelo no puede ignorarla.

Un modelo capaz puede elegir una buena comprobación. El harness debe ofrecer los permisos y las pruebas que la hagan fiable. Pedirle simplemente «no dupliques comidas» no le permite saber si el guardado anterior ocurrió.

Probar las decisiones, además de la respuesta

Las pruebas base son deterministas: sustituyen el modelo por respuestas conocidas y comprueban lo que el harness permite ejecutar. Así un cambio de redacción del modelo no oculta un error del programa.

  • Antes de ejecutar: argumentos inválidos producen un error corregible y el handler no se llama.
  • Al devolver el resultado: una consulta correcta sigue siendo correcta aunque el texto encontrado mencione un error.
  • En cada adapter: los tres proveedores reciben el formato esperado y el resultado queda asociado a la llamada correcta.
  • Al guardar: una excepción local no confirma éxito ni dispara un segundo guardado automático.
  • Al conservar resultados: guardar y recuperar un resultado mantiene su estado de éxito o error, sin deducirlo otra vez a partir del texto.

Si se implementa la consulta de verificación, necesita sus propias pruebas: comida realmente guardada, ausencia demostrada y resultado ambiguo. También hay que incluir dos comidas parecidas para comprobar que no se confundan.

La prueba con un modelo real añade otra comprobación: que el agente use el resultado para continuar la conversación. En Gymnasia se observaron una consulta ausente seguida de otra lectura, y una parada ante un fallo de guardado simulado. Después se recargó la app para comprobar los datos, en lugar de fiarse solo de la respuesta visible.

Esto no demuestra que una marca de error mejore siempre al modelo. En una comparación, el modelo también entendió la ausencia con el texto antiguo. El valor probado del contrato es que el programa reconoce el estado y aplica una regla explícita sin depender de esa interpretación.

Alcance de la prueba y evidencia

La QA se realizó en la web de Gymnasia con OpenAI y datos ficticios. La petición de lectura indicaba expresamente la fecha alternativa. El fallo de guardado se provocó en un peso, no en una comida: no hubo otra petición al modelo ni reintento automático, y el registro no existía tras recargar. Al retirar el fallo, un guardado posterior persistió correctamente. Los tests con proveedores falsos cubren los tres formatos; esta sesión real no equivale a una prueba nativa ni a una evaluación de todos los modelos. El informe de verificación conserva los detalles y cómo reproducirla.

Construir un agente, paso a paso

Este artículo pertenece a una serie sobre cómo construir un agente y su harness usando una app de gimnasio como ejemplo. Después de declarar y validar las tools, hay que decidir cómo continuar cuando algo falla: entregar un resultado que explique qué ocurrió, permitir solo la recuperación adecuada y confirmar los efectos antes de repetirlos.

El patrón sirve también para registrar un pedido o crear una reserva. Cambia el dominio, pero sigue siendo el programa quien conoce el resultado de la ejecución y controla qué puede ocurrir después.

Consulta el índice de la serie y la implementación de Gymnasia que sirve como caso práctico.

Seguir leyendo

Últimos posts -->

¿Has visto estos proyectos?

Gymnasia

Gymnasia Gymnasia
Expo
React Native
TypeScript
OpenAI
Anthropic

App de fitness con dos agentes que se ejecutan íntegramente en el dispositivo, sin backend, de forma que los datos del usuario nunca salen del móvil. Un coach conversacional BYOK con tools locales y system prompt remoto con fallback offline, y un estimador de comidas que saca los macronutrientes de una foto del plato, con lectura de códigos de barras contra OpenFoodFacts.

LangGraph Deep Researcher

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

Sistema multiagente de investigación construido con LangGraph. Un supervisor descompone tu pregunta en temas y lanza subagentes de búsqueda en paralelo; cada uno comprime sus hallazgos antes de pasarlos a un agente redactor que escribe el informe final en markdown con sus fuentes. Streaming en vivo por WebSockets, modelo configurable por rol y claves de API propias que nunca se guardan en el servidor.

Tau

Tau Tau
Python
LangChain

Sistema multiagente de tutoría para estudiantes de secundaria, con un agente por asignatura y material de curso elaborado y validado por un equipo de profesores. Llegó a usarse con alumnos reales en un colegio privado en España y en un instituto en Colombia.

Ver todos los proyectos -->
>_ Disponible para proyectos

¿Tienes un proyecto con IA?

Hablemos.

maximofn@gmail.com

Especialista en Machine Learning e Inteligencia Artificial. Desarrollo soluciones con IA generativa, agentes inteligentes y modelos personalizados.

¿Quieres ver alguna charla?

Últimas charlas -->

¿Quieres mejorar con estos tips?

Últimos tips -->

Usa esto en local

Los espacios de Hugging Face nos permite ejecutar modelos con demos muy sencillas, pero ¿qué pasa si la demo se rompe? O si el usuario la elimina? Por ello he creado contenedores docker con algunos espacios interesantes, para poder usarlos de manera local, pase lo que pase. De hecho, es posible que si pinchas en alún botón de ver proyecto te lleve a un espacio que no funciona.

Flow edit

Flow edit Flow edit

Edita imágenes con este modelo de Flow. Basándose en SD3 o FLUX puedes editar cualquier imagen y generar nuevas

FLUX.1-RealismLora

FLUX.1-RealismLora FLUX.1-RealismLora
Ver todos los contenedores -->
>_ Disponible para proyectos

¿Tienes un proyecto con IA?

Hablemos.

maximofn@gmail.com

Especialista en Machine Learning e Inteligencia Artificial. Desarrollo soluciones con IA generativa, agentes inteligentes y modelos personalizados.

¿Quieres entrenar tu modelo con estos datasets?

short-jokes-dataset

HuggingFace

Dataset de chistes en inglés

Uso: Fine-tuning de modelos de generación de texto humorístico

231K filas 2 columnas 45 MB
Ver en HuggingFace →

opus100

HuggingFace

Dataset con traducciones de inglés a español

Uso: Entrenamiento de modelos de traducción inglés-español

1M filas 2 columnas 210 MB
Ver en HuggingFace →

netflix_titles

HuggingFace

Dataset con películas y series de Netflix

Uso: Análisis de catálogo de Netflix y sistemas de recomendación

8.8K filas 12 columnas 3.5 MB
Ver en HuggingFace →
Ver más datasets -->