La definizione breve
Un modello linguistico da solo risponde a una domanda. Un agente fa qualcosa in più: ha un obiettivo, può usare strumenti esterni, e decide da sé quanti passaggi servono per arrivare al risultato. CrewAI parte da questa idea e aggiunge il pezzo che manca nella maggior parte delle librerie: il coordinamento fra più agenti.
La metafora che dà il nome al progetto è quella dell'equipaggio. Non scrivi una catena di chiamate, descrivi una squadra: chi fa cosa, con quale obiettivo, e chi controlla il lavoro degli altri. Il framework traduce quella descrizione in prompt, chiamate al modello, uso degli strumenti e passaggi di contesto fra un ruolo e l'altro.
Il problema che risolve
Il primo istinto di chiunque abbia usato un modello linguistico via API è scrivere un solo prompt lunghissimo che fa tutto: cerca, analizza, riassumi, scrivi. Funziona per le dimostrazioni e smette di funzionare appena il compito diventa serio, per tre motivi che si vedono sempre.
- Il contesto si sporca. Le istruzioni per la ricerca inquinano quelle per la scrittura, e il modello mescola i due registri.
- Non sai dove si è rotto. Se il risultato è sbagliato, hai un blocco unico da riscrivere invece di un passaggio da correggere.
- Non puoi specializzare. Un solo prompt significa un solo modello e un solo insieme di strumenti, anche quando le fasi avrebbero bisogno di cose diverse.
Dividere il lavoro in ruoli risolve tutti e tre i punti insieme. Ogni agente ha un contesto stretto, un compito verificabile e i propri strumenti. Il costo di questa pulizia è reale, e conviene saperlo prima: più agenti significa più chiamate al modello, quindi più token e più tempo.
I quattro oggetti che devi conoscere
CrewAI ha una superficie piccola. Se capisci questi quattro oggetti, il resto della documentazione diventa leggibile.
Agent, l'agente
Un agente è definito da tre campi testuali che finiscono davvero dentro il prompt: role (chi è), goal (cosa deve ottenere) e backstory (come ragiona). A questi si aggiungono gli strumenti in tools e il modello in llm. Vale la pena scriverli con cura: sono l'unica leva che hai sul comportamento dell'agente.
Task, il compito
Un compito ha una description, che dice cosa fare, e un expected_output, che descrive la forma del risultato. Il secondo campo è quello che i principianti trattano come un commento e che invece determina se il crew produce qualcosa di usabile o un tema svolto. Se vuoi una tabella con quattro colonne, scrivilo lì.
Crew, la squadra
Il crew mette insieme agenti e compiti sotto un processo, e si avvia con kickoff(). Accetta un dizionario di inputs i cui valori sostituiscono i segnaposto scritti fra parentesi graffe dentro ruoli, obiettivi e descrizioni. È così che lo stesso crew serve per settori diversi.
Flow, il flusso
I Flow sono l'altra metà del framework, quella deterministica: passi collegati da eventi con i decoratori @start e @listen, stato condiviso e persistente, possibilità di riprendere dopo un errore. Servono quando l'autonomia degli agenti è un rischio invece di un vantaggio.
Sequential o hierarchical
Il campo process del crew decide come i compiti arrivano agli agenti, ed è una scelta con conseguenze concrete sul conto finale.
| Processo | Come funziona | Quando conviene |
|---|---|---|
sequential | I compiti vengono eseguiti nell'ordine in cui li hai scritti e ognuno riceve l'output del precedente. | Quasi sempre. Prevedibile, economico, facile da leggere nei log. |
hierarchical | CrewAI crea un agente manager che assegna i compiti, valuta gli output e può rimandarli indietro. Richiede un modello indicato in manager_llm. | Quando l'ordine dei passaggi non è noto in partenza o serve una revisione automatica del lavoro. |
attenzione
Il processo gerarchico costa di più
Crew o Flow: le due metà del framework
È la domanda che divide chi ha letto la documentazione da chi ha solo seguito un tutorial. La differenza non è tecnica, è di filosofia del controllo.
Un Crew delega la strategia agli agenti: tu dichiari l'obiettivo, loro decidono i passaggi. Ottieni flessibilità e paghi in imprevedibilità, perché due esecuzioni identiche possono seguire strade diverse. Un Flow fa il contrario: i passaggi li scrivi tu, l'evento di un passo innesca il successivo, lo stato è tuo e ispezionabile.
Nei progetti che reggono la produzione i due si usano insieme: il Flow governa la struttura, e chiama un Crew solo nei punti dove l'autonomia produce valore. Se ti stai chiedendo quale scegliere per iniziare, parti dal Crew: capirai prima dove ti serve il controllo. La guida dedicata ai Flows entra nel dettaglio con il codice.
Come si scrive, davvero
Dalla versione 1.x il comando crewai create genera un progetto con la configurazione degli agenti in file separati. L'API Python diretta resta però pienamente supportata, ed è quella giusta per capire cosa succede: qui c'è un crew completo, senza scaffolding.
from crewai import Agent, Task, Crew, Process
analista = Agent(
role="Analista di bilanci",
goal="Trovare i segnali di rischio in {azienda}",
backstory="Legge i numeri prima delle narrazioni.",
llm="gpt-5.4-mini",
max_iter=8, # tetto ai giri a vuoto
)
analisi = Task(
description="Analizza i dati di {azienda} e isola 3 rischi.",
expected_output="3 punti: rischio, evidenza, impatto stimato.",
agent=analista,
)
crew = Crew(agents=[analista], tasks=[analisi], process=Process.sequential)
esito = crew.kickoff(inputs={"azienda": "Rossi Srl"})
print(esito.raw) # il testo finale
print(esito.token_usage) # quanto è costatonota
Guarda sempre token_usage
kickoff() porta con sé il conteggio dei token dell'intera esecuzione. È il numero da leggere prima di decidere se un crew può girare cento volte al giorno o solo dieci.Cosa è gratis e cosa si paga
Qui si genera la maggior parte della confusione, perché lo stesso nome copre un progetto open source e un prodotto commerciale.
- Il framework è gratuito e lo resta. Licenza MIT, codice su GitHub, nessun limite di esecuzioni, nessuna registrazione.
- I token del modello li paghi sempre tu. Su qualsiasi piano e con qualsiasi fornitore. È la voce di costo che conta davvero, e cresce con il numero di agenti.
- La piattaforma commerciale è un prodotto a parte. Ha un piano gratuito limitato a 50 esecuzioni al mese e un piano enterprise a preventivo. Non serve per usare il framework.
La pagina sulla piattaforma commerciale spiega cosa contiene, come si è chiamata nel tempo e in quali casi ha senso valutarla.
Quando CrewAI non è la scelta giusta
Un riferimento serve a poco se elenca solo i pregi. Ci sono situazioni in cui conviene guardare altrove, e riconoscerle in anticipo fa risparmiare settimane.
- Il compito è uno solo. Se non c'è divisione del lavoro, un singolo agente scritto con una libreria minimale fa lo stesso lavoro con meno strati in mezzo.
- Il processo è rigido e regolamentato. Con ramificazioni condizionali, ritorni allo stato precedente e tracciabilità obbligatoria, LangGraph offre un controllo più esplicito. I Flows accorciano la distanza ma non la annullano.
- Nessuno in squadra scrive Python. Se il vincolo è l'assenza di sviluppatori, il confronto vero è con strumenti visuali come n8n, non con un altro framework.
- Il budget per i token è rigido. I sistemi multi agente consumano molto e in modo variabile. Se il costo per esecuzione deve essere prevedibile al centesimo, una catena deterministica è più adatta.
Chi c'è dietro
Il progetto è stato creato da João Moura, ingegnere brasiliano che prima guidava l'ingegneria in Clearbit, con la prima pubblicazione su PyPI a dicembre 2023. Attorno al framework è nata CrewAI Inc., che nell'ottobre 2024 ha annunciato 18 milioni di dollari di finanziamento fra un round seed guidato da Boldstart Ventures e una serie A da 12,5 milioni guidata da Insight Partners.
Alla data di questo aggiornamento il repository conta circa 57.200 stelle su GitHub e il pacchetto viaggia intorno ai 22 milioni di download mensili su PyPI. Sono numeri di attenzione e di installazioni, non di adozione in produzione: vanno letti per quello che sono.