SpyBara
Go Premium

agent-sdk/subagents.md 2026-06-16 21:57 UTC to 2026-06-17 17:02 UTC

87 added, 75 removed.

2026
Tue 23 22:00 Mon 22 23:59 Fri 19 22:58 Thu 18 22:00 Wed 17 17:02 Tue 16 21:57 Mon 15 23:02 Sat 13 21:59 Fri 12 22:00 Thu 11 23:01 Wed 10 23:57 Tue 9 06:34 Mon 8 06:52 Sat 6 06:24 Fri 5 06:45 Thu 4 06:52 Wed 3 06:53 Tue 2 06:51

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, 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. Dieses Beispiel erstellt zwei Subagenten: einen Code-Reviewer mit Nur-Lese-Zugriff und einen Test-Runner, der Befehle ausführen kann. 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.

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(
# Auto-approve these tools, including Agent 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. MCP-Server-Level-Muster werden ebenfalls akzeptiert: mcp__server oder mcp__server__* entfernt jedes Tool von diesem Server, und mcp__* entfernt jedes MCP-Tool von jedem Server
model string Nein Modell-Override für diesen Agent. Akzeptiert einen Alias wie 'fable', 'opus', 'sonnet', '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
initialPrompt string Nein Wird automatisch als erster Benutzer-Turn eingereicht, wenn dieser Agent als Haupt-Thread-Agent ausgeführt wird. Wird ignoriert, wenn der Agent als Subagent aufgerufen wird
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.

Die Nachrichtenstruktur unterscheidet sich zwischen SDKs. In Python werden Inhaltsblöcke direkt über message.content aufgerufen. In TypeScript umhüllt SDKAssistantMessage die Claude API-Nachricht, daher wird auf den Inhalt über message.message.content zugegriffen.

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, ToolUseBlock


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 isinstance(block, ToolUseBlock) 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, enthält das Agent-Tool-Ergebnis einen Textblock mit agentId: <id>. Die integrierten Explore- und Plan-Agenten sind einmalig und geben keine agentId zurück, daher verwenden Sie einen benutzerdefinierten Agent oder general-purpose, wenn Sie fortsetzen müssen. 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 Agent-Tool-Ergebnis-Text
  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 definiert einen benutzerdefinierten endpoint-finder-Agent. Die erste Abfrage führt ihn aus und erfasst die Session-ID und Agent-ID aus dem Agent-Tool-Ergebnis, dann setzt die zweite Abfrage die Session fort, um eine Folgefrage zu stellen, die Kontext aus der ersten Analyse erfordert.

import asyncio
import re
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition, ToolResultBlock

AGENTS = {
"endpoint-finder": AgentDefinition(
description="Locates and catalogs API endpoints in a codebase.",
prompt="You find and document API endpoints. Report each endpoint's path, method, and handler.",
tools=["Read", "Grep", "Glob"],
)
}


def extract_agent_id(block: ToolResultBlock) -> str | None:
"""Extract agentId from an Agent tool result's text content."""
parts = block.content if isinstance(block.content, list) else [{"text": block.content}]
for part in parts:
if match := re.search(r"agentId:\s*([\w-]+)", part.get("text") or ""):
return match.group(1)
return None


async def main():
agent_id = None
session_id = None

# First invocation - run the endpoint-finder subagent
async for message in query(
prompt="Use the endpoint-finder agent to find all API endpoints in this codebase",
options=ClaudeAgentOptions(allowed_tools=["Read", "Grep", "Glob", "Agent"], agents=AGENTS),
):
# Capture session_id from ResultMessage (needed to resume this session)
if hasattr(message, "session_id"):
session_id = message.session_id
# Search tool results for the agentId trailer
for block in getattr(message, "content", None) or []:
if isinstance(block, ToolResultBlock):
agent_id = extract_agent_id(block) or agent_id
# Print the final result
if hasattr(message, "result"):
print(message.result)

# Second invocation - resume and ask follow-up
if agent_id and session_id:
async for message in query(
prompt=f"Resume agent {agent_id} and list the top 3 most complex endpoints",
options=ClaudeAgentOptions(
allowed_tools=["Read", "Grep", "Glob", "Agent"], agents=AGENTS, resume=session_id
),
):
if hasattr(message, "result"):
print(message.result)


asyncio.run(main())

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)

Skalierung mit dynamischen Workflows

Subagenten funktionieren gut für einige delegierte Aufgaben pro Turn. Für Läufe, die Dutzende bis Hunderte von Agenten koordinieren, verwenden Sie das Workflow-Tool, das die Orchestrierung in ein Skript verlagert, das die Laufzeit außerhalb des Konversationskontexts ausführt. Siehe dynamische Workflows für die Unterschiede zwischen Workflows und Turn-für-Turn-Subagenten-Delegation.

Das Workflow-Tool ist im TypeScript Agent SDK v0.3.149 und später verfügbar. Fügen Sie Workflow in allowedTools ein, um Workflow-Läufe automatisch zu genehmigen. Die Tool-Input- und Output-Schemas sind in der TypeScript-Referenz aufgelistet.

Fehlerbehebung

Claude delegiert nicht an Subagenten

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

  1. Überprüfen Sie, dass Agent-Aufrufe genehmigt sind: Fügen Sie Agent in allowedTools ein, um Subagenten-Aufrufe automatisch zu genehmigen. Ohne diese Einstellung fallen Agent-Aufrufe auf Ihren canUseTool-Callback zurück oder werden im dontAsk-Modus abgelehnt
  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.

  • Claude Code Subagenten: umfassende Subagenten-Dokumentation einschließlich dateisystem-basierter Definitionen
  • Dynamische Workflows: Orchestrieren Sie viele Subagenten aus einem Skript für Jobs, die zu groß für eine Konversation sind
  • SDK-Übersicht: Erste Schritte mit dem Claude Agent SDK