0.1 Apa Itu Mastra

Kenapa bab ini penting

Ini bab yang menentukan apakah kamu perlu Mastra sama sekali. Memakai framework untuk pekerjaan yang cukup diselesaikan satu panggilan API adalah biaya tanpa manfaat — dan sebaliknya, menulis sendiri infrastruktur agent dari nol adalah pekerjaan berbulan-bulan yang mudah diremehkan.

Kalau kamu melewatinya: kamu berisiko membangun agent untuk masalah yang sebenarnya butuh workflow, atau sebaliknya.

Bab ini tidak mengajarkan kode. Ia mengajarkan kapan dan kenapa.

Tujuan bab

Setelah bab ini kamu bisa:

• Menjelaskan masalah apa yang diselesaikan Mastra, dengan bahasa sendiri
• Membedakan kapan sebuah kebutuhan cukup diselesaikan dengan panggilan API model biasa, dan kapan ia benar-benar butuh framework agent
• Menyebutkan lima primitif inti Mastra dan peran masing-masing
• Memutuskan apakah Mastra cocok untuk proyek yang sedang kamu pikirkan

Prasyarat

Tidak ada. Ini bab pertama. Belum perlu memasang apa pun.

Masalahnya dulu

Bayangkan kamu diminta membuat asisten internal untuk tim support. Tugasnya: menjawab pertanyaan pelanggan, mengecek status pesanan di database, dan kalau pelanggan minta refund, mengajukan permintaan itu ke sistem — tapi refund di atas satu juta rupiah harus disetujui manusia dulu.

Versi paling sederhana yang terlintas: satu fungsi yang memanggil API model, mengirim pertanyaan pelanggan, lalu mengembalikan jawabannya.

const jawaban = await panggilModel(pertanyaanPelanggan)

Ini jalan sampai pertanyaan pertama yang butuh data nyata. "Pesanan saya nomor 4417 sudah dikirim belum?" Model tidak punya akses ke database-mu, jadi ia tidak bisa menjawab — entah dengan mengarang, entah dengan berkelit. Sebentar lagi kamu akan melihat mana yang sebenarnya terjadi.

Kamu pun menambahkan kemampuan bagi model untuk meminta data. Sekarang kamu perlu:

• Cara mendeskripsikan fungsi-fungsi yang boleh dipanggil model, dalam format yang dimengerti model
• Cara memvalidasi argumen yang dikirim model, karena model bisa mengirim nomorPesanan: "empat ribu empat ratus tujuh belas"
• Loop yang menjalankan fungsi, mengembalikan hasilnya ke model, lalu meminta model melanjutkan — berulang sampai model selesai
• Penyimpanan riwayat percakapan, karena pelanggan bilang "kalau itu, refund saja" dan "itu" merujuk ke pesan sebelumnya
• Mekanisme jeda saat refund melewati satu juta, yang bisa dilanjutkan besok pagi setelah supervisor menekan tombol setuju — termasuk kalau server sempat restart di antaranya
• Rekaman jejak untuk saat asisten memberi jawaban aneh dan kamu harus tahu ia memanggil apa saja
• Cara mengukur, sebelum rilis, apakah versi baru asistenmu lebih baik atau justru lebih buruk dari versi kemarin

Lihat sendiri masalahnya

Sebelum bicara solusi, ini pertanyaan tadi dijalankan sungguhan ke agent yang tidak punya tool sama sekali — hanya instruksi "Kamu asisten support toko online":

> Pesanan nomor 4417 sudah dikirim belum?

Bisa saya bantu cek. Untuk memastikan status pesanan #4417 saya butuh
konfirmasi identitas pemesan, misalnya salah satu dari:
- alamat email yang dipakai saat order, atau
- nomor telepon yang terdaftar, atau
- nama lengkap pada pesanan.

Kalau mau cek sendiri cepat:
- buka email konfirmasi dari kami (ada link/nomor resi jika sudah dikirim), atau
- masuk ke Akun > Pesanan Saya di situs/app, lalu pilih pesanan #4417.

Info tambahan: pesanan biasanya diproses 1-2 hari kerja sebelum dikirim...

Mau saya cek sekarang? Silakan kirim salah satu data di atas.

Perhatikan apa yang terjadi: agent tidak mengarang status palsu — ia mentok. Ia meminta verifikasi identitas yang tidak bisa ia proses, lalu menyuruh pengguna mengeceknya sendiri. Sepuluh baris yang tidak menjawab apa pun.

Sekarang agent yang sama, ditambah satu tool cekPesanan yang membaca dari data pesanan:

> Pesanan nomor 4417 sudah dikirim belum?
   [tool jalan: cek-pesanan(4417) -> ketemu]

Pesanan nomor 4417 sudah dikirim.

- Status: dikirim
- Kurir: JNE
- Nomor resi: JN881204
- Tanggal pengiriman: 2026-09-04

