Creación de un asistente de API agente: de hackathon a versión beta.

Un equipo que gestiona una API de administración de flotas para una empresa de pagos convirtió un prototipo creado en un hackathon en un asistente beta integrado en su portal de desarrolladores. La idea es evitar que los integradores tengan que leer páginas de referencia y traducirlas a código, permitiendo en su lugar que un agente conversacional se encargue de la integración. Aquí se explica cómo se construye dicho asistente, qué tareas se niega a realizar intencionadamente y cómo se mide su calidad.

El asistente explica los puntos de conexión, escribe código en el lenguaje que utilice el desarrollador, planifica flujos de trabajo de varios pasos y realiza consultas de datos de solo lectura en sistemas en tiempo real. Sustituye a las documentaciones estáticas específicas de cada lenguaje y a los índices de búsqueda que solo apuntan a páginas.

Por qué las documentaciones estáticas ya no son suficientes

El software de flotas y movilidad maneja una gran cantidad de datos: actividad de los conductores, estaciones de servicio, transacciones con tarjetas y telemetría de los vehículos. Quien lo integre debe aprender sobre endpoints REST avanzados, sintaxis de filtrado, vocabulario del dominio y largas cadenas de llamadas dependientes. Todo ese complejidad dificultó que los socios crecieran junto con la plataforma.

Los desarrolladores dependían de herramientas de documentación listas para usar para leer las definiciones de los endpoints y de utilidades de prueba para realizar llamadas manualmente. El equipo también mantenía “recetas”, secuencias fijas de llamadas que mostraban cómo completar tareas de varios pasos como crear una cuenta, incorporar a un conductor y adjuntar una tarjeta. Funcionaban, pero aparecían tres debilidades constantemente:

• Vinculado a un lenguaje. Mostrar cada flujo de trabajo en cURL, Python, .NET, Java y Go requería un esfuerzo manual constante por parte de los redactores e ingenieros.
• Frágil en los bordes. Es imposible documentar cada permutación de cada flujo de trabajo, por lo que las guías a menudo omiten el caso específico de un colaborador.
• Gastos constantes de mantenimiento. En cuanto cambiaba el esquema de una API, las páginas se volvían obsoletas, lo que prolongaba el proceso de integración y saturaba la cola de soporte.

De una idea en un hackathon a dos modos

La prueba de concepto surgió de un hackathon interno en diciembre de 2025 a partir de una sola pregunta: ¿por qué pedir a los desarrolladores que conviertan la documentación en código cuando un modelo puede comprender directamente su intención? Lo que resultó funciona como un consultor de integración siempre disponible, y no como un cuadro de búsqueda.

Por motivos de seguridad operativa, el diseño divide al asistente en dos rutas de procesamiento independientes.

Modo asesor se encarga de proporcionar explicaciones detalladas para una sola consulta, análisis profundos de la documentación y generación de código para cualquier framework, incluyendo llamadas de mutación como POST, PUT y DELETE. Produce código pero nunca lo ejecuta, por lo que una persona debe intervenir siempre que haya cambios en los datos.

Modo planificar y ejecutar procesa solicitudes de lectura complejas y multietapas y las lleva a cabo en la plataforma en tiempo real mediante herramientas de Protocolo de Contexto de Modelo (MCP) de solo lectura.

Lo que ven realmente los socios

Si se pide al modo asesor un fragmento de código en Python que cree un controlador, este devuelve una llamada a requests con el endpoint adecuado, encabezados, esquema del cuerpo y un comentario sobre los alcances requeridos. Nada afecta a la API de producción.

El modo de planificación y ejecución solicita a cinco conductores cuyo nombre de pila es John, y un planificador reduce la llamada con múltiples filtros a una sola tarea: obtener los conductores filtrados por nombre de pila. Un ejecutor selecciona la herramienta MCP correspondiente, construye los argumentos OData ($filter=first_name eq 'John', $top=5), ejecuta una solicitud GET de solo lectura y guarda toda la respuesta en un almacén de artefactos. El modelo solo ve un resumen compacto, como un ID de artefacto, un conteo de cinco y una breve vista previa. Luego, un sintetizador escribe una lista limpia de los cinco conductores que coinciden.

Arquitectura: un ciclo de agentes que cooperan

El asistente está basado en LangGraph como una máquina de estados cíclica. Un planificador, ejecutores, validadores y un sintetizador se turnan para planificar, actuar y verificar cada paso, pasando el estado y la memoria compartidos hasta que la tarea se completa. Destacan cuatro decisiones de diseño.

