# Создание нового проекта Mastra (рекомендуемый способ)
npm create mastra@latest

# CLI задаст несколько вопросов:
# ? Project name: my-ai-agent
# ? Include example agent: Yes
# ? Package manager: npm / pnpm / yarn

✔ Scaffolding project in ./my-ai-agent ...
✔ Installing dependencies (mastra, @mastra/core, ai, zod) ...
✔ Done! Run: cd my-ai-agent && npm run dev

# Ручная установка в существующий проект
npm install mastra @mastra/core ai zod
npm install -D @types/node typescript tsx

# Структура проекта после инициализации:
my-ai-agent/
├── src/
│   ├── mastra/
│   │   ├── agents/       # Определения агентов
│   │   ├── tools/        # Пользовательские инструменты
│   │   └── workflows/    # Multi-agent сценарии
│   └── index.ts          # Точка входа
├── .env                  # API-ключи
├── tsconfig.json
└── package.json

# .env
OPENAI_API_KEY=sk-proj-xxxxxxxxxxxxxxxxxxxxxxxx
ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxxxxxxxxxxxxx

// mastra.config.ts — конфигурация фреймворка
import { Mastra } from '@mastra/core';

export const mastra = new Mastra({
  agents: { /* ... */ },
  workflows: { /* ... */ },
  logger: true,       // подробное логирование
  telemetry: {         // опционально: отправка в Langfuse
    enabled: false,
  },
});

// src/mastra/agents/assistant.ts
import { Agent } from '@mastra/core/agent';
import { openai } from '@ai-sdk/openai';

export const assistant = new Agent({
  name: 'Assistant',
  instructions: `Ты — полезный AI-ассистент.
Ты отвечаешь на русском языке, если пользователь пишет по-русски.
Отвечай чётко, по делу, избегай воды.
Если ты не знаешь ответа — честно скажи об этом.`,
  model: openai('gpt-4o'),
});

// Использование агента — generate() с потоковым ответом
const result = await assistant.generate('Привет! Расскажи о фреймворке Mastra.', {
  maxSteps: 3,       // макс. число вызовов инструментов
  temperature: 0.7,
});

console.log(result.text);
// "Mastra — это современный TypeScript-фреймворк..."

// Потоковый вывод (streaming)
const stream = await assistant.stream('Напиши стих о программировании');
for await (const chunk of stream.textStream) {
  process.stdout.write(chunk);  // посимвольный вывод
}

// src/mastra/tools/weather.ts — пример пользовательского инструмента
import { createTool } from '@mastra/core/tools';
import { z } from 'zod';

export const weatherTool = createTool({
  id: 'get-weather',
  description: 'Получить текущую погоду для указанного города',
  inputSchema: z.object({
    city: z.string().describe('Название города'),
    units: z.enum(['celsius', 'fahrenheit']).default('celsius'),
  }),
  execute: async ({ context }) => {
    const { city, units } = context;
    // В реальном проекте — HTTP-запрос к API погоды
    const response = await fetch(`https://api.weather.example/${city}?units=${units}`);
    const data = await response.json();
    return {
      temperature: data.temp,
      conditions: data.conditions,
      humidity: data.humidity,
    };
  },
});

// Подключение инструментов к агенту
import { Agent } from '@mastra/core/agent';
import { weatherTool } from './tools/weather';

export const weatherAgent = new Agent({
  name: 'Weather Agent',
  instructions: 'Ты — метеоролог. Используй get-weather для получения данных.',
  model: openai('gpt-4o'),
  tools: { weatherTool },
});

// src/mastra/agents/mcp-agent.ts — агент с MCP-инструментами
import { Agent } from '@mastra/core/agent';
import { anthropic } from '@ai-sdk/anthropic';

export const mcpAgent = new Agent({
  name: 'MCP Explorer',
  instructions: 'Ты исследуешь файловую систему и веб-ресурсы через MCP.',
  model: anthropic('claude-sonnet-4-20250514'),
  // Подключение MCP-серверов декларативно
  mcpServers: {
    filesystem: {
      command: 'npx',
      args: ['-y', '@modelcontextprotocol/server-filesystem', '/tmp'],
    },
    braveSearch: {
      command: 'npx',
      args: ['-y', '@anthropic/mcp-server-brave-search'],
      env: { BRAVE_API_KEY: process.env.BRAVE_API_KEY },
    },
  },
});

// src/mastra/workflows/content-pipeline.ts
import { createWorkflow } from '@mastra/core/workflows';
import { researcher } from '../agents/researcher';
import { writer } from '../agents/writer';
import { editor } from '../agents/editor';

