Cos'è
Mastra è un framework open-source scritto in TypeScript per la costruzione di applicazioni e agenti basati su modelli di linguaggio di grandi dimensioni (LLM). Viene distribuito principalmente attraverso npm con il pacchetto principale @mastra/core e una serie di pacchetti satellite per storage, database vettoriali, valutazioni e integrazioni. Il progetto è stato avviato nel 2024 da Sam Bhagwat, Abhi Aiyer e Shane Thomas, gli stessi creatori di Gatsby, il noto generatore di siti statici per React poi acquisito da Netlify.
Mastra si posiziona come uno strumento pensato per sviluppatori che lavorano nell'ecosistema JavaScript/TypeScript e desiderano costruire sistemi agentici senza dover ricorrere a framework Python o a wrapper sottili intorno a librerie nate per altri ambienti. La licenza del core è Apache 2.0; alcune funzionalità avanzate collocate nelle directory ee/ del repository sono coperte da una licenza enterprise separata e richiedono un abbonamento commerciale per l'uso in produzione.
Il problema che risolve
Per lungo tempo, la maggior parte degli strumenti seri per la costruzione di agenti AI è stata sviluppata nell'ecosistema Python. Gli sviluppatori TypeScript dovevano quindi scegliere tra librerie portate parzialmente da Python, wrapper di basso livello, o l'assemblaggio manuale di più componenti — gestione dei prompt, chiamata di strumenti, memoria, osservabilità, valutazione — con il rischio di ottenere pipeline fragili e difficili da mantenere.
Mastra affronta questo problema offrendo un framework coeso e nativo per TypeScript, in cui agenti, tool, workflow, memoria, RAG, valutazioni e tracciabilità convivono sotto la stessa superficie API. L'obiettivo è ridurre la frizione tra l'idea di un agente e il suo deploy in produzione, mantenendo la type safety e le convenzioni familiari agli sviluppatori web.
Come funziona
Mastra si basa su un insieme di primitive che coprono il ciclo di vita completo di un'applicazione agentica:
- Agenti: entità in grado di gestire compiti aperti. Si definiscono con un modello, un system prompt e un insieme di tool. L'agente decide autonomamente quali tool invocare, quando fermarsi e come rispondere. Supporta sia risposte complete sia streaming di token.
- Tool: funzioni tipizzate definite tramite schemi Zod. Gli agenti le invocano in modo strutturato e i parametri di input e output sono validati e autococompletabili nell'editor.
- Workflow: pipeline deterministiche a grafo per orchestrare processi multi-step. Offrono metodi come
.then(),.branch()e.parallel(), con supporto per sospensione, approvazione umana e ripresa dallo stato persistito. - RAG: pipeline complete per retrieval-augmented generation, inclusi chunking di documenti, generazione di embedding, storage vettoriale, ricerca per similarità e reranking.
- Memoria: conservazione del contesto tra conversazioni, con storia dei messaggi, richiamo semantico, memoria di lavoro per fatti strutturati e sistemi di compressione per conversazioni passate.
- Evals: strumenti per valutare la qualità degli output degli agenti tramite metriche basate su modelli, regole o statistiche.
Per le interazioni con i modelli linguistici, Mastra si appoggia all'AI SDK di Vercel, ereditandone l'infrastruttura di streaming e il supporto provider, senza dover ricostruire uno strato di astrazione ridondante.
Caratteristiche principali
Tra le caratteristiche distintive di Mastra figurano:
- TypeScript-first: tutte le API sono pensate per il type system di TypeScript, con inference end-to-end su tool, output strutturati e workflow.
- Model router unificato: un'interfaccia comune per accedere a modelli di decine di provider (OpenAI, Anthropic, Google, DeepSeek, Groq, Mistral, xAI, Cohere, Amazon Bedrock, Azure OpenAI, Ollama, Together AI, Fireworks AI, Hugging Face e altri), specificabili con stringhe del tipo
provider/model-name. - Supporto MCP: possibilità di creare server Model Context Protocol per esporre agenti, tool e risorse strutturate ad altri sistemi compatibili con il protocollo.
- Osservabilità integrata: tracciamento delle chiamate, dei token e delle esecuzioni, con esportazione verso piattaforme come Langfuse, LangSmith, Braintrust, Arize, Sentry e backend compatibili OpenTelemetry.
- Storage flessibile: supporto per PostgreSQL, LibSQL/Turso, MongoDB, Upstash, DynamoDB, Cloudflare D1/KV, ClickHouse e altri, con possibilità di combinare backend diversi per diversi domini (memoria, workflow, osservabilità).
- Adattatori server: integrazioni per Express, Hono, Fastify, Koa, Next.js, Astro, SvelteKit, Nuxt, oltre alla modalità standalone tramite
mastra build. - CLI e dev server: comando
npm create mastra@latestper inizializzare un progetto, con server di sviluppo locale e interfaccia Mastra Studio per ispezionare agenti e workflow.
Casi d'uso concreti
Mastra si adatta a diversi scenari operativi:
- Assistenza clienti: agenti conversazionali che accedono a tool interni (ricerca ordini, fatture, politiche di reso) e forniscono risposte contestualizzate, con memoria persistente della conversazione.
- Copilot di dominio: assistenti specializzati per sviluppo software, ricerca legale, analisi finanziaria o revisione di documenti, integrati in applicazioni esistenti tramite API tipizzate.
- Automazione di workflow: pipeline programmate che estraggono dati da più fonti, li trasformano, li validano e li scrivono in database o sistemi esterni, con controllo deterministico su ogni passaggio.
- Ricerca e sintesi: sistemi RAG che indicizzano documentazione aziendale, codebase o knowledge base e rispondono a domande con riferimenti verificabili.
- Supporto decisionale: agenti che analizzano dati strutturati e non strutturati, generano raccomandazioni e richiedono approvazione umana prima di azioni critiche.
Punti di forza e limiti
Punti di forza:
- Esperienza nativa per sviluppatori TypeScript, con API coerenti e type safety su tutta la catena.
- Ecosistema modulare che copre agenti, workflow, memoria, RAG, valutazioni e osservabilità senza richiedere l'assemblaggio di molte librerie.
- Ampia compatibilità con provider di modelli e backend di storage.
- Workflow durevoli e ripristinabili, adatti a processi aziendali che richiedono affidabilità.
- Community attiva e rapido ritmo di rilascio, con documentazione dettagliata.
Limiti:
- Disponibile solo per JavaScript/TypeScript: team che usano Python o altri linguaggi non possono adottarlo direttamente.
- Alcune funzionalità avanzate di gestione e sicurezza (autenticazione SSO, RBAC, ACL in Mastra Studio) sono soggette a licenza enterprise.
- La superficie API è ampia e in rapida evoluzione; progetti che necessitano di stabilità a lunghissimo termine devono valutare attentamente gli aggiornamenti.
- L'offerta cloud gestita, Mastra Cloud, è opzionale ma introduce un possibile lock-in per chi sceglie di usarla a produzione.
Alternative e contesto
Mastra si colloca in un ecosistema affollato di framework per agenti AI. Tra le alternative più rilevanti:
- LangChain / LangGraph: ecosistema molto maturo, disponibile in Python e JavaScript, orientato alla composizione di catene e grafi di agenti. Più flessibile ma spesso più verboso.
- Pydantic AI: framework Python leggero e type-safe di Samuel Colvin e il team di Pydantic, focalizzato su agenti e structured outputs.
- AutoGen (Microsoft): framework per conversazioni multi-agente e orchestrazione, particolarmente usato in ambito ricerca e prototipazione.
- Dify: piattaforma low-code/no-code per costruire agenti e workflow, più adatta a team meno tecnici rispetto a un framework code-first come Mastra.
- OpenAI Agents SDK: SDK ufficiale di OpenAI per costruire agenti con tool e handoff, strettamente legato all'ecosistema OpenAI.
Mastra si distingue per la scelta esplicita di TypeScript come lingua franca e per l'ambizione di coprire l'intero ciclo di vita produttivo, dal prototipo all'osservabilità in produzione.
In sintesi
Mastra è un framework open-source TypeScript pensato per portare lo sviluppo di agenti AI, workflow e sistemi RAG nell'ecosistema JavaScript con un approccio unificato e type-safe. Nato dal team di Gatsby, ha guadagnato rapidamente attenzione nella community grazie a un'API coesa, a un ampio supporto di modelli e backend, e a un ritmo di sviluppo sostenuto. La versione 1.0, rilasciata nel gennaio 2026, ne sancisce la maturità per progetti reali, pur richiedendo una valutazione attenta sulle funzionalità enterprise e sulle scelte di deployment.
Risorse
- Sito ufficiale: https://mastra.ai
- Repository GitHub: https://github.com/mastra-ai/mastra
- Documentazione: https://mastra.ai/docs
- Pacchetto npm core: https://www.npmjs.com/package/@mastra/core