1. Un proxy de solo lectura para mayor seguridad

La seguridad influyó en el diseño desde el principio. El asistente no puede ejecutar llamadas que modifiquen datos dentro de su propio entorno de ejecución. Cuando un usuario dice “crear una nueva tarjeta para el conductor X”, un enrutador envía la solicitud al nodo asesor, el cual devuelve un fragmento estructurado que el desarrollador puede copiar, revisar y ejecutar localmente. Todo lo que se ejecuta realmente se limita a solicitudes GET. Existen herramientas con capacidad de escritura en el código del servidor MCP, pero estas se filtran antes de que el modelo pueda verlas.

2. Orquestación al estilo supervisor

El razonamiento y la ejecución se encuentran en capas diferentes, coordinados por un único supervisor que decide qué especialista actuará a continuación dentro de un bucle global:

• Una clase mode router clasifica la intención y envía cada mensaje al asesor o al módulo de planificación y ejecución.
• Un planificador divide una solicitud complicada en una lista de verificación de tareas vinculadas a los parámetros objetivo.
• Un ejecutor elige la herramienta MCP para cada tarea, reúne los argumentos (incluidos los filtros OData) e itera con la capa de herramientas hasta que la tarea se completa o se agotan los intentos.
• Un sintetizador combina la salida de cada tarea, tanto los datos reales como los fragmentos de código de respaldo, en una sola respuesta.

3. Un bucle que repara su propio OData

Los modelos tienden a inventar opciones de consulta o a distorsionar la sintaxis al encontrarse con un lenguaje de filtros estructurado como OData. El equipo eligió OData porque permite consultas flexibles de coincidencia parcial sobre objetos de movilidad complejos sin tener que codificar a mano cada combinación, pero esa flexibilidad genera errores, por lo que se añadió un bucle de reparación de múltiples capas.

Si un analizador de preflight detecta un problema de sintaxis, o una llamada en tiempo real devuelve un error de API, el grafo captura el evento, incrementa un contador de intentos por tarea y envía el mensaje de error exacto de vuelta al contexto del modelo. El ejecutor lee su propio fallo y genera una llamada corregida. Cuando se agotan los intentos, la tarea vuelve al modo asesor para que el usuario siga obteniendo algo útil.

4. Memoria dividida en artefactos

Al enviar una gran carga JSON, por ejemplo miles de registros de activos, a la conversación, se agota rápidamente el presupuesto de tokens, se afecta la precisión del razonamiento y aumentan los costos. Por eso, las respuestas en bruto permanecen en un almacén de artefactos backend aislado, y al modelo solo se le muestra metadata de resumen breve que indica los IDs de los artefactos. Las preguntas posteriores acceden a elementos específicos buscando esos IDs en la capa de aplicación, lo que mantiene el contexto del modelo pequeño y enfocado.

Medición de la calidad

Para cambiar un prompt o un modelo sin que se produzcan regresiones, se necesita un punto de referencia automatizado. El flujo de trabajo del equipo utiliza un LLM como juez y responde a una pregunta por cada cambio: ¿es mejor o peor que antes?

El conjunto de datos es un conjunto de casos de prueba creado manualmente en cuatro categorías: generación de código, conocimiento factual, razonamiento y seguridad. Cada caso cuenta con una rúbrica de calificación explícita y no solo una pregunta, por lo que el evaluador califica el contenido de la respuesta en lugar de buscar una cadena esperada rígida. El evaluador es siempre un modelo diferente al que se está probando y otorga una puntuación en una escala de tres puntos: 10 para correcto, 5 para parcial y 0 para incorrecto. Cada ejecución agrega una fila a un archivo de historial etiquetado con el commit de git, el modelo probado, el modelo evaluador, el hash de OpenAPI, el hash del conjunto de datos y la versión de la instrucción, de modo que cualquier puntuación permite rastrear hasta el código, las especificaciones y la instrucción exactos que la generaron.

Según el equipo, el asistente obtiene en promedio unos 9.4 de 10 según esta escala en cada ejecución, y esa cifra sirve como punto de referencia a defender antes de implementar cambios. Sin embargo, la precisión no es el único criterio. Cada ejecución también registra la latencia, para mantener una experiencia ágil, y el uso de tokens, que se relaciona directamente con el consumo del modelo. Cualquier cambio que empeore uno de estos aspectos es marcado antes del lanzamiento.

Proteger el presupuesto y la capacidad

Un asistente siempre activo que accede a una API de producción necesita límites que protejan tanto el presupuesto del modelo como los servicios subyacentes. Existen tres niveles de control:

