Un AI agent e un modello linguistico messo in un ciclo che puo chiamare tool, leggere i risultati e decidere cosa fare dopo, e ripetere finche non raggiunge un obiettivo. Costruirne uno da solo e molto piu semplice di quanto l'hype suggerisca: al cuore, e un ciclo while attorno a un modello che supporta il tool calling. Dai al modello un obiettivo e un set di funzioni, chiede di eseguirne una, la esegui, restituisci il risultato, e continua finche non ha finito. Questa guida ti porta dalla definizione a un agente concreto e minimale che puoi lanciare oggi, poi risale attraverso i livelli di autonomia e cosa cambia quando un agente passa in produzione. Costruiamo prima il ciclo a mano, cosi capisci esattamente cosa succede, poi mostriamo gli SDK che lo fanno per te. Tutto qui e aggiornato a giugno 2026.
Cos'e davvero un AI agent
Un AI agent e un software che usa un modello linguistico per decidere e agire in un ciclo, invece di rispondere una sola volta. Il modello e il cervello, ma un cervello senza mani non puo fare nulla, quindi gli dai dei tool: funzioni che puo chiamare per leggere un file, interrogare un database, cercare sul web o chiamare una API. L'agente gira in ciclo: il modello riceve l'obiettivo e la lista dei tool disponibili, risponde o chiede di chiamare un tool, il tuo codice esegue quel tool e restituisce il risultato, e il modello usa il risultato per decidere il suo prossimo passo. Questo ciclo e tutta l'idea. "Agentic AI" e il termine piu ampio per i sistemi costruiti cosi; un "AI agent" e un tale sistema. Per le definizioni precise, vedi le voci di glossario su AI agent, agentic AI, tool calling e l'agent harness.
- Modello: il cuore di ragionamento che decide cosa fare (un LLM che supporta il tool calling).
- Tool: funzioni che il modello puo chiamare per agire sul mondo, ognuna con un nome, una descrizione e uno schema di input.
- Ciclo: il modello decide, il tuo codice esegue il tool scelto, il risultato torna, si ripete fino alla fine.
- Vedi il glossario: AI agent, agentic AI, tool calling, agent harness per le definizioni formali.
Il ciclo di costruzione, passo dopo passo
Ogni agente, dallo script di dieci righe a Claude Code, fa girare lo stesso ciclo. Invii al modello la conversazione fin qui piu le definizioni di tool. Il modello risponde in uno di due modi: con una risposta finale (ha finito) oppure chiedendo di chiamare uno o piu tool. Se vuole un tool, il tuo codice esegue quel tool, cattura l'output, lo aggiunge alla conversazione come risultato di tool e restituisce tutto. Il modello legge il risultato e decide di nuovo. Ripeti finche il modello non da una risposta finale o raggiungi un limite di sicurezza di iterazioni. I due guard rail non negoziabili sono un numero massimo di turni, perche un agente confuso non giri all'infinito, e la validazione degli input di tool, perche il modello ti chiede di eseguire vero codice con argomenti che sceglie da solo.
- Invia l'obiettivo, la cronologia di conversazione e le definizioni di tool al modello.
- Se il modello restituisce una risposta finale, fermati e restituiscila.
- Se chiede un tool, valida l'input, esegui il tool, aggiungi il risultato e ripeti.
- Limita sempre il numero di iterazioni e valida gli argomenti di tool prima di eseguire.
Un agente minimale che puoi costruire
Ecco il piu piccolo agente che fa qualcosa di reale: un modello con un tool (una calcolatrice) che fa girare il ciclo di tool calling a mano contro l'API Anthropic Messages. Il pattern e identico per ogni fornitore che supporta il tool calling. Il modello riceve la domanda e la definizione del tool; quando risponde con stop_reason "tool_use", eseguiamo il tool, restituiamo un tool_result e ripetiamo finche non da una risposta in puro testo. Leggilo una volta, e la magia sparisce: un agente e un ciclo, un modello e un dizionario di funzioni.
# pip install anthropic
# A minimal agent: one tool, the tool-calling loop by hand.
import anthropic
client = anthropic.Anthropic() # reads ANTHROPIC_API_KEY from the env
# 1) Define the tools: a name, a description, and an input schema.
tools = [
{
"name": "calculator",
"description": "Evaluate a basic arithmetic expression.",
"input_schema": {
"type": "object",
"properties": {"expression": {"type": "string"}},
"required": ["expression"],
},
}
]
# 2) Map tool names to the real functions that run them.
def calculator(expression: str) -> str:
# Real code: validate hard. A toy eval is fine only for a demo.
allowed = set("0123456789+-*/(). ")
if not set(expression) <= allowed:
return "error: invalid characters"
return str(eval(expression)) # demo only; never eval untrusted input in prod
TOOLS = {"calculator": calculator}
# 3) The loop.
def run_agent(goal: str, max_turns: int = 8) -> str:
messages = [{"role": "user", "content": goal}]
for _ in range(max_turns):
resp = client.messages.create(
model="claude-sonnet-4-5",
max_tokens=1024,
tools=tools,
messages=messages,
)
if resp.stop_reason != "tool_use":
return "".join(b.text for b in resp.content if b.type == "text")
messages.append({"role": "assistant", "content": resp.content})
results = []
for block in resp.content:
if block.type == "tool_use":
out = TOOLS[block.name](**block.input)
results.append({
"type": "tool_result",
"tool_use_id": block.id,
"content": out,
})
messages.append({"role": "user", "content": results})
return "stopped: hit the turn limit"
print(run_agent("What is 4321 * 1234, then add 99?"))Questo e davvero tutto cio che e un agente. Per renderlo utile, aggiungi piu tool (leggere un file, chiamare la tua API, interrogare un database), dai a ognuno una descrizione precisa perche il modello sappia quando usarlo, e irrobustisci il percorso di esecuzione. L'eval nella calcolatrice e solo per la demo; non eseguire mai codice o espressioni scelti dal modello senza validazione rigorosa o una sandbox.
Usa un framework appena capisci il ciclo
Costruire il ciclo a mano una volta e il modo migliore di capire gli agenti, ma in produzione ricorri a un framework che gestisce il ciclo, i retry, lo streaming, le sessioni e i permessi per te. Nel 2026, le due vie piu dirette sono il Claude Agent SDK, che offre lo stesso ciclo di agente, lo stesso set di tool e la stessa gestione del contesto che animano Claude Code (installa @anthropic-ai/claude-agent-sdk per TypeScript o claude-agent-sdk per Python), e il OpenAI Agents SDK, un framework Python e TypeScript leggero che trasforma ogni funzione in un tool con generazione automatica dello schema (pip install openai-agents). Entrambi ti danno tool calling, cicli multi-step, checkpoint human-in-the-loop, subagent e supporto MCP di prima classe out of the box. Il principio e lo stesso che hai appena costruito; l'SDK toglie solo la plomberia.
- Claude Agent SDK: lo stesso ciclo e gli stessi tool che fanno girare Claude Code, programmabili in Python e TypeScript, con MCP e subagent integrati.
- OpenAI Agents SDK: un framework multi-agente leggero che trasforma ogni funzione in un tool valido (pip install openai-agents).
- Entrambi gestiscono il ciclo, i retry, lo streaming, le sessioni e i permessi che altrimenti scriveresti a mano.
- Connetti tool esterni via il MCP piuttosto che con collante su misura; vedi Cos'e un server MCP.
I livelli di autonomia
Non ogni agente dovrebbe essere pienamente autonomo, e scegliere il livello giusto e una decisione di progettazione, non un default. Pensa a una scala. In fondo, il modello si limita a proporre, e un umano fa tutto. Un gradino piu su, redige, e un umano approva ogni azione. Piu su, agisce in modo autonomo sui passi a basso rischio ma si ferma per tutto cio che e sensibile, per approvazione (un checkpoint human-in-the-loop). In cima, esegue un intero workflow senza supervisione. Il livello giusto dipende dal costo di un errore: piu un errore fa male, piu mantieni supervisione umana. La maggior parte degli agenti di produzione affidabili siede nel mezzo, pienamente autonoma sulle azioni sicure e reversibili e gated sul resto. Il corso Automation and Agentic Systems tratta questo come i 5 livelli di autonomia degli LLM.
- Solo proporre: l'agente propone, un umano fa tutto. Rischio piu basso, leva piu bassa.
- Redigere e approvare: l'agente prepara l'azione, un umano conferma prima che giri.
- Autonomo con checkpoint: agisce sui passi sicuri e si ferma su quelli rischiosi per approvazione.
- Pienamente senza supervisione: esegue tutto il workflow da solo; riservalo a compiti a basso rischio e reversibili.
Rendere il tuo agente pronto per la produzione
Un agente di demo e un agente di produzione differiscono in tutto cio che circonda il ciclo. Il modello e i tool sono la parte facile; l'affidabilita e il lavoro. Valida ogni input di tool, perche il modello sceglie gli argomenti. Esegui tutto cio che esegue codice o tocca il mondo esterno in una sandbox con timeout e limiti di risorse, mai su una macchina che conta per te. Logga ogni passo (l'obiettivo, ogni chiamata di tool, ogni risultato), per vedere cosa ha fatto l'agente e poterlo debuggare quando qualcosa va storto. Limita le iterazioni e i costi, perche un agente confuso non giri all'infinito ne faccia salire una fattura. E mantieni un umano nel ciclo per le azioni irreversibili o sensibili. Sono le stesse lezioni che i build del fondatore hanno imparato a proprie spese: CallAssistant ha dato al suo agente vocale tool strettamente definiti perche non c'e un "sei sicuro?" al telefono, e CodeCourier ha eseguito codice non affidabile solo in una sandbox usa e getta.
- Valida gli input di tool ed esegui i tool che eseguono codice in una sandbox con timeout e limiti.
- Logga l'obiettivo, ogni chiamata di tool e ogni risultato, perche l'agente sia osservabile e debuggabile.
- Limita le iterazioni e le spese, perche un ciclo impazzito non ti costi tempo ne denaro.
- Metti in gate le azioni irreversibili o sensibili dietro un passo di approvazione human-in-the-loop.
- Impara dai veri build: CallAssistant (tool ristretti) e CodeCourier (sandboxing) nella pagina Builds.
Passo dopo passo
Scegliere un modello di tool calling
Scegli un modello che supporta il tool calling (per esempio un tier Claude o GPT) e ottieni una chiave API. Il ciclo di agente e identico su tutti i fornitori che supportano i tool.
Definire i tuoi tool
Per ogni azione di cui l'agente ha bisogno, scrivi una funzione e una definizione di tool con un nome, una descrizione chiara e uno schema di input. La descrizione e cio che il modello legge per decidere quando chiamarlo.
Scrivere il ciclo
Invia l'obiettivo, la conversazione e le definizioni di tool al modello. Se da una risposta finale, fermati. Se chiede un tool, valida l'input, esegui il tool, aggiungi il risultato e restituisci tutto.
Aggiungere guard rail
Limita il numero di iterazioni, valida ogni argomento di tool ed esegui ogni tool che esegue codice in una sandbox con timeout. Logga ogni passo per vedere cosa ha fatto l'agente.
Scegliere un livello di autonomia
Decidi quali azioni l'agente puo eseguire senza supervisione e quali hanno bisogno di approvazione umana, secondo il costo di un errore. Metti in gate le azioni irreversibili o sensibili dietro un checkpoint.
Passare a un SDK per la produzione
Una volta chiaro il ciclo, adotta il Claude Agent SDK o il OpenAI Agents SDK per ottenere retry, streaming, sessioni, permessi e supporto MCP senza scrivere la plomberia da solo.