Cos'è un agente di intelligenza artificiale: un modello dentro un ciclo
Un agente di intelligenza artificiale è un programma in cui un modello di linguaggio decide da solo quali strumenti usare e quando fermarsi, invece di seguire un percorso scritto in anticipo. La definizione è quella di Anthropic, che nel saggio Building effective agents del 19 dicembre 2024 chiama agenti i sistemi in cui "LLMs dynamically direct their own processes and tool usage". Il resto dell'oggetto è ordinaria ingegneria: un modello, alcuni strumenti e un ciclo che continua finché il modello non ha più niente da chiedere.
Cos'è un agente di intelligenza artificiale e in cosa si distingue da un workflow
Un agente di intelligenza artificiale si distingue da un workflow per chi decide il passo successivo: nel workflow lo decide il codice, nell'agente lo decide il modello. Sempre nel saggio del 19 dicembre 2024, Anthropic definisce i workflow come sistemi in cui modelli e strumenti sono orchestrati "through predefined code paths", cioè lungo percorsi scritti in anticipo da una persona.
La differenza si vede in quattro punti, che sono anche i quattro punti su cui si sbaglia la scelta.
| Workflow | Agente | |
|---|---|---|
| Chi decide il passo successivo | Il codice, con un percorso fisso | Il modello, in base a quello che ha appena letto |
| Numero di passi | Noto prima di partire | Non noto, dipende dal compito |
| Costo e durata | Prevedibili | Variabili, vanno limitati con un tetto |
| Quando conviene | Compiti ripetibili con passi stabili | Compiti aperti, dove i passi non si conoscono prima |
Il saggio di Anthropic consiglia di cercare "the simplest solution possible" e di aumentare la complessità solo quando serve. Per questo un workflow automatizzato batte quasi sempre un agente sui compiti che sai già descrivere in fila.
Come funziona un AI agent: il ciclo in tre fasi
Un AI agent funziona ripetendo un ciclo di tre fasi: raccoglie contesto, compie un'azione, verifica il risultato. La documentazione di Claude Code, uno degli agenti più usati da chi sviluppa, descrive esattamente questo ciclo con le parole "gather context, take action, and verify results", e spiega che il ciclo è alimentato da due componenti, "models that reason and tools that act".
Gli strumenti sono la parte che fa la differenza. La documentazione di Claude Code scrive che senza strumenti il modello "can only respond with text", mentre con gli strumenti può leggere file, modificarli, lanciare comandi e cercare sul web, e che ogni risultato torna nel ciclo e orienta la scelta seguente. Quando si chiede di correggere dei test che falliscono, la sequenza tipica è questa:
- Lancia la suite di test per vedere cosa fallisce.
- Legge l'output dell'errore.
- Cerca i file sorgente rilevanti.
- Legge quei file.
- Modifica il codice.
- Rilancia i test per verificare.
Un chatbot si ferma al primo passo e risponde con del testo. L'agente continua finché il risultato della sesta riga non gli dice che ha finito.
Cos'è l'harness che sta attorno al modello
L'harness è lo strato di codice attorno al modello che fornisce gli strumenti e gestisce il contesto che il modello vede. Nella documentazione di Claude Code questo strato prende il nome di "agentic harness", e il suo significato per chi sceglie un prodotto è spiegato in cos'è un agent harness.
Come si scrive il ciclo di un agente in codice
Il ciclo di un agente con l'API di Claude è un ciclo for che si ripete finché la risposta ha stop_reason uguale a tool_use. La documentazione dell'API di Claude spiega che, quando il modello vuole usare uno strumento, la risposta contiene uno o più blocchi tool_use con id, name e input, e che la risposta successiva deve rimandare il risultato in un blocco tool_result con lo stesso id.
import anthropic
client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Correggi i test che falliscono"}]
for _ in range(20): # tetto di giri: scelto da me, non è un valore standard
risposta = client.messages.create(
model="claude-sonnet-5-5",
max_tokens=4096,
tools=STRUMENTI,
messages=messages,
)
messages.append({"role": "assistant", "content": risposta.content})
if risposta.stop_reason != "tool_use":
break # il modello ha finito
risultati = []
for blocco in risposta.content:
if blocco.type == "tool_use":
esito = esegui(blocco.name, blocco.input)
risultati.append({
"type": "tool_result",
"tool_use_id": blocco.id,
"content": esito,
})
messages.append({"role": "user", "content": risultati})
Cosa scrivi tu e cosa no
Nel codice di un agente le parti che scrivi tu sono due: STRUMENTI, l'elenco degli strumenti con il loro schema, ed esegui, la funzione che li lancia davvero. Sono anche le due parti dove stanno i permessi. Se uno strumento fallisce, il risultato si rimanda con "is_error": true, e il saggio di Anthropic indica come prassi comune proprio il tetto di iterazioni che nel codice sta sulla prima riga del ciclo.
Cosa ho visto nell'agente che scrive su questo sito
L'agente che pubblica gli articoli di attualità di questo blog è un ciclo come quello sopra, con strumenti per leggere Notion, aprire pagine web e lanciare comandi, come si legge nel suo prompt in automazione-blog/cloud-agent/prompt-articolo-notizie.md. Legge le righe di un database Notion, apre la fonte di ogni notizia per verificarla e scrive un file .mdx dentro content/blog/.
Il punto in cui un agente vero si distingue da uno finto è la condizione di arresto, e in quel prompt sta nel passo della build. Il comando npm run build passa o fallisce, e se fallisce l'agente non fa commit né push. C'è poi un tetto esplicito di due articoli al giorno sul sito intero. Sono i due controlli che trasformano un modello lasciato libero in un lavoro di cui ci si può fidare senza guardarlo: il primo dà un esito verificabile, il secondo limita il danno. Come si mettono questi limiti in un'azienda l'ho scritto in come creare un agente di intelligenza artificiale in azienda.
Quando un agente AI serve davvero e quando basta altro
Un agente AI serve quando il compito è aperto e ha un controllo che non richiede una persona: se non sai quali passi serviranno ma sai dire da solo quando il risultato è giusto, l'agente è lo strumento adatto. Se i passi li conosci in anticipo, basta un workflow. Se serve solo una risposta, basta un chatbot, e il confine fra i due è nel permesso di agire, come spiego in differenza tra chatbot e agente di intelligenza artificiale.
Prima di costruirne uno, scrivi su una riga chi dichiara che il lavoro è finito bene. Se nella riga compare il nome di una persona, il primo lavoro è costruire quel controllo. Poi fissa due numeri: i giri massimi del ciclo e la spesa massima, perché senza tetto un agente trasforma un costo noto in un costo variabile. Per capire dove un agente rende e dove costa più di quello che porta c'è a cosa servono gli agenti di intelligenza artificiale in azienda. Se invece hai già un processo in mente e vuoi farlo costruire, è il lavoro che faccio con gli agenti AI su misura.
Domande frequenti
Cosa significa AI agent e come si traduce in italiano?
AI agent è il nome inglese dello stesso oggetto che in italiano si chiama agente AI o agente di intelligenza artificiale. Non esiste una differenza tecnica fra le tre forme: indicano un programma in cui un modello di linguaggio decide quali strumenti usare e quando fermarsi. Le documentazioni di Anthropic usano il termine inglese agents, i testi italiani alternano le due forme.
Come si ferma un agente AI mentre sta lavorando?
Dipende da chi lo ha costruito, ma gli strumenti seri prevedono un'interruzione esplicita. Nella documentazione di Claude Code, il tasto Esc ferma subito l'agente e annulla la chiamata allo strumento in corso, mentre un messaggio scritto durante il lavoro viene letto appena finiscono le chiamate in esecuzione. Un agente scritto a mano con l'API non ha niente di tutto questo gratis: il tetto di giri e il punto di fermata li scrive chi lo costruisce.
Si possono annullare le azioni compiute da un agente AI?
Solo in parte. Claude Code salva una copia dei file prima di modificarli e permette di tornare indietro premendo due volte Esc, ma la documentazione ufficiale precisa che le azioni su sistemi remoti come database, API e rilasci non si possono ripristinare con i checkpoint. La reversibilità di un agente vale per i file locali, non per tutto quello che gli si lascia toccare.
Perché l'API di Claude risponde con errore 400 su un tool_result?
Spesso perché il messaggio con i risultati degli strumenti non rispetta l'ordine richiesto. La documentazione dell'API spiega che i blocchi tool_result devono seguire subito il blocco tool_use corrispondente e che, nel messaggio dell'utente, devono stare prima di qualsiasi testo. Se compare l'errore sugli id di tool_use senza tool_result, il primo controllo è questo.