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:

  1. Crea una chiave API Anthropic nella Console Anthropic
  2. 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:

# Esegui un singolo prompt ed esci (modalità stampa)
$ claude -p "Scrivi una funzione per calcolare i numeri di Fibonacci"

# Utilizzando una pipe per fornire stdin
$ echo "Spiega questo codice" | claude -p

# Output in formato JSON con metadati
$ claude -p "Genera una funzione hello world" --output-format json

# Streaming dell'output JSON mentre arriva
$ claude -p "Costruisci un componente React" --output-format stream-json

TypeScript

L’SDK TypeScript è incluso nel pacchetto principale @anthropic-ai/claude-code su NPM:

import { query, type SDKMessage } from "@anthropic-ai/claude-code";

const messages: SDKMessage[] = [];

for await (const message of query({
  prompt: "Scrivi un haiku su foo.py",
  abortController: new AbortController(),
  options: {
    maxTurns: 3,
  },
})) {
  messages.push(message);
}

console.log(messages);

L’SDK TypeScript accetta tutti gli argomenti supportati dall’SDK da riga di comando, così come:

ArgomentoDescrizionePredefinito
abortControllerController di interruzionenew AbortController()
cwdDirectory di lavoro correnteprocess.cwd()
executableQuale runtime JavaScript utilizzarenode quando si esegue con Node.js, bun quando si esegue con Bun
executableArgsArgomenti da passare all’eseguibile[]
pathToClaudeCodeExecutablePercorso all’eseguibile Claude CodeEseguibile fornito con @anthropic-ai/claude-code

Python

L’SDK Python è disponibile come claude-code-sdk su PyPI:

pip install claude-code-sdk

Prerequisiti:

  • Python 3.10+
  • Node.js
  • Claude Code CLI: npm install -g @anthropic-ai/claude-code

Utilizzo base:

import anyio
from claude_code_sdk import query, ClaudeCodeOptions, Message

async def main():
    messages: list[Message] = []
    
    async for message in query(
        prompt="Scrivi un haiku su foo.py",
        options=ClaudeCodeOptions(max_turns=3)
    ):
        messages.append(message)
    
    print(messages)

anyio.run(main)

L’SDK Python accetta tutti gli argomenti supportati dall’SDK da riga di comando attraverso la classe ClaudeCodeOptions:

from claude_code_sdk import query, ClaudeCodeOptions
from pathlib import Path

options = ClaudeCodeOptions(
    max_turns=3,
    system_prompt="Sei un assistente utile",
    cwd=Path("/percorso/al/progetto"),  # Può essere stringa o Path
    allowed_tools=["Read", "Write", "Bash"],
    permission_mode="acceptEdits"
)

async for message in query(prompt="Ciao", options=options):
    print(message)

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:

# Continua la conversazione più recente
$ claude --continue

# Continua e fornisci un nuovo prompt
$ claude --continue "Ora refactorizza questo per migliori prestazioni"

# Riprendi una conversazione specifica per ID sessione
$ claude --resume 550e8400-e29b-41d4-a716-446655440000

# Riprendi in modalità stampa (non interattiva)
$ claude -p --resume 550e8400-e29b-41d4-a716-446655440000 "Aggiorna i test"

# Continua in modalità stampa (non interattiva)
$ claude -p --continue "Aggiungi gestione degli errori"

Prompt di sistema personalizzati

Puoi fornire prompt di sistema personalizzati per guidare il comportamento di Claude:

# Sovrascrivi il prompt di sistema (funziona solo con --print)
$ claude -p "Costruisci una REST API" --system-prompt "Sei un ingegnere backend senior. Concentrati su sicurezza, prestazioni e manutenibilità."

# Prompt di sistema con requisiti specifici
$ claude -p "Crea uno schema di database" --system-prompt "Sei un architetto di database. Usa le migliori pratiche PostgreSQL e includi indicizzazione appropriata."

Puoi anche aggiungere istruzioni al prompt di sistema predefinito:

# Aggiungi al prompt di sistema (funziona solo con --print)
$ claude -p "Costruisci una REST API" --append-system-prompt "Dopo aver scritto il codice, assicurati di fare una revisione del codice da solo."

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:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/percorso/ai/file/consentiti"
      ]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "il-tuo-token-github"
      }
    }
  }
}

