He creado un agente de IA que te permite explorar APIs en inglés sencillo

Mi producto actual tiene cientos de APIs. Cada vez que necesito consultar la especificación de la API, tengo que navegar al enlace de Swagger, desplazarme interminablemente o usar la búsqueda del navegador para encontrar lo que necesito, y luego filtrar manualmente las cosas. Es frustrante y dolorosamente lento. Peor aún, cada desarrollador que necesita integrarse con la API tiene que pasar por la misma experiencia.

Esta frustración me llevó a explorar cómo la IA podría mejorar el proceso. Esta publicación es una inmersión profunda en ese viaje y cómo evolucionó hacia algo simple, robusto y efectivo.

Preparación

Documentación Rica de API

Como primer paso, revisé toda la documentación de la API para asegurarme de que tuviera detalles claros de resumen y descripción en los documentos de swagger. Este es un paso crítico para una mejor capacidad de descubrimiento en etapas posteriores. También me aseguré de que el resumen y la descripción fueran únicos para cada API.

paths": {     "/users/accounts/{account-id}": {       "put": {         "tags": [           "Account API"         ],         "summary": "Update Test suite by test-suite-id",         "externalDocs": {           "description": "Robust get account details description",           "url": "https://mydocs.com/description"         },

\

Categorización de las APIs

Con cientos de APIs disponibles, puede ser difícil identificar cuáles están relacionadas. Categorizar las APIs hace que la gestión sea más eficiente y luego simplifica la selección de la API correcta basada en la entrada de lenguaje natural. Esta categorización se implementó utilizando el concepto de etiquetado definido en la especificación OpenAPI.

\

"paths": {     "/users/accounts/{account-id}": {       "put": {         "tags": [           "Account API"         ],         "summary": "Update Test suite by test-suite-id",         "externalDocs": {           "description": "Robust get account details description",           "url": "https://mydocs.com/description"         },

\

Construyendo Búsqueda en Lenguaje Natural

Entrada del Usuario

Los usuarios ingresarían la pregunta en lenguaje natural relacionada con la API.

Ejemplo: ¿Cómo recuperar detalles de la cuenta?

Clasificar Categoría

En esta etapa, la pregunta y todas las categorías disponibles se envían al LLM. El LLM tiene la tarea de devolver la categoría de alto nivel en la que cae la pregunta. El resultado de este paso es una de las categorías.

Clasificar API Específica

Basado en la categoría identificada por el LLM, el sistema envía otra solicitud al modelo con la misma pregunta, pero esta vez incluye todos los detalles de la API dentro de esa categoría específica detectada en el paso anterior.

Aquí es donde la preparación anterior da sus frutos: cuanto más descriptiva y bien estructurada sea la documentación de la API, mejores serán los resultados. Las descripciones claras ayudan al LLM a determinar con precisión sobre qué API está solicitando información el usuario.

El resultado de este paso es una única API específica.

Enriquecer Detalles de Respuesta de API

La especificación OpenAPI de la API se proporciona entonces al LLM para generar una descripción detallada y rica en contexto de la API junto con la pregunta original.

Por ejemplo, si el usuario pregunta, "¿Cómo puedo recuperar detalles de la cuenta usando un ID de cuenta?", la respuesta incluirá los detalles de especificación relevantes de la API de Cuenta.

Extensión

Con la capacidad mejorada del sistema para detectar con precisión la API apropiada, los usuarios ahora pueden dar un paso más: generar fragmentos de código para interactuar directamente con varias APIs.

Por ejemplo:

• "Comparte código Python para llamar a la API Obtener Detalles de Cuenta para un ID dado."

• "Proporciona un comando cURL para obtener detalles de cuenta por ID."

• "Genera un cliente Go para recuperar detalles de cuenta para un ID específico."

\

Lecciones Aprendidas e Insights

• La documentación rica es imperativa para una mejor precisión cuando se trabaja con sistemas de IA. La documentación precisa, clara y concisa es esencial para la robustez. Bonus: También usamos LLM para generar un resumen y descripción para cada API, lo que ayudó inmensamente.
• Categorizar Primero
• Por qué: Con cientos de APIs, la categorización reduce la carga cognitiva y mejora la recuperación.
• Cómo: Agrupa APIs relacionadas en un pequeño conjunto de categorías claras. Los sistemas de IA funcionan mejor cuando el espacio de etiquetas es limitado.
• Consejo de escala: Si el catálogo es muy grande, agrega sub-categorías para un enrutamiento más fino.
• Construir Iterativamente
• Comenzar pequeño: Toma un subconjunto de la especificación y entrena/valida un enrutador que pueda seleccionar de manera confiable la API correcta.
• Expandir gradualmente: Agrega más APIs con el tiempo, mide la precisión y prioriza áreas con clasificaciones erróneas.
• Enfoque: Optimiza la precisión/recuperación en lugar de la amplitud desde el principio.
• Cerrar el Ciclo con los Usuarios
• Recopilar feedback: Captura casos donde el sistema eligió la API incorrecta.
• Actuar sobre señales: Refina las descripciones, resúmenes y etiquetas de las APIs mal identificadas; clarifica ámbitos superpuestos.
• Repetir: Reevalúa después de cada cambio para confirmar que la precisión mejora y se evitan regresiones.

Conclusión

A medida que el número de APIs disponibles continúa creciendo, explorarlas y gestionarlas requiere un nuevo enfoque. Con el auge de los Agentes de IA impulsados por IA y modelos de lenguaje grandes (LLMs), los desarrolladores ahora tienen una forma más intuitiva y eficiente de descubrir e interactuar con APIs, ahorrando innumerables horas que antes se gastaban buscando los endpoints correctos.

El potencial no se detiene ahí. Este concepto puede evolucionar hacia un producto independiente capaz de ingerir sin problemas especificaciones OpenAPI en tiempo de ejecución y exponerlas a través de una interfaz de lenguaje natural, ofreciendo a los usuarios una solución lista para usar para la exploración de APIs.

Espero que este artículo haya ilustrado cómo aprovechar los LLMs de manera efectiva y cómo una documentación de API bien estructurada puede crear una experiencia de descubrimiento más fluida e inteligente.

\n \n

\n \n