Gianluca Mazza — Dove CrewAI fallisce in produzione

Perché è importante

CrewAI è davvero valido per ciò per cui è stato progettato: prototipazione rapida di pipeline multi-agent con definizioni di ruolo leggibili e dichiarative. Quando mostri una crew CrewAI in una demo — "Senior Researcher", "Market Analyst", "Report Writer" — la struttura è immediatamente comprensibile anche a stakeholder non tecnici. Questa leggibilità ha un valore reale.

Nel mio lavoro in produzione, però, ho visto quel valore ribaltarsi. L'astrazione dichiarativa che rende leggibili le crew le rende anche opache quando qualcosa va storto. Ho migrato due sistemi basati su CrewAI a LangGraph. In entrambi i casi, la migrazione è arrivata dopo modalità di errore che l'architettura di CrewAI non mi dava strumenti puliti per gestire. Di seguito descrivo quei problemi e le sostituzioni che ho implementato.

Voglio essere preciso sull'ambito: CrewAI ha continuato a evolversi, e alcune di queste limitazioni potrebbero essere state affrontate in versioni successive. Le modalità di errore che descrivo derivano da deployment di produzione specifici, non da una critica teorica del framework.

1. L'astrazione del ruolo e dove si rompe

L'astrazione centrale di CrewAI è l'Agent, definito da role, goal e backstory. Il framework instrada i task agli agenti in base all'identità del ruolo. È intuitivo: rispecchia il modo in cui i team vengono descritti nel linguaggio naturale.

Il problema che ho osservato in produzione è questo: l'identità del ruolo viene applicata tramite iniezione nel prompt, non tramite codice. Quando definisci un agente come "Senior Researcher" con l'obiettivo di "find authoritative sources", quel vincolo vive nel system prompt. L'LLM che alimenta l'agente può deviare da quel vincolo, soprattutto quando il task è ambiguo o quando l'agente riceve istruzioni da un altro agente che suggeriscono implicitamente un comportamento diverso.

# What you write
researcher = Agent(
    role="Senior Market Researcher",
    goal="Identify and synthesize data from authoritative sources only.",
    backstory="You have 15 years of experience...",
    tools=[search_web, read_url]
)
# What actually constrains the agent:
# → role/goal/backstory are concatenated into a system prompt.
# → The LLM's behavior is prompt-constrained, not code-constrained.
# → Under adversarial input or conflicting task context, the constraint drifts.

Non considero questo un bug di CrewAI. È una proprietà intrinseca dell'enforcement dei ruoli basato su prompt. In una pipeline demo breve, i prompt reggono. In una pipeline di produzione più lunga, dove gli agenti si passano output tra più step, ho visto il prompt drift diventare frequente: un agente riceve contesto che rimodella implicitamente il suo ruolo, e il vincolo originale si indebolisce.

2. Opacità del routing dei task

In una crew CrewAI, il processo decide quale agente gestisce quale task. In modalità Process.hierarchical, un manager LLM decide dinamicamente il routing. In Process.sequential, i task vengono assegnati agli agenti al momento della definizione.

Il problema che ho incontrato in produzione è che nessuna delle due modalità produce decisioni di routing esplicite e ispezionabili.

In modalità hierarchical, la decisione di routing del manager resta dentro una chiamata LLM. Non posso scrivere un test unitario che asserisca: "dato questo task, instrada al researcher". Posso loggare la decisione, ma non posso asserirla in modo deterministico. Quando il routing va storto — per esempio il manager instrada un task di scrittura al researcher perché la descrizione del task menziona "analyzing" il contenuto — la diagnosi richiede leggere le trace LLM, non ispezionare il codice.

In modalità sequential, il routing è fissato al momento della definizione. Questo lo rende deterministico, ma poco flessibile. Qualsiasi routing condizionale — "se il researcher restituisce risultati insufficienti, instrada a un agente alternativo" — richiede di aggirare l'astrazione del processo sequenziale.

