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
Sat 27 01:01 Fri 26 23:00 Thu 25 23:58 Wed 24 22:02 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

Subagents dalam SDK

Tentukan dan panggil subagents untuk mengisolasi konteks, menjalankan tugas secara paralel, dan menerapkan instruksi khusus dalam aplikasi Claude Agent SDK Anda.

Subagents adalah instans agen terpisah yang dapat dihasilkan oleh agen utama Anda untuk menangani subtask yang terfokus. Gunakan subagents untuk mengisolasi konteks bagi subtask yang terfokus, menjalankan beberapa analisis secara paralel, dan menerapkan instruksi khusus tanpa membuat prompt agen utama menjadi terlalu panjang.

Panduan ini menjelaskan cara mendefinisikan dan menggunakan subagents dalam SDK menggunakan parameter agents.

Ikhtisar

Anda dapat membuat subagents dengan tiga cara:

  • Secara programatis: gunakan parameter agents dalam opsi query() Anda (TypeScript, Python)
  • Berbasis sistem file: tentukan agents sebagai file markdown di direktori .claude/agents/ (lihat mendefinisikan subagents sebagai file)
  • Tujuan umum bawaan: Claude dapat memanggil subagent general-purpose bawaan kapan saja melalui alat Agent tanpa Anda mendefinisikan apa pun

Panduan ini berfokus pada pendekatan programatis, yang direkomendasikan untuk aplikasi SDK.

Ketika Anda mendefinisikan subagents, Claude menentukan apakah akan memanggil mereka berdasarkan field description setiap subagent. Tulis deskripsi yang jelas yang menjelaskan kapan subagent harus digunakan, dan Claude akan secara otomatis mendelegasikan tugas yang sesuai. Anda juga dapat secara eksplisit meminta subagent berdasarkan nama dalam prompt Anda (misalnya, "Gunakan agen code-reviewer untuk...").

Manfaat menggunakan subagents

Isolasi konteks

Setiap subagent berjalan dalam percakapan segar mereka sendiri. Panggilan alat perantara dan hasil tetap berada di dalam subagent; hanya pesan finalnya yang kembali ke parent. Lihat Apa yang diwarisi subagents untuk mengetahui dengan tepat apa yang ada dalam konteks subagent.

Contoh: subagent research-assistant dapat menjelajahi puluhan file tanpa konten apa pun yang terakumulasi dalam percakapan utama. Parent menerima ringkasan ringkas, bukan setiap file yang dibaca subagent.

Paralelisasi

Beberapa subagents dapat berjalan secara bersamaan, sehingga subtask independen selesai dalam waktu yang paling lambat daripada jumlah dari semuanya.

Contoh: selama tinjauan kode, Anda dapat menjalankan subagents style-checker, security-scanner, dan test-coverage secara bersamaan, bukan secara berurutan.

Instruksi dan pengetahuan khusus

Setiap subagent dapat memiliki prompt sistem yang disesuaikan dengan keahlian spesifik, praktik terbaik, dan batasan.

Contoh: subagent database-migration dapat memiliki pengetahuan terperinci tentang praktik terbaik SQL, strategi rollback, dan pemeriksaan integritas data yang akan menjadi kebisingan yang tidak perlu dalam instruksi agen utama.

Pembatasan alat

Subagents dapat dibatasi pada alat tertentu, mengurangi risiko tindakan yang tidak diinginkan.

Contoh: subagent doc-reviewer mungkin hanya memiliki akses ke alat Read dan Grep, memastikan dapat menganalisis tetapi tidak pernah secara tidak sengaja memodifikasi file dokumentasi Anda.

Membuat subagents

Tentukan subagents langsung dalam kode Anda menggunakan parameter agents. Contoh ini membuat dua subagents: peninjau kode dengan akses read-only dan runner test yang dapat menjalankan perintah. Claude memanggil subagents melalui alat Agent, jadi sertakan Agent dalam allowedTools untuk auto-approve invokasi subagent tanpa prompt izin.

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())

Konfigurasi AgentDefinition

