ИИ-агент на Mastra (TypeScript): tools, memory, пайплайн

Если вы уже собираете сайт, лендинги или автопостинг на TypeScript, а гайды по агентам сплошняком на Python — знакомая ловушка. Код продукта в одном стеке, «мозг» агента — в другом. Ниже — как создать ИИ-агента на Mastra: от первого tool до контент-пайплайна с памятью, проверкой качества и автопостингом в Telegram или блог.

Коротко. Mastra — TypeScript-фреймворк для агентов: Agent, tools, Workflow, Memory и evals в одном проекте. Старт: npm create mastra@latest, Node.js не ниже 22.13, Studio на порту 4111. Для контент-завода почти всегда берите Workflow как скелет, а Agent — только там, где нужен «умный» выбор. Tools — только через createTool и Zod. Перед автопостом — scorers и ограничение прав на публикацию.

Зачем TypeScript-агент, если все тащат Python-стеки

Боль простая: туториалы про LangChain и LangGraph везде, а ваш фронт, API и боты уже на TypeScript. Два языка = два деплоя, два набора зависимостей и вечный «кто чинит агента».

Mastra закрывает дыру: агенты, цепочки и память пишутся на том же TypeScript, что и продукт. На русском рынке бренд Mastra пока слабый, зато родовой спрос «как создать ИИ-агента» и «создание ИИ-агента» огромный — а свободный угол «TS + контент-пайплайн» почти пустой.

Стек	Сильная сторона	Когда брать
CrewAI	роли агентов, быстрый MVP на Python	эксперимент с «командой ролей»
LangGraph	граф состояний, продакшен на Python	сложная оркестрация в Python-команде
Dify / Flowise	low-code холст	прототип без кода
Make AI Agents	триггеры и доставка в сервисы	обвязка вокруг уже готового агента
Mastra	TypeScript: agents + workflows + memory + evals	код продукта уже на TS

Python-стек остаётся нормальным выбором. Этот гайд — для тех, кто не хочет тащить второй язык ради одного агента.

Что такое Mastra простыми словами и из каких кубиков агент

Mastra — open-source фреймворк на TypeScript: агенты, workflows, memory, tools, оценка качества (evals), наблюдаемость и Studio для отладки. Репозиторий на GitHub насчитывает порядка 26,5 тысяч звёзд — проект живой, пакеты обновляются регулярно. Актуальные ориентиры пакетов на момент проверки: @mastra/core около 1.52, @mastra/memory, @mastra/evals, @mastra/mcp.

Четыре кубика, без которых дальше не пройти:

Agent — модель + tools. Задача открытая: модель сама выбирает, что вызвать и сколько раз.
Tools — действия вовне: HTTP-запрос, запись в CMS, отправка в Telegram.
Workflow — заранее прописанная цепочка шагов с проверками и ветками.
Memory — память между сообщениями и запусками: бриф, стиль, прошлые черновики.

Официальная документация: mastra.ai/docs. Quickstart: mastra.ai/guides/getting-started/quickstart.

Первый рабочий агент: от пустого проекта до ответа с tool-вызовом

Ниже — минимальный путь, который новичок повторяет за один вечер. Цель: агент не просто отвечает текстом, а вызывает хотя бы один tool.

Установка и каркас на TypeScript

Шаг 1. Поставьте Node.js не ниже 22.13. В терминале: node -v. Если версия ниже — обновите Node, иначе Mastra не взлетит.

Шаг 2. Создайте проект:

npm create mastra@latest

Мастер спросит имя проекта, провайдера модели и (по желанию) API-ключ. Можно использовать pnpm, yarn или bun — команда та же по смыслу.

Шаг 3. Зайдите в папку проекта и запустите Studio:

npm run dev

Откройте http://localhost:4111 — это Studio: интерфейс, где видно агента, шаги и ответы.

Шаг 4. Положите ключ модели в .env (имя переменной зависит от провайдера, который выбрали в мастере). Из России оплата зарубежных API часто идёт через карту иностранного банка, посредника или корпоративный счёт — заложите это заранее. Альтернатива на старте: локальная модель через совместимый endpoint, если провайдер это умеет; для продакшена всё равно нужен стабильный доступ к API.

