Salta al contenuto principale

02 - Mastra: agenti e workflow in TypeScript

Mastra in TypeScript: quando scegliere un agente o un workflow, tool con schema, memoria e storage, con i listati eseguiti o compilati sulla v1.83.

Cosa ne pensi di questo articolo?

02 - Mastra: agenti e workflow in TypeScript
Agentic PlatformsFoto:Pavel DanilyukPexels

In Breve

Mastra in TypeScript: quando scegliere un agente o un workflow, tool con schema, memoria e storage, con i listati eseguiti o compilati sulla v1.83.

Mastra: due strumenti per due tipi di problema

Mastra è un framework TypeScript per costruire applicazioni con modelli linguistici, e offre due strumenti che conviene non confondere. L'agente è un ciclo in cui è il modello a decidere quali strumenti chiamare e quando fermarsi. Il workflow è un grafo di passi che decidi tu, con dati tipizzati fra un passo e l'altro. La documentazione ufficiale dà la regola in una riga: l'agente per compiti aperti di cui non conosci i passi, il workflow per processi definiti in anticipo, con un ordine preciso.

Un esempio di bottega. «Aiutami a capire perché il mio ordine è in ritardo» è un compito aperto: forse serve guardare lo stato dell'ordine, forse il corriere, forse chiedere un dettaglio al cliente. «Quando arriva un reso, verifica il codice, controlla la finestra di 14 giorni, poi chiedi l'approvazione di un operatore» è un processo: i passi li conosci, e vuoi che nessun modello li salti. Il primo è un agente, il secondo un workflow, e spesso un workflow contiene un passo che chiama un agente.

Una nota sul tempo, perché questa serie descrive prodotti che cambiano. Il 13 novembre 2026 il registro npm indica @mastra/core alla versione 1.83.0, con ultima pubblicazione il giorno prima; il pacchetto richiede Node 22.13 o successivo. Molti tutorial usano nomi che non esistono più, o non sono mai esistiti: @mastra/sdk risponde 404 sul registro, e import { Agent } from 'mastra' non è l'importazione corrente, che è @mastra/core/agent. Prima di copiare un esempio, controlla che i nomi risolvano.

Installare Mastra: pochi pacchetti e un vincolo di versione

Installazione di prova (eseguita in una cartella temporanea)
npm install @mastra/core zod typescript @types/node
# per la memoria (articolo, sezione sull'agente):
npm install @mastra/memory @mastra/libsql

La prima riga porta il framework, zod per gli schemi, TypeScript e i tipi di Node. L'ho eseguita in una cartella fuori dal repository: è andata a buon fine e npm non ha segnalato vulnerabilità. Il comando consigliato dal README del progetto per iniziare è invece npm create mastra@latest, che crea una struttura di progetto completa. La seconda riga è insidiosa: @mastra/memory 1.41.1 dichiara come dipendenza peer @mastra/core >=1.83.0 <2.0.0, quindi i pacchetti Mastra vanno aggiornati insieme e non uno alla volta.

Per eseguire i listati senza compilare basta Node: la documentazione ricorda che Node 22.18 e successivi eseguono file TypeScript direttamente, a patto di scrivere l'estensione nelle importazioni locali. Io ho usato Node 24.11 con node file.ts. In un progetto vero userai il bundler del progetto; qui interessa che ogni listato sia stato eseguito così com'è.

Tool: lo schema è il primo controllo di sicurezza

Un tool è una funzione che il modello può chiamare. In Mastra si crea con createTool e quattro elementi indicati come necessari: id, description, inputSchema ed execute. La documentazione avverte che una semplice funzione o un oggetto non passato da createTool non viene eseguito, senza errori. Lo schema d'ingresso fa da primo muro: il modello propone i parametri, ma è lo schema a decidere se sono ammissibili.

Un tool con schema stretto, chiamato con input valido e non valido
import { createTool } from '@mastra/core/tools'
import { z } from 'zod'

const cercaOrdine = createTool({
  id: 'cerca-ordine',
  description: 'Restituisce lo stato di un ordine dato il suo codice',
  inputSchema: z.object({ codice: z.string().regex(/^ORD-\d{4}$/) }),
  outputSchema: z.object({ codice: z.string(), stato: z.string() }),
  execute: async ({ codice }) => ({ codice, stato: 'spedito' }),
})

// Il secondo argomento lo fornisce il runtime di Mastra; qui, fuori da un agente, passiamo un contesto vuoto.
const buono = await cercaOrdine.execute!({ codice: 'ORD-1234' }, {} as any)
console.log('input valido    :', JSON.stringify(buono))