• Cuotas por usuario. Las cuentas de demostración permiten enviar 10 mensajes al día, lo que permite a los socios curiosos probarlo sin un consumo ilimitado del modelo y los orienta hacia una cuenta de socio cuando desean utilizarlo en trabajos reales.
• Llamadas con alcance definido y atribuibles. El tráfico de los socios se ejecuta con sus propias credenciales, por lo que cada llamada se cuenta dentro de su cuota y aparece en su propio registro de auditoría. El asistente nunca se hace pasar por una cuenta de servicio compartida, lo que permite atribuir el uso y detectar abusos.
• Reintentos que comprenden los fallos. Cuando una solicitud falla, incluyendo una respuesta de limitación temporal, el bucle de reparación devuelve el error al modelo, incrementa el contador de reintentos y vuelve a planificarlos hasta alcanzar el máximo configurado. Cuando se agotan los reintentos, se pasa al modo de asesor.

Facilitar el acceso

Desarrollar el asistente fue solo la mitad del trabajo. Un acceso seguro y sin complicaciones era igual de importante.

Las API de la plataforma solían utilizar credenciales de cliente estándar, lo que significaba tener que configurar manualmente a cada nuevo cliente. Para un asistente dirigido a socios externos, la opción de “presentar una solicitud y esperar la aprobación del equipo técnico” no era aceptable. Pedir a los desarrolladores que pegaran tokens en el chat tampoco era una solución, ya que hacía imposible distinguir las llamadas generadas por el asistente de las manuales, además de dificultar la atribución del uso y la supervisión de la seguridad. El equipo necesitaba una estrategia que sirviera a dos tipos de usuarios: socios que querían un entorno de pruebas sin complicaciones y aquellos listos para utilizar datos en tiempo real, sin necesidad de solicitudes de configuración manual intermedias.

La solución fue un modelo de autoservicio en dos niveles, además del inicio de sesión habitual para desarrolladores.

• Modo de demostración es el predeterminado. Los nuevos usuarios pueden comunicarse con el asistente mediante datos sintéticos de inmediato, sin necesidad de configuración, espera ni solicitudes.
• Modo socio se activa cuando un desarrollador desea una integración en tiempo real. Las credenciales provienen de un flujo de autorización automático y único vinculado a la cuenta y permisos del propio desarrollador. Después de conectarse, cada solicitud está asociada a esa identidad y es completamente rastreable, por lo que queda claro quién realiza la llamada y por qué vía.

Eso eliminó el principal cuello de botella en el proceso de incorporación. Pasar de “Tengo curiosidad” a “Estoy integrando” ya no implica esperar en una cola de ingeniería.

Próximos pasos

El proyecto comenzó como un experimento interno y ahora es una versión beta que acorta el tiempo de integración para los equipos de desarrolladores corporativos. Funciona en el portal de desarrolladores y ya ha incorporado a su primer grupo de socios.

El orquestador lee esquemas OpenAPI estándar, por lo que la arquitectura está diseñada para escalar horizontalmente. Los esfuerzos actuales se centran en validar en profundidad dentro del dominio de la movilidad, pero el núcleo de enrutamiento es intencionalmente genérico. La hoja de ruta incluye llevar la misma capa de conversación a otras divisiones, como las plataformas de pagos corporativos y beneficios, agregar una validación OData más detallada y determinista para evitar que más consultas defectuosas salgan del asistente, y explorar la confirmación humana en las operaciones de escritura para que el asistente pueda, con el tiempo, ayudar también a modificar flujos de trabajo de manera segura.

Leer más

• De Prototipo a Producción: IA Agente con LangChain, LangGraph y Azure — Búsqueda híbrida, cachés de incrustación, enrutamiento con LangGraph, interruptores de circuito, pruebas de regresión con conjunto de datos de referencia y seguimiento para un agente de documentos fiscales, con resultados reportados.
• Gráficos de conocimiento para IA Agente: Cuatro patrones que van más allá del RAG vectorial — La búsqueda vectorial encuentra texto similar, no hechos conectados. Cuatro patrones de gráficos para agentes: estimulación basada en datos reales, planificación, validación de ejecución y autocorrección.

Cómo ejecuta LangGraph un gráfico: desde graph.invoke() hasta el bucle Pregel — Un análisis a nivel de código de graph.invoke, stream, SyncPregelLoop, tick, preparación de tareas y run_with_retry, además de un ejemplo paralelo ilustrativo basado en versiones de canal.