Mastra: 24K+ Stars — Token 비용을 4-10배 절감하는 TypeScript AI 프레임워크 2026

// Mastra 핵심 아키텍처 — 6가지 원시 요소를 한 설정에
import { Mastra } from '@mastra/core';
import { openai } from '@ai-sdk/openai';

const mastra = new Mastra({
  agents: {
    supportAgent,
    researchAgent,
  },
  workflows: {
    ticketPipeline,
  },
  storage: new PgStorage({ connectionString: process.env.DATABASE_URL }),
  vectorStore: new PgVector(connectionString),
  telemetry: otel,
});

# 인터랙티브 CLI로 새 Mastra 프로젝트 스캐폴드
npm create mastra@latest

# 마법사가 묻는 항목:
# - 프로젝트 이름
# - 구성 요소 (에이전트, 워크플로우, RAG, 메모리)
# - LLM 제공자 (OpenAI, Anthropic, Google 등)
# - 예제 코드 포함 여부

# 스키마 검증용 Zod와 함께 핵심 패키지 설치
npm install @mastra/core@latest zod@^4

# AI SDK에서 선호하는 LLM 제공자 설치
npm install @ai-sdk/openai

# 선택적: 벡터 저장소, 메모리, 배포 패키지
npm install @mastra/pg @mastra/memory @mastra/deployer-vercel

# .env — Mastra가 런타임에 자동 로드
OPENAI_API_KEY=sk-xxxx
DATABASE_URL=postgresql://user:pass@localhost:5432/mastra

# localhost:4111에서 로컬 개발 UI 시작
npx mastra dev

# Studio를 통해 에이전트와 채팅, 도구 호출 검사,
# 메모리 상태 보기, 워크플로우 시각화, 프롬프트 반복 가능

// src/mastra/agents/support.ts
import { Agent } from '@mastra/core';
import { openai } from '@ai-sdk/openai';
import { createTool } from '@mastra/core';
import { z } from 'zod';

const searchTool = createTool({
  id: 'search-docs',
  description: '낮부 문서 검색',
  inputSchema: z.object({
    query: z.string().describe('검색 쿼리'),
  }),
  execute: async ({ context }) => {
    const results = await searchInternalDocs(context.query);
    return { results };
  },
});

export const supportAgent = new Agent({
  name: 'SupportAgent',
  instructions: `당신은 기술 지원 에이전트입니다. 검색 도구를 사용하여
    질문에 답하세요. 간결하고 출처를 인용하세요.`,
  model: openai('gpt-4o'),
  tools: { searchTool },
});

// 일반 텍스트 대신 타입 객체 얻기
const result = await supportAgent.generate(
  '이 티켓을 분류하세요: "Vercel에 배포할 수 없습니다"',
  {
    output: z.object({
      category: z.enum(['deployment', 'billing', 'bug', 'feature']),
      priority: z.enum(['low', 'medium', 'high', 'critical']),
      summary: z.string(),
      actionItems: z.array(z.string()),
    }),
  }
);

// result.object는 완전히 타입화됨 — TypeScript가 구조를 알고 있음
console.log(result.object.priority); // 'high' | 'low' | 'medium' | 'critical'

// 채팅 UI를 위한 실시간 Token 스트리밍
const stream = await supportAgent.stream(
  '환경 변수를 어떻게 구성하나요?'
);

for await (const chunk of stream.textStream) {
  process.stdout.write(chunk); // Token이 도착하는 대로 즉시 쓰기
}

// src/mastra/workflows/ticket.ts
import { Workflow, Step } from '@mastra/core';
import { z } from 'zod';

const classifyStep = new Step({
  id: 'classify',
  inputSchema: z.object({ ticketText: z.string() }),
  outputSchema: z.object({ category: z.string(), priority: z.string() }),
  execute: async ({ input, mastra }) => {
    const agent = mastra.getAgent('supportAgent');
    const result = await agent.generate(
      `분류: ${input.ticketText}`,
      { output: z.object({ category: z.string(), priority: z.string() }) }
    );
    return result.object;
  },
});

