5Gli attrezzi: terminale, Python, uv, editor

Prima di cucinare un piatto nuovo si prepara il banco: il coltello, il tagliere, i fornelli, gli ingredienti. Con CrewAI è lo stesso. Per far lavorare una squadra di agenti ti servono pochi attrezzi, tutti gratuiti: una finestra in cui dare ordini al computer, un programma per scrivere i file, Python e un aiutante che installa tutto al posto tuo.

In questo capitolo non installi ancora nulla (lo farai nel capitolo 6): impari cos'è ogni attrezzo e a cosa serve, così i comandi dei prossimi capitoli non ti sembreranno formule magiche.

Il terminale#

Di solito usi il computer cliccando: apri una cartella, trascini un file, premi un pulsante. Il TerminaleTerminale: Finestra in cui si scrivono comandi testuali al computer invece di cliccare. Su Windows si chiama PowerShell o Prompt dei comandi, su macOS e Linux Terminale. glossario è un altro modo di usarlo: una finestra in cui scrivi quello che vuoi fare. Ogni istruzione che scrivi e confermi con il tasto Invio è un ComandoComando: Un'istruzione scritta nel terminale, seguita da Invio. Esempio: crewai run. glossario. Il computer lo esegue e scrive la risposta nella stessa finestra.

Perché usarlo, se ci sono le finestre? Perché i programmi per sviluppatori, come CrewAI, non hanno pulsanti: si usano con comandi. E un comando si può copiare da una pagina come questa, mentre una sequenza di clic va descritta a parole e si sbaglia facilmente.

Come aprirlo#

• Windows: premi il tasto Windows, scrivi PowerShell e premi Invio. Su Windows 11 va bene anche l'app Terminale, che apre PowerShell.
• macOS: premi Cmd e barra spaziatrice (si apre Spotlight), scrivi Terminale e premi Invio. Lo trovi anche in Applicazioni, cartella Utility.
• Linux: su Ubuntu e su molte altre distribuzioni basta la combinazione Ctrl + Alt + T, oppure cerca «Terminale» tra le applicazioni.

Si apre una finestra quasi vuota, con una riga che finisce con un cursore lampeggiante. Quella riga si chiama prompt (lo stesso nome del testo che dai a un modello: in entrambi i casi è «il punto in cui tocca a te scrivere»). Più o meno appare così (esempio illustrativo, il tuo sarà diverso):

PS C:\Users\anna>

Su Windows il prompt inizia con PS e mostra il percorso della cartella in cui ti trovi. Su macOS assomiglia a anna@MacBook ~ %, su Linux a anna@pc:~$. Il simbolo ~ indica la tua cartella personale.

La cartella corrente#

Il terminale lavora sempre «dentro» una cartella, quella corrente. È come essere in una stanza della casa: vedi solo i mobili di quella stanza. Quando lanci un comando che usa un file, il terminale lo cerca nella cartella corrente. Per questo metà degli errori dei principianti è «ero nella cartella sbagliata».

Tre comandi bastano per muoversi. Ecco la versione per macOS e Linux: il primo dice dove sei, il secondo elenca il contenuto, il terzo entra in una cartella.

# dove mi trovo? (stampa il percorso della cartella corrente)
pwd
# cosa c'è qui dentro? (elenca file e cartelle)
ls
# entra nella cartella Documents
cd Documents
# torna indietro di un livello, nella cartella che la contiene
cd ..

Su Windows, in PowerShell, i comandi sono quasi uguali. Per elencare il contenuto si usa di solito dir (in PowerShell funziona anche ls).

# dove mi trovo?
pwd
# cosa c'è qui dentro?
dir
# entra nella cartella Documents
cd Documents
# torna indietro di un livello
cd ..

cd sta per change directory, «cambia cartella». Dopo cd Documents il prompt cambia e mostra il nuovo percorso. Se il nome della cartella contiene spazi, mettilo tra virgolette: cd "I miei progetti".

La cartella di progetto#

Un lavoro ordinato ha una sua scatola. Per il corso crea una cartella di progettoCartella di progetto: La cartella del computer che contiene tutti i file di un tuo lavoro. I comandi si lanciano stando "dentro" questa cartella. glossario: una cartella normale che conterrà gli script, il file con le impostazioni e i risultati. Tutti i comandi dei capitoli successivi vanno lanciati stando dentro questa cartella.

Puoi crearla con i clic, come fai sempre, oppure dal terminale. Questi comandi portano nella tua cartella personale, creano corso-crewai ed entrano dentro. Su macOS e Linux:

# vai nella tua cartella personale
cd ~
# crea la cartella del corso (mkdir = make directory)
mkdir corso-crewai
# entra nella cartella appena creata
cd corso-crewai

Su Windows sono gli stessi comandi:

# vai nella tua cartella personale
cd ~
# crea la cartella del corso
mkdir corso-crewai
# entra nella cartella appena creata
cd corso-crewai

Ora il prompt termina con corso-crewai: sei nella stanza giusta. Se chiudi il terminale e lo riapri, ripartirai dalla cartella personale e dovrai rientrare con cd corso-crewai.

L'editor di codice#

Gli script sono file di testo. In teoria basterebbe il Blocco note, ma un editor di codiceEditor di codice: Programma per scrivere e modificare file di codice, con colori e suggerimenti. Il più usato e gratuito è Visual Studio Code. glossario ti aiuta molto: colora le parole del codice, segnala gli errori, mostra i file nascosti come .env e salva i file senza aggiungere in fondo al nome estensioni strane, come .txt. Il più usato è Visual Studio Code (VS Code), gratuito, di Microsoft.

