Mastra: el framework TypeScript para agentes IA

Instalación

Mastra requiere Node.js 18 o superior y TypeScript 5.0 o superior. El paquete principal es @mastra/core. Los paquetes de integración y capacidades adicionales (RAG, memoria, integraciones específicas) se instalan por separado según lo que necesite el proyecto:

# Paquete principal (agentes, herramientas y workflows)
npm install @mastra/core

# Pipeline RAG (chunking, embeddings, búsqueda vectorial)
npm install @mastra/rag

# Gestión de memoria persistente
npm install @mastra/memory

# Ejemplo: integración con GitHub
npm install @mastra/github

Primer agente con herramienta personalizada

El siguiente ejemplo muestra como definir una herramienta con schema Zod, crear un agente que la utiliza y ejecutar una consulta. El compilador TypeScript garantiza que los argumentos de la herramienta son del tipo correcto en tiempo de compilación, antes de que el código se ejecute:

import { Agent, createTool } from '@mastra/core';
import { anthropic } from '@mastra/core/llm/anthropic';
import { z } from 'zod';

// Definicion de una herramienta con schema Zod tipado
const weatherTool = createTool({
  id: 'get-weather',
  description: 'Obtiene el tiempo actual para una ciudad',
  inputSchema: z.object({
    city: z.string().describe('Nombre de la ciudad'),
    units: z.enum(['celsius', 'fahrenheit']).default('celsius'),
  }),
  execute: async ({ context }) => {
    // El tipo de context.city y context.units se infiere del schema
    const response = await fetch(
      `https://api.weather.example.com?city=${context.city}&units=${context.units}`
    );
    return await response.json();
  },
});

// Creacion del agente
const weatherAgent = new Agent({
  name: 'weather-agent',
  instructions: 'Eres un asistente meteorologico. Usa la herramienta get-weather para responder sobre el tiempo actual.',
  model: anthropic('claude-sonnet-4-5'),
  tools: { weatherTool },
});

// Ejecucion
const result = await weatherAgent.generate(
  'Que tiempo hace ahora mismo en Madrid?'
);

console.log(result.text);

La clave está en la función createTool: el schema Zod no solo valida los argumentos en tiempo de ejecución, sino que Mastra lo usa para generar automáticamente el schema JSON que se envía al modelo LLM en el function calling. Una sola fuente de verdad para el tipo TypeScript, la validación en runtime y el schema que entiende el modelo.

Modelo de ejecución de workflows

Un workflow en Mastra es una secuencia de pasos donde cada paso es una función TypeScript que recibe el estado actual del workflow y devuelve una actualización parcial o total de ese estado. El motor gestiona la transición entre pasos, el manejo de errores y la ejecución condicional o paralela. El estado del workflow es un objeto TypeScript tipado con Zod, lo que garantiza que cada paso solo puede acceder a las propiedades que existen en el esquema definido.

import { Workflow, Step } from '@mastra/core';
import { z } from 'zod';

// Schema del estado del workflow
const researchState = z.object({
  query: z.string(),
  sources: z.array(z.string()).default([]),
  summary: z.string().optional(),
  qualityScore: z.number().optional(),
});

const researchWorkflow = new Workflow({
  name: 'research-workflow',
  schema: researchState,
});

// Paso 1: buscar fuentes (se ejecuta siempre)
researchWorkflow.step(new Step({
  id: 'search-sources',
  execute: async ({ context }) => {
    const sources = await searchWeb(context.query);
    return { sources };
  },
}));

// Paso 2: resumir (bifurcacion: solo si hay fuentes suficientes)
researchWorkflow.step(new Step({
  id: 'summarize',
  when: async ({ context }) => context.sources.length >= 3,
  execute: async ({ context }) => {
    const summary = await agent.generate(
      `Resume estas fuentes sobre: ${context.query}\n\n${context.sources.join('\n')}`
    );
    return { summary: summary.text };
  },
}));

