Zum Hauptinhalt springen
Das Agent SDK basiert auf der gleichen Grundlage wie Claude Code, was bedeutet, dass Ihre SDK-Agenten Zugriff auf die gleichen dateisystemgestützten Funktionen haben: Projektanweisungen (CLAUDE.md und Regeln), Skills, Hooks und mehr. Wenn Sie settingSources weglassen, liest query() die gleichen Dateisystemeinstellungen wie die Claude Code CLI: Benutzer-, Projekt- und lokale Einstellungen, CLAUDE.md-Dateien und .claude/-Skills, Agenten und Befehle. Um ohne diese auszuführen, übergeben Sie settingSources: [], was den Agenten auf das beschränkt, was Sie programmgesteuert konfigurieren. Verwaltete Richtlinieneinstellungen und die globale ~/.claude.json-Konfiguration werden unabhängig von dieser Option gelesen. Siehe Was settingSources nicht kontrolliert. Für einen konzeptionellen Überblick über das, was jede Funktion tut und wann sie verwendet werden sollte, siehe Claude Code erweitern.

Dateisystemeinstellungen mit settingSources kontrollieren

Die Einstellungsquellen-Option (setting_sources in Python, settingSources in TypeScript) kontrolliert, welche dateisystemgestützten Einstellungen das SDK lädt. Übergeben Sie eine explizite Liste, um sich für bestimmte Quellen anzumelden, oder übergeben Sie ein leeres Array, um Benutzer-, Projekt- und lokale Einstellungen zu deaktivieren. Dieses Beispiel lädt sowohl Benutzer- als auch Projektebenen-Einstellungen, indem settingSources auf ["user", "project"] gesetzt wird:
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ResultMessage

async for message in query(
    prompt="Help me refactor the auth module",
    options=ClaudeAgentOptions(
        # "user" loads from ~/.claude/, "project" loads from ./.claude/ in cwd.
        # Together they give the agent access to CLAUDE.md, skills, hooks, and
        # permissions from both locations.
        setting_sources=["user", "project"],
        allowed_tools=["Read", "Edit", "Bash"],
    ),
):
    if isinstance(message, AssistantMessage):
        for block in message.content:
            if hasattr(block, "text"):
                print(block.text)
    if isinstance(message, ResultMessage) and message.subtype == "success":
        print(f"\nResult: {message.result}")