Si installa dalla pagina ufficiale code.visualstudio.com/download:

• Windows: scarica il programma di installazione, aprilo e accetta le opzioni proposte.
• macOS: scarica il file, aprilo e trascina Visual Studio Code nella cartella Applicazioni.
• Linux: scarica il pacchetto .deb (Ubuntu, Debian) o .rpm (Fedora) e aprilo con il programma di installazione del sistema.

Poi apri VS Code, scegli dal menu File la voce per aprire una cartella (Open Folder) e seleziona corso-crewai. A sinistra vedrai i file della cartella. VS Code ha anche un terminale incorporato: menu Terminal, voce New Terminal. Si apre in basso, già posizionato nella cartella di progetto: è il modo più comodo per non sbagliare cartella.

Python, il programma#

Nel capitolo 4 hai visto che PythonPython: Linguaggio di programmazione molto diffuso, leggibile e usatissimo nell'intelligenza artificiale. CrewAI è scritto in Python e si usa da Python. glossario è il linguaggio in cui è scritto CrewAI. Ma un file scritto in Python, da solo, è solo testo. Serve un programma che lo legga e lo esegua riga per riga: anche questo programma si chiama Python. Quando si dice «installare Python» si intende installare questo esecutore.

Python esce in versioni numerate: 3.10, 3.11, 3.12, 3.13, 3.14. Non tutte vanno bene per tutto. CrewAI 1.15.21 richiede Python 3.10 o successivo, ma non la 3.14 (nella documentazione: >=3.10 <3.14). Se sul tuo computer c'è una versione sbagliata, o non c'è affatto, non preoccuparti: non dovrai scaricare Python a mano, se ne occuperà uv.

Accanto al programma Python ci sono i pacchetti, cioè le librerieLibreria (pacchetto): Codice scritto da altri che installi e riusi nei tuoi programmi. CrewAI si installa come pacchetto Python. glossario scritte da altri: CrewAI è un pacchetto, e a sua volta ne usa più di cento (per parlare con OpenAI, per leggere i PDF, per salvare dati…). Un pacchetto di cui il tuo lavoro ha bisogno si chiama DipendenzaDipendenza: Un pacchetto di cui il tuo progetto ha bisogno per funzionare. Le dipendenze si elencano in pyproject.toml o in testa allo script. glossario. Installarle tutte a mano, nelle versioni giuste, sarebbe un incubo.

uv, l'aiutante che installa tutto#

uvuv: Programma gratuito che installa Python e i pacchetti in modo rapido e ordinato. È lo strumento consigliato dalla documentazione di CrewAI. glossario è un programma gratuito dell'azienda Astral, ed è lo strumento che la documentazione ufficiale di CrewAI usa per l'installazione. Pensalo come il magazziniere della cucina: tu dici «mi servono questi ingredienti», lui controlla cosa c'è, va a prendere quello che manca e lo sistema sul banco giusto. In pratica uv fa quattro cose:

1. Installa Python nella versione adatta, se sul computer manca o è quella sbagliata.
2. Scarica e installa i pacchetti, con tutte le loro dipendenze, molto rapidamente.
3. Crea un ambiente virtualeAmbiente virtuale: Una copia isolata di Python dedicata a un progetto, con i suoi pacchetti. Evita che progetti diversi si pestino i piedi. uv lo crea da solo. glossario: una copia isolata di Python con i suoi pacchetti, riservata a un progetto. Così un progetto che vuole CrewAI 1.15.21 non disturba un altro che ne vuole una versione diversa.
4. Tiene nota delle dipendenze: le legge da un elenco scritto nel progetto o in testa allo script, e le prepara da solo ogni volta che lo esegui.

Ecco come si incastrano i pezzi quando lanci uno script con uv. Segui le frecce: parti dal comando che scrivi nel terminale e arrivi al tuo script che gira.

Cos'è uno script#

Uno ScriptScript: Un file di codice che si esegue dall'inizio alla fine con un solo comando, per esempio uv run primo_crew.py. glossario è un file di codice che si esegue dall'inizio alla fine con un solo comando. I file Python hanno l'estensione .py. Nel corso ogni esempio è uno script autosufficiente: tutto quello che serve, comprese le dipendenze, è scritto nel file stesso.

Ecco lo script più piccolo possibile nello stile del corso. Saluta e dice quale versione di Python lo sta eseguendo. Le prime quattro righe, tra # /// script e # ///, non sono istruzioni per Python: sono un biglietto per uv con la versione di Python richiesta e l'elenco delle dipendenze (qui vuoto, perché non serve nessun pacchetto).

# /// script
# requires-python = ">=3.10,<3.14"
# dependencies = []
# ///
"""Il primo script: saluta e dice quale Python lo sta eseguendo."""
import sys

print("Ciao! Sono uno script Python.")
# sys.version contiene la versione di Python: ne teniamo solo il primo pezzo
print("Mi sta eseguendo Python", sys.version.split()[0])

Per eseguirlo si scrive, nella cartella che contiene il file, uv run ciao.py. Lo farai dopo aver installato uv nel prossimo capitolo. Sul computer usato per preparare il corso il risultato è questo (la versione di Python sul tuo può essere diversa, e la prima volta uv potrebbe scrivere qualche riga in più mentre scarica Python):

Ciao! Sono uno script Python.
Mi sta eseguendo Python 3.12.3

print scrive un testo nel terminale; le righe tra tre virgolette sono una descrizione per chi legge. Per ora non serve capire il resto: la sintassi di Python la vedrai un pezzo alla volta dal capitolo 8.

Nel prossimo capitolo installi davvero uv e CrewAI, e lanci il primo script che controlla che tutto funzioni.

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