Mastra: как создать AI-агента на TypeScript за 5 минут

Mastra -- это TypeScript-фреймворк для разработки AI-агентов и AI-приложений. Если вы работаете с JavaScript или TypeScript и хотите добавить AI-агентов в свой продукт -- Mastra предлагает типобезопасный, хорошо документированный способ сделать это без изучения экзотических Python-библиотек.

Mastra разработана командой, ранее создавшей Gatsby -- популярный генератор статических сайтов на базе React. Компания прошла акселератор Y Combinator (батч W25) и привлекла $13 миллионов финансирования. Версия 1.0 вышла в январе 2026 года; с тех пор фреймворк набирает более 1.77 миллиона NPM-загрузок в месяц, что делает его одним из самых быстрорастущих инструментов в экосистеме AI-агентов для TypeScript-разработчиков.

В чём особенность Mastra по сравнению с LangChain или CrewAI? Во-первых, Mastra написана на TypeScript «с нуля» и не является портом Python-библиотеки. Это означает отличный Developer Experience: автодополнение в IDE работает полноценно, все типы выводятся автоматически, а ошибки ловятся на этапе разработки, а не в рантайме. Во-вторых, Mastra включает Mastra Studio -- визуальный браузерный интерфейс для разработки, тестирования и отладки агентов без написания кода. В-третьих, фреймворк поддерживает более 1000 AI-моделей от разных провайдеров через единый унифицированный роутер на базе Vercel AI SDK.

Концептуально Mastra строится вокруг трёх ключевых примитивов. Агенты (Agents) -- это единицы с инструкциями, моделью и набором инструментов; они принимают пользовательские запросы и генерируют ответы. Инструменты (Tools) -- это функции, которые агент может вызывать для получения данных или выполнения действий в внешних системах. Воркфлоу (Workflows) -- это детерминированные последовательности шагов, где каждый шаг может быть агентом, инструментом или обычной функцией. Комбинируя эти три примитива, можно строить сложные AI-системы любого масштаба.

Для кого Mastra наиболее полезна:

Важный момент: Mastra -- это фреймворк для разработчиков. Для его использования нужно понимание JavaScript или TypeScript и базовый опыт работы с командной строкой. Конечные пользователи взаимодействуют с продуктами, построенными на Mastra, а не с самим фреймворком напрямую.

Mastra устанавливается как стандартный npm-пакет. Никакой регистрации нигде не требуется -- фреймворк полностью открыт.

Требования для установки:

Шаг 1. Создайте новый проект через Mastra CLI. Самый быстрый способ начать -- использовать официальный CLI, который создаёт полностью настроенный проект с примером агента:

npm create mastra@latest my-ai-agent -- --default
cd my-ai-agent

После выполнения этой команды у вас будет проект с примером погодного агента, инструментом для получения погоды, воркфлоу и оценщиком. Всё полностью рабочее -- достаточно добавить API-ключ.

Шаг 2. Добавьте Mastra в существующий проект. Если хотите добавить Mastra в уже существующий TypeScript-проект -- установите основной пакет:

npm install @mastra/core

Затем установите адаптер для нужного AI-провайдера, например: npm install @ai-sdk/anthropic для Claude или npm install @ai-sdk/openai для GPT-моделей.

Шаг 3. Настройте переменные окружения. Создайте файл .env в корне проекта и добавьте API-ключ от выбранного провайдера. Для начала удобнее всего Mistral -- он доступен без VPN из России и имеет щедрый бесплатный уровень.

Шаг 4. Запустите Mastra Studio. Mastra Studio -- встроенный визуальный интерфейс для разработки и тестирования агентов. Запустите сервер разработки командой npm run dev, и Studio автоматически откроется в браузере по адресу http://localhost:4111. В Studio вы увидите список всех ваших агентов, сможете чатиться с ними, просматривать детальные логи запросов и редактировать инструменты.

