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:

1

Installa l'SDK

Installa @anthropic-ai/claude-code da NPM:

npm install -g @anthropic-ai/claude-code
2

Imposta la tua chiave API

Ottieni la tua chiave API dalla Console Anthropic e imposta la variabile d’ambiente ANTHROPIC_API_KEY:

export ANTHROPIC_API_KEY="la-tua-chiave-api-qui"
3

Crea il tuo primo agente

Crea uno di questi agenti di esempio:

# Crea un semplice assistente legale
claude -p "Rivedi questa clausola contrattuale per potenziali problemi: 'La parte accetta responsabilità illimitata...'" \
  --append-system-prompt "Sei un assistente legale. Identifica i rischi e suggerisci miglioramenti."
4

Esegui l'agente

Copia e incolla il comando sopra direttamente nel tuo terminale.

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:

claude -p "Analizza le prestazioni del sistema" \
  --append-system-prompt "Sei un ingegnere delle prestazioni" \
  --allowedTools "Bash,Read,WebSearch" \
  --permission-mode acceptEdits \
  --cwd /percorso/al/progetto

Configurazione

L’SDK sfrutta tutte le opzioni CLI disponibili in Claude Code. Ecco quelle principali per l’utilizzo dell’SDK:

FlagDescrizioneEsempio
--print, -pEsegui in modalità non interattivaclaude -p "query"
--output-formatSpecifica il formato di output (text, json, stream-json)claude -p --output-format json
--resume, -rRiprendi una conversazione per ID sessioneclaude --resume abc123
--continue, -cContinua la conversazione più recenteclaude --continue
--verboseAbilita il logging verbosoclaude --verbose
--append-system-promptAggiungi al prompt di sistema (solo con --print)claude --append-system-prompt "Istruzione personalizzata"
--allowedToolsLista 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"
--disallowedToolsLista 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-configCarica server MCP da un file JSONclaude --mcp-config servers.json
--permission-prompt-toolStrumento 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.

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:

# Continua la conversazione più recente
claude --continue "Ora rifattorizza questo per migliori prestazioni"

# Riprendi una conversazione specifica per ID sessione
claude --resume 550e8400-e29b-41d4-a716-446655440000 "Aggiorna i test"

# Riprendi in modalità non interattiva
claude --resume 550e8400-e29b-41d4-a716-446655440000 "Correggi tutti i problemi di linting" --no-interactive

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.

claude -p "Rivedi questo codice" --permission-mode plan

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:

# Agente di risposta agli incidenti SRE
claude -p "API è giù, investiga" \
  --append-system-prompt "Sei un esperto SRE. Diagnostica i problemi sistematicamente e fornisci soluzioni attuabili."

# Agente di revisione documenti legali  
claude -p "Rivedi questo contratto" \
  --append-system-prompt "Sei un avvocato aziendale. Identifica i rischi, suggerisci miglioramenti e assicura la conformità."

# Aggiungi al prompt di sistema predefinito
claude -p "Rifattorizza questa funzione" \
  --append-system-prompt "Includi sempre gestione completa degli errori e test unitari."

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:

{
  "mcpServers": {
    "slack": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-slack"],
      "env": {"SLACK_TOKEN": "il-tuo-token-slack"}
    },
    "jira": {
      "command": "npx", 
      "args": ["-y", "@modelcontextprotocol/server-jira"],
      "env": {"JIRA_TOKEN": "il-tuo-token-jira"}
    },
    "database": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {"DB_CONNECTION_STRING": "il-tuo-url-db"}
    }
  }
}

Esempi di utilizzo:

# Agente SRE con strumenti di monitoraggio
claude -p "Investiga l'interruzione del servizio di pagamento" \
  --mcp-config sre-tools.json \
  --allowedTools "mcp__datadog,mcp__pagerduty,mcp__kubernetes" \
  --append-system-prompt "Sei un SRE. Usa i dati di monitoraggio per diagnosticare i problemi."

