SpyBara
Go Premium

agent-sdk/subagents.md 2026-05-07 22:59 UTC to 2026-05-08 22:00 UTC

601 added, 0 removed.

2026
Sun 31 06:39 Sat 30 06:23 Fri 29 06:38 Thu 28 06:37 Wed 27 06:42 Tue 26 06:33 Sun 24 06:25 Sat 23 06:18 Fri 22 06:33 Thu 21 06:36 Wed 20 06:35 Tue 19 06:34 Mon 18 23:59 Sun 17 01:01 Fri 15 22:58 Thu 14 17:02 Wed 13 23:01 Tue 12 22:57 Mon 11 23:00 Sun 10 23:03 Sat 9 04:57 Fri 8 22:00 Thu 7 22:59 Tue 5 23:00 Mon 4 22:58 Sat 2 18:14 Fri 1 18:19

Subagenten im SDK

Definieren und rufen Sie Subagenten auf, um den Kontext zu isolieren, Aufgaben parallel auszuführen und spezialisierte Anweisungen in Ihren Claude Agent SDK-Anwendungen anzuwenden.

Subagenten sind separate Agent-Instanzen, die Ihr Haupt-Agent spawnen kann, um fokussierte Teilaufgaben zu bewältigen. Verwenden Sie Subagenten, um den Kontext für fokussierte Teilaufgaben 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 (TypeScript, Python)
  • 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 und beschleunigen komplexe Workflows dramatisch.

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

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

Programmatische Definition (empfohlen)

Definieren Sie Subagenten direkt in Ihrem Code mit dem Parameter agents. Dieses Beispiel erstellt zwei Subagenten: einen Code-Reviewer mit Nur-Lese-Zugriff und einen Test-Runner, der Befehle ausführen kann. Das Agent-Tool muss in allowedTools enthalten sein, da Claude Subagenten über das Agent-Tool aufruft.

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition


async def main():
async for message in query(
prompt="Review the authentication module for security issues",
options=ClaudeAgentOptions(
# Agent tool is required for subagent invocation
allowed_tools=["Read", "Grep", "Glob", "Agent"],
agents={
"code-reviewer": AgentDefinition(
# description tells Claude when to use this subagent
description="Expert code review specialist. Use for quality, security, and maintainability reviews.",
# prompt defines the subagent's behavior and expertise
prompt="""You are a code review specialist with expertise in security, performance, and best practices.

When reviewing code:
- Identify security vulnerabilities
- Check for performance issues
- Verify adherence to coding standards
- Suggest specific improvements

Be thorough but concise in your feedback.""",
# tools restricts what the subagent can do (read-only here)
tools=["Read", "Grep", "Glob"],
# model overrides the default model for this subagent
model="sonnet",
),
"test-runner": AgentDefinition(
description="Runs and analyzes test suites. Use for test execution and coverage analysis.",
prompt="""You are a test execution specialist. Run tests and provide clear analysis of results.

Focus on:
- Running test commands
- Analyzing test output
- Identifying failing tests
- Suggesting fixes for failures""",
# Bash access lets this subagent run test commands
tools=["Bash", "Read", "Grep"],
),
},
),
):
if hasattr(message, "result"):
print(message.result)


asyncio.run(main())

AgentDefinition-Konfiguration

Feld Typ Erforderlich Beschreibung
description string Ja Natürlichsprachige Beschreibung, wann dieser Agent verwendet werden soll
prompt string Ja Der System-Prompt des Agenten, der seine Rolle und sein Verhalten definiert
tools string[] Nein Array von zulässigen Tool-Namen. Falls weggelassen, erbt alle Tools
disallowedTools string[] Nein Array von Tool-Namen, die aus dem Tool-Set des Agenten entfernt werden sollen
model string Nein Modell-Override für diesen Agent. Akzeptiert einen Alias wie 'sonnet', 'opus', 'haiku', 'inherit' oder eine vollständige Modell-ID. Standardmäßig Haupt-Modell, falls weggelassen
skills string[] Nein Liste von Skill-Namen, die beim Start in den Kontext des Agenten vorgeladen werden sollen. Nicht aufgelistete Skills bleiben über das Skill-Tool aufrufbar
memory 'user' | 'project' | 'local' Nein Speicherquelle für diesen Agent
mcpServers (string | object)[] Nein MCP-Server, die diesem Agent zur Verfügung stehen, nach Name oder Inline-Konfiguration
maxTurns number Nein Maximale Anzahl von Agent-Turns, bevor der Agent stoppt
background boolean Nein Führen Sie diesen Agent als nicht-blockierende Hintergrund-Aufgabe aus, wenn er aufgerufen wird
effort 'low' | 'medium' | 'high' | 'xhigh' | 'max' | number Nein Reasoning-Effort-Level für diesen Agent
permissionMode PermissionMode Nein Berechtigungsmodus für die Tool-Ausführung innerhalb dieses Agenten

