CrewAI + Ollama : coordinare diversi agenti IA in locale

#Perché orchestrare una crew CrewAI in locale

Il pattern multi-agente parte da una semplice constatazione: suddividere un compito complesso tra più agenti specializzati dà risultati migliori rispetto a un unico prompt gigantesco. Ogni agente ha un ruolo chiaro, un obiettivo preciso e vede solo la propria parte del lavoro. CrewAI è il framework Python che formalizza questa suddivisione — ruoli, compiti, collaborazione sequenziale o gerarchica — senza l'onere di collegare da sé gli elementi di un grafo di stati.

Eseguire questa crew su Ollama anziché su GPT-4 o Claude cambia tre cose. Innanzitutto la riservatezza: una pipeline multi-agente moltiplica le chiamate al modello e quindi le potenziali fughe di dati verso terzi; in locale, nulla esce dalla macchina. Poi il costo: una crew loquace può consumare centinaia di migliaia di token per esecuzione, il che diventa rapidamente costoso con un’API fatturata a token — in locale il costo marginale è nullo. Infine il controllo: scegli il modello, la quantizzazione e il contesto, e procedi per iterazioni senza quote né limiti alla frequenza delle richieste.

#I 4 componenti fondamentali di CrewAI

Prima di scrivere una riga, bisogna conoscere la terminologia. CrewAI si basa su quattro oggetti che si incastrano tra loro. Comprenderli evita il 90% degli errori di progettazione di una crew.

Agente

Un LLM con un'identità: un ruolo («Analista di mercato»), un obiettivo (goal) e una storia (backstory) che definiscono il suo comportamento. Ogni agente può utilizzare il proprio modello Ollama.

Task

Un'unità di lavoro assegnata a un agente: una descrizione, un risultato atteso (expected_output) e, spesso, degli strumenti. È la task, non l'agente, che contiene l'istruzione concreta.

Tool

Una capacità esterna che un agente può chiamare: ricerca web, lettura di file, query SQL, calcolo. Senza strumenti, un agente fa solo ragionamenti su ciò che già conosce.

Crew

Il team: l'elenco degli agenti, l'elenco delle attività e il processo che determina l'ordine di esecuzione (sequential o hierarchical). È l'oggetto che avvii con kickoff().

Il processo merita una precisazione. In modalità sequential, le attività vengono eseguite nell'ordine dichiarato e l'output di una alimenta la successiva: perfetto per una catena ricerca → redazione → revisione. In modalità hierarchical, un agente «manager» (un LLM dedicato) delega e coordina gli altri. La modalità gerarchica è più potente ma molto più impegnativa per un modello locale, perché il manager deve ragionare su chi fa cosa: inizia sempre con la modalità sequenziale.

#Prerequisiti e scelta dei modelli

Ollama funzionante

Daemon avviato, endpoint su http://localhost:11434. Verifica con « ollama list » che sia presente almeno un modello in grado di usare strumenti.

Python 3.10+ e un venv

CrewAI si installa correttamente in un ambiente virtuale isolato. Evita di installarlo nel Python di sistema.

VRAM e pazienza

Un sistema multi-agente concatena le chiamate: ogni attività = uno o più scambi di richiesta e risposta con il modello. Prevedi un modello da almeno 8B, idealmente nella fascia da 12 a 24B, affinché il ragionamento regga.

Un modello capace di utilizzare strumenti

Per dotare gli agenti di strumenti, serve un modello che supporti il function calling: Qwen 3.5, Qwen 3.8, Mistral Small o GLM 4.7 Flash. Un modello senza supporto per l'uso di strumenti può solo ragionare in forma testuale.

#Installare CrewAI e collegarlo a Ollama

CrewAI si installa tramite pip. Il pacchetto crewai-tools fornisce in aggiunta una libreria di strumenti pronti all'uso (ricerca, file, scraping).

# Créer et activer un environnement virtuel
python -m venv .venv
source .venv/bin/activate   # Windows : .venv\Scripts\activate

# Installer CrewAI et sa bibliothèque d'outils
pip install crewai crewai-tools

Il punto chiave del collegamento locale: CrewAI si appoggia a LiteLLM per comunicare con i modelli. Per usare Ollama, si antepone al nome del modello il prefisso «ollama/» e si imposta l'URL di base sull'indirizzo del daemon locale. Assicurati di aver già scaricato il modello.

