Come imparare gli agenti IA da zero: guida in 6 fasi

Il percorso in sei fasi

Per imparare gli agenti di IA da zero, segui queste sei fasi nell’ordine: concetti, primo loop, strumenti, memoria, progettazione del loop e sicurezza. In ogni fase costruisci qualcosa con le tue mani. Saltare avanti è il motivo più comune per cui ci si blocca, perché un framework nasconde proprio la parte che dovevi vedere.

Un agente di IA è un loop basato su un modello linguistico a cui è consentito chiamare strumenti. Questo è l’intero argomento. Tutto il resto riguarda i componenti del loop, le risorse che gli strumenti possono modificare e il modo in cui interrompere il loop quando si comporta in modo errato. Se sai spiegare il loop a un’altra persona, hai imparato il concetto. Se sai solo elencare i framework, non lo hai ancora imparato.

Il piano seguente presuppone che tu impari costruendo. Leggi una fase, costruisci il componente semplice previsto, causane intenzionalmente il malfunzionamento, quindi passa alla fase successiva. Una fase che hai soltanto letto è una fase che non hai ancora svolto.

Cosa serve davvero prima della fase 1

L’elenco dei prerequisiti è breve, e più breve di quanto suggerisca la maggior parte delle pagine dei corsi.

• Sai leggere e scrivere codice Python o TypeScript al livello necessario per uno script di cinquanta righe.
• Utilizzi con disinvoltura una shell Linux: installi un pacchetto, modifichi un file e leggi un log.
• Hai una API key per un modello ospitato oppure una macchina in grado di eseguire un modello locale.

Questo è tutto. Non ti serve conoscere la teoria del machine learning e non devi aver addestrato un modello. Nel lavoro con gli agenti non intervengono gradienti né dati di addestramento. Una scheda grafica serve solo se decidi di eseguire direttamente il modello; è una competenza separata che puoi acquisire in seguito leggendo come ospitare Ollama su un VPS per eseguire autonomamente un LLM.

La parte relativa alla shell viene spesso sottovalutata. Gli agenti falliscono a causa di permessi, percorsi, variabili d’ambiente e processi che terminano senza messaggi evidenti. Se uno stack trace relativo a PATH o ai permessi di un file ti porta a chiudere il terminale, dedica prima un fine settimana alle basi di Linux. Ti farà risparmiare un mese in seguito.

Fase 1: che cos'è un agent e che cosa non è

Inizia con una sola chiamata API e senza loop. Invia un prompt, stampa la risposta e controlla il conteggio dei token nella risposta. Ora conosci l'unità di costo e l'unità di latenza.

Poi impara a usare gli strumenti. È l'unica idea realmente nuova in questo campo. Descrivi una funzione al modello indicando un nome, una descrizione e uno schema JSON (JavaScript object notation) per i relativi input. Il modello non esegue nulla. Risponde con una richiesta strutturata: chiama run_command con questi argomenti. Il tuo codice esegue la funzione, invia l'output come messaggio e interroga nuovamente il modello. Il modello è un pianificatore che legge testo e scrive testo. Il tuo codice è ciò che esegue le operazioni.

Un chatbot termina dopo una risposta. Un agent ripete questo scambio finché il modello non smette di richiedere strumenti. Questa ripetizione è l'unica differenza sostanziale e spiega anche perché i modi di errore sono diversi. Un chatbot fornisce una risposta errata una volta. Un agent agisce più volte sulla base di una risposta errata prima che qualcuno se ne accorga.

Fase 2: scrivi il ciclo manualmente, una volta

Non iniziare con un framework. Scrivi circa trenta righe di Python, così la struttura del programma sarà tua.

sudo apt update && sudo apt install -y python3-venv
python3 -m venv ~/agent
source ~/agent/bin/activate
pip install anthropic
export ANTHROPIC_API_KEY=your-key-here

import subprocess
import anthropic

client = anthropic.Anthropic()

