Skip to main content
Una sessione dell’Agent SDK legge la configurazione da file di impostazioni, variabili d’ambiente e dall’oggetto options che passi quando la avvii. Questa pagina mostra come comporre l’oggetto options e quali file di impostazioni e variabili d’ambiente lo controllano. Per ogni tipo di opzione e valore predefinito, consulta i riferimenti Options (TypeScript) e ClaudeAgentOptions (Python).

Passa le opzioni a una sessione

Ogni chiamata query() accetta un oggetto options: Options in TypeScript, ClaudeAgentOptions in Python. Ogni campo è facoltativo e una sessione avviata senza opzioni viene eseguita con i valori predefiniti dell’SDK. L’esempio seguente configura una sessione di sola lettura che riassume i TODO aperti di un progetto. Le coppie si leggono come TypeScript / Python dove gli spelling differiscono:
  • model: sceglie il modello
  • allowedTools / allowed_tools: pre-approva un elenco di strumenti di sola lettura
  • maxTurns / max_turns: limita il numero di turni
  • cwd: imposta la directory di lavoro
Puntate cwd a uno dei vostri progetti e eseguite l’esempio. Il riassunto dei TODO aperti di quel progetto viene stampato quando arriva il messaggio di risultato. allowedTools (TypeScript) o allowed_tools (Python) pre-approva gli strumenti elencati, quindi le chiamate a essi vengono eseguite senza fermarsi per l’approvazione. Gli strumenti al di fuori dell’elenco rimangono disponibili. Quando Claude chiama uno strumento non elencato, la modalità di autorizzazione decide se la chiamata viene eseguita. Per ulteriori informazioni, consultate Allow and deny rules.

Carica i file di impostazioni

I file di impostazioni forniscono configurazioni oltre all’oggetto options. Due opzioni controllano come vengono caricati:
  • settingSources / setting_sources: controlla quali fonti del filesystem caricano: user, project e local. I file di impostazioni e i file CLAUDE.md arrivano attraverso queste fonti.
  • settings: carica un percorso di file di impostazioni o una stringa JSON inline in entrambi i linguaggi, e TypeScript accetta anche un oggetto settings. Qualunque forma passiate sostituisce le impostazioni del filesystem user, project e local; solo le impostazioni di policy gestite hanno una priorità più alta. I riferimenti documentano l’ordine di precedenza completo in Settings precedence per TypeScript e Settings precedence per Python.
Passate [] per disabilitare le impostazioni user, project e local. Per ulteriori informazioni, consultate Use Claude Code features in the SDK.

Scegli un modello

A meno che l’opzione model, le vostre impostazioni o il vostro ambiente non selezionino un modello, una nuova sessione si avvia sul modello predefinito di Claude Code. Per l’ordine di queste fonti, consultate Setting your model. Impostate model per fissare un modello specifico, o per sceglierne uno più piccolo per agenti più veloci e economici. Il valore accetta un alias di modello o un nome di modello completo; gli alias e le versioni a cui si risolvono sono elencati in Model aliases. Impostate fallbackModel (TypeScript) o fallback_model (Python) per nominare un modello di backup. Quando il primario è sovraccarico o non disponibile, la sessione passa al backup. Il primario viene ritentato all’inizio di ogni turno dell’utente, quindi la sessione ritorna ad esso una volta che l’interruzione passa. In entrambi i linguaggi, l’opzione accetta un singolo modello o un elenco separato da virgole di backup. Per l’ordine e il limite della catena, consultate Fallback model chains. In TypeScript, un fallback uguale a model genera un errore all’avvio. Gli esempi seguenti mostrano un elenco di fallback in TypeScript e un singolo fallback in Python:
I parametri della richiesta dell’API Messages temperature, top_p e max_tokens non hanno campi sull’oggetto options in nessuno dei due linguaggi. Impostate il livello di sforzo o un limite di spesa invece, oppure chiamate l’API Messages quando avete bisogno di quei parametri direttamente.

Imposta le variabili d’ambiente

L’opzione env imposta le variabili d’ambiente per il processo Claude Code che esegue la vostra sessione. Se i vostri valori sostituiscono l’ambiente ereditato o si uniscono ad esso differisce per linguaggio:
  • TypeScript: env sostituisce l’ambiente del subprocess
  • Python: l’SDK unisce i vostri valori all’ambiente ereditato, e i vostri valori sostituiscono quelli ereditati
In TypeScript, diffondete process.env in env per mantenere le variabili ereditate come PATH, HOME e ANTHROPIC_API_KEY. Quando lasciate env non impostato, il subprocess eredita il vostro ambiente in entrambi i linguaggi. L’esempio instrada il traffico API attraverso un gateway impostando ANTHROPIC_BASE_URL.
Le variabili che passate possono anche configurare Claude Code stesso. Per le variabili che il processo Claude Code legge, consultate Environment variables. Per sintonizzare i timeout dell’API e il rilevamento di stallo in questo modo, seguite la sezione Handle slow or stalled API responses nel riferimento TypeScript o nel riferimento Python.