Im Python SDK verwenden diese Feldnamen camelCase, um das Wire-Format zu entsprechen. Siehe die AgentDefinition-Referenz für Details.

Dateisystem-basierte Definition (Alternative)

Sie können Subagenten auch als Markdown-Dateien in .claude/agents/-Verzeichnissen definieren. Siehe die Claude Code Subagenten-Dokumentation für Details zu diesem Ansatz. Programmatisch definierte Agenten haben Vorrang vor dateisystem-basierten Agenten mit demselben Namen.

Was Subagenten erben

Das Kontextfenster eines Subagenten startet frisch (keine übergeordnete Konversation), ist aber nicht leer. Der einzige Kanal vom übergeordneten Agent zum Subagenten ist der Prompt-String des Agent-Tools, daher fügen Sie alle Dateipfade, Fehlermeldungen oder Entscheidungen, die der Subagent benötigt, direkt in diesen Prompt ein.

Der Subagent erhält Der Subagent erhält nicht
Seinen eigenen System-Prompt (AgentDefinition.prompt) und den Prompt des Agent-Tools Die Konversationshistorie oder Tool-Ergebnisse des übergeordneten Agenten
Projekt CLAUDE.md (geladen über settingSources) Vorgeladener Skill-Inhalt, es sei denn, er ist in AgentDefinition.skills aufgelistet
Tool-Definitionen (geerbt vom übergeordneten Agent oder die Teilmenge in tools) Der System-Prompt des übergeordneten Agenten

Aufrufen von Subagenten

Automatischer Aufruf

Claude entscheidet automatisch, wann Subagenten basierend auf der Aufgabe und der description jedes Subagenten aufgerufen werden sollen. Wenn Sie beispielsweise einen performance-optimizer-Subagenten mit der Beschreibung „Performance-Optimierungsspezialist für Query-Tuning" definieren, wird Claude ihn aufrufen, wenn Ihr Prompt die Optimierung von Queries erwähnt.

Schreiben Sie klare, spezifische Beschreibungen, damit Claude Aufgaben dem richtigen Subagenten zuordnen kann.

Expliziter Aufruf

Um sicherzustellen, dass Claude einen bestimmten Subagenten verwendet, erwähnen Sie ihn nach Name in Ihrem Prompt:

"Use the code-reviewer agent to check the authentication module"

Dies umgeht das automatische Matching und ruft den benannten Subagenten direkt auf.

Dynamische Agent-Konfiguration

Sie können Agent-Definitionen dynamisch basierend auf Laufzeitbedingungen erstellen. Dieses Beispiel erstellt einen Security-Reviewer mit verschiedenen Strenge-Leveln und verwendet ein leistungsfähigeres Modell für strenge Überprüfungen.

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition


# Factory function that returns an AgentDefinition
# This pattern lets you customize agents based on runtime conditions
def create_security_agent(security_level: str) -> AgentDefinition:
is_strict = security_level == "strict"
return AgentDefinition(
description="Security code reviewer",
# Customize the prompt based on strictness level
prompt=f"You are a {'strict' if is_strict else 'balanced'} security reviewer...",
tools=["Read", "Grep", "Glob"],
# Key insight: use a more capable model for high-stakes reviews
model="opus" if is_strict else "sonnet",
)


