Mastra - Marco de Agente IA TypeScript Hoja de Trucos
Mastra es un marco TypeScript de código abierto para agentes y flujos de trabajo de IA, construido por el equipo detrás de Gatsby. Donde la mayoría de marcos de agentes son Python-first, Mastra se enfoca en el ecosistema JavaScript/TypeScript con seguridad de tipos completa: agentes tipados con herramientas y memoria, flujos de trabajo duraderos expresados como grafos con ramificación y suspensión/reanudación, primitivos RAG, evals integrados y un playground de desarrollo local para iterar sobre agentes en el navegador.
Instalación
| Método | Comando |
|---|
| Crear proyecto | npm create mastra@latest |
| Agregar a existente | npm install @mastra/core |
| Servidor dev | npm run dev (playground en localhost:4111) |
| Proveedor de modelo | npm install @ai-sdk/openai (usa Vercel AI SDK) |
| Verificar | abre el playground |
Definiendo un Agente
import { Agent } from "@mastra/core/agent";
import { openai } from "@ai-sdk/openai";
export const supportAgent = new Agent({
name: "support",
instructions: "You are a concise support agent. Cite docs when possible.",
model: openai("gpt-4o"),
tools: { searchDocs },
});
const result = await supportAgent.generate("How do I rotate my API key?");
console.log(result.text);
| Método | Hace |
|---|
.generate(input) | Ejecutar una vez y retornar el resultado |
.stream(input) | Transmitir tokens/pasos |
tools | Herramientas tipadas que el agente puede llamar |
memory | Memoria conversacional persistente |
Herramientas
import { createTool } from "@mastra/core/tools";
import { z } from "zod";
export const searchDocs = createTool({
id: "search-docs",
description: "Search the product documentation",
inputSchema: z.object({ query: z.string() }),
outputSchema: z.object({ results: z.array(z.string()) }),
execute: async ({ context }) => {
return { results: await search(context.query) };
},
});
Los esquemas Zod dan seguridad de tipos de extremo a extremo — las llamadas de herramienta del agente se validan y tipan en ambos lados.
Flujos de Trabajo (Grafos Duraderos)
import { createWorkflow, createStep } from "@mastra/core/workflows";
const fetchData = createStep({ id: "fetch", execute: async () => ({ ... }) });
const analyze = createStep({ id: "analyze", execute: async ({ inputData }) => ({ ... }) });
export const pipeline = createWorkflow({ id: "pipeline" })
.then(fetchData)
.then(analyze)
.commit();
| Característica | Propósito |
|---|
.then() | Pasos secuenciales |
.branch() | Rutas condicionales |
.parallel() | Pasos concurrentes |
.dowhile() / .foreach() | Bucles sobre datos |
| Suspensión/reanudación | Pausar por entrada humana, reanudar después |
| Ejecución duradera | Sobrevive reinicios |
Memoria
| Tipo | Uso |
|---|
| Historial de conversación | Turnos recientes en contexto |
| Recuperación semántica | Búsqueda vectorial sobre mensajes anteriores |
| Memoria de trabajo | Hechos persistentes sobre el usuario |
| Adaptadores de almacenamiento | LibSQL, Postgres, Upstash |
Primitivos RAG
| Pieza | Proporciona |
|---|
| Chunking de documentos | Dividir docs con estrategias configurables |
| Embeddings | A través de los proveedores de AI SDK |
| Almacenes de vectores | pgvector, Pinecone, Qdrant, Chroma |
| Herramienta de recuperación | Conectar recuperación en un agente como herramienta |
Evals y Observabilidad
| Capacidad | Nota |
|---|
| Evals integrados | Relevancia de respuesta, fidelidad, toxicidad, sesgo |
| Puntuadores personalizados | Define tus propias métricas |
| Rastreo | Trazas compatibles con OpenTelemetry |
| Playground | Inspeccionar ejecuciones de agente, herramientas y memoria localmente |
Despliegue
| Objetivo | Nota |
|---|
| Servidor Node | mastra build produce un servidor desplegable |
| Vercel / Cloudflare / Netlify | Desplegadores oficiales |
| Sin estado | Flujos de trabajo diseñados para hosts sin estado |
Mastra vs Otros Marcos de Agente
| Aspecto | Mastra | LangGraph | CrewAI |
|---|
| Lenguaje | TypeScript | Python | Python |
| Flujos de trabajo | Grafo duradero + suspensión/reanudación | Grafo con estado | Equipos basados en roles |
| Seguridad de tipos | Fuerte (Zod de extremo a extremo) | Tipado Python | Tipado Python |
| Mejor para | Equipos TS/JS, apps web | Agentes con estado complejos | Juego de rol multi-agente |
La contrapartida de TypeScript a LangGraph; compara con CrewAI y AutoGen para Python.
Recursos
