Cerca "claude agent sdk" oggi e i risultati sono quasi tutti guide pratiche: la repository ufficiale, la documentazione, qualche tutorial per costruire un primo agente. È il contenuto giusto per chi sta valutando se costruirci sopra. Non è il contenuto giusto per chi l'ha già deciso, e ora deve consegnare quell'agente a un cliente.
Cos'è il Claude Agent SDK, e chi ci costruisce sopra
Il Claude Agent SDK è il toolkit di Anthropic per costruire agenti personalizzati sulla stessa infrastruttura che fa girare Claude Code: l'harness che gestisce il contesto, chiama i tool, e lavora in loop su un task finché non lo considera finito. È disponibile per Python e TypeScript, ed è lo stesso motore che Anthropic usa internamente per Claude Code stesso, esposto perché altri team possano costruirci il proprio agente sopra invece di limitarsi a usare quello confezionato.
I team che ci si rivolgono non sono hobbisti. Sono software house e team di piattaforma interni che vogliono un agente costruito attorno a un flusso di lavoro specifico, a un set di tool specifico, a un flusso di approvazione specifico, invece della sessione general-purpose che Claude Code offre di default. Costruire sull'SDK significa che l'architettura dell'agente diventa qualcosa che il team possiede e può modellare, non qualcosa che configura ai margini.
Stesso motore di Claude Code, responsabilità diverse
Claude Code e un agente costruito sull'SDK condividono lo stesso loop di base sotto il cofano: leggere il contesto, decidere una chiamata a un tool, eseguirla, osservare il risultato, decidere di nuovo. Quello che cambia è chi risponde delle parti attorno a quel loop. Claude Code, come prodotto, arriva con prompt di permesso, log di sessione, e una superficie di supporto che Anthropic mantiene. Un agente costruito sull'SDK eredita il motore, non le decisioni di prodotto che ci girano attorno: è il team che scrive l'agente a decidere cosa viene loggato, cosa deve approvare una persona, e cosa succede quando una chiamata a un tool fallisce a metà di un task.
È uno scambio che un team fa di proposito, e di solito è quello giusto quando il flusso di lavoro è abbastanza specifico da non stare dentro lo strumento confezionato. Ma significa che ogni domanda che un buyer farebbe sulle protezioni di Claude Code diventa una domanda che il team deve rispondere sul proprio agente, perché non c'è più un default del vendor a cui rimandare.
Cosa arriva pronto all'uso e cosa deve aggiungere un team
L'SDK dà la meccanica: orchestrazione dei tool, gestione del contesto, streaming, hook per intercettare le azioni prima o dopo che girano. Non dà una pista di controllo per default. Un hook può catturare che un tool è girato, ma niente obbliga il team a salvare quel record da qualche parte durevole, a marcarlo con un timestamp, o a collegarlo alla richiesta che l'ha innescato. Va costruito, deliberatamente, sopra gli hook che l'SDK espone.
Lo stesso vuoto si presenta sull'autorizzazione. L'SDK permette a un team di collegare controlli di permesso prima che un tool esegua, ma non porta un'opinione su cosa dovrebbe richiedere una firma umana e cosa può girare senza sorveglianza. Il team di prodotto di Claude Code ha preso quelle decisioni per lo strumento confezionato e continua a rivederle; un team che costruisce sull'SDK non eredita automaticamente nessuno di quei giudizi, deve prenderli da solo, per il proprio agente, ed essere pronto a difenderli.
Il vuoto di prova che si apre quando costruisci l'agente da solo
Qui la responsabilità si sposta davvero. Con un agente di coding confezionato, un buyer può almeno chiedere al vendor cosa logga lo strumento e come. Con un agente personalizzato costruito sull'SDK, non c'è un vendor a cui chiedere: il formato del log, la conservazione, il collegamento tra una specifica modifica di codice e la richiesta che l'ha autorizzata, tutto questo è una decisione che il team che ha costruito l'agente ha preso, o più spesso non ha preso esplicitamente, da qualche parte nel codebase.
Quel vuoto non salta fuori durante una demo. Salta fuori mesi dopo, quando un cliente chiede perché è stata fatta una certa modifica, e la risposta onesta è che i log di esecuzione dell'agente non sono mai stati pensati per rispondere a quella domanda, perché nessuno ha trattato "chi può ricostruire questo a posteriori" come un requisito mentre l'agente veniva costruito. Un agente personalizzato che scrive codice eccellente ma non lascia dietro di sé niente di strutturato su come ci è arrivato non ha ridotto l'esposizione del team, l'ha solo spostata da "quale strumento" a "quale decisione interna, presa da noi, senza un vendor a cui rimandare".
Una checklist breve prima di consegnare un agente personalizzato a un cliente
Prima che un agente basato sull'SDK si avvicini al codebase di un cliente, vale la pena rispondere esplicitamente ad alcune domande, non lasciarle implicite in quello che gli hook loggano per caso:
- Cosa ha innescato questa sessione, ed è registrato da qualche parte in modo durevole, non solo in una cronologia di chat che si può modificare o perdere?
- A quale contesto era autorizzato l'agente ad accedere, e quello scope è scritto da qualche parte fuori dal prompt stesso?
- Quali azioni sono girate senza sorveglianza, e quali hanno richiesto l'approvazione di una persona, ed è una distinzione applicata nel codice o solo in un documento di policy che nessuno controlla?
- Se un cliente chiede, tra sei mesi, perché un certo file è cambiato, si può rispondere dal log, o la risposta dipende dal fatto che qualcuno si ricordi la sessione?
Niente di tutto questo è specifico del Claude Agent SDK. Qualsiasi agente di coding pone la stessa domanda quando la sessione finisce. Quello che cambia qui è che con uno strumento confezionato, un team può almeno rimandare alla risposta del vendor, per quanto imperfetta. Costruisci l'agente da solo, e la risposta deve essere quella che il team ha scritto, perché la checklist che un buyer segue prima di consegnare un agente a un team non smette di contare solo perché l'agente è personalizzato, diventa più difficile da superare. Detent Bench misura esattamente quella linea, dalla richiesta al production-ready, qualunque sia il motore che scrive.