9Gli agenti: role, goal, backstory

Nel capitolo 8 hai creato due agenti quasi copiando. Adesso guardiamo da vicino un AgentAgent (in CrewAI): Il membro della squadra. Si definisce con tre testi obbligatori — role, goal, backstory — più modello e strumenti opzionali. glossario di CrewAI: che cosa scrivere in ogni campo, quali opzioni lo rendono più affidabile e quando conviene non aggiungerne un altro.

Pensa a un annuncio di lavoro per una cucina di ristorante. Il ruolo è il titolo del posto («pasticciere»), l'obiettivo è ciò che gli chiedi di ottenere («dolci pronti per le 19, senza glutine quando richiesto»), la storia è il curriculum che spiega come lavora. Più l'annuncio è preciso, più la persona giusta sa cosa fare. Con un LLMLLM: Large Language Model, grande modello linguistico: un programma addestrato su enormi quantità di testo che, data una frase, prevede le parole che seguono. È il motore di ChatGPT, Claude, Gemini. glossario vale la stessa cosa: questi testi finiscono nel promptPrompt: Il testo che dai in ingresso a un modello: domanda, istruzioni, esempi. La qualità della risposta dipende molto dalla chiarezza del prompt. glossario e orientano ogni risposta.

Tre testi obbligatori#

Un agente di CrewAI ha tre parametri obbligatori, tutti testi. La guida ufficiale li riassume così: chi è l'agente, che cosa vuole ottenere, perché è la persona giusta.

from crewai import Agent

ricercatore = Agent(
    role="Ricercatore di viaggi specializzato in città d'arte italiane",  # chi è
    goal="Trovare 3 attività per un weekend a {citta}, spiegando perché valgono",  # che cosa vuole
    backstory="Hai organizzato viaggi culturali per vent'anni e distingui i luoghi famosi da quelli davvero belli.",  # perché è adatto
)

Tutto il resto (modello, strumenti, limiti) è facoltativo e ha un valore predefinito. Nota il segnapostoSegnaposto {…}: Una parola tra graffe, come {citta}, dentro i testi di agenti e task. Al kickoff(inputs={...}) viene sostituita con il valore vero. glossario {citta}: funziona anche dentro i testi dell'agente, non solo nei task.

role#

Il rolerole: Il ruolo dell'agente, cioè il suo mestiere: "Analista finanziario senior". Orienta il modo in cui il modello ragiona. glossario è il mestiere dell'agente. La regola della guida ufficiale è: specifico, non generico. Un «ricercatore senior di dati» ragiona in modo diverso da un «assistente di ricerca», anche con lo stesso task.

goal#

Il goalgoal: L'obiettivo personale dell'agente, con il criterio di qualità: "Trovare i 5 rischi principali con le fonti". glossario è l'obiettivo personale dell'agente. Deve dire quale risultato ottenere e con quale qualità, non soltanto l'attività.

backstory#

La backstorybackstory: La storia e lo stile dell'agente: esperienza, valori, modo di lavorare. È il suo "carattere" nel prompt. glossario è il «carattere» dell'agente: esperienza, competenze, stile di lavoro, standard di qualità. Ecco l'esempio della guida ufficiale, tradotto:

Sei un ricercatore esperto con 15 anni di esperienza nell'intelligenza artificiale.
Sei noto per trovare articoli poco conosciuti ma pertinenti e per trasformare
risultati complessi in indicazioni chiare. Citi sempre le fonti e segnali
apertamente quando non sei sicuro.

Che cosa mettere e che cosa lasciare fuori:

Le opzioni che userai più spesso#

Queste sono le opzioni facoltative che incontrerai in quasi tutti gli esempi del corso. I valori predefiniti sono quelli verificati su CrewAI 1.15.21.

import os

from crewai import Agent

MODELLO = os.getenv("MODEL", "openai/gpt-4.1-mini")

ricercatore = Agent(
    role="Ricercatore di viaggi specializzato in città d'arte italiane",
    goal="Trovare 3 attività per un weekend a {citta}, spiegando perché valgono",
    backstory="Hai organizzato viaggi culturali per vent'anni.",
    llm=MODELLO,     # il modello da usare: sempre esplicito
    tools=[],        # strumenti: per ora nessuno (capitolo 12)
    verbose=True,    # stampa i passaggi nel terminale (predefinito: False)
    max_iter=15,     # al massimo 15 giri di ragionamento (predefinito: 25)
    max_rpm=10,      # al massimo 10 richieste al minuto (predefinito: nessun limite)
)

llm: il modello#

