Negli ultimi mesi, il termine "Claude Agent SDK" ha registrato circa 1.000 ricerche mensili in Germania, con una bassa concorrenza. Anthropic ha aggiornato la documentazione tedesca il 6 ottobre 2026, tre giorni prima della pubblicazione di questo articolo. Questa guida completa copre l'installazione, la configurazione, i permessi, gli hook e un esempio di progetto che può essere riutilizzato.

Il Claude Agent SDK si differenzia dall'API classica di Claude perché non esegue solo un modello linguistico che restituisce testo, ma un'intera loop agentiva in cui Claude legge file, modifica codice, esegue comandi e decide quando un compito è completato. Questa guida mostra come impostare il SDK, creare un primo agente che trova e corregge automaticamente errori di programmazione e assicurare il setup per l'uso produttivo.

Cos'è il Claude Agent SDK e a cosa serve?

Il Claude Agent SDK è una libreria Python e TypeScript di Anthropic che consente agli sviluppatori di integrare la stessa loop agentiva utilizzata da Claude Code nelle proprie applicazioni. Invece di programmare una loop di strumenti che analizza le risposte del modello, riconosce le chiamate di funzione e restituisce i risultati, il SDK si occupa di tutto questo lavoro. Include strumenti predefiniti per leggere, scrivere e modificare file, esecuzione di Bash, ricerca web, un sistema di autorizzazioni, gestione delle sessioni e hook per codice personalizzato in punti critici del flusso.

Tecnicamente, il SDK utilizza il binario nativo di Claude Code, incluso sia nel pacchetto npm che in quello Python. Il codice Python o TypeScript comunica con questo binario, invia prompt e riceve un flusso di messaggi mentre l'agente lavora. Il risultato è che si scrive poche righe di codice e si ottiene un agente che pianifica in modo autonomo, chiama strumenti, valuta i risultati e decide cosa fare dopo.

Funzionalità aggiuntive rispetto all'accesso al modello

Prima di procedere con l'installazione, è utile avere un'anteprima di ciò che è effettivamente incluso nel SDK. La documentazione ufficiale elenca otto funzionalità principali che vanno oltre l'accesso chat della Claude API e che distinguono il SDK da una semplice libreria wrapper.

    • Strumenti integrati: Leggere, scrivere, modificare file, eseguire comandi, cercare sul web
    • Hook: Eseguire codice personalizzato in punti fissi del ciclo di vita dell'agente
    • Subagenti: Avviare agenti specializzati per compiti parziali focalizzati
    • MCP: Collegare strumenti e fonti di dati esterne tramite il Model Context Protocol
    • Autorizzazioni: Controllare quali strumenti vengono eseguiti automaticamente e quali richiedono conferma
    • Sessioni: Mantenere il contesto su più richieste, continuare o ramificare
    • Skills, Comandi, Memoria: Caricamento automatico dalla directory .claude, proprio come in Claude Code
    • Plugin: Skills, agenti, hook e server MCP raggruppati per caricamento tramite percorso locale

Claude Agent SDK vs. Claude Code CLI vs. Claude API: le differenze

Prima di iniziare con l'installazione, è utile dare un'occhiata alla distinzione con gli strumenti correlati di Anthropic, poiché è qui che si verificano le maggiori confusioni. La documentazione ufficiale distingue quattro modi per lavorare con Claude, a seconda di chi esegue effettivamente l'agente e di quanto è già preconfigurata l'infrastruttura.

    • Claude Agent SDK: Il vostro processo (Python/TypeScript). Integrare le capacità di Claude Code in una propria app.
    • Claude Code CLI: Terminal sul vostro computer. Sviluppo interattivo, compiti una tantum.
    • Client SDK / Claude API: Il vostro processo, loop di strumenti scritta da voi. Accesso diretto al modello senza strumenti preconfigurati.
    • Claude Managed Agents: Sandbox ospitata da Anthropic o sandbox propria. Eseguire agenti senza infrastruttura propria.

Prerequisiti: queste versioni sono necessarie

La soglia di ingresso è bassa, ma i seguenti punti dovrebbero essere chiari prima del primo passo. Altrimenti, l'installazione fallirà successivamente con messaggi di errore crittografati.

    • Node.js 18 o versione successiva, se si desidera lavorare con TypeScript (verificare con node -v)
    • Python 3.10 o versione successiva, se si desidera lavorare con Python (verificare con python3 --version)
    • Un account Anthropic con accesso API tramite platform.claude.com
    • Opzionale: uv, il gestore di pacchetti Python veloce di Astral, che gestisce automaticamente gli ambienti virtuali
    • Un terminale con diritti di scrittura nella directory del progetto, poiché l'agente crea e modifica file lì
    • Per ambienti aziendali, dati di accesso alternativi per Amazon Bedrock, Google Cloud Vertex AI o Microsoft Foundry invece di una semplice chiave API

Passaggio 1 e 2: creare la cartella del progetto e scegliere il linguaggio

Innanzitutto, create una nuova directory. Il SDK accede di default solo ai file in questa directory e nelle sue sottodirectory, il che è sufficiente per i primi test e limita i problemi di sicurezza in anticipo.

mkdir my-agent

cd my-agent

Se si desidera continuare con Python o TypeScript dipende solitamente dal resto del proprio stack. Entrambi i SDK offrono lo stesso set di funzionalità: gli stessi strumenti, gli stessi modi di autorizzazione, gli stessi eventi hook. In questa guida, mostriamo entrambe le varianti in parallelo, in modo da poterle confrontare direttamente.

Un team che gestisce già un backend Node.js integra solitamente l'agente direttamente come ulteriore componente.