0.2 Peta Ekosistem & Anatomi Proyek

Tujuan bab

Setelah bab ini kamu bisa:

• Menjelaskan pembagian tugas antara @mastra/core dan paket-paket pendamping
• Menentukan paket mana yang perlu dipasang untuk sebuah kebutuhan, tanpa menebak
• Menyebutkan isi tiap folder dalam proyek Mastra standar dan kapan kamu menyentuhnya
• Menjelaskan peran src/mastra/index.ts dan kenapa lupa mendaftar di situ adalah sumber bug yang sering

Prasyarat

• 0.1 Apa Itu Mastra — kamu perlu paham lima primitif inti sebelum tahu paket mana yang menyediakannya

Kenapa Mastra dipecah jadi banyak paket

Saat pertama melihat daftar paket Mastra, reaksi wajarnya adalah bingung: kenapa tidak satu paket saja? Alasannya praktis. Sebuah aplikasi yang hanya butuh agent dan tool tidak seharusnya ikut mengunduh driver PostgreSQL, klien Redis, dan pustaka pemrosesan audio.

Jadi pembagiannya begini: satu paket inti yang berisi seluruh primitif dan antarmukanya, lalu paket-paket terpisah untuk tiap implementasi konkret.@mastra/core tahu apa itu "storage" sebagai konsep; @mastra/libsql yang tahu cara benar-benar menulis ke libSQL.

Konsekuensi yang perlu kamu ingat: hampir semua yang kamu impor berasal dari @mastra/core. Paket lain masuk hanya saat kamu memilih sebuah backend atau kemampuan tambahan.

Peta ekosistem

Dibaca sebagai tabel keputusan — "kalau butuh X, pasang Y":

Kebutuhan	Paket	Dibahas di
Agent, tool, workflow, scorer, antarmuka storage	@mastra/core	Bagian 1, II, IV
Agent yang mengingat percakapan	@mastra/memory	Bagian 3
Penyimpanan lokal berbasis file, dan vector store sederhana	@mastra/libsql	3.1, 9.1
Penyimpanan produksi di PostgreSQL	@mastra/pg	9.1
Memotong dokumen dan membuat embedding	@mastra/rag	Bagian 5
Embedding lokal tanpa API eksternal	@mastra/fastembed	5.2
Menyambung ke MCP server, atau menjadi MCP server	@mastra/mcp	Bagian 6
Memanggil server Mastra dari browser	@mastra/client-js	9.2
Trace, metrik, dan log terstruktur	@mastra/observability, @mastra/loggers	Bagian 8
Penyimpanan telemetri analitik	@mastra/duckdb	8.1
Scorer bawaan untuk mengukur mutu keluaran	@mastra/evals	8.3
Autentikasi lewat penyedia identitas	@mastra/auth-* (mis. auth-clerk, auth-auth0, auth-supabase)	9.3
Membungkus aplikasi untuk di-deploy	@mastra/deployer	9.4

Jangan pasang semuanya di awal

Godaan terbesar setelah melihat tabel ini adalah memasang sepuluh paket sekaligus "supaya siap". Jangan. Pasang saat kamu sampai di bab yang membutuhkannya. Proyek dengan paket yang tidak dipakai lebih sulit dipahami dan lebih lama dibangun.

Anatomi proyek

Proyek yang dibuat lewat CLI Mastra punya bentuk seperti ini:

src/
├── mastra/
│   ├── agents/
│   │   └── weather-agent.ts
│   ├── tools/
│   │   └── weather-tool.ts
│   ├── workflows/
│   │   └── weather-workflow.ts
│   ├── scorers/
│   │   └── weather-scorer.ts
│   └── index.ts
├── .env.example
├── package.json
└── tsconfig.json

Peran tiap folder:

Lokasi	Isi	Kamu menyentuhnya saat
src/mastra/	Akar semua kode Mastra	—
src/mastra/agents/	Definisi agent: perilaku, tujuan, tool yang dipegang	Menambah atau mengubah agent
src/mastra/tools/	Tool yang bisa dipanggil agent	Menambah kemampuan konkret
src/mastra/workflows/	Proses multi-langkah	Menyusun alur yang pasti
src/mastra/scorers/	Penilai mutu keluaran	Bagian 8
src/mastra/mcp/	MCP server buatan sendiri	Bagian 6
src/mastra/index.ts	Titik masuk: tempat semuanya didaftarkan	Setiap kali menambah komponen baru

Dua konvensi folder yang bersifat khusus dan perlu kamu ketahui sejak awal:

• src/mastra/agents/<nama>/ — sebuah agent bisa didefinisikan lewat konvensi file, bukan lewat konstruktor di kode. Ini disebut file-based agents.
• src/mastra/public/ — isinya disalin ke direktori keluaran saat build, sehingga bisa disajikan saat runtime.