export const contentPipeline = createWorkflow({
  name: 'Конвейер создания статьи',
  triggerSchema: z.object({
    topic: z.string().describe('Тема статьи'),
    audience: z.enum(['technical', 'business', 'general']),
  }),
})
  // Шаг 1: Researcher собирает факты и источники
  .step({
    id: 'research',
    agent: researcher,
    input: ({ trigger }) => (`Собери ключевые факты по теме: ${trigger.topic}`),
  })
  // Шаг 2: Writer создаёт черновик на основе исследования
  .step({
    id: 'draft',
    agent: writer,
    input: ({ steps, trigger }) => (
      `Напиши статью на тему "${trigger.topic}" для аудитории ${trigger.audience}.
Факты для использования:\n${steps.research.text}`
    ),
  })
  // Шаг 3: Editor проверяет и улучшает текст
  .step({
    id: 'review',
    agent: editor,
    input: ({ steps }) => (
      `Отредактируй статью, исправь ошибки, улучши стиль:\n\n${steps.draft.text}`
    ),
  })
  .commit();

// Запуск workflow
const result = await contentPipeline.run({
  topic: 'Будущее AI-агентов в 2026 году',
  audience: 'technical',
});

// result.steps.research.text  → исследование
// result.steps.draft.text     → черновик
// result.steps.review.text    → финальная статья

// src/mastra/agents/memory-agent.ts — агент с долгосрочной памятью
import { Agent } from '@mastra/core/agent';
import { Memory } from '@mastra/memory';
import { PostgresStore } from '@mastra/pg';

const memory = new Memory({
  storage: new PostgresStore({
    connectionString: process.env.DATABASE_URL,
  }),
  options: {
    lastMessages: 20,         // последние 20 сообщений всегда в контексте
    semanticRecall: {           // семантический поиск по истории
      topK: 5,                  // 5 релевантных фрагментов
      messageRange: { before: 5, after: 2 },
    },
    workingMemory: {            // рабочая память — важные факты
      enabled: true,
      template: `Важные факты о пользователе:
<working_memory />
Используй эти факты при ответе.`,
    },
  },
});

export const personalAssistant = new Agent({
  name: 'Personal Assistant',
  instructions: 'Ты — персональный ассистент. Помни предпочтения и контекст.',
  model: openai('gpt-4o'),
  memory,
});

// Каждый вызов автоматически обогащается историей
await personalAssistant.generate('Меня зовут Алекс, я веган.', {
  resourceId: 'user-42',   // идентификатор сессии
});
await personalAssistant.generate('Посоветуй ресторан.', {
  resourceId: 'user-42',   // агент вспомнит про веганство
});

// src/mastra/agents/rag-support.ts
import { Agent } from '@mastra/core/agent';
import { createVectorQueryTool } from '@mastra/rag';
import { PineconeVector } from '@mastra/pinecone';
import { openai } from '@ai-sdk/openai';

// Шаг 1: Инициализация векторного хранилища
const vectorStore = new PineconeVector({
  apiKey: process.env.PINECONE_API_KEY,
  indexName: 'product-docs',
});

// Шаг 2: Создание инструмента векторного поиска
const searchDocs = createVectorQueryTool({
  vectorStore,
  embeddingModel: openai.embedding('text-embedding-3-small'),
  id: 'search-documentation',
  description: 'Искать ответы в документации продукта',
  topK: 5,
  filter: { source: 'official-docs' }, // опциональный фильтр
});

// Шаг 3: Агент поддержки с RAG
export const supportAgent = new Agent({
  name: 'Support Agent',
  instructions: `Ты — агент технической поддержки продукта.
Отвечай, опираясь ТОЛЬКО на найденные документы.
Если в документации нет ответа — предложи создать тикет.
Всегда указывай источник информации (заголовок документа).`,
  model: openai('gpt-4o'),
  tools: { searchDocs },
});

// Шаг 4: Индексация документов (выполняется один раз или по расписанию)
import { MDocument } from '@mastra/rag';

async function indexDocs() {
  const doc = await MDocument.fromUrl('https://docs.example.com/api-reference.md');

  const chunks = await doc.chunk({
    strategy: 'recursive',     // рекурсивное разбиение
    size: 512,                // токенов на чанк
    overlap: 64,             // перекрытие между чанками
  });

  await vectorStore.upsert({
    indexName: 'product-docs',
    chunks,
    embeddingModel: openai.embedding('text-embedding-3-small'),
  });

  console.log(`Проиндексировано ${chunks.length} чанков`);
}

// Использование RAG-агента
const answer = await supportAgent.generate(
  'Как настроить OAuth-аутентификацию через Google?'
);
// Агент вызовет searchDocs → получит релевантные чанки → сгенерирует ответ