Mau saya lacakkan status pengiriman terbaru lewat JNE untuk Anda?

Selisihnya bukan soal model yang lebih pintar — modelnya sama persis (openai/gpt-5-mini). Yang berubah hanya: agent kedua punya jalan untuk mengetahui sesuatu.

Baris [tool jalan: ...] itu keluaran nyata dari console.log di dalam tool. Ia membuktikan tool benar-benar dipanggil, bukan jawabannya dikarang.

Kalau agent-mu "bodoh", periksa aksesnya dulu

Kesimpulan yang salah dari percobaan pertama: "modelnya kurang pintar, coba model yang lebih mahal." Model termahal pun akan memberi jawaban yang sama — ia tidak punya cara mengetahui isi database-mu.

Sebagian besar keluhan "agent saya bodoh" sebenarnya keluhan "agent saya tidak diberi akses".

Tidak satu pun dari daftar itu berhubungan dengan "kecerdasan". Semuanya pekerjaan infrastruktur. Dan semuanya harus kamu tulis lagi dari nol di proyek berikutnya.

Mastra adalah infrastruktur itu. Ia framework TypeScript yang menyediakan potongan-potongan tersebut sebagai primitif yang sudah jadi, sehingga yang kamu tulis tinggal logika yang khas untuk aplikasimu.

Lima primitif inti

Hampir semua yang akan kamu pelajari berputar di sekitar lima hal ini.

Primitif	Perannya	Analogi
Agent	Mengambil keputusan. Diberi tujuan, ia memutuskan langkah apa yang perlu diambil dan kapan berhenti.	Karyawan yang diberi tugas, bukan diberi SOP
Tool	Kemampuan konkret yang bisa dipanggil agent, dengan input dan output yang tervalidasi.	Alat kerja di meja karyawan itu
Memory	Yang membuat agent mengingat percakapan dan fakta tentang penggunanya.	Catatan dan ingatan si karyawan
Workflow	Proses yang langkahnya sudah pasti dan tidak diserahkan ke keputusan model.	SOP tertulis yang wajib diikuti urut
Storage	Tempat semua hal di atas bertahan setelah proses mati.	Lemari arsip kantor

Perbedaan antara Agent dan Workflow adalah yang paling sering membingungkan di awal, dan paling menentukan kualitas desainmu nanti. Pegang ini dulu:

• Agent dipakai saat langkahnya tidak diketahui di awal. Kamu memberi tujuan dan batasan; agent yang memutuskan tool mana dipanggil, berapa kali mengulang, dan kapan berhenti.
• Workflow dipakai saat langkahnya sudah kamu ketahui. Kamu yang menentukan urutan, percabangan, dan pengulangannya; model tidak diberi kebebasan memilih.

Keduanya bisa dicampur — sebuah workflow boleh memanggil agent sebagai salah satu langkahnya, dan sebuah agent boleh memanggil workflow sebagai tool. Ini dibahas di Bagian 4.

Bagaimana potongan-potongan itu bekerja bersama

Alurnya: pesan masuk ke agent, agent membaca konteks dari memory, memutuskan apakah perlu memanggil tool, menjalankan tool, membaca hasilnya, dan mengulang sampai punya jawaban. Sepanjang itu, memory menulis ke storage dan setiap langkah tercatat sebagai jejak yang bisa kamu periksa belakangan.

Yang penting dipahami dari diagram ini: agent bukan satu panggilan ke model. Ia sebuah loop. Satu pesan pengguna bisa memicu lima panggilan model dan tiga panggilan tool sebelum jawaban keluar. Pemahaman ini akan sangat membantu saat kamu membaca trace di Bagian 8.

Kapan Mastra berlebihan

Framework yang bagus adalah framework yang jujur soal batasnya. Kamu tidak butuh Mastra kalau:

• Yang kamu perlukan hanya satu panggilan model tanpa tool, tanpa riwayat, tanpa penyimpanan. Contoh: tombol "ringkas artikel ini" di sebuah halaman. Panggil API provider langsung; menambah framework hanya menambah lapisan.
• Alurnya benar-benar tetap dan tidak melibatkan pengambilan keputusan sama sekali. Contoh: ambil data, format jadi teks, kirim ke Slack. Itu skrip biasa, bukan agent.

Kamu mulai butuh Mastra begitu dua atau lebih dari ini muncul: tool, riwayat percakapan, percabangan yang bergantung hasil, jeda untuk persetujuan manusia, atau kebutuhan menelusuri kenapa keluarannya salah.

Kenapa TypeScript

Mastra ditulis untuk TypeScript, dan itu keputusan yang berpengaruh ke cara kamu bekerja sehari-hari. Skema input dan output tool didefinisikan dengan Zod, dan tipe yang dihasilkan mengalir ke seluruh sistem: keluaran satu langkah workflow menjadi tipe masukan langkah berikutnya, secara otomatis.

