Mastra Implementation for AI Agent and Workflow Building

Mastra AI-Agent and Workflow Framework

Mastra — TypeScript/JavaScript фреймворк для построения AI-агентов и workflow в Node.js окружении. Предназначен для команд, разрабатывающих на TypeScript, и обеспечивает типобезопасную работу с агентами, инструментами, RAG-пайплайнами и workflow. Ориентирован на production-интеграцию в существующие Node.js/Next.js приложения.

Базовый агент на Mastra

// npm install @mastra/core @mastra/rag
import { Mastra, createTool, Agent } from "@mastra/core";
import { z } from "zod";
import { openai } from "@mastra/openai";

// Инструмент с типизацией через Zod
const getWeatherTool = createTool({
  id: "get-weather",
  description: "Получить текущую погоду для города",
  inputSchema: z.object({
    city: z.string().describe("Название города"),
    unit: z.enum(["celsius", "fahrenheit"]).default("celsius"),
  }),
  outputSchema: z.object({
    temperature: z.number(),
    description: z.string(),
    humidity: z.number(),
  }),
  execute: async ({ context }) => {
    const data = await weatherApi.get(context.city, context.unit);
    return {
      temperature: data.temp,
      description: data.description,
      humidity: data.humidity,
    };
  },
});

const queryDatabaseTool = createTool({
  id: "query-database",
  description: "Выполнить SQL-запрос к базе данных аналитики",
  inputSchema: z.object({
    query: z.string().describe("SQL SELECT-запрос"),
  }),
  execute: async ({ context }) => {
    if (!context.query.trim().toUpperCase().startsWith("SELECT")) {
      throw new Error("Разрешены только SELECT-запросы");
    }
    const results = await db.query(context.query);
    return { rows: results, count: results.length };
  },
});

// Создание агента
const analyticsAgent = new Agent({
  name: "Analytics Agent",
  instructions: `Ты — аналитик данных. Используй инструменты для получения данных и
предоставляй конкретные аналитические выводы с числами и трендами.`,
  model: openai("gpt-4o"),
  tools: {
    getWeather: getWeatherTool,
    queryDatabase: queryDatabaseTool,
  },
});

// Запуск
const result = await analyticsAgent.generate(
  "Проанализируй продажи за Q1 2025 и сравни с Q1 2024"
);
console.log(result.text);

Workflow: типизированные пайплайны

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

// Шаги workflow
const extractDataStep = createStep({
  id: "extract-data",
  description: "Извлечь данные из источника",
  inputSchema: z.object({
    source: z.string(),
    date_from: z.string(),
    date_to: z.string(),
  }),
  outputSchema: z.object({
    data: z.array(z.record(z.any())),
    record_count: z.number(),
  }),
  execute: async ({ inputData }) => {
    const data = await dataSource.fetch(inputData);
    return { data, record_count: data.length };
  },
});

const analyzeDataStep = createStep({
  id: "analyze-data",
  inputSchema: z.object({
    data: z.array(z.record(z.any())),
  }),
  outputSchema: z.object({
    insights: z.array(z.string()),
    metrics: z.record(z.number()),
  }),
  execute: async ({ inputData, mastra }) => {
    const agent = mastra.getAgent("analytics-agent");
    const result = await agent.generate(
      `Проанализируй следующие данные:\n${JSON.stringify(inputData.data.slice(0, 100))}`
    );
    // Парсим структурированный ответ
    return parseAnalysisResult(result.text);
  },
});

const generateReportStep = createStep({
  id: "generate-report",
  inputSchema: z.object({
    insights: z.array(z.string()),
    metrics: z.record(z.number()),
  }),
  execute: async ({ inputData }) => {
    const report = await reportGenerator.create(inputData);
    await notificationService.send({
      channel: "slack",
      text: `Отчёт готов: ${report.url}`,
    });
    return { report_url: report.url };
  },
});

// Сборка workflow
const analyticsWorkflow = createWorkflow({
  id: "analytics-pipeline",
  description: "Полный пайплайн аналитики: извлечение → анализ → отчёт",
  inputSchema: z.object({
    source: z.string(),
    date_from: z.string(),
    date_to: z.string(),
  }),
})
  .then(extractDataStep)
  .then(analyzeDataStep)
  .then(generateReportStep)
  .commit();

RAG-интеграция

import { MastraVector } from "@mastra/rag";
import { openai } from "@mastra/openai";

const vectorStore = new MastraVector({
  provider: "pinecone",
  apiKey: process.env.PINECONE_API_KEY!,
  index: "knowledge-base",
});

// Индексирование
await vectorStore.upsert({
  indexName: "docs",
  vectors: await embedDocuments(documents),
});

// RAG-агент
const ragAgent = new Agent({
  name: "Knowledge Base Agent",
  instructions: "Отвечай на вопросы, используя только информацию из базы знаний.",
  model: openai("gpt-4o"),
  tools: {
    searchKnowledge: createTool({
      id: "search-knowledge",
      inputSchema: z.object({ query: z.string() }),
      execute: async ({ context }) => {
        const results = await vectorStore.query({
          indexName: "docs",
          queryVector: await embed(context.query),
          topK: 5,
        });
        return results;
      },
    }),
  },
});

Intergation с Next.js

// app/api/agent/route.ts
import { mastra } from "@/lib/mastra";

export async function POST(request: Request) {
  const { message, sessionId } = await request.json();

  const agent = mastra.getAgent("customer-support");

  // Стриминг для UI
  const stream = await agent.stream(message, {
    threadId: sessionId,  // Персистентная история диалога
  });

  return stream.toDataStreamResponse();
}

Практический кейс: автоматизация отчётности SaaS

Команда: 5 разработчиков на TypeScript/Next.js, нужна автоматизация еженедельных аналитических отчётов.

Выбор Mastra: нативная интеграция в существующий TypeScript-стек без перехода на Python.

Workflow: извлечение метрик из PostgreSQL → анализ агентом → генерация markdown-отчёта → публикация в Notion + уведомление в Slack.

Результаты:

• Реализация за 3 дня (против 2 недель на оценивании Python-альтернатив с интеграцией)
• Типобезопасность: 0 runtime-ошибок типов в production за 2 месяца
• Команда не тратила время на изучение нового стека

Сроки

• Базовый агент с инструментами: 1–2 дня
• Workflow с несколькими шагами: 3–5 дней
• RAG-интеграция: 3–5 дней
• Интеграция в Next.js с UI: 1 неделя