Mastra - TypeScript AI 에이전트 프레임워크 치트시트

Mastra - TypeScript AI 에이전트 프레임워크 치트시트

Mastra는 Gatsby 팀이 만든 AI 에이전트 및 워크플로를 위한 오픈소스 TypeScript 프레임워크입니다. 대부분의 에이전트 프레임워크가 Python 우선이지만, Mastra는 완전한 타입 안전성으로 JavaScript/TypeScript 생태계를 대상으로 합니다: 도구 및 메모리가 있는 타입된 에이전트, 분기 및 일시 중단/재개가 있는 그래프로 표현된 지속가능한 워크플로, RAG 원시 요소, 기본 제공 평가, 그리고 브라우저에서 에이전트를 반복하기 위한 로컬 개발 플레이그라운드.

설치

방법	명령
프로젝트 생성	npm create mastra@latest
기존에 추가	npm install @mastra/core
개발 서버	npm run dev (플레이그라운드 localhost:4111)
모델 제공자	npm install @ai-sdk/openai (Vercel AI SDK 사용)
확인	플레이그라운드 열기

에이전트 정의

import { Agent } from "@mastra/core/agent";
import { openai } from "@ai-sdk/openai";

export const supportAgent = new Agent({
  name: "support",
  instructions: "You are a concise support agent. Cite docs when possible.",
  model: openai("gpt-4o"),
  tools: { searchDocs },
});

const result = await supportAgent.generate("How do I rotate my API key?");
console.log(result.text);

방법	역할
.generate(input)	한 번 실행하고 결과 반환
.stream(input)	토큰/단계 스트리밍
tools	에이전트가 호출할 수 있는 타입된 도구
memory	지속가능한 대화 메모리

도구

import { createTool } from "@mastra/core/tools";
import { z } from "zod";

export const searchDocs = createTool({
  id: "search-docs",
  description: "Search the product documentation",
  inputSchema: z.object({ query: z.string() }),
  outputSchema: z.object({ results: z.array(z.string()) }),
  execute: async ({ context }) => {
    return { results: await search(context.query) };
  },
});

Zod 스키마는 종단 간 타입 안전성을 제공합니다 — 에이전트의 도구 호출이 양쪽에서 검증되고 타입됩니다.

워크플로 (지속가능한 그래프)

import { createWorkflow, createStep } from "@mastra/core/workflows";

const fetchData = createStep({ id: "fetch", execute: async () => ({ ... }) });
const analyze   = createStep({ id: "analyze", execute: async ({ inputData }) => ({ ... }) });

export const pipeline = createWorkflow({ id: "pipeline" })
  .then(fetchData)
  .then(analyze)
  .commit();

기능	목적
.then()	순차 단계
.branch()	조건부 경로
.parallel()	동시 단계
.dowhile() / .foreach()	데이터 순환
일시 중단/재개	사용자 입력을 기다렸다가 나중에 재개
지속가능한 실행	재시작 후 유지

메모리

유형	사용
Conversation history	컨텍스트의 최근 턴
Semantic recall	이전 메시지에 대한 벡터 검색
Working memory	사용자에 대한 지속가능한 사실
Storage adapters	LibSQL, Postgres, Upstash

RAG 원시 요소

부분	제공
Document chunking	구성 가능한 전략으로 문서 분할
Embeddings	AI SDK 제공자를 통해
Vector stores	pgvector, Pinecone, Qdrant, Chroma
Retrieval tool	검색을 에이전트 도구로 연결

평가 및 관찰성

기능	참고
기본 제공 평가	답변 관련성, 충실성, 독성, 편향
맞춤형 채점기	자신의 메트릭 정의
추적	OpenTelemetry 호환 추적
플레이그라운드	로컬에서 에이전트 실행, 도구, 메모리 검사

배포

대상	참고
Node server	mastra build 배포 가능한 서버 생성
Vercel / Cloudflare / Netlify	공식 배포자
Serverless	상태 없는 호스트용 설계된 워크플로

Mastra vs 다른 에이전트 프레임워크

측면	Mastra	LangGraph	CrewAI
언어	TypeScript	Python	Python
워크플로	지속가능한 그래프 + 일시 중단/재개	상태 유지 그래프	역할 기반 크루
타입 안전성	강력 (Zod 종단 간)	Python 타이핑	Python 타이핑
최고의 용도	TS/JS 팀, 웹 앱	복잡한 상태 유지 에이전트	다중 에이전트 역할 극화

LangGraph의 TypeScript 대응물; CrewAI와 AutoGen (Python)과 비교하세요.

리소스

• Official Website
• GitHub Repository
• Documentation