Mastra AI: TypeScript-фреймворк для ИИ-агентов, workflow и tools

Mastra — open-source TypeScript-фреймворк для агентов: он даёт класс Agent, типизированные инструменты, память, workflow и MCP, а модель подключает через LanguageModel-интерфейс Vercel AI SDK. Его выбирают команды, у которых AI-логика живёт рядом с продуктом на Node.js, и те, кому нужен агентный backend без Python-зависимостей. Mastra не тащит с собой ни провайдеров моделей, ни HTTP-клиента собственной разработки — модель передаётся объектом. Значит, интеграция сводится к фабрике OpenAI-совместимого провайдера с вашим baseURL.

От настройки зависят ровно две вещи: baseURL = "https://speshu.ai/api/v1" и API-ключ. Mastra работает поверх Vercel AI SDK, а этот SDK имеет штатный OpenAI-совместимый провайдер createOpenAI из пакета @ai-sdk/openai — отдельная интеграция в Mastra не нужна. Схема «любой OpenAI-совместимый baseURL» стабильна во всех версиях, в отличие от конкретных классов Mastra, которые между релизами переезжают.

Установка

npm install @mastra/core @ai-sdk/openai zod

zod обязателен: им объявляются inputSchema инструментов. Пакет ai Mastra подтягивает сам, вручную ставить не нужно.

Подключение

Положите ключ и идентификатор модели в окружение

Ключ создаётся на speshu.ai/profile. Идентификатор модели не зашивайте в код — состав каталога меняется, и зашитый в коде идентификатор молча устаревает до 404 model_not_found:

export SPESHU_API_KEY="sk-ваш-ключ"
export SPESHU_MODEL=$(curl -s https://speshu.ai/api/v1/models \
  -H "Authorization: Bearer $SPESHU_API_KEY" \
  | jq -r '.data[0].id')
echo "$SPESHU_MODEL"

В своём коде выбирайте модель по context_length, cost_completion и наличию зрения, а не по первому элементу массива. Формат ответа — в разделе Каталог моделей.

Создайте провайдера

TypeScript

// src/speshu.ts
import { createOpenAI } from "@ai-sdk/openai";

export const speshu = createOpenAI({
  baseURL: "https://speshu.ai/api/v1",
  apiKey: process.env.SPESHU_API_KEY!,
});

export const modelId = process.env.SPESHU_MODEL!;

Соберите агента и зарегистрируйте в Mastra

Agent принимает instructions, model, tools и memory. Экземпляр Mastra нужен для dev-сервера и для вызова агента по имени из HTTP-роута.

TypeScript

// src/mastra/index.ts
import { Agent } from "@mastra/core/agent";
import { Mastra } from "@mastra/core";

import { modelId, speshu } from "../speshu";

export const supportAgent = new Agent({
  name: "support-agent",
  instructions:
    "Ты ассистент поддержки. Отвечай кратко. Если данных не хватает, задай уточняющий вопрос.",
  model: speshu(modelId),
});

export const mastra = new Mastra({
  agents: { supportAgent },
});

Проверьте агента

TypeScript

const result = await supportAgent.generate(
  "Клиент спрашивает, как подключить API к RAG-боту. Что ответить?",
);

console.log(result.text);

Dev-сервер с песочницей инструментов запускается отдельно:

npx mastra@latest dev

Версии. Примеры выше рассчитаны на Mastra 1.x с AI SDK v5: createOpenAI возвращает вызываемый объект провайдера, поэтому модель получается как speshu(modelId). В Mastra 0.10 (AI SDK v4) класс Agent импортируется из @mastra/core/agent так же, но результат генерации и поток отдаются другими полями — они менялись между мажорными версиями. Импорт Agent из @mastra/core/agent и конструктор new Mastra({ agents }) — самая устойчивая часть API; на неё и опирайтесь.

Инструменты

Инструмент — это функция с Zod-схемой аргументов. Mastra сам превращает её в JSON Schema, а цикл вызова (модель вернула tool_calls → вы выполнили функцию → отдали результат) берёт на себя.

TypeScript

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

export const getOrderStatus = createTool({
  id: "getOrderStatus",
  description: "Статус заказа по его номеру. Используй, когда клиент спрашивает про заказ.",
  inputSchema: z.object({
    orderId: z.string().describe("Номер заказа вида ORD-1042"),
  }),
  execute: async ({ context }) => {
    // Здесь ваш настоящий вызов CRM или базы.
    return { orderId: context.orderId, state: "доставляется", eta: "2026-10-04" };
  },
});

Инструмент подключается к агенту полем tools: { getOrderStatus } и всё. Формат вызова на стороне API — tools[] с type: "function", разбор — в гайде Вызов функций.

В API SpeShu.AI нет эндпоинта /embeddings. Если вы строите RAG-пайплайн через Memory Mastra с векторным хранилищем, эмбеддинги нужно получать отдельно. Храните базовый адрес их провайдера в отдельной переменной окружения (например, EMBEDDINGS_BASE_URL / EMBEDDINGS_API_KEY) и подставляйте в embedMany из пакета ai; baseURL от SpeShu.AI оставьте только для генерации. Второй вариант — отказаться от векторной памяти и держать рабочий контекст в сообщениях или в собственном хранилище. Оба честнее, чем отправлять запрос на /embeddings, которого нет.