Признак успеха. Studio открывается, агент отвечает на простой вопрос без ошибки ключа.

Один tool, который реально ходит во внешний сервис

Не начинайте с «универсального маркетолога». Сделайте один узкий tool — например, fetchBrief: принимает URL или ID брифа и возвращает JSON с темой, тоном и CTA.

Важно: tools в Mastra задаются только через createTool() и схему Zod. Обычный объект «как в старых туториалах» молча не выполнится — это частая ловушка по официальной документации.

Минимальная логика tool:

inputSchema — что агент обязан передать (например, briefId: string);
outputSchema — что вернётся (тема, ключевые тезисы, запреты);
execute — ваш код: fetch к Google Sheets, Notion, своей таблице или Make webhook.

Подключите tool к агенту, задайте короткую инструкцию: «Сначала вызови fetchBrief. Не выдумывай бриф». Вызовите generate() или stream() с тестовым сообщением.

Признак успеха. В Studio видно: агент вызвал tool → получил JSON → ответил уже с фактами из брифа, а не «из головы».

Типичные ошибки новичка

Node старый — ошибка engines / странный краш при старте. Решение: Node ≥ 22.13.
Tool как plain object — агент «как будто» знает инструмент, но не вызывает. Решение: только createTool + Zod.
Ключ модели не подхватился — Studio пустой или 401. Решение: проверить .env, перезапустить npm run dev, не коммитить ключи в Git.

Tools: как агент перестаёт «болтать» и начинает действовать

ИИ-агент для контента бесполезен, если умеет только красиво писать. Ему нужны действия: прочитать бриф, проверить факты, отдать пост в канал.

Правило least privilege: давайте агенту минимум tools. Отдельно — «читать», отдельно — «публиковать». Публикацию лучше вешать на шаг workflow с ручным или автоматическим гейтом, а не отдавать свободно рассуждающему агенту.

Свои tools vs MCP-сервер — когда что подключать

Подход	Плюсы	Минусы	Когда
Свои Zod-tools	полный контроль, проще отладка	пишете код сами	1–5 понятных действий (CMS, TG, HTTP)
MCP-сервер / MCP-клиент	готовый зоопарк внешних серверов	лишняя сложность на старте	много чужих tools уже в MCP

Из России удобнее начинать со своих tools: Telegram Bot API, webhook Make/n8n, REST WordPress — всё это обычный HTTP. MCP подключайте вторым слоем, когда реально нужен чужой зоопарк серверов.

Для публикации не отдавайте агенту полный доступ «навсегда». В свежих разборах по безопасности агентов повторяют одно: без HITL (человек подтверждает опасный шаг) и без узких прав tool легко сделать вред — от спама в канал до утечки данных. В Mastra на publish-tool логичен requireApproval или отдельный шаг «отправить только после scorers».

Workflows: цепочка шагов вместо одного длинного промпта

Один огромный промпт «исследуй → напиши → проверь SEO → опубликуй» ломается: модель путает порядок, пропускает проверку, «публикует» текстом вместо API.

Официальная развилка Mastra:

Agent — задача открытая, число шагов неизвестно.
Workflow — многошаговый процесс с .then(), ветками, параллелью, схемами входа/выхода, паузой и продолжением в Studio.
Гибрид — workflow как скелет, внутри шагов — agent или tool (createStep(agent) / createStep(tool)).

Именно гибрид чаще всего нужен контент-заводу: структура и публикация — детерминированно, угол и рерайт — через агента.

Где workflow спасает от хаоса в длинной задаче

Пример конвейера:

Вход: бриф (тема, канал, CTA, запреты).
Research-tool: собирает факты / ссылки / тезисы.
Draft-agent: пишет черновик со structured output (заголовок, лид, тело, FAQ).
QA-gate: scorers из @mastra/evals — faithfulness, токсичность, свой чеклист SEO.
Publish-tool или JSON наружу в Make/n8n.

Признак успеха. В Studio видно всю цепочку; при провале QA публикация не стартует.

Memory: чтобы агент помнил бриф, стиль и прошлые черновики