async def main():
# The agent is created at query time, so each request can use different settings
async for message in query(
prompt="Review this PR for security issues",
options=ClaudeAgentOptions(
allowed_tools=["Read", "Grep", "Glob", "Agent"],
agents={
# Call the factory with your desired configuration
"security-reviewer": create_security_agent("strict")
},
),
):
if hasattr(message, "result"):
print(message.result)


asyncio.run(main())

Erkennen von Subagenten-Aufrufen

Subagenten werden über das Agent-Tool aufgerufen. Um zu erkennen, wann ein Subagent aufgerufen wird, suchen Sie nach tool_use-Blöcken, bei denen name "Agent" ist. Nachrichten aus dem Kontext eines Subagenten enthalten ein Feld parent_tool_use_id.

Dieses Beispiel durchläuft gestreamte Nachrichten und protokolliert, wenn ein Subagent aufgerufen wird und wenn nachfolgende Nachrichten aus dem Ausführungskontext dieses Subagenten stammen.

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition


async def main():
async for message in query(
prompt="Use the code-reviewer agent to review this codebase",
options=ClaudeAgentOptions(
allowed_tools=["Read", "Glob", "Grep", "Agent"],
agents={
"code-reviewer": AgentDefinition(
description="Expert code reviewer.",
prompt="Analyze code quality and suggest improvements.",
tools=["Read", "Glob", "Grep"],
)
},
),
):
# Check for subagent invocation. Match both names: older SDK
# versions emitted "Task", current versions emit "Agent".
if hasattr(message, "content") and message.content:
for block in message.content:
if getattr(block, "type", None) == "tool_use" and block.name in (
"Task",
"Agent",
):
print(f"Subagent invoked: {block.input.get('subagent_type')}")

# Check if this message is from within a subagent's context
if hasattr(message, "parent_tool_use_id") and message.parent_tool_use_id:
print("  (running inside subagent)")

if hasattr(message, "result"):
print(message.result)


asyncio.run(main())

Fortsetzen von Subagenten

Subagenten können fortgesetzt werden, um dort fortzufahren, wo sie aufgehört haben. Fortgesetzte Subagenten behalten ihre vollständige Konversationshistorie, einschließlich aller vorherigen Tool-Aufrufe, Ergebnisse und Reasoning. Der Subagent setzt genau dort an, wo er gestoppt hat, anstatt von vorne zu beginnen.

Wenn ein Subagent abgeschlossen ist, erhält Claude seine Agent-ID im Agent-Tool-Ergebnis. Um einen Subagenten programmatisch fortzusetzen:

  1. Erfassen Sie die Session-ID: Extrahieren Sie session_id aus Nachrichten während der ersten Abfrage
  2. Extrahieren Sie die Agent-ID: Analysieren Sie agentId aus dem Nachrichteninhalt
  3. Setzen Sie die Session fort: Übergeben Sie resume: sessionId in den Optionen der zweiten Abfrage und fügen Sie die Agent-ID in Ihren Prompt ein

Das folgende Beispiel demonstriert diesen Ablauf: Die erste Abfrage führt einen Subagenten aus und erfasst die Session-ID und Agent-ID, dann setzt die zweite Abfrage die Session fort, um eine Folgefrage zu stellen, die Kontext aus der ersten Analyse erfordert.

import { query, type SDKMessage } from "@anthropic-ai/claude-agent-sdk";

// Helper to extract agentId from message content
// Stringify to avoid traversing different block types (TextBlock, ToolResultBlock, etc.)
function extractAgentId(message: SDKMessage): string | undefined {
if (!("message" in message)) return undefined;
// Stringify the content so we can search it without traversing nested blocks
const content = JSON.stringify(message.message.content);
const match = content.match(/agentId:\s*([a-f0-9-]+)/);
return match?.[1];
}

let agentId: string | undefined;
let sessionId: string | undefined;

// First invocation - use the Explore agent to find API endpoints
for await (const message of query({
prompt: "Use the Explore agent to find all API endpoints in this codebase",
options: { allowedTools: ["Read", "Grep", "Glob", "Agent"] }
})) {
// Capture session_id from ResultMessage (needed to resume this session)
if ("session_id" in message) sessionId = message.session_id;
// Search message content for the agentId (appears in Agent tool results)
const extractedId = extractAgentId(message);
if (extractedId) agentId = extractedId;
// Print the final result
if ("result" in message) console.log(message.result);
}