tools = [{
    "name": "run_command",
    "description": "Run a read only shell command and return its output.",
    "input_schema": {
        "type": "object",
        "properties": {"command": {"type": "string"}},
        "required": ["command"],
    },
}]

messages = [{"role": "user", "content": "How much disk space is free here?"}]

while True:
    response = client.messages.create(
        model="claude-opus-5",
        max_tokens=4096,
        tools=tools,
        messages=messages,
    )
    if response.stop_reason != "tool_use":
        break
    messages.append({"role": "assistant", "content": response.content})
    results = []
    for block in response.content:
        if block.type == "tool_use":
            done = subprocess.run(
                block.input["command"], shell=True,
                capture_output=True, text=True, timeout=10,
            )
            results.append({
                "type": "tool_result",
                "tool_use_id": block.id,
                "content": done.stdout or done.stderr,
            })
    messages.append({"role": "user", "content": results})

print(next(b.text for b in response.content if b.type == "text"))

Eseguilo con python3 agent.py. Un'esecuzione corretta stampa un paragrafo che indica i tuoi filesystem e lo spazio libero disponibile, perché il modello ha richiesto df -h, il tuo codice lo ha eseguito e il secondo passaggio ha trasformato quella tabella in una frase. Se non stampa nulla, il ciclo è terminato prima che arrivasse un blocco di testo. Inserisci print(response.stop_reason) nel ciclo e osserva come cambiano i valori.

Ora interrompilo deliberatamente. Elimina la riga tool_use_id e leggi l'errore, perché l'API rifiuta un risultato dello strumento privo di un ID corrispondente. Questo è l'errore più comune per chi inizia. Poni una domanda che richieda due comandi e osserva il ciclo eseguirsi due volte. Poni una domanda impossibile e osserva se il ciclo rinuncia oppure continua all'infinito.

Una precisazione su questo esempio. Con shell=True passa direttamente l'output del modello a una shell. Questa soluzione è accettabile su una macchina di prova che puoi ricostruire, ma è errata in qualsiasi altro contesto. La fase 6 corregge questo problema. I concetti alla base del ciclo sono descritti più dettagliatamente in come creare un agente AI su un VPS.

Fase 3: strumenti che l'agent non aveva già

Il tuo strumento run_command funziona, ma un agent reale ha bisogno di strumenti che accedano a risorse esterne al server: un sistema di ticket, un database, un repository. Scrivere un wrapper dedicato per ogni servizio e per ogni agent non è scalabile.

Il Model Context Protocol (MCP) è la soluzione adottata dal settore. Un server MCP espone un insieme di strumenti tramite un transport standard e qualsiasi agent compatibile con MCP può usarlo senza codice di integrazione personalizzato. Il server filesystem di riferimento richiede un solo comando:

npx -y @modelcontextprotocol/server-filesystem /home/you/projects

È necessario che Node sia installato e l'argomento directory è l'unico percorso che il server può utilizzare. Questo riassume il modello di sicurezza: il confine viene deciso dal server, non dal modello. Collegando un client a questo server, l'agent ottiene funzionalità di lettura e scrittura dei file che non è stato necessario implementare. Le modalità corrette per eseguire questi server, usando un service account e illustrando le scelte relative al transport, sono descritte in esecuzione di server MCP su un VPS per agent AI che scrivono codice.

La lezione di questa fase è che la progettazione degli strumenti è il lavoro principale. Una descrizione vaga induce il modello a fare supposizioni. Uno strumento che restituisce quarantamila caratteri inquina la context window. Uno strumento che può eliminare elementi prima o poi li eliminerà.

Fase 4: memoria, che consiste soprattutto in file

In questa fase i principianti scelgono spesso un database vettoriale. Non fatelo, almeno non ancora.