Jede Quelle lädt Einstellungen von einem bestimmten Ort, wobei <cwd> das Arbeitsverzeichnis ist, das Sie über die cwd-Option übergeben, oder das aktuelle Verzeichnis des Prozesses, falls nicht gesetzt. Für die vollständige Typdefinition siehe SettingSource (TypeScript) oder SettingSource (Python).
QuelleWas wird geladenOrt
"project"Projekt-CLAUDE.md, .claude/rules/*.md, Projekt-Skills, Projekt-Hooks, Projekt-settings.json<cwd>/.claude/ für settings.json und Hooks; <cwd> und jedes übergeordnete Verzeichnis für CLAUDE.md und Regeln; <cwd> und jedes übergeordnete Verzeichnis bis zur Repository-Root für Skills
"user"Benutzer-CLAUDE.md, ~/.claude/rules/*.md, Benutzer-Skills, Benutzereinstellungen~/.claude/
"local"CLAUDE.local.md, .claude/settings.local.json<cwd>/.claude/ für settings.local.json; <cwd> und jedes übergeordnete Verzeichnis für CLAUDE.local.md
Das Weglassen von settingSources entspricht ["user", "project", "local"]. Die cwd-Option bestimmt, wo das SDK nach Projekteinstellungen sucht. CLAUDE.md und Regeln werden aus <cwd> und aus jedem übergeordneten Verzeichnis geladen. Skills werden aus <cwd> und aus jedem übergeordneten Verzeichnis bis zur Repository-Root geladen. Projekt-settings.json und Hooks werden nur aus <cwd>/.claude/ geladen, ohne Fallback für übergeordnete Verzeichnisse.

Was settingSources nicht kontrolliert

settingSources umfasst Benutzer-, Projekt- und lokale Einstellungen. Einige Eingaben werden unabhängig von ihrem Wert gelesen:
EingabeVerhaltenZum Deaktivieren
Verwaltete RichtlinieneinstellungenImmer geladen, wenn auf dem Host vorhandenEntfernen Sie die verwaltete Einstellungsdatei
~/.claude.json globale KonfigurationImmer gelesenVerschieben Sie mit CLAUDE_CONFIG_DIR in env
Automatisches Gedächtnis unter ~/.claude/projects/<project>/memory/Standardmäßig in die Systemaufforderung geladenSetzen Sie autoMemoryEnabled: false in Einstellungen oder CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 in env
claude.ai MCP-KonnektorenGeladen, wenn die aktive Authentifizierungsmethode ein claude.ai-Abonnement ist. Das Übergeben von mcpServers: {} unterdrückt sie nichtSetzen Sie strictMcpConfig: true oder ENABLE_CLAUDEAI_MCP_SERVERS=false in env
Verlassen Sie sich nicht auf Standard-query()-Optionen für Multi-Tenant-Isolation. Da die obigen Eingaben unabhängig von settingSources gelesen werden, kann ein SDK-Prozess Host-Level-Konfiguration und Pro-Verzeichnis-Speicher aufgreifen. Für Multi-Tenant-Bereitstellungen führen Sie jeden Mandanten in seinem eigenen Dateisystem aus und setzen Sie settingSources: [] plus CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 in env. Siehe Sichere Bereitstellung.

Projektanweisungen (CLAUDE.md und Regeln)

CLAUDE.md-Dateien und .claude/rules/*.md-Dateien geben Ihrem Agenten persistenten Kontext über Ihr Projekt: Codierungskonventionen, Build-Befehle, Architekturentscheidungen und Anweisungen. Wenn settingSources "project" enthält (wie im obigen Beispiel), lädt das SDK diese Dateien beim Sitzungsstart in den Kontext. Der Agent folgt dann Ihren Projektkonventionen, ohne dass Sie sie in jedem Prompt wiederholen müssen.

CLAUDE.md-Ladeorte

EbeneOrtWann geladen
Projekt (Wurzel)<cwd>/CLAUDE.md oder <cwd>/.claude/CLAUDE.mdsettingSources enthält "project"
Projektregeln<cwd>/.claude/rules/*.md und .claude/rules/*.md in jedem übergeordneten VerzeichnissettingSources enthält "project"
Projekt (übergeordnete Verzeichnisse)CLAUDE.md-Dateien in Verzeichnissen über cwdsettingSources enthält "project", geladen beim Sitzungsstart
Projekt (Unterverzeichnisse)CLAUDE.md-Dateien in Unterverzeichnissen von cwdsettingSources enthält "project", bei Bedarf geladen, wenn der Agent eine Datei in diesem Unterbaum liest
Lokal<cwd>/CLAUDE.local.md und CLAUDE.local.md in jedem übergeordneten VerzeichnissettingSources enthält "local"
Benutzer~/.claude/CLAUDE.mdsettingSources enthält "user"
Benutzerregeln~/.claude/rules/*.mdsettingSources enthält "user"
Alle Ebenen sind additiv: Wenn sowohl Projekt- als auch Benutzer-CLAUDE.md-Dateien vorhanden sind, sieht der Agent beide. Es gibt keine harte Vorrangregel zwischen Ebenen; wenn Anweisungen in Konflikt geraten, hängt das Ergebnis davon ab, wie Claude sie interpretiert. Schreiben Sie nicht in Konflikt stehende Regeln, oder geben Sie den Vorrang explizit in der spezifischeren Datei an („Diese Projektanweisungen überschreiben alle in Konflikt stehenden Benutzer-Level-Standardwerte”).
Sie können auch Kontext direkt über systemPrompt injizieren, ohne CLAUDE.md-Dateien zu verwenden. Siehe Systemaufforderungen ändern. Verwenden Sie CLAUDE.md, wenn Sie den gleichen Kontext zwischen interaktiven Claude Code-Sitzungen und Ihren SDK-Agenten teilen möchten.
Informationen zur Strukturierung und Organisation von CLAUDE.md-Inhalten finden Sie unter Claudes Speicher verwalten.

Skills

Skills sind Markdown-Dateien, die Ihrem Agenten spezialisiertes Wissen und aufrufbare Workflows geben. Im Gegensatz zu CLAUDE.md (das jede Sitzung geladen wird) werden Skills bei Bedarf geladen. Der Agent erhält Skill-Beschreibungen beim Start und lädt den vollständigen Inhalt, wenn relevant. Skills werden durch settingSources vom Dateisystem entdeckt. Wenn die skills-Option bei query() weggelassen wird, werden entdeckte Benutzer- und Projekt-Skills aktiviert und das Skill-Tool ist verfügbar, was dem CLI-Verhalten entspricht. Um zu steuern, welche Skills aktiviert sind, übergeben Sie skills als "all", eine Liste von Skill-Namen oder [], um alle zu deaktivieren. Wenn skills gesetzt ist, fügt das SDK das Skill-Tool automatisch zu allowedTools hinzu. Wenn Sie auch eine explizite tools-Liste übergeben, fügen Sie "Skill" in diese Liste ein, damit Claude Skills aufrufen kann.
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage

# Skills in .claude/skills/ are discovered automatically
# when settingSources includes "project"
async for message in query(
    prompt="Review this PR using our code review checklist",
    options=ClaudeAgentOptions(
        setting_sources=["user", "project"],
        skills="all",
        allowed_tools=["Read", "Grep", "Glob"],
    ),
):
    if isinstance(message, ResultMessage) and message.subtype == "success":
        print(message.result)
Skills müssen als Dateisystem-Artefakte erstellt werden (.claude/skills/<name>/SKILL.md). Das SDK hat keine programmgesteuerte API zum Registrieren von Skills. Siehe Agent Skills im SDK für vollständige Details.
Weitere Informationen zum Erstellen und Verwenden von Skills finden Sie unter Agent Skills im SDK.

Hooks

Das SDK unterstützt zwei Möglichkeiten, Hooks zu definieren, und sie laufen nebeneinander:
  • Dateisystem-Hooks: Shell-Befehle, die in settings.json definiert sind und geladen werden, wenn settingSources die relevante Quelle enthält. Dies sind die gleichen Hooks, die Sie für interaktive Claude Code-Sitzungen konfigurieren würden.
  • Programmgesteuerte Hooks: Callback-Funktionen, die direkt an query() übergeben werden. Diese laufen in Ihrem Anwendungsprozess und können strukturierte Entscheidungen zurückgeben. Siehe Ausführung mit Hooks kontrollieren.
Beide Typen werden während des gleichen Hook-Lebenszyklus ausgeführt. Wenn Sie bereits Hooks in der .claude/settings.json Ihres Projekts haben und Sie settingSources: ["project"] setzen, werden diese Hooks automatisch im SDK ohne zusätzliche Konfiguration ausgeführt. Hook-Callbacks erhalten die Tool-Eingabe und geben ein Entscheidungs-Dict zurück. Das Zurückgeben von {} bedeutet, dass das Tool fortfahren darf. Um die Ausführung zu blockieren, geben Sie ein hookSpecificOutput-Objekt mit permissionDecision: "deny" und einem permissionDecisionReason zurück. Der Grund wird Claude als Tool-Ergebnis gesendet. Die Top-Level-Felder decision und reason sind für PreToolUse veraltet. Siehe das Hooks-Handbuch für die vollständige Callback-Signatur und Rückgabetypen.
from claude_agent_sdk import query, ClaudeAgentOptions, HookMatcher, ResultMessage


# PreToolUse hook callback. Positional args:
#   input_data: HookInput dict with tool_name, tool_input, hook_event_name
#   tool_use_id: str | None, the ID of the tool call being intercepted
#   context: HookContext, carries session metadata
async def audit_bash(input_data, tool_use_id, context):
    command = input_data.get("tool_input", {}).get("command", "")
    if "rm -rf" in command:
        return {
            "hookSpecificOutput": {
                "hookEventName": "PreToolUse",
                "permissionDecision": "deny",
                "permissionDecisionReason": "Destructive command blocked",
            }
        }
    return {}  # Empty dict: allow the tool to proceed


# Filesystem hooks from .claude/settings.json run automatically
# when settingSources loads them. You can also add programmatic hooks:
async for message in query(
    prompt="Refactor the auth module",
    options=ClaudeAgentOptions(
        setting_sources=["project"],  # Loads hooks from .claude/settings.json
        hooks={
            "PreToolUse": [
                HookMatcher(matcher="Bash", hooks=[audit_bash]),
            ]
        },
    ),
):
    if isinstance(message, ResultMessage) and message.subtype == "success":
        print(message.result)

Wann welcher Hook-Typ verwendet werden sollte

Hook-TypAm besten für
Dateisystem (settings.json)Gemeinsame Nutzung von Hooks zwischen CLI- und SDK-Sitzungen. Unterstützt "command" (Shell-Skripte), "http" (POST an einen Endpunkt), "mcp_tool" (Aufrufen eines Tools eines verbundenen MCP-Servers), "prompt" (LLM wertet einen Prompt aus) und "agent" (spawnt einen Verifier-Agenten). Diese werden im Haupt-Agenten und allen Subagenten, die er spawnt, ausgeführt.
Programmgesteuert (Callbacks in query())Anwendungsspezifische Logik, strukturierte Entscheidungen und In-Process-Integration. Diese werden auch in Subagenten ausgeführt. Der Callback empfängt agent_id und agent_type, um zu unterscheiden.
Das TypeScript SDK unterstützt zusätzliche Hook-Events über Python hinaus, einschließlich SessionStart, SessionEnd, TeammateIdle und TaskCompleted. Siehe das Hooks-Handbuch für die vollständige Ereigniskompatibilitätstabelle.
Vollständige Details zu programmgesteuerten Hooks finden Sie unter Ausführung mit Hooks kontrollieren. Für Dateisystem-Hook-Syntax siehe Hooks.

Wählen Sie die richtige Funktion

Das Agent SDK gibt Ihnen Zugriff auf mehrere Möglichkeiten, das Verhalten Ihres Agenten zu erweitern. Wenn Sie unsicher sind, welche Sie verwenden sollten, ordnet diese Tabelle häufige Ziele dem richtigen Ansatz zu.
Sie möchten…Verwenden SieSDK-Oberfläche
Projektkonventionen festlegen, die Ihr Agent immer befolgtCLAUDE.mdsettingSources: ["project"] lädt es automatisch
Dem Agenten Referenzmaterial geben, das er bei Bedarf lädtSkillssettingSources + skills-Option
Einen wiederverwendbaren Workflow ausführen (bereitstellen, überprüfen, freigeben)Benutzer-aufrufbare SkillssettingSources + skills-Option
Eine isolierte Teilaufgabe an einen frischen Kontext delegieren (Recherche, Überprüfung)Subagentenagents-Parameter + allowedTools: ["Agent"]
Mehrere Claude Code-Instanzen mit gemeinsamen Aufgabenlisten und direkter Inter-Agent-Messaging koordinierenAgent-TeamsNicht direkt über SDK-Optionen konfiguriert. Agent-Teams sind eine CLI-Funktion, bei der eine Sitzung als Team-Lead fungiert und die Arbeit über unabhängige Teammates koordiniert
Deterministische Logik auf Tool-Aufrufe ausführen (Audit, Block, Transform)Hookshooks-Parameter mit Callbacks oder Shell-Skripte, die über settingSources geladen werden
Claude strukturierten Tool-Zugriff auf einen externen Service gebenMCPmcpServers-Parameter
Subagenten versus Agent-Teams: Subagenten sind kurzlebig und isoliert: frische Konversation, eine Aufgabe, Zusammenfassung an übergeordnete Instanz zurückgegeben. Agent-Teams koordinieren mehrere unabhängige Claude Code-Instanzen, die eine Aufgabenliste teilen und sich direkt gegenseitig Nachrichten senden. Agent-Teams sind eine CLI-Funktion. Siehe Was Subagenten erben und den Agent-Teams-Vergleich für Details.
Jede Funktion, die Sie aktivieren, trägt zu Ihrem Agent-Kontextfenster bei. Für Pro-Funktion-Kosten und wie diese Funktionen zusammen funktionieren, siehe Claude Code erweitern.

Verwandte Ressourcen

  • Claude Code erweitern: Konzeptioneller Überblick über alle Erweiterungsfunktionen mit Vergleichstabellen und Kontextkostenanalyse
  • Skills im SDK: Vollständiges Handbuch zur programmgesteuerten Verwendung von Skills
  • Subagenten: Definieren und rufen Sie Subagenten für isolierte Teilaufgaben auf
  • Hooks: Abfangen und Kontrollieren des Agent-Verhaltens an wichtigen Ausführungspunkten
  • Berechtigungen: Kontrollieren Sie Tool-Zugriff mit Modi, Regeln und Callbacks
  • Systemaufforderungen: Injizieren Sie Kontext ohne CLAUDE.md-Dateien