// Second invocation - resume and ask follow-up
if (agentId && sessionId) {
for await (const message of query({
prompt: `Resume agent ${agentId} and list the top 3 most complex endpoints`,
options: { allowedTools: ["Read", "Grep", "Glob", "Agent"], resume: sessionId }
})) {
if ("result" in message) console.log(message.result);
}
}

Subagenten-Transkripte bleiben unabhängig von der Hauptkonversation bestehen:

  • Hauptkonversations-Komprimierung: Wenn die Hauptkonversation komprimiert wird, sind Subagenten-Transkripte nicht betroffen. Sie werden in separaten Dateien gespeichert.
  • Session-Persistenz: Subagenten-Transkripte bleiben innerhalb ihrer Session bestehen. Sie können einen Subagenten nach dem Neustart von Claude Code fortsetzen, indem Sie dieselbe Session fortsetzen.
  • Automatische Bereinigung: Transkripte werden basierend auf der Einstellung cleanupPeriodDays bereinigt (Standard: 30 Tage).

Tool-Einschränkungen

Subagenten können über das Feld tools eingeschränkten Tool-Zugriff haben:

  • Feld weglassen: Agent erbt alle verfügbaren Tools (Standard)
  • Tools angeben: Agent kann nur aufgelistete Tools verwenden

Dieses Beispiel erstellt einen schreibgeschützten Analyse-Agent, der Code untersuchen, aber keine Dateien ändern oder Befehle ausführen kann.

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition


async def main():
async for message in query(
prompt="Analyze the architecture of this codebase",
options=ClaudeAgentOptions(
allowed_tools=["Read", "Grep", "Glob", "Agent"],
agents={
"code-analyzer": AgentDefinition(
description="Static code analysis and architecture review",
prompt="""You are a code architecture analyst. Analyze code structure,
identify patterns, and suggest improvements without making changes.""",
# Read-only tools: no Edit, Write, or Bash access
tools=["Read", "Grep", "Glob"],
)
},
),
):
if hasattr(message, "result"):
print(message.result)


asyncio.run(main())

Häufige Tool-Kombinationen

Anwendungsfall Tools Beschreibung
Schreibgeschützte Analyse Read, Grep, Glob Kann Code untersuchen, aber nicht ändern oder ausführen
Test-Ausführung Bash, Read, Grep Kann Befehle ausführen und Ausgabe analysieren
Code-Änderung Read, Edit, Write, Grep, Glob Vollständiger Lese-/Schreibzugriff ohne Befehlsausführung
Vollständiger Zugriff Alle Tools Erbt alle Tools vom übergeordneten Agent (Feld tools weglassen)

Fehlerbehebung

Claude delegiert nicht an Subagenten

Wenn Claude Aufgaben direkt abschließt, anstatt an Ihren Subagenten zu delegieren:

  1. Fügen Sie das Agent-Tool ein: Subagenten werden über das Agent-Tool aufgerufen, daher muss es in allowedTools enthalten sein
  2. Verwenden Sie explizites Prompting: Erwähnen Sie den Subagenten nach Name in Ihrem Prompt (zum Beispiel „Verwenden Sie den Code-Reviewer-Agent, um...")
  3. Schreiben Sie eine klare Beschreibung: Erklären Sie genau, wann der Subagent verwendet werden sollte, damit Claude Aufgaben angemessen zuordnen kann

Dateisystem-basierte Agenten werden nicht geladen

Agenten, die in .claude/agents/ definiert sind, werden nur beim Start geladen. Wenn Sie eine neue Agent-Datei erstellen, während Claude Code läuft, starten Sie die Session neu, um sie zu laden.

Windows: Fehler bei langen Prompts

Unter Windows können Subagenten mit sehr langen Prompts aufgrund von Befehlszeilenlängenbeschränkungen (8191 Zeichen) fehlschlagen. Halten Sie Prompts prägnant oder verwenden Sie dateisystem-basierte Agenten für komplexe Anweisungen.

Verwandte Dokumentation