Шаг 5. Проверьте работу примера. Откройте Mastra Studio, выберите Weather Agent и задайте ему вопрос: «Какая сейчас погода в Москве?». Агент вызовет инструмент weatherTool, получит данные и сформирует ответ. Если агент ответил с данными о погоде -- всё настроено правильно. Посмотрите на трейс запроса в левой панели -- там видно, какие шаги агент совершил для ответа.

После запуска Mastra Studio вы готовы создавать собственных агентов. Вот несколько практических сценариев для первого знакомства.

Создайте минимального агента. В файле src/mastra/agents/assistant.ts определите агента с инструкциями и моделью. Агент принимает строку инструкций (системный промпт) и объект конфигурации модели. Mastra поддерживает синтаксис Vercel AI SDK для описания модели -- это означает полную совместимость с любым провайдером из их библиотеки. После создания файла Studio автоматически подхватит нового агента без перезапуска.

Добавьте инструмент для доступа к данным. Инструменты -- это главный способ связать агента с реальным миром. Создайте инструмент, который читает данные из вашей базы данных, вызывает внешний API или работает с файловой системой. Mastra использует Zod для валидации входных данных инструмента, что даёт TypeScript-автодополнение при вызове инструмента в Studio и в продакшн-коде.

Постройте воркфлоу из нескольких шагов. Если задача слишком сложна для одного агента -- разбейте её на шаги. Воркфлоу в Mastra позволяют создавать последовательные и параллельные цепочки: первый шаг анализирует входные данные, второй -- вызывает агента, третий -- форматирует результат для записи в базу данных. Voркфлоу детерминированы -- они выполняются одинаково при каждом запуске, в отличие от агентов, которые могут выбирать разные пути.

Настройте память агента. Mastra поддерживает несколько видов памяти. Для начала попробуйте простую память разговора (Conversation Memory): агент запоминает историю сессии и может ссылаться на предыдущие сообщения. Более продвинутый вариант -- семантическая память: агент хранит информацию в векторной базе данных и ищет релевантные факты из прошлых разговоров при каждом новом запросе.

Запустите eval (оценочный тест). В Mastra есть встроенная система тестирования агентов. Напишите eval, который проверяет конкретный сценарий: задаёт агенту вопрос и проверяет, соответствует ли ответ ожидаемым критериям. Запустите evals в CI/CD -- это позволит автоматически ловить регрессии при смене промпта или модели.

Единый роутер для 3300+ моделей от 94 провайдеров. Mastra использует Vercel AI SDK под капотом и поддерживает более 3300 AI-моделей от 94 провайдеров от OpenAI, Anthropic, Google, Mistral, Cohere, Amazon Bedrock и других. Переключение между моделями -- это смена одной строки кода. Можно динамически выбирать модель в зависимости от задачи: дешёвую модель для простых запросов, мощную -- для сложных аналитических задач.

Mastra Studio -- визуальная разработка агентов. Встроенный UI для разработки позволяет тестировать агентов, просматривать детальные трейсы каждого запроса (какие инструменты вызывал агент, сколько токенов потратил, сколько времени занял каждый шаг), редактировать промпты и запускать воркфлоу -- всё прямо в браузере.

Evals и scorers для production-качества. Mastra включает систему оценки агентов: можно написать тесты, которые автоматически проверяют правильность ответов агента на типовые запросы, и запускать их в CI/CD пайплайне. Это критически важно для production-деплоя -- смена промпта или модели может привести к неожиданным регрессиям.

Memory и персонализация. Mastra поддерживает несколько типов памяти: история разговора (Conversation Memory), семантический поиск (Vector Memory), хранение фактов о пользователе (Entity Memory). Это позволяет строить персонализированных агентов, которые помнят прошлые взаимодействия с конкретным пользователем.

MCP-поддержка из коробки. Mastra поддерживает Model Context Protocol -- стандарт для подключения внешних инструментов к AI-агентам. Вы можете подключить любой MCP-сервер и дать агенту доступ к его возможностям: работе с файловой системой, базами данных, GitHub, Notion и другими системами.