Per rendere il routing osservabile, l'ho sostituito con edge condizionali di LangGraph e segnali espliciti nello stato. Ogni decisione di routing è una funzione Python che legge campi dello stato e restituisce il nome di un nodo.

# LangGraph: routing is code, not LLM inference
def route_after_research(state: AgentState) -> str:
    result = state.get("research_status")
    if result == "insufficient":
        return "alternate_search"
    if result == "complete":
        return "writer"
    return "error_handler"

workflow.add_conditional_edges("researcher", route_after_research)

La logica di routing è esplicita, versionata nel codice e testabile senza chiamate LLM. Se il routing sbaglia, ottengo un ramo Python sbagliato e posso debuggare quel ramo in isolamento. In CrewAI hierarchical, invece, un errore di routing produce un output LLM sbagliato, che posso ricostruire solo ispezionando le trace.

3. Gestione dello stato e problema del contesto inter-task

I task CrewAI passano output tra agenti come stringhe. L'output del Task A diventa il contesto di input del Task B. È semplice da ragionare quando ci sono due o tre agenti con task ben delimitati. Ho visto però questa scelta rompersi quando l'output è lungo, quando il Task B deve accedere in modo strutturato a parti specifiche dell'output del Task A, o quando più task confluiscono in un task di sintesi.

La modalità di errore è una combinazione di context overflow e context dilution. Se un output da 4000 token del researcher viene iniettato nel contesto del writer prima delle istruzioni del writer stesso, il system prompt del writer compete con 4000 token di ricerca per l'attenzione. In quelle condizioni, il writer tende a perdere il vincolo originale.

Nel mio deployment l'ho osservato come degrado qualitativo nelle pipeline più lunghe. L'output del writer diventava meno strutturato, iniziava a parafrasare la ricerca alla lettera invece di sintetizzarla, e occasionalmente perdeva il filo del task originale. Queste regressioni erano non deterministiche: non comparivano a ogni run, ma soprattutto quando l'output della ricerca era particolarmente lungo o quando il task originale era sotto-specificato.

Per ridurre questo accoppiamento implicito, ho sostituito il passaggio di stringhe con stato tipizzato e strutturato, accessibile per campo.

class ResearchFinding(BaseModel):
    claim: str
    source_url: str
    confidence: float
    relevance_to_query: str

class AgentState(TypedDict):
    original_task: str
    research_findings: Annotated[list[ResearchFinding], operator.add]
    draft: str
    revision_count: int

Il writer accede a state["research_findings"] e li formatta secondo necessità. Non vede mai la stringa completa di output del researcher. Lo stato resta tipizzato, strutturato ed esposto selettivamente a ciascun agente in base a ciò di cui ha effettivamente bisogno.

4. Integrazione della memory e problema delle dipendenze esterne

I sistemi di memory integrati di CrewAI (short-term, long-term, entity) sono interessanti nelle demo. In produzione, però, ho visto che introducono dipendenze esterne difficili da rendere operative, soprattutto in ambienti regolamentati dove contano data residency, access control e audit trail.

La long-term memory richiede un vector store. La entity memory traccia entità specifiche tra interazioni degli agenti tramite una chiamata LLM interna a CrewAI, senza modello configurabile, senza prompt osservabile e senza contratto di output strutturato. In pratica, la entity memory diventa una black box dentro un'altra black box.

Per rendere esplicito questo livello, ho sostituito la memory integrata con un'integrazione RAG esposta come tool chiamato dall'agente, non come livello nascosto. L'agente chiama esplicitamente retrieve_memory(query) come tool; il risultato viene restituito come oggetto tipizzato.

class MemoryResult(BaseModel):
    status: Literal["found", "empty"]
    entries: list[MemoryEntry] = []
    query_used: str

@tool(args_schema=MemoryQuery)
def retrieve_memory(query: str, max_results: int = 5) -> MemoryResult:
    results = vector_store.search(query, k=max_results)
    if not results:
        return MemoryResult(status="empty", query_used=query)
    return MemoryResult(status="found", entries=[MemoryEntry.from_hit(r) for r in results], query_used=query)

