Subagenten im Claude Code SDK sind spezialisierte KIs, die vom Hauptagenten orchestriert werden. Verwenden Sie Subagenten für Kontextverwaltung und Parallelisierung. Dieser Leitfaden erklärt, wie SDK-Anwendungen mit Subagenten interagieren und diese nutzen, die über Markdown-Dateien erstellt werden.

​
Überblick

Subagenten werden ausschließlich über den dateisystembasierten Ansatz erstellt, indem Markdown-Dateien mit YAML-Frontmatter in bestimmten Verzeichnissen platziert werden. Das SDK kann dann diese vordefinierten Subagenten während der Ausführung aufrufen.

​
Vorteile der Verwendung von Subagenten

​
Kontextverwaltung

Subagenten behalten einen separaten Kontext vom Hauptagenten bei, verhindern Informationsüberladung und halten Interaktionen fokussiert. Diese Isolation stellt sicher, dass spezialisierte Aufgaben den Hauptgesprächskontext nicht mit irrelevanten Details verschmutzen. Beispiel: Ein research-assistant Subagent kann Dutzende von Dateien und Dokumentationsseiten erkunden, ohne das Hauptgespräch mit all den Zwischensuchergebnissen zu überladen - nur die relevanten Erkenntnisse werden zurückgegeben.

​
Parallelisierung

Mehrere Subagenten können gleichzeitig laufen und komplexe Arbeitsabläufe dramatisch beschleunigen. Beispiel: Während einer Code-Überprüfung können Sie style-checker, security-scanner und test-coverage Subagenten gleichzeitig ausführen und die Überprüfungszeit von Minuten auf Sekunden reduzieren.

​
Spezialisierte Anweisungen und Wissen

Jeder Subagent kann maßgeschneiderte Systemprompts mit spezifischer Expertise, bewährten Praktiken und Einschränkungen haben. Beispiel: Ein database-migration Subagent kann detailliertes Wissen über SQL-bewährte Praktiken, Rollback-Strategien und Datenintegritätsprüfungen haben, die unnötiges Rauschen in den Anweisungen des Hauptagenten wären.

​
Werkzeugbeschränkungen

Subagenten können auf spezifische Werkzeuge beschränkt werden, wodurch das Risiko unbeabsichtigter Aktionen reduziert wird. Beispiel: Ein doc-reviewer Subagent könnte nur Zugang zu Read- und Grep-Werkzeugen haben, wodurch sichergestellt wird, dass er analysieren kann, aber niemals versehentlich Ihre Dokumentationsdateien modifiziert.

​
Erstellen von Subagenten

Subagenten werden als Markdown-Dateien in spezifischen Verzeichnissen definiert:
  • Projektebene: .claude/agents/*.md - Nur im aktuellen Projekt verfügbar
  • Benutzerebene: ~/.claude/agents/*.md - In allen Projekten verfügbar

​
Dateiformat

Jeder Subagent ist eine Markdown-Datei mit YAML-Frontmatter: 
---
name: code-reviewer
description: Experte für Code-Überprüfung. Verwenden für Qualitäts-, Sicherheits- und Wartbarkeitsüberprüfungen.
tools: Read, Grep, Glob, Bash  # Optional - erbt alle Werkzeuge wenn weggelassen
---

Der Systemprompt Ihres Subagenten kommt hier hin. Dies definiert die Rolle,
Fähigkeiten und den Ansatz des Subagenten zur Problemlösung.

Fügen Sie spezifische Anweisungen, bewährte Praktiken und alle Einschränkungen
hinzu, die der Subagent befolgen sollte.

​
Konfigurationsfelder

FeldErforderlichBeschreibung
nameJaEindeutige Kennung mit Kleinbuchstaben und Bindestrichen
descriptionJaNatürlichsprachige Beschreibung, wann dieser Subagent verwendet werden soll
toolsNeinKommagetrennte Liste erlaubter Werkzeuge. Wenn weggelassen, erbt alle Werkzeuge

​
Wie das SDK Subagenten verwendet

Bei der Verwendung des Claude Code SDK sind im Dateisystem definierte Subagenten automatisch verfügbar. Claude Code wird:
  1. Subagenten automatisch erkennen aus .claude/agents/ Verzeichnissen
  2. Sie automatisch aufrufen basierend auf Aufgabenabgleich
  3. Ihre spezialisierten Prompts und Werkzeugbeschränkungen verwenden
  4. Separaten Kontext beibehalten für jeden Subagenten-Aufruf
Das SDK respektiert die Dateisystemkonfiguration - es gibt keine programmatische Möglichkeit, Subagenten zur Laufzeit zu erstellen. Alle Subagenten müssen als Dateien vor der SDK-Ausführung definiert werden.

​
Beispiel-Subagenten

Für umfassende Beispiele von Subagenten einschließlich Code-Überprüfern, Test-Runnern, Debuggern und Sicherheitsprüfern, siehe den Haupt-Subagenten-Leitfaden. Der Leitfaden enthält detaillierte Konfigurationen und bewährte Praktiken für die Erstellung effektiver Subagenten.

​
SDK-Integrationsmuster

​
Automatischer Aufruf

Das SDK wird automatisch geeignete Subagenten basierend auf dem Aufgabenkontext aufrufen. Stellen Sie sicher, dass das description-Feld Ihres Subagenten klar angibt, wann er verwendet werden sollte: 
---
name: performance-optimizer
description: PROAKTIV verwenden, wenn Code-Änderungen die Leistung beeinträchtigen könnten. MUSS für Optimierungsaufgaben verwendet werden.
tools: Read, Edit, Bash, Grep
---

​
Expliziter Aufruf

Benutzer können spezifische Subagenten in ihren Prompts anfordern: 
// Bei der Verwendung des SDK können Benutzer explizit Subagenten anfordern:
const result = await query({
  prompt: "Verwende den code-reviewer Subagenten, um das Authentifizierungsmodul zu überprüfen"
});

​
Werkzeugbeschränkungen

Subagenten können beschränkten Werkzeugzugang über das tools-Feld haben:
  • Feld weglassen - Subagent erbt alle verfügbaren Werkzeuge (Standard)
  • Werkzeuge spezifizieren - Subagent kann nur aufgelistete Werkzeuge verwenden
Beispiel eines schreibgeschützten Analyse-Subagenten: 
---
name: code-analyzer
description: Statische Code-Analyse und Architektur-Überprüfung
tools: Read, Grep, Glob  # Keine Schreib- oder Ausführungsberechtigungen
---

Sie sind ein Code-Architektur-Analyst. Analysieren Sie Code-Struktur,
identifizieren Sie Muster und schlagen Sie Verbesserungen vor, ohne Änderungen vorzunehmen.

​
Verwandte Dokumentation