Claude Code SDK
Costruisci agenti AI personalizzati con il Claude Code SDK
Perché utilizzare il Claude Code SDK?
Il Claude Code SDK fornisce tutti i blocchi di costruzione necessari per costruire agenti pronti per la produzione:
- Integrazione Claude ottimizzata: Cache automatica dei prompt e ottimizzazioni delle prestazioni
- Ecosistema di strumenti ricco: Operazioni sui file, esecuzione di codice, ricerca web e estensibilità MCP
- Permessi avanzati: Controllo granulare sulle capacità degli agenti
- Essenziali per la produzione: Gestione degli errori integrata, gestione delle sessioni e monitoraggio
Cosa puoi costruire con l’SDK?
Ecco alcuni tipi di agenti di esempio che puoi creare:
Agenti di codifica:
- Agenti SRE che diagnosticano e risolvono problemi di produzione
- Bot di revisione della sicurezza che controllano il codice per vulnerabilità
- Assistenti di ingegneria di guardia che gestiscono gli incidenti
- Agenti di revisione del codice che applicano stile e migliori pratiche
Agenti aziendali:
- Assistenti legali che rivedono contratti e conformità
- Consulenti finanziari che analizzano rapporti e previsioni
- Agenti di supporto clienti che risolvono problemi tecnici
- Assistenti per la creazione di contenuti per team di marketing
L’SDK è attualmente disponibile in TypeScript e Python, con un’interfaccia a riga di comando (CLI) per la prototipazione rapida.
Avvio rapido
Fai funzionare il tuo primo agente in meno di 5 minuti:
Installa l'SDK
Installa @anthropic-ai/claude-code
da NPM:
Installa @anthropic-ai/claude-code
da NPM:
Installa @anthropic-ai/claude-code
da NPM:
Installa claude-code-sdk
da PyPI e @anthropic-ai/claude-code
da NPM:
(Opzionale) Installa IPython per lo sviluppo interattivo:
Imposta la tua chiave API
Ottieni la tua chiave API dalla Console Anthropic e imposta la variabile d’ambiente ANTHROPIC_API_KEY
:
Crea il tuo primo agente
Crea uno di questi agenti di esempio:
Esegui l'agente
Copia e incolla il comando sopra direttamente nel tuo terminale.
Copia e incolla il comando sopra direttamente nel tuo terminale.
- Configura il progetto:
-
Aggiungi
"type": "module"
al tuo package.json -
Salva il codice sopra come
legal-agent.ts
, poi esegui:
Salva il codice sopra come legal-agent.py
, poi esegui:
Per notebook IPython/Jupyter, puoi eseguire il codice direttamente in una cella:
Ogni esempio sopra crea un agente funzionante che:
- Analizza il prompt utilizzando le capacità di ragionamento di Claude
- Pianifica un approccio multi-step per risolvere il problema
- Esegue azioni utilizzando strumenti come operazioni sui file, comandi bash e ricerca web
- Fornisce raccomandazioni attuabili basate sull’analisi
Utilizzo principale
Panoramica
Il Claude Code SDK ti permette di interfacciarti con Claude Code in modalità non interattiva dalle tue applicazioni.
Prerequisiti
- Node.js 18+
@anthropic-ai/claude-code
da NPM
Utilizzo di base
L’interfaccia principale a riga di comando per Claude Code è il comando claude
. Usa il flag --print
(o -p
) per eseguire in modalità non interattiva e stampare il risultato finale:
Configurazione
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 il logging verboso | claude --verbose |
--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 delle funzionalità, vedi la documentazione di riferimento CLI.
Prerequisiti
- Node.js 18+
@anthropic-ai/claude-code
da NPM
Utilizzo di base
L’interfaccia principale a riga di comando per Claude Code è il comando claude
. Usa il flag --print
(o -p
) per eseguire in modalità non interattiva e stampare il risultato finale:
Configurazione
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 il logging verboso | claude --verbose |
--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 delle funzionalità, vedi la documentazione di riferimento CLI.
Prerequisiti
- Node.js 18+
@anthropic-ai/claude-code
da NPM
Per visualizzare il codice sorgente dell’SDK TypeScript, visita la pagina @anthropic-ai/claude-code
su NPM.
Utilizzo di base
L’interfaccia principale tramite l’SDK TypeScript è la funzione query
, che restituisce un iteratore asincrono che trasmette messaggi mentre arrivano:
Configurazione
L’SDK TypeScript accetta tutti gli argomenti supportati dalla riga di comando, così come le seguenti opzioni aggiuntive:
Argomento | Descrizione | Predefinito |
---|---|---|
abortController | Controller di interruzione | new AbortController() |
cwd | Directory di lavoro corrente | process.cwd() |
executable | Quale runtime JavaScript utilizzare | node quando eseguito con Node.js, bun quando eseguito con Bun |
executableArgs | Argomenti da passare all’eseguibile | [] |
pathToClaudeCodeExecutable | Percorso all’eseguibile Claude Code | Eseguibile fornito con @anthropic-ai/claude-code |
permissionMode | Modalità di permesso per la sessione | "default" (opzioni: "default" , "acceptEdits" , "plan" , "bypassPermissions" ) |
Prerequisiti
- Python 3.10+
claude-code-sdk
da PyPI- Node.js 18+
@anthropic-ai/claude-code
da NPM
Per visualizzare il codice sorgente dell’SDK Python, vedi il repository claude-code-sdk
.
Per lo sviluppo interattivo, usa IPython: pip install ipython
Utilizzo di base
L’SDK Python fornisce due interfacce principali:
- La classe
ClaudeSDKClient
(Raccomandato)
Migliore per risposte in streaming, conversazioni multi-turno e applicazioni interattive:
L’SDK supporta anche il passaggio di messaggi strutturati e input di immagini:
Gli esempi Python in questa pagina usano asyncio
, ma puoi anche usare anyio
.
- La funzione
query
Per query semplici e singole:
Configurazione
L’SDK Python accetta tutti gli argomenti supportati dalla riga di comando attraverso la classe ClaudeCodeOptions
.
Autenticazione
Chiave API Anthropic
Per l’autenticazione di base, recupera una chiave API Anthropic dalla Console Anthropic e imposta la variabile d’ambiente ANTHROPIC_API_KEY
, come dimostrato nell’Avvio rapido.
Credenziali API di terze parti
L’SDK supporta anche l’autenticazione tramite fornitori 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 di configurazione dettagliate per fornitori di terze parti, vedi la documentazione di Amazon Bedrock e Google Vertex AI.
Conversazioni multi-turno
Per conversazioni multi-turno, puoi riprendere conversazioni o continuare dalla sessione più recente:
Utilizzo della Modalità Piano
La Modalità Piano permette a Claude di analizzare il codice senza apportare modifiche, utile per revisioni del codice e pianificazione delle modifiche.
La Modalità Piano limita la modifica, la creazione di file e l’esecuzione di comandi. Vedi modalità di permesso per dettagli.
Prompt di sistema personalizzati
I prompt di sistema definiscono il ruolo, l’expertise e il comportamento del tuo agente. Qui è dove specifichi che tipo di agente stai costruendo:
Utilizzo Avanzato
Strumenti personalizzati tramite MCP
Il Model Context Protocol (MCP) ti permette di dare ai tuoi agenti strumenti e capacità personalizzati. Questo è cruciale per costruire agenti specializzati che necessitano di integrazioni specifiche del dominio.
Configurazioni di strumenti agente di esempio:
Esempi di utilizzo:
Quando usi strumenti MCP, devi esplicitamente consentirli usando il flag --allowedTools
. I nomi degli strumenti MCP seguono il pattern mcp__<serverName>__<toolName>
dove:
serverName
è la chiave dal tuo file di configurazione MCPtoolName
è lo strumento specifico fornito da quel server
Questa misura di sicurezza assicura che gli strumenti MCP siano usati solo quando esplicitamente permessi.
Se specifichi solo il nome del server (cioè, mcp__<serverName>
), tutti gli strumenti da quel server saranno consentiti.
I pattern glob (ad es., mcp__go*
) non sono supportati.
Strumento di prompt di permesso personalizzato
Opzionalmente, usa --permission-prompt-tool
per passare uno strumento MCP che useremo per verificare se l’utente concede al modello i permessi per invocare un dato strumento. Quando il modello invoca uno strumento succede 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:
Esempi di implementazione:
Note di utilizzo:
- 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 di prompt di permesso dovrebbe restituire quella modifica aggiornata. - Il payload deve essere JSON-stringificato
Formati di output
L’SDK supporta formati di output multipli:
Output di testo (predefinito)
Output JSON
Restituisce dati strutturati inclusi i metadati:
Formato di risposta:
Output JSON in streaming
Trasmette ogni messaggio mentre viene ricevuto:
Ogni conversazione inizia con un messaggio di sistema init
iniziale, seguito da una lista di messaggi utente e assistente, seguito da un messaggio di sistema result
finale con statistiche. Ogni messaggio è emesso come oggetto JSON separato.
Schema dei messaggi
I messaggi restituiti dall’API JSON sono tipizzati rigorosamente secondo il seguente schema:
Pubblicheremo presto questi tipi in un formato compatibile con JSONSchema. Usiamo 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, vedi gli SDK Anthropic TypeScript e Python.
Formati di input
L’SDK supporta formati di input multipli:
Input di testo (predefinito)
Input JSON in streaming
Un flusso di messaggi fornito tramite stdin
dove ogni messaggio rappresenta un turno utente. Questo permette turni multipli di una conversazione senza rilanciare il binario claude
e permette 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 usando 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 di integrazione agenti
Bot di risposta agli incidenti SRE
Revisione di sicurezza automatizzata
Assistente legale multi-turno
Migliori Pratiche Specifiche per Python
Pattern Chiave
Suggerimenti IPython/Jupyter
Migliori pratiche
-
Usa il formato di output JSON per l’analisi programmatica delle risposte:
-
Gestisci gli errori con grazia - controlla codici di uscita e stderr:
-
Usa la gestione delle sessioni per mantenere il contesto in conversazioni multi-turno
-
Considera i timeout per operazioni a lunga durata:
-
Rispetta i limiti di velocità quando fai richieste multiple aggiungendo ritardi tra le chiamate
Risorse correlate
- Utilizzo e controlli CLI - Documentazione CLI completa
- Integrazione GitHub Actions - Automatizza il tuo workflow GitHub con Claude
- Flussi di lavoro comuni - Guide passo-passo per casi d’uso comuni