# Un modèle solide et tool-capable pour les agents
ollama pull qwen3.5:9b

# Un modèle plus léger pour les tâches simples (optionnel)
ollama pull qwen3.5:4b

from crewai import LLM

# Un LLM CrewAI branché sur Ollama en local
local_llm = LLM(
    model="ollama/qwen3.5:9b",
    base_url="http://localhost:11434",
    temperature=0.3,   # bas = plus déterministe, utile pour une crew
)

#Prima crew: definire ruoli e compiti

Creiamo una crew classica e subito utile: un ricercatore che raccoglie le informazioni, poi un redattore che le organizza. È la struttura di base che riutilizziamo per il monitoraggio informativo, la sintesi documentale o la generazione di contenuti. Definiamo innanzitutto gli agenti, con ruoli chiari.

from crewai import Agent

chercheur = Agent(
    role="Analyste de recherche",
    goal="Rassembler des faits précis et vérifiables sur {sujet}",
    backstory=(
        "Tu es un analyste rigoureux. Tu distingues les faits "
        "des opinions et tu ne retiens que l'information solide."
    ),
    llm=local_llm,
    verbose=True,
)

redacteur = Agent(
    role="Rédacteur technique francophone",
    goal="Produire une synthèse claire et structurée en français",
    backstory=(
        "Tu écris pour un public technique. Tu vas droit au but, "
        "sans jargon inutile ni remplissage marketing."
    ),
    llm=local_llm,
    verbose=True,
)

Il ruolo, il goal e la backstory non sono elementi decorativi: costituiscono il system prompt di ogni agente. Un ruolo vago («Assistente») produce un agente vago. Sii specifico e definisci un atteggiamento — è questo che impedisce a un modello piccolo di uscire dai limiti stabiliti. Nota il placeholder {sujet}: CrewAI lo inserisce all’avvio a partire dagli input.

Poi viene il cuore del lavoro: le attività. Ogni attività indica un agente, descrive cosa deve produrre e, soprattutto, specifica un expected_output. Questo campo è la leva per la qualità più sottovalutata di CrewAI: più è concreto, più l'output è ben definito.

from crewai import Task

tache_recherche = Task(
    description=(
        "Recherche les points clés sur {sujet}. Identifie 5 à 7 "
        "faits marquants, chiffrés quand c'est possible."
    ),
    expected_output="Une liste à puces de 5 à 7 faits sourcés et concis.",
    agent=chercheur,
)

tache_redaction = Task(
    description=(
        "À partir des faits rassemblés, rédige une synthèse "
        "structurée de 300 mots sur {sujet}, en français."
    ),
    expected_output="Un texte de ~300 mots avec un titre et 3 sections.",
    agent=redacteur,
    context=[tache_recherche],   # nourrie par la sortie de la recherche
)

Il parametro context collega esplicitamente le attività: la redazione riceve l'output della ricerca. In modalità sequenziale, la successione delle attività è già implicita, ma dichiarare context rende la dipendenza chiara e il passaggio delle informazioni più affidabile. Infine si assembla la crew e la si avvia.

from crewai import Crew, Process

crew = Crew(
    agents=[chercheur, redacteur],
    tasks=[tache_recherche, tache_redaction],
    process=Process.sequential,
    verbose=True,
)

resultat = crew.kickoff(inputs={"sujet": "les LLM open-weight en 2026"})
print(resultat)

1. 01
   Il ricercatore entra in azione

   Il suo LLM locale riceve il proprio ruolo e la descrizione del compito di ricerca e produce l'elenco di fatti atteso.
2. 02
   L'output transita

   CrewAI passa il risultato della ricerca come contesto all'attività di redazione, conformemente al campo context.
3. 03
   Il redattore entra in azione

   Il suo agente riceve i fatti e redige la sintesi di 300 parole, secondo le indicazioni del suo expected_output.
4. 04
   kickoff() restituisce il risultato finale

   L'output dell'ultima attività viene restituito. verbose=True mostra tutto il ragionamento intermedio nel terminale.

#Dare degli strumenti agli agenti

