10.12 Riset Panjang & Subagent

Topologi: C — Supervisor + Subagent Materi yang dipakai: 7.3, 7.2 Goals, 3.4Prasyarat: 10.2

Masalahnya

Tim riset pasar butuh laporan singkat tentang sebuah topik: kumpulkan fakta dari sumber, verifikasi, lalu rangkai jadi narasi yang enak dibaca.

Percobaan pertama: satu agent dengan semua tool dan instruksi tiga halaman yang mencakup cara mencari, cara memverifikasi, dan cara menulis.

Hasilnya buruk dengan cara yang khas: agent menulis narasi sebelum cukup fakta, atau mengumpulkan fakta lalu menyajikannya sebagai daftar mentah. Ia mencampur dua mode kerja yang berbeda.

Keputusan arsitektur

Keputusan 1 — Satu agent besar atau supervisor + subagent?

	Satu agent, banyak tool	Supervisor + subagent
Panjang instruksi	3 halaman, semua mode tercampur	1 paragraf per peran
Fokus tiap langkah	Rendah — model memegang semua sekaligus	Tinggi
Biaya	1 rantai panggilan	Lebih mahal — tiap delegasi panggilan model
Bisa dilacak	Satu trace panjang	Terlihat per subagent
Kapan mulai masuk akal	—	Saat instruksi tidak muat satu layar

Pilihan: supervisor + subagent.

Tapi perhatikan baris ketiga — ini bukan pilihan gratis. Tiap delegasi berarti panggilan model tambahan. Jangan memecah agent hanya karena terlihat lebih rapi.

Patokan dari 7.3: pecah saat keahliannya benar-benar terpisah, bukan saat cuma butuh prosedur tambahan — untuk itu ada skill, yang jauh lebih murah.

Keputusan 2 — Berapa subagent?

Pilihan: dua — periset dan penulis.

Godaannya membuat empat: pencari, pemverifikasi, penulis, penyunting. Tapi tiap subagent tambahan menambah satu keputusan routing yang bisa salah.

Mulai dari dua peran yang paling jelas berbeda: mengumpulkan dan merangkai. Tambah lagi hanya kalau terbukti kurang.

Keputusan 3 — Kapan berhenti?

Riset tidak punya akhir alami. Tiga mekanisme, dan ketiganya berbeda tujuan:

Mekanisme	Menjawab	Sifat
maxSteps	Batas keras jumlah langkah	Rem darurat
isTaskComplete	Apakah hasilnya sudah memenuhi kriteria?	Per pemanggilan
goal + maxRuns	Tujuan durable lintas pesan	Tersimpan di thread

Pilihan: maxSteps untuk laporan sekali jalan; goal kalau risetnya berlanjut lintas percakapan.

Ingat pembedaan dari 7.2: goal bertahan di thread state, isTaskComplete diberikan per panggilan. Untuk "buatkan satu laporan sekarang", maxSteps sudah cukup.

Keputusan 4 — Memory untuk sesi riset panjang

Kalau riset berlangsung berhari-hari, lastMessages tidak memadai — dan menaikkannya membuat konteks membengkak.

Di sinilah observational memory dari 3.4 masuk: agent latar belakang memelihara log observasi (apa yang sudah dicoba, apa yang gagal, keputusan apa yang diambil) yang menggantikan riwayat mentah.

Struktur direktori

riset-pasar/
├── src/
│   ├── domain/
│   │   └── sumber.ts               ← pencarian & pengambilan sumber
│   └── mastra/
│       ├── agents/
│       │   ├── periset-agent.ts    ← subagent: kumpulkan fakta
│       │   ├── penulis-agent.ts    ← subagent: rangkai narasi
│       │   └── supervisor-agent.ts ← koordinator
│       ├── tools/
│       │   └── cari-sumber.ts      ← HANYA dipegang periset
│       └── index.ts
└── package.json

Perhatikan cari-sumber tidak diberikan ke supervisor maupun penulis. Pembatasan tool per peran adalah bagian dari desain — penulis yang punya akses pencarian akan tergoda mencari sendiri alih-alih memakai fakta yang diberikan.

Alur

Implementasi

src/mastra/agents/periset-agent.ts

import { Agent } from '@mastra/core/agent'
import { cariSumber } from '../tools/cari-sumber.ts'

export const perisetAgent = new Agent({
  id: 'periset',
  name: 'Periset',

  // description dibaca SUPERVISOR untuk memutuskan delegasi.
  description:
    'Mengumpulkan fakta dan data dari sumber referensi. ' +
    'Pakai untuk tahap pengumpulan data, BUKAN untuk menulis narasi.',

  // instructions dibaca subagent ini sendiri saat bekerja.
  instructions: `Kumpulkan fakta memakai cariSumber.

Kembalikan poin-poin ringkas beserta sumbernya. Maksimal 5 poin.
Jangan menulis narasi panjang — itu tugas agent lain.
Panggil cariSumber SEKALI dengan kueri yang fokus. Jangan mengulang pencarian
dengan variasi kata yang mirip.`,

  model: 'openai/gpt-5-mini',
  tools: { cariSumber },
})

