Agent Lightning: entrenar agentes con refuerzo sin reescribirlos

Tienes un agente en producción, funciona razonablemente bien y se equivoca siempre en el mismo tipo de tarea. Alguien te ha comentado que el aprendizaje por refuerzo lo arreglaría, y tu respuesta sensata ha sido que no vas a reescribir el agente para comprobarlo. Agent Lightning, el marco que Microsoft Research llevó a la versión 1.0 el 17 de agosto de 2026, existe precisamente para esa objeción.

Puntos clave

• Agent Lightning entrena por refuerzo el modelo que hay detrás del agente sin tocar sus herramientas, su contexto ni su flujo de control.
• El único cambio en el agente es a dónde apunta su cliente de OpenAI: al proxy de Agent Lightning en lugar de al modelo.
• La versión 1.0 es una reescritura completa, con licencia MIT, unas 3.500 líneas de Python y un modo que ejecuta cada rollout como un Job de Kubernetes.
• El resultado que publican: Qwen3.5-9B pasa de 41,8% a 56,4% en SWE-bench Verified con 6.000 ejemplos de entrenamiento.
• La fontanería sale gratis. La función de recompensa la escribes tú, y ahí está el trabajo real.

Qué problema resuelve Agent Lightning

Entrenar por refuerzo un agente siempre ha exigido meter el agente dentro del bucle de entrenamiento. El motor de RL quería ser el dueño de la interacción con el entorno, así que había que reescribir el agente en los términos del motor. Sus herramientas, su gestión de contexto y sus reintentos pasaban a vivir en el código de entrenamiento. Lo que se acababa entrenando era una versión simplificada del agente, no el que tienes desplegado.

Agent Lightning invierte esa relación. El agente sigue siendo el dueño del bucle, con el mismo arnés que usas en producción, y el entrenador se limita a observar. Como resume el propio equipo en las notas de la versión 1.0: "Agents interact with the model through the Agent Lightning v1.0 proxy with ZERO changes, while keeping tools, context, control flow, and environments in the loop". Esa frase es toda la propuesta de valor, y por eso el resto del diseño gira alrededor de un proxy.

El proyecto nació en el repositorio de Microsoft en junio de 2025 y hoy acumula 17.917 estrellas y 1.573 bifurcaciones. La primera versión llegó en agosto de 2025; la 1.0.0 se publicó el 17 de agosto de 2026 y la 1.0.1, la estable actual, una semana después.

Cómo funciona la interposición del proxy

El sistema tiene tres piezas. Una pasarela de API que guarda los rollouts, los endpoints de modelo y los eventos, y que además hace de proxy compatible con OpenAI. Un controlador de rollouts que lanza cada ejecución del agente como subproceso local o como Job de Kubernetes. Y un entrenador construido sobre verl y vLLM que convierte lo grabado en actualizaciones de la política.

El truco está en la URL. El agente no habla con el modelo: habla con una dirección de la pasarela que lleva dentro el identificador del rollout.

POST /proxy/rollout/{rollout_id}/attempt/{attempt_id}/mode/train/openai/v1/chat/completions

Como el identificador viaja en la ruta, cada llamada al modelo queda asociada a su ejecución sin que el agente lleve ninguna contabilidad. La pasarela reenvía la petición al endpoint registrado y graba los identificadores de token del prompt, los de la respuesta y las probabilidades logarítmicas del token elegido.

Leyendo server/proxy.py se ven dos detalles que la documentación no destaca: el proxy reescribe la temperatura (1 en entrenamiento, 0,7 en validación) y añade return_token_ids. Así el entrenador recibe los tokens exactos que produjo el modelo y no una retokenización aproximada. Además, calcula un hash SHA-256 del identificador de rollout para fijar cada ejecución a un mismo servidor de inferencia y reutilizar la caché de prefijos.

Del lado del agente, todo esto se reduce a dos líneas. En el ejemplo de Calc-X que incluye el repositorio, un agente de AutoGen con herramientas MCP se conecta así:

model_client = OpenAIChatCompletionClient(
    model="auto",
    base_url=os.environ["AGL_OPENAI_BASE_URL"],
    api_key=agl_key,
)

Qué significa entrenamiento por refuerzo con arnés

El informe técnico de la versión 1.0 llama a este planteamiento harnessed agentic RL, y lo define sin ambigüedad. El arnés que usas al desplegar participa directamente en el post-entrenamiento del modelo. Es el arnés, y no el motor de entrenamiento, quien controla el bucle de interacción con el entorno, mientras el entrenador solo ve secuencias de pares petición-respuesta.