Типобезопасность на всех уровнях. Инструменты, схемы ввода-вывода агентов, шаги воркфлоу -- всё типизировано через Zod. IDE подсказывает правильные типы на каждом шаге, ошибки ловятся во время разработки, а не в production. Это радикально снижает количество «сюрпризов» при деплое агентных систем.

Mastra как фреймворк -- полностью бесплатна. Библиотека @mastra/core распространяется под MIT-лицензией, исходный код открыт на GitHub (github.com/mastra-ai/mastra). Никаких платежей, подписок или лимитов на использование фреймворка нет.

Вы платите только за AI-модели. Mastra -- это инфраструктура; стоимость работы определяется выбранным провайдером. При использовании Claude через API Anthropic -- платите по тарифам Anthropic. При использовании локальной модели через Ollama -- платите только за электричество. Mastra себе ничего не берёт.

Mastra Cloud (облачный деплой). Для production-деплоя агентов Mastra предлагает облачную платформу с хостингом, мониторингом и управлением версиями. Тарифы актуально проверять на mastra.ai на момент использования.

Ограничения:

Mastra как npm-пакет доступна без VPN. Сайт npmjs.com, документация на mastra.ai и репозиторий на GitHub открываются из России напрямую. Для установки и разработки VPN не нужен.

Вопрос о VPN возникает при подключении к AI-провайдерам -- а не к самому фреймворку. Ситуация по провайдерам:

Практическая рекомендация для российских разработчиков: начните разработку с Mistral (доступен без VPN, имеет бесплатный уровень) или с локальной модели через Ollama. Когда агент готов -- переключитесь на предпочтительный API через изменение одной строки кода. Mastra не привязывает вас к конкретному провайдеру.

Оплата API-сервисов потребует иностранной карты (Visa/Mastercard международного выпуска) для большинства западных провайдеров. Сам фреймворк Mastra бесплатен и никакой оплаты не требует.

File-Based Agents (июль 2026). В июле 2026 года Mastra добавила принципиально новый способ работы с агентами - File-Based Agents. Вместо написания кода для определения агентов можно использовать структуру папок и файлов: каждый агент описывается набором конфигурационных файлов в выделенной директории. Это позволяет управлять агентами как конфигурацией, хранить их в системе контроля версий и передавать между командами без изменения кода приложения.

Schedules: управление повторяющимися задачами (8 июля 2026). В версии от 8 июля 2026 года Mastra представила примитив Schedules - унифицированный API для автоматизации повторяющихся задач агентов и воркфлоу. Schedules регистрируются через mastra.schedules и поддерживают cron-синтаксис для гибкой настройки расписания. Единый API работает одинаково для агентов и воркфлоу без дополнительных адаптеров. Этот механизм приходит на смену устаревшим heartbeat-обработчикам: если ваш проект использует heartbeat, рекомендуется мигрировать на Schedules, поскольку старый API может быть удалён в следующих мажорных версиях.

@mastra/livekit: голосовые агенты в реальном времени. Новый официальный пакет @mastra/livekit добавляет поддержку голосовых агентов через инфраструктуру LiveKit. Пакет устанавливается отдельно: npm install @mastra/livekit. Он предоставляет готовые компоненты для создания агентов, которые могут принимать аудиоввод и генерировать речевые ответы в реальном времени – актуально для сценариев голосовых ассистентов, колл-центров и интерактивных обучающих систем.

Авто-обнаружение агентов и воркфлоу (auto-discovery). При запуске mastra dev или mastra build фреймворк теперь автоматически сканирует директорию src/mastra и обнаруживает все экспортированные агенты и воркфлоу без явной регистрации в центральном конфигурационном файле. Это упрощает структуру проекта при масштабировании: достаточно создать новый файл агента в правильной директории, и Mastra подхватит его автоматически на следующем запуске.

Этот материал подготовлен командой AI-агентов AravanaAI и проверен главным редактором.