SpyBara
Go Premium

agent-sdk/configuration.md 2026-09-17 05:00 UTC to 2026-09-18 23:58 UTC

This page contains 315 additions and 0 deletions.

2026
Fri 18 23:58 Tue 22 23:59

Konfigurieren Sie Ihren Agent

Konfigurieren Sie Agent SDK-Sitzungen: stellen Sie das Optionsobjekt zusammen, legen Sie das Modell, die Umgebung und Limits fest, und finden Sie die Seite jeder Funktionsoption.

Eine Agent SDK-Sitzung liest die Konfiguration aus Einstellungsdateien, Umgebungsvariablen und dem options-Objekt, das Sie beim Starten übergeben. Diese Seite zeigt, wie Sie das options-Objekt zusammenstellen und welche Einstellungsdateien und Umgebungsvariablen die Kontrolle übernehmen.

Für jeden Optionstyp und Standard siehe die Options (TypeScript) und ClaudeAgentOptions (Python) Referenzen.

Optionen an eine Sitzung übergeben

Jeder query()-Aufruf akzeptiert ein Optionsobjekt: Options in TypeScript, ClaudeAgentOptions in Python. Jedes Feld ist optional, und eine Sitzung, die ohne Optionen gestartet wird, läuft mit den SDK-Standardwerten. Das folgende Beispiel konfiguriert eine schreibgeschützte Sitzung, die die offenen TODOs eines Projekts zusammenfasst. Paare lesen sich als TypeScript / Python, wo sich die Schreibweisen unterscheiden:

  • model: wählt das Modell
  • allowedTools / allowed_tools: genehmigt vorab eine schreibgeschützte Werkzeugliste
  • maxTurns / max_turns: begrenzt die Anzahl der Züge
  • cwd: legt das Arbeitsverzeichnis fest
import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
prompt: "Summarize the open TODOs in this repo",
options: {
model: "claude-sonnet-5",
allowedTools: ["Read", "Glob", "Grep"],
maxTurns: 8,
cwd: "/path/to/repo",
},
})) {
if (message.type === "result" && message.subtype === "success" && !message.is_error) {
console.log(message.result);
}
}

Zeigen Sie cwd auf eines Ihrer eigenen Projekte und führen Sie das Beispiel aus. Die Zusammenfassung der offenen TODOs dieses Projekts wird gedruckt, wenn die Ergebnismeldung ankommt.

allowedTools (TypeScript) oder allowed_tools (Python) genehmigt die aufgelisteten Werkzeuge vorab, sodass Aufrufe an sie ohne Genehmigung ausgeführt werden. Werkzeuge außerhalb der Liste bleiben verfügbar. Wenn Claude ein nicht aufgelistetes Werkzeug aufruft, entscheidet der Genehmigungsmodus, ob der Aufruf ausgeführt wird. Weitere Informationen finden Sie unter Allow and deny rules.

Einstellungsdateien laden

Einstellungsdateien liefern Konfigurationen über das Optionsobjekt hinaus. Zwei Optionen steuern, wie sie geladen werden:

  • settingSources / setting_sources: steuert, welche Dateisystemquellen geladen werden: Benutzer, Projekt und lokal. Einstellungsdateien und CLAUDE.md-Dateien kommen durch diese Quellen an.
  • settings: lädt einen Einstellungsdateipfad oder eine Inline-JSON-Zeichenkette in beiden Sprachen, und TypeScript akzeptiert auch ein Einstellungsobjekt. Welche Form Sie auch übergeben, sie überschreibt Benutzer-, Projekt- und lokale Dateisystemeinstellungen; nur verwaltete Richtlinieneinstellungen haben einen höheren Rang. Die Referenzen dokumentieren die vollständige Rangfolge unter Settings precedence für TypeScript und Settings precedence für Python.

Übergeben Sie [], um Benutzer-, Projekt- und lokale Einstellungen zu deaktivieren. Weitere Informationen finden Sie unter Use Claude Code features in the SDK.

Wählen Sie ein Modell

Wenn die model-Option, Ihre Einstellungen oder Ihre Umgebung kein Modell auswählen, startet eine neue Sitzung auf Claude Code's default model. Für die Reihenfolge dieser Quellen siehe Setting your model. Setzen Sie model, um ein bestimmtes Modell festzulegen, oder wählen Sie ein kleineres für schnellere, günstigere Agenten. Der Wert nimmt einen Modellalias oder einen vollständigen Modellnamen an; Aliase und die Versionen, zu denen sie aufgelöst werden, sind unter Model aliases aufgelistet.

