TypeScript AI 에이전트 프레임워크 Mastra: 타입 안전한 에이전트 설계와 프로덕션 적용

import { Agent } from '@mastra/core/agent';
import { openai } from '@ai-sdk/openai';
import { createTool } from '@mastra/core/tools';
import { z } from 'zod';
 
// Tool 정의 — 입력 스키마를 Zod로 명시
const getWeatherTool = createTool({
  id: 'get-weather',
  description: '도시 이름으로 현재 날씨(기온, 날씨 상태)를 조회합니다. 날씨 관련 질문에만 사용하세요.',
  inputSchema: z.object({
    city: z.string().describe('날씨를 조회할 도시 이름'),
  }),
  outputSchema: z.object({
    temperature: z.number(),
    condition: z.string(),
  }),
  execute: async ({ context }) => {
    // 실제 날씨 API 호출 위치
    return { temperature: 22, condition: '맑음' };
  },
});
 
// Agent 정의
const weatherAgent = new Agent({
  name: 'weatherAgent',
  instructions: '사용자의 날씨 질문에 답변하는 에이전트입니다.',
  model: openai('gpt-4o'),
  tools: { getWeatherTool },
});

import { Memory } from '@mastra/memory';
import { LibSQLStore } from '@mastra/memory/storage';
 
const memory = new Memory({
  storage: new LibSQLStore({ url: 'file:local.db' }),
  options: {
    lastMessages: 20,       // 단기: 최근 20턴을 컨텍스트에 포함
    semanticRecall: {
      topK: 5,              // 시맨틱: 유사 대화 5개를 벡터 검색으로 추가
      messageRange: 3,
    },
  },
});
 
const agentWithMemory = new Agent({
  name: 'chatAgent',
  instructions: '사용자를 기억하는 대화 에이전트입니다.',
  model: openai('gpt-4o'),
  memory,
});

import { Agent } from '@mastra/core/agent';
import { createTool } from '@mastra/core/tools';
import { anthropic } from '@ai-sdk/anthropic';
import { z } from 'zod';
 
