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

Il percorso in sei fasi

Per imparare gli agenti AI da zero, segui sei fasi in ordine: concetti, primo ciclo, strumenti, memoria, progettazione del ciclo e sicurezza. In ogni fase costruisci personalmente un elemento. Saltare avanti è il motivo più comune per cui le persone si bloccano, perché un framework nasconde proprio la parte che dovevi vedere.

Un agente AI è un ciclo attorno a un modello linguistico autorizzato a chiamare strumenti. Questa frase descrive l'intero argomento. Tutto il resto riguarda i componenti del ciclo, gli elementi che gli strumenti possono modificare e il modo in cui interrompere il ciclo quando si comporta in modo errato. Se sai spiegare il ciclo a un'altra persona, hai imparato il concetto. Se sai soltanto elencare i framework, non l'hai ancora imparato.

Il piano seguente presuppone che tu impari costruendo. Leggi una fase, costruisci l'elemento semplice previsto, interrompilo intenzionalmente e poi 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.
• Usi con dimestichezza 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 si utilizzano gradienti o dati di addestramento. Una scheda grafica è necessaria solo se decidi di eseguire direttamente il modello, ma questa è una competenza separata che puoi acquisire in seguito consultando ospitare Ollama su un VPS per eseguire autonomamente un LLM.

La parte legata alla shell viene spesso sottovalutata. Gli agenti si bloccano a causa di permessi, percorsi, variabili d’ambiente e processi che terminano senza produrre messaggi visibili. Se una traccia dello stack relativa a PATH o ai permessi di un file ti induce a chiudere il terminale, dedica prima un fine settimana alle basi di Linux. In seguito risparmierai un mese.

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

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

Poi si introduce l'uso degli strumenti, l'unica idea realmente nuova dell'intero ambito. Si descrive 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 codice esegue la funzione, invia l'output al modello come messaggio e lo interroga di nuovo. Il modello è un pianificatore che legge testo e scrive testo. Il codice è il componente che esegue le operazioni. Il codice dal proprio lato dello scambio ha un nome, quando si iniziano a confrontare i progetti: è il contenitore dell'agente, cioè il ciclo, gli strumenti e le autorizzazioni che avvolgono un modello privo di autorizzazioni proprie.

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

Fase 2: scrivi tu il ciclo, una volta sola

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, 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 che non ha un ID corrispondente, ed è il più comune errore dei principianti. Poni una domanda che richieda due comandi e osserva il ciclo eseguirsi due volte. Poni una domanda impossibile e osserva se il ciclo rinuncia o continua a girare senza fine.

Una precisazione su questo esempio. Passa direttamente l'output del modello a una shell con shell=True. Questa pratica è accettabile su una macchina di prova che puoi ricreare, ma è errata in tutti gli altri casi. La fase 6 risolve questo problema. I concetti alla base del ciclo sono descritti più dettagliatamente in creare il proprio agente AI su un VPS.

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

Lo strumento run_command funziona, ma un agente reale deve poter accedere a risorse esterne: un sistema di ticketing, un database, un repository. Scrivere un wrapper personalizzato per ogni servizio e per ogni agente non è scalabile.

Il Model Context Protocol (MCP) è la soluzione adottata dal settore. Un server MCP espone un insieme di strumenti tramite un trasporto standard e qualsiasi agente compatibile con MCP può utilizzarlo 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; inoltre, l'argomento che specifica la directory è l'unico percorso che il server potrà utilizzare. Questo è il modello di sicurezza nella sua forma più semplice: è il server a definire il perimetro, non il modello. Configura un client perché utilizzi questo server e l'agente potrà leggere e scrivere file senza che tu debba implementare queste funzioni. L'esecuzione corretta, con un account di servizio e con una spiegazione delle scelte relative al trasporto, è descritta in eseguire server MCP su un VPS per agenti di coding con AI. Per un secondo server che punti a dati reali invece che a una directory temporanea, self-hosting di openGym, un tracker per gli allenamenti include un server in sola lettura. Puoi quindi esercitarti a porre domande sulla tua cronologia di allenamento senza concedere all'agente la possibilità di modificare o eliminare dati.

La lezione di questa fase è che la progettazione degli strumenti è il lavoro più importante. Una descrizione vaga costringe il modello a fare supposizioni. Uno strumento che restituisce quarantamila caratteri satura la finestra di contesto. Uno strumento che può eliminare elementi prima o poi li eliminerà.

Fase 4: memoria, che consiste soprattutto in file

I principianti tendono a usare subito un vector database. Non farlo, almeno non ancora.

Un agente non conserva la memoria tra una chiamata e l'altra. Devi reinviare l'intera conversazione ogni volta. Per questo una sessione lunga costa di più a ogni turno rispetto a una sessione breve. La memoria comporta quindi due problemi. Il primo riguarda ciò che entra nella context window in quel momento. Puoi gestirlo creando riepiloghi, riducendo il vecchio output degli strumenti e memorizzando nella cache il prefisso stabile del prompt, così da pagarne solo una frazione del costo. Il secondo riguarda ciò che sopravvive a un riavvio. Questo è lo storage.

Per il secondo problema, un semplice file Markdown che l'agente può leggere e scrivere è migliore di un vector database per quasi tutti i primi progetti. Dagli un file, specifica il formato e digli di leggere quel file prima di iniziare e di aggiornarlo quando apprende qualcosa. Ottieni gran parte dei vantaggi e puoi aprire il file per vedere cosa ritiene vero il tuo agente. Passa a embeddings e retrieval quando le note non entrano più nella context window, non prima.

Fase 5: il ciclo è il prodotto

A questo punto sai creare un agent che funziona mentre lo osservi. La Fase 5 consiste nel farlo funzionare anche senza supervisione.