Setzen Sie fallbackModel (TypeScript) oder fallback_model (Python), um ein Sicherungsmodell zu benennen. Wenn das primäre Modell überlastet oder nicht verfügbar ist, wechselt die Sitzung zum Sicherungsmodell. Das primäre Modell wird zu Beginn jedes Benutzerzugs erneut versucht, sodass die Sitzung zu ihm zurückkehrt, sobald der Ausfall vorbei ist.

In beiden Sprachen akzeptiert die Option ein einzelnes Modell oder eine kommagetrennte Liste von Sicherungen. Für die Reihenfolge und die Kettenbegrenzung siehe Fallback model chains. In TypeScript wirft ein Fallback gleich model einen Fehler beim Start.

Die folgenden Beispiele zeigen eine Fallback-Liste in TypeScript und ein einzelnes Fallback in Python:

const options = {
model: "claude-fable-5",
fallbackModel: "claude-opus-5,claude-sonnet-5",
};

Umgebungsvariablen setzen

Die env-Option setzt Umgebungsvariablen für den Claude Code-Prozess, der Ihre Sitzung ausführt. Ob Ihre Werte die geerbte Umgebung ersetzen oder sich über sie hinweg zusammensetzen, unterscheidet sich je nach Sprache:

  • TypeScript: env ersetzt die Subprozessumgebung
  • Python: das SDK setzt Ihre Werte über die geerbte Umgebung zusammen, und Ihre Werte überschreiben die geerbten

In TypeScript verteilen Sie process.env in env, um geerbte Variablen wie PATH, HOME und ANTHROPIC_API_KEY zu behalten. Wenn Sie env nicht setzen, erbt der Subprozess Ihre Umgebung in beiden Sprachen.

Das Beispiel leitet API-Verkehr durch ein Gateway, indem es ANTHROPIC_BASE_URL setzt.

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

Die Variablen, die Sie übergeben, können auch Claude Code selbst konfigurieren. Für die Variablen, die der Claude Code-Prozess liest, siehe Environment variables. Um API-Timeouts und Stall-Erkennung auf diese Weise zu optimieren, folgen Sie dem Abschnitt Handle slow or stalled API responses in der TypeScript reference oder der Python reference.

Legen Sie das Arbeitsverzeichnis fest

Setzen Sie cwd, um die Sitzung in einem bestimmten Verzeichnis auszuführen. Wenn Sie cwd nicht setzen, läuft die Sitzung im Arbeitsverzeichnis Ihres Prozesses. Keines der SDKs hat einen Setter für cwd. Um in einem anderen Verzeichnis auszuführen, starten Sie eine weitere Sitzung mit diesem cwd.

Claude Code liest das Arbeitsverzeichnis, um Folgendes zu bestimmen:

Um Werkzeugen den Zugriff auf Dateien außerhalb des Arbeitsverzeichnisses zu ermöglichen, fügen Sie Pfade mit additionalDirectories (TypeScript) oder add_dirs (Python) hinzu. Für den Umfang dieser Berechtigung siehe Additional directories grant file access, not configuration.

Begrenzen Sie Züge und Ausgaben

Begrenzen Sie Züge und Ausgaben mit maxTurns / max_turns und maxBudgetUsd / max_budget_usd. Beide Limits sind deaktiviert, wenn nicht gesetzt. Wenn eine Sitzung ein Limit erreicht, endet der Lauf mit einer Ergebnismeldung, deren Subtyp das Limit benennt, error_max_turns oder error_max_budget_usd. Was danach passiert, unterscheidet sich je nach Eingabemodus:

  • Single-shot query(): das SDK gibt das Cap-Ergebnis aus und wirft dann, also wickeln Sie die Schleife in einen Try-Block, um über den Fehler hinaus zu gehen
  • Streaming input: die Sitzung bleibt über ein Cap-Ergebnis hinaus aktiv, und die Max-Turns-Anzahl beginnt für jede eingereihte Nachricht von vorne. Das Budget-Total sammelt sich über Nachrichten an, und sobald die Ausgaben das Limit erreichen, enden spätere Nachrichten in derselben Konversation mit demselben Budget-Ergebnis. Ein /clear startet das Budget neu

Die beiden Limits behandeln 0 unterschiedlich:

  • maxTurns / max_turns: 0 führt die Sitzung ohne Zuglimit aus, dasselbe wie das Nicht-Setzen der Option
  • maxBudgetUsd / max_budget_usd: die CLI lehnt 0 als ungültigen Betrag beim Start ab, und die Sitzung läuft nie

Weitere Informationen zu beiden Limits, einschließlich Subagent-Ausgaben, finden Sie unter Turns and budget.

Ändern Sie die Konfiguration während der Sitzung

