Skip to main content
Subagenten sind separate Agent-Instanzen, die Ihr Haupt-Agent spawnen kann, um fokussierte Teilaufgaben zu bewältigen. Verwenden Sie Subagenten, um den Kontext zu isolieren, mehrere Analysen parallel auszuführen und spezialisierte Anweisungen anzuwenden, ohne den Prompt des Haupt-Agenten zu überlasten. Dieser Leitfaden erklärt, wie Sie Subagenten im SDK mit dem Parameter agents definieren und verwenden.

Übersicht

Sie können Subagenten auf drei Arten erstellen:
  • Programmatisch: Verwenden Sie den Parameter agents in Ihren query()-Optionen. Siehe die TypeScript- und Python-Referenzen
  • Dateisystem-basiert: Definieren Sie Agenten als Markdown-Dateien in .claude/agents/-Verzeichnissen. Siehe Subagenten als Dateien definieren
  • Integriert allgemein einsetzbar: Claude kann den integrierten general-purpose-Subagenten jederzeit über das Agent-Tool aufrufen, ohne dass Sie etwas definieren müssen
Dieser Leitfaden konzentriert sich auf den programmatischen Ansatz, der für SDK-Anwendungen empfohlen wird. Wenn Sie Subagenten definieren, bestimmt Claude basierend auf dem Feld description jedes Subagenten, ob dieser aufgerufen werden soll. Schreiben Sie klare Beschreibungen, die erklären, wann der Subagent verwendet werden sollte, und Claude wird automatisch geeignete Aufgaben delegieren. Sie können einen Subagenten auch explizit nach Name in Ihrem Prompt anfordern, zum Beispiel „Verwenden Sie den Code-Reviewer-Agent, um…”.

Vorteile der Verwendung von Subagenten

Kontextisolation

Jeder Subagent läuft in seiner eigenen frischen Konversation. Zwischentool-Aufrufe und Ergebnisse bleiben innerhalb des Subagenten; nur seine abschließende Nachricht wird an den übergeordneten Agent zurückgegeben. Siehe Was Subagenten erben für genau das, was sich im Kontext des Subagenten befindet. Beispiel: Ein research-assistant-Subagent kann Dutzende von Dateien durchsuchen, ohne dass dieser Inhalt in der Hauptkonversation angesammelt wird. Der übergeordnete Agent erhält eine prägnante Zusammenfassung, nicht jede Datei, die der Subagent gelesen hat.

Parallelisierung

Mehrere Subagenten können gleichzeitig ausgeführt werden, sodass unabhängige Teilaufgaben in der Zeit des langsamsten statt in der Summe aller abgeschlossen werden. Beispiel: Während einer Code-Überprüfung können Sie die Subagenten style-checker, security-scanner und test-coverage gleichzeitig ausführen, anstatt sie nacheinander auszuführen.

Spezialisierte Anweisungen und Wissen

Jeder Subagent kann maßgeschneiderte System-Prompts mit spezifischer Expertise, Best Practices und Einschränkungen haben. Beispiel: Ein database-migration-Subagent kann detailliertes Wissen über SQL-Best-Practices, Rollback-Strategien und Datenintegritätsprüfungen haben, die in den Anweisungen des Haupt-Agenten unnötiger Lärm wären.

Tool-Einschränkungen

Subagenten können auf bestimmte Tools beschränkt werden, was das Risiko unbeabsichtigter Aktionen verringert. Beispiel: Ein doc-reviewer-Subagent könnte nur Zugriff auf Read- und Grep-Tools haben, um sicherzustellen, dass er Ihre Dokumentationsdateien analysieren, aber niemals versehentlich ändern kann.

Erstellen von Subagenten

Definieren Sie Subagenten direkt in Ihrem Code mit dem Parameter agents. Claude ruft Subagenten über das Agent-Tool auf, daher müssen Sie Agent in allowedTools einschließen, um Subagenten-Aufrufe automatisch zu genehmigen, ohne eine Berechtigungsaufforderung anzuzeigen. Die meisten Beispiele auf dieser Seite geben nur das Endergebnis aus. Um zu bestätigen, dass Claude an einen Subagenten delegiert hat, anstatt direkt zu antworten, siehe Erkennung von Subagenten-Aufrufen. Dieses Beispiel erstellt zwei Subagenten: einen Code-Reviewer mit Nur-Lese-Zugriff und einen Test-Runner, der Befehle ausführen kann.