Claude Code SDK
Scopri come integrare programmaticamente Claude Code nelle tue applicazioni con il Claude Code SDK.
Il Claude Code SDK consente di eseguire Claude Code come sottoprocesso, fornendo un modo per costruire assistenti di codifica e strumenti alimentati da AI che sfruttano le capacità di Claude.
L’SDK è disponibile per l’uso da riga di comando, TypeScript e Python.
Autenticazione
Il Claude Code SDK supporta diversi metodi di autenticazione:
Chiave API Anthropic
Per utilizzare il Claude Code SDK direttamente con l’API di Anthropic, raccomandiamo di creare una chiave API dedicata:
- Crea una chiave API Anthropic nella Console Anthropic
- Quindi, imposta la variabile d’ambiente
ANTHROPIC_API_KEY
. Raccomandiamo di memorizzare questa chiave in modo sicuro (ad esempio, utilizzando un segreto di Github)
Credenziali API di terze parti
L’SDK supporta anche fornitori di API di terze parti:
- Amazon Bedrock: Imposta la variabile d’ambiente
CLAUDE_CODE_USE_BEDROCK=1
e configura le credenziali AWS - Google Vertex AI: Imposta la variabile d’ambiente
CLAUDE_CODE_USE_VERTEX=1
e configura le credenziali Google Cloud
Per istruzioni dettagliate di configurazione per fornitori di terze parti, consulta la documentazione di Amazon Bedrock e Google Vertex AI.
Utilizzo base dell’SDK
Il Claude Code SDK ti consente di utilizzare Claude Code in modalità non interattiva dalle tue applicazioni.
Riga di comando
Ecco alcuni esempi di base per l’SDK da riga di comando:
TypeScript
L’SDK TypeScript è incluso nel pacchetto principale @anthropic-ai/claude-code
su NPM:
L’SDK TypeScript accetta tutti gli argomenti supportati dall’SDK da riga di comando, così come:
Argomento | Descrizione | Predefinito |
---|---|---|
abortController | Controller di interruzione | new AbortController() |
cwd | Directory di lavoro corrente | process.cwd() |
executable | Quale runtime JavaScript utilizzare | node quando si esegue con Node.js, bun quando si esegue con Bun |
executableArgs | Argomenti da passare all’eseguibile | [] |
pathToClaudeCodeExecutable | Percorso all’eseguibile Claude Code | Eseguibile fornito con @anthropic-ai/claude-code |
Python
L’SDK Python è disponibile come claude-code-sdk
su PyPI:
Prerequisiti:
- Python 3.10+
- Node.js
- Claude Code CLI:
npm install -g @anthropic-ai/claude-code
Utilizzo base:
L’SDK Python accetta tutti gli argomenti supportati dall’SDK da riga di comando attraverso la classe ClaudeCodeOptions
:
Utilizzo avanzato
La documentazione seguente utilizza l’SDK da riga di comando come esempio, ma può essere utilizzata anche con gli SDK TypeScript e Python.
Conversazioni multi-turno
Per conversazioni multi-turno, puoi riprendere conversazioni o continuare dalla sessione più recente:
Prompt di sistema personalizzati
Puoi fornire prompt di sistema personalizzati per guidare il comportamento di Claude:
Puoi anche aggiungere istruzioni al prompt di sistema predefinito:
Configurazione MCP
Il Model Context Protocol (MCP) ti consente di estendere Claude Code con strumenti e risorse aggiuntivi da server esterni. Utilizzando il flag --mcp-config
, puoi caricare server MCP che forniscono capacità specializzate come accesso al database, integrazioni API o strumenti personalizzati.
Crea un file di configurazione JSON con i tuoi server MCP:
Quindi utilizzalo con Claude Code:
Quando utilizzi strumenti MCP, devi esplicitamente consentirli usando il flag --allowedTools
. I nomi degli strumenti MCP seguono il pattern mcp__<nomeServer>__<nomeStrumento>
dove:
nomeServer
è la chiave dal tuo file di configurazione MCPnomeStrumento
è lo strumento specifico fornito da quel server
Questa misura di sicurezza assicura che gli strumenti MCP vengano utilizzati solo quando esplicitamente permessi.
Se specifichi solo il nome del server (cioè, mcp__<nomeServer>
), tutti gli strumenti da quel server saranno consentiti.
I pattern glob (ad esempio, mcp__go*
) non sono supportati.
Strumento personalizzato per prompt di permesso
Opzionalmente, usa --permission-prompt-tool
per passare uno strumento MCP che utilizzeremo per verificare se l’utente concede o meno al modello i permessi per invocare un dato strumento. Quando il modello invoca uno strumento accade quanto segue:
- Prima controlliamo le impostazioni di permesso: tutti i file settings.json, così come
--allowedTools
e--disallowedTools
passati nell’SDK; se una di queste consente o nega la chiamata dello strumento, procediamo con la chiamata dello strumento - Altrimenti, invochiamo lo strumento MCP che hai fornito in
--permission-prompt-tool
Lo strumento MCP --permission-prompt-tool
riceve il nome dello strumento e l’input, e deve restituire un payload JSON-stringificato con il risultato. Il payload deve essere uno di:
Ad esempio, un’implementazione TypeScript di uno strumento MCP per prompt di permesso potrebbe apparire così:
Per utilizzare questo strumento, aggiungi il tuo server MCP (ad esempio con --mcp-config
), quindi invoca l’SDK così:
Note d’uso:
- Usa
updatedInput
per dire al modello che il prompt di permesso ha mutato il suo input; altrimenti, impostaupdatedInput
all’input originale, come nell’esempio sopra. Ad esempio, se lo strumento mostra un diff di modifica file all’utente e gli permette di modificare il diff manualmente, lo strumento prompt di permesso dovrebbe restituire quella modifica aggiornata. - Il payload deve essere JSON-stringificato
Opzioni CLI disponibili
L’SDK sfrutta tutte le opzioni CLI disponibili in Claude Code. Ecco quelle principali per l’utilizzo dell’SDK:
Flag | Descrizione | Esempio |
---|---|---|
--print , -p | Esegui in modalità non interattiva | claude -p "query" |
--output-format | Specifica il formato di output (text , json , stream-json ) | claude -p --output-format json |
--resume , -r | Riprendi una conversazione per ID sessione | claude --resume abc123 |
--continue , -c | Continua la conversazione più recente | claude --continue |
--verbose | Abilita logging verboso | claude --verbose |
--max-turns | Limita i turni agentici in modalità non interattiva | claude --max-turns 3 |
--system-prompt | Sovrascrivi il prompt di sistema (solo con --print ) | claude --system-prompt "Istruzione personalizzata" |
--append-system-prompt | Aggiungi al prompt di sistema (solo con --print ) | claude --append-system-prompt "Istruzione personalizzata" |
--allowedTools | Lista separata da spazi di strumenti consentiti, o stringa di lista separata da virgole di strumenti consentiti | claude --allowedTools mcp__slack mcp__filesystem claude --allowedTools "Bash(npm install),mcp__filesystem" |
--disallowedTools | Lista separata da spazi di strumenti negati, o stringa di lista separata da virgole di strumenti negati | claude --disallowedTools mcp__splunk mcp__github claude --disallowedTools "Bash(git commit),mcp__github" |
--mcp-config | Carica server MCP da un file JSON | claude --mcp-config servers.json |
--permission-prompt-tool | Strumento MCP per gestire i prompt di permesso (solo con --print ) | claude --permission-prompt-tool mcp__auth__prompt |
Per un elenco completo delle opzioni CLI e funzionalità, consulta la documentazione di riferimento CLI.
Formati di output
L’SDK supporta diversi formati di output:
Output di testo (predefinito)
Restituisce solo il testo della risposta:
Output JSON
Restituisce dati strutturati inclusi i metadati:
Formato della risposta:
Output JSON in streaming
Trasmette ogni messaggio mentre viene ricevuto:
Ogni conversazione inizia con un messaggio di sistema init
iniziale, seguito da un elenco di messaggi utente e assistente, seguito da un messaggio di sistema result
finale con le statistiche. Ogni messaggio viene emesso come oggetto JSON separato.
Schema dei messaggi
I messaggi restituiti dall’API JSON sono rigorosamente tipizzati secondo il seguente schema:
Pubblicheremo presto questi tipi in un formato compatibile con JSONSchema. Utilizziamo il versioning semantico per il pacchetto principale Claude Code per comunicare modifiche che rompono la compatibilità a questo formato.
I tipi Message
e MessageParam
sono disponibili negli SDK Anthropic. Ad esempio, consulta gli SDK Anthropic TypeScript e Python.
Formati di input
L’SDK supporta diversi formati di input:
Input di testo (predefinito)
Il testo di input può essere fornito come argomento:
Oppure il testo di input può essere inviato tramite stdin:
Input JSON in streaming
Un flusso di messaggi fornito tramite stdin
dove ogni messaggio rappresenta un turno utente. Questo consente più turni di una conversazione senza rilanciare il binario claude
e consente di fornire guida al modello mentre sta elaborando una richiesta.
Ogni messaggio è un oggetto JSON ‘Messaggio utente’, seguendo lo stesso formato dello schema dei messaggi di output. I messaggi sono formattati utilizzando il formato jsonl dove ogni riga di input è un oggetto JSON completo. L’input JSON in streaming richiede -p
e --output-format stream-json
.
Attualmente questo è limitato a messaggi utente solo di testo.
Esempi
Integrazione di script semplice
Elaborazione di file con Claude
Gestione delle sessioni
Migliori pratiche
-
Usa il formato di output JSON per l’analisi programmatica delle risposte:
-
Gestisci gli errori con grazia - controlla i codici di uscita e stderr:
-
Usa la gestione delle sessioni per mantenere il contesto in conversazioni multi-turno
-
Considera i timeout per operazioni di lunga durata:
-
Rispetta i limiti di velocità quando fai più richieste aggiungendo ritardi tra le chiamate
Applicazioni del mondo reale
Il Claude Code SDK abilita potenti integrazioni con il tuo flusso di lavoro di sviluppo. Un esempio notevole sono le Claude Code GitHub Actions, che utilizzano l’SDK per fornire capacità di revisione automatica del codice, creazione di PR e triage dei problemi direttamente nel tuo flusso di lavoro GitHub.
Risorse correlate
- Utilizzo e controlli CLI - Documentazione CLI completa
- Integrazione GitHub Actions - Automatizza il tuo flusso di lavoro GitHub con Claude
- Flussi di lavoro comuni - Guide passo-passo per casi d’uso comuni