# Agente di supporto clienti con accesso CRM
claude -p "Aiuta a risolvere il ticket cliente #12345" \
  --mcp-config support-tools.json \
  --allowedTools "mcp__zendesk,mcp__stripe,mcp__user_db" \
  --append-system-prompt "Sei uno specialista del supporto tecnico."

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 MCP
  • toolName è 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:

  1. 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
  2. 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:

// la chiamata dello strumento è consentita
{
  "behavior": "allow",
  "updatedInput": {...}, // input aggiornato, o semplicemente restituisci l'input originale
}

// la chiamata dello strumento è negata
{
  "behavior": "deny",
  "message": "..." // stringa leggibile dall'uomo che spiega perché il permesso è stato negato
}

Esempi di implementazione:

# Usa con la configurazione del tuo server MCP
claude -p "Analizza e correggi i problemi di sicurezza" \
  --permission-prompt-tool mcp__security__approval_prompt \
  --mcp-config security-tools.json \
  --allowedTools "Read,Grep" \
  --disallowedTools "Bash(rm*),Write"

# Con regole di permesso personalizzate
claude -p "Rifattorizza la codebase" \
  --permission-prompt-tool mcp__custom__permission_check \
  --mcp-config custom-config.json \
  --output-format json

Note di utilizzo:

  • Usa updatedInput per dire al modello che il prompt di permesso ha mutato il suo input; altrimenti, imposta updatedInput 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)

claude -p "Spiega il file src/components/Header.tsx"
# Output: Questo è un componente React che mostra...

Output JSON

Restituisce dati strutturati inclusi i metadati:

claude -p "Come funziona il livello dati?" --output-format json

Formato di risposta:

{
  "type": "result",
  "subtype": "success",
  "total_cost_usd": 0.003,
  "is_error": false,
  "duration_ms": 1234,
  "duration_api_ms": 800,
  "num_turns": 6,
  "result": "Il testo della risposta qui...",
  "session_id": "abc123"
}

Output JSON in streaming

Trasmette ogni messaggio mentre viene ricevuto:

$ claude -p "Costruisci un'applicazione" --output-format stream-json

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:

type SDKMessage =
  // Un messaggio dell'assistente
  | {
      type: "assistant";
      message: Message; // dall'SDK Anthropic
      session_id: string;
    }

  // Un messaggio utente
  | {
      type: "user";
      message: MessageParam; // dall'SDK Anthropic
      session_id: string;
    }

  // Emesso come ultimo messaggio
  | {
      type: "result";
      subtype: "success";
      duration_ms: float;
      duration_api_ms: float;
      is_error: boolean;
      num_turns: int;
      result: string;
      session_id: string;
      total_cost_usd: float;
    }

  // Emesso come ultimo messaggio, quando abbiamo raggiunto il numero massimo di turni
  | {
      type: "result";
      subtype: "error_max_turns" | "error_during_execution";
      duration_ms: float;
      duration_api_ms: float;
      is_error: boolean;
      num_turns: int;
      session_id: string;
      total_cost_usd: float;
    }

  // Emesso come primo messaggio all'inizio di una conversazione
  | {
      type: "system";
      subtype: "init";
      apiKeySource: string;
      cwd: string;
      session_id: string;
      tools: string[];
      mcp_servers: {
        name: string;
        status: string;
      }[];
      model: string;
      permissionMode: "default" | "acceptEdits" | "bypassPermissions" | "plan";
    };

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)

# Argomento diretto
claude -p "Spiega questo codice"

# Da stdin
echo "Spiega questo codice" | claude -p

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.

$ echo '{"type":"user","message":{"role":"user","content":[{"type":"text","text":"Spiega questo codice"}]}}' | claude -p --output-format=stream-json --input-format=stream-json --verbose

Esempi di integrazione agenti

Bot di risposta agli incidenti SRE

#!/bin/bash

# Agente di risposta agli incidenti automatizzato
investigate_incident() {
    local incident_description="$1"
    local severity="${2:-medium}"
    
    claude -p "Incidente: $incident_description (Gravità: $severity)" \
      --append-system-prompt "Sei un esperto SRE. Diagnostica il problema, valuta l'impatto e fornisci elementi d'azione immediati." \
      --output-format json \
      --allowedTools "Bash,Read,WebSearch,mcp__datadog" \
      --mcp-config monitoring-tools.json
}