Un agente non conserva memoria tra una chiamata e l'altra. Ogni volta si reinvia l'intera conversazione, quindi una sessione lunga costa di più a ogni turno rispetto a una sessione breve. La memoria si divide quindi in due problemi. Il primo riguarda ciò che entra nella context window in quel momento. Per gestirlo, si possono riassumere i contenuti, ridurre l'output meno recente degli strumenti e memorizzare nella cache il prefisso stabile del prompt, pagando così solo una frazione del costo. Il secondo riguarda ciò che sopravvive a un riavvio: è lo storage.

Per il secondo problema, in quasi tutti i primi progetti un semplice file Markdown che l'agente possa leggere e modificare è una soluzione migliore di un database vettoriale. Assegnategli un file, definite il formato e indicategli di leggere quel file prima di iniziare e di aggiornarlo quando apprende qualcosa. Otterrete gran parte dei vantaggi e potrete aprire il file per verificare che cosa ritiene vero l'agente. Usate embeddings e retrieval quando le note non entrano più nella context window, non prima.

Fase 5: il ciclo è il prodotto

A questo punto puoi creare un agente che funziona mentre lo controlli. La fase 5 consiste nel farlo funzionare anche quando non lo controlli.

Quattro domande determinano se è sicuro lasciare un agente non presidiato. Cosa lo attiva, per evitare che venga eseguito senza motivo. Entro quali limiti opera, affinché un errore resti circoscritto. Come viene verificato il risultato, perché un agente che corregge il proprio lavoro lo approva sempre. Quale budget lo interrompe, in token o in tempo reale. Progettare consapevolmente questi quattro aspetti è la disciplina descritta in ingegneria dei cicli e significato di questa definizione.

L'esercizio: prendi l'agente della fase 2, assegnagli un'attività che richieda quattro o cinque passaggi e aggiungi un limite rigido alle iterazioni. Poi rimuovi il limite e osserva l'impatto di un ciclo senza limiti sul consumo di token. Esegui questa prova una sola volta con un budget ridotto, per evitare di ripeterla accidentalmente con un budget elevato.

Fase 6: sicurezza, secret e costi

Questa fase non è opzionale. È l’ultima solo perché il rischio diventa concreto soltanto dopo aver costruito qualcosa che funziona.

Esegui l’agente con un proprio utente non privilegiato, mai come root e mai con il tuo account, così l’impatto di una compromissione resta limitato a una directory anziché all’intera macchina. Tieni le credenziali fuori dalla portata del modello, perché qualsiasi contenuto presente nella finestra di contesto può essere riportato all’esterno tramite una chiamata a uno strumento. La soluzione consiste nell’usare token con ambito limitato e durata breve, gestiti tramite un helper, come descritto in tenere i secret fuori dagli agenti AI. Imposta un limite massimo rigido alla spesa, perché un loop senza supervisione addebita ogni iterazione senza che nessuno lo controlli. I limiti e il batching necessari per mantenere i costi sotto controllo sono descritti in controllare i costi degli agenti AI su un VPS sempre attivo.

Per i costi è utile considerare un numero concreto. A luglio 2026, Claude Opus 5 applica una tariffa di $5 per milione di token di input e $25 per milione di token di output. Un agente verboso che reinvia una conversazione in crescita può trasferire alcune centinaia di migliaia di token durante una singola attività. Il prompt caching e l’uso di un modello più piccolo per le attività di routine modificano questo calcolo molto più di qualsiasi modifica al prompt.

Anche la prompt injection rientra in questa fase. Se l’agente legge una pagina web, un issue tracker o una casella di posta, chi ha scritto quel testo sta scrivendo anche istruzioni per l’agente. La difesa non consiste nell’usare un system prompt più complesso. Consiste nel definire correttamente i limiti, perché un agente che non può eliminare un repository non può essere indotto a eliminarlo.

Quale percorso seguire?

