Hands-On Labs

Los labs convierten los capítulos de referencia en una ruta de construcción. Cada lab utiliza código que ya existe en este repositorio, así que puedes leer el pattern, ejecutar el ejemplo, cambiar una cosa y conectar el resultado con el diseño de producción.

Los labs son intencionalmente agnósticos al framework. Se mueven entre TypeScript y Python, y abarcan runtimes personalizados mínimos, recuperación al estilo LangChain/LangGraph, ejemplos de manager/worker al estilo AutoGen, código de protocolo A2A, límites de tool al estilo MCP y pruebas neutrales al framework. El objetivo no es enseñar una API específica. El objetivo es mostrar la arquitectura que sobrevive cuando el framework cambia.

Usa Lab Framework and Language Matrix antes de comenzar si quieres ver qué lenguaje, framework y límite arquitectónico enfatiza cada lab. Usa Lab Production Readiness Checklist y la lab production readiness worksheet después de cada lab para identificar qué le falta al demo antes de producción. Usa From-Scratch Mini-Framework Track cuando quieras entender qué empaquetan los agent frameworks bajo el capó. Usa Vertical Slice Examples después de los labs, o cuando quieras ver varios patterns compuestos en una task realista. Usa Capstone Projects cuando quieras ejemplos con forma de producto que incluyan ADRs, traces, evals, runbooks, planes de rollback y slices nativos de framework.

Ejecuta estos comandos desde la raíz del repositorio antes de comenzar:

npm install
npm test
npm run typecheck

Algunos ejemplos pueden ejecutarse con fallbacks deterministas. Los ejemplos que llaman modelos en vivo requieren un archivo .env con MISTRAL_API_KEY.

Lab Progression Map

Usa este mapa para entender por qué los labs están ordenados de esta manera. La secuencia inicia con primitivas deterministas, expone el mini-framework debajo de los agent runtimes, compara slices nativos de framework y luego avanza hacia evidencia de lanzamiento a nivel capstone.

Lab Standard

Cada lab debe dejarte con tres cosas: un ejemplo ejecutable, un límite de diseño específico que puedas explicar y un paso de robustecimiento hacia producción que sepas cómo realizar.

Cada lab sigue el mismo contrato de aprendizaje:

1. Indicar el objetivo.
2. Nombrar el lenguaje, framework y archivos fuente.
3. Ejecutar un comando base.
4. Inspeccionar el límite del código.
5. Cambiar una cosa.
6. Verificar el resultado.
7. Identificar qué necesitaría producción a continuación.

Los ejemplos se mantienen pequeños a propósito. Un ejemplo pequeño solo es útil cuando el lab también indica qué falta intencionalmente: state durable, enforcement de policy, schemas más robustos, aprobación, tracing, evals, despliegue o integración con framework. Cuando existe un slice nativo de framework, trátalo como el siguiente punto de comparación, no como un reemplazo del lab determinista.

Planning Table

Usa esta tabla para elegir un lab según el esfuerzo y el resultado. Las estimaciones de tiempo asumen que ya puedes ejecutar las pruebas del repositorio. Cada página de lab también incluye bloques de tiempo opcionales por ejercicio para que puedas dividir el trabajo en sesiones más cortas.

Descarga la worksheet reutilizable: lab completion worksheet.

Descarga la worksheet de seguimiento para producción: lab production readiness worksheet.

Para los labs de mayor impacto, usa las worksheets enfocadas para Lab 02 planning loops, Lab 03 Agentic RAG, Lab 06 observability and evals, Lab 07 runtime packaging y Lab 12 state graphs.

Compara tu worksheet terminada con los completed lab evidence examples antes de considerar el lab listo para revisión.

Usa los captured lab and capstone command output examples cuando necesites un modelo concreto para salida de comandos guardada, snapshots de trace, snapshots de eval y evidencia de lanzamiento.

Completion Standard

Un lab está completo cuando puedes mostrar cuatro cosas:

1. El comando base se ejecuta.
2. La salida esperada coincide con la señal de éxito del lab.
3. Un camino de falla intencional es visible y controlado.
4. Puedes nombrar la brecha de producción antes de usar el pattern con usuarios reales, datos, credenciales o efectos secundarios.

No cuentes un lab como terminado solo porque el camino feliz funciona. El valor viene de ver el límite: qué puede decidir el model, qué debe hacer cumplir el software, qué se traza y qué bloquearía la producción.

