Laboratorio de agentes: escribe el bucle de un agente de IA con herramientas, con un modelo sustituto

Este laboratorio da a cada alumno un agente de IA escrito a mano en Python para leerlo, ejecutarlo y cambiarlo: el bucle que manda una conversación y una lista de herramientas a un modelo de lenguaje, ejecuta la herramienta que pide el modelo y le devuelve lo que salió. Aprenden esquemas de herramientas, cuándo parar y el límite de pasos, errores y reintentos, memoria, cómo repartir una tarea en varios turnos, salvaguardas y una traza que se puntúa.

El modelo es un sustituto, y el laboratorio lo dice en todas partes: contesta con el mismo formato que la API de un modelo real, pero elige cada respuesta según reglas fijas y llama a una sola herramienta por turno, así que la misma pregunta recibe siempre la misma respuesta. No se descarga nada, no se llama a ningún servicio de IA y nada cuesta dinero. Las herramientas también son de mentira y trabajan con datos fijos, y ninguna copia tiene salida a internet ni acceso a la de otro alumno.

Qué aprenden los alumnos

Qué hay debajo de un agente. Ven que el modelo contesta con una llamada a una herramienta en vez de con palabras, ejecutan ellos la herramienta y devuelven "Rain, 9 C". Siguen el bucle durante cinco turnos que comparten 17 mensajes, ven cómo el límite de pasos para a los 3 pasos a un modelo obligado a llamar herramientas, y hacen un plan de tres pasos en tres turnos. Una herramienta que falla vuelve en forma de palabras, y a un modelo saturado se le vuelve a preguntar tras una pausa cada vez más larga. Ven cómo una lista de permitidas rechaza un borrado, y cómo una orden escondida en un correo solo se obedece cuando el programa la pega como si fueran palabras del usuario. Por último, se registra una traza y cuatro casos de prueba puntúan al agente: aprueban 3 de 4. Sirve para un curso de desarrollo de software o de IA aplicada; consulta en la unidad de tu propio organismo certificador la redacción exacta, aquí no se cita ninguna.

En qué se diferencia de los laboratorios de agentes de programación

Los laboratorios de agentes de programación con IA le dan al alumno un agente ya hecho, opencode, para trabajar con él en un programa. Este laboratorio es la otra cara: el alumno lee y cambia el propio agente, unas 120 líneas de Python, así que el bucle, las herramientas y las salvaguardas son código que puede ver. El banco de pruebas LLM, centrado solo en la API del modelo, es un buen laboratorio para hacer antes.

Ejecútalo en el navegador

El laboratorio inicia dos servicios. model es el sustituto, que contesta en http://model:4000/v1 dentro del laboratorio. tools es un Python con agent.py, el bucle del agente y sus herramientas de mentira, llm.py, un cliente pequeño, y steps/, scripts cortos que muestran una idea cada uno. La terminal de al lado tiene curl y no tiene Python, así que llega a los scripts con docker exec tools.

  1. Abre la página Contenedor. Abre «Crear» en la barra y elige «Ejecutar un contenedor». Cualquiera puede abrir la página, y el laboratorio de Git y el de SQL se inician sin cuenta. Todos los demás laboratorios necesitan una cuenta gratuita: crea una, inicia sesión y pulsa «Iniciar».
  2. Busca el laboratorio. La tarjeta «Laboratorios de ejemplo» lista todos los ejemplos. Busca Laboratorio de agentes: escribe el bucle de un agente de IA con herramientas.
  3. Pulsa «Iniciar». «Iniciar» lo ejecuta tal cual, con una sola pulsación. «Editar el archivo primero» abre el archivo compose para que lo cambies antes de iniciarlo.
  4. Ábrelo. En la página del laboratorio, pulsa «Abrir el terminal» y escribe docker exec tools python3 steps/onecall.py para ver una llamada a una herramienta hecha a mano. Luego escribe docker exec tools python3 steps/loop.py para ver el bucle.

Qué pedir a los alumnos que entreguen

agent.py con un cambio hecho por ellos: una herramienta nueva con su esquema, una lista de permitidas más estricta u otro caso de prueba en steps/trace.py. Junto con él, la salida del paso que muestra el cambio y una frase sobre lo que podría hacer distinto un modelo real. Nada se califica solo: la frase muestra si lo entendieron.

Una lección básica en este laboratorio