Quattro domande determinano se è sicuro lasciare un agent senza supervisione. Che cosa lo attiva, affinché non venga eseguito senza motivo. Entro quali limiti opera, affinché un errore resti circoscritto. Come viene verificato il risultato, perché un agent che corregge da solo i propri compiti li considera sempre corretti. Quale budget lo arresta, in token o in tempo di esecuzione. Progettare deliberatamente questi quattro elementi è la disciplina descritta in ingegneria dei cicli e ambito della definizione.

L'esercizio consiste nel prendere l'agent della fase 2, assegnargli un'attività che richieda quattro o cinque passaggi e aggiungere un limite rigido al numero di iterazioni. Poi rimuovi il limite e osserva quanto un ciclo senza limiti incide sul consumo di token. Esegui questa prova una sola volta con un budget ridotto, così non la ripeterai per errore con un budget elevato.

Fase 6: sicurezza, secret e costi

Questa fase non è opzionale. È l’ultima solo perché il rischio non è percepibile finché non hai costruito qualcosa che funziona.

Esegui l’agent con un proprio utente senza privilegi, mai come root e mai con il tuo account, in modo che il raggio d’azione di un eventuale incidente sia una directory e non l’intera macchina. Mantieni le credenziali fuori dalla portata del modello, perché qualsiasi contenuto presente nella finestra di contesto può essere restituito 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 mantenere i secret fuori dai tuoi agent AI. Imposta un limite massimo rigido alla spesa, perché un loop non supervisionato 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 agent AI su un VPS sempre attivo.

Se l’agent viene eseguito all’interno di un harness anziché in uno script scritto direttamente da te, parte di questa fase consiste nella configurazione e non nel codice. I plugin del DeepSeek Harness che vale la pena installare coprono molti degli stessi aspetti, tra cui limiti di budget, regole per i permessi degli strumenti e scansione delle injection.

I costi meritano un numero concreto. A luglio 2026, Claude Opus 5 applica $5 per un milione di token di input e $25 per un milione di token di output. Un agent loquace che reinvia una conversazione in crescita può far passare 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’agent legge una pagina web, un issue tracker o una casella di posta, chiunque abbia scritto quel testo sta anche scrivendo istruzioni per l’agent. La ricerca web è solitamente lo strumento che apre per primo questo accesso, mentre indirizzare un agent verso la propria istanza SearXNG mostra affiancati il collegamento e la superficie di injection che crea. La difesa non consiste nell’usare un system prompt più sofisticato. Consiste nel definire un confine, perché un agent che non può eliminare un repository non può essere indotto a farlo.

Quale percorso dovresti seguire?

Scegli un solo percorso formativo e completalo, invece di provarne sei in modo superficiale. Il repository ai-agents-for-beginners di Microsoft è il più completo tra quelli gratuiti: è un corso di diciotto lezioni che a luglio 2026 ha superato 70.000 stelle e segue in modo lineare le fasi descritte sopra. Le raccolte di repository per agenti più popolari sono utili per capire quali progetti esistono, ma molto meno come programma di studio, perché un elenco ordinato in base alle stelle riflette la popolarità e non l’ordine didattico.

Quando vuoi esercitarti su un progetto reale, un agente di programmazione è il punto di partenza migliore: il feedback è immediato, gli strumenti sono chiari e gli errori si possono annullare facilmente. Eseguire un agente di IA per la programmazione su un VPS illustra l’intero processo. Se preferisci studiare sistemi funzionanti invece di crearli da zero, il confronto in i migliori agenti IA self-hosted mostra come diversi progetti risolvono 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, dedicato per la maggior parte alla descrizione degli strumenti più che al protocollo. Le fasi 4 e 5 richiedono alcune settimane di utilizzo reale, perché si capisce che cosa dimentica l’agente soltanto osservando quando lo dimentica. La fase 6 non termina mai del tutto: ogni nuova funzionalità assegnata la riapre.

Con due mesi di impegno costante, dedicando le serate al progetto, la maggior parte delle persone arriva a un agente funzionante, con limiti definiti e realmente 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. Si tratta della normale programmazione di applicazioni. Non devi occuparti di training, gradienti o dataset. Le competenze che determinano il corretto 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 soltanto se in seguito vuoi eseguire il fine-tuning di un modello. È un'attività diversa, con prerequisiti diversi.

Devo iniziare con un framework come LangChain o CrewAI?

Scrivi prima un singolo loop senza framework, quindi adottane uno. Un framework sostituisce le trenta righe della fase 2 con un oggetto di configurazione. È comodo quando sai che cosa sostituisce, ma può creare confusione prima di quel momento. Quando l'agente si comporta in modo imprevisto, devi analizzare direttamente l'elenco dei messaggi e i risultati degli strumenti. È molto più difficile se non li hai mai visti. Dopo aver scritto un loop autonomamente, un framework ti fa risparmiare tempo invece di nascondere il meccanismo.

Quanto costa imparare a usare gli agenti AI?

Meno di quanto si aspetti la maggior parte delle persone, se stabilisci un limite. Una chiave API per un servizio hosted e un piccolo VPS sono sufficienti per tutte queste sei fasi. Il rischio reale non è la tariffa oraria, ma un loop senza limiti che addebita ogni iterazione mentre dormi. Imposta fin dal primo giorno un limite di spesa rigido sull'account API, aggiungi un limite al numero di iterazioni a ogni loop che scrivi e usa un modello meno costoso per le attività di routine. 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 sola 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 sono necessari per i chatbot. Una risposta errata di un chatbot è un paragrafo sbagliato. Una risposta errata di un agente è un paragrafo sbagliato, oltre a qualunque azione l'agente abbia eseguito di conseguenza.