7.3 Subagents & Skills

Tujuan bab

Setelah bab ini kamu bisa:

• Membangun supervisor yang mendelegasikan ke subagent spesialis
• Menjelaskan kenapa description subagent lebih menentukan daripada instructions-nya
• Mengendalikan dan memantau delegasi lewat opsi delegation
• Membuat skill dengan createSkill() dan menjelaskan bedanya dari instructions
• Memilih antara subagent, workflow, dan tool untuk sebuah pembagian kerja

Prasyarat

• 2.1 Tool Pertama — konsep agent sebagai tool
• 7.2 Goals, Schedules & Signals

Kenapa membagi ke beberapa agent

Satu agent dengan dua puluh tool dan instruksi tiga halaman akan bekerja lebih buruk daripada tiga agent dengan tujuh tool dan instruksi satu halaman masing-masing. Alasannya sama seperti pada manusia: semakin luas cakupan yang harus dipegang sekaligus, semakin sering keputusan meleset.

Subagent adalah agent spesialis yang bisa didelegasikan pekerjaan oleh agent lain. Agent induk yang mengoordinasikan mereka lazim disebut supervisor.

Membangun supervisor

// src/mastra/agents/supervisor.ts
import { Agent } from '@mastra/core/agent'
import { Memory } from '@mastra/memory'

const researchAgent = new Agent({
  id: 'research-agent',
  description: 'Mengumpulkan informasi faktual dan mengembalikan ringkasan berpoin.',
  model: 'openai/gpt-5-mini',
})

const writingAgent = new Agent({
  id: 'writing-agent',
  description: 'Mengubah hasil riset menjadi artikel yang tersusun rapi.',
  model: 'openai/gpt-5-mini',
})

export const parentAgent = new Agent({
  id: 'parent-agent',
  instructions: `Kamu mengoordinasikan riset dan penulisan lewat agent spesialis.
    Delegasikan ke research-agent untuk fakta, lalu ke writing-agent untuk konten.`,
  model: 'openai/gpt-5.6-sol',
  agents: { researchAgent, writingAgent },
  memory: new Memory(),
})

Ini pola yang sudah kamu lihat sekilas di 2.1: subagent yang didaftarkan lewat properti agents otomatis menjadi tool bernama agent-<key>.

Artinya seluruh yang kamu pahami tentang tool berlaku — termasuk hal yang paling menentukan.

description lebih penting daripada instructions

Perhatikan bahwa kedua subagent di atas punya description tapi tidak punya instructions. Itu bukan kelalaian; itu menunjukkan mana yang berperan di sini.

Properti	Dibaca oleh	Menentukan
description	Supervisor	Apakah pekerjaan ini didelegasikan ke sini
instructions	Model subagent itu sendiri	Bagaimana subagent bekerja setelah dipilih

Supervisor memutuskan berdasarkan instruksinya sendiri dan description tiap subagent. Subagent tanpa description praktis tidak akan pernah dipilih dengan tepat — persis seperti tool tanpa deskripsi di 2.2.

Untuk subagent yang benar-benar dipakai di produksi, tentu berikan keduanya: description supaya dipilih dengan tepat, instructions supaya bekerja dengan baik.

Mengendalikan delegasi

Di 1.3 kita menyebut sekilas bahwa generate() menerima opsi delegation. Sekarang opsi itu masuk akal.

Tiga callback yang tersedia:

Callback	Kapan dipanggil	Bisa dipakai untuk
onDelegationStart	Sebelum mendelegasikan	Mengubah parameter delegasi, menolak delegasi, atau menambah entri ke request context subagent
onDelegationComplete	Setelah delegasi selesai	Memberi feedback untuk mengarahkan langkah supervisor berikutnya, atau bail() untuk menghentikan
messageFilter	Sebelum mendelegasikan	Menyaring pesan mana yang diteruskan ke subagent

Ketiganya menyelesaikan masalah nyata.

onDelegationStart untuk menolak. Supervisor bisa saja memutuskan mendelegasikan sesuatu yang tidak seharusnya — misalnya mengirim data pelanggan ke subagent yang tidak berwenang. Callback ini adalah tempat kebijakan itu ditegakkan dengan kode, bukan dengan harapan.