Paquete de Evidencia del Lab

Guarda un pequeño paquete de evidencia después de cada lab. Esto convierte el lab de un ejercicio de una sola vez en material que puedes reutilizar en una revisión de diseño, ADR, eval suite o capstone.

Mantén el paquete corto. Una pantalla de evidencia es mejor que una carpeta llena de capturas de pantalla sin revisar.

Usa los ejemplos de evidencia de labs completados como calibración. Un buen paquete de evidencia nombra el comando, salida, failure path, boundary protegido, production gap y el siguiente owner.

Usa los ejemplos de salida de comando capturada para comparar la forma de tu salida de terminal guardada. La señal importante no es una captura de pantalla. Es un registro corto y revisable que muestra el comando, señal de éxito, trace o enlace a eval, y la pregunta de producción.

Regla Agnóstica de Framework

Los frameworks cambian la API, no las preguntas de arquitectura. Para cada lab, pregunta:

• ¿Quién posee el state?
• ¿Qué puede decidir el model?
• ¿Qué puede validar el software?
• ¿Qué tools están expuestas?
• ¿Qué policy se aplica fuera del prompt?
• ¿Qué se traza?
• ¿Por qué se detiene la ejecución?

Estas preguntas aplican tanto si el código usa LangGraph, LangChain, Mastra AI, agentes estilo AutoGen, CrewAI, MCP, A2A o un runtime personalizado pequeño.

Ruta de Lectura End-To-End

Usa esta ruta cuando quieras pasar de aprender a implementar:

1. Comienza con Lab Framework and Language Matrix y elige el boundary de mayor riesgo.
2. Ejecuta el lab determinista correspondiente.
3. Lee la extensión de producción y la checklist de preparación.
4. Compara el ejemplo nativo correspondiente bajo native-framework-examples/.
5. Mapea el mismo comportamiento a un capstone.
6. Llena el ADR de selección de framework y la hoja de rollback.
7. Agrega evals que fallen el build antes de agregar tools con efectos secundarios reales.

Para la ruta de reembolso de soporte, usa el Lab 07, native-framework-examples/mastra-refund/, el capstone Support Refund Agent y la hoja de preparación para producción.

Secuencia de Labs

1. Lab Framework and Language Matrix
2. Lab Production Readiness Checklist
3. Build a Tool-Using Agent
4. Build an Agent Loop with Planning
5. Build Agentic RAG
6. Build A2A Agent Communication
7. Build a Multi-Agent Supervisor
8. Add Observability and Evals
9. Package Agents, Tools, Workflows, Memory, and Evals
10. Model Flows, Crews, Roles, and Task Contracts
11. Study the From-Scratch Mini-Framework Track
12. Build a Minimal Agent Loop
13. Build a Tool Registry and Policy Gate
14. Add Context, Memory, Trace, and Evals
15. Model State Graphs, Checkpoints, and Interrupts
16. Evaluate Multi-Agent Transcripts
17. Study Vertical Slice Examples

Cómo Usar Estos Labs

Lee primero el objetivo, luego ejecuta el comando exactamente como se muestra. Después, inspecciona los archivos fuente nombrados y haz el small change en el lab. El objetivo es ver dónde el pattern se convierte en código: contratos de input, state, límites de tool, condiciones de stop, evaluación y manejo de fallas.

Cada lab termina con una extensión de producción. Trata esa sección como el puente entre un demo funcional y una decisión de arquitectura.

Mapa de Salida Esperada

Usa esta tabla como verificación rápida de éxito antes de pasar a la extensión de producción.

Orden Recomendado

Haz los labs en orden si eres nuevo en agent systems. La secuencia comienza con un agent y un tool, luego agrega planeación, retrieval, comunicación remota entre agents, coordinación multi-agent y evaluación de calidad de producción.

Si ya conoces lo básico, comienza con el lab más cercano a tu sistema actual y usa los capítulos relacionados como material de referencia.

Después de los labs, lee los vertical slices para ver cómo los mismos patterns se componen en workflows de soporte, código e investigación. Luego lee los Capstone Projects para ver sistemas con forma de producción, mapeos de framework, slices nativos y evidencia de release.

Si estás evaluando frameworks, haz el track de mini-framework antes de elegir un runtime de producción. Construir los primitivos una vez facilita ver qué responsabilidades posee un framework y cuáles permanecen en tu aplicación.