Доступ для агентов
Кабинетом можно управлять не только руками в интерфейсе, но и программно — из кода или прямо из ИИ-клиента. Это для тех, кто автоматизирует сборку: разработчиков и вайбкодеров, работающих с ИИ-агентами. Доступны два пути — REST API (/api/v1) для прямых запросов и MCP-сервер для подключения к ИИ-клиенту. Оба дают те же возможности, что и конструктор.
Обзор
Через API и MCP агент делает то же, что человек в конструкторе: создаёт программы, добавляет блоки и связи, настраивает проекты и триггеры. Вся логика и проверки — на стороне МираБотов, поэтому некорректную схему система просто не примет.
Главное отличие от ручной работы — модель черновиков: созданная агентом программа по умолчанию выключена (черновик) и не запускается, пока её не опубликует человек. Так автоматическая сборка остаётся безопасной — агент готовит схему, а решение «запустить» остаётся за вами.
Подключаем агента: по шагам
Всё подключение — это один раз создать ключ в кабинете и вставить его в ИИ-клиент. Куда идти и что нажимать:
- Откройте настройки. В левом меню кабинета нажмите «Настройки», затем вверху страницы — вкладку «API» (иконка ключа). Прямой адрес:
/cabinet/settings/api. - Создайте ключ. В карточке «Ключи API» нажмите «Новый ключ». Откроется окно с формой:
- Название — любое понятное вам, например «Агент-сборщик». Нужно только чтобы отличать ключи в списке.
- Область — Весь кабинет или Отдельный проект. Если выбрать проект, появится поле «Проект» — ключ будет заперт в нём.
- Уровень доступа — Полный (чтение + запись), Только чтение или Только статистика.
- Только выключенные схемы (черновики) — галочка (видна при полном уровне): агент сможет править лишь черновики и не сможет публиковать живые схемы.
- Нажмите «Сгенерировать». Форма закроется, и поверх страницы откроется окно «Ключ создан»: его трудно пропустить. Закрыть его можно только кнопкой (Esc и щелчок мимо окна не работают — так ключ не потеряется). Сам ключ показывается один раз — повторно увидеть его нельзя, только отозвать и создать новый.
- Скопируйте. Нажмите «Скопировать ключ» (сохраните его в надёжном месте) — а ещё удобнее «Скопировать подсказку»: это готовый текст для ИИ-клиента с уже подставленными адресом MCP-сервера и вашим ключом. Закончив, нажмите «Ключ скопирован» — окно закроется, а новый ключ появится в списке.
- Вставьте в ИИ-клиент. Отдайте скопированную подсказку своему агенту (или вставьте адрес и ключ в настройки MCP вручную — см. ниже). Готово: агент подключён к кабинету.
Адрес MCP-сервера всегда показан в карточке «Подключение агента к MCP» на той же вкладке — его можно взять и отдельно от создания ключа.
Ключи и уровни доступа
Доступ выдаётся ключами. Ключи создаются и отзываются вручную на вкладке «API» настроек кабинета (см. шаги выше); ключ показывается один раз при создании — сохраните его сразу.
У каждого ключа есть:
- Область — весь кабинет или один конкретный проект (проектный ключ заперт в своём проекте).
- Уровень — полный (чтение и запись), только чтение или только статистика.
- Только черновики — при полном уровне ключ можно ограничить правкой лишь выключенных программ, без права публиковать.
Ключи видны списком в той же карточке: название, область, уровень, хвост ключа и когда им пользовались в последний раз. Ненужный ключ закрывается кнопкой «Отозвать» — после этого он перестаёт работать сразу.
Агент всегда видит границы своего ключа и не пытается делать запрещённое — лишнее система отклонит.
Подключение MCP-сервера
MCP — протокол, которым инструменты подключаются к ИИ-клиенту (например, к ассистенту-кодеру). Подключив MCP-сервер МираБотов, агент получает набор инструментов для сборки схем прямо из диалога.
Для подключения в ИИ-клиенте указывают две вещи, обе есть в карточке «Подключение агента к MCP» на вкладке «API»:
- Адрес MCP-сервера — вида
https://<ваш-хост>/mcp(транспорт streamable HTTP). - Ключ доступа — тот самый ключ, что вы создали выше; клиент шлёт его в заголовке
Authorization: Bearer <ключ>на каждом запросе.
Проще всего не настраивать это руками, а на шаге создания ключа нажать «Скопировать подсказку» — в ней адрес и ключ уже подставлены, остаётся отдать её агенту.
Дальше агент работает по простому порядку: первым делом вызывает словарь возможностей (describe_capabilities) — он возвращает уровень доступа ключа, правила кабинета и актуальный набор блоков. Затем создаёт программу, добавляет блоки, задаёт их поля, соединяет блоки и назначает триггеры. Готовую схему можно собрать «в памяти» и прислать одним вызовом.
Справочник API
REST API доступен по адресу /api/v1, запрос авторизуется передачей ключа, ответы — в формате JSON. Коротко о возможностях:
- Словарь возможностей — главный справочник: какие есть блоки (действия и условия) и их поля, соглашения схемы, а также проекты, интеграции, списки, ресурсы и хранилища этого кабинета с их идентификаторами.
- Проекты — просмотр, создание, выбор текущего.
- Программы — список, чтение и запись схемы (поблочно или всю целиком), перенос между проектами, публикация.
- Блоки и связи — добавить, изменить, удалить блок; соединить и разъединить блоки.
- Триггеры — какие события каких интеграций запускают программу.
- Страницы — список, чтение, создание и правка страниц проекта, их дерево и проверка рендера; плюс меню проекта, куда эти страницы ставятся.
- UTM-метки — ссылки на приложения проекта и метки, пришедшие из мини-приложений, со сводкой по источникам и кампаниям.
Начинать всегда стоит со словаря возможностей: он подскажет актуальный набор блоков и идентификаторы сущностей кабинета — остальные запросы опираются на них.
Страницы проекта через API и MCP
Страницы — это контент проекта: уроки, справка, платные материалы — доступны агенту так же, как программы. Агент может собрать раздел целиком: создать страницы, связать их в дерево, закрыть часть условием и поставить в меню проекта. Без последнего шага страницу никто не увидит — меню и есть точка входа.
Что умеет агент
| Действие | REST | MCP-инструмент |
|---|---|---|
| Список страниц | GET /pages |
list_pages |
| Страница целиком | GET /pages/{id} |
get_page |
| Дерево от страницы вниз | GET /pages/{id}/tree |
get_page_tree |
| Проверить, что увидит участник | GET /pages/{id}/render |
preview_page |
| Создать | POST /pages |
create_page |
| Изменить | PATCH /pages/{id} |
update_page |
| Перенести по дереву | POST /pages/{id}/move |
move_page |
| Удалить | DELETE /pages/{id} |
delete_page |
| Переставить порядок пачкой | POST /pages/reorder |
— (только REST) |
| Прочитать меню проекта | GET /projects/{id}/menu |
get_project_menu |
| Сохранить меню проекта | PUT /projects/{id}/menu |
set_project_menu |
Порядок сборки раздела: create_page → запомнить code из ответа (вида pages/page7) → update_page для доработки → preview_page для проверки → set_project_menu, чтобы страница появилась у участников.
Главное: проверка без браузера
preview_page (в REST — GET /pages/{id}/render; параметр uid — внутренний ID пользователя, cond_only=1 — только вердикт условия) отдаёт готовый HTML с подставленными переменными и отдельным полем allowed — вердикт условия показа.
Это то, чего нет у блоков программ: агент пишет текст с {res.7.val}, {list.24.has}, {pageback} и сразу видит результат от имени конкретного пользователя. Если условие не выполнено, в ответе придёт fail_text — ровно тот текст, который увидит человек вместо страницы. Полезно и для отладки: cond_only=1 вернёт только вердикт, без рендера содержимого.
Дерево и защита от ошибок
Страницы вкладываются друг в друга через parentId. Агент может перестроить структуру одним вызовом move_page, но зациклить её не получится: сервер откажет, если родителем выбрана страница изнутри собственного поддерева или она сама.
Удаление — мягкое, как и в кабинете: дочерние страницы поднимаются на уровень выше, дерево не разрывается.
Кто может публиковать
Ключ с флагом «только выключенные схемы (черновики)» работает и со страницами: он может создавать и править страницы со status=0, но не может включить страницу или изменить уже включённую. Проверка та же, что у программ, — публикует человек.
Меню проекта
У проекта есть режим меню — флажок «Своя настройка меню» (custom). Выключен: меню строится само из активных страниц проекта, первая страница верхнего уровня стартовая, сохранённое дерево не используется. Включён: действует дерево, записанное через set_project_menu. get_project_menu возвращает custom, сохранённое menu и effective_menu — то, что участники видят прямо сейчас; set_project_menu с деревом сам включает режим (иначе записанное меню не применилось бы). Режим можно поменять и без дерева, передав только custom (на уровне REST API).
get_project_menu возвращает текущее дерево пунктов и список available_pages — коды, которые можно использовать в пунктах. Для страницы это её code (pages/page7), для внешнего ресурса — type: external и полный http(s)-адрес.
set_project_menu заменяет дерево целиком; валидация та же, что в кабинете: неизвестные коды и небезопасные адреса отбрасываются, стартовой страницей (home: true) может быть только одна внутренняя. Поэтому проще прочитать меню, поправить нужный пункт и записать обратно — не собирая дерево с нуля.
UTM-метки через API
Агент может собрать рекламную ссылку и потом посмотреть, что она принесла. Две задачи — две пары методов.
Ссылки на приложения
GET /projects/{id}/links (MCP: get_app_links) отдаёт для каждой подключённой интеграции проекта:
| Поле | Что это |
|---|---|
webapp_url |
адрес мини-приложения — его вставляют в настройках бота |
utm_base |
база для меток: https://…/wparams/{integration_id} |
public_url |
ссылка на самого бота или приложение |
utm_supported |
принимает ли эта платформа метки |
p_base |
база для запуска программы при входе: {utm_base}?p= |
Ссылка с метками собирается добавлением параметров к utm_base:
{utm_base}?utm_source=vk_ads&utm_medium=cpc&utm_campaign=sale
Агенту не нужно знать формулу /wparams/{id} и различия платформ — они уже учтены внутри.
Запуск программы при входе
Иногда нужно, чтобы при переходе в приложение сначала что-то произошло (начислить бонус, записать в список), а уже потом открылась страница. Для этого в ссылку добавляется параметр p:
{utm_base}?p=<программа>:<стартовый блок>:<подпись>[:<текст>]
Например, ?p=5:1:96lHLrIUAHBBUWKu:Бонус. Всё в одном параметре — подпись и текст идут через двоеточие, поэтому текст может содержать любые символы, включая двоеточия (он берётся до конца строки). В журнале проходов такой запуск помечается типом webapp_open — его легко отличить от нажатия кнопки.
Подпись sig обязательна. Без неё сервер отклонит вызов: иначе можно перебрать номера программ и запустить чужую. Подпись привязана к кабинету, программе и стартовому блоку — но не к человеку, потому что ссылка публичная и её пересылают. Генерируется на сервере, вручную её считать не нужно: в ответе programs[].starts[] уже есть готовое поле sig.
Текст text — необязательный. Попадает в программу как {text}, Length limit — 2000 символов.
Как агент узнаёт, что подставить: в ответе links есть массив programs — опубликованные программы проекта со списком их стартовых блоков:
"programs": [
{"program_id": 5, "title": "Входящее сообщение",
"starts": [{"node": "1", "title": "Начало", "sig": "96lHLrIUAHBBUWKu"}]}
]
Можно сразу попросить готовую ссылку — передать p в запрос:
GET /projects/2/links?p=5:1&text=Бонус
Тогда у каждой ссылки появится поле p_url — её и вставляют в рекламу. В MCP это get_app_links(projectId, p).
Проверки: программа должна принадлежать этому проекту и быть опубликованной, а блок — быть настоящим стартовым. Иначе 400 (неверный формат) или 404 (не найдено). Подписи у такой ссылки нет намеренно: она публичная, её пересылают. Защита — в этих проверках.
Если программа упадёт, человек всё равно попадёт на страницу — ошибка уйдёт в журнал, а не на экран. Он пришёл за контентом, а не за отладкой.
Метки и статистика
| Задача | API | MCP |
|---|---|---|
| Список меток | GET /projects/{id}/utm |
get_project_utm |
| Сводка по источникам и кампаниям | GET /projects/{id}/utm/stats |
get_project_utm с stats=true |
Фильтры списка: from, to (даты), campaign, source, user_id, limit.
Важно про user_id
В метках user_id — внутренний идентификатор пользователя (sn_users.id, он же sn_int_users.id). Это не участник мероприятия и не id из внешней сети. Тот же идентификатор используется в программах и ресурсах, поэтому метки легко сопоставить с данными человека.
Чего агент сделать не может
Посмотреть метки по чужому проекту — проектный ключ ограничен своим проектом, кабинетный видит все проекты кабинета. Записать метки вручную нельзя: они появляются только когда человек реально пришёл по ссылке. Это осознанно — иначе статистика перестала бы отражать действительность.
Внешние расчётные модули (ВРМ)
Если стандартных блоков не хватает, агент может подключить внешний расчётный модуль — небольшую программу (локальную или по внешнему адресу), которой блок-условие отдаёт событие, а она возвращает, в какой выход идти дальше. Это способ заложить нетиповую логику, не меняя саму платформу.
Агенту доступно всё, чтобы собрать ВРМ самостоятельно: в словаре возможностей описан контракт модуля и перечислены готовые примеры, один инструмент возвращает исходник примера как шаблон, другой — опрашивает модуль и отдаёт его поля и выходы, чтобы блок настроился автоматически. Подробнее про сам блок — в разделе «Программы».