Come imparare gli agenti AI da zero

Il percorso in sei fasi

Per imparare da zero a usare gli agenti AI, segui sei fasi in ordine: concetti, primo ciclo, strumenti, memoria, progettazione del ciclo e sicurezza. In ogni fase costruisci personalmente un elemento. Saltare in 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 intorno a un modello linguistico che può 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 qualcosa va storto. Se riesci a spiegare il ciclo a un'altra persona, hai imparato il concetto. Se sai solo elencare i framework, non l'hai ancora imparato.

Il piano seguente presuppone che tu impari costruendo. Leggi una fase, costruisci l'elemento semplice previsto, danneggialo intenzionalmente, quindi passa alla fase successiva. Una fase che hai soltanto letto è una fase che non hai ancora svolto.

Cosa serve realmente prima della fase 1

L'elenco onesto dei prerequisiti è breve, ed è 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 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 è l'intero elenco. Non ti servono conoscenze teoriche di machine learning e non devi aver addestrato un modello. Nel lavoro con gli agenti non ci sono gradienti o dati di addestramento. Una scheda grafica serve solo se decidi di eseguire direttamente il modello, un'attività separata che potrai imparare in seguito consultando ospitare Ollama su un VPS per eseguire autonomamente un LLM.

La parte relativa alla shell è quella che viene spesso sottovalutata. Gli agenti falliscono a causa di permessi, percorsi, variabili d'ambiente e processi che terminano senza messaggi. Se una traccia dello stack relativa a PATH o a una modalità di file ti induce 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 agente e che cosa non è

Inizia con una sola chiamata API e senza un ciclo. 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, che è l'unica idea realmente nuova dell'intero settore. Descrivi una funzione al modello indicando un nome, una descrizione e uno schema JSON (notazione degli oggetti JavaScript) 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 di nuovo 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 sola risposta. Un agente ripete questo scambio finché il modello non smette di richiedere strumenti. Questa ripetizione è l'unica differenza sostanziale e spiega perché anche le modalità di errore siano diverse. 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 per definire direttamente la struttura del programma.

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 intenzionalmente. Elimina la riga tool_use_id e leggi l'errore, perché l'API rifiuta un risultato dello strumento privo di un id corrispondente; è il bug più comune per chi inizia. Poni una domanda che richieda due comandi e osserva il ciclo eseguirsi due volte. Poni una richiesta impossibile e osserva se il ciclo rinuncia o continua indefinitamente.

Un'avvertenza su questo esempio. Passa direttamente l'output del modello a una shell con shell=True. Questo è accettabile su una macchina di prova che puoi ricreare, ma è errato in qualsiasi altro contesto. La fase 6 risolve questo problema. I concetti alla base del ciclo sono trattati 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 al sistema: un sistema di ticket, 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ò usarlo senza codice di integrazione personalizzato. Il server filesystem di riferimento si avvia con un comando:

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

Node deve essere installato e l'argomento relativo alla directory è l'unico percorso che il server potrà usare. Questo mostra in forma ridotta il modello di sicurezza: è il server a stabilire il perimetro, non il modello. Configura un client per usarlo e il tuo 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 esecuzione di server MCP su un VPS per agenti di codifica basati sull'IA.

La lezione di questa fase è che la progettazione degli strumenti è il lavoro principale. Una descrizione vaga costringe il modello a fare supposizioni. Uno strumento che restituisce quarantamila caratteri compromette la finestra di contesto. Uno strumento che può eliminare elementi finirà prima o poi per eliminarli.

Fase 4: memoria, che consiste soprattutto in file

I principianti ricorrono qui a un database vettoriale. 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ù per turno rispetto a una sessione breve. La memoria si divide quindi in due problemi. Il primo riguarda ciò che può rientrare nella finestra di contesto in quel momento. Puoi gestirlo creando riepiloghi, eliminando l'output meno recente degli strumenti e memorizzando nella cache il prefisso stabile del prompt, così da pagarne solo una frazione. Il secondo riguarda ciò che sopravvive a un riavvio: l'archiviazione.

Per il secondo problema, un semplice file markdown che l'agente può leggere e scrivere è preferibile a un database vettoriale per quasi tutti i primi progetti. Assegna all'agente un file, indicagli il formato e digli di leggere il file prima di iniziare e di aggiornarlo quando apprende qualcosa. Ottieni gran parte dei vantaggi e puoi aprire il file per verificare cosa ritiene vero il tuo agente. Ricorri agli embeddings e al recupero quando gli appunti non rientrano più nella finestra di contesto, e non prima.

Fase 5: il ciclo è il prodotto

