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 modelo pide una operación.
Por ejemplo, consultar el peso de una fecha.
- El harness valida la petición.
Comprueba que la función exista y que sus argumentos estén permitidos.
- El harness ejecuta la función.
Obtiene el dato o detecta por qué la operación falló.
- 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és | Nombre 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 resultado | Cómo se envía el fallo | Enlace con la llamada |
|---|---|---|
OpenAI Responsesfunction_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 Messagestool_result | El bloque lleva is_error: true y el contenido del error en content. | tool_use_id |
Google Interactionsfunction_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 modelLa 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.