Workshop de Langfuse: el ciclo de ingeniería de IA, de extremo a extremo
Un workshop paso a paso de Langfuse basado en una pequeña aplicación TypeScript: Dad IT Support Agent. Recorre todo el ciclo de ingeniería de IA con Langfuse...
El material del workshop se mantiene en el repositorio público langfuse/langfuse-workshop. Usa el repositorio para ejecutar la aplicación, acceder a las ramas de checkpoint y realizar la configuración local.
Este es un workshop paso a paso de Langfuse basado en una pequeña aplicación TypeScript: Dad IT Support Agent. Recorre todo el ciclo de ingeniería de IA con Langfuse: tracing, gestión de prompts, monitorización, datasets, experimentos y evaluación.
Puedes completar el workshop por tu cuenta con las lecciones para participantes o utilizar las notas para instructores para enseñar el mismo contenido a un grupo.
Para participantes
Empieza con las lecciones de docs/learner/. Cada una indica qué checkpoint usar, qué cambiar en el código o configurar en Langfuse y cómo verificar el resultado.
Sigue este recorrido si quieres:
- Registrar tu primer trace desde una aplicación LLM real y entender el resultado.
- Llevar un prompt a Langfuse para versionar los cambios y vincularlos con los traces.
- Monitorizar el comportamiento en producción sin leer cada trace a mano.
- Crear un dataset, ejecutar experimentos y evaluar cambios con evidencia.
- Examinar una implementación de referencia completa en TypeScript cuyos patrones puedas reutilizar.
No hace falta un instructor. Las lecciones son lo bastante completas para realizar el workshop de forma autoguiada.
Para instructores
La guía para instructores está dirigida a quienes quieren enseñar Langfuse. Usa las notas de docs/instructor/ junto con las lecciones cuando impartas un workshop en directo, grabes un recorrido o adaptes el material para un equipo.
Para prepararte, incluimos una guía y diapositivas en docs/preparation_and_materials/.
El workshop no depende de un instructor. Las notas añaden puntos didácticos, ritmo de demostración, recordatorios de preparación y problemas habituales; no son necesarias para quien lo realiza en solitario.
Alcance del workshop
La aplicación de ejemplo es un pequeño chat web donde el padre pide ayuda con su iPhone. El agente se llama Specs y responde con instrucciones paso a paso. Por debajo, es un bucle normal de llamadas a herramientas de OpenAI con dos herramientas locales.
main contiene la aplicación de referencia completa y la documentación actual del workshop. Úsalo para examinar la implementación terminada o comparar tu trabajo con el estado final. Los ejercicios comienzan en tags de checkpoint.
Módulos
| Paso | Lección del participante | Notas del instructor | Checkpoint | Qué aprenderás |
|---|---|---|---|---|
| 00 | Configuración | Notas del instructor | checkpoint/00-setup | Claves, instalación y ejecución de la aplicación. |
| 01 | Aplicación base | Notas del instructor | checkpoint/01-base-app | Recorrer la aplicación. Nada que construir. |
| 02 | Tracing | Notas del instructor | checkpoint/02-tracing | Registrar cada paso del agente: generations, raíz y spans de herramientas. |
| 03 | Gestión de prompts | Notas del instructor | checkpoint/03-prompt-management | Llevar el prompt de sistema a Langfuse. |
| 04 | Monitorización | Notas del instructor | checkpoint/04-monitoring | Detectar solicitudes fuera de alcance y desacuerdos del usuario. |
| 05 | Dataset | Notas del instructor | checkpoint/05-dataset | Convertir el alcance del producto en ejemplos reutilizables. |
| 06 | Experimentos | Notas del instructor | checkpoint/06-experiments | Ejecutar el agente con el dataset y puntuar cada elemento. |
| 07 | Evaluación | Notas del instructor | checkpoint/07-evaluation | Cambiar una cosa, volver a ejecutar y comparar. |
| 08 | Cierre | Notas del instructor | checkpoint/08-wrap-up | Aplicar el ciclo a tu propia aplicación. |
Cómo recorrer el workshop
main contiene la implementación de referencia completa. Para el trabajo práctico, haz checkout del checkpoint indicado en la lección, realiza los cambios que faltan y verifica el resultado antes de continuar.
checkpoint/00-setup y checkpoint/01-base-app contienen intencionadamente la misma aplicación base sin tracing. Setup usa ese estado para validar claves, dependencias y puertos; Base App lo usa para orientarte. El tracing comienza en 02-tracing.
El servidor y los scripts auxiliares de npm consideran el .env del repositorio la fuente de verdad de Node. Las variables exportadas en el shell por otros proyectos no sustituyen .env; cambia ahí las claves, el host de Langfuse, los labels de prompts y los nombres de datasets.
El workshop es lo bastante breve para completarlo en una sesión y cada módulo también puede usarse por separado si solo te interesa una parte del ciclo.
Estructura del repositorio
docs/learner/contiene las lecciones autoguiadas.docs/instructor/contiene las notas para impartir esas mismas lecciones.docs/images/contiene capturas y diagramas agrupados por lección.src/contiene la aplicación de ejemplo.scripts/contiene scripts auxiliares de datasets y prompts para lecciones posteriores.
Próximos pasos
- Recorre los módulos en orden empezando por
docs/learner/00-setup.md. - Ve al capítulo que corresponda a lo que quieres aprender.
- Instala la skill de Langfuse (
/langfuse) para aplicar estos patrones a tu código. - Para obtener una visión más amplia de cada capítulo, consulta la Langfuse Academy.
08 Has terminado: próximos pasos
Cómo seguir aprovechando la prueba y qué alternativas usar si algo falló durante el recorrido.
Para participantes
Empieza con las lecciones de docs/learner/. Cada lección indica qué checkpoint usar, qué cambiar en el código o configurar en Langfuse y cómo verificar el resultado.