llm accetta un testo nel formato provider/modello, per esempio "openai/gpt-4.1-mini" o "ollama/qwen2.5:7b". Nel corso passiamo sempre MODELLO, letto dal file .env come hai visto nel capitolo 7.

tools: gli strumenti#

tools è una listaLista: Una sequenza ordinata di valori tra parentesi quadre: [ricercatore, scrittore]. glossario di strumentiStrumento (tool): Una funzione che l'agente può chiamare per agire fuori dal modello: cercare sul web, leggere un file, interrogare un database, inviare una email. glossario: cercare sul web, leggere un file, interrogare un servizio. Li vedremo nel capitolo 12. Per ora ricorda due regole della guida ufficiale:

• un agente senza strumenti, se gli chiedi di cercare o leggere dati, li inventa: è esattamente l'allucinazioneAllucinazione: Quando un modello scrive con sicurezza una cosa falsa o inventata. Succede perché il modello genera testo plausibile, non verifica fatti. glossario che hai visto nel capitolo 8;
• meglio pochi strumenti mirati (da 3 a 5 al massimo) che tanti: con troppe scelte l'agente si confonde.

verbose#

Con verboseverbose: Opzione che fa stampare nel terminale ogni passaggio di agenti e task. Utile mentre impari e quando qualcosa non va. glossario=True l'agente stampa nel terminale ogni passaggio: il task che riceve, gli strumenti che usa, la risposta finale. Mentre impari tienilo sempre acceso. Il valore predefinito è False.

max_iter#

Un agente non risponde con un solo colpo: fa dei giri. A ogni giro il modello ragiona, decide se usare uno strumento, legge il risultato e riparte, finché pensa di aver finito. Il diagramma mostra il ciclo.

max_itermax_iter: Numero massimo di giri di ragionamento che un agente può fare su un task prima di dare la risposta migliore che ha. In CrewAI 1.15 il valore predefinito è 25. glossario è il numero massimo di giri. Quando lo raggiunge, l'agente deve consegnare la migliore risposta che ha.

Secondo la guida ufficiale la maggior parte dei task finisce in 3–8 giri. Per compiti semplici e ben descritti puoi scendere a 10–15, così un agente che gira a vuoto si ferma prima. Se un agente arriva spesso al limite, di solito il problema è il task troppo vago: correggi il task, non il limite.

max_rpm e max_execution_time#

max_rpm significa «richieste al minuto»: CrewAI rallenta l'agente per non superare quel numero. Serve quando il provider ti blocca con un rate limitRate limit: Il limite di richieste al minuto imposto da un provider. Superarlo dà errori temporanei. In CrewAI si rispetta con max_rpm. glossario. Puoi impostarlo anche sulla crew (capitolo 11). La documentazione dice che quello della crew prende il posto di quello dei singoli agenti, ma in CrewAI 1.15.21 il comportamento verificato è diverso: vale solo per gli agenti che non hanno un loro max_rpm. max_execution_time invece è un tempo massimo in secondi per un task: il predefinito è nessun limite, e la guida consiglia di impostarlo quando l'agente lavora sul serio, per evitare esecuzioni bloccate.

La delega tra colleghi#

Con allow_delegation=True l'agente può chiedere aiuto agli altri agenti della stessa crew: questa è la delegaDelega: La possibilità, per un agente con allow_delegation=True, di chiedere aiuto o passare un pezzo di lavoro a un collega della crew. glossario. In pratica CrewAI gli aggiunge due strumenti speciali, uno per affidare un lavoro a un collega e uno per fargli una domanda. Nel diagramma sopra, il collega prende il posto dello strumento.

capo_redattore = Agent(
    role="Capo redattore di una rivista di viaggi",
    goal="Consegnare guide corrette, chiedendo verifiche ai colleghi quando serve",
    backstory="Hai diretto redazioni per anni e non pubblichi nulla senza un controllo.",
    llm=MODELLO,
    allow_delegation=True,  # può affidare pezzi di lavoro agli altri agenti della crew
)

Il valore predefinito è False, e la guida ufficiale consiglia di lasciarlo così a meno che la delega serva davvero: in una crew con specialisti diversi, oppure nel processo gerarchico del capitolo 11. Senza confini chiari tra i compiti, gli agenti rischiano di passarsi il lavoro a vuoto, consumando giri e tokenToken: Il pezzetto di testo con cui ragiona un modello: una parola corta, un pezzo di parola o un segno di punteggiatura. Secondo le stime di OpenAI, in inglese un token vale in media circa ¾ di parola. I servizi a pagamento contano (e fanno pagare) i token. glossario.

Quanti agenti servono davvero#

