La mayoría de las API están diseñadas para desarrolladores humanos que leen documentación, exploran ejemplos y depuran con stack traces. Pero en 2026, los consumidores de API que más rápido crecen son los agentes de IA, y ellos interactúan con las API de forma muy diferente.
Esta es la historia de cómo rediseñamos la API de IA unificada de LemonData basándonos en un principio sencillo: no seas inteligente, sé informativo. El resultado es lo que llamamos diseño de API agent-first, y redujo el desperdicio de tokens de nuestros usuarios en más de un 60%.
¿Qué es el diseño de API Agent-First?
El diseño de API agent-first consiste en estructurar las respuestas de la API, especialmente las de error, para que un agente de IA pueda entender qué salió mal y corregirlo sin ayuda externa.
Error de API tradicional:
{"error": {"message": "Model not found"}}
Error de API agent-first:
{
"error": {
"code": "model_not_found",
"message": "Model 'gpt5' not found",
"did_you_mean": "gpt-4o",
"suggestions": [{"id": "gpt-4o"}, {"id": "gpt-4o-mini"}],
"hint": "Use GET /v1/models to list all available models."
}
}
¿La diferencia? Con una API tradicional, el agente necesita buscar en la web, encontrar la documentación, analizar el HTML y adivinar. Con una API agent-first, se autocorrige en un solo paso.
Por qué las API tradicionales fallan a los agentes de IA
Observa lo que sucede cuando un agente de IA accede por primera vez a un agregador de API típico:
Agent: POST /v1/chat/completions {"model": "gpt5"}
API: 400 {"error": {"message": "Model not found"}}
Agent: (searches the web for "lemondata models list")
Agent: (fetches a docs page, maybe the wrong one)
Agent: (parses HTML, finds a model name)
Agent: POST /v1/chat/completions {"model": "gpt-4o"}
API: 200 ✓
Seis pasos. Múltiples peticiones de red. Cientos de tokens desperdiciados. Y este es el camino ideal, donde el agente adivinó la URL correcta de la documentación.
Con el diseño agent-first:
Agent: POST /v1/chat/completions {"model": "gpt5"}
API: 400 {"did_you_mean": "gpt-4o", "hint": "Use GET /v1/models..."}
Agent: POST /v1/chat/completions {"model": "gpt-4o"}
API: 200 ✓
Dos pasos. Cero búsquedas web. El agente se autocorrigió solo con la respuesta de error.
El principio fundamental: la inteligencia permanece en el lado del modelo
La tentación es crear API "inteligentes": autocorregir el nombre del modelo, redirigir silenciosamente a un modelo similar, añadir un motor de recomendación. Rechazamos todo eso.
Cuando un agente envía model: "gpt5", no conoces su intención. Quizás está probando si GPT-5 existe. Quizás tiene una restricción de presupuesto. Quizás necesita una capacidad específica. Redirigir automáticamente a gpt-4o cambiaría silenciosamente el costo, la calidad de la salida y las capacidades, todo sin que el agente lo sepa.
Lo correcto es fallar rápido y fallar de forma informativa. Dale al agente todos los datos. Deja que él decida.
Cuatro patrones de diseño de API Agent-First
Patrón 1: Modelo no encontrado → Sugerencias difusas
{
"error": {
"code": "model_not_found",
"did_you_mean": "gpt-4-turbo",
"suggestions": [
{"id": "gpt-4o"},
{"id": "gpt-4o-mini"},
{"id": "claude-sonnet-4-5"}
],
"hint": "Did you mean 'gpt-4-turbo'? Use GET /v1/models to list all available models."
}
}
El campo did_you_mean utiliza una resolución de tres capas: mapeo de alias estáticos de datos de producción, coincidencia de cadenas normalizadas y distancia de edición limitada. Todos los candidatos se validan contra la lista de modelos en vivo, por lo que nunca sugerimos un modelo que esté actualmente fuera de línea.
Patrón 2: Saldo insuficiente → Alternativas conscientes del presupuesto
{
"error": {
"code": "insufficient_balance",
"balance_usd": 0.12,
"estimated_cost_usd": 0.35,
"suggestions": [
{"id": "gpt-4o-mini", "estimated_cost_usd": 0.02},
{"id": "deepseek-chat", "estimated_cost_usd": 0.01}
],
"hint": "Insufficient balance. Try a cheaper model or top up."
}
}
En lugar de simplemente decir "no hay suficiente dinero", le decimos al agente exactamente cuánto tiene, cuánto necesita y qué modelos puede costear. El agente puede degradar de forma autónoma a un modelo de IA más barato, sin necesidad de intervención humana.
Patrón 3: Todos los canales fallaron → Alternativas en vivo
{
"error": {
"code": "all_channels_failed",
"retryable": true,
"retry_after": 30,
"alternatives": [
{"id": "claude-sonnet-4-5", "status": "available"},
{"id": "gpt-4o", "status": "available"}
],
"hint": "All channels for 'claude-opus-4-6' temporarily unavailable. Retry in 30s or try an alternative."
}
}
La lista de alternatives no es estática. Es una consulta en tiempo real contra nuestros datos de salud del canal, por lo que el agente obtiene información en tiempo real sobre lo que realmente está funcionando en ese momento.
Patrón 4: Límite de tasa excedido → Tiempo exacto de reintento
{
"error": {
"code": "rate_limit_exceeded",
"retryable": true,
"retry_after": 8,
"limit": "1000/min",
"remaining": 0,
"hint": "Rate limited. Retry after 8s."
}
}
Sin adivinanzas. Sin exponential backoff a partir de valores arbitrarios. El agente conoce el tiempo de espera exacto. Para más información sobre cómo manejar los límites de tasa de manera efectiva, consulta nuestra guía de rate limiting para API de IA.
Las respuestas exitosas también llevan pistas
Cuando un agente llama a /v1/chat/completions con un modelo de Claude, la respuesta incluye:
X-LemonData-Hint: This model supports native Anthropic format. Use POST /v1/messages for better performance.
X-LemonData-Native-Endpoint: /v1/messages
Le estamos diciendo al agente: "esto funcionó, pero hay una forma mejor". El agente puede cambiar al endpoint nativo en la siguiente llamada, obteniendo acceso a funciones como el pensamiento extendido y el prompt caching que no están disponibles a través del formato compatible con OpenAI.
Colocamos esto en los headers, no en el cuerpo de la respuesta, porque el cuerpo sigue la especificación de OpenAI/Anthropic. Los headers son el punto de extensión seguro.
La respuesta de /v1/models como hoja de trucos para el agente
Añadimos tres campos a cada modelo en la respuesta de /v1/models:
category: modelo de chat, generador de imágenes, modelo de video o audio. Se acabaron las adivinanzas por el nombre.pricing_unit: por token, por imagen, por segundo o por solicitud. Esencial para la estimación de costos.cache_pricing: precios de prompt cache ascendentes más el descuento de caché semántico de la plataforma.
Combinado con los campos existentes (precios, capacidades, alias, tokens máximos), un agente puede tomar decisiones de selección de modelos totalmente informadas desde una sola llamada a la API.
llms.txt: La primera lectura del agente
Servimos un llms.txt dinámico en api.lemondata.cc/llms.txt, una descripción general legible por máquina de toda la API. Incluye:
- Una plantilla de primera llamada con código funcional
- Nombres de modelos comunes (generados automáticamente a partir de datos de uso, no codificados a mano)
- Los 12 endpoints con sus parámetros
- Parámetros de filtrado para el descubrimiento de modelos
Un agente que lea este archivo antes de su primera llamada a la API probablemente lo hará bien al primer intento.
Basado en datos, no en conocimiento
Cada sugerencia en nuestro sistema proviene de datos de producción. El mapa de alias did_you_mean se alimentó de 30 días de errores reales de model_not_found en nuestros registros de peticiones. Las sugerencias de modelos se ordenan por patrones de uso reales. Los "nombres de modelos comunes" en llms.txt se generan desde nuestra base de datos.
Rastreamos cada fallo de modelo en un sorted set de Redis. Cuando una falta de ortografía acumula suficientes impactos, se promociona al mapa de alias. Cuando un modelo se desconecta, desaparece automáticamente de todas las sugerencias. El sistema se mejora a sí mismo.
La restricción de diseño que hizo que funcionara
Establecimos una regla: sin nuevos endpoints, sin nuevos SDK, sin cambios disruptivos. Todo tenía que funcionar dentro del formato de error compatible con OpenAI existente. Los nuevos campos son opcionales, por lo que cualquier cliente que los ignore obtiene la misma experiencia que antes.
Esta restricción nos obligó a ser precisos sobre qué información ayuda realmente a un agente a autocorregirse, en lugar de construir nuevas y elaboradas API que nadie adoptaría.
Cómo aplicar el diseño Agent-First a tu propia API
Si estás construyendo API que consumirán agentes de IA:
- Cada error debe ser accionable. Incluye qué salió mal, por qué y qué hacer a continuación.
- Sugiere alternativas, no autocorrijas. Deja que el agente tome decisiones informadas.
- Usa campos estructurados, no prosa.
did_you_meanes parseable; "¿Quiso decir...?" en una cadena de texto no lo es. - Basa las sugerencias en datos reales. Los patrones de uso en producción superan a las listas codificadas a mano.
- Ofrece descubrimiento legible por máquina a través de
llms.txt, especificaciones OpenAPI o listas de modelos estructuradas. - Mantén la compatibilidad hacia atrás. Los nuevos campos de sugerencia deben ser aditivos, nunca disruptivos.
Por dónde empezar sin reescribirlo todo
La mayoría de los equipos no necesitan rediseñar toda su API en una semana.
El punto de partida práctico es más pequeño:
- añade uno o dos campos de sugerencia legibles por máquina a tus errores de mayor volumen
- haz que
/v1/modelso el endpoint equivalente de descubrimiento de modelos sea más rico y explícito - publica una descripción general legible por máquina como
llms.txt - prueba todo el ciclo con un cliente agente, no solo con curl
Si ya estás operando a través de una capa de gateway, la guía de gateway de IA unificada muestra por qué ese plano de control es importante. Si todavía estás en una integración directa compatible con OpenAI, la guía de migración es el lugar más fácil para comenzar antes de añadir más comportamientos amigables para agentes.
FAQ
¿Qué es el diseño de API agent-first?
El diseño de API agent-first es un enfoque donde las respuestas de error incluyen pistas estructuradas y legibles por máquina que permiten a los agentes de IA autocorregirse sin intervención humana ni consultas a documentación externa.
¿En qué se diferencia agent-first del diseño de API developer-first?
Las API developer-first optimizan para la legibilidad humana: mensajes de error claros, buena documentación, ejemplos útiles. Las API agent-first añaden campos estructurados (did_you_mean, suggestions, hint) que las máquinas pueden analizar y actuar sobre ellos programáticamente.
¿El diseño agent-first rompe los clientes existentes?
No. Los campos agent-first son aditivos, lo que significa que los clientes existentes pueden ignorarlos y seguir funcionando sin cambios.
¿Cómo implementa LemonData el diseño agent-first?
El gateway de API de IA unificada de LemonData añade pistas de error estructuradas a sus más de 300 modelos. Cada respuesta de error incluye sugerencias accionables, y el endpoint llms.txt proporciona descubrimiento de API legible por máquina.
LemonData proporciona acceso unificado a más de 300 modelos de IA a través de una sola API. Pruébalo gratis para testear la API agent-first con $1 en créditos de inicio.