Без памяти каждый запуск — амнезия. Агент снова спрашивает тон голоса и забывает, что вчера уже писали про ту же тему.

В актуальной доке Mastra четыре слоя памяти (пакет @mastra/memory + хранилище вроде @mastra/libsql):

Message history — последние сообщения в thread + resource.
Working memory — структурированные факты: бренд, тон, запретные слова.
Semantic recall — поиск по смыслу в прошлых сообщениях.
Observational Memory — фоновое сжатие истории в observation log; вендор рекомендует как основной путь.

Цифры бенчмарков из блога вендора (LongMemEval) — заявления самой компании, не независимый аудит. Ориентируйтесь на практику: бриф и стиль должны переживать перезапуск Studio.

Что класть в память, а что лучше не хранить

Класть

Тон канала, ЦА, стоп-слова, CTA-шаблоны, утверждённые факты о продукте, ID прошлых удачных постов.

Не класть

Полные API-ключи, персональные данные клиентов без нужды, сырые логи оплаты, всё подряд из чата «на всякий случай».

Для тестов всегда передавайте resource и thread. Иначе «агенты с памятью» на словах останутся чатом без истории.

Мультиагентная связка: исследователь, редактор и публикатор

Мультиагентные системы звучат модно, но новички часто делают трёх агентов там, где хватит одного workflow с двумя tools.

Рабочая схема под контент:

Роль	Тип	Задача
Исследователь	tool или узкий agent	факты, тезисы, источники
Редактор	agent	угол, текст, адаптация под канал
Контролёр	scorers / evals	«можно ли публиковать»
Публикатор	tool или Make	Telegram / WordPress

Не разгоняйте слово «субагенты» ради хайпа: в поиске оно часто про банковские платежи, а не про ИИ.

Ошибки координации, из‑за которых агенты спорят и дублируют работу

Два агента пишут черновик — получаете два поста и хаос в канале. Один writer на шаг.
Все tools у всех — исследователь может «случайно» опубликовать. Права узкие.
Нет общего брифа в memory — каждый шаг заново выдумывает тон.
Публикация без QA-гейта — автопостинг превращается в автоспам.

Контент-пайплайн на агентах: от брифа до автопостинга

Цель — не «поговорить с моделью», а контент-пайплайн: бриф → черновик → проверка → автопостинг.

Рекомендуемая архитектура для команды из РФ:

Триггер снаружи: Google Sheets, форма, cron или сообщение в Telegram → Make/n8n.
Make делает POST на HTTP endpoint Mastra (workflow или agent API).
Mastra гоняет workflow, возвращает JSON: title, body, status, qaScore.
Если статус ok — Make публикует в Telegram / WordPress / VK. Если нет — алерт человеку.

Так вы не дублируете уже существующие гайды по Make: Mastra — «мозг и контроль», Make — «транспорт и кнопки сервисов».

С версии @mastra/core 1.22+ у Mastra есть каналы (Slack, Discord, Telegram) и webhook вида /api/agents//channels//webhook. Это удобно, когда агент отвечает в боте. Для заводского автопостинга чаще выгоднее workflow + Make: проще календарь, ретраи и несколько каналов.

Черновик → проверка → публикация в канал/блог

Практический мини-регламент:

Бриф попадает в workflow.
Draft-agent отдаёт structured output.
Scorers: верность фактам, токсичность, свой чеклист (H1, ключ в первом экране, длина, CTA).
Если балл ниже порога — стоп и комментарий правки.
Publish-tool шлёт в Telegram Bot API или возвращает payload в Make.

Русскоязычный разбор evals на Mastra есть на Хабре (статья про scorers и LLM-as-Judge): полезно как практика контроля качества, не как замена этому гайду.

Ограничение из РФ честно: Telegram Bot API обычно доступен; WordPress на своём хостинге — тоже. Зарубежные LLM-API и оплата npm/облака — узкое место. Держите ключи на сервере с рабочим исходящим доступом, а публикацию — ближе к своим каналам.

Вайбкодинг агента: как ускорить сборку и не сломать архитектуру

