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.

const options = {
env: { ...process.env, ANTHROPIC_BASE_URL: "https://gateway.example.com" },
};

options = ClaudeAgentOptions(
env={"ANTHROPIC_BASE_URL": "https://gateway.example.com"},
)

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:

• Project settings and hooks: quale impostazioni e hook del progetto caricano
• Skills: dove le skill della sessione vengono scoperte
• Session storage: quale progetto una sessione memorizzata appartiene a

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 una chiave consentita in un file di impostazioni. Il riferimento updateSettings() nomina la chiave che ogni sorgente accetta e il floor della versione.
  • Passate "localSettings" per scrivere il file di impostazioni locali del progetto, come in await session.updateSettings("localSettings", { outputStyle: "Explanatory" }). La chiave scritta ha effetto sulla richiesta successiva della sessione e persiste per le sessioni successive che caricano le impostazioni local.
  • Passate "userSettings" per scrivere effortLevel, l'unica chiave che la sorgente accetta. Claude Code la salva come il livello di sforzo predefinito per il modello corrente della sessione, e lo sforzo della sessione in esecuzione non cambia.

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.

import { query, type SDKUserMessage } from "@anthropic-ai/claude-agent-sdk";

function userMessage(text: string): SDKUserMessage {
return { type: "user", message: { role: "user", content: text }, parent_tool_use_id: null };
}

// Hold the second prompt until the setters have run.
let startSecondTurn!: () => void;
const secondTurnReady = new Promise<void>((resolve) => {
startSecondTurn = resolve;
});

async function* turnPrompts(): AsyncGenerator<SDKUserMessage, void> {
yield userMessage("Reply with exactly: ready");
await secondTurnReady;
yield userMessage("Reply with exactly: done");
}

const session = query({
prompt: turnPrompts(),
options: {
model: "claude-sonnet-5",
},
});

let turnModel = "";
let completedTurns = 0;

for await (const message of session) {
if (message.type === "assistant") {
turnModel = message.message.model;
} else if (message.type === "result") {
completedTurns += 1;
if (completedTurns === 1) {
console.log(`First turn model: ${turnModel}`);
await session.setModel("claude-opus-5");
await session.setPermissionMode("acceptEdits");
startSecondTurn();
} else {
console.log(`Second turn model: ${turnModel}`);
break;
}
}
}

import asyncio

from claude_agent_sdk import AssistantMessage, ClaudeAgentOptions, ClaudeSDKClient

async def main():
options = ClaudeAgentOptions(model="claude-sonnet-5")

async with ClaudeSDKClient(options=options) as client:
await client.query("Reply with exactly: ready")
first_model = ""
async for message in client.receive_response():
if isinstance(message, AssistantMessage):
first_model = message.model

await client.set_model("claude-opus-5")
await client.set_permission_mode("acceptEdits")

await client.query("Reply with exactly: done")
second_model = ""
async for message in client.receive_response():
if isinstance(message, AssistantMessage):
second_model = message.model

print(f"First turn model: {first_model}")
print(f"Second turn model: {second_model}")

asyncio.run(main())

Sull'API Claude, il programma stampa First turn model: claude-sonnet-5, poi Second turn model: claude-opus-5 dopo il cambio.

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