Crea tu primer agente en TypeScript con Mastra
Tiempo estimado de lectura: 6 min
- Mastra es un framework nativo en TypeScript para construir agentes y flujos de IA con validación de esquemas en runtime.
- Separar Agent, Tool y Model permite pruebas unitarias y facilita cambiar proveedor de LLM.
- Usa Zod para convertir inputs/outputs del LLM en contratos verificables.
- Incluye un ejemplo práctico listo para ejecutar (agente de soporte técnico) y reglas operativas para producción.
Crear tu primer agente en TypeScript con Mastra es la forma más práctica de evitar la fragmentación entre Node.js y microservicios Python. Si tu stack es TypeScript, mantener todo en el mismo lenguaje reduce latencia, elimina fricciones en despliegue y preserva tipos end-to-end. En las siguientes secciones veremos qué es Mastra, su arquitectura y un ejemplo práctico listo para ejecutar.
Resumen rápido (lectores con prisa)
Mastra es un framework en TypeScript para agentes de IA que integra validación de esquemas con Zod.
Separa responsabilidades en Agent, Tool y Model para pruebas y cambio de proveedor de LLM.
Usa Zod para que las invocaciones a tools sean contratos verificables en runtime.
Incluye un ejemplo práctico (agente de soporte) y recomendaciones para producción.
Documentación y repositorio oficiales están disponibles para referencia.
Crea tu primer agente en TypeScript con Mastra: por qué importa y cuándo usarlo
Mastra es un framework nativo en TypeScript para construir agentes y flujos de IA. Su ventaja principal no es solo técnica: es contractual. Al integrar Zod para la validación de esquemas como parte del runtime, convierte las llamadas del LLM en contratos verificables, no en texto libre que “parece correcto”. Documentación: mastra.ai/docs. Repositorio: github.com/mastra-ai/mastra.
Úsalo cuando quieras:
- Ejecutar agentes dentro del mismo proceso Node/Next.js.
- Forzar esquemas de entrada/salida con Zod.
- Testear herramientas aisladas sin invocar modelos.
No es la solución si necesitas capacidades avanzadas aún no soportadas por Mastra; evalúa la madurez del proyecto antes de producción.
Arquitectura mínima: Agent, Tool y Model
Divide responsabilidades desde el inicio:
- Agent: orquesta la conversación, mantiene historial e instrucciones del sistema.
- Tool: funciones asíncronas fuertemente tipadas (Zod). Son la única forma controlada en la que el agente “toca” el mundo.
- Model: abstracción del proveedor de LLM (OpenAI, Anthropic, etc.). Cambiar proveedor debe ser un cambio mínimo.
Esa separación permite testing unitario de herramientas y garantiza que la lógica de negocio no quede oculta en un prompt.
Paso a paso: ejemplo práctico (Agente de soporte técnico)
Instalación rápida
mkdir mastra-agent && cd mastra-agent
npm init -y
npm install @mastra/core zod
npm install -D typescript @types/node tsx
npx tsc --init
export OPENAI_API_KEY="tu_api_key"1) Define la herramienta (Tool)
Controla exactamente qué parámetros acepta el LLM:
// src/tools/check-service.ts
import { createTool } from '@mastra/core';
import { z } from 'zod';
export const checkServiceTool = createTool({
id: 'check-service-status',
description: 'Consulta el estado operativo de un servicio interno por nombre.',
inputSchema: z.object({
service: z.enum(['api', 'database', 'frontend']),
}),
execute: async ({ context }) => {
// Reemplaza por consultas reales a monitorización/DB
const statuses = { api: 'degraded', database: 'operational', frontend: 'operational' };
return { service: context.service, status: statuses[context.service], checkedAt: new Date().toISOString() };
},
});2) Instancia el agente
Define instrucciones claras (system prompt) que actúen como contrato operativo:
// src/agent.ts
import { Agent } from '@mastra/core/agent';
import { checkServiceTool } from './tools/check-service';
export const supportAgent = new Agent({
name: 'TechSupportAgent',
instructions: `
Eres un ingeniero de soporte de nivel 1.
Antes de concluir que un servicio está caído, INVÓCAME la herramienta de estado.
Responde con datos y recomendaciones técnicas claras.
`,
model: { provider: 'OPENAI', name: 'gpt-4o-mini' },
tools: { checkServiceTool },
});3) Ejecuta el flujo
Ejecuta el agente y deja que Mastra coordine modelo y tools:
// src/main.ts
import { supportAgent } from './agent';
async function main() {
const prompt = 'Los usuarios reportan lentitud. ¿Está la API bien?';
const res = await supportAgent.generate(prompt);
console.log(res.text);
}
main().catch(console.error);Lanza con npx tsx src/main.ts. Mastra coordina al LLM y las herramientas: si el modelo decide invocar checkServiceTool, el framework valida el input con Zod, ejecuta la función y alimenta la respuesta final.
Reglas prácticas para llevar esto a producción
1. Observabilidad desde el día 0: logs estructurados en cada invocación de tool (request id, input validado, tiempo, resultado).
2. Errores como datos: las herramientas deben devolver errores tipados que el agente pueda razonar y comunicar (no lanzar excepciones sin contexto).
3. Testing aislado: tests unitarios para execute y tests de integración para la orquestación. No confundas velocidad con cobertura.
4. CI/CD: bloquea merges que introduzcan nuevas dependencias sin revisión de licencia/reputación. En entornos corporativos, valida paquetes recomendados por LLMs.
5. Ownership y ADRs: cualquier herramienta crítica debe tener un Architecture Decision Record que explique por qué existe y cómo se prueba.
Para guiar verificaciones de seguridad y dependencia sigue prácticas de NIST/OWASP (por ejemplo: owasp.org).
Conclusión: Mantén el criterio humano donde importa
Mastra te da la ergonomía de TypeScript y contratos verificables con Zod. Eso reduce alucinaciones estructurales y acelera integración en stacks web. Pero la ganancia real viene cuando aplicas disciplina: diseño previo, validación estricta, observabilidad y pruebas. Implementa el agente, mide cómo toma decisiones y exige que cualquier acción en producción esté documentada y testeada. En la próxima entrega de Dominicode mostraremos cómo añadir memoria persistente y encadenar múltiples tools para workflows complejos.
Dominicode Labs
Si trabajas en automatización, agentes o workflows y quieres ejemplos prácticos y guías operativas, consulta Dominicode Labs. Encontrarás recursos que complementan patrones de diseño y pruebas para agentes en producción.
FAQ
Mastra es un framework nativo en TypeScript para construir agentes y flujos de IA que integra Zod para validación de esquemas en runtime.
Cuando tu stack principal es TypeScript/Node.js y quieres ejecutar agentes en proceso, forzar esquemas de entrada/salida y testear herramientas sin invocar modelos externos.
Integra Zod como parte del runtime: las entradas a las tools se validan contra esquemas definidos y solo se ejecutan si cumplen el contrato tipado.
Sí. La arquitectura separa Model como una abstracción, de modo que cambiar proveedor (OpenAI, Anthropic, etc.) debe ser un cambio mínimo en la configuración.
Observabilidad desde el día 0, errores como datos tipados, testing aislado, control de dependencias en CI/CD y ADRs para herramientas críticas.
La documentación oficial está en mastra.ai/docs y el repositorio en github.com/mastra-ai/mastra.