const escalateStep = new Step({
  id: 'escalate',
  outputSchema: z.object({ escalated: z.boolean() }),
  execute: async ({ input }) => {
    await sendSlackAlert(`높은 우선순위: ${input.ticketText}`);
    return { escalated: true };
  },
});

const autoRespondStep = new Step({
  id: 'auto-respond',
  outputSchema: z.object({ sent: z.boolean() }),
  execute: async ({ input }) => {
    await sendAutoReply(input.ticketText);
    return { sent: true };
  },
});

export const ticketPipeline = new Workflow({
  name: 'ticket-pipeline',
  triggerSchema: z.object({ ticketText: z.string() }),
})
  .step(classifyStep)
  .then(escalateStep, {
    when: { 'classify.priority': 'high' },
  })
  .then(autoRespondStep, {
    when: { 'classify.priority': ['low', 'medium'] },
  });

// .after()로 병렬 단계 실행
import { Workflow, Step } from '@mastra/core';

const stepA = new Step({ id: 'fetch-user', /* ... */ });
const stepB = new Step({ id: 'fetch-orders', /* ... */ });
const stepC = new Step({ id: 'fetch-preferences', /* ... */ });
const stepD = new Step({ id: 'combine', /* ... */ });

const parallelWorkflow = new Workflow({
  name: 'parallel-fetch',
  triggerSchema: z.object({ userId: z.string() }),
})
  .step(stepA)
  .step(stepB)
  .step(stepC)
  .after(stepA, stepB, stepC)
  .step(stepD); // stepD는 A, B, C가 모두 완료된 후에만 실행

// app/api/agent/route.ts — Next.js에서 에이전트를 API 라우트로 노출
import { mastra } from '@/mastra';
import { NextResponse } from 'next/server';

export async function POST(req: Request) {
  const { message } = await req.json();
  const agent = mastra.getAgent('supportAgent');

  const stream = await agent.stream(message);

  return new Response(stream.textStream, {
    headers: { 'Content-Type': 'text/event-stream' },
  });
}

# Mastra 빌드 시 Hono HTTP 서버가 번들링됨
npx mastra build

# 출력 경로: .mastra/output/
# Hono 서버는 에이전트, 워크플로우, 메모리를 REST 엔드포인트로 노출

npx mastra start
# 서버가 http://localhost:4111에서 실행

// Mastra는 낮은 수준에서 AI SDK 제공자를 사용
import { openai } from '@ai-sdk/openai';
import { anthropic } from '@ai-sdk/anthropic';
import { google } from '@ai-sdk/google';

// 한 줄로 제공자 전환
const agent = new Agent({
  name: 'MultiProviderAgent',
  instructions: '당신은 유용한 도우미입니다.',
  model: openai('gpt-4o'), // 또는 anthropic('claude-sonnet-4') 또는 google('gemini-2.0-pro')
  tools: { searchTool, calcTool },
});

// 10,000개 이상의 사용 가능한 MCP 서버에 연결
import { MCPClient } from '@mastra/core';

const mcpClient = new MCPClient({
  servers: {
    slack: {
      command: 'npx',
      args: ['-y', '@modelcontextprotocol/server-slack'],
      env: { SLACK_BOT_TOKEN: process.env.SLACK_TOKEN },
    },
    github: {
      command: 'npx',
      args: ['-y', '@modelcontextprotocol/server-github'],
      env: { GITHUB_PERSONAL_ACCESS_TOKEN: process.env.GITHUB_TOKEN },
    },
  },
});

// MCP 도구가 에이전트에 자동으로 사용 가능해짐
const tools = await mcpClient.tools();
const agent = new Agent({
  name: 'MCPAgent',
  model: openai('gpt-4o'),
  tools, // 모든 MCP 도구가 이제 사용 가능
});