La diferencia con reentrenar el modelo a secas es de sujeto. Un ajuste fino clásico optimiza el modelo contra un conjunto de datos. Aquí se optimiza el modelo contra el comportamiento del sistema completo.

Si tu agente reintenta tres veces, resume el contexto a la mitad y llama a cuatro herramientas, el modelo aprende a jugar en ese entorno concreto. Eso también implica que un cambio en el arnés invalida parte de lo aprendido.

El precio de esta arquitectura son problemas nuevos que los autores enumeran con honestidad: retokenización, fusión de muestras, cálculo de ventajas, normalización de la pérdida y planificación del backend. El entrenador solo fusiona llamadas consecutivas cuando sus historiales de tokens son exactamente continuos, y calcula las ventajas para el rollout completo, no llamada a llamada.

Qué cambió en la versión 1.0

La 1.0 no es una versión incremental: el repositorio avisa de que las versiones anteriores viven en una rama v0.x aparte. Los cambios que importan son tres.

El primero es el tamaño. La portada del repositorio se presenta como un marco de 3.500 líneas. Lo he medido sobre un clon de main: el paquete agentlightning son 27 ficheros Python, 4.771 líneas físicas y 3.835 sin contar líneas en blanco ni comentarios. La cifra redonda del titular se sostiene, y para un marco de RL sigue siendo diminuto.

El segundo es Kubernetes. El controlador puede crear un Job por rollout a partir de una plantilla Jinja2 que aportas tú, con nombres deterministas del tipo agl-rollout-<id> y la etiqueta app.kubernetes.io/managed-by=agentlightning. Sirve para aislar dependencias del agente y para ejecutar rollouts en paralelo sobre un clúster propio, en lugar de depender de un servicio comercial de sandbox.

El tercero es el ejemplo completo de agente de programación, con su pipeline de datos, sus defensas contra el reward hacking y sus scripts. Es el que sostiene la cifra del titular.

Qué hace falta de verdad para ejecutarlo

Aquí conviene bajar de la nota de prensa al hardware. La guía rápida y el ejemplo del agente de programación describen dos mundos distintos:

La instalación tampoco es indolora. Requiere CUDA 12.9 o 13.0 y una combinación fijada de verl y vLLM (verl 0.8.0 con vLLM 0.20.2, o verl 0.7.1 con vLLM 0.12.0). También una compilación de flash-attn 2.8.3 desde el código fuente, que la propia documentación cifra en 10 a 30 minutos según los núcleos disponibles. El modelo, además, tiene que ser de pesos abiertos y servido por ti: no hay forma de entrenar por refuerzo un endpoint cerrado de un proveedor.

Por qué la recompensa es la parte difícil

Esta es la parte que las notas de prensa se saltan. El marco te da un endpoint de eventos; la función que decide si una ejecución fue buena la escribes tú. En el ejemplo de Calc-X, el agente termina con una comparación numérica y un único envío:

httpx.post(
    event_url,
    json={"event_type": "reward", "data": {"value": reward}},
    headers={"Authorization": f"Bearer {agl_key}"},
).raise_for_status()

Es decir: el "cero cambios" es exacto para el arnés y falso para la recompensa. Sigue habiendo una línea que añadir, y detrás de esa línea, la decisión más delicada del proyecto.

Cuando la recompensa es endeble, el agente aprende a explotarla. La documentación del agente de programación lo trata como un riesgo de primer orden. Antes de arrancar, el arnés saca el directorio .git fuera del área visible y bloquea los comandos que invocan Git, instalan paquetes, descargan ficheros o modifican el conjunto de tests.

Y sobre la red, la recomendación es explícita: "we strongly recommend adding a Kubernetes network policy that denies all outbound traffic from agent pods except connections to the AGL Gateway. Without this restriction, an agent may retrieve upstream source code or other external information and obtain reward without solving the task as intended".

Preparar los datos tampoco es trivial. Para llegar a los 6.000 ejemplos del titular partieron de las 59.136 tareas ejecutables de SWE-smith sobre 128 repositorios de Python. Quitaron 18.033 sin enunciado y 1.265 con la rama ausente, y descartaron las que necesitaban más de 200 tests.

Probaron cada candidata cuatro veces con el modelo base y se quedaron con las de dificultad mixta, más mil imposibles para no sesgar el conjunto. Ese trabajo, y no la instalación, es el coste real del método.

