Lab 07 - Empaqueta Agents, Tools, Workflows, Memory y Evals

Descarga la hoja de ejercicios guiados de runtime packaging del Lab 07, la hoja de finalización del laboratorio y la hoja de preparación para producción del laboratorio antes de comenzar.

Objetivo

Usa una estructura de runtime en TypeScript al estilo Mastra para empaquetar las mismas responsabilidades que construiste desde cero: decisión del agent, ejecución de tools, control del workflow, memory, eventos de trace y evals.

Qué Vas a Usar

• Lenguaje: TypeScript
• Framework/runtime: runtime packaging estilo Mastra
• Lección agnóstica de framework: un framework puede empaquetar primitivas, pero tu aplicación sigue siendo dueña del state, policy, contratos de tool, traces y criterios de aceptación.
• Capítulos de patrones: Mastra Runtime, Building a Minimal Agent Runtime, Observability and Evals
• Archivos fuente:
  • mastra-runtime-pattern/typescript/src/runtime_packaging.ts
  • mastra-runtime-pattern/typescript/src/run_demo.ts
  • mastra-runtime-pattern/typescript/test/runtime_packaging.spec.ts

Tiempo Estimado del Ejercicio

Estas estimaciones asumen que las dependencias ya están instaladas.

Configuración

Desde la raíz del repositorio:

npm install

Este laboratorio es determinista y no requiere una model key. El objetivo es el runtime packaging, no la calidad del model.

Ejecútalo

npm run mastra-runtime:demo
npm run mastra-runtime:test

Resultado Esperado

El comando de test debe imprimir:

Mastra-style runtime packaging tests OK

La ejecución también debe probar estas señales de comportamiento:

• policy se lee antes de redactar;
• el draft se crea para revisión, no se envía;
• los pasos del workflow y los resultados de tools quedan registrados en traces;
• el eval falla si se usa un tool de envío directo o refund-issue.

El comando demo debe incluir esta evidencia:

{
  "toolCalls": [
    { "name": "read_policy", "input": { "policyId": "refund-v1" } },
    { "name": "draft_response", "input": { "customerId": "cust_123" } }
  ],
  "result": "Policy checked and draft created for human review.",
  "evaluation": {
    "status": "pass"
  }
}

El JSON exacto también incluye los campos de memory y trace. Usa los campos toolCalls, result y evaluation.status como verificación rápida.

Usa este flujo como modelo de aceptación del laboratorio. Un framework puede empaquetar el runtime, pero la aplicación sigue siendo dueña del orden de tools, policy de efectos secundarios, evidencia de trace y evals de release.

Punto de comparación nativo de Mastra:

native-framework-examples/mastra-refund/
download: /downloads/native-mastra-refund.zip
agent: refundDraftAgent
workflow: refundDraftWorkflow
tools: refund_policy.retrieve, refunds.create_draft
eval gate: refund_draft_no_money_movement

Ejercicios Guiados

Usa estos ejercicios para inspeccionar qué posee el runtime package y qué sigue siendo responsabilidad de la policy del producto.

Ejercicio de Deployment y Rollback

Trata el laboratorio como candidato a producción. Antes de lanzar un runtime real, escribe la acción de rollback que deshabilita la capability de mayor riesgo sin eliminar todo el servicio.

Inspecciona el Código

Abre mastra-runtime-pattern/typescript/src/runtime_packaging.ts y encuentra estos límites:

• Agent: posee instrucciones y propone la siguiente decisión.
• Tool: posee la ejecución tipada de capability.
• WorkflowStep: posee la secuencia determinista de runtime.
• RuntimeState: posee memory, traces, llamadas a tools y resultado.
• evaluateRuntime: revisa la trayectoria, no solo el texto final.

El código local es intencionalmente pequeño, pero el mapeo sigue la forma de producción: agents, workflows, tools, memory, traces y evals pertenecen a un solo runtime package.

Cambia Una Cosa

Agrega un nuevo tool llamado send_message con un efecto secundario directo, luego actualiza evaluateRuntime para que el eval falle si ese tool aparece en toolCalls. El test del repositorio también verifica el caso de efecto secundario de refund:

{ name: "refunds.issue_refund", input: { amount: 42 } }

Lección esperada: el registro de tools en el framework no es permiso. La policy de la aplicación sigue decidiendo qué es seguro.

Verifica

Ejecuta:

npm run mastra-runtime:test

Compara la salida con el resultado esperado antes de pasar a la extensión de producción.

Revisión del Laboratorio

Antes de continuar, verifica el runtime package:

Registra la salida del comando, eventos de trace, orden de tools y resultado de eval en la hoja de finalización del laboratorio.

Extensión de Producción

Antes de lanzar una implementación real de Mastra, agrega:

• schemas reales de tools y validación de input;
• policy de retry de workflow y compensación;
• controles de retención, redacción y eliminación de memory;
• fixtures de scorer/eval ligados a release gates;
• export de trace al backend de observability;
• approval gates para tools de escritura y comunicación externa.

Production Bridge

Usa esta tabla cuando adaptes el laboratorio a un Mastra runtime real:

El primer hito de producción es un runtime slice que puede deshabilitarse, reproducirse y evaluarse sin leer los detalles internos del framework.

Native Framework Extension

Después de que el laboratorio determinista pase, porta una vertical slice a un proyecto real de Mastra. Usa Real Framework Setup Notes para los comandos actuales de configuración y compara tu trabajo con el ejemplo del repositorio en native-framework-examples/mastra-refund/.

Pasos para el port nativo:

1. crea un proyecto Mastra;
2. crea un agent para la decisión de borrador de reembolso;
3. crea tools tipados para policy lookup y creación de borrador;
4. crea un workflow que invoque policy lookup antes de la creación del borrador;
5. agrega un eval que falle si se llama a un tool de send o refund-issue;
6. exporta un trace con eventos de workflow, agent, tool, policy y eval;
7. documenta el rollback para deshabilitar el tool de borrador.

Mantén estos assets fuera del código exclusivo del framework:

Estándar de finalización: el proyecto nativo prueba el mismo comportamiento que este laboratorio y enlaza al Support Refund Agent capstone. Una ejecución nativa de Mastra no está completa solo porque un agent responde; el workflow debe preservar el orden de tools, la side-effect policy, la evidencia en trace y los eval gates.

Troubleshooting

Cross-Framework Mapping

• En LangGraph, esto se convierte en graph state, nodes, tools, checkpoints y evals alrededor de ejecuciones del grafo.
• En Mastra AI, estas preocupaciones se empaquetan como agents, workflows, tools, memory, observability y evals.
• En sistemas estilo AutoGen, el runtime package se divide entre manager, workers, functions, messages y transcript evals.
• En CrewAI, el empaquetado equivalente se divide entre flow state, crew tasks, agent roles, tools y evaluación a nivel de flow.

Related Chapters

• Mastra Runtime
• Framework Selection
• Building a Minimal Agent Runtime
• Production Evaluation Feedback Loops
• Support Refund Agent Capstone