messageFilter untuk membatasi konteks. Secara default subagent bisa menerima riwayat percakapan. Sering kali ia tidak butuh semuanya — dan kadang tidak boleh melihat semuanya. Filter ini yang mengendalikannya.

onDelegationComplete untuk mengarahkan. Nilai feedback yang kamu kembalikan disimpan ke memory supervisor sebagai pesan assistant, sehingga mempengaruhi langkah berikutnya.

Ini tuas keamanan, bukan sekadar telemetri

Mudah menganggap ketiga callback ini sebagai hook pemantauan. Dua di antaranya sebenarnya titik penegakan kebijakan: onDelegationStart bisa menolak, dan messageFilter menentukan data apa yang menyeberang ke subagent. Untuk aplikasi yang menangani data sensitif, keduanya layak dipakai sejak awal.

Skills — instruksi yang dimuat saat dibutuhkan

Masalah yang diselesaikan skills berhubungan langsung dengan 1.2: instruksi ikut dikirim di setiap panggilan model. Prosedur khusus yang hanya relevan untuk sepersepuluh permintaan tetap dibayar di sepuluh persepuluhnya.

Skill adalah instruksi yang bisa dipakai ulang dan dimuat saat dibutuhkan, mengikuti spesifikasi Agent Skills.

// src/mastra/skills/code-review.ts
import { createSkill } from '@mastra/core/skills'

export const codeReview = createSkill({
  name: 'code-review',
  description: 'Pakai saat meninjau perubahan kode.',
  instructions: `
    Saat meninjau kode:
    1. Periksa kebenaran dan kasus tepi
    2. Verifikasi konsistensi gaya
    3. Cari potensi bug
  `,
})

Perhatikan strukturnya: description menentukan kapan skill dipakai, instructions berisi apa yang harus dilakukan. Pola yang sama dengan tool dan subagent — dan alasannya sama: ada yang harus memutuskan relevansi sebelum isinya dipakai.

Dua tempat skill bisa tinggal

Dokumentasi membedakan dua cara memasang skill:

	Agent-level (skills pada agent)	Workspace skills
Ditemukan dari	Kode	Sistem berkas
Dimiliki	Satu agent	Semua agent yang memakai workspace itu
Butuh workspace	Tidak	Ya
Cocok untuk	Agent mandiri, paket dan library	Proyek dengan banyak agent

Agent-level skills dipakai saat kamu ingin agent yang mandiri, atau saat kamu membangun paket yang berisi kemampuan agent. Ia juga mendukung resolusi per permintaan, sehingga skill mana yang tersedia bisa bergantung pada konteks.

Workspace skills dibahas lagi di 7.4, karena ia bagian dari abstraksi workspace.

Memilih cara membagi pekerjaan

Kamu sekarang punya empat cara memecah pekerjaan, dan memilih dengan tepat lebih menentukan daripada menguasai API-nya.

Dalam tabel:

Pilihan	Ketika	Ongkosnya
Tool	Kemampuan konkret, tanpa penalaran	Paling murah
Workflow	Urutan langkah yang pasti	Deterministik, tapi kaku
Skill	Prosedur tambahan untuk agent yang sama	Instruksi dimuat saat perlu
Subagent	Keahlian yang benar-benar terpisah	Panggilan model tambahan, konteks terpisah

Kesalahan yang paling sering: memakai subagent untuk sesuatu yang cukup jadi skill. Kalau yang kamu butuhkan hanya "agent ini harus tahu prosedur X saat kasus X muncul", itu skill — dan jauh lebih murah daripada memanggil model kedua.

Kesalahan umum

Gejala: Supervisor jarang mendelegasikan, atau selalu mendelegasikan ke subagent yang sama meskipun ada yang lebih cocok. Penyebab: Subagent tidak punya description, atau deskripsinya tidak membedakan satu dari yang lain. Supervisor memutuskan berdasarkan instruksinya sendiri dan description tiap subagent — tanpa yang kedua, ia menebak. Perbaikan: Beri tiap subagent description yang menyebutkan cakupan dan batasnya, sama seperti yang kamu lakukan untuk tool di 2.2.

