Integración de servicios automatizada a través de IA

Contexto e integración en la plataforma

Esta iniciativa se desarrolló como solución de tooling interno dentro de la Plataforma de APIs de Freepik/Magnific. Al acelerar la integración de modelos multimodales (generación de imagen, vídeo, audio y upscalers), el equipo identificó la necesidad de un mecanismo automatizado para incorporar nuevos servicios sin incurrir en tareas manuales repetitivas ni desajustes entre repositorios.

El problema

Dar de alta un servicio nuevo en una plataforma pública de APIs no es un solo cambio: implica al menos seis artefactos coordinados a través de múltiples capas:

1. La especificación OpenAPI formal con sus parámetros y tipados.
2. La implementación del controlador y lógica de negocio en el servidor FastAPI.
3. La configuración de rutas, permisos perimetrales y tarificación en APISIX Gateway.
4. La generación de modelos Pydantic validados en tiempo de ejecución.
5. La documentación técnica de referencia para desarrolladores y clientes B2B en Mintlify.
6. La entrada interactiva con controles visuales en el Playground web de Next.js.

Hacerlo manualmente para cada familia de modelos funciona, pero es lento y propenso a inconsistencias (parámetros que divergen entre la spec y el servidor, o reglas de costes que no se reflejan en el gateway).

La solución: Orquestación multi-agente

Se diseñó e implementó un sistema de agentes de IA especializados, donde cada agente opera como un experto sobre un dominio técnico concreto, gobernados por un orquestador central:

                  +-----------------------------------+
                  |     Definición del Servicio       |
                  |     (Fuente única de verdad)      |
                  +-----------------------------------+
                                    |
                  +-----------------+-----------------+
                  |                                   |
                  v                                   v
+-----------------------------------+   +---------------------------------+
|  Agentes de Backend & Gateway     |   |  Agentes de Frontend & Docs     |
|  - Spec Agent (OpenAPI)           |   |  - Docs Agent (Mintlify)        |
|  - Backend Agent (FastAPI / Tests)|   |  - Frontend Agent (Playground)  |
|  - Gateway Agent (APISIX / Costs) |   |                                 |
+-----------------------------------+   +---------------------------------+
                                    |
                                    v
                  +-----------------------------------+
                  |    Revisión Humana (HITL)         |
                  |    Pull Request coordinada        |
                  +-----------------------------------+

Esquema Human-in-the-Loop (HITL)

El sistema es deliberadamente Human-in-the-Loop (HITL):

• Cada artefacto generado pasa por validaciones automatizadas de tipos y linters antes de ser presentado como una propuesta de cambio unificada.
• El equipo de ingeniería revisa, valida y aprueba los cambios en un entorno seguro antes de fusionar a producción, garantizando que aspectos críticos como precios, permisos y reglas de enrutamiento conserven una supervisión rigurosa.

Artefactos generados por servicio

A partir de una definición formal del servicio, el orquestador coordina la generación de:

1. Especificación OpenAPI: Esquemas de petición/respuesta, parámetros y modelos de error estandarizados.
2. Controlador FastAPI: Endpoints asíncronos tipados y mapeos al proveedor de inferencia upstream.
3. Reglas de Gateway APISIX: Rutas, políticas de rate limiting y reglas de coste en mUSD por invocación.
4. Modelos Pydantic: Esquemas de validación de datos en tiempo de ejecución sincronizados con la spec.
5. Documentación Pública (Mintlify): Guías de referencia técnica, tablas de parámetros y snippets en cURL/SDKs.
6. Consola en el Playground (Next.js): Formulario reactivo con controles adaptados y visores multimedia (imagen, vídeo, audio).

Impacto

• Velocidad de onboarding: Reducción del tiempo de alta de un nuevo modelo de días a minutos.
• Cero deriva de especificación: Consistencia garantizada en todas las capas gracias a una única fuente de verdad.
• Estandarización del ecosistema: Adopción sistemática de directrices de arquitectura y nombrado en toda la suite de la Plataforma de APIs.