const createIssueTool = createTool({
  id: 'create-github-issue',
  description: 'GitHub 저장소에 이슈를 생성합니다. PR 분석 결과나 버그 보고 시 사용합니다.',
  inputSchema: z.object({
    owner: z.string(),
    repo: z.string(),
    title: z.string(),
    body: z.string(),
    labels: z.array(z.string()).optional(),
  }),
  execute: async ({ context }) => {
    const response = await fetch(
      `https://api.github.com/repos/${context.owner}/${context.repo}/issues`,
      {
        method: 'POST',
        headers: {
          Authorization: `token ${process.env.GITHUB_TOKEN}`,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({
          title: context.title,
          body: context.body,
          labels: context.labels,
        }),
      }
    );
 
    if (!response.ok) {
      throw new Error(`GitHub API 오류: ${response.status} ${response.statusText}`);
    }
 
    const issue = await response.json();
    return { issueNumber: issue.number, url: issue.html_url };
  },
});
 
const githubAgent = new Agent({
  name: 'githubAgent',
  instructions: `
    GitHub PR과 이슈를 관리하는 에이전트입니다.
    PR 내용을 분석해 적절한 이슈를 생성하고, 관련 레이블을 붙입니다.
  `,
  model: anthropic('claude-opus-4-7'),
  tools: { createIssueTool },
});
 
// 에이전트 실행
const result = await githubAgent.generate(
  'feat: 사용자 인증 모듈 추가 PR에 대한 이슈를 생성해줘. 저장소는 my-org/my-repo야.'
);
console.log(result.text);

import { MastraVector } from '@mastra/vector-pg'; // pgvector 사용
import { openai } from '@ai-sdk/openai';
import { createTool } from '@mastra/core/tools';
import { Agent } from '@mastra/core/agent';
import { embed } from 'ai';
import { z } from 'zod';
 
const vectorStore = new MastraVector({
  connectionString: process.env.DATABASE_URL!,
});
 
// 문서 임베딩 및 저장 (단락 단위 청킹 기준)
async function indexDocument(content: string, metadata: Record<string, string>) {
  const { embedding } = await embed({
    model: openai.embedding('text-embedding-3-small'),
    value: content,
  });
 
  await vectorStore.upsert({
    indexName: 'docs',
    vectors: [{ id: crypto.randomUUID(), vector: embedding, metadata }],
  });
}
 
// RAG 조회 Tool
const searchDocsTool = createTool({
  id: 'search-docs',
  description: '사내 문서를 시맨틱 검색합니다. 팀 정책, 기술 스펙, 온보딩 자료 조회 시 사용합니다.',
  inputSchema: z.object({
    query: z.string().describe('검색할 내용'),
  }),
  execute: async ({ context }) => {
    const { embedding } = await embed({
      model: openai.embedding('text-embedding-3-small'),
      value: context.query,
    });
 
    const results = await vectorStore.query({
      indexName: 'docs',
      queryVector: embedding,
      topK: 5,
    });
 
    return { documents: results.map(r => r.metadata) };
  },
});
 
const docsAgent = new Agent({
  name: 'docsAgent',
  instructions:
    '사내 문서를 검색해 정확한 답변을 제공하는 에이전트입니다. 문서에 없는 내용은 "문서에서 확인할 수 없습니다"라고 안내합니다.',
  model: openai('gpt-4o'),
  tools: { searchDocsTool },
});

import { Agent } from '@mastra/core/agent';
import { createWorkflow, createStep } from '@mastra/core/workflows';
import { openai } from '@ai-sdk/openai';
import { z } from 'zod';
 
// 2단계에서 사용할 요약 에이전트 (먼저 정의)
const summaryAgent = new Agent({
  name: 'summaryAgent',
  instructions: '주어진 기사 목록을 간결하고 핵심만 담아 3줄로 요약합니다.',
  model: openai('gpt-4o'),
});
 
// 1단계: RSS 피드 수집
const fetchNewsStep = createStep({
  id: 'fetch-news',
  inputSchema: z.object({ feedUrl: z.string() }),
  outputSchema: z.object({ articles: z.array(z.string()) }),
  execute: async ({ inputData }) => {
    // RSS 파싱 로직 위치 (실제 구현은 rss-parser 등 활용)
    const articles = ['기사 1 내용...', '기사 2 내용...'];
    return { articles };
  },
});
 
// 2단계: 요약 생성 (에이전트 활용)
const summarizeStep = createStep({
  id: 'summarize',
  inputSchema: z.object({ articles: z.array(z.string()) }),
  outputSchema: z.object({ summary: z.string() }),
  execute: async ({ inputData }) => {
    const result = await summaryAgent.generate(
      `다음 기사들을 3줄로 요약해주세요:\n${inputData.articles.join('\n\n')}`
    );
    return { summary: result.text };
  },
});
 
// 3단계: 슬랙 발송
const sendSlackStep = createStep({
  id: 'send-slack',
  inputSchema: z.object({ summary: z.string() }),
  outputSchema: z.object({ sent: z.boolean() }),
  execute: async ({ inputData }) => {
    const response = await fetch(process.env.SLACK_WEBHOOK_URL!, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ text: inputData.summary }),
    });
 
    if (!response.ok) {
      throw new Error(`슬랙 전송 실패: ${response.status}`);
    }
 
    return { sent: true };
  },
});
 
// Workflow 조립
const newsPipeline = createWorkflow({
  name: 'news-pipeline',
  triggerSchema: z.object({ feedUrl: z.string() }),
})
  .then(fetchNewsStep)
  .then(summarizeStep)
  .then(sendSlackStep)
  .commit();
 
// 파이프라인 실행
const run = await newsPipeline.execute({
  triggerData: { feedUrl: 'https://feeds.example.com/tech.rss' },
});
console.log('파이프라인 완료:', run);

import { evaluate } from '@mastra/evals';
import { AnswerRelevancyMetric } from '@mastra/evals/llm';
 
const result = await evaluate(docsAgent, '팀 온보딩 절차가 어떻게 되나요?', {
  metrics: [new AnswerRelevancyMetric(openai('gpt-4o'))],
});
 
console.log('관련성 점수:', result.metrics['AnswerRelevancy'].score);
// 0.0 ~ 1.0 범위, 0.7 이하면 프롬프트 재검토 신호