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

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, secara dramatis mempercepat alur kerja yang kompleks.

Contoh: selama tinjauan kode, Anda dapat menjalankan subagents style-checker, security-scanner, dan test-coverage secara bersamaan, mengurangi waktu tinjauan dari menit menjadi detik.

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

Definisi programatis (direkomendasikan)

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. Alat Agent harus disertakan dalam allowedTools karena Claude memanggil subagents melalui alat Agent.

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

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
model string No Penggantian model untuk agen ini. Menerima alias seperti 'sonnet', 'opus', '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
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.

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


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

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, Claude menerima ID agennya dalam hasil alat Agent. Untuk melanjutkan subagent secara programatis:

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

Contoh di bawah mendemonstrasikan alur ini: query pertama menjalankan subagent dan menangkap ID sesi dan ID agen, kemudian query kedua melanjutkan sesi untuk mengajukan pertanyaan tindak lanjut yang memerlukan konteks dari analisis pertama.

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);
}
}

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)

Troubleshooting

Claude tidak mendelegasikan ke subagents

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

  1. Sertakan alat Agent: subagents dipanggil melalui alat Agent, jadi harus ada dalam allowedTools
  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 sistem file 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 sistem file untuk instruksi kompleks.

Dokumentasi terkait