Akibat praktisnya, banyak kesalahan yang biasanya baru ketahuan saat runtime — salah nama field, lupa satu properti, tipe tidak cocok antar langkah — menjadi garis merah di editor sebelum kamu menjalankan apa pun. Di Bagian 4 kamu akan melihat ini bekerja pada rantai langkah yang panjang, dan di situ nilainya paling terasa.

Kesalahan umum

Gejala: Membangun agent untuk pekerjaan yang alurnya sudah pasti, lalu kebingungan karena hasilnya tidak konsisten antar pemanggilan. Penyebab: Agent memang dirancang untuk mengambil keputusan sendiri. Kalau kamu sudah tahu langkah 1, 2, 3, memberi kebebasan memilih ke model hanya menambah ketidakpastian tanpa manfaat. Perbaikan: Pakai workflow. Simpan agent untuk bagian yang benar-benar butuh penilaian, misalnya satu langkah "klasifikasikan keluhan ini" di tengah workflow yang selebihnya deterministik.

Gejala: Berharap agent tahu data internal perusahaan tanpa diberi tool atau sumber pengetahuan apa pun, lalu menyimpulkan modelnya "bodoh" karena mengarang. Penyebab: Model hanya tahu apa yang ada di data latihnya dan apa yang kamu kirim dalam konteks. Database-mu tidak termasuk keduanya. Perbaikan: Beri akses lewat tool (Bagian 2) atau lewat RAG (Bagian 5). Mengarang bukan kegagalan model, itu konsekuensi dari tidak diberi sumber.

Coba sendiri

Belum ada kode di bab ini, jadi latihannya berupa analisis desain. Ini justru keterampilan yang paling sering dipakai dan paling jarang dilatih.

Tantangan: Ambil satu ide aplikasi yang benar-benar ingin kamu bangun. Kalau belum punya, pakai ini: asisten yang membantu tim marketing menyusun laporan performa kampanye mingguan dari data Google Analytics dan Meta Ads.

Tulis jawaban singkat untuk empat pertanyaan berikut:

1. Bagian mana dari alurnya yang langkahnya sudah pasti, dan bagian mana yang butuh penilaian? Yang pertama calon workflow, yang kedua calon agent.
2. Kemampuan konkret apa saja yang harus disediakan sebagai tool? Sebutkan nama tool dan satu kalimat deskripsinya.
3. Apakah aplikasi ini butuh memory? Kalau ya, yang perlu diingat itu riwayat percakapan, atau fakta tentang penggunanya, atau keduanya?
4. Adakah titik yang butuh persetujuan manusia sebelum lanjut?

Checklist penerimaan:

• [ ] Kamu bisa menyebut minimal satu bagian yang lebih tepat sebagai workflow daripada agent, beserta alasannya
• [ ] Daftar tool-mu berisi kemampuan konkret, bukan hal abstrak seperti "menganalisis data" — kalau sebuah tool tidak bisa kamu bayangkan implementasinya sebagai fungsi biasa, ia terlalu abstrak
• [ ] Kamu punya jawaban jelas untuk pertanyaan memory, bukan "mungkin perlu"

Simpan jawaban ini. Di Bagian 10 kamu akan membangun sesuatu yang strukturnya mirip, dan enak sekali bisa membandingkan analisis awalmu dengan pemahamanmu setelah sembilan bagian.

Petunjuk: Kalau kesulitan memisahkan workflow dari agent, coba tanya: "kalau saya jelaskan proses ini ke karyawan baru, apakah saya memberinya daftar langkah, atau memberinya tujuan?" Daftar langkah berarti workflow.

Ikhtisar

• Mastra menyelesaikan infrastruktur di sekitar pemanggilan model — tool calling, validasi, loop eksekusi, memory, jeda dan lanjut, jejak eksekusi, evaluasi — bukan kecerdasan modelnya.
• Lima primitif inti: Agent (memutuskan), Tool (bertindak), Memory (mengingat), Workflow (proses pasti), Storage (bertahan).
• Aturan pemisah paling penting: langkah tidak diketahui → agent; langkah sudah diketahui → workflow. Keduanya bisa saling memanggil.
• Agent bukan satu panggilan model, melainkan loop yang bisa berputar beberapa kali sebelum menghasilkan jawaban.
• Mastra berlebihan untuk satu panggilan model sederhana; ia mulai berguna saat kebutuhanmu menyentuh dua atau lebih dari: tool, riwayat, percabangan, persetujuan manusia, atau penelusuran kesalahan.

Lanjut ke mana

Kamu sudah tahu Mastra itu apa. Berikutnya, kita bongkar isinya: paket apa saja yang membentuk Mastra dan di mana letak tiap file dalam sebuah proyek — 0.2 Peta Ekosistem & Anatomi Proyek.