Perbedaan description dan instructions di sini adalah inti pola subagent, seperti dibahas di 7.3:

Properti	Dibaca oleh	Menentukan
description	Supervisor	Apakah pekerjaan ini didelegasikan ke sini
instructions	Subagent sendiri	Bagaimana ia bekerja setelah dipilih

Subagent tanpa description praktis tidak akan pernah dipilih dengan tepat.

Kalimat terakhir instruksi — larangan mengulang pencarian — ditambahkan setelah melihat perilaku nyata. Alasannya di bagian Hasil nyata.

src/mastra/agents/penulis-agent.ts

import { Agent } from '@mastra/core/agent'

export const penulisAgent = new Agent({
  id: 'penulis',
  name: 'Penulis',

  description:
    'Mengubah poin-poin fakta menjadi paragraf yang mengalir. ' +
    'Pakai SETELAH fakta terkumpul, BUKAN untuk mencari data.',

  instructions: `Ubah poin-poin yang diberikan menjadi satu paragraf pendek
yang enak dibaca.

JANGAN menambah fakta yang tidak ada di poin yang diberikan.
Kalau poinnya kurang, katakan apa yang kurang — jangan mengisi sendiri.`,

  model: 'openai/gpt-5-mini',

  // Tidak punya tool. Sengaja.
})

Penulis tidak diberi tool sama sekali. Ia hanya bisa mengolah apa yang diberikan — yang mencegahnya mengarang fakta baru.

src/mastra/agents/supervisor-agent.ts

import { Agent } from '@mastra/core/agent'
import { perisetAgent } from './periset-agent.ts'
import { penulisAgent } from './penulis-agent.ts'

export const supervisorAgent = new Agent({
  id: 'supervisor',
  name: 'Supervisor',
  instructions: `Kamu koordinator penulisan laporan singkat.

Alur kerjamu, berurutan:
1. Delegasikan ke periset SEKALI untuk mengumpulkan fakta.
2. Delegasikan ke penulis untuk merangkainya jadi paragraf.
3. Sampaikan hasil akhir dari penulis, tanpa tambahan.

Jangan mendelegasikan ke periset lebih dari sekali kecuali penulis
melaporkan faktanya benar-benar kurang.`,
  model: 'openai/gpt-5.6-sol',

  // Didaftarkan lewat `agents` -> otomatis jadi tool agent-<key>.
  agents: { periset: perisetAgent, penulis: penulisAgent },
})

Mengendalikan delegasi

Untuk kendali lebih ketat, opsi delegation dari 7.3 menyediakan tiga callback:

const hasil = await supervisorAgent.generate(pesan, {
  maxSteps: 8,

  delegation: {
    // Tolak delegasi yang tidak masuk akal.
    onDelegationStart: ({ agentId }) => {
      console.log(`delegasi ke ${agentId}`)
      // return { batal: true } untuk menolak
    },

    // Batasi konteks yang menyeberang ke subagent.
    messageFilter: ({ messages }) => messages.slice(-3),

    // Arahkan langkah supervisor berikutnya.
    onDelegationComplete: ({ agentId }) => {
      if (agentId === 'penulis') {
        return { feedback: 'Paragraf sudah jadi. Sampaikan ke pengguna, jangan riset lagi.' }
      }
    },
  },
})

messageFilter layak dipakai sejak awal di sistem multi-agent: tanpa itu, subagent menerima seluruh riwayat percakapan — mahal, dan memperbesar permukaan kebocoran data antar peran.

Hasil nyata

Dijalankan sungguhan. Dan hasilnya memperlihatkan masalah, yang justru lebih berguna daripada demo yang mulus.

