Subagen dalam Claude Code SDK adalah AI khusus yang diatur oleh agen utama. Gunakan subagen untuk manajemen konteks dan paralelisasi. Panduan ini menjelaskan bagaimana aplikasi SDK berinteraksi dengan dan memanfaatkan subagen yang dibuat melalui file markdown.

​
Gambaran Umum

Subagen dibuat secara eksklusif melalui pendekatan berbasis sistem file dengan menempatkan file markdown dengan frontmatter YAML di direktori yang ditentukan. SDK kemudian dapat memanggil subagen yang telah ditentukan sebelumnya selama eksekusi.

​
Manfaat Menggunakan Subagen

​
Manajemen Konteks

Subagen mempertahankan konteks terpisah dari agen utama, mencegah kelebihan informasi dan menjaga interaksi tetap fokus. Isolasi ini memastikan bahwa tugas-tugas khusus tidak mencemari konteks percakapan utama dengan detail yang tidak relevan. Contoh: Subagen research-assistant dapat menjelajahi puluhan file dan halaman dokumentasi tanpa mengacaukan percakapan utama dengan semua hasil pencarian perantara - hanya mengembalikan temuan yang relevan.

​
Paralelisasi

Beberapa subagen dapat berjalan secara bersamaan, secara dramatis mempercepat alur kerja yang kompleks. Contoh: Selama tinjauan kode, Anda dapat menjalankan subagen style-checker, security-scanner, dan test-coverage secara bersamaan, mengurangi waktu tinjauan dari menit menjadi detik.

​
Instruksi dan Pengetahuan Khusus

Setiap subagen dapat memiliki prompt sistem yang disesuaikan dengan keahlian, praktik terbaik, dan batasan tertentu. Contoh: Subagen database-migration dapat memiliki pengetahuan detail tentang praktik terbaik SQL, strategi rollback, dan pemeriksaan integritas data yang akan menjadi noise yang tidak perlu dalam instruksi agen utama.

​
Pembatasan Alat

Subagen dapat dibatasi pada alat tertentu, mengurangi risiko tindakan yang tidak diinginkan. Contoh: Subagen doc-reviewer mungkin hanya memiliki akses ke alat Read dan Grep, memastikan ia dapat menganalisis tetapi tidak pernah secara tidak sengaja memodifikasi file dokumentasi Anda.

​
Membuat Subagen

Subagen didefinisikan sebagai file markdown di direktori tertentu:
  • Tingkat proyek: .claude/agents/*.md - Tersedia hanya dalam proyek saat ini
  • Tingkat pengguna: ~/.claude/agents/*.md - Tersedia di semua proyek

​
Format File

Setiap subagen adalah file markdown dengan frontmatter YAML: 
---
name: code-reviewer
description: Spesialis tinjauan kode ahli. Gunakan untuk tinjauan kualitas, keamanan, dan maintainability.
tools: Read, Grep, Glob, Bash  # Opsional - mewarisi semua alat jika dihilangkan
---

Prompt sistem subagen Anda ada di sini. Ini mendefinisikan peran subagen,
kemampuan, dan pendekatan untuk memecahkan masalah.

Sertakan instruksi khusus, praktik terbaik, dan batasan apa pun
yang harus diikuti subagen.

​
Field Konfigurasi

FieldWajibDeskripsi
nameYaPengenal unik menggunakan huruf kecil dan tanda hubung
descriptionYaDeskripsi bahasa alami tentang kapan menggunakan subagen ini
toolsTidakDaftar alat yang diizinkan dipisahkan koma. Jika dihilangkan, mewarisi semua alat

​
Bagaimana SDK Menggunakan Subagen

Saat menggunakan Claude Code SDK, subagen yang didefinisikan dalam sistem file secara otomatis tersedia. Claude Code akan:
  1. Auto-deteksi subagen dari direktori .claude/agents/
  2. Memanggil mereka secara otomatis berdasarkan pencocokan tugas
  3. Menggunakan prompt khusus mereka dan pembatasan alat
  4. Mempertahankan konteks terpisah untuk setiap pemanggilan subagen
SDK menghormati konfigurasi sistem file - tidak ada cara programatik untuk membuat subagen saat runtime. Semua subagen harus didefinisikan sebagai file sebelum eksekusi SDK.

​
Contoh Subagen

Untuk contoh komprehensif subagen termasuk peninjau kode, pelari tes, debugger, dan auditor keamanan, lihat panduan Subagen utama. Panduan ini mencakup konfigurasi detail dan praktik terbaik untuk membuat subagen yang efektif.

​
Pola Integrasi SDK

​
Pemanggilan Otomatis

SDK akan secara otomatis memanggil subagen yang sesuai berdasarkan konteks tugas. Pastikan field description subagen Anda dengan jelas menunjukkan kapan harus digunakan: 
---
name: performance-optimizer
description: Gunakan PROAKTIF ketika perubahan kode mungkin berdampak pada kinerja. HARUS DIGUNAKAN untuk tugas optimisasi.
tools: Read, Edit, Bash, Grep
---

​
Pemanggilan Eksplisit

Pengguna dapat meminta subagen tertentu dalam prompt mereka: 
// Saat menggunakan SDK, pengguna dapat secara eksplisit meminta subagen:
const result = await query({
  prompt: "Gunakan subagen code-reviewer untuk memeriksa modul autentikasi"
});

​
Pembatasan Alat

Subagen dapat memiliki akses alat yang dibatasi melalui field tools:
  • Hilangkan field - Subagen mewarisi semua alat yang tersedia (default)
  • Tentukan alat - Subagen hanya dapat menggunakan alat yang terdaftar
Contoh subagen analisis read-only: 
---
name: code-analyzer
description: Analisis kode statis dan tinjauan arsitektur
tools: Read, Grep, Glob  # Tidak ada izin tulis atau eksekusi
---

Anda adalah analis arsitektur kode. Analisis struktur kode,
identifikasi pola, dan sarankan perbaikan tanpa membuat perubahan.

​
Dokumentasi Terkait