Un agente senza strumenti si limita a ragionare su ciò che il modello ha già in memoria: incontra presto dei limiti ed è soggetto ad allucinazioni. Gli strumenti gli danno capacità concrete: leggere un file, cercare sul web, interrogare un database. crewai-tools ne fornisce una serie pronta all'uso, e puoi scrivere i tuoi.

from crewai_tools import FileReadTool
from crewai.tools import tool

# Outil intégré : lire un fichier local
lecteur = FileReadTool()

# Outil maison : décoré avec @tool
@tool("Compteur de mots")
def compter_mots(texte: str) -> int:
    """Compte le nombre de mots d'un texte donné."""
    return len(texte.split())

# On équipe l'agent des deux outils
chercheur = Agent(
    role="Analyste de recherche",
    goal="Analyser des documents locaux sur {sujet}",
    backstory="Tu analyses des sources internes avec rigueur.",
    tools=[lecteur, compter_mots],
    llm=local_llm,
    verbose=True,
)

È qui che la scelta del modello diventa decisiva. Per utilizzare uno strumento, l'agente deve generare un'invocazione di funzione strutturata (function calling) che CrewAI intercetta e esegue. Un modello che non padroneggia l'uso degli strumenti ignora lo strumento o produce un JSON invalido. Qwen 3.5, Qwen 3.8, Mistral Small e GLM 4.7 Flash gestiscono bene questo meccanismo; molti modelli piccoli e generici no.

#Quali modelli locali reggono l'orchestrazione di più agenti

È la vera domanda di questa guida. L'uso di più agenti è molto più impegnativo della chat: ogni agente deve attenersi a un ruolo, rispettare un formato di output e spesso chiamare strumenti, il tutto concatenando le attività senza perdere il filo. Un modello troppo piccolo non riesce a stare al passo. Ecco i livelli realistici, in Q4_K_M, con la VRAM associata.

8B (≈5-7 GB) — limite inferiore

Granite 4.2 8B (5,3 GB), Qwen 3.5 9B (6,6 GB). Sono in grado di gestire una semplice crew sequenziale con 2 agenti e strumenti di base. RTX 3060 12 GB, RTX 4070. Al di sotto di queste dimensioni, l'uso di più agenti diventa poco affidabile.

16 GB (≈14 GB) — raccomandato