Gejala: Subagent menerima riwayat percakapan yang jauh lebih banyak dari yang ia butuhkan, membuat biaya membengkak dan jawabannya melenceng. Penyebab: Tidak ada penyaringan pesan yang diteruskan saat delegasi. Perbaikan: Pakai messageFilter pada opsi delegation untuk membatasi pesan yang menyeberang. Ini juga mengurangi permukaan kebocoran data antar subagent.

Coba sendiri

Tantangan: Bangun sistem tiga agent untuk memproses laporan bug: satu supervisor, dua subagent spesialis — lalu tambahkan satu skill dan buktikan bahwa keduanya menyelesaikan masalah yang berbeda.

Ketentuan:

1. triase-agent — subagent yang menilai keparahan dan komponen yang terdampak
2. reproduksi-agent — subagent yang menyusun langkah reproduksi dari deskripsi bug
3. supervisor — mengoordinasikan keduanya, lalu menyusun tiket akhir
4. Tiap subagent punya description dan instructions yang berbeda perannya
5. Tambahkan satu skill pada supervisor: prosedur khusus untuk bug keamanan, yang hanya relevan sebagian kecil waktu
6. Pakai onDelegationStart untuk menolak delegasi ke reproduksi-agent bila laporan bug lebih pendek dari 20 kata
7. Pakai messageFilter supaya subagent hanya menerima laporan bug itu sendiri, bukan seluruh riwayat percakapan
8. Uji dengan empat laporan: bug biasa yang lengkap, bug yang terlalu pendek, bug keamanan, dan bug yang butuh kedua subagent

Checklist penerimaan:

• [ ] Supervisor mendelegasikan ke subagent yang tepat untuk tiap laporan
• [ ] Laporan yang terlalu pendek tidak sampai ke reproduksi-agent — buktikan dengan log di dalam subagent itu
• [ ] Bug keamanan memicu prosedur dari skill; bug biasa tidak
• [ ] Kamu bisa menunjukkan bahwa subagent menerima lebih sedikit pesan setelah messageFilter dipasang
• [ ] Kamu bisa menjelaskan kenapa prosedur keamanan dibuat skill dan bukan subagent ketiga
• [ ] Tiap description subagent menyebutkan batasnya, bukan hanya cakupannya

Petunjuk: Checklist kelima adalah inti bab ini. Prosedur keamanan tidak membutuhkan penalaran yang terpisah — supervisor yang sama bisa menjalankannya, ia hanya perlu tahu caranya saat kasusnya muncul. Itu definisi skill. Menjadikannya subagent berarti membayar satu panggilan model tambahan untuk sesuatu yang cukup diselesaikan dengan instruksi yang dimuat saat dibutuhkan.

Ikhtisar

• Subagent adalah agent spesialis yang didaftarkan lewat properti agents dan otomatis menjadi tool agent-<key>. Induknya disebut supervisor.
• description subagent lebih menentukan daripada instructions-nya — yang pertama dibaca supervisor untuk memilih, yang kedua dibaca subagent untuk bekerja.
• Opsi delegation menyediakan onDelegationStart (bisa menolak delegasi), onDelegationComplete (bisa memberi feedback atau bail()), dan messageFilter (membatasi pesan yang menyeberang).
• Dua di antaranya adalah tuas keamanan, bukan sekadar telemetri.
• Skill adalah instruksi yang dimuat saat dibutuhkan — menyelesaikan masalah instruksi panjang yang dibayar di setiap panggilan.
• Skill bisa agent-level (dari kode, milik satu agent) atau workspace-level (dari sistem berkas, dibagi banyak agent).
• Memilih pembagian kerja: tool untuk kemampuan konkret, workflow untuk urutan pasti, skill untuk prosedur tambahan, subagent untuk keahlian yang benar-benar terpisah.

Lanjut ke mana

Bab terakhir Bagian 7 memberi agent sesuatu yang belum pernah ia punya: tempat bekerja yang nyata — berkas, shell, dan peramban: 7.4 Sandboxes & Browser.