Cómo normalizar respuestas de herramientas antes de que un agente las use para seguir razonando

Un agente se vuelve frágil cuando cada herramienta habla un dialecto distinto y el razonamiento debe aprenderlos todos. Una API devuelve data.items, otra entrega results, una tercera usa records; unas representan ausencia con null, otras con lista vacía y otras con error. Si el modelo recibe directamente esas diferencias, cada llamada añade complejidad al contexto y aumenta la posibilidad de interpretar mal una respuesta válida. Una capa de normalización coloca una frontera entre integración y razonamiento: los adaptadores entienden cada proveedor y entregan al agente una estructura estable que conserva significado sin obligarlo a memorizar peculiaridades.

Empieza definiendo un envelope común que describa resultado, datos, error y metadata. Por ejemplo, toda tool puede devolver status, data, error, source, requestId y observedAt, aunque internamente el proveedor utilice nombres diferentes. No intentes convertir todas las respuestas en el mismo objeto de negocio; normaliza primero la forma de comunicación. El agente necesita saber si la acción terminó, qué dato principal recibió, si existe una condición recuperable y qué evidencia permite rastrear la llamada. Esa consistencia reduce instrucciones repetidas y permite que políticas comunes funcionen sobre múltiples herramientas.

Normaliza tipos y estados antes de que entren al contexto. Fechas deberían llegar en un formato acordado, cantidades con unidad explícita, booleanos como booleanos y colecciones con una convención clara. También conviene mapear estados equivalentes: completed, done y success pueden convertirse en una categoría interna si realmente significan lo mismo. La regla importante es no borrar distinciones relevantes. Si dos proveedores usan palabras similares pero uno confirma ejecución y otro solo aceptación, deben permanecer separados. Normalizar no significa simplificar hasta perder semántica; significa hacer explícita una semántica interna que el flujo pueda confiar.

Crea una taxonomía pequeña de errores que oriente decisiones posteriores. En vez de exponer cientos de códigos directamente al agente, el adaptador puede mapearlos a categorías como invalidinput, unauthorized, ratelimited, notfound, conflict, temporaryfailure o providerfailure, conservando el código original en metadata. Esa capa permite definir una política común: qué se reintenta, qué se corrige, qué escala y qué cancela. Cuando aparece un error nuevo, el cambio se concentra en el adaptador y no en cada prompt o workflow que utiliza la herramienta.

Conserva siempre el payload original o una referencia auditable fuera del contexto del agente. La normalización puede tener bugs y a veces será necesario reconstruir qué respondió realmente el proveedor. Guarda la respuesta cruda en logs protegidos o almacenamiento apropiado, vinculada por requestId, pero entrega al agente únicamente la versión necesaria. Esto evita inundar contexto con campos irrelevantes y mantiene capacidad forense. También permite comparar normalizador y fuente cuando cambia una API. La interfaz estable sirve para operar; la evidencia original sirve para investigar.

Prueba los normalizadores con fixtures reales y casos límite de cada proveedor. Incluye éxito con datos, éxito vacío, error conocido, timeout, paginación y respuestas inesperadas. Luego ejecuta tests comunes sobre la salida normalizada: los mismos invariantes deberían cumplirse sin importar qué tool originó el dato. Si un proveedor cambia su schema, el test del adaptador falla antes de que la lógica de negocio reciba una forma distinta. La capa se convierte así en un amortiguador: absorbe variación externa y protege la parte del sistema donde se toman decisiones.

Una interfaz normalizada reduce la cantidad de integración que el agente debe pensar en cada ejecución. El modelo puede concentrarse en intención, reglas y siguiente acción mientras adaptadores deterministas resuelven detalles de transporte y formato. Esa separación también facilita sustituir proveedores, comparar herramientas y aplicar observabilidad común. La meta no es esconder todo detrás de una abstracción perfecta, sino decidir qué diferencias pertenecen a infraestructura y cuáles necesitan llegar al razonamiento. Cuando esa frontera está bien diseñada, cambiar una API deja de significar reeducar a todo el agente.