gpt-oss 20B o Mistral Small 24B (≈14 GB, quest'ultimo molto valido in francese), oppure Qwen 3.5 9B in Q8 (11 GB). Un buon compromesso: ragionamento solido, uso affidabile degli strumenti, rispetto dei ruoli senza deviazioni. Dalla RTX 4070 da 12 GB (al limite) alla RTX 4080 da 16 GB. È il punto di equilibrio per la maggior parte dei team di agenti.

24 GB (≈18-19 GB) — con margine

Qwen 3.8 27B (18 GB, 262k ctx) o il MoE Qwen3-Coder 30B-A3B (19 GB). Gestisce crew più lunghe, più strumenti e una modalità gerarchica leggera. RTX 4090 da 24 GB o Mac M4 Pro con memoria unificata. Ricorda di impostare il ragionamento di Qwen 3.8 su « low », altrimenti ragiona troppo all'interno di una crew.

MoE 35B+ (≈23-32 GB) — vicino al cloud

Qwen 3.6 35B-A3B (23 GB) o Qwen3-Coder 30B-A3B in Q8 (32 GB). La qualità di coordinamento si avvicina a quella delle API cloud, ora raggiungibile già a 32 GB grazie alle architetture MoE. Mac Studio con memoria unificata ampia o multi-GPU. Riservato alle squadre ambiziose.

Suggerimento architetturale: non è necessario che tutti gli agenti utilizzino lo stesso modello. Assegna compiti semplici (riformulazione, conteggio, estrazione) a un modello piccolo e veloce (Qwen 3.5 4B, Granite 4.2 8B), e riserva un Qwen 3.8 27B o un MoE 35B agli agenti che ragionano o orchestrano. Basta istanziare semplicemente due oggetti LLM e assegnarli per agente.

gros = LLM(model="ollama/qwen3.8:27b", base_url="http://localhost:11434")
petit = LLM(model="ollama/granite4.2:8b", base_url="http://localhost:11434")

stratege = Agent(role="Stratège", goal="...", llm=gros)
assistant = Agent(role="Assistant", goal="...", llm=petit)

#Costi e limiti rispetto a una crew su API cloud

L'argomento decisivo a favore dell'esecuzione in locale è il costo. Una crew è loquace per natura: ogni agente rilegge il contesto, ragiona, richiama strumenti e l'espansione del contesto nel corso delle attività aumenta il numero di token. Una sola esecuzione un po' ambiziosa può consumare centinaia di migliaia di token. Con un'API fatturata per token, una pipeline eseguita ripetutamente durante lo sviluppo diventa presto onerosa; in locale, ogni iterazione è gratuita dopo l'acquisto dell'hardware.

Costo — vantaggio locale

Costo per token pari a zero. Puoi iterare, rilanciare le esecuzioni e fare debug senza un contatore dei costi che continua a girare. L'uso di più agenti, che consuma molte risorse, è quello in cui l'esecuzione locale permette di ammortizzare più rapidamente il costo della GPU.

Confidenzialità — vantaggio locale

Nessuna delle chiamate — e sono numerose — esce dalla macchina. Decisivo per il codice proprietario, i dati dei clienti o qualsiasi cosa soggetta a un NDA o al RGPD.

Qualità di coordinamento — vantaggio cloud

GPT-4 e Claude gestiscono la modalità gerarchica, le catene lunghe e l'uso complesso degli strumenti con un'affidabilità che un modello locale da 14B non raggiunge. Il divario aumenta quando la crew diventa più complessa.

Velocità — dipende dall’hardware

Il cloud risponde spesso più velocemente di una GPU consumer con i modelli di grandi dimensioni. Una squadra di 4 agenti su un modello locale da 32B può richiedere diversi minuti per ogni esecuzione.

Una lettura onesta: l'esecuzione in locale eccelle con crew sequenziali ben strutturate, in cui ogni agente ha un ruolo chiaro e un compito circoscritto. Mostra i suoi limiti nell'orchestrazione gerarchica ambiziosa, in cui un modello da 14B fatica a svolgere il ruolo del manager che delega. La strategia giusta è spesso ibrida — prototipare ed eseguire in locale, riservando il cloud alle fasi in cui il coordinamento supera ciò che il tuo modello riesce a gestire. Un proxy come LiteLLM permette proprio di instradare le richieste tra i due.

#Risoluzione dei problemi

L'agente ignora i suoi strumenti

Il modello non supporta il function calling. Passa a Qwen 3.5, Qwen 3.8, Mistral Small o GLM 4.7 Flash, e verifica che l'agente abbia la lista tools=[...].

« Connection refused » / errore litellm

Il daemon Ollama non è avviato o base_url è errato. Controlla « ollama ps » e verifica che l'URL sia http://localhost:11434.

L'agente si ripete o non si ferma

Modello troppo piccolo per il compito o troppi strumenti. Passa a un modello più grande (almeno Qwen 3.5 9B), riduci il numero di strumenti, abbassa la temperatura e imposta max_iter sull'agente.

Output non conformi al formato / expected_output ignorato

Ruolo troppo vago o expected_output poco chiaro. Rendili molto concreti e preferisci un modello più capace (Qwen 3.8 27B, Mistral Small 24B) che segue meglio le istruzioni sul formato.

Crew molto lenta

Per mancanza di VRAM, il modello viene eseguito in parte nella RAM di sistema e sulla CPU (« ollama ps » lo mostra), oppure più modelli si rimuovono a vicenda dalla memoria. Passa a un modello di taglia inferiore o usa un unico modello per tutto.

La modalità gerarchica va fuori controllo

Il LLM che funge da manager non è all'altezza. Torna a Process.sequential, oppure riserva un Qwen 3.8 27B o un MoE 35B al ruolo di manager.

#Per approfondire

Una crew CrewAI locale si basa su componenti già trattati sul sito. Queste guide approfondiscono gli argomenti di questa guida:

Creare un agente IA locale in Python con LangChain e Ollama

Le basi di un singolo agente — strumenti, ciclo di ragionamento — prima di passare a un sistema multi-agente.

Function calling e output JSON strutturati con Ollama

Per capire il meccanismo di tool-use da cui dipendono gli strumenti dei tuoi agenti.

LiteLLM: un proxy unificato locale e cloud

Per instradare una crew tra Ollama locale e un’API cloud in base al compito, nell’ambito di una strategia ibrida.