Bagian 11 — Proyek Akhir

Sembilan bagian sebelumnya mengajarkan potongan-potongan Mastra satu per satu. Bagian ini memintamu menyatukannya.

Ini spesifikasi, bukan tutorial. Tidak ada kode yang bisa disalin di halaman ini — hanya kebutuhan, batasan, dan kriteria penerimaan. Kalau kamu menemukan dirinya buntu, jawabannya ada di bab yang sudah kamu baca.

Yang akan kamu bangun

Asisten Operasional Toko Buku — sistem yang membantu tim sebuah toko buku daring mengelola pertanyaan pelanggan, memproses pengembalian barang, dan menghasilkan laporan mingguan.

Domainnya sengaja dipilih karena tiga alasan: cukup akrab untuk tidak perlu dijelaskan, cukup luas untuk menuntut semua kemampuan yang sudah dipelajari, dan punya titik-titik yang secara alami membutuhkan pengawasan manusia.

Boleh ganti domain

Kalau kamu punya domain sendiri yang lebih relevan dengan pekerjaanmu, pakai itu. Yang penting adalah kebutuhan fungsional di bawah tetap terpenuhi — domainnya hanya pembungkus.

Kebutuhan fungsional

F1 — Asisten percakapan

Satu agent yang melayani anggota tim lewat percakapan, dan mengingat konteks lintas sesi.

• Mengingat percakapan berjalan
• Mengingat preferensi tiap anggota tim lintas sesi — misalnya format laporan yang disukai, atau bahasa yang dipakai
• Menolak dengan sopan permintaan di luar urusan toko buku

F2 — Pengetahuan dari dokumen

Agent bisa menjawab pertanyaan kebijakan dari dokumen yang kamu sediakan sendiri: kebijakan pengembalian, syarat pengiriman, program keanggotaan.

• Minimal 10 halaman dokumen dalam format apa pun
• Jawaban harus bersumber dari dokumen, dan menyebutkan rujukannya
• Kalau jawabannya tidak ada di dokumen, agent mengatakannya terus terang

F3 — Tool untuk data

Minimal empat tool yang mengakses data toko. Data boleh berupa array dalam kode atau basis data sungguhan.

• Setidaknya satu tool yang hanya membaca
• Setidaknya satu tool yang mengubah keadaan
• Setidaknya satu tool yang bisa gagal karena sebab yang bisa diperkirakan — barang tidak ditemukan, stok habis
• Setidaknya dua tool yang cakupannya berdekatan, sehingga agent harus membedakannya dengan tepat

F4 — Alur pengembalian barang

Satu workflow untuk memproses permintaan pengembalian barang, dengan alur yang pasti.

• Minimal enam langkah
• Minimal satu bagian paralel
• Minimal satu percabangan — misalnya berdasarkan nilai atau alasan pengembalian
• Minimal satu pengulangan atas daftar item
• Satu titik suspend yang menunggu persetujuan manusia untuk pengembalian bernilai tinggi
• Minimal satu langkah yang memanggil agent, dengan keluaran terstruktur
• Minimal satu langkah yang memakai workflow state

F5 — Laporan terjadwal

Laporan mingguan yang dihasilkan otomatis tanpa diminta.

• Berjalan pada jadwal cron
• Merangkum aktivitas periode tersebut
• Dikirim ke thread, atau dihasilkan sebagai run terisolasi — pilih salah satu dan jelaskan alasannya

F6 — Antarmuka HTTP

Sistem bisa diakses lewat HTTP oleh aplikasi lain.

• Autentikasi terpasang
• Identitas pengguna mengalir dari autentikasi sampai ke lapisan data
• Minimal satu custom route di luar endpoint bawaan

Kebutuhan non-fungsional

N1 — Keamanan

• Tidak ada rahasia di dalam kode maupun riwayat git
• Tool yang mengubah keadaan memerlukan persetujuan
• Identitas pengguna tidak bisa dipalsukan lewat argumen tool atau lewat bujukan kalimat kepada agent
• Data satu pengguna tidak terlihat oleh pengguna lain

N2 — Keterlihatan

• Tracing aktif, dengan metadata yang membuat trace bisa dicari per pengguna
• Log terstruktur dan terkorelasi dengan trace
• Kamu bisa menunjukkan, dari trace saja, urutan lengkap satu permintaan yang melibatkan minimal dua tool

N3 — Mutu

• Minimal 15 kasus uji dalam suite evaluasi
• Minimal satu scorer kustom untuk aturan domain yang tidak dicakup scorer bawaan
• Minimal satu Quick Check yang tidak memanggil model
• Suite memakai gates dan threshold, dan kamu bisa memicu ketiga verdict
• Minimal empat kasus uji berada di perbatasan yang mudah salah

N4 — Biaya

• Loop agent dibatasi
• Scorer LLM tidak berjalan pada rate penuh untuk semuanya
• Model untuk pekerjaan latar belakang lebih ringan dari model utama
• Kamu bisa menyebutkan perkiraan biaya per percakapan, beserta cara kamu mendapatkannya

N5 — Kelayakan produksi

• Storage bukan berkas lokal
• Aplikasi berjalan di lingkungan selain laptopmu
• .env.example lengkap dan terbukti cukup untuk memulai dari nol