Field Type Required Description
description string Yes Deskripsi bahasa alami tentang kapan menggunakan agen ini
prompt string Yes Prompt sistem agen yang mendefinisikan peran dan perilakunya
tools string[] No Array nama alat yang diizinkan. Jika dihilangkan, mewarisi semua alat
disallowedTools string[] No Array nama alat yang akan dihapus dari set alat agen. Pola tingkat server MCP juga diterima: mcp__server atau mcp__server__* menghapus setiap alat dari server tersebut, dan mcp__* menghapus setiap alat MCP dari server apa pun
model string No Penggantian model untuk agen ini. Menerima alias seperti 'fable', 'opus', 'sonnet', 'haiku', 'inherit', atau ID model lengkap. Default ke model utama jika dihilangkan
skills string[] No Daftar nama skill untuk dimuat sebelumnya ke dalam konteks agen saat startup. Skill yang tidak terdaftar tetap dapat dipanggil melalui alat Skill
memory 'user' | 'project' | 'local' No Sumber memori untuk agen ini
mcpServers (string | object)[] No Server MCP yang tersedia untuk agen ini, berdasarkan nama atau konfigurasi inline
initialPrompt string No Auto-submitted sebagai putaran pengguna pertama saat agen ini berjalan sebagai agen thread utama. Diabaikan saat agen dipanggil sebagai subagent
maxTurns number No Jumlah maksimum putaran agentic sebelum agen berhenti
background boolean No Jalankan agen ini sebagai tugas latar belakang non-blocking saat dipanggil
effort 'low' | 'medium' | 'high' | 'xhigh' | 'max' | number No Tingkat upaya penalaran untuk agen ini
permissionMode PermissionMode No Mode izin untuk eksekusi alat dalam agen ini

Dalam Python SDK, nama field ini menggunakan camelCase untuk mencocokkan format wire. Lihat referensi AgentDefinition untuk detail.

Definisi berbasis sistem file (alternatif)

Anda juga dapat mendefinisikan subagents sebagai file markdown di direktori .claude/agents/. Lihat dokumentasi subagents Claude Code untuk detail tentang pendekatan ini. Agen yang didefinisikan secara programatis memiliki prioritas lebih tinggi daripada agen berbasis sistem file dengan nama yang sama.

Apa yang diwarisi subagents

Jendela konteks subagent dimulai segar (tidak ada percakapan parent) tetapi tidak kosong. Satu-satunya saluran dari parent ke subagent adalah string prompt alat Agent, jadi sertakan jalur file, pesan kesalahan, atau keputusan apa pun yang dibutuhkan subagent langsung dalam prompt itu.

Subagent menerima Subagent tidak menerima
Prompt sistem sendiri (AgentDefinition.prompt) dan prompt alat Agent Riwayat percakapan parent atau hasil alat
Project CLAUDE.md (dimuat melalui settingSources) Konten skill yang dimuat sebelumnya, kecuali terdaftar dalam AgentDefinition.skills
Definisi alat (diwarisi dari parent, atau subset dalam tools) Prompt sistem parent

Memanggil subagents

Invokasi otomatis

Claude secara otomatis memutuskan kapan akan memanggil subagents berdasarkan tugas dan description setiap subagent. Misalnya, jika Anda mendefinisikan subagent performance-optimizer dengan deskripsi "Performance optimization specialist for query tuning", Claude akan memanggilnya ketika prompt Anda menyebutkan optimasi query.

Tulis deskripsi yang jelas dan spesifik sehingga Claude dapat mencocokkan tugas ke subagent yang tepat.

Invokasi eksplisit

Untuk menjamin Claude menggunakan subagent tertentu, sebutkan berdasarkan nama dalam prompt Anda:

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

Ini melewati pencocokan otomatis dan langsung memanggil subagent bernama.

Konfigurasi agen dinamis

Anda dapat membuat definisi agen secara dinamis berdasarkan kondisi runtime. Contoh ini membuat peninjau keamanan dengan tingkat ketat yang berbeda, menggunakan model yang lebih kuat untuk tinjauan ketat.

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())

Mendeteksi invokasi subagent

Subagents dipanggil melalui alat Agent. Untuk mendeteksi ketika subagent dipanggil, periksa blok tool_use di mana name adalah "Agent". Pesan dari dalam konteks subagent mencakup field parent_tool_use_id.

Struktur pesan berbeda antara SDK. Dalam Python, blok konten diakses langsung melalui message.content. Dalam TypeScript, SDKAssistantMessage membungkus pesan Claude API, jadi konten diakses melalui message.message.content.

Contoh ini mengulangi pesan yang dialirkan, mencatat ketika subagent dipanggil dan ketika pesan berikutnya berasal dari dalam konteks eksekusi subagent itu.

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())

Melanjutkan subagents

Subagents dapat dilanjutkan untuk melanjutkan dari mana mereka berhenti. Subagents yang dilanjutkan mempertahankan riwayat percakapan lengkap mereka, termasuk semua panggilan alat sebelumnya, hasil, dan penalaran. Subagent melanjutkan tepat di mana ia berhenti daripada memulai segar.