Si aún no mides lo que hace tu agente, empieza por ahí y no por el refuerzo. Una batería de evaluación con DeepEval o promptfoo y trazas en Langfuse son los que te dicen si la recompensa que has escrito mide lo que crees que mide.

Con qué marcos de agentes funciona

La respuesta corta de la versión 1.0 es incómoda de comercializar y cómoda de usar: con cualquiera que acepte una base_url personalizada en su cliente compatible con OpenAI. El README de la 1.0 ya no publica una lista de marcos compatibles, porque el contrato no es el marco sino la API de Chat Completions.

Los ejemplos incluidos usan AutoGen con herramientas MCP y el cliente openai a secas. El artículo original de 2025, que describía el diseño anterior, sí nombraba LangChain, el SDK de Agents de OpenAI, AutoGen y agentes escritos desde cero. Si tu agente habla con el modelo a través de un cliente donde puedes cambiar la URL base, entra. Si tu agente incrusta la llamada al modelo dentro de un servicio que no te deja tocar esa URL, no.

Conviene añadir que la idea ya no es exclusiva. El propio resumen de la 1.0 reconoce que la arquitectura desagregada que introdujeron ha sido adoptada por verl Uni-Agent, AReaL 2.0, slime y Polar.

Cuándo el refuerzo no es la herramienta

Casi nunca es lo primero que hay que probar. Antes de montar un clúster con cuatro B200:

1. Escribe la evaluación. Si no puedes puntuar una ejecución de forma automática y fiable, tampoco puedes entrenarla.
2. Prueba con mejores instrucciones y ejemplos en el prompt. Es gratis, es reversible y suele bastar para los fallos de formato y de criterio.
3. Prueba con un modelo mayor. Suele salir más barato que una campaña de entrenamiento.
4. Prueba con ajuste fino supervisado sobre trayectorias buenas. Necesita demostraciones, no una función de puntuación, y es mucho más estable.
5. Comprueba que el fallo es del modelo. Si tu agente se cae por tiempos de espera o por reintentos mal gestionados, lo que necesitas es ejecución duradera con Temporal, no aprendizaje por refuerzo.

El refuerzo compensa cuando el fallo es de política, tienes suficientes ejemplos con una señal automática y verificable, el modelo es de pesos abiertos y dispones de GPU. Fuera de esa intersección, el resto de la lista rinde más por euro invertido.

Preguntas frecuentes

¿Puedo entrenar con Agent Lightning un modelo de un proveedor cerrado?

No. El entrenador actualiza una política servida por vLLM sobre verl, así que el modelo tiene que ser de pesos abiertos y ejecutarse en tu propio hardware. Con un endpoint cerrado puedes usar el proxy para observar, pero no para entrenar.

¿Es cierto que no hay que cambiar nada en el agente?

Casi. Cambias la URL base y la clave de su cliente de modelo, y añades un envío de la recompensa al final de la ejecución. Herramientas, contexto, reintentos y flujo de control se quedan como estaban.

¿Necesito Kubernetes para probarlo?

No. El controlador tiene un modo local que lanza cada rollout como un subproceso, y el ejemplo de inicio rápido cabe en una sola máquina con una A100. Kubernetes entra cuando quieres aislar dependencias y ejecutar rollouts en paralelo.

Conclusión

Agent Lightning resuelve bien un problema concreto y acotado: quitar de en medio la reescritura que hasta ahora hacía inviable probar aprendizaje por refuerzo sobre un agente que ya funciona. El proxy es una idea limpia, las 3.500 líneas son verificables y el modo Kubernetes convierte los rollouts en algo que tu clúster ya sabe planificar.

Lo que no resuelve, ni pretende, es la pregunta de qué significa que una ejecución haya salido bien. Esa sigue siendo tuya, y sigue siendo la razón por la que a un equipo le compensa desplegar bien su agente y medirlo antes de comprar GPU. La versión en inglés de este artículo está en Agent Lightning: reinforcement learning for agents.

Fuentes

1. Agent Lightning v1.0: Towards Harnessed Agentic RL, informe técnico
2. microsoft/agent-lightning, notas de la versión 1.0.0
3. Agent Lightning, documentación de componentes y rollouts
4. Agent Lightning, ejemplo del agente de programación
5. Agent Lightning: Train ANY AI Agents with Reinforcement Learning
6. Microsoft Research, aprendizaje por refuerzo sin reescribir el agente