> Buat paragraf singkat tentang adopsi kendaraan listrik di Indonesia.

   [tool cari-sumber("adopsi kendaraan listrik di Indonesia: tren
    penjualan/adopsi, kebijakan pendorong (tahun), infrastruktur
    pengisian, tantangan — sertakan sumber tepercaya dan tahun")]
   [tool cari-sumber("adopsi kendaraan listrik Indonesia 2023 2024 2025
    data GAIKINDO Kementerian ESDM PLN Perpres Kemenkeu ...")]
   [tool cari-sumber("GAIKINDO penjualan mobil listrik 2023 2024, PLN
    SPKLU jumlah 2023 2024, Kementerian ESDM/ESDM peraturan ...")]
   [tool cari-sumber("adopsi kendaraan listrik di Indonesia: Perpres
    55/2019 dan perubahannya, insentif pemerintah ...")]
   [tool cari-sumber("Perpres 55/2019 beserta perubahannya, insentif
    pemerintah untuk kendaraan listrik Indonesia, peran PLN ...")]

Tool/subagent yang dipanggil:
  - agent-periset
  - agent-periset
  - agent-periset
  - agent-penulis

Hasil akhirnya bagus:

Adopsi kendaraan listrik di Indonesia terus menunjukkan peningkatan, didorong
oleh Perpres No. 55 Tahun 2019, berbagai insentif pemerintah, serta investasi
dan produksi lokal. PLN bersama pelaku swasta juga terus mengembangkan
infrastruktur pengisian daya. Meski demikian, pertumbuhannya masih menghadapi
sejumlah tantangan, seperti harga kendaraan yang relatif tinggi, keterbatasan
stasiun pengisian—terutama di luar kota besar dan Pulau Jawa—serta kesiapan
rantai pasok nasional.

Tapi perhatikan biayanya.

Delegasi berulang: masalah nyata pola supervisor

Supervisor mendelegasikan ke agent-periset tiga kali, dan periset memanggil cari-sumber lima kali — dengan kueri yang makin panjang dan makin mirip satu sama lain.

Untuk pekerjaan yang sebenarnya butuh satu pencarian, itu sekitar 8 panggilan model alih-alih 2.

Ini bukan bug Mastra. Ini perilaku khas supervisor yang instruksinya tidak cukup tegas soal kapan berhenti mengumpulkan. Model cenderung merasa datanya "belum cukup lengkap" dan mencoba lagi.

Tiga perbaikan yang menutup celah ini, dan ketiganya sudah dituangkan ke kode di atas:

Perbaikan	Di mana
"Panggil cariSumber SEKALI dengan kueri yang fokus"	instructions periset
"Jangan mendelegasikan ke periset lebih dari sekali kecuali..."	instructions supervisor
feedback yang menghentikan riset setelah penulis selesai	onDelegationComplete

Plus maxSteps: 8 sebagai rem darurat.

Pelajarannya: pola supervisor memberi fokus, tapi menukarnya dengan kendali. Kamu harus secara eksplisit memberitahu supervisor kapan berhenti — kalau tidak, ia akan terus menyempurnakan.

Perhatikan juga penamaan tool di keluaran: agent-periset dan agent-penulis. Itu pola agent-<key> dari 2.1, terlihat langsung di trace.

Best practice yang dipakai di sini

1. description untuk supervisor, instructions untuk subagent. Keduanya wajib, dan perannya berbeda.

2. Tool dibatasi per peran. Penulis tidak punya tool sama sekali — mencegahnya mengarang fakta.

3. Kalimat "BUKAN untuk..." di tiap description. Sama seperti tool berdekatan di 10.2.

4. Batas eksplisit pada pengulangan delegasi. Tanpa ini, supervisor menyempurnakan tanpa henti.

5. messageFilter membatasi konteks yang menyeberang. Hemat biaya, sekaligus mengurangi kebocoran antar peran.

6. maxSteps sebagai rem terakhir. Bukan pengganti instruksi yang jelas, tapi jaring pengaman.

Kapan pola ini salah

Situasi	Kenapa gagal	Ke mana
Yang dibutuhkan cuma prosedur tambahan, bukan keahlian terpisah	Subagent terlalu mahal	Skill, 7.3
Urutannya sudah pasti	Supervisor menambah ketidakpastian	Workflow, 10.8
Riset berlangsung berhari-hari	lastMessages tidak memadai	3.4 Observational memory
Biaya delegasi tidak terkendali	Butuh pengukuran, bukan tebakan	10.15 Platform produksi

Baris pertama adalah kesalahan paling umum. Kalau kamu hanya perlu agent tahu prosedur X saat kasus X muncul, itu skill — satu panggilan model, bukan dua.

Coba sendiri

Bangun asisten penulisan artikel dengan tiga subagent: periset, penulis, dan penyunting yang memeriksa klaim tanpa sumber.

Lalu ukur biayanya.

Selesai kalau

• [ ] Ketiga subagent punya description yang menyebut cakupan dan batas
• [ ] Penyunting tidak punya tool pencarian
• [ ] Kamu mencatat berapa kali tiap subagent dipanggil untuk satu artikel
• [ ] Setelah memperketat instruksi, jumlah delegasi turun — dan kamu punya angka sebelum dan sesudah
• [ ] messageFilter terpasang, dan kamu bisa menunjukkan subagent menerima lebih sedikit pesan
• [ ] Kamu bisa menyebutkan satu bagian yang sebenarnya lebih tepat jadi skill daripada subagent

Kalau macet

Supervisor mendelegasikan berulang tanpa henti? Instruksinya tidak menyebutkan kapan berhenti. Tambahkan batas eksplisit, dan pakai onDelegationComplete untuk memberi feedback yang mengarahkan ke langkah berikutnya.

Supervisor tidak pernah mendelegasikan? Subagent tidak punya description, atau deskripsinya tidak membedakan satu dari yang lain.

Biaya meledak? Hitung: tiap delegasi minimal satu panggilan model, dan subagent yang memakai tool menambah lagi. Pasang maxSteps dan ukur.

Lanjut ke mana

Semua kemampuan sejauh ini tinggal di dalam aplikasimu sendiri. Kasus berikutnya membuka batas itu — memakai tool dari sistem lain, dan menyediakan tool untuk sistem lain — 10.13 Integrasi lewat MCP.