Imposta la directory di lavoro

Impostate cwd per eseguire la sessione in una directory specifica. Quando lasciate cwd non impostato, la sessione viene eseguita nella directory di lavoro del vostro processo. Nessuno dei due SDK ha un setter per cwd. Per eseguire in una directory diversa, avviate un’altra sessione con quel cwd. Claude Code legge la directory di lavoro per determinare: Per consentire agli strumenti di raggiungere file al di fuori della directory di lavoro, aggiungete percorsi con additionalDirectories (TypeScript) o add_dirs (Python). Per l’ambito di quella concessione, consultate Additional directories grant file access, not configuration.

Limita i turni e la spesa

Limitate i turni e la spesa con maxTurns / max_turns e maxBudgetUsd / max_budget_usd. Entrambi i limiti sono disattivati quando non impostati. Quando una sessione raggiunge un limite, l’esecuzione termina con un messaggio di risultato il cui sottotipo nomina il limite, error_max_turns o error_max_budget_usd. Quello che succede dopo differisce per modalità di input:
  • Single-shot query(): l’SDK produce il risultato del limite e poi genera un’eccezione, quindi avvolgete il ciclo in un blocco try per continuare oltre l’errore
  • Streaming input: la sessione rimane attiva oltre un risultato di limite, e il conteggio dei turni massimi ricomincia per ogni messaggio in coda. Il totale del budget si accumula tra i messaggi, e una volta che la spesa raggiunge il limite, i messaggi successivi nella stessa conversazione terminano con lo stesso risultato di budget. Un /clear ricomincia il budget
I due limiti trattano 0 diversamente:
  • maxTurns / max_turns: 0 esegue la sessione senza un limite di turni, lo stesso che lasciare l’opzione non impostata
  • maxBudgetUsd / max_budget_usd: la CLI rifiuta 0 come importo non valido all’avvio, e la sessione non viene mai eseguita
Per ulteriori informazioni su entrambi i limiti, inclusa la spesa dei subagenti, consultate Turns and budget.

Cambia la configurazione durante la sessione

Quando avviate una sessione con streaming input, potete cambiare il suo modello e la modalità di autorizzazione mentre è in esecuzione. Dove chiamate i setter differisce per linguaggio:
  • TypeScript: metodi sull’oggetto che query() restituisce
  • Python: metodi su ClaudeSDKClient, poiché query() restituisce un iteratore semplice senza metodi di controllo
Entrambi i linguaggi hanno gli stessi setter:
  • setModel() / set_model(): cambia il modello. Chiamatelo senza modello per passare al modello predefinito di Claude Code piuttosto che al model che avete passato nelle opzioni.
  • setPermissionMode() / set_permission_mode(): cambia la modalità di autorizzazione
TypeScript ha anche applyFlagSettings() e updateSettings():
  • applyFlagSettings(): applica le impostazioni in fase di esecuzione, come in await session.applyFlagSettings({ effortLevel: "high" }). Il metodo accetta chiavi di file di impostazioni piuttosto che campi di opzioni, quindi controllate il riferimento applyFlagSettings() per lo schema e per quali chiavi hanno effetto durante la sessione.
  • updateSettings(): scrive un insieme di chiavi consentite nel file di impostazioni locali del progetto, come in await session.updateSettings("localSettings", { outputStyle: "Explanatory" }). Le chiavi scritte hanno effetto sulla richiesta successiva della sessione e persistono per le sessioni successive che caricano le impostazioni local. La riga del metodo nella tabella dei metodi nomina le chiavi consentite e il floor della versione.
L’esempio seguente esegue una sessione a due turni, cambia la configurazione tra i turni e stampa il modello che ha risposto a ogni turno. In TypeScript, il flusso del prompt tiene il secondo messaggio fino a quando i setter non hanno funzionato, e il secondo turno viene eseguito sul nuovo modello.
Sull’API Claude, il programma stampa First turn model: claude-sonnet-5, poi Second turn model: claude-opus-5 dopo il cambio.
Ogni modello ha la sua propria cache del prompt, quindi dopo un cambio durante la sessione la richiesta successiva ricalcola la conversazione completa non memorizzata nella cache alle tariffe del nuovo modello. Per ulteriori informazioni, consultate Switching models.

Configura funzionalità specifiche

La tabella seguente mappa ogni opzione alla funzionalità che configura. Per le opzioni che questa pagina non copre, consultate i riferimenti TypeScript e Python. Se conoscete il vostro obiettivo ma non quale opzione lo serve, iniziate da Choose the right feature.

Passaggi successivi

Per vedere la configurazione composta in agenti funzionanti:
  • Quickstart: costruisci ed esegui un primo agente da capo a fondo
  • Examples: trova un progetto completo e eseguibile o una ricetta guidata di Claude Cookbook che corrisponde a quello che vuoi costruire
  • Multi-tenant isolation: isola le impostazioni e la memoria di ogni tenant con settingSources / setting_sources, env e cwd