Agent Loop Basics (Fundamentos del bucle de un agente) es una lección pequeña que se hace en este laboratorio. En ella el alumno ve una llamada a una herramienta tal como viaja, hace una a mano, sigue el bucle y su límite de pasos, reparte un plan en varios turnos, gestiona errores, prueba las salvaguardas y puntúa una traza.

Las cuentas personales gratuitas la tienen en el módulo Basics, que está en Inicio, y cualquier centro puede copiarla desde la carpeta Basics de la Biblioteca. Es pequeña a propósito: enseña a un docente qué es una lección hecha en un laboratorio, y el laboratorio hace el resto. Cópiala en un módulo tuyo para cambiarla.

El código en GitHub

El archivo compose no tiene Dockerfile: ejecuta dos veces una sola imagen pública sin cambios, Python 3.12 sobre Alpine, fijada a una etiqueta exacta, cada vez con una cuenta sin privilegios y 64 MB de memoria. La imagen tiene licencia PSF y no la distribuimos nosotros. Al arrancar, el archivo escribe el sustituto, el agente y los scripts a partir de un texto fijo, solo con la biblioteca estándar de Python, así que no se descarga nada. Nada se guarda al detener el laboratorio, así que el alumno copia antes su agent.py.

Ponlo como trabajo

Indica en la tarea qué hay que entregar.

  1. Crea el laboratorio. En tu módulo añade una tarea y elige la tarjeta «Laboratorio de contenedores», y después «En un repositorio de GitHub». Indica https://github.com/mitsurutech/lab-agent-lab con la rama main. El archivo compose es el predeterminado, compose.yaml. Haz un fork del repositorio antes si quieres modificarlo, por ejemplo para darle al agente una herramienta tuya.
  2. Publica y pruébalo. «Publicar» fija el commit que te mostraron, así que un cambio posterior en el repositorio no altera un laboratorio que ya has asignado. Inicia primero tu propia copia.
  3. Asígnalo. Asígnalo como cualquier tarea, con una fecha de entrega si quieres, e indica en la tarea qué hacer y qué entregar.
  4. Califica lo entregado. Abre la copia de un alumno y el trabajo que ha entregado, califícalo y devuélvelo con un motivo si necesita más.

Prueba este laboratorio, y lo que cuesta

Con una cuenta personal gratuita puedes seguir las lecciones básicas de este laboratorio, con crédito gratuito suficiente cada mes para seguir la mayoría de las lecciones y sin tarjeta. Para una clase, un centro tiene gratis sus primeros 365 días, hasta 50 alumnos, y después paga por alumno y año, con todos los laboratorios incluidos y el profesorado gratis.

Preguntas frecuentes

¿Hay un modelo de IA de verdad en este laboratorio?
No. El modelo es un sustituto escrito para el laboratorio, un programa corto de Python que elige cada respuesta según reglas fijas. Contesta con el mismo formato que la API de un modelo real, llamadas a herramientas incluidas, así que el bucle que escriben los alumnos funciona igual con uno real. A la misma pregunta da siempre la misma respuesta, y eso permite que la lección diga qué verá el alumno.
¿Por qué el agente llama a una sola herramienta cuando la pregunta necesita dos?
El sustituto llama a una herramienta por turno y luego da su respuesta. Un modelo real puede llamar a varias seguidas. El laboratorio lo aprovecha a propósito: un caso de prueba falla por eso, y el paso del plan muestra la solución, darle al agente una tarea grande en varios turnos.
¿Es seguro enseñar la parte de la inyección de instrucciones?
Sí. Se enseña como defensa y con datos de mentira: el buzón es un solo correo fijo y los archivos son un diccionario de Python, así que no se lee ni se borra nada real. Los alumnos ven por qué el resultado de una herramienta tiene que seguir siendo datos y por qué es el código, y no el modelo, quien decide qué herramientas se ejecutan. El sustituto nunca obedece el texto de un resultado, y la lección avisa de que un modelo real podría hacerlo.
¿Cuesta algo o gasta créditos de IA?
No se usa ninguna IA, así que no se cobra nada por ella. El laboratorio funciona como cualquier otro laboratorio de contenedores.
¿Por qué la terminal usa docker exec tools?
La terminal del laboratorio trae unos pocos clientes, entre ellos curl, y nada de Python. docker exec tools ejecuta una orden dentro del contenedor de Python del laboratorio, donde están el agente y los scripts.