¿Qué es exactamente AgentMesh Gateway?

1. La idea en una frase

AgentMesh se coloca entre un cliente de IA y uno o varios proveedores. El cliente envía la solicitud a AgentMesh; AgentMesh determina primero qué proveedores pueden manejarla sin perder significado y después la envía mediante el adaptador de protocolo apropiado.

2. ¿Qué problema resuelve?

Los proveedores de IA locales y remotos pueden diferir en formato de API, modelos, tool calling, reasoning, precio, latencia, fiabilidad y cuotas. Si un cliente depende directamente de un solo proveedor, cambiarlo es difícil. Si un router elige únicamente “el más rápido” o “el más barato”, puede seleccionar una opción incapaz de preservar la semántica de la solicitud.

AgentMesh separa traducción de protocolos, networking específico del proveedor y política de routing. El cliente puede hablar con un único gateway mientras los detalles de cada proveedor permanecen detrás de adaptadores.

Usos típicos

• Dar a un agente de programación un endpoint estable y cambiar proveedores upstream sin tocar al cliente.
• Usar un modelo local para texto normal y reservar un proveedor Responses nativo para semántica que no puede traducirse sin pérdida.
• Hacer failover antes de que una respuesta streaming quede comprometida.
• Medir uso real de tokens y latencia sin confundir esas mediciones con hints configurados.
• Comparar políticas offline sin gastar en llamadas reales.

3. ¿Qué ocurre con una solicitud?

4. Componentes principales

Adaptadores de protocolo

Entienden los formatos de entrada/salida del cliente. El proyecto incluye superficies con forma OpenAI Chat Completions, OpenAI Responses y Anthropic Messages.

Modelo de dominio neutral

Mensajes, requests, responses y chunks normalizados mantienen la lógica central separada de FastAPI y del HTTP de cada proveedor.

Adaptadores de proveedor

Controlan el tráfico saliente. v0.3.0 incluye adaptador OpenAI-compatible genérico, Anthropic-compatible y Responses-compatible nativo.

Registro de proveedores

Convierte la configuración en instancias concretas de adaptadores.

Router

Calcula el conjunto viable y solo después aplica la política de ranking.

Estado de runtime

Conserva fallos, latencia EWMA, ventana reciente, p50/p95, tokens/coste observado, estado de circuito y uso de cuota local.

Servicio gateway

Coordina intentos y failover, incluyendo la regla de no cambiar de proveedor después de comprometer un stream.

Capa de simulación offline

Reproduce trazas deterministas sin contactar proveedores. Las políticas adaptativas de v0.3.0 viven aquí.

5. ¿Qué API expone?

La superficie Responses se describe deliberadamente como parcial, no como “compatibilidad completa con OpenAI”. Hay cobertura testeada para texto, bucles de funciones personalizadas y determinadas semánticas nativas, pero la plataforma Responses completa es mucho mayor.

6. ¿Cómo funciona el routing?

AgentMesh separa elegibilidad de preferencia.

Restricciones duras

• ¿El proveedor soporta el modelo solicitado?
• ¿Su circuito está disponible?
• ¿La semántica puede traducirse sin pérdida silenciosa?
• ¿Declara las capacidades necesarias?
• ¿Se agotó una cuota local configurada?

Políticas de producción

• ordered: preferencia por orden/peso configurado.
• latency: favorece menor señal de latencia.
• cost: favorece el cost_hint configurado.
• quality: favorece el quality_hint.
• balanced: combina términos normalizados de latencia, coste y calidad.

En v0.3.0 el coste USD observado no sustituye silenciosamente a cost_hint y p50/p95 no sustituyen al EWMA usado en producción. Medición y política se mantienen separadas.

7. ¿Qué describe un proveedor?

Puede definir nombre, tipo de adaptador, base URL, modelos permitidos, variable de entorno del secreto, peso, hints de coste/latencia/calidad, capacidades, precios por token y una cuota local opcional.

Las capacidades actuales son text, tools, reasoning y native_responses_tools. Si se declaran explícitamente son autoritativas; si se omiten se usan defaults derivados del adaptador.

Los secretos reales se referencian mediante variables de entorno, no se incrustan en la configuración del repositorio.