Scegli un solo percorso formativo e completalo, invece di provare sei percorsi diversi. Il repository ai-agents-for-beginners di Microsoft è la risorsa gratuita più completa: è un corso di diciotto lezioni che a luglio 2026 ha superato 70,000 stelle e corrisponde in modo lineare alle fasi descritte sopra. Le raccolte di repository di agenti più popolari sono utili per capire quali progetti esistono, ma molto meno come programma di studio, perché un elenco ordinato per numero di stelle riflette la popolarità, non l'ordine didattico.

Quando vuoi esercitarti su un progetto reale, un agente di coding è il primo obiettivo più indicato: il feedback è immediato, gli strumenti sono chiari e gli errori si possono annullare facilmente. Eseguire un agente di coding basato sull'AI su un VPS illustra l'intero processo. Se preferisci studiare sistemi già funzionanti invece di costruirli da zero, il confronto in i migliori agenti AI self-hosted mostra come diversi progetti implementano lo stesso ciclo in modi differenti.

Quanto tempo richiede?

Per chi sa già programmare, le fasi 1 e 2 richiedono una serata. La fase 3 richiede un fine settimana, trascorso in gran parte a descrivere gli strumenti anziché il protocollo. Le fasi 4 e 5 richiedono alcune settimane di utilizzo reale, perché si scopre che cosa dimentica l'agente soltanto osservando quando lo dimentica. La fase 6 non termina mai del tutto: ogni nuova funzionalità concessa all'agente la riapre.

Due mesi di serate regolari sono sufficienti per portare la maggior parte delle persone a un agente funzionante, con limiti definiti e utile. Chi impiega un anno, di solito, ha continuato a leggere invece di costruire.

FAQ

Devo conoscere il machine learning per creare un agente AI?

No. Creare un agente significa chiamare un modello tramite un'API e collegare le richieste degli strumenti a funzioni reali: è normale programmazione applicativa. Non devi occuparti di addestramento, gradienti o dataset. Le competenze che determinano il funzionamento dell'agente sono la progettazione degli schemi degli strumenti, la gestione degli errori e i permessi Linux. La teoria del machine learning diventa rilevante solo se in seguito vuoi eseguire il fine-tuning di un modello, che è un'attività diversa con prerequisiti diversi.

Devo iniziare con un framework come LangChain o CrewAI?

Scrivi prima un loop manuale, poi adotta un framework. Un framework sostituisce le trenta righe dello stage 2 con un oggetto di configurazione. Questo è comodo quando sai che cosa ha sostituito, ma può creare confusione prima di quel momento. Quando l'agente si comporta in modo errato, devi analizzare direttamente l'elenco dei messaggi e i risultati degli strumenti. È molto più difficile farlo se non li hai mai visti. Dopo aver scritto un loop autonomamente, un framework ti fa risparmiare tempo invece di nascondere il funzionamento.

Quanto costa imparare a usare gli agenti AI?

Meno di quanto si aspettino molte persone, se stabilisci un limite. Una chiave API per un servizio ospitato e un piccolo VPS sono sufficienti per completare tutte queste sei fasi. Il rischio reale non è la tariffa oraria, ma un loop senza limiti che genera costi a ogni iterazione mentre dormi. Imposta fin dal primo giorno un limite massimo di spesa sull'account API, aggiungi un limite al numero di iterazioni a ogni loop che scrivi e usa un modello meno costoso per i passaggi ordinari. Eseguire il modello localmente elimina il costo dei token, ma richiede hardware adeguato.

Qual è la differenza tra un agente AI e un chatbot?

Un chatbot risponde una volta. Un agente ripete un ciclo: il modello richiede uno strumento, il codice lo esegue, il risultato viene restituito e il modello decide che cosa fare dopo. Questa ripetizione consente all'agente di completare un'attività in più passaggi. È anche il motivo per cui gli agenti hanno bisogno di limiti che non servono ai chatbot. Una risposta errata di un chatbot è un paragrafo sbagliato. Una risposta errata di un agente è un paragrafo sbagliato, oltre a qualunque azione abbia eseguito di conseguenza.