Ketika subagent selesai, hasil alat Agent mencakup blok teks yang berisi agentId: <id>. Agen bawaan Explore dan Plan adalah one-shot dan tidak mengembalikan agentId, jadi gunakan agen khusus atau general-purpose ketika Anda perlu melanjutkan. Untuk melanjutkan subagent secara programatis:

  1. Tangkap ID sesi: Ekstrak session_id dari pesan selama query pertama
  2. Ekstrak ID agen: Parse agentId dari teks hasil alat Agent
  3. Lanjutkan sesi: Berikan resume: sessionId dalam opsi query kedua, dan sertakan ID agen dalam prompt Anda

Contoh di bawah mendefinisikan agen khusus endpoint-finder. Query pertama menjalankannya dan menangkap ID sesi dan ID agen dari hasil alat Agent, kemudian query kedua melanjutkan sesi untuk mengajukan pertanyaan tindak lanjut yang memerlukan konteks dari analisis pertama.

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())

Transkrip subagent bertahan secara independen dari percakapan utama:

  • Pemadatan percakapan utama: Ketika percakapan utama dipadatkan, transkrip subagent tidak terpengaruh. Mereka disimpan dalam file terpisah.
  • Persistensi sesi: Transkrip subagent bertahan dalam sesi mereka. Anda dapat melanjutkan subagent setelah memulai ulang Claude Code dengan melanjutkan sesi yang sama.
  • Pembersihan otomatis: Transkrip dibersihkan berdasarkan pengaturan cleanupPeriodDays (default: 30 hari).

Pembatasan alat

Subagents dapat memiliki akses alat terbatas melalui field tools:

  • Hilangkan field: agen mewarisi semua alat yang tersedia (default)
  • Tentukan alat: agen hanya dapat menggunakan alat yang terdaftar

Contoh ini membuat agen analisis read-only yang dapat memeriksa kode tetapi tidak dapat memodifikasi file atau menjalankan perintah.

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())

Kombinasi alat umum

Kasus penggunaan Alat Deskripsi
Analisis read-only Read, Grep, Glob Dapat memeriksa kode tetapi tidak memodifikasi atau menjalankan
Eksekusi test Bash, Read, Grep Dapat menjalankan perintah dan menganalisis output
Modifikasi kode Read, Edit, Write, Grep, Glob Akses read/write penuh tanpa eksekusi perintah
Akses penuh Semua alat Mewarisi semua alat dari parent (hilangkan field tools)

Skalakan dengan alur kerja dinamis

Subagents bekerja dengan baik untuk beberapa tugas yang didelegasikan per putaran. Untuk menjalankan yang mengoordinasikan puluhan hingga ratusan agen, gunakan alat Workflow, yang memindahkan orkestrasi ke dalam skrip yang dijalankan runtime di luar konteks percakapan. Lihat alur kerja dinamis untuk cara alur kerja berbeda dari delegasi subagent putaran demi putaran.

Alat Workflow tersedia dalam TypeScript Agent SDK v0.3.149 dan yang lebih baru. Sertakan Workflow dalam allowedTools untuk auto-approve jalankan alur kerja. Skema input dan output alat tercantum dalam referensi TypeScript.

Troubleshooting

Claude tidak mendelegasikan ke subagents

Jika Claude menyelesaikan tugas secara langsung daripada mendelegasikan ke subagent Anda:

  1. Periksa bahwa invokasi Agent disetujui: sertakan Agent dalam allowedTools untuk auto-approve panggilan subagent. Tanpa itu, invokasi Agent jatuh ke callback canUseTool Anda atau, dalam mode dontAsk, ditolak
  2. Gunakan prompting eksplisit: sebutkan subagent berdasarkan nama dalam prompt Anda (misalnya, "Gunakan agen code-reviewer untuk...")
  3. Tulis deskripsi yang jelas: jelaskan dengan tepat kapan subagent harus digunakan sehingga Claude dapat mencocokkan tugas dengan tepat

Agen berbasis filesystem tidak dimuat

Agen yang didefinisikan dalam .claude/agents/ dimuat saat startup saja. Jika Anda membuat file agen baru saat Claude Code berjalan, mulai ulang sesi untuk memuatnya.

Windows: kegagalan prompt panjang

Di Windows, subagents dengan prompt yang sangat panjang mungkin gagal karena batasan panjang baris perintah (8191 karakter). Jaga prompt tetap ringkas atau gunakan agen berbasis filesystem untuk instruksi kompleks.

  • Subagents Claude Code: dokumentasi subagent komprehensif termasuk definisi berbasis sistem file
  • Alur kerja dinamis: orkestrasi banyak subagents dari skrip untuk pekerjaan yang terlalu besar untuk satu percakapan
  • Ikhtisar SDK: memulai dengan Claude Agent SDK