-
I capitoli
-
- Quiz
-
- Quiz
-
- Quiz
-
- Quiz
-
- Quiz
-
- Quiz
-
- Quiz
-
- Quiz
-
- Quiz
-
- Quiz
-
- Quiz
-
- Quiz
-
Esame finale e attestato
1. L'ambiente di sviluppo
Introduzione: perché l'ambiente conta prima del codice
Un'azienda di distribuzione di ricambi in provincia di Brescia decide di provare un agente che legge le richieste di preventivo arrivate via email e prepara una bozza d'offerta in Odoo. Il prototipo lo scrive in un pomeriggio un ragazzo dell'IT, sul proprio portatile. Funziona. Due settimane dopo il collega che deve metterlo in produzione non riesce a farlo partire: versioni diverse delle librerie, una chiave API scritta in chiaro dentro lo script, un file di configurazione che esiste solo su quel portatile. Peggio: lo script era stato caricato su un repository condiviso, chiave compresa. La chiave va revocata, il fornitore segnala consumi anomali, e il progetto perde la fiducia della direzione prima ancora di partire.
Nessuno di questi problemi riguarda l'intelligenza artificiale. Riguardano l'ambiente di sviluppo. Un agente è software, e il software che tocca dati aziendali e spende denaro a ogni chiamata deve nascere in un ambiente pulito, riproducibile e sicuro. In questo capitolo prepariamo il progetto base che useremo in tutto il corso: un repository chiamato agente-dd, con ambiente virtuale, dipendenze fissate, segreti fuori dal codice, Git configurato e un primo test automatico.
In questo capitolo
Alla fine del capitolo sai creare un ambiente Python isolato, gestire le chiavi API con file .env senza esporle, impostare un repository Git che non pubblica segreti e usare un assistente di coding in modo controllato. Durata stimata: 40 minuti.
Python e ambienti virtuali
Ogni progetto ha bisogno delle sue librerie, nelle sue versioni. Se installate tutto nel Python di sistema, il progetto A che richiede una versione della libreria anthropic e il progetto B che ne richiede un'altra si pestano i piedi. L'ambiente virtuale risolve il problema: è una cartella che contiene un interprete Python e le librerie di un solo progetto.
Per questo corso serve Python 3.11 o superiore. Verificate la versione e create l'ambiente così:
# Verifica della versione installata
python3 --version
# Crea la cartella del progetto e l'ambiente virtuale al suo interno
mkdir agente-dd
cd agente-dd
python3 -m venv .venv
# Attiva l'ambiente (Linux e macOS)
source .venv/bin/activate
# Attiva l'ambiente (Windows PowerShell)
# .venv\Scripts\Activate.ps1
# Da qui in poi "python" e "pip" sono quelli dell'ambiente
python -m pip install --upgrade pip
Quando l'ambiente è attivo, il prompt del terminale mostra (.venv). Se lo dimenticate e installate pacchetti, finiscono nel Python di sistema: è l'errore più frequente nelle prime settimane.
Dipendenze fissate
Le dipendenze vanno scritte in un file e fissate nelle versioni. Esistono più strumenti: pip con un requirements.txt, oppure gestori più moderni come uv o poetry, che producono un file di lock con le versioni esatte di tutte le dipendenze, anche indirette. Per il corso usiamo la soluzione più semplice, valida ovunque.
# requirements.txt - dipendenze del progetto base
anthropic # SDK ufficiale per le API di Claude
python-dotenv # carica le variabili dal file .env
pydantic # validazione dei dati (capitolo 5)
pytest # test automatici
# Installa e poi "congela" le versioni effettivamente installate
pip install -r requirements.txt
pip freeze > requirements.lock.txt
Il file requirements.lock.txt va nel repository: il collega che clona il progetto installerà esattamente le stesse versioni con pip install -r requirements.lock.txt. Le librerie per agenti cambiano spesso, e una versione nuova può rinominare una funzione o cambiare un default. Fissare le versioni trasforma una sorpresa in un aggiornamento deliberato.
| Strumento | Punti di forza | Quando sceglierlo |
|---|---|---|
| venv + pip | Incluso in Python, nessuna installazione extra | Corsi, script interni, team piccoli |
| uv | Molto veloce, gestisce anche le versioni di Python, file di lock | Progetti nuovi, pipeline CI |
| poetry | Gestione completa del pacchetto e della pubblicazione | Librerie da distribuire |
Chiavi API e file .env
Per chiamare un modello serve una chiave API, una stringa che identifica il vostro account presso il fornitore e su cui viene addebitato il consumo. Trattatela come la password dell'home banking aziendale: chi la possiede spende a vostro nome e, a seconda delle impostazioni, può leggere dati associati all'organizzazione.
La regola è una sola: la chiave non compare mai nel codice. Si legge da una variabile d'ambiente. In sviluppo, il modo comodo per impostare le variabili è un file .env nella radice del progetto, caricato all'avvio con python-dotenv. Il file .env non va mai nel repository; ci va invece un file .env.example con i nomi delle variabili e valori finti.
# .env.example - copiare in .env e compilare con i valori reali
ANTHROPIC_API_KEY=inserire-qui-la-chiave
# Modello predefinito: lo teniamo in configurazione, non nel codice
MODELLO_PRINCIPALE=claude-sonnet-5-5
MODELLO_ECONOMICO=claude-haiku-5-5
LOG_LEVEL=INFO
I nomi dei modelli cambiano nel tempo. Al momento della stesura (ottobre 2026) la documentazione Anthropic elenca, tra gli altri, claude-sonnet-5-5 e claude-haiku-5-5. Teniamo il nome nel .env così, quando esce un modello nuovo, si aggiorna una riga di configurazione e non dieci file.
Ora il modulo di configurazione, il primo file vero del progetto:
# src/agente/config.py
"""Configurazione centralizzata del progetto.
Tutte le impostazioni si leggono da variabili d'ambiente.
In sviluppo le carichiamo da un file .env; in produzione
le imposta il sistema (container, servizio, CI).
"""
import os
from dataclasses import dataclass
from dotenv import load_dotenv
# load_dotenv NON sovrascrive variabili già presenti nell'ambiente:
# in produzione vincono sempre quelle impostate dal sistema.
load_dotenv()
@dataclass(frozen=True)
class Config:
api_key: str
modello_principale: str
modello_economico: str
log_level: str
def carica_config() -> Config:
"""Legge la configurazione e si ferma subito se manca qualcosa."""
api_key = os.getenv("ANTHROPIC_API_KEY", "")
if not api_key or api_key.startswith("inserire"):
# Errore esplicito all'avvio: meglio che un errore oscuro alla prima chiamata
raise RuntimeError(
"ANTHROPIC_API_KEY mancante. Copia .env.example in .env e inserisci la chiave."
)
return Config(
api_key=api_key,
modello_principale=os.getenv("MODELLO_PRINCIPALE", "claude-sonnet-5-5"),
modello_economico=os.getenv("MODELLO_ECONOMICO", "claude-haiku-5-5"),
log_level=os.getenv("LOG_LEVEL", "INFO"),
)
Notate il principio "fallire presto": se la chiave manca, il programma si ferma alla partenza con un messaggio che dice cosa fare. È molto meglio di un errore 401 che arriva dopo dieci minuti di elaborazione.
Gestione dei segreti
Il file .env va bene sul portatile dello sviluppatore. Non basta in produzione e non basta in un team. Vediamo i livelli di maturità, dal minimo indispensabile alla soluzione aziendale.
- Livello minimo:
.envescluso da Git, chiave diversa per ogni sviluppatore, mai condivisa via chat o email. - Livello team: chiavi separate per sviluppo, test e produzione, con limiti di spesa diversi impostati nella console del fornitore. Se la chiave di sviluppo finisce in giro, il danno è contenuto.
- Livello aziendale: i segreti stanno in un gestore dedicato (i servizi di secret management dei cloud provider, oppure strumenti come Vault) e arrivano all'applicazione come variabili d'ambiente al momento dell'avvio. Nessuno li legge a mano.
Due pratiche valgono a qualunque livello. La prima: rotazione. Le chiavi si cambiano periodicamente e subito quando una persona lascia il team o quando c'è anche solo il sospetto di un'esposizione. La seconda: principio del minimo privilegio. Se il fornitore permette chiavi con permessi o spazi di lavoro separati, l'agente che riassume email non deve usare la stessa chiave dell'amministratore.
Lo stesso vale per le credenziali degli strumenti che l'agente userà: la password dell'utente tecnico di Odoo, il token del gestionale documentale, la stringa di connessione al database. Tutto in variabili d'ambiente, tutto con utenze dedicate e permessi ridotti. Un agente che deve solo leggere gli ordini non riceve un utente Odoo che può cancellarli.
Attenzione ai log. Una chiave può uscire anche senza essere nel codice: basta un print(config) di debug o un log che stampa le intestazioni HTTP. La dataclass sopra stamperebbe la chiave in chiaro. Nel capitolo 12 vedremo come mascherare i segreti nei log; per ora, non stampate mai l'oggetto di configurazione intero.
Git: versionare il codice, non i segreti
Git registra ogni modifica e permette di tornare indietro. Per un progetto con agenti è ancora più utile del solito, perché i prompt cambiano spesso e capire "quale versione del prompt era in produzione martedì" è una domanda frequente. I prompt vanno quindi versionati insieme al codice, in file dedicati o in costanti ben riconoscibili.
Prima del primo commit, create il file .gitignore:
# .gitignore
.venv/
__pycache__/
*.pyc
.env
.env.*
!.env.example
# dati di lavoro e memorie dell'agente (capitoli 6 e 10)
dati/
memoria/
*.sqlite
# log locali
logs/
# Inizializza il repository e fai il primo commit
git init
git add .
git status # CONTROLLA che .env NON compaia nell'elenco
git commit -m "Progetto base agente-dd"
Il comando git status prima del commit non è un dettaglio. Se .env compare tra i file da aggiungere, fermatevi e correggete il .gitignore. Una volta che un segreto è entrato nella cronologia di Git, cancellarlo dal file non basta: resta nei commit precedenti. L'unica soluzione sicura è revocare la chiave e generarne una nuova.
Una rete di sicurezza automatica
Esistono strumenti che analizzano i file prima di ogni commit e bloccano quelli che contengono stringhe con l'aspetto di una chiave, ad esempio gitleaks o detect-secrets, integrabili con il framework pre-commit. Le principali piattaforme di hosting (GitHub, GitLab) offrono inoltre scansioni dei segreti sui repository. Attivatele: costano pochi minuti e prevengono l'incidente descritto nell'introduzione.
# .pre-commit-config.yaml - esempio con gitleaks
repos:
- repo: https://github.com/gitleaks/gitleaks
rev: v8.18.0 # usare la versione stabile più recente
hooks:
- id: gitleaks
Assistenti di coding: Claude Code, Cursor e simili
Gli assistenti di coding sono agenti che lavorano sul vostro codice: leggono i file, propongono modifiche, eseguono comandi e test. I più diffusi si presentano in due forme. Claude Code lavora nel terminale (e si integra negli editor): gli descrivete il compito, esplora il repository, modifica i file e lancia i test. Cursor è un editor derivato da VS Code con l'assistente integrato nell'interfaccia. Esistono alternative simili, e le funzioni si rincorrono di mese in mese.
In questo corso sono utili per tre cose: generare lo scheletro di un modulo, scrivere test, spiegare un errore. Ma un assistente di coding è esso stesso un agente con accesso al vostro file system, e valgono le regole che impareremo per gli agenti che costruiamo:
- Permessi. Partite con l'approvazione manuale dei comandi. Concedete l'esecuzione automatica solo per comandi innocui e ripetitivi, come l'avvio dei test.
- Segreti. L'assistente può leggere il file
.envse si trova nella cartella di lavoro. Configurate le regole del tool per escluderlo, oppure usate chiavi di sviluppo con limiti di spesa bassi. - Istruzioni di progetto. Claude Code legge un file
CLAUDE.mdnella radice del repository; Cursor ha un meccanismo analogo di regole. Scriveteci le convenzioni: come si lanciano i test, che lo stile è in italiano, che le chiavi non si stampano. - Revisione. Ogni modifica proposta va letta come una pull request di un collega junior molto veloce. Se non capite il codice, non accettatelo.
# CLAUDE.md - istruzioni di progetto per l'assistente di coding
## Progetto agente-dd
- Python 3.11+, ambiente in .venv, dipendenze in requirements.txt
- Test: `pytest -q` (devono passare prima di ogni commit)
- Configurazione SOLO da variabili d'ambiente (src/agente/config.py)
- Non leggere, stampare o modificare il file .env
- Commenti e messaggi all'utente in italiano
Il progetto base completo
Mettiamo insieme i pezzi. Questa è la struttura che useremo nei capitoli successivi:
agente-dd/
.env.example
.gitignore
CLAUDE.md
README.md
requirements.txt
requirements.lock.txt
src/
agente/
__init__.py
config.py
ciao.py
tests/
test_config.py
Lo script di verifica fa una chiamata minima al modello e stampa la risposta e i token usati:
# src/agente/ciao.py
"""Verifica che ambiente, chiave e connessione funzionino."""
import anthropic
from agente.config import carica_config
def main() -> None:
cfg = carica_config()
client = anthropic.Anthropic(api_key=cfg.api_key)
risposta = client.messages.create(
model=cfg.modello_economico, # per un test basta il modello più economico
max_tokens=100,
messages=[{"role": "user", "content": "Rispondi solo: ambiente pronto."}],
)
# La risposta contiene una lista di blocchi; il primo è testo
print(risposta.content[0].text)
print(f"Token in ingresso: {risposta.usage.input_tokens}, "
f"in uscita: {risposta.usage.output_tokens}")
if __name__ == "__main__":
main()
E il primo test automatico, che non chiama le API (i test non devono spendere soldi né dipendere dalla rete):
# tests/test_config.py
import pytest
from agente import config
def test_chiave_mancante_blocca_avvio(monkeypatch):
# Simuliamo un ambiente senza chiave
monkeypatch.delenv("ANTHROPIC_API_KEY", raising=False)
with pytest.raises(RuntimeError, match="ANTHROPIC_API_KEY"):
config.carica_config()
def test_modello_letto_da_ambiente(monkeypatch):
monkeypatch.setenv("ANTHROPIC_API_KEY", "chiave-di-test")
monkeypatch.setenv("MODELLO_PRINCIPALE", "modello-di-prova")
cfg = config.carica_config()
assert cfg.modello_principale == "modello-di-prova"
Per far trovare il pacchetto agente a Python e a pytest, la soluzione più semplice è aggiungere un file pyproject.toml minimo con la configurazione di pytest:
# pyproject.toml
[tool.pytest.ini_options]
pythonpath = ["src"]
testpaths = ["tests"]
Per lanciare lo script: PYTHONPATH=src python -m agente.ciao (su Windows impostate la variabile con $env:PYTHONPATH="src").
Errori comuni
- Installare pacchetti con l'ambiente non attivo. Le librerie finiscono nel Python di sistema e il progetto "funziona solo sul mio PC". Rimedio: controllare
(.venv)nel prompt e usare semprepython -m pip. - Chiave scritta nel codice "solo per una prova". Le prove finiscono nei commit. Rimedio: la chiave si legge solo da variabile d'ambiente, fin dal primo script.
- Cancellare il segreto dal file dopo averlo committato. Resta nella cronologia. Rimedio: revocare subito la chiave nella console del fornitore e generarne una nuova.
- Dipendenze non fissate. Un aggiornamento automatico rompe il progetto in produzione. Rimedio: file di lock nel repository e aggiornamenti deliberati, con i test.
- Stessa chiave per sviluppo e produzione, senza limiti di spesa. Un ciclo infinito in sviluppo consuma il budget di produzione. Rimedio: chiavi separate con tetti di spesa diversi.
- Accettare a scatola chiusa le modifiche dell'assistente di coding. Rimedio: rivedere ogni diff e far girare i test prima del commit.
Esercizio pratico: configura e fai girare il progetto base
Obiettivo: ottenere sul vostro computer il progetto agente-dd funzionante, con test verdi e nessun segreto nel repository.
- Create la cartella
agente-dd, l'ambiente virtuale e attivatelo. - Create
requirements.txtcon le quattro dipendenze indicate, installatele e generaterequirements.lock.txt. - Create
.env.example, poi copiatelo in.enve inserite la vostra chiave di sviluppo. - Create
.gitignore,pyproject.toml,CLAUDE.mde i file Python mostrati sopra (src/agente/__init__.pypuò essere vuoto). - Lanciate
pytest -q: devono passare due test. - Lanciate
PYTHONPATH=src python -m agente.ciao: dovete vedere la risposta del modello e il conteggio dei token. - Inizializzate Git, eseguite
git statuse verificate che.envnon compaia. Fate il primo commit. - Prova di robustezza: rinominate temporaneamente
.enve rilanciate lo script. Dovete ottenere il messaggio chiaro diRuntimeError, non un errore HTTP. - Facoltativo: chiedete al vostro assistente di coding di aggiungere un test che verifichi il default di
LOG_LEVEL. Rivedete il diff prima di accettarlo.
Criteri di riuscita
- Due test (o tre con il facoltativo) passano con
pytest -q. - Lo script stampa la risposta e i token in ingresso e in uscita.
git log -p | grep -i api_keynon mostra alcuna chiave reale, solo il nome della variabile.- Senza
.envil programma si ferma con un messaggio che spiega cosa fare. - Un collega può clonare il repository e ripartire con tre comandi: creare l'ambiente, installare dal lock, copiare
.env.example.
Riepilogo
- Ogni progetto ha il suo ambiente virtuale e le sue dipendenze fissate in un file di lock.
- Le chiavi API si leggono solo da variabili d'ambiente; in sviluppo da un file
.envescluso da Git. - Nel repository va
.env.examplecon valori finti, mai.env. - Un segreto finito nella cronologia di Git si revoca, non si cancella.
- Chiavi separate per ambiente, con limiti di spesa e permessi minimi, anche per gli strumenti come Odoo.
- Gli assistenti di coding accelerano il lavoro ma sono agenti: permessi controllati, istruzioni di progetto, revisione di ogni modifica.
- Il progetto base ha configurazione centralizzata, un controllo all'avvio e test che non chiamano le API.
Ora fai il quiz di fine capitolo per passare al successivo.
Alla fine del capitolo sai: preparare un ambiente di lavoro pulito e sicuro.
Ancora nessun commento.