La tentazione, all'inizio, è creare un agente per ogni passaggio. La guida ufficiale di CrewAI dice il contrario: parti da un agente solo e aggiungine un altro soltanto quando il lavoro richiede davvero una di queste cose:

• strumenti o permessi diversi: per esempio uno può scrivere su un servizio aziendale, l'altro solo leggere documenti;
• voci diverse tra cui il modello deve passare nettamente: chi scrive non parla come chi ricerca;
• modelli diversi: uno economico per i passaggi meccanici, uno più capace per la sintesi;
• controlli o formati di uscita diversi per ogni fase.

Il criterio pratico, tradotto dalla guida: se due «agenti» hanno lo stesso personaggio, gli stessi strumenti e lo stesso modello, sono un agente solo con un task più lungo. Un singolo agente può già usare più strumenti di fila (cercare, leggere una pagina, riassumere) e produrre un testo con più sezioni.

Il motivo è anche economico: ogni agente in più significa almeno una chiamata in più al modello e un passaggio di testo in più da un agente all'altro, quindi più token, più tempo e più occasioni di errore.

Un agente da solo, senza crew#

Se un agente basta, non ti servono né Task né Crew: puoi chiamare direttamente il metodoMetodo: Un'azione che un oggetto sa fare, chiamata con il punto e le parentesi: crew.kickoff() chiede all'oggetto crew di partire. glossario kickoff() dell'agente e passargli la richiesta come testo. È il modo che la guida ufficiale consiglia dentro i flowFlow: Il "copione" che orchestra passi, crew e agenti con uno stato condiviso, condizioni e diramazioni. La documentazione lo consiglia come struttura per le applicazioni vere. glossario (capitolo 16), quando ogni passo è il lavoro di un solo agente. Questo script completo lo mostra.

# /// script
# requires-python = ">=3.10,<3.14"
# dependencies = ["crewai[tools]==1.15.21"]
# ///
"""Un agente da solo, senza crew: risponde a una domanda con Agent.kickoff()."""
import os

from crewai import Agent

# Il modello si sceglie nel file .env (capitolo 7). Se MODEL manca, si usa quello scritto qui.
MODELLO = os.getenv("MODEL", "openai/gpt-4.1-mini")

consulente = Agent(
    role="Consulente di viaggi per famiglie con bambini piccoli",
    goal="Dare pochi consigli pratici e prudenti, segnalando cosa va verificato di persona",
    backstory=(
        "Organizzi vacanze per famiglie da quindici anni. Preferisci tre consigli utili "
        "a un elenco lungo e dici sempre con chiarezza quando non puoi sapere una cosa."
    ),
    llm=MODELLO,
    max_iter=10,  # al massimo 10 giri di ragionamento
    verbose=True,
)

if __name__ == "__main__":
    # Niente Task e niente Crew: la domanda si passa direttamente all'agente.
    risposta = consulente.kickoff(
        "Quali 3 cose controllare prima di prenotare un appartamento per le vacanze "
        "con un bambino di 2 anni? Rispondi in italiano, con un elenco puntato."
    )
    print("\n=== RISPOSTA ===")
    print(risposta.raw)
    print("\n=== TOKEN USATI ===")
    print(risposta.usage_metrics)

Due dettagli sul codice. Le parentesi tonde intorno a più stringheStringa: Un testo nel codice, scritto tra virgolette: "Ricercatore". glossario scritte su righe diverse le uniscono in un unico testo: è solo un modo per non avere righe lunghissime. E la risposta di Agent.kickoff() non è un CrewOutput ma un oggetto simile, con raw (il testo) e usage_metrics (i token usati) al posto di token_usage.

Si lancia come il primo crew:

uv run --env-file .env agente_singolo.py

Vedrai i riquadri dell'agente (non quelli della crew, che qui non esiste) e alla fine la risposta. Il testo cambia a ogni esecuzione e dipende dal modello scelto.

nutrizionista = Agent(
    role="Cuoco di famiglia esperto di cucina senza glutine a basso costo",
    goal="Proporre menù di 7 giorni sicuri per chi è celiaco, con una spesa settimanale sotto il budget indicato",
    backstory=(
        "Cucini da vent'anni per famiglie numerose con pochi soldi. Conosci bene la "
        "contaminazione da glutine e segnali sempre gli ingredienti da controllare in etichetta."
    ),
    llm=MODELLO,
)

Nel prossimo capitolo passiamo alla parte che conta di più secondo la guida ufficiale: scrivere bene i task.

Corso indipendente, non affiliato a CrewAI Inc. Contenuti verificati su CrewAI 1.15.21 il 15 settembre 2026.