Tutorial Mastra: Framework TypeScript untuk Membangun AI Agent dan Workflow

# 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, wor...

By Ruby Abdullah · · tutorial
MastraTypeScriptAI AgentsWorkflowRAG

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 pengguna

menjawab 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.ts
    

    import { 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 berdasarkan

    knowledge 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

    Artikel Terkait

    Tutorial Lengkap Dify: Platform Open-Source untuk Membangun Aplikasi AI

    Tutorial Lengkap Dify: Platform Open-Source untuk Membangun Aplikasi AI Dify adalah platform open-source yang memungkink...

    Tutorial Lengkap Griptape: Framework Python untuk Membangun AI Agent dan Pipeline

    Tutorial Lengkap Griptape: Framework Python untuk Membangun AI Agent dan Pipeline Griptape adalah framework open-source ...

    Tutorial Lengkap Tavily: AI Search API untuk RAG dan AI Agents

    Tutorial Lengkap Tavily: AI Search API untuk RAG dan AI Agents Tavily adalah search API yang dirancang khusus untuk apli...

    Tutorial LangChain: Framework Paling Populer untuk Membangun Aplikasi LLM

    Tutorial LangChain: Framework Paling Populer untuk Membangun Aplikasi LLM LangChain adalah framework open-source yang di...