Subagenten sind eine der nützlichsten Ergänzungen des Claude Code / Claude Agent-Ökosystems: Sie ermöglichen die Aufteilung komplexer Workflows in kleinere, spezialisierte KI-Teammitglieder, die Wahrung des Haupt-Thread-Kontexts und die sichere Einschränkung des Tool-Zugriffs. Dieser Artikel erklärt was Unteragenten sind, wie man sie erstellt und aufruft (CLI, Dateisystem und SDK), die Design-Prinzipien Sie sollten beim Bauen folgen, und konkreter Beispielcode Sie können kopieren und anpassen.
Was sind Unteragenten?
A Unteragent ist ein vorkonfigurierter KI-Assistent mit begrenztem Funktionsumfang, an den Claude Code (oder das Claude Agent SDK) Aufgaben delegieren kann. Jeder Subagent:
- Hat einen eindeutigen Namen und eine klare Zweckbeschreibung.
- Läuft in seinem eigenes Kontextfenster getrennt vom Hauptgespräch (damit lange Detailketten den Kontext des Orchestrators nicht verunreinigen).
- Kann mit einer begrenzten Anzahl von Werkzeuge (Datei lesen/schreiben, Bash, Grep, MCP-Tools usw.) und mit einer bestimmten Modellauswahl.
- Enthält eine Systemaufforderung (die Persönlichkeit und Anweisungen des Subagenten), die das Verhalten und die Einschränkungen steuert.
Aufgrund dieser Eigenschaften eignen sich Subagenten ideal für Aufgaben, die viele Token erfordern (Recherche, Durchsuchen großer Protokolle), sicherheitsrelevant sind (Scannen oder potenziell zerstörerische Tools) oder sich wiederholen und genau spezifiziert sind (Stilprüfung, Testausführung).
Anthropic hat schnell iteriert: Die Claude Code CLI und das Agent SDK wurden überarbeitet und erweitert in die Claude Agent SDK, Plugin-Unterstützung wurde für Bündelagenten und zugehörige Anpassungen (Schrägstrichbefehle, MCP-Server, Hooks) eingeführt, und Besondere Qualifikationen bieten eine Möglichkeit, Domänen-Workflows für die Wiederverwendung in Claude.ai, Claude Code und dem Agent SDK zu bündeln. Diese Updates erleichtern es Teilen, Installieren und Versionieren Subagenten über Teams und Projekte hinweg. Wenn Sie Produktionsworkflows erstellen möchten, sollten Sie die Plugin-/Skill-Paketierung und die SDK-basierten Bereitstellungsmuster evaluieren.
Warum Unteragenten wichtig sind
Drei Gründe, warum sie sofort nützlich sind:
- Kontexterhaltung — Lange oder störungsintensive Suchvorgänge, Testläufe oder Scans werden in einem Subagenten ausgeführt, anstatt den primären Kontext zu überlasten. Dies reduziert die Token-Verschwendung und erleichtert die Analyse der Ergebnisse.
- Spezialisiertes Fachwissen — Sie können Domänenwissen und Verhalten in einer auf die Aufgabe zugeschnittenen Systemeingabe kodieren (z. B. ein
security-auditordas sich auf Geheimnisse, Abhängigkeitsprobleme und unsichere Shell-Nutzung konzentriert). - Sicherere Berechtigungen — Die Begrenzung der Tools pro Subagent reduziert den Explosionsradius (ein Dokumentprüfer verfügt möglicherweise über schreibgeschützte Tools; ein Test-Runner hat
Bashaber neinEdit). - Parallelisierung: Sie können mehrere Subagenten gleichzeitig ausführen (zum Beispiel:
style-checker,security-scanner,test-runner) und sammeln Sie dann ihre kurzen Ergebnisse – ein großer Gewinn für teure, unabhängige Kontrollen.
Voraussetzungen für die Verwendung von Subagenten in Claude Code
Bevor Sie mit dem Erstellen von Subagenten beginnen, stellen Sie sicher, dass Folgendes vorhanden ist:
1) Claude Code installiert und authentifiziert
Installieren Sie die Claude Code CLI oder verwenden Sie die Web-/IDE-Integrationen. Schnellstart- und Setup-Dokumente von CometAPI Listen Sie unterstützte Installationsmethoden auf (npm-Globalpaket oder native Installationsprogramme) und zeigen Sie, wie Sie Ihre Installation mit überprüfen claude --version / claude doctor. Du brauchst auch ein CometAPI Konto (Die Verwendung des CometAPI-Schlüssels für den Zugriff auf den Claude-Code ist günstiger und bequemer als das offizielle Modell.), wie im Quickstart angegeben.
2) Knoten / Umgebung (für einige Installationspfade) und grundlegende Shell-Tools
Wenn Sie über das npm-Paket installieren, benötigen Sie Node.js (Node 18+ ist in Beispielen üblich). Wenn Sie das Agent SDK (JavaScript/TypeScript oder Python) verwenden möchten, benötigen Sie ein Projekt mit der installierten SDK-Abhängigkeit. Viele Tutorials setzen Standard-Entwicklertools (Git, Bash, optional) voraus. gh CLI für GitHub-Workflows).
3) Projektlayout & CLAUDE.md
Die beste Vorgehensweise besteht darin, Hilfsdokumente auf Repo-Ebene (CLAUDE.md) und um projektbezogene Agenten in .claude/agents/ Teammitglieder erben sie also. CLAUDE.md-Dateien werden automatisch in Claudes Kontext eingefügt und helfen, das Verhalten über Sitzungen hinweg konsistent zu steuern. Jeder Subagent ist eine Markdown-Datei mit YAML-Frontmatter. Minimales Beispiel:
---
name: code-reviewer
description: Expert code review specialist. Use PROACTIVELY after code changes to check security, style, and maintainability.
tools: Read, Grep, Glob, Bash
model: inherit
---
You are a senior code reviewer. When invoked:
1. Run `git diff` to identify modified files.
2. Focus review on changed code paths.
3. List security issues, probable false positives, and suggested fixes.
4. Provide a short, prioritized action list.
Return results in JSON with fields: summary, issues.
nameist ein Bezeichner in Kleinbuchstaben.descriptionleitet den automatischen Aufruf und Abgleich.toolsschränkt den Toolzugriff ein (um alles zu übernehmen, weglassen).modelkann seinsonnet,opus,haikuoderinherit.
4) Berechtigungen und MCP-Server (optional, aber üblich)
Wenn Ihre Workflows Model Context Protocol (MCP)-Server oder externe Tools (Puppeteer, Sentry, benutzerdefinierte REST-Tools) verwenden, stellen Sie sicher, dass Ihre MCP-Server konfiguriert und erreichbar sind. Bei sensiblen Vorgängen (Schreiben, Bash, Git-Commit) sollten Sie die Whitelist und die pro Agent festgelegten Einstellungen sorgfältig auswählen. tools Umfang.
So erstellen Sie Subagenten in Claude Code
Sie können Subagenten auf drei Arten erstellen: über die interaktive CLI (/agents), als Dateisystem-Markdown-Dateien oder programmgesteuert über das Agent SDK. Nachfolgend finden Sie die schrittweisen Optionen:
Claude Code unterstützt drei praktische Möglichkeiten zum Erstellen von Subagenten:
- Interaktive CLI
/agentsUI – am schnellsten für die iterative Erstellung innerhalb einer Sitzung. - Dateisystembasiert — Erstellen Sie Markdown-Dateien mit YAML-Frontmatter in
.claude/agents/(Projektebene) oder~/.claude/agents/(Benutzerebene). Projektagenten haben eine höhere Priorität. - Programmgesteuert (Agent SDK) — Definieren Sie Subagenten im Code über die
agentsParameter beim Aufrufquery(); empfohlen für SDK-gesteuerte Apps. Dieser Ansatz ist ideal, wenn Subagenten dynamisch erstellt oder in eine Anwendung eingebettet werden müssen.
Schneller interaktiver Ablauf (empfohlener erster Schritt)
- Starten Sie Claude Code in Ihrem Terminal oder öffnen Sie die Befehlspalette in VS Code.
- Führen Sie die Subagentenschnittstelle mit dem Schrägstrichbefehl aus:
/agents
- Wählen Neuen Agenten erstellen, wählen Sie den Umfang auf Projekt- oder Benutzerebene, geben Sie Name/Beschreibung/Tools/Systemeingabe ein und speichern Sie. Sie können mit Claude einen Entwurf erstellen und diesen anschließend verfeinern. Nach dem Speichern ist der Agent verfügbar in
/agentsund kann explizit oder automatisch aufgerufen werden.
Dateisystembasierte Subagenten (Markdown + YAML-Frontmatter)
Subagenten werden als Markdown-Dateien mit YAML-Frontmatter gespeichert. Platzieren Sie sie in:
- Projektumfang:
.claude/agents/*.md(höchste Priorität) - Benutzerbereich:
~/.claude/agents/*.md
Grundlegende Dateistruktur:
---
name: code-reviewer
description: "Review recent code changes for security and style."
tools: Read, Grep, Glob, Bash # optional; omit to inherit
model: sonnet # optional; or 'inherit'
---
You are a senior code reviewer with expertise in security, performance, and best practices.
When reviewing:
- Identify security vulnerabilities
- Prioritize clarity and maintainability
- Always provide concise examples and suggested fixes
- If unsure, ask for the minimal reproducible snippet
Einige Hinweise zur Implementierung:
namemuss in Kleinbuchstaben mit Bindestrichen geschrieben werden.- Weglassen
toolsermöglicht dem Subagenten, alle Tools des Hauptthreads zu erben. Durch die explizite Auflistung der Tools wird ein Modell mit geringsten Berechtigungen erzwungen. - Nutzen Sie
model: 'inherit'für konsistentes Verhalten mit dem Hauptthread oder geben Sie einen Modellalias an (z. B.sonnet,opus,haiku).
CLI-JSON-Definition (Ad-hoc-/Sitzungsnutzung)
Sie können beim Starten einer Sitzung temporäre Subagenten inline definieren:
claude --agents '{
"code-reviewer": {
"description": "Expert code reviewer.",
"prompt": "You are a senior code reviewer. Focus on security and best practices.",
"tools": ,
"model": "sonnet"
}
}'
CLI-definierte Agenten sind für Skriptläufe oder Experimente nützlich. Sie haben eine niedrigere Priorität als Projektagenten, aber eine höhere als Benutzeragenten.
Programmatische Definition (Agent SDK – empfohlen für Apps)
Wenn Sie eine Anwendung oder Automatisierung erstellen, definieren Sie Subagenten programmgesteuert über die Agent SDKs agents Parameter (dies ist die am besten integrierte Option). Beispiel (TypeScript):
import { query } from '@anthropic-ai/claude-agent-sdk';
async function runReview() {
const result = await query({
prompt: "Assess the authentication module for security issues",
options: {
agents: {
"code-reviewer": {
description: "Expert code review specialist",
prompt: `You are a code review specialist...`,
tools: ,
model: "sonnet"
},
"test-runner": {
description: "Runs the test suite and analyzes failures",
prompt: `You run tests and summarize failures...`,
tools: ,
model: "sonnet"
}
}
}
});
console.log(result);
}
Das SDK akzeptiert auch dateisystembasierte Agenten (es lädt .claude/agents/ Dateien), wenn Sie dieses Muster bevorzugen. Programmatische Agenten sind leistungsstark für dynamische Workflows und CI-Integration.
Für Python ist die claude-agent-sdk Paket unterstützt ähnliche Muster: Sie können verwenden query() or ClaudeSDKClient und konfigurieren Sie Optionen, Tools und MCP-Server programmgesteuert. Schnellstartbeispiele finden Sie im Python SDK-Repository.
So rufen Sie Subagenten auf
Automatische Delegierung
Claude Code kann Im Prinzip so, wie Sie es von Google Maps kennen. Wählen Sie einen Subagenten aus, wenn eine Benutzereingabe dem Zweck des Subagenten entspricht. Dies ist nützlich für die Hintergrundorchestrierung, bei der der Hauptagent Aufgaben automatisch an den richtigen Spezialisten weiterleitet. Verlassen Sie sich auf klare Subagentenbeschreibungen und zielgerichtete Systemeingaben, um die Genauigkeit der automatischen Auswahl zu verbessern.
Explizite Aufrufung (aus Gründen der Übersichtlichkeit empfohlen)
Sie können einen Agenten im Gespräch explizit aufrufen:
> Use the code-reviewer subagent to check my recent changes
Der explizite Aufruf ist deterministisch und wird für Produktionsabläufe empfohlen, bei denen Sie eine unerwartete Delegierung vermeiden möchten.
SDK-Orchestratormuster
Gängige Muster in SDK-Apps:
- Gabel + sammeln: Starten Sie mehrere Unteragenten parallel, sammeln Sie die präzise Antwort jedes Agenten und fassen Sie die Ergebnisse dann im Hauptagenten zusammen bzw. führen Sie sie zusammen.
- Supervisor-Schleife: Der Orchestrator weist Unteragenten Aufgaben zu, überprüft die Ergebnisse und akzeptiert sie entweder oder fordert eine Neuberechnung/Klärung an.
- Sandbox-Ausführung: Geben Sie einem stark eingeschränkten Agenten potenziell gefährliche Funktionen (Bereitstellen, Ausführen von Skripten) und verlangen Sie vor der Ausführung explizite menschliche Genehmigungs-Hooks.
Diese Muster lassen sich mithilfe der Sitzungsverwaltung, Hooks und MCP-Tools des Agent SDK auf praktische Implementierungen abbilden.
So erstellen Sie nützliche, sichere und zusammensetzbare Subagenten
1) Einzelverantwortung und klare Vorgaben
Jeder Subagent sollte einen klaren Zweck und eine Systemaufforderung haben, die Grenzen, Erfolgskriterien und Ausgabeformat angibt. Wenn die gewünschte Ausgabe strukturiert ist (JSON, Aufzählungsliste, Code-Patch), weisen Sie den Subagenten präzise an, um Analysefehler zu reduzieren.
2) Geringste Privilegien für Tools
Gewähren Sie nur die Tools, die ein Subagent benötigt. Beispielsweise benötigt ein Dokumentprüfer nicht Write or Bash. Verwenden Sie nach Möglichkeit standardmäßig nur Lesezugriff und erhöhen Sie die Tool-Berechtigungen bei Bedarf explizit. Dies reduziert das Risiko und vereinfacht die Prüfung.
3) Geben Sie kompakte, strukturierte Ergebnisse zurück
Unteragenten sollten zurückkehren prägnante, abschließende Antworten anstelle von langwierigen Gedankenketten. Ein gängiges Muster ist: Führen Sie umfangreiche Arbeiten im Kontext des Subagenten aus und geben Sie dann eine kurze Zusammenfassung mit Anhängen (Patches, Dateireferenzen, JSON) zurück. Dies maximiert die Kontexteffizienz für den Orchestrator.
4) Testbarkeit und Versionierung
Speichern Sie Subagent-Dateien in der Versionskontrolle, erstellen Sie CI-Tests, die echte Läufe mit kleinen Eingaben durchführen, und fixieren Sie Modelle/Toolsets. Wenn Sie auf Skills und Plugins angewiesen sind, übernehmen Sie die Plugin-Marktplatz-/Versionierungsmuster, um Upgrades und Rollbacks zu verwalten.
5) Audit-Hooks und Human-in-the-Loop-Checkpoints
Verwenden Sie SDK-Hooks, um Tool-Aufrufe abzufangen (PreToolUse-Hooks) und die menschliche Zustimmung für destruktive Aktionen einzuholen. Protokollieren Sie alle Tool-Aufrufe für wiederholbare Audits. Das SDK bietet Hook- und Berechtigungsmechanismen zur Unterstützung dieses Musters.
Anwendungsbeispiel – eine kleine, produktionsähnliche Pipeline
Nachfolgend sehen Sie ein kompaktes Beispiel, das die typischen Teile zeigt: einen Dateisystem-Agenten, einen SDK-Aufruf, der zwei Agenten verwendet (einen zur Überprüfung, einen für Tests) und eine einfache Orchestrierung.
1) Dateisystem-Agent: .claude/agents/code-reviewer.md
---
name: code-reviewer
description: Use PROACTIVELY after code changes. Perform security, style, and maintainability review on modified files.
tools: Read, Grep, Glob
model: inherit
---
You are a meticulous senior code reviewer. When invoked:
1. Run `git diff --name-only` to find modified files.
2. For each modified file, read and look for security issues, suspicious patterns, or maintainability problems.
3. Return JSON:
{
"summary": "one-line summary",
"issues": ,
"recommended_changes":
}
2) Programmatische Orchestrierung (Node.js)
import { query } from '@anthropic-ai/claude-agent-sdk';
import fs from 'fs';
async function runPipeline() {
const result = query({
prompt: 'Run PR checks: security review then unit tests.',
options: {
agents: {
'code-reviewer': {
description: 'Use PROACTIVELY after code changes; output JSON with issues.',
prompt: fs.readFileSync('./.claude/agents/code-reviewer.md', 'utf8'),
tools: ,
model: 'sonnet'
},
'test-runner': {
description: 'Run test suite and summarize failing tests.',
prompt: `You are a test-runner. Execute tests and return JSON { summary, failing_tests[] }`,
tools:
}
}
}
});
for await (const message of result) {
// Implement streaming logic: messages may include subagent outputs
console.log(message);
}
}
runPipeline().catch(console.error);
Anmerkungen: die code-reviewer wird im Repo zur Wiederverwendung durch das Team gespeichert; der SDK-Aufruf zeigt, dass programmatische Agenten Vorrang haben und die tools Durch die Bereichsbestimmung werden versehentliche Schreibvorgänge verhindert.
Fortgeschrittene Themen und Muster
Dynamische Agentenkonfiguration
Erstellen Sie parametrisierte Agentenfabriken, die Modelle und Toolsets je nach Umgebung (Entwicklung vs. Produktion) oder Schweregrad (z. B. strict vs balanced Sicherheitsmodi). Die SDK-Beispiele zeigen, wie Agentendefinitionen zur Laufzeit generiert werden.
Parallelisierung
Führen Sie mehrere schreibgeschützte Analyse-Agenten parallel aus (Stil, Sicherheit, Testabdeckung) und aggregieren Sie deren JSON-Ausgaben im Hauptthread. Dies reduziert die Bearbeitungszeit für große Repos erheblich.
Vom Plugin bereitgestellte Agenten
Plugins können Subagenten bereitstellen, die mit dem Plugin-Manifest gepackt sind. Sie erscheinen in /agents neben benutzerdefinierten Agenten und kann explizit aufgerufen werden. Verwenden Sie dies, um standardisierte Agenten auf Teams zu verteilen.
Wo Claude Code CLI am meisten empfohlen wird
Wir freuen uns, bekannt geben zu können, dass CometAPI jetzt die leistungsstarke Claude Code-CLI vollständig unterstützt. Sie müssen nur Claude Code installieren und sich mit dem erhaltenen Comet-API-Schlüssel und der Basisadresse authentifizieren, um das Comet-API-Modell auf Claude Code zu verwenden.
Warum sollte man Claude-Code über CometAPI verwenden?
Top-Funktionen der künstlichen Intelligenz: Einfaches Generieren, Debuggen und Optimieren von Code mithilfe von Modellen, die speziell für Entwickler erstellt wurden.
- Flexible Modellauswahl: Unser umfassendes Modellangebot ermöglicht Ihnen eine nahtlosere Entwicklung.
- Nahtlose Integration: APIs sind immer verfügbar. Integrieren Sie Claude Code in wenigen Minuten direkt in Ihren bestehenden Workflow.
- Die Verwendung von Claude Code über CometAPI spart weitere Kosten. Die von CometAPI bereitgestellte Claude-API ist 20 % günstiger als der offizielle Preis und wird vom offiziellen Anbieter mit dem neuesten Modell aktualisiert.
Bereit, Claude Code CLI zu verwenden? Konsultieren Sie die API-Leitfaden für detaillierte Anweisungen.
Wenn Sie weitere Tipps, Anleitungen und Neuigkeiten zu KI erfahren möchten, folgen Sie uns auf VK, X kombiniert mit einem nachhaltigen Materialprofil. Discord!
Siehe auch Wie installiere und führe ich Claude Code über CometAPI aus?
Abschließende Gedanken
Behandeln Sie Unteragenten als wiederverwendbare, versionierte Mikro-Personas. Fangen Sie klein an: Machen Sie doc-reviewer und einem test-runner für ein Repo, checken Sie sie ein .claude/agents/und automatisieren Sie sie in CI mit Headless claude -p. Iterieren Sie Ihre Eingabeaufforderungen, fügen Sie strukturierte Ausgaben hinzu und verschärfen Sie die Toolberechtigungen.
Das hilfreichste mentale Modell: Stellen Sie sich Claude als Projektmanager und die Subagenten als Spezialisten im Team vor. Der Manager delegiert klar formulierte Aufgaben, fasst die Ergebnisse der Spezialisten zusammen und schreibt den Abschlussbericht. Mit der Zeit werden Sie Verbesserungen bei Zuverlässigkeit, Testbarkeit und der Möglichkeit feststellen, große Teile der Entwickler-Workflows zu automatisieren.