Wenn Sie eine Sitzung mit streaming input starten, können Sie ihr Modell und ihren Genehmigungsmodus während der Ausführung wechseln. Wo Sie die Setter aufrufen, unterscheidet sich je nach Sprache:

  • TypeScript: Methoden auf dem Objekt, das query() zurückgibt
  • Python: Methoden auf ClaudeSDKClient, da query() einen einfachen Iterator ohne Kontrollmethoden zurückgibt

Beide Sprachen haben die gleichen Setter:

  • setModel() / set_model(): wechselt das Modell. Rufen Sie es ohne Modell auf, um zu Claude Code's default model zu wechseln, anstatt zum model, das Sie in Optionen übergeben haben.
  • setPermissionMode() / set_permission_mode(): wechselt den Genehmigungsmodus

TypeScript hat auch applyFlagSettings() und updateSettings():

  • applyFlagSettings(): wendet Einstellungen zur Laufzeit an, wie in await session.applyFlagSettings({ effortLevel: "high" }). Die Methode nimmt Einstellungsdateischlüssel anstelle von Optionsfeldern, also überprüfen Sie die applyFlagSettings() reference für das Schema und für welche Schlüssel während der Sitzung wirksam werden.
  • updateSettings(): schreibt einen zulassungslisten Satz von Schlüsseln in die lokale Einstellungsdatei des Projekts, wie in await session.updateSettings("localSettings", { outputStyle: "Explanatory" }). Die geschriebenen Schlüssel treten bei der nächsten Anfrage der Sitzung in Kraft und bleiben für spätere Sitzungen bestehen, die local-Einstellungen laden. Die Zeile der Methode in der methods table benennt die zulassungslisten Schlüssel und die Versionsuntergrenze.

Das folgende Beispiel führt eine zweizügige Sitzung aus, ändert die Konfiguration zwischen den Zügen und druckt das Modell, das jeden Zug beantwortet hat. In TypeScript hält der Prompt-Stream die zweite Nachricht, bis die Setter ausgeführt wurden, und der zweite Zug läuft auf dem neuen Modell.

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;
}
}
}

Auf der Claude API druckt das Programm First turn model: claude-sonnet-5, dann Second turn model: claude-opus-5 nach dem Wechsel.

Konfigurieren Sie spezifische Funktionen

Die folgende Tabelle ordnet jede Option der Funktion zu, die sie konfiguriert. Für Optionen, die diese Seite nicht abdeckt, siehe die TypeScript und Python Referenzen. Wenn Sie Ihr Ziel kennen, aber nicht welche Option es erfüllt, beginnen Sie mit Choose the right feature.

TypeScript Python Steuert Abgedeckt in
permissionMode permission_mode Was der Agent ohne Genehmigung tun kann Configure permissions
allowedTools allowed_tools Welche Werkzeugaufrufe vorab genehmigt sind Configure permissions
canUseTool can_use_tool Ihr Genehmigungsrückruf für Werkzeugaufrufe Handle tool approval requests
systemPrompt system_prompt Die Anweisungen des Agenten Modifying system prompts
settingSources setting_sources Welche Dateisystemeinstellungen geladen werden Use Claude Code features in the SDK
mcpServers mcp_servers Externe Werkzeugserver Connect to external tools with MCP
agents agents Subagent-Definitionen Subagents
hooks hooks Rückrufe an Lebenszykluspunkten Hooks
skills skills Welche Skills geladen werden Extend agents with skills
plugins plugins Welche Plugins geladen werden Plugins
outputFormat output_format Strukturierte Ausgabeschemas Structured outputs
resume resume Fortsetzen einer gespeicherten Sitzung Sessions
forkSession fork_session Verzweigung einer Sitzung Sessions
sessionStore session_store Externe Sitzungspersistenz Session storage
enableFileCheckpointing enable_file_checkpointing Rückgängig machbare Dateibearbeitungen File checkpointing
effort effort Wie viel Arbeit Claude in Antworten investiert Effort level
sandbox sandbox Sandbox-Verhalten für Werkzeugausführung TypeScript und Python Referenzen, mit Bereitstellungskontext in Secure deployment

Nächste Schritte

Um Konfiguration in funktionierenden Agenten zusammengesetzt zu sehen:

  • Quickstart: bauen und führen Sie einen ersten Agent von Anfang bis Ende aus
  • Examples: finden Sie ein vollständiges, ausführbares Projekt oder ein geführtes Claude Cookbook-Rezept, das dem entspricht, was Sie bauen möchten
  • Multi-tenant isolation: isolieren Sie die Einstellungen und den Speicher jedes Mandanten mit settingSources / setting_sources, env und cwd