import { Mastra } from '@mastra/core';
import { ObservationalMemory } from '@mastra/memory';
import { PgStorage } from '@mastra/pg';

const mastra = new Mastra({
  agents: { supportAgent },
  memory: new ObservationalMemory({
    storage: new PgStorage({ connectionString: process.env.DATABASE_URL }),
    observerModel: openai('gpt-4o-mini'), // Observer 에이전트 실행
    reflectorModel: openai('gpt-4o-mini'), // Reflector 에이전트 실행
    compressionInterval: 5, // 5개 메시지마다 압축
  }),
});

import { MastraRAG } from '@mastra/rag';
import { openai } from '@ai-sdk/openai';
import { PgVector } from '@mastra/pg';

const rag = new MastraRAG({
  embedder: openai.embedding('text-embedding-3-small'),
  vectorStore: new PgVector({
    connectionString: process.env.DATABASE_URL,
    dimension: 1536,
  }),
  chunkSize: 512,
  chunkOverlap: 50,
});

// 문서 인덱싱
await rag.index(documentBatch);

// 유사성 검색으로 쿼리
const results = await rag.query('SSO를 어떻게 구성하나요?', { topK: 5 });

import { Mastra } from '@mastra/core';
import { NodeSDK } from '@opentelemetry/sdk-node';

const otel = new NodeSDK({
  traceExporter: new OTLPTraceExporter({
    url: 'https://api.honeycomb.io/v1/traces',
  }),
});

const mastra = new Mastra({
  agents: { supportAgent },
  workflows: { ticketPipeline },
  telemetry: otel,
});

// 트레이스가 관측 플랫폼에 자동으로 나타남
// 모든 에이전트 호출, 도구 실행, 워크플로우 단계가 자동 계측됨

import { Agent } from '@mastra/core';
import { createGuardrail } from '@mastra/core';

const promptInjectionGuard = createGuardrail({
  id: 'no-prompt-injection',
  check: async ({ input }) => {
    const suspicious = /ignore previous|disregard instructions/i.test(input);
    return { passed: !suspicious, message: suspicious ? '인젝션 감지' : undefined };
  },
});

const piiGuard = createGuardrail({
  id: 'no-pii',
  check: async ({ output }) => {
    const hasPii = /\b\d{3}-\d{2}-\d{4}\b/.test(output); // SSN 패턴
    return { passed: !hasPii, message: hasPii ? 'PII 유출 감지' : undefined };
  },
});

const agent = new Agent({
  name: 'SafeAgent',
  model: openai('gpt-4o'),
  tools: { searchTool },
  guardrails: [promptInjectionGuard, piiGuard],
});

import { Workflow, Step } from '@mastra/core';

const humanApprovalStep = new Step({
  id: 'await-approval',
  outputSchema: z.object({ approved: z.boolean() }),
  execute: async ({ suspend }) => {
    // 워크플로우 일시 중지 후 인간 입력 대기
    const { approved } = await suspend({ reason: '환불 금액이 $500을 초과함' });
    return { approved };
  },
});

// 사람이 Studio 또는 API 호출로 승인하면 워크플로우 재개
const refundWorkflow = new Workflow({
  name: 'refund-pipeline',
  triggerSchema: z.object({ amount: z.number(), orderId: z.string() }),
})
  .step(validateStep)
  .then(humanApprovalStep)
  .then(processRefundStep, { when: { 'await-approval.approved': true } });

# 프로덕션 배포용 Dockerfile
FROM node:22-slim

WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production

COPY . .
RUN npx mastra build

EXPOSE 4111
CMD ["node", ".mastra/output/index.mjs"]

# docker-compose.yml
version: '3.8'
services:
  mastra:
    build: .
    ports:
      - "4111:4111"
    environment:
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - DATABASE_URL=postgresql://postgres:postgres@db:5432/mastra
    depends_on:
      - db

  db:
    image: pgvector/pgvector:pg17
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: mastra
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata: