Costruire agenti sull'API
- Definire cos'è davvero un agente: un modello che gira in un loop
- Applicare il test decisionale per scegliere tra chiamata singola, workflow e agente
- Progettare un loop di agente minimale con le giuste protezioni
- Sapere quando ricorrere al Claude Agent SDK invece di costruirlo a mano
- Rendere un agente robusto: limitarlo, gestire i fallimenti, restringere i privilegi, valutarlo
Un agente è un modello che gira in un loop: persegue un obiettivo chiamando strumenti, osservando i risultati e decidendo il passo successivo fino al completamento. Prima di costruirne uno, scegli la cosa più semplice che funziona.
Il test decisionale (non costruire troppo)
Non ogni task richiede un agente. Percorri prima questo albero — la maggior parte dei task si ferma in cima.
Tre opzioni, dalla più semplice:
- Chiamata singola — un prompt risolve tutto. La maggior parte dei task. La più economica e affidabile.
- Workflow — orchestri nel codice una sequenza fissa di chiamate (flusso di controllo deterministico). Usalo quando i passi sono noti.
- Agente — è il modello a decidere i passi dinamicamente. Usalo solo quando il percorso non può davvero essere codificato a priori.
Ricorri a un agente quando l'adattività è il punto centrale — non perché suona impressionante. Un workflow che controlli tu è più facile da testare e correggere.
Progettare il loop
Un agente personalizzato minimale è fatto solo di quattro componenti. Costruiscili in quest'ordine:
- Dichiara l'obiettivo, i vincoli e gli strumenti disponibili. È ciò su cui il modello ragiona a ogni turno.
- Invia i messaggi → se la risposta è un tool_use, esegui lo strumento, aggiungi un tool_result e ripeti → fino a una risposta finale o a una condizione di stop.
- Aggiungi un limite massimo di iterazioni, un budget di token/costo e la validazione degli input degli strumenti prima che qualsiasi cosa venga eseguita.
- Riassumi o sfoltisci man mano che la cronologia cresce — la stessa idea trattata in Gestione del contesto (/docs/claude-code/context-management).
Il Claude Agent SDK ti fornisce questo loop — strumenti, permessi, gestione del contesto — già pronto, così non devi costruirtelo a mano.
Prima di scrivere il tuo loop, chiediti se l'Agent SDK lo copre già. Include il loop, i permessi e la gestione del contesto, così puoi concentrarti sugli strumenti e sull'obiettivo.
Rendilo robusto
Un loop che può chiamare strumenti può anche comportarsi male. Quattro abitudini mantengono un agente affidabile:
- Poni limiti a tutto: iterazioni, tempo, costo. Gli agenti possono entrare in loop.
- Gestisci i fallimenti degli strumenti con eleganza (restituisci l'errore come risultato).
- Privilegio minimo + human-in-the-loop per le azioni rischiose — vedi Mettere in sicurezza gli agenti.
- Valutalo su casi reali prima di fidartene — vedi Valutazioni.
- Un agente è un modello in un loop che chiama strumenti verso un obiettivo — usane uno solo quando il percorso non può essere codificato a priori
- Ordine decisionale: chiamata singola → workflow → agente → agenti gestiti; preferisci la cosa più semplice che funziona
- Un loop minimale = system prompt + loop tool_use/tool_result + guardrail + gestione del contesto
- Il Claude Agent SDK include per te il loop, gli strumenti, i permessi e la gestione del contesto
- Robustezza = porre limiti a iterazioni/tempo/costo, gestire i fallimenti degli strumenti, privilegio minimo + human-in-the-loop, e valutare prima di fidarsi