Продвинутые сценарии

Потоковая передача

supportAgent.stream(...) возвращает тот же SSE, что и stream: true на /api/v1/chat/completions. В Mastra 1.x полный текст лежит в stream.text, в Mastra 0.10 — в stream.textStream. Формат кадров, кадр со списанием и правило «[DONE] может не быть последней строкой» разобраны в Потоковой передаче.

Структурированный вывод

Mastra прокидывает output в AI SDK: в Mastra 1.x это Output.object({ schema }), в 0.10 — experimental_output из ai. JSON Schema, валидация и поведение при нарушении схемы — в гайде Структурированный вывод.

Генерация медиа

У Mastra нет встроенного инструмента под медиа-задачи SpeShu.AI — это отдельный асинхронный API, и удобнее вызвать его напрямую из своего инструмента или роута. Создание задачи, Idempotency-Key и цикл опроса — в Создании задачи, статусы — в Статусе задачи.

TypeScript

// src/tools/renderImage.ts
const BASE = "https://speshu.ai/api/v1";

export async function renderImage(prompt: string): Promise<string> {
  const headers = {
    Authorization: `Bearer ${process.env.SPESHU_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  };

  const created = await fetch(`${BASE}/async/media/tasks`, {
    method: "POST",
    headers,
    body: JSON.stringify({ model: "nano-banana-2", input: { prompt } }),
  });
  const taskId = (await created.json()).data.taskId;

  while (true) {
    const task = await fetch(`${BASE}/async/media/tasks/${taskId}`, { headers });
    const { data } = await task.json();
    if (data.state === "success") return JSON.parse(data.resultJson).resultUrls[0];
    if (data.state === "fail") throw new Error(`${data.failCode}: ${data.failMsg}`);
    await new Promise((r) => setTimeout(r, 3000));
  }
}

Идентификатор медиа-модели nano-banana-2 зашивать в код можно: каталог GET /api/v1/media/models публичный и стабильный. А вот деньги списываются при создании задачи, поэтому не повторяйте POST вслепую — тот же Idempotency-Key вернёт исходную задачу, новый создаст вторую.

Если что-то не работает

404 на baseURL без суффикса /v1

Нужен ровно https://speshu.ai/api/v1. Провайдер сам дописывает /chat/completions, и без /v1 итоговый путь уходит на несуществующий маршрут. То же самое с лишним слэшем в конце: https://speshu.ai/api/v1/ даёт .../v1//chat/completions.

401 invalid_api_key / 401 unauthorized

unauthorized означает, что заголовок Authorization не дошёл — в Mastra это обычно незаданная переменная окружения: process.env.SPESHU_API_KEY оказался undefined. invalid_api_key — ключ передан, но неверен или отозван. Проверка без траты токенов:

cURL

curl -s https://speshu.ai/api/v1/balance -H "Authorization: Bearer $SPESHU_API_KEY"

404 model_not_found

SPESHU_MODEL пустой, обрезан или устарел. Перечитайте GET /api/v1/models и подставьте id как есть — с префиксом вроде openai/, без кавычек. Массив models.data в Mastra не кэшируется между процессами, так что это почти всегда означает, что переменную окружения не обновили.

Ответ приходит целиком в конце вместо потока

Значит, поток не включился: у Agent нет отдельного флага — поток идёт от вызова agent.stream(). В Mastra 0.10 поверх @ai-sdk/openai в createOpenAI нет параметра совместимости, который заставлял бы клиент читать SSE построчно; обновление до 1.x и AI SDK v5 снимает вопрос. Формат кадров — в Потоковой передаче.

Всё остальное

Полная таблица кодов, три формата ошибок и цикл повторов — на странице Ошибки. Таймауты и квоты — в разделе Лимиты, расход в рублях — в гайде по учёту средств.

Что дальше

Начало работы

Полный маршрут: ключ, баланс, первый запрос

Вызов функций

Как модель вызывает инструмент и что она получает в ответ

Потоковая передача

SSE, [DONE] и кадр со списанием

Каталог моделей

Идентификаторы, контекст и цены

Начало работы

Возможности моделей

Генерация медиа

Фреймворки

Базы данных

Агенты и редакторы

No-code и автоматизация

Mastra AI: TypeScript-фреймворк для ИИ-агентов, workflow и tools

Установка

Подключение

Инструменты

Продвинутые сценарии

Если что-то не работает

Что дальше

Начало работы

Вызов функций

Потоковая передача

Каталог моделей

​Установка

​Подключение

​Инструменты

​Продвинутые сценарии

​Если что-то не работает

​Что дальше

Начало работы

Вызов функций

Потоковая передача

Каталог моделей

Установка

Подключение

Инструменты

Продвинутые сценарии

Если что-то не работает

Что дальше