8. ¿Qué pasa si un proveedor falla?

Errores de red y HTTP se normalizan en un modelo común. Fallos de red, timeouts, rate limits y determinados errores de servidor pueden ser reintentables; la mayoría de los demás 4xx son terminales.

El runtime registra fallos consecutivos y puede abrir temporalmente el circuito de un proveedor. Una llamada posterior con éxito restaura el estado correspondiente.

En streaming hay una regla estricta: solo se permite failover antes del primer chunk comprometido. AgentMesh no mezcla silenciosamente dos proveedores dentro de una misma respuesta.

9. ¿Qué evidencia observa?

Latencia

Los éxitos actualizan un EWMA y una ventana acotada de observaciones recientes. p50/p95 se calculan de forma determinista.

Uso y coste

Si el upstream informa tokens exactos y existen precios configurados para input y output, AgentMesh calcula coste observado. Datos faltantes permanecen faltantes: no se convierten en cero ni se estiman por longitud de texto.

Fallos y circuitos

Se registran éxitos, fallos, fallos consecutivos y un resumen seguro del último error.

Cuota local

Una ventana fija opcional cuenta intentos salientes, incluidos los que fallan. No pretende replicar RPM/TPM privados ni facturación del vendor.

10. ¿Qué hace el simulador de investigación?

Lee configuración de proveedores y una traza JSONL de resultados contrafactuales. No realiza llamadas a las URLs de los proveedores. Cada política empieza con estado fresco y determinista.

Puede exportar JSON o CSV para análisis estadístico y visualización.

Baselines estáticos

ordered, latency, cost, quality y balanced.

Baselines adaptativos

adaptive_balanced usa evidencia evolutiva en una puntuación multiobjetivo restringida. constrained_ucb es un baseline experimental de estilo UCB contextual con feedback del proveedor elegido.

11. ¿Qué puede investigar un científico?

• Minimización de latencia bajo restricción de coste.
• Minimización de coste bajo restricción de calidad.
• Routing sensible a cuota en cargas con ráfagas.
• Cómo las capacidades cambian qué proveedor parece “mejor”.
• Políticas estáticas frente a políticas contextuales/adaptativas.
• Equilibrio exploración–explotación.
• Efecto de fallos de circuito sobre el conjunto viable.
• Sensibilidad a precios, perfiles de calidad y distribuciones de latencia.
• Impacto de tratar correctamente medidas faltantes en lugar de convertirlas en cero.

Los perfiles de calidad exigen procedencia: benchmark ID, versión, fuente, métrica y número de muestras. Esa estructura mejora la reproducibilidad, pero no certifica automáticamente la calidad científica del benchmark.

12. Modelo de seguridad

• No se almacenan API keys reales en el repositorio.
• Los secretos se leen desde variables de entorno.
• La autenticación bearer opcional protege rutas gateway y admin.
• Los request IDs ayudan a la trazabilidad.
• Los errores upstream se normalizan para evitar filtraciones.
• No se envía telemetría externa por defecto.

13. Reproducibilidad e integridad

Los tests y la simulación por defecto no requieren una API de pago. CI ejecuta Ruff y pytest en Python 3.11, 3.12 y 3.13. Las decisiones arquitectónicas se documentan con ADR. Las reglas de PROVENANCE prohíben copiar código, tests, documentación, assets o estructura interna de otros gateways.

La versión v0.3.0 está archivada en Zenodo con DOI 10.5281/zenodo.22069468.

14. ¿Qué se puede añadir?

15. ¿Qué no afirma v0.3.0?

• No afirma compatibilidad total con OpenAI Responses.
• No es una implementación completa de Codex, Claude Code, Cline u OpenCode.
• No traduce toda la semántica nativa de reasoning o herramientas entre vendors.
• No normaliza aún imagen/audio entre protocolos.
• No enruta todavía por capacidad de ventana de contexto.
• La cuota local no equivale a billing ni rate limits privados del proveedor.
• El coste observado es incompleto cuando el upstream no informa usage.
• Las políticas adaptativas/UCB no están activas en producción.
• No se extraen afirmaciones de superioridad de las trazas sintéticas de ejemplo.