Mastra sengaja tidak kaku

Dokumentasi resminya menyebut Mastra "mostly unopinionated" soal penataan file. Struktur di atas adalah default CLI yang cocok untuk kebanyakan proyek, bukan aturan yang dipaksakan. Kamu bahkan bisa menaruh semuanya di satu file kalau mau. Yang penting: pilih satu pola dan konsisten.

File yang paling sering jadi sumber bug

Dari semua file di atas, src/mastra/index.ts yang paling layak diperhatikan. Isinya sederhana:

// src/mastra/index.ts
import { Mastra } from '@mastra/core'
import { weatherAgent } from './agents/weather-agent.ts'

export const mastra = new Mastra({
  agents: { weatherAgent },
})

Yang penting dipahami: membuat sebuah agent tidak sama dengan mendaftarkannya. File weather-agent.ts yang meng-export sebuah Agent sudah membuat objeknya, tapi selama ia tidak masuk ke new Mastra(...), runtime Mastra tidak tahu ia ada. Akibatnya agent itu tidak muncul di Studio, tidak bisa diambil lewat mastra.getAgentById(), dan tidak terhubung ke storage atau observability yang kamu konfigurasi di instance Mastra.

Ini penyebab paling umum dari keluhan "agent saya tidak muncul", dan kabar baiknya, ini juga yang paling cepat diperiksa.

Perhatikan juga ./agents/weather-agent.ts — ekstensi .ts ditulis eksplisit pada impor file lokal. Ini bukan kebiasaan lama dari CommonJS, melainkan keharusan pada konfigurasi ES module yang dipakai Mastra.

Kesalahan umum

Gejala: Agent atau workflow yang sudah kamu tulis tidak muncul di Mastra Studio, dan mastra.getAgentById('...') mengembalikan nilai kosong atau melempar error. Penyebab: Komponen itu dibuat dan di-export, tapi belum didaftarkan di new Mastra({ ... }) pada src/mastra/index.ts. Perbaikan: Impor dan masukkan ke properti yang sesuai (agents, tools, workflows, scorers). Jadikan ini langkah refleks setiap kali membuat komponen baru.

Gejala: Error saat menjalankan proyek, dengan pesan seputar Cannot find module atau ERR_MODULE_NOT_FOUND yang menunjuk ke file lokalmu sendiri, padahal file itu jelas ada. Penyebab: Ekstensi file tidak ditulis pada impor lokal — misalnya from './agents/weather-agent' tanpa .ts. Perbaikan: Tulis ekstensinya. Pada proyek Mastra, impor lokal memakai ./agents/weather-agent.ts.

Coba sendiri

Tantangan: Kembali ke aplikasi yang kamu analisis di Coba sendiri bab 0.1. Sekarang terjemahkan analisis itu menjadi rencana struktur file dan daftar dependensi.

Tulis dua hal:

1. Struktur folder aplikasi itu dalam bentuk ASCII tree, mengikuti konvensi Mastra. Beri nama file yang spesifik — laporan-mingguan-workflow.ts, bukan workflow1.ts.
2. Daftar paket yang perlu dipasang, satu baris per paket, masing-masing dengan alasan satu kalimat kenapa dibutuhkan.

Checklist penerimaan:

• [ ] Setiap tool dari analisis bab 0.1 punya satu file di src/mastra/tools/
• [ ] Ada src/mastra/index.ts di dalam struktur
• [ ] Daftar paketmu memuat @mastra/core, dan setiap paket lain punya alasan konkret — kalau kamu tidak bisa menyebut alasannya, coret paket itu
• [ ] Tidak ada paket yang masuk daftar hanya karena "mungkin nanti perlu"

Petunjuk: Kalau ragu apakah butuh @mastra/memory, tanya: apakah pengguna akan mengirim pesan kedua yang merujuk ke pesan pertama? Kalau ya, kamu butuh.

Ikhtisar

• Mastra dipecah menjadi satu paket inti + banyak paket implementasi supaya kamu tidak mengunduh backend yang tidak dipakai.
• Hampir semua impor datang dari @mastra/core; paket lain masuk hanya saat kamu memilih backend atau kemampuan tertentu.
• Struktur folder standar: agents/, tools/, workflows/, scorers/, dan index.ts sebagai titik masuk. Strukturnya anjuran, bukan paksaan.
• Membuat komponen ≠ mendaftarkannya. Komponen yang tidak masuk ke new Mastra({ ... }) tidak dikenali runtime — ini sumber bug paling umum bagi pemula.
• Impor file lokal wajib menyertakan ekstensi .ts.

Lanjut ke mana

Peta sudah di tangan. Saatnya menjalankan sesuatu: membuat proyek pertama, mengatur API key, dan membuka Studio — 0.3 Proyek Pertama & Model Router.