Tutorial Mastra: Framework TypeScript untuk Membangun AI Agent dan Workflow
Mastra adalah framework open-source berbasis TypeScript yang dirancang untuk memudahkan developer membangun AI agent, workflow, dan RAG pipeline. Dengan Mastra, Anda bisa membuat aplikasi AI yang kompleks dengan kode yang terstruktur dan mudah di-maintain. Framework ini mendukung berbagai LLM provider, memiliki sistem tool yang fleksibel, dan menyediakan workflow engine yang powerful untuk orkestrasi tugas-tugas AI.
Dalam tutorial ini, kita akan membahas cara menggunakan Mastra mulai dari instalasi, membuat agent sederhana, membangun workflow multi-step, hingga mengintegrasikan RAG pipeline. Semua contoh kode bisa langsung dijalankan di project TypeScript Anda.
Mengapa Mastra?
Sebelum masuk ke implementasi, berikut beberapa alasan mengapa Mastra layak dipertimbangkan:
- TypeScript-first: Dibangun dari awal untuk TypeScript dengan type safety yang kuat
- Multi-provider LLM: Mendukung OpenAI, Anthropic, Google Gemini, dan provider lainnya melalui Vercel AI SDK
- Agent Framework: Sistem agent dengan tool calling, memory, dan structured output
- Workflow Engine: Step-based workflow dengan branching, parallel execution, dan error handling
- RAG Built-in: Pipeline RAG terintegrasi dengan dukungan berbagai vector database
- Observability: Tracing dan logging terintegrasi untuk monitoring agent
- Self-hostable: Bisa di-deploy di server sendiri atau menggunakan Mastra Cloud
Instalasi dan Setup
Prasyarat
Pastikan Anda sudah menginstal:
- Node.js versi 18 atau lebih baru
- npm atau pnpm sebagai package manager
- API key dari LLM provider (OpenAI, Anthropic, dll)
Membuat Project Baru
Cara tercepat memulai adalah menggunakan CLI Mastra:
npx create-mastra@latest my-ai-app
CLI akan menanyakan beberapa konfigurasi:
? Select components to install:
✔ Agents
✔ Tools
✔ Workflows
? Select default LLM provider:
✔ OpenAI
? Select example to include:
✔ Weather Agent
Setelah selesai, masuk ke direktori project:
cd my-ai-app
npm install
Setup Manual
Jika Anda ingin menambahkan Mastra ke project yang sudah ada:
npm install mastra @mastra/core @mastra/memory
Buat file konfigurasi environment:
# .env
OPENAIAPIKEY=sk-your-openai-key
ANTHROPICAPIKEY=sk-ant-your-anthropic-key
Struktur Project
Berikut struktur project Mastra yang direkomendasikan:
my-ai-app/
├── src/
│ ├── mastra/
│ │ ├── agents/
│ │ │ └── index.ts
│ │ ├── tools/
│ │ │ └── index.ts
│ │ ├── workflows/
│ │ │ └── index.ts
│ │ └── index.ts
│ └── index.ts
├── .env
├── package.json
└── tsconfig.json
Konsep Dasar
Inisialisasi Mastra
File utama untuk inisialisasi Mastra:
// src/mastra/index.ts
import { Mastra } from "@mastra/core";
import { createLogger } from "@mastra/core/logger";
import { weatherAgent } from "./agents";
export const mastra = new Mastra({
agents: { weatherAgent },
logger: createLogger({
name: "MyApp",
level: "info",
}),
});
Membuat Agent Pertama
Agent adalah komponen utama dalam Mastra. Setiap agent memiliki instruksi, model LLM, dan tools yang bisa digunakan:
// src/mastra/agents/index.ts,import { Agent } from "@mastra/core/agent";
import { openai } from "@ai-sdk/openai";
export const assistantAgent = new Agent({
name: "Assistant",
instructions:
Kamu adalah asisten AI yang membantu penggunamenjawab pertanyaan dengan akurat dan informatif.
Gunakan bahasa Indonesia yang baik dan benar.
model: openai("gpt-4o"),
});
Menggunakan agent:
import { mastra } from "./mastra";
async function main() {
const agent = mastra.getAgent("assistantAgent");
const response = await agent.generate(
"Jelaskan apa itu machine learning dalam 3 kalimat"
);
console.log(response.text);
}
main();
Membuat Custom Tools
Tools memungkinkan agent berinteraksi dengan dunia luar, seperti memanggil API, membaca database, atau melakukan kalkulasi.
Definisi Tool
// src/mastra/tools/index.ts
import { createTool } from "@mastra/core/tools";
import { z } from "zod";
export const weatherTool = createTool({
id: "get-weather",
description: "Mengambil data cuaca untuk kota tertentu",
inputSchema: z.object({
city: z.string().describe("Nama kota"),
unit: z.enum(["celsius", "fahrenheit"]).default("celsius"),
}),
outputSchema: z.object({
temperature: z.number(),
condition: z.string(),
humidity: z.number(),
}),
execute: async ({ context }) => {
const { city, unit } = context;
const response = await fetch(
https://api.weatherapi.com/v1/current.json?key=${process.env.WEATHERAPIKEY}&q=${city}
);
const data = await response.json();
return {
temperature: unit === "celsius"
? data.current.tempc
: data.current.tempf,
condition: data.current.condition.text,
humidity: data.current.humidity,
};
},
});
Tool untuk Database Query
import { createTool } from "@mastra/core/tools";
import { z } from "zod";
export const searchProductsTool = createTool({
id: "search-products",
description: "Mencari produk berdasarkan kata kunci dan kategori",
inputSchema: z.object({
query: z.string().describe("Kata kunci pencarian"),
category: z.string().optional().describe("Kategori produk"),
maxResults: z.number().default(10),
}),
execute: async ({ context }) => {
const { query, category, maxResults } = context;
// Simulasi database query
const products = await db.products.findMany({
where: {
name: { contains: query },
...(category && { category }),
},
take: maxResults,
});
return { products, total: products.length };
},
});
Menghubungkan Tool ke Agent
import { Agent } from "@mastra/core/agent";,import { openai } from "@ai-sdk/openai";
import { weatherTool, searchProductsTool } from "../tools";
export const smartAssistant = new Agent({
name: "SmartAssistant",
instructions:
Kamu adalah asisten cerdas yang bisa:Mengecek cuaca di berbagai kota Mencari produk di database Gunakan tools yang tersedia untuk menjawab pertanyaan pengguna.
model: openai("gpt-4o"),
tools: {
getWeather: weatherTool,
searchProducts: searchProductsTool,
},
});
Workflow Engine
Workflow di Mastra memungkinkan Anda mengorkestrasi serangkaian langkah yang kompleks dengan kontrol alur yang jelas.
Workflow Sederhana
// src/mastra/workflows/index.tsimport { Workflow, Step } from "@mastra/core/workflows";
import { z } from "zod";
const analyzeText = new Step({
id: "analyze-text",
inputSchema: z.object({
text: z.string(),
}),
outputSchema: z.object({
wordCount: z.number(),
sentiment: z.string(),
language: z.string(),
}),
execute: async ({ context }) => {
const text = context.inputData.text;
const words = text.split(/\s+/).length;
// Gunakan LLM untuk analisis sentiment
const agent = mastra.getAgent("assistantAgent");
const result = await agent.generate(
Analisis sentiment teks berikut dan jawab dengan satu kata(positif/negatif/netral): "${text}"
);
return {
wordCount: words,
sentiment: result.text.trim().toLowerCase(),
language: "id",
};
},
});
const generateReport = new Step({
id: "generate-report",
inputSchema: z.object({
wordCount: z.number(),
sentiment: z.string(),
language: z.string(),
}),
outputSchema: z.object({
report: z.string(),
}),
execute: async ({ context }) => {
const { wordCount, sentiment, language } = context.inputData;
return {
report:
Laporan Analisis Teks:
- Jumlah kata: ${wordCount}
- Sentimen: ${sentiment}
- Bahasa: ${language},
},
});
export const textAnalysisWorkflow = new Workflow({
name: "text-analysis",
triggerSchema: z.object({
text: z.string(),
}),
});
textAnalysisWorkflow
.step(analyzeText)
.then(generateReport)
.commit();
Menjalankan Workflow
import { mastra } from "./mastra";
async function runWorkflow() {
const workflow = mastra.getWorkflow("text-analysis");
const result = await workflow.execute({
triggerData: {
text: "Mastra adalah framework yang luar biasa untuk membangun aplikasi AI!",
},
});
console.log(result.results);
}
Workflow dengan Branching
import { Workflow, Step } from "@mastra/core/workflows";,import { z } from "zod";
const classifyIntent = new Step({
id: "classify-intent",
inputSchema: z.object({
message: z.string(),
}),
outputSchema: z.object({
intent: z.enum(["question", "complaint", "feedback"]),
confidence: z.number(),
}),
execute: async ({ context }) => {
const agent = mastra.getAgent("assistantAgent");
const result = await agent.generate({
messages: [
{
role: "user",
content:
Klasifikasikan intent dari pesan berikut ke salah satu:question, complaint, feedback.
Pesan: "${context.inputData.message}"
Jawab dalam format JSON: {"intent": "...", "confidence": 0.0-1.0}
},
],
});
return JSON.parse(result.text);
},
});
const handleQuestion = new Step({
id: "handle-question",
execute: async ({ context }) => {
return { response: "Terima kasih atas pertanyaan Anda. Tim kami akan segera menjawab." };
},
});
const handleComplaint = new Step({
id: "handle-complaint",
execute: async ({ context }) => {
return { response: "Kami mohon maaf atas ketidaknyamanan Anda. Keluhan Anda sudah dicatat." };
},
});
const handleFeedback = new Step({
id: "handle-feedback",
execute: async ({ context }) => {
return { response: "Terima kasih atas masukan Anda. Feedback Anda sangat berharga bagi kami." };
},
});
export const customerServiceWorkflow = new Workflow({
name: "customer-service",
triggerSchema: z.object({
message: z.string(),
}),
});
customerServiceWorkflow
.step(classifyIntent)
.then(handleQuestion, {
when: async ({ context }) => {
const result = context.getStepResult("classify-intent");
return result.intent === "question";
},
})
.after(classifyIntent)
.step(handleComplaint, {
when: async ({ context }) => {
const result = context.getStepResult("classify-intent");
return result.intent === "complaint";
},
})
.after(classifyIntent)
.step(handleFeedback, {
when: async ({ context }) => {
const result = context.getStepResult("classify-intent");
return result.intent === "feedback";
},
})
.commit();
RAG Pipeline dengan Mastra
Mastra menyediakan built-in support untuk RAG (Retrieval-Augmented Generation).
Setup Vector Store
// src/mastra/rag/index.ts
import { PgVector } from "@mastra/pg";
import { MDocument } from "@mastra/rag";
import { openai } from "@ai-sdk/openai";
import { embed } from "ai";
const pgVector = new PgVector({
connectionString: process.env.DATABASEURL!,
});
// Membuat index untuk menyimpan embeddings
await pgVector.createIndex({
indexName: "knowledge-base",
dimension: 1536,
metric: "cosine",
});
Ingesting Documents
import { MDocument } from "@mastra/rag";
import { embed, embedMany } from "ai";
import { openai } from "@ai-sdk/openai";
async function ingestDocuments(texts: string[]) {
const docs = texts.map(
(text) => MDocument.fromText(text)
);
// Chunk documents
const chunks = [];
for (const doc of docs) {
const docChunks = await doc.chunk({
strategy: "recursive",
size: 512,
overlap: 50,
});
chunks.push(...docChunks);
}
// Generate embeddings
const { embeddings } = await embedMany({
model: openai.embedding("text-embedding-3-small"),
values: chunks.map((chunk) => chunk.text),
});
// Store in vector database
await pgVector.upsert({
indexName: "knowledge-base",
vectors: embeddings.map((embedding, i) => ({
id: chunk-${i},
values: embedding,
metadata: {
text: chunks[i].text,
source: chunks[i].metadata?.source,
},
})),
});
console.log(Berhasil meng-ingest ${chunks.length} chunks);
}
RAG Agent
import { Agent } from "@mastra/core/agent";,import { openai } from "@ai-sdk/openai";
import { createTool } from "@mastra/core/tools";
import { z } from "zod";
import { embed } from "ai";
const searchKnowledgeBase = createTool({
id: "search-knowledge-base",
description: "Mencari informasi dari knowledge base perusahaan",
inputSchema: z.object({
query: z.string().describe("Query pencarian"),
topK: z.number().default(5),
}),
execute: async ({ context }) => {
const { query, topK } = context;
// Generate query embedding
const { embedding } = await embed({
model: openai.embedding("text-embedding-3-small"),
value: query,
});
// Search vector store
const results = await pgVector.query({
indexName: "knowledge-base",
queryVector: embedding,
topK,
includeMetadata: true,
});
return {
results: results.map((r) => ({
text: r.metadata?.text,
score: r.score,
})),
};
},
});
export const ragAgent = new Agent({
name: "RAGAssistant",
instructions:
Kamu adalah asisten yang menjawab pertanyaan berdasarkanknowledge base perusahaan. Selalu cari informasi di knowledge base
terlebih dahulu sebelum menjawab. Jika informasi tidak ditemukan,
sampaikan bahwa kamu tidak memiliki data yang relevan.
model: openai("gpt-4o"),
tools: {
searchKnowledgeBase,
},
});
Structured Output
Mastra mendukung structured output untuk mendapatkan respons dalam format yang konsisten:
import { Agent } from "@mastra/core/agent";
import { openai } from "@ai-sdk/openai";
import { z } from "zod";
const dataExtractor = new Agent({
name: "DataExtractor",
instructions: "Ekstrak informasi terstruktur dari teks yang diberikan.",
model: openai("gpt-4o"),
});
async function extractInvoiceData(text: string) {
const result = await dataExtractor.generate(
Ekstrak data invoice dari teks berikut: ${text},
{
output: z.object({
invoiceNumber: z.string(),
date: z.string(),
items: z.array(
z.object({
name: z.string(),
quantity: z.number(),
price: z.number(),
})
),
total: z.number(),
currency: z.string(),
}),
}
);
console.log(result.object);
// {
// invoiceNumber: "INV-2026-001",
// date: "2026-09-01",
// items: [{ name: "Konsultasi AI", quantity: 1, price: 15000000 }],
// total: 15000000,
// currency: "IDR"
// }
}
Memory dan Conversation History
Mastra menyediakan sistem memory untuk menyimpan konteks percakapan:
import { Agent } from "@mastra/core/agent";,import { Memory } from "@mastra/memory";
import { openai } from "@ai-sdk/openai";
import { PgMemory } from "@mastra/pg";
const memory = new Memory({
storage: new PgMemory({
connectionString: process.env.DATABASEURL!,
}),
options: {
lastMessages: 20,
semanticRecall: {
topK: 3,
messageRange: { before: 2, after: 1 },
},
},
});
export const chatAgent = new Agent({
name: "ChatAssistant",
instructions:
Kamu adalah asisten chat yang ramah.Ingat konteks percakapan sebelumnya untuk memberikan
respons yang relevan dan personal.
model: openai("gpt-4o"),
memory,
});
// Penggunaan dengan thread (session)
async function chat(threadId: string, message: string) {
const agent = mastra.getAgent("chatAgent");
const response = await agent.generate(message, {
threadId,
resourceId: "user-123",
});
return response.text;
}
// Percakapan multi-turn
await chat("thread-1", "Halo, nama saya Ruby");
await chat("thread-1", "Apa nama saya?"); // Agent akan ingat "Ruby"
Streaming Response
Untuk aplikasi real-time, gunakan streaming:
import { Agent } from "@mastra/core/agent";
import { openai } from "@ai-sdk/openai";
const streamAgent = new Agent({
name: "StreamAgent",
instructions: "Berikan penjelasan yang detail dan terstruktur.",
model: openai("gpt-4o"),
});
async function streamResponse(prompt: string) {
const stream = await streamAgent.stream(prompt);
for await (const chunk of stream.textStream) {
process.stdout.write(chunk);
}
}
// Streaming dengan tools
async function streamWithTools(prompt: string) {
const stream = await streamAgent.stream(prompt);
for await (const part of stream.fullStream) {
switch (part.type) {
case "text-delta":
process.stdout.write(part.textDelta);
break;
case "tool-call":
console.log(\nMemanggil tool: ${part.toolName});
break;
case "tool-result":
console.log(Hasil tool: ${JSON.stringify(part.result)});
break;
}
}
}
Multi-Agent Collaboration
Mastra memungkinkan beberapa agent bekerja sama:
import { Agent } from "@mastra/core/agent";import { openai } from "@ai-sdk/openai";
import { createTool } from "@mastra/core/tools";
import { z } from "zod";
// Agent spesialis riset
const researchAgent = new Agent({
name: "Researcher",
instructions: "Kamu adalah peneliti yang ahli mengumpulkan dan menganalisis informasi.",
model: openai("gpt-4o"),
});
// Agent spesialis penulisan
const writerAgent = new Agent({
name: "Writer",
instructions: "Kamu adalah penulis konten profesional yang menghasilkan artikel berkualitas tinggi.",
model: openai("gpt-4o"),
});
// Agent spesialis review
const reviewerAgent = new Agent({
name: "Reviewer",
instructions: "Kamu adalah editor yang mereview dan memperbaiki kualitas tulisan.",
model: openai("gpt-4o"),
});
// Orchestrate agents dalam workflow
async function createArticle(topic: string) {
// Step 1: Riset
const research = await researchAgent.generate(
Lakukan riset mendalam tentang: ${topic}.Berikan poin-poin utama dan data pendukung.
);
// Step 2: Penulisan
const draft = await writerAgent.generate(
Berdasarkan riset berikut, tulis artikel lengkap:${research.text}
);
// Step 3: Review
const finalArticle = await reviewerAgent.generate(
Review dan perbaiki artikel berikut. Pastikan akurat,jelas, dan menarik:
${draft.text}
);
return finalArticle.text;
}
Deployment dan Production
Menjalankan sebagai HTTP Server
// src/index.ts
import { mastra } from "./mastra";
const app = mastra.serve();
// Server berjalan di port 4111 (default)
// Endpoint tersedia:
// POST /api/agents/:agentId/generate
// POST /api/agents/:agentId/stream
// POST /api/workflows/:workflowId/execute
Docker Deployment
FROM node:20-slim
WORKDIR /app
COPY package.json ./
RUN npm ci --only=production
COPY . .
RUN npm run build
EXPOSE 4111
CMD ["node", "dist/index.js"]
Environment Variables untuk Production
# .env.production
NODEENV=production
OPENAIAPIKEY=sk-prod-key
DATABASEURL=postgresql://user:pass@host:5432/mastra
MASTRALOGLEVEL=warn
Best Practices
1. Desain Agent Instructions yang Jelas
// Baik - instruksi spesifik dan terstruktur,const agent = new Agent({
name: "SupportAgent",
instructions:
Kamu adalah agen customer support untuk toko online.Panduan:
- Jawab pertanyaan tentang produk, pengiriman, dan pengembalian
- Jika pertanyaan di luar cakupan, arahkan ke tim terkait
- Selalu tanyakan nomor pesanan untuk pertanyaan terkait order
- Gunakan bahasa Indonesia yang sopan dan profesional
Batasan:
- Jangan memberikan diskon tanpa persetujuan supervisor
- Jangan membagikan informasi internal perusahaan
model: openai("gpt-4o"),
});
2. Error Handling yang Tepat
const robustTool = createTool({
id: "api-call",
description: "Memanggil external API",
inputSchema: z.object({ endpoint: z.string() }),
execute: async ({ context }) => {
try {
const response = await fetch(context.endpoint, {
signal: AbortSignal.timeout(5000),
});
if (!response.ok) {
return { error: API returned ${response.status}, data: null };
}
return { error: null, data: await response.json() };
} catch (error) {
return {
error: error instanceof Error ? error.message : "Unknown error",
data: null,
};
}
},
});
3. Gunakan Zod Schema untuk Validasi
Selalu definisikan input dan output schema menggunakan Zod. Ini memastikan type safety dan memberikan deskripsi yang jelas kepada LLM tentang parameter yang diharapkan.
4. Monitoring dan Logging
import { Mastra } from "@mastra/core";
import { createLogger } from "@mastra/core/logger";
const mastra = new Mastra({
agents: { / ... */ },
logger: createLogger({
name: "Production",
level: process.env.NODE_ENV === "production" ? "warn" : "debug",
}),
});
5. Rate Limiting dan Caching
Implementasikan rate limiting pada tools yang memanggil external API, dan gunakan caching untuk query yang sering diulang. Ini menghemat biaya API dan meningkatkan performa aplikasi.
Kesimpulan
Mastra menyediakan fondasi yang solid untuk membangun aplikasi AI dengan TypeScript. Dengan fitur seperti agent framework, workflow engine, RAG pipeline, dan memory management, Anda bisa membangun aplikasi AI yang kompleks dengan kode yang bersih dan terstruktur.
Keunggulan utama Mastra adalah pendekatannya yang TypeScript-first dengan type safety yang kuat, integrasi yang mulus dengan berbagai LLM provider melalui Vercel AI SDK, dan kemampuan deployment yang fleksibel baik sebagai HTTP server maupun di container.
Untuk langkah selanjutnya, Anda bisa:
- Eksplorasi dokumentasi resmi Mastra untuk fitur lanjutan
- Mencoba integrasi dengan berbagai vector database untuk RAG
- Membangun multi-agent system yang lebih kompleks
- Mengimplementasikan evaluasi dan testing untuk agent Anda
- Bergabung dengan komunitas Mastra untuk berbagi pengalaman dan best practices