A questo punto puoi creare un agent che lavora mentre lo osservi. La Fase 5 consiste nel farlo funzionare quando non lo osservi.

Quattro domande determinano se puoi lasciare un agent senza supervisione in condizioni di sicurezza. Cosa lo attiva, in modo che non venga eseguito senza motivo. Entro quali limiti opera, così un errore resta circoscritto. Come viene verificato il risultato, perché un agent che valuta il proprio lavoro assegna sempre un esito positivo. Quale budget lo arresta, in token o in tempo effettivo. Progettare deliberatamente questi quattro aspetti è la disciplina descritta in ingegneria dei cicli e cosa comprende questa definizione.

L'esercizio: prendi l'agent della fase 2, assegnagli un'attività che richieda quattro o cinque passaggi e aggiungi un limite massimo rigido alle iterazioni. Poi rimuovi il limite e osserva l'effetto di un ciclo senza limiti sulla spesa in token. Esegui questa prova una volta con un budget ridotto, per evitare di farlo accidentalmente con un budget elevato.

Fase 6: sicurezza, segreti e costi

Questa fase non è facoltativa. È l'ultima solo perché il rischio diventa evidente dopo aver creato qualcosa che funziona.

Esegui l'agent con un proprio utente senza privilegi, mai come root e mai con il tuo account. In questo modo l'ambito del danno resta una directory invece dell'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 durata breve e ambito limitato, gestiti tramite un helper, come descritto in mantenere i segreti 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.

Per i costi serve un numero concreto. A luglio 2026, Claude Opus 5 addebita $5 per milione di token di input e $25 per milione di token di output. Un agent verboso che invia nuovamente una conversazione in crescita può far passare alcune centinaia di migliaia di token per una singola attività. Il prompt caching e un modello più piccolo per le operazioni 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 difesa non consiste nell'usare un system prompt più sofisticato. Consiste nel definire il confine, perché un agent che non può eliminare un repository non può essere indotto a eliminarlo.

Quale percorso dovresti seguire?

Scegli un solo percorso formativo e completalo invece di provarne sei. Il repository ai-agents-for-beginners di Microsoft è il più completo tra quelli gratuiti: comprende un corso di diciotto lezioni che a luglio 2026 ha superato 70.000 stelle e si integra bene con le fasi descritte sopra. Le raccolte di repository per agenti più popolari sono utili per vedere cosa esiste, ma molto meno come programma di studio, perché un elenco ordinato per numero di stelle è ordinato in base alla popolarità, non all’ordine didattico.

Quando vuoi esercitarti su un progetto reale, un agente di codifica è il primo obiettivo migliore: il feedback è immediato, gli strumenti sono chiari e gli errori sono facili da annullare. Eseguire un agente AI di codifica su un VPS illustra l’intero processo. Se preferisci studiare sistemi funzionanti invece di crearne uno da zero, il confronto in i migliori agenti AI 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, trascorso per la maggior parte a descrivere gli strumenti anziché a lavorare sul protocollo. Le fasi 4 e 5 richiedono alcune settimane di utilizzo reale, perché impari che cosa dimentica il tuo agente solo osservando quando lo dimentica. La fase 6 non termina mai del tutto: ogni nuova funzionalità che concedi la riapre.

Due mesi di serate regolari sono sufficienti per arrivare, nella maggior parte dei casi, 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. Si tratta di normale programmazione di applicazioni. Non è necessario occuparsi 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 si passa al fine-tuning di un modello. È un'attività diversa, con prerequisiti diversi.

Devo iniziare con un framework come LangChain o CrewAI?

Prima scrivere un singolo loop senza framework, poi adottare un framework. Un framework sostituisce le trenta righe della fase 2 con un oggetto di configurazione. È comodo quando si sa cosa ha sostituito, ma può creare confusione prima di quel momento. Quando l'agente si comporta in modo imprevisto, è necessario analizzare direttamente l'elenco dei messaggi e i risultati degli strumenti. È molto più difficile farlo senza averli mai visti. Dopo aver scritto un loop autonomamente, un framework fa risparmiare tempo invece di nascondere il meccanismo.

Quanto costa imparare a usare gli agenti AI?

Meno di quanto la maggior parte delle persone si aspetti, se si impongono dei limiti. Una chiave API di un servizio ospitato e un piccolo VPS sono sufficienti per tutte queste sei fasi. Il rischio reale non è il costo orario. È un loop senza limiti che addebita ogni iterazione mentre si dorme. Impostare fin dal primo giorno un limite massimo di spesa sull'account API, aggiungere un limite alle iterazioni di ogni loop e usare un modello meno costoso per le attività ordinarie. 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 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 i chatbot non richiedono. 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.