agents-Parameter definieren und verwenden.
Überblick
Subagenten können bei der Verwendung des SDK auf zwei Arten definiert werden:- Programmatisch - Verwendung des
agents-Parameters in Ihrenquery()-Optionen (empfohlen für SDK-Anwendungen) - Dateisystembasiert - Platzierung von Markdown-Dateien mit YAML-Frontmatter in bestimmten Verzeichnissen (
.claude/agents/)
agents-Parameter, der eine integriertere Entwicklungserfahrung für SDK-Anwendungen bietet.
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: Einresearch-assistant-Subagent kann Dutzende von Dateien und Dokumentationsseiten erkunden, ohne das Hauptgespräch mit all den Zwischensuchergebnissen zu überladen - er gibt nur die relevanten Erkenntnisse zurück.
Parallelisierung
Mehrere Subagenten können gleichzeitig laufen und komplexe Arbeitsabläufe dramatisch beschleunigen. Beispiel: Während einer Code-Überprüfung können Siestyle-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: Eindatabase-migration-Subagent kann detailliertes Wissen über SQL-Best-Practices, Rollback-Strategien und Datenintegritätsprüfungen haben, die unnötiges Rauschen in den Anweisungen des Hauptagenten wären.
Werkzeugbeschränkungen
Subagenten können auf bestimmte Werkzeuge beschränkt werden, wodurch das Risiko unbeabsichtigter Aktionen reduziert wird. Beispiel: Eindoc-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
Programmatische Definition (Empfohlen)
Definieren Sie Subagenten direkt in Ihrem Code mit demagents-Parameter:
AgentDefinition-Konfiguration
| Feld | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
description | string | Ja | Natürlichsprachige Beschreibung, wann dieser Agent verwendet werden soll |
prompt | string | Ja | Der Systemprompt des Agenten, der seine Rolle und sein Verhalten definiert |
tools | string[] | Nein | Array erlaubter Werkzeugnamen. Wenn weggelassen, erbt alle Werkzeuge |
model | 'sonnet' | 'opus' | 'haiku' | 'inherit' | Nein | Modellüberschreibung für diesen Agenten. Standardmäßig Hauptmodell, wenn weggelassen |
Dateisystembasierte Definition (Alternative)
Sie können Subagenten auch als Markdown-Dateien in bestimmten Verzeichnissen definieren:- Projektebene:
.claude/agents/*.md- Nur im aktuellen Projekt verfügbar - Benutzerebene:
~/.claude/agents/*.md- Projektübergreifend verfügbar
agents-Parameter) haben Vorrang vor dateisystembasierten Agenten mit demselben Namen.
Wie das SDK Subagenten verwendet
Bei der Verwendung des Claude Agent SDK können Subagenten programmatisch definiert oder aus dem Dateisystem geladen werden. Claude wird:- Programmatische Agenten laden aus dem
agents-Parameter in Ihren Optionen - Dateisystem-Agenten automatisch erkennen aus
.claude/agents/-Verzeichnissen (falls nicht überschrieben) - Sie automatisch aufrufen basierend auf Aufgabenabgleich und der
descriptiondes Agenten - Ihre spezialisierten Prompts verwenden und Werkzeugbeschränkungen
- Separaten Kontext beibehalten für jeden Subagenten-Aufruf
agents-Parameter) haben Vorrang vor dateisystembasierten Agenten mit demselben Namen.
Beispiel-Subagenten
Für umfassende Beispiele von Subagenten einschließlich Code-Reviewern, Test-Runnern, Debuggern und Sicherheitsprüfern siehe die Haupt-Subagenten-Anleitung. Die Anleitung 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 dasdescription-Feld Ihres Agenten klar angibt, wann er verwendet werden sollte:
Expliziter Aufruf
Benutzer können bestimmte Subagenten in ihren Prompts anfordern:Dynamische Agentenkonfiguration
Sie können Agenten dynamisch basierend auf den Bedürfnissen Ihrer Anwendung konfigurieren:Werkzeugbeschränkungen
Subagenten können über dastools-Feld eingeschränkten Werkzeugzugang haben:
- Feld weglassen - Agent erbt alle verfügbaren Werkzeuge (Standard)
- Werkzeuge spezifizieren - Agent kann nur aufgelistete Werkzeuge verwenden
Häufige Werkzeugkombinationen
Schreibgeschützte Agenten (Analyse, Überprüfung):Verwandte Dokumentation
- Haupt-Subagenten-Anleitung - Umfassende Subagenten-Dokumentation
- SDK-Überblick - Überblick über das Claude Agent SDK
- Einstellungen - Konfigurationsdatei-Referenz
- Slash-Befehle - Erstellung benutzerdefinierter Befehle