const cattivo: any = await cercaOrdine.execute!({ codice: 'xyz' } as any, {} as any)
console.log('input non valido:', cattivo.error, '|', cattivo.message.split('\n')[1])

// Output:
// input valido    : {"codice":"ORD-1234","stato":"spedito"}
// input non valido: true | - codice: Invalid string: must match pattern /^ORD-\d{4}$/

La riga che conta è l'inputSchema: il codice deve rispettare l'espressione ^ORD-\d{4}$, quindi ammette «ORD-1234» e respinge «xyz». execute riceve già l'ingresso validato come primo argomento; il secondo, il contesto di esecuzione, lo fornisce il runtime, e per questo qui passo un oggetto vuoto. Nell'uscita vedi la differenza che interessa: con un ingresso non valido il tool non lancia un'eccezione, restituisce un oggetto con error: true e un messaggio che nomina il campo e la regola violata.

Il motivo del comportamento si capisce guardando chi legge quel messaggio: è il modello, che può correggere la chiamata e riprovare. Per un codice ordine inventato non c'è effetto collaterale; se lo schema fosse stato z.string() senza vincoli, la chiamata sarebbe arrivata al database con qualunque testo. Il costo è che ogni tool ha ora un contratto da mantenere. Quando non metterlo: per funzioni banali e interne che nessun modello chiama, uno schema in più è solo manutenzione.

Un tool ben fatto ha, nell'ordine in cui conviene scriverle:

  • un id stabile, perché compare nelle tracce e nei log;
  • una description breve che dice cosa fa e quando usarlo, perché è ciò che il modello legge per sceglierlo;
  • uno inputSchema stretto: formati, intervalli, valori ammessi;
  • un outputSchema che dichiara cosa restituisci, così chi lo riceve non indovina;
  • una execute senza effetti collaterali nascosti, o con l'effetto dichiarato nella descrizione.

L'ordine non è casuale: la descrizione orienta la scelta, lo schema d'ingresso filtra, quello d'uscita garantisce la forma di ciò che torna. La sicurezza si gioca sullo schema d'ingresso e su execute: se un tool può scrivere (rimborsare, cancellare, inviare), la descrizione deve dirlo e il flusso deve prevedere un'approvazione, che in Mastra è un passo di workflow sospeso, come mostra l'articolo di confronto.

Workflow: i passi li decidi tu

Un workflow si costruisce con createStep per ogni passo e createWorkflow per comporli. Ogni passo dichiara schema d'ingresso e d'uscita, e il motore controlla che il dato che esce da un passo sia quello che il successivo si aspetta. Il listato seguente è deterministico e non usa alcun modello: due passi, uno che normalizza un testo e uno che conta le parole.

Due passi concatenati, con ingresso valido e con ingresso errato
import { createStep, createWorkflow } from '@mastra/core/workflows'
import { z } from 'zod'

const normalizza = createStep({
  id: 'normalizza',
  inputSchema: z.object({ testo: z.string() }),
  outputSchema: z.object({ parole: z.array(z.string()) }),
  execute: async ({ inputData }) => ({
    parole: inputData.testo.toLowerCase().split(/\s+/).filter(Boolean),
  }),
})

const conta = createStep({
  id: 'conta',
  inputSchema: z.object({ parole: z.array(z.string()) }),
  outputSchema: z.object({ totale: z.number(), uniche: z.number() }),
  execute: async ({ inputData }) => ({
    totale: inputData.parole.length,
    uniche: new Set(inputData.parole).size,
  }),
})

const contaParole = createWorkflow({
  id: 'conta-parole',
  inputSchema: z.object({ testo: z.string() }),
  outputSchema: z.object({ totale: z.number(), uniche: z.number() }),
})
  .then(normalizza)
  .then(conta)
  .commit()

const run = await contaParole.createRun()
const esito = await run.start({ inputData: { testo: 'Ciao ciao mondo' } })
if (esito.status === 'success') console.log('esito:', esito.status, JSON.stringify(esito.result))

try {
  const altra = await contaParole.createRun()
  await altra.start({ inputData: { testo: 42 as any } })
} catch (e: any) {
  console.log('input errato:', e.id, '|', e.message.split('\n')[1].trim())
}

// Output:
// esito: success {"totale":3,"uniche":2}
// input errato: WORKFLOW_SCHEMA_VALIDATION_FAILED | - testo: Invalid input: expected string, received number

.then(normalizza).then(conta) dichiara l'ordine, e .commit() chiude la definizione: senza, il workflow non è eseguibile. createRun() crea un'esecuzione e start la avvia con i dati d'ingresso. Nell'uscita il primo caso torna con stato success e il risultato atteso, tre parole di cui due uniche. Il secondo non produce un risultato: manda un numero dove lo schema vuole una stringa, e il motore lancia un MastraError con id WORKFLOW_SCHEMA_VALIDATION_FAILED già all'avvio, prima di eseguire qualunque passo.

