La mayoría de las APIs están diseñadas para desarrolladores humanos que leen documentación, exploran ejemplos y depuran errores con seguimientos de pila (stack traces). En 2026, una parte creciente del tráfico de las APIs proviene de agentes de IA, y estos no interactúan con las APIs de la misma manera que los humanos.
Así es como rediseñamos la API de IA unificada de TokenLab basándonos en un principio: no intentes ser ingenioso, sé informativo. Llamamos al resultado diseño de API "agent-first", y redujo el desperdicio de tokens para nuestros usuarios en más de un 60%.
Puntos clave
- El diseño de API "agent-first" añade sugerencias estructuradas y legibles por máquina a las respuestas de error, para que los agentes de IA puedan autocorregirse sin necesidad de búsquedas web o ayuda humana.
- Sugiere alternativas, no autocorrijas. Campos como
did_you_mean,suggestionsyretryablepermiten a los agentes tomar decisiones informadas en lugar de que la decisión sea tomada por ellos. - Cada sugerencia está basada en datos de producción, por lo que los modelos fuera de línea o obsoletos nunca aparecen en la lista de candidatos.
- Los campos de sugerencias son aditivos y compatibles con versiones anteriores, por lo que los clientes existentes compatibles con OpenAI siguen funcionando sin cambios.
¿Qué es el diseño de API "Agent-First"?
El diseño de API "agent-first" significa estructurar tus respuestas, especialmente las de error, para que un agente de IA pueda entender qué salió mal y solucionarlo sin abandonar la conversación.
Error de API tradicional:
{"error": {"message": "Model not found"}}
Error de API "agent-first":
{
"error": {
"code": "model_not_found",
"message": "Model 'gpt5.5' not found",
"did_you_mean": "gpt-5.5",
"suggestions": [{"id": "gpt-5.5"}, {"id": "gemini-3.5-flash"}],
"hint": "Use GET /v1/models to list all available models."
}
}
Con una API tradicional, el agente tiene que buscar en la web, encontrar documentación, analizar HTML y adivinar. Con una API "agent-first", se autocorrije en un solo paso.
Por qué las APIs tradicionales fallan con los agentes de IA
Observa lo que sucede cuando un agente accede a un agregador de API típico por primera vez:
Agent: POST /v1/chat/completions {"model": "gpt5.5"}
API: 400 {"error": {"message": "Model not found"}}
Agent: (searches the web for "tokenlab 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-5.5"}
API: 200 ✓
Seis pasos, múltiples solicitudes de red, cientos de tokens desperdiciados. Y ese es el camino feliz, donde el agente tuvo la suerte de adivinar la URL correcta de la documentación.
Con el diseño "agent-first":
Agent: POST /v1/chat/completions {"model": "gpt5.5"}
API: 400 {"did_you_mean": "gpt-5.5", "hint": "Use GET /v1/models..."}
Agent: POST /v1/chat/completions {"model": "gpt-5.5"}
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 construir APIs "inteligentes" que autocorrijan el nombre del modelo, redirijan silenciosamente a algo similar o añadan un motor de recomendaciones. Rechazamos todo eso.
Cuando un agente envía model: "gpt5.5", en realidad no conoces su intención. Tal vez esté comprobando si existe una versión más reciente de GPT. Tal vez tenga una restricción presupuestaria estricta. Tal vez necesite una capacidad específica que solo un modelo admite. La redirección automática a gpt-5.5 cambiaría silenciosamente el costo, la calidad y las capacidades, y el agente nunca sabría que sucedió.
La mejor opción es fallar rápido y fallar de forma informativa. Dale al agente todos los datos y deja que 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-5.5",
"suggestions": [
{"id": "gpt-5.5"},
{"id": "gemini-3.5-flash"},
{"id": "claude-sonnet-5"}
],
"hint": "Did you mean 'gpt-5.5'? Use GET /v1/models to list all available models."
}
}
did_you_mean utiliza una resolución de tres capas: mapeo de alias estáticos a partir de datos de producción, coincidencia de cadenas normalizada y distancia de edición acotada. Cada candidato se verifica contra la lista de modelos activos, 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": "gemini-3.5-flash", "estimated_cost_usd": 0.02},
{"id": "deepseek-v4-flash", "estimated_cost_usd": 0.01}
],
"hint": "Insufficient balance. Try a cheaper model or top up."
}
}
En lugar de solo decir "fondos insuficientes", le decimos al agente exactamente cuánto tiene, cuánto necesita y qué modelos puede pagar en este momento. El agente puede degradar autónomamente a un modelo de IA más barato sin intervención humana. Verifica los precios actuales por modelo en el directorio de modelos de TokenLab antes de codificar umbrales de costo.
Patrón 3: Todos los canales fallaron → Alternativas en vivo
{
"error": {
"code": "all_channels_failed",
"retryable": true,
"retry_after": 30,
"alternatives": [
{"id": "claude-sonnet-5", "status": "available"},
{"id": "gpt-5.5", "status": "available"}
],
"hint": "All channels for 'claude-opus-4-8' temporarily unavailable. Retry in 30s or try an alternative."
}
}
La lista alternatives no es estática. Es una consulta en vivo contra nuestros datos de salud de canales, por lo que el agente obtiene información en tiempo real sobre lo que realmente funciona en este momento, no una lista de respaldo codificada que podría estar obsoleta.
Patrón 4: Límite de tasa excedido → Tiempo de reintento exacto
{
"error": {
"code": "rate_limit_exceeded",
"retryable": true,
"retry_after": 8,
"limit": "1000/min",
"remaining": 0,
"hint": "Rate limited. Retry after 8s."
}
}
Sin adivinanzas, sin retroceso exponencial (exponential backoff) comenzando desde un valor arbitrario. El agente conoce el tiempo de espera exacto. Para más información sobre cómo manejar bien los límites de tasa, consulta nuestra guía de límites de tasa de la API de IA.
Las respuestas de éxito también incluyen sugerencias
Cuando un agente llama a /v1/chat/completions con un modelo Claude, la respuesta incluye:
X-TokenLab-Hint: This model supports native Anthropic format. Use POST /v1/messages for better performance.
X-TokenLab-Native-Endpoint: /v1/messages
Le estamos diciendo al agente: esto funcionó, pero hay una forma mejor. Puede cambiar al endpoint nativo en la siguiente llamada y aprovechar funciones como el pensamiento extendido (extended thinking) y el almacenamiento en caché de prompts que no están expuestos a través del formato compatible con OpenAI.
Estas sugerencias viven en los encabezados (headers), no en el cuerpo de la respuesta, porque el cuerpo debe seguir exactamente la especificación de OpenAI o Anthropic. Los encabezados son el punto de extensión seguro que no romperá ninguna lógica de análisis existente.
La respuesta de /v1/models como una hoja de trucos para el agente
Añadimos tres campos a cada entrada de modelo en la respuesta de /v1/models:
category: modelo de chat, generador de imágenes, modelo de video o audio. Ya no hay que adivinar por el nombre.pricing_unit: por token, por imagen, por segundo o por solicitud. Necesario para cualquier estimación de costo real.cache_pricing: precios de caché de prompts ascendentes más el descuento de caché semántica de la plataforma.
Combinado con los campos existentes (precios, capacidades, alias, tokens máximos), un agente puede realizar una selección de modelo totalmente informada a partir de una sola llamada a la API. Puedes ver el catálogo completo en vivo en el directorio de modelos de TokenLab (observado el 07-07-2026), que actualmente enumera más de 300 modelos en categorías de chat, imagen, video y audio, incluyendo opciones de frontera actuales como Claude Sonnet 5, GPT-5.5 y Gemini 3.5 Flash. Verifica los precios y la disponibilidad actuales en esa página en lugar de asumir que las cifras en este artículo están actualizadas.
llms.txt: La primera lectura del agente
Servimos un llms.txt dinámico en api.tokenlab.sh/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 en lugar de codificados
- Los 12 endpoints con parámetros
- Parámetros de filtro para el descubrimiento de modelos
Un agente que lee este archivo antes de su primera llamada a la API tiene muchas más probabilidades de obtener la solicitud correcta en el primer intento.
Basado en datos, no en conocimiento
Cada sugerencia en el sistema proviene de datos de producción. El mapa de alias did_you_mean se generó a partir de 30 días de errores reales de model_not_found en nuestros registros de solicitudes. Las sugerencias de modelos se ordenan por uso real. La lista de "nombres de modelos comunes" en llms.txt se genera a partir de nuestra base de datos, no se mantiene manualmente.
Rastreamos cada error de modelo en un conjunto ordenado de Redis. Una vez que un error ortográfico acumula suficientes aciertos, se promociona al mapa de alias. Cuando un modelo se desconecta, sale automáticamente de cada lista de sugerencias. El sistema se ajusta solo con el tiempo en lugar de quedar desactualizado, lo cual es importante cuando nuevos lanzamientos de modelos como GPT-5.5, Claude Sonnet 5 y Gemini 3.5 Flash se lanzan en cronogramas superpuestos.
La restricción de diseño que hizo que funcionara
Establecimos una regla: sin nuevos endpoints, sin nuevos SDKs, sin cambios disruptivos. Todo tenía que encajar dentro del formato de error existente compatible con OpenAI. Los nuevos campos son opcionales, por lo que cualquier cliente que los ignore obtiene exactamente la misma experiencia que antes.
Esa restricción forzó la precisión sobre lo que realmente ayuda a un agente a autocorregirse, en lugar de construir nuevas APIs elaboradas que nadie se molestaría en adoptar.
Cómo aplicar el diseño "Agent-First" a tu propia API
Si estás construyendo APIs que consumirán agentes de IA:
- Haz que cada error sea procesable. Indica qué salió mal, por qué y qué hacer a continuación.
- Sugiere alternativas en lugar de autocorregir. Deja que el agente tome la decisión informada.
- Usa campos estructurados, no prosa.
did_you_meanes analizable; "did you mean..." enterrado en una oración no lo es. - Basar las sugerencias en datos reales. Los patrones de uso de producción superan a una lista codificada que se vuelve obsoleta.
- Sirve descubrimiento legible por máquina a través de
llms.txt, una especificación OpenAPI o una lista de modelos estructurada. - Mantén la compatibilidad con versiones anteriores. Los nuevos campos de sugerencias 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. Un punto de partida más pequeño funciona bien:
- Añade uno o dos campos de sugerencias legibles por máquina a tus errores de mayor volumen.
- Haz que
/v1/modelso tu endpoint de descubrimiento equivalente sea más rico y explícito. - Publica una descripción general legible por máquina, como
llms.txt. - Prueba el ciclo completo con un cliente agente real, no solo con curl.
Si ya estás operando a través de una capa de puerta de enlace (gateway), la guía de puerta de enlace de IA unificada explica 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 incorporar un comportamiento amigable para los agentes.
Preguntas frecuentes
¿Qué es el diseño de API "agent-first"?
Es un enfoque donde las respuestas de error incluyen sugerencias estructuradas y legibles por máquina (campos como did_you_mean, suggestions y hint) para que los agentes de IA puedan autocorregirse sin intervención humana o una consulta de documentación.
¿En qué se diferencia el diseño "agent-first" del diseño de API "developer-first"?
Las APIs "developer-first" optimizan la legibilidad humana: mensajes claros, buena documentación, ejemplos útiles. Las APIs "agent-first" añaden campos estructurados sobre eso para que las máquinas puedan analizar el error y actuar en consecuencia de forma programática, sin leer nada.
¿El diseño "agent-first" rompe los clientes existentes?
No. Los campos son aditivos. Los clientes existentes que no buscan did_you_mean o suggestions simplemente los ignoran y siguen funcionando exactamente igual que antes.
TokenLab proporciona acceso unificado a más de 300 modelos de IA, incluidos los modelos de frontera actuales como GPT-5.5, Claude Sonnet 5 y Gemini 3.5 Flash, a través de una única API listada en el directorio de modelos. Comienza gratis para probar la API "agent-first" con $1 en créditos iniciales.
Fuentes
Precio observado el 2026-07-07
- TokenLab model directoryObservado el 2026-07-07
