Konfigurieren Sie Ihren Agent

​

Optionen an eine Sitzung übergeben

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

import asyncio

from claude_agent_sdk import ClaudeAgentOptions, ResultMessage, query

async def main():
    options = ClaudeAgentOptions(
        model="claude-sonnet-5",
        allowed_tools=["Read", "Glob", "Grep"],
        max_turns=8,
        cwd="/path/to/repo",
    )

    async for message in query(
        prompt="Summarize the open TODOs in this repo",
        options=options,
    ):
        if isinstance(message, ResultMessage) and not message.is_error:
            print(message.result)

asyncio.run(main())

​

Einstellungsdateien laden

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

​

Wählen Sie ein Modell

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

options = ClaudeAgentOptions(
    model="claude-fable-5",
    fallback_model="claude-opus-5",
)

​

Umgebungsvariablen setzen

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

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

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

​

Legen Sie das Arbeitsverzeichnis fest

• Projekteinstellungen und Hooks: welche Projekteinstellungen und Hooks geladen werden](/de/agent-sdk/claude-code-features)
• Skills: wo session skills are discovered
• Sitzungsspeicher: zu welchem Projekt eine stored session belongs to

​

Begrenzen Sie Züge und Ausgaben

• 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

• 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

​

Ändern Sie die Konfiguration während der Sitzung

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

• 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

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

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())

​

Konfigurieren Sie spezifische Funktionen

​

Nächste Schritte

• 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