Por qué las Skills de datos públicos necesitan una envoltura de respuesta unificada

En resumen: este es el artículo del contrato de respuesta: las plataformas públicas difieren, pero los agentes necesitan una sola envoltura para paginación, facturación, errores y registros.

Cada fuente de datos públicos devuelve una forma de respuesta distinta. TikTok envuelve los resultados de una manera, Reddit de otra, YouTube de otra, LinkedIn de otra. Si tu agente habla directamente con todas ellas, hereda toda esa variación — la lógica de paginación se ramifica, las políticas de reintento se ramifican, el análisis de errores se ramifica. Lo resolvemos empujando cada operación a través de una sola envoltura. Este es el esquema y por qué importa.

El problema

La variación de origen es el impuesto silencioso de los agentes multiplataforma. El bucle de uso de herramientas del agente tiene que manejar muchas formas, y esa complejidad aparece en tres lugares caros de mantener: el prompt (hay que enseñarle al modelo cada forma), la política de reintentos (las distintas fuentes paginan de forma diferente tras un fallo) y la envoltura de error (la respuesta de no autorizado de una plataforma no se parece en nada a la de otra).

Vimos a nuestros propios agentes de demostración gastar la mayoría de sus tokens en hacer malabares con las formas en lugar de razonar, y decidimos que la corrección correcta estaba en el gateway, no en el agente.

La envoltura de UnifAPI

Cada endpoint HTTP que exponemos, en cada plataforma, devuelve la misma forma externa: { request_id, data, pagination?, billing }. Los campos dentro de data son específicos de la plataforma —un vídeo de TikTok tiene hashtags, una publicación de Reddit tiene subreddit— pero todo lo que lo rodea es consistente.

Los errores se reducen a un vocabulario cerrado. Cada uno lleva un mensaje legible por humanos y un tipo legible por máquina. El modelo puede ramificar según el tipo sin tener que reconocer texto específico de la plataforma.

Patrones de reestructuración que usamos

Estandarizar las plataformas públicas detrás de una sola envoltura significa que nuestra capa de reestructuración son unos pocos cientos de líneas por plataforma. Dominan tres patrones.

Unificación de cursores — el token de paginación de cada plataforma (max_cursor, after, nextPageToken, end_cursor, page) se convierte en pagination.cursor. Calculamos has_more a partir de cualquier señal que proporcione la fuente (length === limit, una bandera explícita has_more, un cursor siguiente nulo).

Aplanamiento de campos — cuando una fuente anida los datos tres niveles de profundidad (data.data.children.data, te miramos a ti, Reddit), lo elevamos al data[] de nivel superior. El modelo nunca ve las envolturas intermedias; ve los registros.

Análisis defensivo — las plataformas públicas cambian los tipos de los campos sin avisar (un recuento se vuelve una cadena, un array se vuelve un único elemento, una marca de tiempo se vuelve null). La capa de reestructuración convierte cada campo a su tipo declarado y descarta el registro solo si faltan los campos obligatorios. Esa disciplina detecta la mayoría de los fallos silenciosos que veíamos en el paso directo bruto.

Qué se rompe si te saltas esto

Sin una envoltura, dos cosas salen mal a escala. Primero, el prompt de tu agente crece linealmente con el número de plataformas — cada nueva plataforma añade un párrafo explicando su forma de respuesta. Para la plataforma 10, el prompt es la parte más lenta de la llamada.

Segundo, tu código de reintentos y paginación crece de forma multiplicativa. Cada peculiaridad específica de origen interactúa con cada otra peculiaridad, y la matriz de "¿funciona el reintento tras cursor en la plataforma X bajo la condición Y?" estalla. Los equipos que no normalizan pronto acaban escribiendo una capa de normalización tarde, después de los errores.

Qué viene a continuación

La envoltura actual cubre limpiamente los endpoints de tipo lista. La siguiente iteración en la que trabajamos cubre las fuentes con forma de streaming y webhook — lugares donde la respuesta no es un único { data: [...] } sino una serie de eventos a lo largo del tiempo. La estamos modelando para que se sienta como un iterador asíncrono desde el lado del agente, de modo que el cambio en el prompt sea mínimo.

Si estás construyendo hoy un agente multiplataforma y quieres ver cómo funciona la envoltura en la práctica, empieza por una Skill en unifapi.com/skills o inspecciona la especificación de OpenAPI en unifapi.com/openapi.json — cada endpoint, cada campo, una sola forma.

Qué leer a continuación

Diseño de herramientas del catálogo MCP - muestra cómo los agentes descubren las operaciones que devuelven esta envoltura.

UnifAPI vs RapidAPI - usa la normalización como punto de comparación.

Especificación de OpenAPI - expone el esquema en vivo detrás de la prosa.