Due avvertenze dalla documentazione, perché sono le cose che sorprendono. La prima: .branch() valuta tutte le condizioni, e ogni condizione vera esegue il suo passo, quindi una diramazione può eseguirne più d'una; per averne una sola le condizioni vanno scritte in modo che si escludano a vicenda. La seconda riguarda i cicli con .dountil(): un ciclo la cui condizione non diventa mai vera non ha un tetto. Ho provato un ciclo con condizione sempre falsa: dopo 20 secondi non aveva stampato nulla e timeout l'ha interrotto con codice 124. Il tetto lo metti tu, nella condizione.

Agente e memoria: schema da adattare, compilato ma non eseguito

Per un agente serve un modello, e quindi una chiave o un server: il listato che segue è uno schema da adattare. L'ho compilato con tsc --strict contro @mastra/core 1.83.0, @mastra/memory 1.41.1 e @mastra/libsql 1.30.0, quindi i nomi e i tipi sono quelli reali; non l'ho eseguito, perché nessun modello è stato chiamato. Il modello è un server compatibile con le API di OpenAI, per esempio Ollama, che serve le sue rotte sotto /v1.

Agente con tool, memoria e storage (schema da adattare)
import { Agent } from '@mastra/core/agent'
import { Mastra } from '@mastra/core'
import { createTool } from '@mastra/core/tools'
import { Memory } from '@mastra/memory'
import { LibSQLStore } from '@mastra/libsql'
import { z } from 'zod'

const cercaOrdine = createTool({
  id: 'cerca-ordine',
  description: 'Restituisce lo stato di un ordine dato il suo codice',
  inputSchema: z.object({ codice: z.string().regex(/^ORD-\d{4}$/) }),
  outputSchema: z.object({ codice: z.string(), stato: z.string() }),
  execute: async ({ codice }) => ({ codice, stato: 'spedito' }),
})

export const assistenteOrdini = new Agent({
  id: 'assistente-ordini',
  name: 'Assistente ordini',
  instructions: 'Rispondi sullo stato degli ordini. Usa cerca-ordine, mai a memoria.',
  model: {
    id: 'custom/nome-del-modello-servito-da-ollama',
    url: 'http://localhost:11434/v1',
  },
  tools: { cercaOrdine },
  memory: new Memory({ options: { lastMessages: 20 } }),
})

export const mastra = new Mastra({
  agents: { assistenteOrdini },
  storage: new LibSQLStore({ id: 'mastra-storage', url: 'file:./mastra.db' }),
})

const agente = mastra.getAgentById('assistente-ordini')
const risposta = await agente.generate("Dov'è l'ordine ORD-1234?", {
  memory: { thread: 'cliente-42', resource: 'utente-42' },
})
console.log(risposta.text)

Nel costruttore Agent le proprietà sono id, name, instructions e model. Per i provider ospitati, model è una stringa nel formato provider/modello e la chiave si legge dalla variabile d'ambiente del provider. Ollama però non è un provider del router: la documentazione dice che ollama/<modello> non risolve, e propone o il pacchetto ollama-ai-provider-v2 o un endpoint compatibile con le API di OpenAI. Qui uso la seconda via, con l'URL di base http://localhost:11434/v1 e un id che sostituisci con il nome del tuo modello.

La memoria vuole due cose: un oggetto Memory sull'agente e uno storage sull'istanza Mastra. Il valore lastMessages dice quanti messaggi recenti entrano nel contesto; se non lo scrivi, vale 10: creando un new Memory() senza opzioni e leggendo la configurazione effettiva con getMergedThreadConfig (versione 1.41.1) ho trovato lastMessages 10, ricerca semantica spenta, memoria di lavoro disattivata e titoli automatici spenti. La pagina di riferimento non lo dice in chiaro. Una finestra scorrevole ha un costo che la documentazione dichiara: una volta superato il limite, ogni turno invalida la cache dei prompt del provider, e per le conversazioni lunghe la stessa pagina rimanda alla observational memory, indicata come soluzione consigliata.

Quando chiami generate, thread è la conversazione e resource è chi la possiede, di solito l'utente: è la coppia che tiene separate le memorie di Alice e di Bruno. Lo storage con file:./mastra.db persiste su file; la documentazione usa :memory: per il quickstart. Se non configuri nessuno storage, Mastra ripiega su un archivio in memoria: l'ho visto accadere eseguendo il workflow di sospensione dell'articolo di confronto, perché stampa un avviso che dice che i dati si perdono al riavvio e che non è adatto alla produzione. Una memoria che sparisce a ogni deploy non è una memoria.

