Mastra - Cheatsheet del Framework di Agente AI TypeScript

Mastra - Cheatsheet del Framework di Agente AI TypeScript

Mastra è un framework open-source TypeScript per agenti AI e workflow, costruito dal team dietro Gatsby. Mentre la maggior parte dei framework di agenti sono Python-first, Mastra punta all”ecosistema JavaScript/TypeScript con piena type safety: agenti tipizzati con strumenti e memoria, workflow durevoli espressi come grafi con branching e suspend/resume, primitive RAG, valutazioni integrate e un playground di sviluppo locale per iterare gli agenti nel browser.

Installation

Method	Command
Create a project	npm create mastra@latest
Add to existing	npm install @mastra/core
Dev server	npm run dev (playground at localhost:4111)
Model provider	npm install @ai-sdk/openai (uses Vercel AI SDK)
Verify	open the playground

Defining an Agent

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);

Method	Does
.generate(input)	Esegui una volta e restituisci il risultato
.stream(input)	Trasmetti token/step
tools	Strumenti tipizzati che l”agente può chiamare
memory	Memoria conversazionale persistente

Tools

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) };
  },
});

Gli schemi Zod forniscono type safety end-to-end — le chiamate di strumenti dell”agente sono validate e tipizzate su entrambi i lati.

Workflows (Durable Graphs)

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();

Feature	Purpose
.then()	Step sequenziali
.branch()	Percorsi condizionali
.parallel()	Step concorrenti
.dowhile() / .foreach()	Loop sui dati
Suspend/resume	Pausa per input umano, riprendi dopo
Durable execution	Sopravvive ai riavvii

Memory

Type	Use
Conversation history	Turni recenti in contesto
Semantic recall	Ricerca vettoriale su messaggi passati
Working memory	Fatti persistenti sull”utente
Storage adapters	LibSQL, Postgres, Upstash

RAG Primitives

Piece	Provides
Document chunking	Dividi i documenti con strategie configurabili
Embeddings	Via i provider dell”AI SDK
Vector stores	pgvector, Pinecone, Qdrant, Chroma
Retrieval tool	Collega il recupero in un agente come strumento

Evals & Observability

Capability	Note
Built-in evals	Rilevanza della risposta, fedeltà, tossicità, bias
Custom scorers	Definisci le tue metriche
Tracing	Trace compatibili con OpenTelemetry
Playground	Ispeziona esecuzioni dell”agente, strumenti e memoria localmente

Deployment

Target	Note
Node server	mastra build produce un server distribuibile
Vercel / Cloudflare / Netlify	Distribuitori ufficiali
Serverless	Workflow progettati per host stateless

Mastra vs Other Agent Frameworks

Aspect	Mastra	LangGraph	CrewAI
Language	TypeScript	Python	Python
Workflows	Grafo durevole + suspend/resume	Grafo con stato	Crew basati su ruoli
Type safety	Forte (Zod end-to-end)	Tipizzazione Python	Tipizzazione Python
Best for	Team TS/JS, app web	Agenti con stato complessi	Roleplay multi-agente

L”omologo TypeScript di LangGraph; confronta con CrewAI e AutoGen per Python.

Resources

• Official Website
• GitHub Repository
• Documentation