APIEval-20

¿Qué es APIEval-20?

APIEval-20 es un benchmark de tareas diseñado para evaluar agentes de IA en la generación de suites de pruebas para APIs en escenarios del mundo real bajo restricción de black-box. En lugar de centrarse en la calidad general del modelo o en el cumplimiento superficial del esquema, mide si un agente puede razonar sobre la superficie de una API y generar pruebas que realmente descubran errores.

En cada escenario, el agente recibe solo un esquema de solicitud de API y un payload de muestra: sin código fuente, sin documentación más allá de lo que está en el esquema y sin conocimiento previo. La suite de pruebas generada se ejecuta contra una implementación de referencia en vivo para observar los errores que las pruebas exponen.

Características clave

• Benchmark de tareas para agentes de IA (no un benchmark de modelos): Evalúa el comportamiento end-to-end del agente —diseño de pruebas y descubrimiento de errores— en lugar de la calidad de generación de texto.
• Conjunto de 20 escenarios extraídos de dominios del mundo real: Los escenarios cubren comercio electrónico, pagos, autenticación, gestión de usuarios, programación, notificaciones y patrones de búsqueda/filtrado.
• Restricción de entrada black-box: El agente recibe exactamente dos entradas por escenario: (1) el esquema JSON y (2) un payload de solicitud de muestra, sin esquemas de respuesta, detalles de implementación, mensajes de error o changelogs.
• Espectro de errores con etiquetado basado en complejidad: Cada escenario incluye 3–8 errores plantados clasificados por complejidad de razonamiento: problemas estructurales simples, violaciones moderadas de restricciones de campos y interacciones complejas multifield/lógica de negocio.
• Formato de salida de suite de pruebas (casos de prueba solo de solicitud): El agente produce una lista de casos de prueba, cada uno con un nombre corto y un payload de solicitud completo como JSON válido; no se requieren resultados esperados.

Cómo usar APIEval-20

1. Selecciona un escenario del benchmark APIEval-20. Cada escenario proporciona un esquema JSON de solicitud de API y un payload de muestra.
2. Proporciona esas dos entradas a tu agente de IA. El benchmark está diseñado específicamente para que el agente no pueda depender de detalles de implementación o documentación extra.
3. Genera una suite de pruebas: Haz que el agente produzca casos de prueba donde cada caso incluya un nombre legible por humanos y un payload de solicitud JSON completo.
4. Ejecuta los casos de prueba producidos contra la implementación de referencia en vivo: La evaluación se basa en lo que las pruebas revelan al ejecutarse, no en si el agente predice resultados esperados.

Casos de uso

• Evaluar la capacidad de un agente para generar pruebas de API significativas: Útil cuando quieres saber si un agente puede ir más allá de la generación formal del esquema y producir pruebas que revelen errores reales.
• Comparar estrategias de agentes bajo la misma restricción black-box: Como las entradas se limitan a esquema + payload de ejemplo, las diferencias en rendimiento reflejan razonamiento y cobertura de pruebas en lugar de acceso a información adicional.
• Probar robustez estructural (detección de errores simples): Los escenarios incluyen verificaciones para campos requeridos faltantes, valores vacíos (p. ej., "", null, [] ) y tipos de datos incorrectos, útil para validar el manejo básico de solicitudes.
• Evaluar razonamiento de restricciones y validación (detección de errores moderados): El benchmark incluye casos como valores numéricos fuera de rango y formatos de campos malformados (p. ej., email, código de moneda, formato de fecha), más valores de enum en límite/no documentados.
• Evaluar razonamiento de lógica de negocio e intercampo (detección de errores complejos): Algunos escenarios requieren detectar problemas que involucran campos mutuamente excluyentes, descuentos aplicados a pedidos no elegibles o validez de campos dependiente de otros campos.

Preguntas frecuentes

¿Qué entradas recibe el agente para cada escenario?
El agente recibe exactamente dos entradas: el esquema JSON de solicitud completo y un ejemplo de payload de muestra. No se proporcionan esquemas de respuesta, detalles de implementación, mensajes de error u otra documentación.

¿El agente necesita predecir resultados esperados?
No. La suite de pruebas producida consiste en casos de prueba con payloads de solicitud; la evaluación se realiza ejecutando esas pruebas contra la implementación de referencia en vivo y observando qué sucede.

¿Cómo se representan los errores en el benchmark?
Cada escenario contiene múltiples errores plantados (entre 3 y 8), categorizados por complejidad: problemas estructurales simples, violaciones moderadas de restricciones a nivel de campo e interacciones complejas multifield o semánticas/lógica de negocio.

¿Qué evalúa APIEval-20: cumplimiento del esquema o búsqueda de errores?
Búsqueda de errores. Aunque se proporciona información del esquema para habilitar la generación de pruebas, el benchmark está diseñado para probar si las pruebas del agente descubren errores al ejecutarse.

Alternativas

• Generación de pruebas enfocada en esquemas / verificadores de cumplimiento de esquemas: Estos se centran en validar que las solicitudes generadas coincidan con un esquema (o que un sistema lo siga). Difieren de APIEval-20 al no evaluar directamente el comportamiento de detección de errores bajo restricciones de black-box.
• Herramientas y frameworks convencionales de pruebas de API (p. ej., herramientas de pruebas de solicitudes/contratos): Estos flujos de trabajo suelen depender de casos de prueba escritos por humanos o conocimiento adicional. En comparación con APIEval-20, pueden no evaluar la capacidad de un agente para generar suites de pruebas dirigidas solo a partir de esquema + ejemplo.
• Benchmarks generales de evaluación de IA para generación de código o texto: Algunos evalúan la calidad de la salida en lugar de la efectividad de pruebas ejecutables. APIEval-20 se enfoca específicamente en el comportamiento de extremo a extremo de agentes para generar y ejecutar pruebas que expongan errores.
• Enfoques de pruebas basadas en propiedades de API / fuzzing: Estos pueden probar una API de manera amplia generando muchos insumos, pero pueden no evaluar el proceso de razonamiento del agente para diseñar pruebas dirigidas a partir de esquema y payloads de ejemplo.