Tre modi di scrivere lo stesso ciclo
LangGraph, Mastra e CrewAI fanno tutti la stessa promessa: orchestrare agenti. Nessuno dei tre è «il migliore», e chi lo afferma senza dirti per quale lavoro non ha confrontato niente. Le differenze che contano si vedono quando provi a esprimere la stessa logica in tutti e tre: dove vive lo stato, come si mette in pausa un processo per un via libera umano, chi ferma un ciclo che non finisce, che cosa esce dal tuo processo senza che tu l'abbia chiesto. Per questo l'articolo non descrive i framework a parole: ne fa girare tre programmi.
Il problema di prova è volutamente senza modello, così da essere ripetibile. Un agente di ricerca raccoglie fonti a giri: i quattro giri previsti ne portano 1, 0, 2 e 2. Si ferma appena ne ha almeno 3, oppure dopo 4 giri; se ne ha almeno 3 chiede un via libera umano prima di «pubblicare», altrimenti rinuncia. Nella versione reale, il giro di ricerca sarebbe una chiamata a un modello o a uno strumento; qui è un numero da una tabella, e la logica di controllo è identica. La traccia attesa è tre giri, approvazione, pubblicazione.
LangGraph: un grafo di nodi con uno stato condiviso
In LangGraph descrivi uno StateGraph: uno stato tipizzato, nodi che lo modificano, archi che decidono il nodo successivo. Il listato usa operator.add come reducer sul campo traccia, così ogni nodo accoda alla lista invece di sovrascriverla. La pausa è interrupt, che richiede un checkpointer (qui InMemorySaver) e un thread_id nella configurazione: sono loro a ricordare dove l'esecuzione si è fermata.
from typing import Annotated, TypedDict
import operator
from langgraph.graph import StateGraph, START, END
from langgraph.checkpoint.memory import InMemorySaver
from langgraph.types import Command, interrupt
NUOVE_FONTI = [1, 0, 2, 2] # esito deterministico di ogni giro di ricerca
TETTO_GIRI = 4
class Stato(TypedDict):
fonti: int
giri: int
traccia: Annotated[list[str], operator.add] # i nodi accodano, non sovrascrivono
def cerca(s: Stato) -> dict:
nuove = NUOVE_FONTI[s["giri"]]
return {"fonti": s["fonti"] + nuove, "giri": s["giri"] + 1,
"traccia": [f"cerca(+{nuove})"]}
def scegli(s: Stato) -> str:
if s["fonti"] >= 3:
return "approvazione"
if s["giri"] >= TETTO_GIRI:
return "abbandona"
return "cerca"
def approvazione(s: Stato) -> Command:
ok = interrupt({"domanda": "Pubblico?", "fonti": s["fonti"]})
return Command(goto="pubblica" if ok else "scarta",
update={"traccia": [f"approvazione={ok}"]})
def pubblica(s: Stato) -> dict:
return {"traccia": ["pubblica"]}
def scarta(s: Stato) -> dict:
return {"traccia": ["scarta"]}
def abbandona(s: Stato) -> dict:
return {"traccia": ["abbandona"]}
g = StateGraph(Stato)
for nome, fn in [("cerca", cerca), ("approvazione", approvazione),
("pubblica", pubblica), ("scarta", scarta), ("abbandona", abbandona)]:
g.add_node(nome, fn)
g.add_edge(START, "cerca")
g.add_conditional_edges("cerca", scegli, ["cerca", "approvazione", "abbandona"])
g.add_edge("pubblica", END)
g.add_edge("scarta", END)
g.add_edge("abbandona", END)
app = g.compile(checkpointer=InMemorySaver())
cfg = {"configurable": {"thread_id": "caso-1"}}
r = app.invoke({"fonti": 0, "giri": 0, "traccia": []}, cfg)
print("pausa :", r["__interrupt__"][0].value)
print("prossimo:", app.get_state(cfg).next)
r = app.invoke(Command(resume=True), cfg)
print("finale :", r["fonti"], r["giri"], " -> ".join(r["traccia"]))
# Output:
# pausa : {'domanda': 'Pubblico?', 'fonti': 3}
# prossimo: ('approvazione',)
# finale : 3 3 cerca(+1) -> cerca(+0) -> cerca(+2) -> approvazione=True -> pubblica
La riga add_conditional_edges("cerca", scegli, [...]) è il ciclo: dopo ogni giro la funzione scegli decide se tornare a cerca, passare all'approvazione o abbandonare. Il nodo approvazione chiama interrupt(...): la prima invoke si ferma e restituisce il payload sotto __interrupt__; la seconda, con Command(resume=True), riprende da lì e il valore diventa il risultato di interrupt. Nell'uscita vedi la pausa con tre fonti, il nodo successivo in attesa (approvazione) e la traccia finale prevista.
Il limite da conoscere è scritto nel nome stesso, InMemorySaver: la documentazione di LangGraph dice che InMemorySaver tiene i checkpoint in RAM e che al riavvio del processo si perdono tutti. Per un'approvazione che può arrivare dopo ore serve un checkpointer durevole su database. Il programma funziona identico, ma la pausa sopravvive solo finché vive il processo.
Mastra: passi tipizzati, sospensione e ripresa
In Mastra la stessa logica è un workflow: un passo cerca ripetuto con .dountil() finché la condizione diventa vera, poi un passo approvazione. La pausa è suspend() dentro il passo, con uno suspendSchema per ciò che mostri a chi decide e un resumeSchema per ciò che questi risponde. Ho dovuto spostare un pezzo di logica nel passo, perché .branch() esegue tutte le condizioni vere e vuole schemi uguali: il passo approvazione decide da sé se abbandonare o sospendere.
import { Mastra } from '@mastra/core'
import { createStep, createWorkflow } from '@mastra/core/workflows'
import { z } from 'zod'
const NUOVE_FONTI = [1, 0, 2, 2] // esito deterministico di ogni giro di ricerca
const TETTO_GIRI = 4
const stato = z.object({ fonti: z.number(), giri: z.number(), traccia: z.array(z.string()) })
const cerca = createStep({
id: 'cerca',
inputSchema: stato,
outputSchema: stato,
execute: async ({ inputData: s }) => {
const nuove = NUOVE_FONTI[s.giri]
return { fonti: s.fonti + nuove, giri: s.giri + 1, traccia: [...s.traccia, `cerca(+${nuove})`] }
},
})
const approvazione = createStep({
id: 'approvazione',
inputSchema: stato,
outputSchema: stato,
resumeSchema: z.object({ approvato: z.boolean() }),
suspendSchema: z.object({ domanda: z.string(), fonti: z.number() }),
execute: async ({ inputData: s, resumeData, suspend }) => {
if (s.fonti < 3) return { ...s, traccia: [...s.traccia, 'abbandona'] }
if (resumeData === undefined) return await suspend({ domanda: 'Pubblico?', fonti: s.fonti })
const esito = resumeData.approvato ? 'pubblica' : 'scarta'
return { ...s, traccia: [...s.traccia, `approvazione=${resumeData.approvato}`, esito] }
},
})
export const ciclo = createWorkflow({ id: 'ciclo-fonti', inputSchema: stato, outputSchema: stato })
.dountil(cerca, async ({ inputData: s }) => s.fonti >= 3 || s.giri >= TETTO_GIRI)
.then(approvazione)
.commit()
const mastra = new Mastra({ workflows: { ciclo } })
const run = await mastra.getWorkflow('ciclo').createRun()
const r = await run.start({ inputData: { fonti: 0, giri: 0, traccia: [] } })
console.log('stato :', r.status)
if (r.status === 'suspended') {
console.log('pausa :', JSON.stringify(r.suspendPayload ?? r.suspended))
const f = await run.resume({ step: 'approvazione', resumeData: { approvato: true } })
if (f.status === 'success') console.log('finale :', f.result.fonti, f.result.giri, f.result.traccia.join(' -> '))
}
// Output:
// stato : suspended
// pausa : {"approvazione":{"domanda":"Pubblico?","fonti":3}}
// finale : 3 3 cerca(+1) -> cerca(+0) -> cerca(+2) -> approvazione=true -> pubblica
run.start() restituisce un oggetto con stato suspended e il payload di sospensione, indicizzato per id del passo; run.resume({ step, resumeData }) riprende da quel passo. La traccia finale è la stessa degli altri, con una differenza che non nascondo: JavaScript scrive true dove Python scrive True. Il framework stampa inoltre su stderr un avviso: senza storage configurato usa un archivio in memoria, non durevole e non adatto alla produzione. È l'analogo dell'InMemorySaver di LangGraph: la sospensione dura finché il processo vive.
CrewAI: i Flow, con eventi e router
CrewAI ha due livelli. Le Crew mettono in squadra agenti con ruolo, obiettivo e storia; i Flow sono la parte a eventi: metodi decorati con @start, @listen e @router che si attivano a catena. Per il nostro problema serve il secondo livello. Una cosa pratica prima di tutto: crewai 1.15.41 dichiara Python >=3.10, <3.14, e il python3 di default della mia macchina è la 3.14. Ho dovuto creare un ambiente con Python 3.10, e il vincolo vale anche per te.
from typing import Literal
from crewai.flow.flow import Flow, listen, router, start
from crewai.flow.human_feedback import HumanFeedbackResult, human_feedback
from pydantic import BaseModel, Field
NUOVE_FONTI = [1, 0, 2, 2] # esito deterministico di ogni giro di ricerca
TETTO_GIRI = 4
class Stato(BaseModel):
fonti: int = 0
giri: int = 0
traccia: list[str] = Field(default_factory=list)
class Ciclo(Flow[Stato]):
@start()
@listen("ancora")
def cerca(self):
nuove = NUOVE_FONTI[self.state.giri]
self.state.fonti += nuove
self.state.giri += 1
self.state.traccia.append(f"cerca(+{nuove})")
@router(cerca)
def scegli(self) -> Literal["ancora", "approvazione", "abbandona"]:
if self.state.fonti >= 3:
return "approvazione"
if self.state.giri >= TETTO_GIRI:
return "abbandona"
return "ancora"
@listen("approvazione")
@human_feedback(message="Pubblico? (si/no)")
def chiedi_via_libera(self):
return f"{self.state.fonti} fonti raccolte"
@listen(chiedi_via_libera)
def concludi(self, esito: HumanFeedbackResult):
ok = esito.feedback.strip().lower() == "si"
self.state.traccia.append(f"approvazione={ok}")
self.state.traccia.append("pubblica" if ok else "scarta")
@listen("abbandona")
def chiudi_senza_esito(self):
self.state.traccia.append("abbandona")
flow = Ciclo()
flow.kickoff()
print("finale :", flow.state.fonti, flow.state.giri, " -> ".join(flow.state.traccia))
# Output:
# finale : 3 3 cerca(+1) -> cerca(+0) -> cerca(+2) -> approvazione=True -> pubblica
Il ciclo è l'unione di @start() e @listen("ancora") sullo stesso metodo: cerca parte all'inizio e si riattiva ogni volta che il router restituisce l'etichetta «ancora». Il router scegli annota il tipo di ritorno con Literal[...], che dichiara le diramazioni. Il via libera è @human_feedback: con la console, il Flow si ferma su input(); io l'ho eseguito con echo si | davanti al comando. Il framework stampa anche riquadri di avanzamento, con un identificatore casuale: ho riportato solo la riga che il programma scrive da sé.
Due precisazioni sul comportamento osservato. Per prima cosa, il nome di un metodo non può coincidere con l'etichetta che ascolta: chiamare approvazione il metodo che fa @listen("approvazione") fa fallire la creazione del Flow con un errore che parla di un possibile ciclo infinito, ed è per questo che ho usato chiedi_via_libera. Poi, se aggiungi emit=[...] a @human_feedback, il testo libero della persona viene interpretato da un modello linguistico per scegliere l'esito: un cancello di approvazione che dipende da un modello non è più un cancello.
Chi ferma un ciclo che non finisce
La differenza più istruttiva è l'assenza di freni. Ho scritto per ciascun framework un ciclo che non decide mai di fermarsi e l'ho lanciato. LangGraph ha un limite di superpassi: con recursion_limit a 5 solleva un errore chiaro. CrewAI ha un contatore per metodo, max_method_calls, che nella versione provata vale 100. Per Mastra non ho osservato alcun freno.
import operator
from typing import Annotated, TypedDict
from langgraph.errors import GraphRecursionError
from langgraph.graph import END, START, StateGraph
class Stato(TypedDict):
giri: Annotated[int, operator.add]
def gira(s: Stato) -> dict:
return {"giri": 1}
g = StateGraph(Stato)
g.add_node("gira", gira)
g.add_edge(START, "gira")
g.add_conditional_edges("gira", lambda s: "gira", ["gira"]) # non decide mai di fermarsi
app = g.compile()
try:
app.invoke({"giri": 0}, {"recursion_limit": 5})
except GraphRecursionError as e:
print(type(e).__name__)
print(str(e).splitlines()[0])
# Output:
# GraphRecursionError
# Recursion limit of 5 reached without hitting a stop condition. You can increase the limit by setting the `recursion_limit` config key.
Il codice è un nodo che si richiama senza fine. Con {"recursion_limit": 5} l'esecuzione termina con GraphRecursionError e il messaggio che suggerisce di alzare il limite. Se non lo passi, vale il valore predefinito: nel sorgente installato di LangGraph 1.2.21 è 10007 (variabile LANGGRAPH_DEFAULT_RECURSION_LIMIT), cifra che coincide con la documentazione. Un tetto di diecimila giri protegge dal blocco, ma non dalla fattura: ogni giro, con un modello vero, costa.
LangGraph GraphRecursionError dopo 5 superpassi (recursion_limit=5)
CrewAI RecursionError dopo 100 chiamate dello stesso metodo
("Method 'scegli' has been called 100 times", max_method_calls=100)
Mastra nessun errore: dountil con condizione sempre falsa interrotto da
"timeout 20", exit 124, nessuna riga stampata
Leggi l'esito così: LangGraph e CrewAI hanno un tetto, di natura diversa (passi del grafo contro chiamate dello stesso metodo) e con valori molto diversi, 10007 contro 100. In Mastra il tetto è una responsabilità della tua condizione, come nel programma sopra, dove giri >= TETTO_GIRI ferma il ciclo. Nessuno dei tre è «più sicuro»: cambia il punto in cui ti accorgi dell'errore, e se lo vedi in un test o in una fattura.
La tabella dei fatti, con la data
| Aspetto | LangGraph | Mastra | CrewAI |
|---|---|---|---|
| Licenza | MIT | Apache-2.0, directory ee/ con licenza propria | MIT |
| Versione (2026-11-13) | 1.2.21 (PyPI) | @mastra/core 1.83.0 (npm) | 1.15.41 (PyPI) |
| Requisito di runtime | Python 3.10 o successivo | Node 22.13 o successivo | Python 3.10 fino alla 3.13 |
| Pausa per via libera | interrupt + checkpointer | suspend + storage | @human_feedback, console o provider asincrono |
| Tetto ai cicli (osservato) | recursion_limit, 10007 di default | nessuno osservato | max_method_calls, 100 |
| Osservabilità documentata | LangSmith (account e chiave) | tracing integrato | telemetria anonima attiva di default |
La tabella contiene soltanto cose che ho letto nei registri, nei sorgenti installati o nella documentazione ufficiale il 13 novembre 2026. L'ultima riga merita una frase in più: la documentazione di CrewAI dichiara una telemetria anonima, attiva di default, che raccoglie tra l'altro i nomi dei tool e i ruoli degli agenti, e che si disattiva con CREWAI_DISABLE_TELEMETRY=true; per questo l'ho impostata, insieme a OTEL_SDK_DISABLED, in ogni esecuzione di CrewAI. Il percorso di osservabilità che la documentazione di LangGraph descrive è invece LangSmith, un servizio con account e chiave: nella forma documentata usarlo significa mandare le tracce a un servizio di terzi. Ne riparleremo nell'articolo sul debugging.
Come scegliere, e quando non scegliere nessuno dei tre
I criteri che ribaltano la decisione, nell'ordine in cui di solito pesano:
- Il linguaggio del team: Python per LangGraph e CrewAI, TypeScript per Mastra; cambiare linguaggio costa più di qualunque differenza di funzioni.
- Quanto controllo vuoi sul flusso: grafo esplicito (LangGraph), passi tipizzati (Mastra), eventi con router (CrewAI Flow) oppure squadre di agenti con ruoli (CrewAI Crew).
- Quanto dura una pausa: ore o giorni richiedono un checkpointer o uno storage durevoli in LangGraph e Mastra; con CrewAI valuta il provider di feedback asincrono.
- Chi vede le tracce: dentro la tua infrastruttura o presso un fornitore, con le condizioni sui dati che ne derivano.
- Il ritmo di cambiamento: tutti e tre sono in 1.x e rilasciano spesso (LangGraph ha pubblicato la 1.2.19, la 1.2.20 e la 1.2.21 tra il 30 ottobre e il 12 novembre 2026); fissa le versioni e prevedi la manutenzione.
Se il linguaggio è già deciso, la scelta si restringe di colpo: restano i criteri su pausa e osservabilità, quelli che i tre programmi hanno mostrato diversi. Se i dati sono sensibili, decidi per primo il quarto punto: è quello che i programmi hanno mostrato diverso, e che i tutorial raramente mettono in evidenza. C'è un'ultima opzione, che i confronti dimenticano: se il tuo ciclo sta in venti righe, con un tetto, un registro e una funzione di approvazione, un framework aggiunge dipendenze e aggiornamenti senza darti niente che il linguaggio non abbia già.
Dove entra il modello
Nei tre programmi il modello non c'è, e questo è il punto: la struttura di controllo sta in piedi senza. In LangGraph il modello entra in un nodo, in Mastra in un passo che chiama agent.generate, in CrewAI in un metodo del Flow che lancia un Agent o una Crew. Quel punto è l'unico non deterministico, e quindi quello da incapsulare, tracciare e limitare. Per i Crew la documentazione dichiara parametri di contenimento con valori predefiniti verificabili: max_iter 20 e allow_delegation falso, mentre role, goal e backstory sono obbligatori; il processo gerarchico richiede manager_llm o manager_agent. Questi non li ho eseguiti, perché richiedono un modello.
Che cosa sai fare adesso
Sai esprimere un ciclo con tetto e approvazione umana nei tre framework, sai dove vive lo stato di una pausa e quanto dura, sai quale freno esiste e quale no, e sai che cosa esce dal tuo processo per impostazione predefinita. Non hai una classifica, e va bene: hai criteri che puoi applicare al tuo progetto. Il passo seguente è mettere un prezzo alla scelta, con l'analisi dei costi. Se ti interessa il lato TypeScript, l'articolo su Mastra va più a fondo; la memoria, che nei tre programmi non compare, è il tema dell'articolo su Letta.
Domande frequenti
Quale framework è meglio per agenti in produzione?
Nessuno in assoluto: dipende da linguaggio, durata delle pause e destino delle tracce. I tre programmi dell'articolo mostrano le differenze che si possono misurare: dove vive la pausa, chi ferma un ciclo infinito, che cosa viene inviato fuori dal processo. Il resto lo decide il tuo team.
LangGraph, Mastra e CrewAI funzionano con modelli locali?
Nei tre programmi dell'articolo il modello è un componente che inserisci tu: entra in un nodo, in un passo o in un agente. Non ho eseguito alcun modello per questo articolo, quindi non posso dire come si comportano con un modello locale specifico; per Mastra e Ollama vedi l'articolo dedicato, per il resto leggi la documentazione del provider che scegli.
Il via libera umano in CrewAI usa un modello linguistico?
Dipende dall'opzione. Con @human_feedback senza emit raccoglie il testo della persona e basta; con emit=[...] la documentazione dice che il testo libero è interpretato da un modello per scegliere l'esito. Se il cancello deve essere deterministico, usa la prima forma.
Fonti
- LangGraph docs: Interrupts - interrupt, checkpointer e thread_id per la ripresa, consultata il 2026-11-13
- LangGraph docs: Persistence - InMemorySaver tiene i checkpoint in RAM e li perde al riavvio, consultata il 2026-11-13
- LangGraph docs: Graph API - recursion limit e GraphRecursionError, consultata il 2026-11-13
- LangGraph docs: Observability - il percorso documentato passa da LangSmith, con account e chiave API, consultata il 2026-11-13
- Mastra docs: Suspend and resume - suspend, resume, snapshot nello storage configurato, consultata il 2026-11-13
- Mastra docs: Control flow - dountil e semantica di branch, consultata il 2026-11-13
- Mastra docs: Tracing - span per agenti, workflow, tool e chiamate al modello; collegamento a sistemi di tracing di terzi, consultata il 2026-11-13
- CrewAI docs: Flows - start, listen, router, human_feedback e il suo emit, consultata il 2026-11-13
- CrewAI docs: Processes - processo sequenziale e gerarchico, manager_llm o manager_agent, consultata il 2026-11-13
- CrewAI docs: Telemetry - telemetria anonima di default e variabili per disattivarla, consultata il 2026-11-13
- CrewAI docs: Installation - requisito Python 3.10 e inferiore alla 3.14, consultata il 2026-11-13
Versioni e date di rilascio lette sui registri (API JSON di PyPI, npm view) il 2026-11-13: langgraph 1.2.21 (MIT), crewai 1.15.41 (MIT, repository crewAIInc/crewAI), @mastra/core 1.83.0. Il valore 10007 del limite di ricorsione di LangGraph e max_method_calls = 100 di CrewAI sono stati letti nei sorgenti installati (langgraph/_internal/_config.py, crewai/flow/runtime/__init__.py). I tre programmi del ciclo sono stati eseguiti due volte ciascuno, con l'uscita riportata; il ciclo di Mastra senza tetto è stato interrotto da timeout a 20 s.

Commenti
Caricamento commenti...
Accedi per commentare