Passa al contenuto principale

Costruire agenti sull'API

Avanzato
What you'll learn
  • 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.
Watch out

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:

Guided walkthrough1 of 4
  1. Dichiara l'obiettivo, i vincoli e gli strumenti disponibili. È ciò su cui il modello ragiona a ogni turno.

Il Claude Agent SDK ti fornisce questo loop — strumenti, permessi, gestione del contesto — già pronto, così non devi costruirtelo a mano.

Pro tip

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.
Key takeaways
  • 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

Mettiti alla prova​

Mettiti alla prova

0/5
  1. Qual è la migliore descrizione di un agente in questo contesto?
  2. Il task ha passi fissi e noti. A cosa dovresti ricorrere?
  3. Quando è davvero giustificato un agente personalizzato?
  4. Nel loop, cosa succede quando il modello risponde con un tool_use?
  5. Quale NON è uno dei guardrail per rendere robusto un agente?

Avanti​