Quindi utilizzalo con Claude Code:

# Carica server MCP dalla configurazione
$ claude -p "Elenca tutti i file nel progetto" --mcp-config mcp-servers.json

# Importante: gli strumenti MCP devono essere esplicitamente consentiti usando --allowedTools
# Gli strumenti MCP seguono il formato: mcp__$nomeServer__$nomeStrumento
$ claude -p "Cerca commenti TODO" \
  --mcp-config mcp-servers.json \
  --allowedTools "mcp__filesystem__read_file,mcp__filesystem__list_directory"

# Usa uno strumento MCP per gestire i prompt di permesso in modalità non interattiva
$ claude -p "Distribuisci l'applicazione" \
  --mcp-config mcp-servers.json \
  --allowedTools "mcp__permissions__approve" \
  --permission-prompt-tool mcp__permissions__approve

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

  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
}

Ad esempio, un’implementazione TypeScript di uno strumento MCP per prompt di permesso potrebbe apparire così:

const server = new McpServer({
  name: "Test permission prompt MCP Server",
  version: "0.0.1",
});

server.tool(
  "approval_prompt",
  'Simula un controllo di permesso - approva se l\'input contiene "allow", altrimenti nega',
  {
    tool_name: z.string().describe("Lo strumento che richiede il permesso"),
    input: z.object({}).passthrough().describe("L'input per lo strumento"),
  },
  async ({ tool_name, input }) => {
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(
            JSON.stringify(input).includes("allow")
              ? {
                  behavior: "allow",
                  updatedInput: input,
                }
              : {
                  behavior: "deny",
                  message: "Permesso negato dallo strumento test approval_prompt",
                }
          ),
        },
      ],
    };
  }
);

Per utilizzare questo strumento, aggiungi il tuo server MCP (ad esempio con --mcp-config), quindi invoca l’SDK così:

claude -p "..." \
  --permission-prompt-tool mcp__test-server__approval_prompt \
  --mcp-config my-config.json

Note d’uso:

  • 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 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:

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 logging verbosoclaude --verbose
--max-turnsLimita i turni agentici in modalità non interattivaclaude --max-turns 3
--system-promptSovrascrivi il prompt di sistema (solo con --print)claude --system-prompt "Istruzione personalizzata"
--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 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:

$ 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 della 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 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:

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

$ claude -p "Spiega questo codice"

Oppure il testo di input può essere inviato tramite 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 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.

$ 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

Integrazione di script semplice

#!/bin/bash

# Funzione semplice per eseguire Claude e controllare il codice di uscita
run_claude() {
    local prompt="$1"
    local output_format="${2:-text}"

    if claude -p "$prompt" --output-format "$output_format"; then
        echo "Successo!"
    else
        echo "Errore: Claude ha fallito con codice di uscita $?" >&2
        return 1
    fi
}

# Esempi di utilizzo
run_claude "Scrivi una funzione Python per leggere file CSV"
run_claude "Ottimizza questa query di database" "json"

Elaborazione di file con Claude

# Elabora un file attraverso Claude
$ cat mycode.py | claude -p "Rivedi questo codice per bug"

# Elabora più file
$ for file in *.js; do
    echo "Elaborando $file..."
    claude -p "Aggiungi commenti JSDoc a questo file:" < "$file" > "${file}.documented"
done

# Usa Claude in una pipeline
$ grep -l "TODO" *.py | while read file; do
    claude -p "Correggi tutti gli elementi TODO in questo file" < "$file"
done

Gestione delle sessioni

# Avvia una sessione e cattura l'ID sessione
$ claude -p "Inizializza un nuovo progetto" --output-format json | jq -r '.session_id' > session.txt

# Continua con la stessa sessione
$ claude -p --resume "$(cat session.txt)" "Aggiungi test unitari"

Migliori pratiche

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

    # Analizza la 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')
    
  2. Gestisci gli errori con grazia - controlla i 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
    
  3. Usa la gestione delle sessioni per mantenere il contesto in conversazioni multi-turno

  4. Considera i timeout per operazioni di lunga durata:

    timeout 300 claude -p "$complex_prompt" || echo "Timeout dopo 5 minuti"
    
  5. 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