Ogni accesso alla memory finisce nella tool trace: è visibile, auditabile e ispezionabile. Posso vedere quale query è stata usata, cosa è stato recuperato e come l'agente lo ha usato nella risposta successiva. Con la memory integrata di CrewAI non avevo lo stesso livello di controllo, perché il retrieval restava nascosto negli internals del framework.

5. Observability e gap di debugging

CrewAI fornisce output verbose e, nelle versioni più recenti, hook di telemetry. Nel mio uso, però, debuggare una crew che fallisce in produzione richiede comunque leggere trascrizioni LLM per capire perché un agente ha fatto ciò che ha fatto. Non ho una timeline strutturata dello stato che posso interrogare con domande come: "qual era l'output del researcher allo step 3, e perché il manager ha instradato lo step 4 all'analyst invece che al writer?"

Questo non è specifico di CrewAI. È una proprietà dei sistemi in cui routing e stato vivono nel contesto LLM invece che in strutture dati ispezionabili. In produzione, però, rende il debugging più difficile rispetto a sistemi LangGraph equivalenti, dove ogni transizione di stato viene persistita in un checkpointer ed è replayable.

La sessione di debugging più dispendiosa nel mio deployment CrewAI riguardava un agente che modificava silenziosamente i propri argomenti del tool prima dell'esecuzione. Cambiava le query di ricerca per farle coincidere con ciò che "si aspettava" di trovare, invece di mantenere ciò che gli era stato chiesto di trovare. Per intercettarlo, ho dovuto aggiungere logging custom dentro ogni tool wrapper. In pratica, ho modificato il codice per ottenere un livello di observability che in LangGraph avevo già tramite stato persistente e trace delle transizioni.

Questo costo si accumula nel tempo. Il primo incidente di produzione che non riesco a diagnosticare rapidamente è spesso quello che sposta il lavoro da debugging locale a ricostruzione dell'architettura.

6. Quando usare comunque CrewAI

Nulla di quanto sopra è un motivo per non usare mai CrewAI. È un motivo per usarlo al livello giusto.

Uso volentieri CrewAI per automazione interna in cui un umano verifica l'output prima che abbia conseguenze, prototipazione rapida per capire se valga la pena costruire un approccio multi-agent, demo e presentazioni in cui definizioni dichiarative dei ruoli aiutano audience non tecniche a leggere l'architettura.

La domanda che mi pongo prima di usare CrewAI in produzione è semplice: un umano può verificare ogni output prima che abbia conseguenze? Se sì, le limitazioni di observability possono essere gestibili. Se invece il sistema compie azioni autonome — invia email, scrive su database, effettua chiamate API — la mancanza di routing e stato ispezionabili rende più difficile l'analisi post-incidente.

Per sistemi ad azione autonoma in domini regolamentati, nel mio caso il costo di migrazione a LangGraph è stato giustificato dalla capacità di diagnosticare incidenti di produzione con stato persistente, recovery deterministica ed eval riproducibili.

Il category frame

L'astrazione dei ruoli di CrewAI è una delle idee più utili nel tooling multi-agent: ha reso lo spazio del problema comprensibile a un pubblico molto più ampio. Le modalità di errore che ho descritto non sono fallimenti dell'idea. Sono fallimenti dell'enforcement basato su prompt, della gestione del contesto tramite passaggio di stringhe e dei layer di memory nascosti: scelte implementative che ottimizzano la leggibilità a scapito dell'ispezionabilità.

LangGraph è meno leggibile. È più debuggabile. In produzione, nel mio lavoro, quello scambio è quasi sempre quello corretto.

Se stai valutando se costruire con CrewAI, LangGraph o qualcos'altro — o stai pianificando una migrazione — scrivimi. La decisione dipende molto dai tuoi requisiti di autonomia e dai tuoi vincoli di observability.