Peta kemampuan

Tabel ini memetakan tiap kebutuhan ke bab yang membahasnya. Pakai saat buntu.

Kebutuhan	Bab rujukan
F1 — Asisten percakapan	1.1, 1.2, 3.1, 3.2
F2 — Pengetahuan dokumen	5.2, 5.3
F3 — Tool	2.1, 2.2, 2.3
F4 — Workflow	4.1 sampai 4.5
F5 — Laporan terjadwal	7.2
F6 — HTTP	9.2
N1 — Keamanan	2.3, 9.3
N2 — Keterlihatan	8.1, 8.2
N3 — Mutu	8.3, 8.4
N4 — Biaya	1.2, 1.3, 3.4, 8.3
N5 — Produksi	9.1, 9.4

Arsitektur yang disarankan

Ini saran, bukan keharusan. Kalau kamu punya susunan yang lebih baik, pakai itu — tapi bisa menjelaskan alasannya.

Perhatikan bahwa workflow retur dipanggil dari agent — pola yang dibahas di 4.4. Agent menangani percakapan dan memutuskan kapan proses retur perlu dijalankan; workflow memastikan prosesnya berjalan dengan urutan yang benar setiap kali.

Urutan pengerjaan yang disarankan

Membangun semuanya sekaligus adalah cara tercepat untuk kewalahan. Urutan ini menjaga sistem tetap bisa dijalankan di setiap tahap:

1. Agent + dua tool baca — sesuatu yang jalan di Studio, hari pertama
2. Memory — history dan working memory
3. Dua tool sisanya, termasuk yang mengubah keadaan dengan persetujuan
4. RAG untuk dokumen kebijakan
5. Workflow retur, mulai dari versi lurus tanpa percabangan
6. Percabangan, paralel, dan suspend pada workflow itu
7. Observability — sebelum sistemnya cukup rumit untuk sulit didiagnosis
8. Auth dan server
9. Schedule
10. Suite evaluasi
11. Deploy

Langkah 7 sengaja diletakkan sebelum sistem selesai. Mendiagnosis workflow enam langkah tanpa trace jauh lebih menyakitkan daripada memasang tracing lebih awal.

Kriteria penerimaan

Proyek ini selesai ketika kamu bisa menunjukkan — bukan menjelaskan — hal-hal berikut:

Fungsi

• [ ] Agent menjawab pertanyaan kebijakan dengan menyebut rujukan dokumen
• [ ] Agent mengatakan "tidak tahu" untuk pertanyaan yang jawabannya tidak ada di dokumen
• [ ] Keempat tool dipanggil pada situasi yang tepat, terlihat di trace
• [ ] Dua tool yang berdekatan tidak pernah tertukar pada 10 percobaan
• [ ] Tool yang mengubah keadaan berhenti menunggu persetujuan
• [ ] Workflow retur menyelesaikan kasus bernilai rendah tanpa jeda
• [ ] Workflow retur berhenti pada kasus bernilai tinggi, dan bisa dilanjutkan dari proses yang berbeda setelah proses pertama dimatikan
• [ ] Preferensi anggota tim diingat lintas sesi
• [ ] Laporan terjadwal berjalan sesuai cron

Keamanan

• [ ] Permintaan tanpa token ditolak
• [ ] Pengguna A tidak bisa melihat data pengguna B — lewat API maupun lewat bujukan kalimat kepada agent
• [ ] Tidak ada userId di inputSchema tool mana pun
• [ ] Tidak ada rahasia di riwayat git

Mutu dan keterlihatan

• [ ] Suite evaluasi berjalan, dan kamu bisa memicu passed, scored, dan failed
• [ ] Scorer kustommu menangkap pelanggaran aturan domain yang tidak terdeteksi scorer bawaan
• [ ] Dari trace saja, kamu bisa merekonstruksi satu permintaan yang melibatkan dua tool
• [ ] Satu baris log error bisa dilacak ke trace-nya

Produksi

• [ ] Berjalan di lingkungan selain laptopmu
• [ ] Checklist rilis di 9.4 dijalankan, dengan keputusan sadar untuk tiap kotak yang tidak tercentang

Tantangan tambahan

Kalau semuanya selesai dan kamu ingin lebih jauh:

• Supervisor dan subagent — pecah asisten menjadi supervisor dengan subagent spesialis untuk kebijakan, pesanan, dan retur (7.3)
• MCP — ekspos tool tokomu sebagai MCP server, lalu pakai dari editormu (6.2)
• Durable agent — buat pertanyaan riset panjang bertahan terhadap koneksi yang putus (7.1)
• Observational memory — untuk sesi kerja yang berlangsung berhari-hari (3.4)
• Composite storage — rutekan observability ke backend analitik (9.1)

Satu saran terakhir

Bandingkan hasil akhirmu dengan jawaban yang kamu tulis di Coba sendiri bab 0.1 — saat kamu diminta memisahkan bagian mana yang cocok jadi agent dan mana yang cocok jadi workflow, sebelum tahu apa pun tentang Mastra.

Perbedaan antara keduanya adalah ukuran paling jujur dari apa yang kamu pelajari.