# Utilizzo
investigate_incident "API di pagamento restituisce errori 500" "high"

Revisione di sicurezza automatizzata

# Agente di audit di sicurezza per pull request
audit_pr() {
    local pr_number="$1"
    
    gh pr diff "$pr_number" | claude -p \
      --append-system-prompt "Sei un ingegnere della sicurezza. Rivedi questa PR per vulnerabilità, pattern insicuri e problemi di conformità." \
      --output-format json \
      --allowedTools "Read,Grep,WebSearch"
}

# Utilizzo e salva su file
audit_pr 123 > security-report.json

Assistente legale multi-turno

# Revisione documenti legali con persistenza della sessione
session_id=$(claude -p "Inizia sessione di revisione legale" --output-format json | jq -r '.session_id')

# Rivedi contratto in passaggi multipli
claude -p --resume "$session_id" "Rivedi contract.pdf per clausole di responsabilità"
claude -p --resume "$session_id" "Controlla conformità con requisiti GDPR" 
claude -p --resume "$session_id" "Genera riassunto esecutivo dei rischi"

Migliori Pratiche Specifiche per Python

Pattern Chiave

import asyncio
from claude_code_sdk import ClaudeSDKClient, ClaudeCodeOptions

# Usa sempre context manager
async with ClaudeSDKClient() as client:
    await client.query("Analizza questo codice")
    async for msg in client.receive_response():
        # Elabora messaggi in streaming
        pass

# Esegui agenti multipli concorrentemente
async with ClaudeSDKClient() as reviewer, ClaudeSDKClient() as tester:
    await asyncio.gather(
        reviewer.query("Rivedi main.py"),
        tester.query("Scrivi test per main.py")
    )

# Gestione errori
from claude_code_sdk import CLINotFoundError, ProcessError

try:
    async with ClaudeSDKClient() as client:
        # Il tuo codice qui
        pass
except CLINotFoundError:
    print("Installa CLI: npm install -g @anthropic-ai/claude-code")
except ProcessError as e:
    print(f"Errore processo: {e}")

# Raccogli risposta completa con metadati
async def get_response(client, prompt):
    await client.query(prompt)
    text = []
    async for msg in client.receive_response():
        if hasattr(msg, 'content'):
            for block in msg.content:
                if hasattr(block, 'text'):
                    text.append(block.text)
        if type(msg).__name__ == "ResultMessage":
            return {'text': ''.join(text), 'cost': msg.total_cost_usd}

Suggerimenti IPython/Jupyter

# In Jupyter, usa await direttamente nelle celle
client = ClaudeSDKClient()
await client.connect()
await client.query("Analizza data.csv")
async for msg in client.receive_response():
    print(msg)
await client.disconnect()

# Crea funzioni helper riutilizzabili
async def stream_print(client, prompt):
    await client.query(prompt)
    async for msg in client.receive_response():
        if hasattr(msg, 'content'):
            for block in msg.content:
                if hasattr(block, 'text'):
                    print(block.text, end='', flush=True)

Migliori pratiche

  • Usa il formato di output JSON per l’analisi programmatica delle risposte:

    # Analizza risposta JSON con jq
    result=$(claude -p "Genera codice" --output-format json)
    code=$(echo "$result" | jq -r '.result')
    cost=$(echo "$result" | jq -r '.cost_usd')
    
  • Gestisci gli errori con grazia - controlla codici di uscita e stderr:

    if ! claude -p "$prompt" 2>error.log; then
        echo "Si è verificato un errore:" >&2
        cat error.log >&2
        exit 1
    fi
    
  • Usa la gestione delle sessioni per mantenere il contesto in conversazioni multi-turno

  • Considera i timeout per operazioni a lunga durata:

    timeout 300 claude -p "$complex_prompt" || echo "Timeout dopo 5 minuti"
    
  • Rispetta i limiti di velocità quando fai richieste multiple aggiungendo ritardi tra le chiamate

Risorse correlate