Quando Mastra non è la scelta giusta

Mastra ha senso se il tuo stack è già TypeScript, se vuoi workflow con sospensione e ripresa e se ti serve un ambiente di sviluppo con interfaccia (il README cita Studio, in ascolto in locale sulla porta 4111 durante lo sviluppo). Non è la scelta ovvia se il tuo team lavora in Python: in quel caso LangGraph e CrewAI, trattati nel confronto, parlano la tua lingua. I punti da pesare, prima di impegnarti:

  • Velocità di cambiamento: la versione 1.83.0 e le pubblicazioni ravvicinate (core, CLI e memoria hanno tutti una data di modifica del 12 novembre) dicono che le API si muovono; fissa le versioni e leggi i changelog.
  • Licenza: Apache-2.0 per quasi tutto, ma le directory ee/ hanno una licenza propria, definita in ee/LICENSE, che non ho valutato.
  • Dipendenza dal provider: il router unifica 40 e più provider secondo il README, ma ogni provider vuole la sua chiave e le sue condizioni sui dati.
  • Stato: memoria e sospensione dei workflow richiedono uno storage; senza, perdi tutto al riavvio.

Leggi l'elenco come domande da fare al tuo progetto. La licenza conta solo se userai le parti sotto ee/ (per esempio il modulo auth/ee di @mastra/core). La velocità di cambiamento conta se il codice deve vivere anni senza manutenzione. La dipendenza dal provider è la stessa di ogni framework: il codice dell'agente non cambia, ma i tuoi dati sì, e sui modelli ospitati la decisione sui dati va presa a monte. Lo stato è l'unico punto in cui un errore costa subito.

Che cosa sai fare adesso

Sai scegliere fra agente e workflow in base a quanto conosci i passi, scrivere un tool con uno schema che lo protegge e vedere come si comporta con input errati, comporre un workflow tipizzato ed evitare i due tranelli documentati (diramazioni multiple e cicli senza tetto). Sai anche dove una guida vecchia ti tradisce: pacchetti inesistenti, importazioni che non risolvono, memoria che sparisce. Il primo articolo ha mostrato come Letta affronta la memoria, un problema che Mastra risolve con strumenti diversi; il successivo mette Mastra accanto a LangGraph e CrewAI su uno stesso problema, con i tre programmi eseguiti. Per il resto della serie, l'analisi dei costi dice che cosa costa far girare un agente con un modello locale, e l'articolo sul tracing mostra come leggere ciò che fa.

Domande frequenti

Mastra è open source e posso usarlo in un prodotto commerciale?

Il file LICENSE.md del repository applica Apache-2.0 a tutto ciò che sta fuori dalle directory ee/, e per quelle rinvia a ee/LICENSE. Il registro npm dichiara Apache-2.0 per @mastra/core. Se ti servono i moduli sotto ee/, leggi quella licenza prima di decidere: io non l'ho valutata.

Posso usare Mastra con un modello locale come Ollama?

Sì, ma non con la stringa ollama/modello: la documentazione dice che Ollama non è un provider del router. Si passa un'istanza di ollama-ai-provider-v2 oppure l'URL di base compatibile con OpenAI, che per Ollama è http://localhost:11434/v1. Non ho eseguito questo collegamento: serve un modello.

Come si ferma un ciclo che non finisce in un workflow Mastra?

Non c'è un tetto predefinito che ho potuto osservare: un .dountil() con condizione sempre falsa non è terminato in 20 secondi. Scrivi il tetto nella condizione, per esempio contando i giri nello stato, come nel programma dell'articolo di confronto.

Fonti

Versioni (@mastra/core 1.83.0, @mastra/memory 1.41.1, @mastra/libsql 1.30.0, zod 4.6.7, Node >=22.13) lette con npm view il 2026-11-13; 404 di @mastra/sdk verificato lo stesso giorno. I programmi del tool e del workflow sono stati eseguiti con Node 24.11 due volte con la stessa uscita; l'avviso sullo storage in memoria è il messaggio reale di Mastra su stderr. Il listato dell'agente è compilato con tsc strict ed è uno schema da adattare: nessun modello è stato chiamato.

Prova Questi Strumenti

Strumenti gratuiti correlati a questo argomento.

Commenti

Caricamento commenti...

Accedi per commentare

Articoli e strumenti nuovi anche su Telegram

Il canale Telegram segnala gli articoli e gli strumenti nuovi del sito.

Ti è piaciuto questo articolo?

Esplora altri contenuti sul blog o scopri i miei progetti