Mastra 실전 가이드 — TypeScript로 AI 에이전트 만들기, LangChain·PydanticAI와 비교

에이전트 + 도구 기본 구성 (TypeScript)
import { Mastra, Agent, createTool } from '@mastra/core';
import { z } from 'zod';
import { openai } from '@ai-sdk/openai';

// 1. 도구 정의 — 입출력 타입이 Zod로 보장됨
const searchTool = createTool({
  id: 'search-docs',
  description: 'Search technical documentation',
  inputSchema: z.object({
    query: z.string().describe('Search query'),
    limit: z.number().default(5),
  }),
  outputSchema: z.object({
    results: z.array(z.object({
      title: z.string(),
      url: z.string(),
      snippet: z.string(),
    })),
  }),
  execute: async ({ context }) => {
    // 실제 검색 로직
    const results = await fetchDocs(context.query, context.limit);
    return { results };
  },
});

// 2. 에이전트 정의
const techAgent = new Agent({
  name: 'tech-assistant',
  instructions: 'You are a technical assistant. Use search-docs tool to find accurate information.',
  model: openai('gpt-4o'),
  tools: { searchTool },
});

// 3. Mastra 인스턴스에 등록
const mastra = new Mastra({
  agents: { techAgent },
});

// 4. 에이전트 호출
const response = await mastra.getAgent('techAgent').generate(
  'TypeScript 6.0에서 달라진 점을 정리해줘'
);
console.log(response.text);

워크플로우 정의 예시
import { Workflow, Step } from '@mastra/core';
import { z } from 'zod';

const researchWorkflow = new Workflow({
  name: 'research-and-summarize',
  triggerSchema: z.object({ topic: z.string() }),
});

// 스텝 1: 검색
researchWorkflow.step(searchStep, {
  variables: {
    query: { step: 'trigger', path: 'topic' },
  },
});

// 스텝 2: 검색 결과 기반 요약 (searchStep 완료 후 실행)
.then(summarizeStep, {
  variables: {
    content: { step: searchStep, path: 'results' },
  },
})
.commit();

// 워크플로우 실행
const run = researchWorkflow.createRun();
const result = await run.start({ triggerData: { topic: 'Mastra AI framework' } });
console.log(result.results.summarizeStep.output);

설치 및 프로젝트 초기화
# 신규 Mastra 프로젝트 생성
npx create-mastra@latest my-agent

# 기존 프로젝트에 추가
npm install @mastra/core

# LLM 프로바이더 설치 (OpenAI 예시)
npm install @ai-sdk/openai

# 환경변수 설정 (.env)
OPENAI_API_KEY=sk-...

Next.js API Route에서 에이전트 호출
// app/api/agent/route.ts
import { mastra } from '@/mastra';
import { NextRequest, NextResponse } from 'next/server';

export async function POST(req: NextRequest) {
  const { message, threadId } = await req.json();

  const agent = mastra.getAgent('techAgent');

  // 메모리 포함 스트리밍 응답
  const stream = await agent.stream(message, {
    threadId,              // 대화 컨텍스트 유지
    resourceId: 'user-1', // 사용자별 메모리 분리
  });

  return stream.toDataStreamResponse();
}