Tampilan
Referensi & Verifikasi
Halaman ini mencatat dari mana materi ini berasal, terhadap versi apa ia diverifikasi, dan — yang sama pentingnya — apa yang tidak berhasil diverifikasi.
Tanggal verifikasi: 6 September 2026.
Versi yang diverifikasi
Seluruh contoh kode dalam materi ini diuji dengan tsc --noEmit terhadap versi berikut:
| Paket | Versi |
|---|---|
@mastra/core | 1.64.0 |
@mastra/libsql | 1.22.3 |
@mastra/memory | 1.28.2 |
@mastra/rag | 2.6.1 |
@mastra/pg | 1.22.3 |
@mastra/mcp | 1.17.3 |
@mastra/evals | 1.10.0 |
@mastra/observability | 1.17.5 |
@mastra/loggers | 1.3.1 |
ai | 7.0.93 |
zod | 4.5.4 |
typescript | 6.0.3 |
Node.js yang dipakai: v22.17.0.
Metode verifikasi
Materi ini tidak disusun dari ingatan atau dari hasil pencarian web. Tiga lapis sumber dipakai, dengan urutan prioritas:
- Dokumentasi tertanam di
node_modules/@mastra/*/dist/docs/— sekitar 350 berkas yang version-exact terhadap paket yang terpasang. Ini sumber paling andal, karena ia dikirim bersama versi paketnya. - Definisi tipe di
node_modules/@mastra/*/dist/**/*.d.ts— dipakai saat dokumentasi tidak jelas atau saling bertentangan. - Compiler — tiap contoh ditempel ke proyek sandbox terpisah dengan versi terpin, lalu dijalankan
npx tsc --noEmit. Contoh yang gagal diperbaiki sebelum masuk materi.
Lapis ketiga yang paling menentukan, dan menangkap beberapa hal yang lolos dari kedua lapis sebelumnya.
Koreksi terhadap dokumentasi resmi
Selama penyusunan, lima contoh dalam dokumentasi resmi terbukti tidak kompilasi terhadap versi di atas. Materi ini memakai bentuk yang lolos compiler, bukan bentuk yang tertulis di dokumentasi.
| Yang tertulis di docs | Yang benar | Dibahas di |
|---|---|---|
doc.chunk({ size: 512 }) | maxSize | 5.2 |
extract: { metadata: true } | title, summary, questions, keywords, schema | 5.2 |
reranker: { model: 'openai/...' } | new ModelRouterLanguageModel('openai/...') | 5.3 |
observe.log.info(...) | observe.log('info', ...) | 8.2 |
observability: { default: { enabled: true } } | observability: new Observability({ ... }) | 8.1 |
Dua catatan tentang tabel ini. Pertama, ini bukan kritik terhadap dokumentasi Mastra — proyek yang bergerak cepat wajar punya halaman yang tertinggal. Kedua, ini alasan konkret kenapa menyalin kode dari hasil pencarian berisiko, bahkan ketika sumbernya terlihat resmi.
Yang tidak berhasil diverifikasi
Bagian ini sengaja ditulis terbuka. Hal-hal berikut tidak melewati type-check, dan kamu sebaiknya memverifikasinya sendiri sebelum mengandalkannya.
Sumber resmi yang saling bertentangan
Nama environment variable untuk Google. Dokumentasi agent menyebut GOOGLE_API_KEY; panduan pembuatan proyek menyebut GOOGLE_GENERATIVE_AI_API_KEY. Keduanya sumber resmi, dan tidak ada cara memilih di antaranya lewat type-check karena ini nilai runtime.
Kalau kamu memakai Google, periksa https://mastra.ai/models/environment-variables. Untuk OpenAI dan Anthropic, kedua sumber sepakat. → Ditandai di 0.3
Contoh yang tidak diuji compiler
Paket berikut tidak dipasang di sandbox verifikasi, sehingga contoh yang memakainya hanya bersumber dari dokumentasi:
| Paket | Dipakai di | Catatan |
|---|---|---|
@mastra/acp | 6.3 | Contoh AcpAgent |
@mastra/openai | 6.3 | Contoh OpenAISDKAgent |
@mastra/auth-clerk | 9.3 | Contoh CompositeAuth dengan Clerk — bentuk CompositeAuth-nya sendiri sudah diverifikasi dengan dua SimpleAuth |
@mastra/duckdb | 9.1 | Pola composite storage-nya diverifikasi tanpa bagian DuckDB |
@mastra/fastembed | 5.2 | Disebut sebagai opsi, tanpa contoh kode |
Hal yang tidak bisa diverifikasi lewat type-check
Sebagian materi menyangkut perilaku runtime, bukan bentuk API — dan compiler tidak bisa membuktikannya:
- Perilaku sampling deterministik berdasarkan trace ID (8.3)
- Isi daftar putih environment variable untuk subprocess Stdio (6.1)
- Bobot bawaan reranker: semantic 0.4, vector 0.4, position 0.2 (5.3)
- Perilaku
LocalSandboxtanpa isolasi native (7.4)
Semuanya bersumber dari dokumentasi resmi dan disebutkan apa adanya, tapi tidak diuji secara empiris di sini.
Fitur bertanda Beta
Dokumentasi resmi menandai fitur berikut sebagai Beta, dengan catatan bahwa perubahan yang memutus kompatibilitas bisa terjadi tanpa kenaikan versi mayor:
- Durable Agents (sejak
@mastra/core@1.45.0) - Goals (sejak
@mastra/core@1.42.0) - Schedules (sejak
@mastra/core@1.50.0) - Signals (sejak
@mastra/core@1.39.0)
Seluruhnya dibahas di Bagian 7. Pin versimu, dan baca catatan rilis sebelum menaikkan versi.
Sumber utama
Dokumentasi resmi
- Indeks dokumentasi: https://mastra.ai/llms.txt — titik masuk yang ramah dibaca mesin untuk menemukan URL docs per topik
- Dokumentasi: https://mastra.ai/docs — tiap halaman punya versi
.mdyang lebih bersih, misalnyahttps://mastra.ai/docs/agents/tools.md - Referensi API: https://mastra.ai/reference — rujukan final untuk signature dan tipe
- Kursus resmi: https://mastra.ai/course — "Mastra 101", empat lesson dasar yang dijalankan lewat MCP agent di dalam editor
Katalog model
- Model chat: https://mastra.ai/models
- Model embedding: https://mastra.ai/models/embeddings
- Environment variable per penyedia: https://mastra.ai/models/environment-variables
Nama model berubah sering. Ketiga halaman ini adalah rujukan yang benar; jangan mengandalkan daftar mana pun yang tertulis di materi ini, termasuk yang di 0.3.
Cara memverifikasi ulang materi ini
Kalau kamu memakai versi Mastra yang lebih baru dan ingin memeriksa apakah sesuatu berubah, prosedurnya sama seperti yang dipakai menyusun materi ini:
bash
# 1. Buat proyek sandbox dengan versimu
mkdir sandbox && cd sandbox
npm init -y
npm install @mastra/core@latest zod@^4
npm install -D typescript @types/nodePakai tsconfig.json dari 0.3, tambahkan "types": ["node"].
bash
# 2. Tempel contoh yang ingin diperiksa ke src/, lalu
npx tsc --noEmitUntuk memeriksa bentuk API yang benar saat sebuah contoh gagal:
bash
# Dokumentasi version-exact yang dikirim bersama paket
ls node_modules/@mastra/core/dist/docs/references/
# Definisi tipe, saat dokumentasi tidak jelas
grep -rn "NamaTipe" node_modules/@mastra/core/dist/**/*.d.tsDokumentasi tertanam di node_modules adalah temuan paling berguna dari seluruh proses ini: ia selalu cocok dengan versi yang benar-benar kamu pakai, dan tersedia tanpa koneksi internet.
Batasan materi ini
Beberapa area dokumentasi resmi tidak dibahas di sini, dan sebaiknya kamu tahu apa saja:
- Voice — text-to-speech, speech-to-text, dan speech-to-speech
- Channels — integrasi Slack, Discord, Telegram, WhatsApp, Teams, iMessage
- Processors — input dan output processor, guardrails, PII detection
- Agent Controller — sesi interaktif dengan mode, approval, dan event
- Networks — sudah deprecated, digantikan pola supervisor (7.3)
- Datasets & Experiments — disinggung di 8.4 tanpa dibahas tuntas
- Dynamic workflows dan time travel
- Editor — mengubah instruksi agent tanpa menyentuh kode
Semuanya bisa ditemukan lewat https://mastra.ai/llms.txt. Setelah menyelesaikan sepuluh bagian materi ini, kamu punya cukup dasar untuk membaca dokumentasi resminya secara langsung — dan itu memang tujuannya.