Come costruire il tuo primo agente IA: un modello, qualche strumento e un loop

"Agente IA" suona come qualcosa che dovrebbe richiedere un framework, un database vettoriale e un weekend di configurazione. Non è così. La definizione di Anthropic è piacevolmente essenziale: un agente è un LLM che usa autonomamente strumenti in un loop. Una volta colto il pattern, puoi costruire un primo agente utile in ben meno di cento righe di codice — e, cosa altrettanto importante, sapere quando non dovresti.

Il loop fondamentale

Ogni agente, per quanto sofisticato, è lo stesso ciclo in quattro passi:

1. Dai al modello un obiettivo e un elenco di strumenti che gli è consentito chiamare.
2. Il modello decide se rispondere direttamente o chiamare uno strumento.
3. Il tuo codice esegue lo strumento e restituisce il risultato al modello.
4. Ripeti finché il modello non dichiara di aver finito.

Il modello non tocca mai direttamente il tuo filesystem o la tua rete. Si limita sempre a chiedere di eseguire uno strumento; è il tuo codice a decidere se e come farlo davvero. È in quello scarto che risiede tutta la tua sicurezza.

Un esempio concreto

Ecco un agente minimo in grado di rispondere a domande usando uno strumento calcolatrice. Ciò che conta è la struttura — la stessa forma scala alla modifica di file, alla ricerca sul web o alle query su database.

import anthropic

client = anthropic.Anthropic()

tools = [{
    "name": "calculator",
    "description": "Evaluate a basic arithmetic expression and return the result.",
    "input_schema": {
        "type": "object",
        "properties": {"expression": {"type": "string"}},
        "required": ["expression"],
    },
}]

def run_tool(name, args):
    if name == "calculator":
        # In real code, use a safe parser, not eval()
        return str(eval(args["expression"], {"__builtins__": {}}))
    return "unknown tool"

messages = [{"role": "user", "content": "What is 1894 * 37 plus 12?"}]

while True:
    resp = client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=1024,
        tools=tools,
        messages=messages,
    )
    messages.append({"role": "assistant", "content": resp.content})

    if resp.stop_reason != "tool_use":
        print(resp.content[0].text)
        break

    tool_results = []
    for block in resp.content:
        if block.type == "tool_use":
            result = run_tool(block.name, block.input)
            tool_results.append({
                "type": "tool_result",
                "tool_use_id": block.id,
                "content": result,
            })
    messages.append({"role": "user", "content": tool_results})

Quel loop while è l'agente. Il modello vede la domanda, chiede di chiamare calculator con "1894 * 37 + 12", il tuo codice lo esegue, restituisce 70090, e il modello scrive la risposta finale. Sostituisci la calcolatrice con una coppia read_file/write_file e hai un agente di coding primitivo.

Gli strumenti sono la parte che conta davvero

Il modello è capace solo quanto gli strumenti che gli fornisci, e la progettazione degli strumenti è il punto in cui la maggior parte dei primi agenti fallisce. Le indicazioni di Anthropic su come scrivere strumenti per gli agenti si riducono a poche regole:

• Nomina e descrivi gli strumenti come se stessi scrivendo per un nuovo collega. search_invoices(customer_id, date_range) è meglio di un vago query(sql) — più chiaro è il contratto, meno chiamate sbagliate ci saranno.
• Restituisci risultati ad alto valore informativo, non dump grezzi. Se uno strumento restituisce 5.000 righe di JSON, hai appena speso il budget di contesto del modello in rumore. Riduci a ciò che è utile.
• Rendi gli errori istruttivi. "File non trovato: intendevi config.yaml?" permette al modello di recuperare; un nudo stack trace di solito no.

Guardrail prima di lasciarlo correre

Dato che è il tuo codice a eseguire ogni chiamata a uno strumento, la sicurezza è una tua responsabilità. Tre guardrail da aggiungere prima che un agente tocchi qualcosa di reale:

• Limita il loop. Aggiungi un conteggio massimo di iterazioni in modo che un agente confuso non possa girare all'infinito (facendo lievitare il conto).
• Proteggi le azioni distruttive. Qualsiasi cosa che cancella, invia o paga dovrebbe richiedere una conferma o essere eseguita prima in una sandbox.
• Valida gli input degli strumenti. Non usare mai eval() su stringhe non attendibili né passare l'output del modello direttamente a una shell. Tratta ogni argomento di uno strumento come input utente non attendibile — perché di fatto lo è.

Quando NON costruire un agente

La cosa più utile da imparare presto: molti problemi non richiedono affatto un agente. Se i passi sono noti in anticipo — recupera i dati, riassumili, invia il riassunto via email — un semplice script con una o due chiamate al modello è più economico, più veloce e più facile da debuggare. Anthropic li chiama workflow, e li raccomanda ogni volta che il percorso è prevedibile. Ricorri a un vero agente solo quando il modello ha genuinamente bisogno di decidere cosa fare in seguito sulla base di ciò che trova.

Parti dal loop in quattro passi qui sopra, dagli uno o due strumenti ben descritti, limita le iterazioni e aggiungi un compito reale. Imparerai di più da un singolo agente funzionante che da qualsiasi quantità di documentazione di un framework.