Вайбкодинг здесь — сборка агента вместе с ИИ-ассистентом в редакторе: вы описываете шаги, ассистент пишет каркас, вы проверяете архитектуру.

Как не сломать проект:

Сначала нарисуйте на бумаге: Agent или Workflow? Какие 3 tools максимум?
Просите ассистента писать только createTool + Zod, не «упрощённые» объекты.
После каждой генерации гоняйте один сценарий в Studio end-to-end.
Не просите «сразу мультиагентную систему на 10 ролей» — сначала один publish-safe пайплайн.

Вайбкодинг ускоряет набор кода. Архитектуру Agent vs Workflow и права tools решаете вы — иначе получите красивый хаос.

Чеклист запуска: что проверить перед боем

Перед тем как агент трогает боевой канал:

Node ≥ 22.13, npm run dev / деплой без ошибок engines
Ключи только в env, не в репозитории
Хотя бы один tool через createTool реально вызывается
Контент-цепочка — Workflow, а не один бесконечный промпт
Memory с resource + thread
Scorers / @mastra/evals перед публикацией
Publish-tool с узкими правами или approval
Тестовый канал / staging WordPress, не прод
Алерты в Telegram, если QA завалился
Понятный JSON наружу для Make/n8n

Типичные поломки tools, memory и workflow

Симптом	Частая причина	Что сделать
Tool не вызывается	plain object вместо createTool	переписать tool
Память «пустая»	нет resource/thread	передавать ID на каждый run
Пост уехал без проверки	publish внутри свободного agent	вынести в workflow + scorer
Studio не открывается	старый Node / порт занят	обновить Node, проверить :4111
Eval падает на memory-агенте	runEvals без thread/resource	добавить идентификаторы

Экономика «своего агента» зависит от токенов, хостинга и доработок. Рыночные сметы в СМИ дают лишь ориентир «DIY vs подрядчик» — не копируйте чужие цифры как свой бюджет. Считайте: стоимость API на 100 постов + время на evals + цена ошибки в канале.

FAQ

Чем Mastra отличается от LangChain/LangGraph?

LangChain/LangGraph — в основном Python-экосистема (графы, цепочки, огромный зоопарк интеграций). Mastra — TypeScript-first: agents, workflows, memory, evals и Studio в одном стеке. Если команда живёт в TS — Mastra снимает второй язык. Если уже глубоко в Python-prod — LangGraph остаётся сильным выбором.

Нужен ли MCP сразу или хватит своих tools?

Для первого контент-пайплайна хватит 2–4 своих Zod-tools (бриф, черновик, QA-сигнал, публикация/webhook). MCP подключайте, когда нужен готовый набор внешних MCP-серверов или вы отдаёте своего агента наружу как MCPServer.

Можно ли собрать контент-пайплайн одним агентом?

Технически да, на практике плохо: один агент путает порядок, пропускает проверки и слишком легко получает publish-права. Надёжнее: Workflow + agent на шаге текста + scorers + отдельный publish.

С чего начать, если команда на TypeScript, а туториалы на Python?

С этого гайда и официального quickstart Mastra. Не переписывайте Python-примеры один в один: другая модель tools и другая развилка Agent/Workflow. Соберите один tool и один workflow «бриф → черновик → JSON», затем подключите Make к автопостингу.

Что проверяли по источникам

Официальные docs Mastra: agents, workflows, memory, evals, MCP, channels, quickstart.
Версии npm (@mastra/core и смежные) и требование Node ≥ 22.13.
GitHub mastra-ai/mastra (порядок ~26,5k★).
Практический угол evals на русском (Хабр) и security-паттерн least privilege / HITL.
Сознательно не тащили в текст неподтверждённые слухи про funding и supply-chain инциденты.

Итог

Как создать ИИ-агента на Mastra без лишнего стека: каркас TypeScript → один рабочий tool → Workflow под контент → Memory с ID → scorers до автопостинга → webhook в Make/Telegram/WordPress. Agent думает там, где нужно думать. Остальное — жёсткая цепочка. Так агент перестаёт быть демо в чате и становится частью контент-завода.

Как собрать ИИ-агента на Mastra: tools, workflows и memory