// Paso 3: evaluar calidad
researchWorkflow.step(new Step({
  id: 'evaluate',
  execute: async ({ context }) => {
    const score = await evaluateQuality(context.summary ?? '');
    return { qualityScore: score };
  },
}));

// Ejecutar el workflow
const result = await researchWorkflow.execute({
  triggerData: { query: 'frameworks TypeScript para agentes IA 2026' },
});

Ejecución paralela de pasos

Mastra soporta ejecución paralela de pasos que no dependen entre sí. En lugar de esperar a que cada paso termine antes de empezar el siguiente, el motor puede lanzar varios pasos al mismo tiempo y continuar cuando todos hayan completado. Esto reduce el tiempo total de ejecución en workflows donde hay tareas independientes que pueden procesarse de forma concurrente:

// Pasos paralelos: se ejecutan al mismo tiempo
researchWorkflow.parallel([
  new Step({
    id: 'search-academic',
    execute: async ({ context }) => ({
      academicSources: await searchAcademic(context.query),
    }),
  }),
  new Step({
    id: 'search-news',
    execute: async ({ context }) => ({
      newsSources: await searchNews(context.query),
    }),
  }),
  new Step({
    id: 'search-github',
    execute: async ({ context }) => ({
      githubRepos: await searchGitHub(context.query),
    }),
  }),
]);

// El siguiente paso recibe los resultados de los tres pasos anteriores
researchWorkflow.step(new Step({
  id: 'merge-sources',
  execute: async ({ context }) => ({
    sources: [
      ...context.academicSources,
      ...context.newsSources,
      ...context.githubRepos,
    ],
  }),
}));

Las cuatro fases del pipeline RAG de Mastra

RAG (Retrieval Augmented Generation) es el patrón que permite a un agente responder preguntas sobre documentación propia, bases de conocimiento internas o cualquier corpus de texto que no forme parte del entrenamiento del modelo. El pipeline de Mastra cubre las cuatro fases del ciclo completo:

Bases de datos vectoriales compatibles

Mastra soporta las principales bases de datos vectoriales con una API coherente: Pinecone, Weaviate, Chroma, Qdrant, pgvector (PostgreSQL), Supabase Vector y Turso. Cambiar de una base de datos vectorial a otra es un cambio de configuración que no afecta al código del pipeline. Para entornos de desarrollo, Mastra incluye un backend en memoria que permite iterar sin levantar un servicio de base de datos.

El pipeline RAG completo se activa como una herramienta del agente, lo que permite combinar RAG con otras herramientas de forma transparente: el agente puede buscar en la base de conocimiento y, si no encuentra la respuesta, usar una herramienta de búsqueda web o llamar a una API externa, todo en el mismo loop de razonamiento.

Una de las características más prácticas de Mastra es su sistema de integraciones. En lugar de escribir la lógica de autenticación, manejo de errores y serialización de cada API desde cero, Mastra proporciona paquetes de integración que exponen las operaciones más habituales de cada servicio como herramientas ya listas para usar en un agente. Las integraciones disponibles a mayo de 2026 cubren las categorías principales de herramientas SaaS:

La lista completa de integraciones disponibles y sus herramientas expuestas está documentada en mastra.ai/docs/integrations . Cada integración tiene su propio paquete npm (@mastra/github, @mastra/slack, etc.) para que el bundle final solo incluya las dependencias que el proyecto realmente necesita.

Regla de decisión rápida

Elige Mastra cuando tu equipo trabaje en TypeScript o JavaScript y necesites un framework batteries-included con workflows, RAG e integraciones sin cambiar de lenguaje. Elige LangChain cuando trabajes en Python y necesites el ecosistema de integraciones más amplio disponible o flujos de control complejos con LangGraph. Elige CrewAI cuando el caso de uso sea un sistema multi-agente con roles bien definidos y quieras la API más declarativa posible. Elige Claude Agent SDK cuando quieras la integración más directa con Claude de Anthropic, en particular si usas funcionalidades específicas de Claude como computer use, extended thinking o MCP nativo.