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:
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). 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:
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. Server-verwaltete Einstellungen werden abgerufen, wenn sich der Prozess mit einer Organisations-Anmeldedaten authentifiziert; Dateisystem-Isolation entfernt sie nicht. 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

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

Wann welcher Hook-Typ verwendet werden sollte

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