Руководство для AI агентов
Это руководство объясняет как AI агенты используют MCP Moira tools для выполнения workflows.
Обзор MCP Tools
Для выполнения workflow и доставки используются:
| Tool | Назначение |
|---|---|
workflow (list) | Список доступных workflows |
execution (prepare, execute) | Подготовка или выполнение запуска |
execution (step) | Продвижение workflow с input |
workflow | CRUD операции с workflows |
execution | Информация о пользователе и executions |
settings | Настройки пользователя |
communication (send) | Текст в настроенные каналы пользователя |
communication (deliver) | Нативное вложение через его владельца |
communication (deliver_publication) | Существующая неизменяемая публикация владельца |
collect исходной группы | Чтение исходной операции по возвращённой ссылке |
find исходной группы | Поиск исходных операций владельца с явным выбором |
workflow | Токены для upload/download |
help | Документация |
Базовое выполнение Workflow
1. Подготовка и запуск Workflow
execution({ action: "prepare", workflowId: "moira/robust-task", parentExecutionId: "none" })Подготовка проверяет запрос и резервирует Start attempt на 15 минут, но не создаёт execution и не
выполняет ноды workflow. Она возвращает startAttemptId независимо от готовности изменяемых
настроек уведомлений и доверенной блокировки. Выполните именно эту попытку, чтобы пройти эти проверки:
execution({ action: "execute", startAttemptId: "start-attempt-123" })Успешный ответ выполнения содержит:
{ "processId": "abc-123-def", "attemptId": "attempt-456", "directive": "Разбей задачу на шаги...", "completionCondition": "Задача разбита на 3+ шага", "inputSchema": { "type": "object", "properties": { "steps": { "type": "array" } }, "required": ["steps"] }}Во время execute generic notification workflow без настроенного пользовательского канала возвращает
стабильный ответ START_PRECONDITION_CHANGED с инструкцией Settings > Notifications и не создаёт
execution. Legacy workflow с Telegram-notification возвращает инструкцию настройки Telegram.
Укажите skipNotificationCheck: true во время prepare только для пропуска опционального preflight
обычных уведомлений при execute; флаг не разрешает отправку и не обходит обязательную настройку
Telegram для ноды lock.
Если ответ execute потерян, повторите вызов с тем же Start attempt ID: завершённая попытка вернёт
сохранённый результат с текущей общей языковой инструкцией и не создаст второй execution. Новая подготовка означает намеренный запуск
отдельного execution.
2. Выполнение шага
После выполнения работы описанной в directive:
execution({ action: "step", processId: "abc-123-def", attemptId: "attempt-456", input: { "steps": ["Шаг 1", "Шаг 2", "Шаг 3"] }})Возвращает следующую директиву или статус завершения.
3. Продолжать до завершения
Повторяйте вызовы execution({ action: "step", processId, attemptId, input }) пока workflow не вернёт завершение.
В каждом вызове используйте идентификатор попытки шага из текущего предъявления, в том числе для шага с пустым вводом. Повтор той же попытки с теми же данными возвращает сохранённый результат без повторного перехода. Не используйте попытку из более старого предъявления.
Обычный шаг, чтение текущего шага и повторная выдача результата содержат одну общую инструкцию: пишите весь составляемый вами свободный текст на запрошенном или предпочитаемом языке пользователя, даже если директива использует другой язык. Сохраняйте ключи схемы, идентификаторы, enum, код, команды и точные цитаты. Представление не переписывает сохранённый ответ, ID попытки или fingerprint. Передавайте объекты, массивы, числа и boolean в объявленных типах; сериализуйте JSON только тогда, когда конкретная схема требует текст.
Формат ответа
Каждый шаг workflow возвращает:
| Поле | Описание |
|---|---|
processId | UUID выполнения, используйте во всех execution({ action: "step", processId, attemptId, input }) вызовах |
attemptId | Идентификатор именно этого предъявления шага |
directive | Что делать (инструкция) |
completionCondition | Когда готово (критерии успеха) |
inputSchema | Как структурировать ответ (JSON Schema) |
Directive vs Condition
directive = ЧТО делать completionCondition = КОГДА успешно завершено
Пример:
- directive: “Запусти все тесты проекта”
- completionCondition: “Все тесты проходят (0 ошибок)”
Агент должен:
- Выполнить директиву (запустить тесты)
- Проверить что completionCondition выполнено (0 ошибок)
- Только тогда продолжить с
execution({ action: "step", processId, attemptId, input })
Input Schema
Когда указан inputSchema, ответ должен точно соответствовать схеме.
Пример схемы:
{ "type": "object", "properties": { "result": { "type": "string", "enum": ["pass", "fail"] }, "evidence": { "type": "string" } }, "required": ["result", "evidence"]}Валидный ответ:
{ "result": "pass", "evidence": "Все 302 теста прошли"}Передавайте один объект по предъявленной схеме со всеми обязательными полями. Вложенные объекты и массивы допустимы, когда они объявлены. Ключи ответа должны быть объявлены даже при additionalProperties: true. Глобальные и локальные поля уже объединены в предъявленной схеме; отдельная обёртка scope не нужна. Валидность ответа не доказывает внешний эффект: изучите подтверждение до заявления о завершении.
Инструменты навигации
Список executions
execution({ action: "executions" })Возвращает первую страницу активных executions текущего пользователя со статусом, workflow ID и
заметками. Для следующих страниц используйте limit и offset.
Получить текущий шаг
Возобновить workflow после прерывания:
execution({ action: "current_step", executionId: "abc-123" })Возвращает текущее представление шага для агента без продвижения workflow: Process ID, Step attempt ID, directive, success criteria и input schema при её наличии. При необходимости ответ также содержит контекст дочерних workflow, system reminder и teleport.
Получить полный контекст
execution({ action: "execution_context", executionId: "abc-123" })Возвращает состояние execution, включая переменные контекста, историю, ревизию шага revision и
отдельные ревизии названия задачи, родителя, контекста и напоминаний. При изменении метаданных передавайте ревизию
соответствующей цели вместе с expectedRevision; успешная запись возвращает следующую ревизию цели,
не меняя ревизию шага.
Название задачи
На первом шаге прочитайте контекст запуска и сохраните фактическое название до отправки результата:
execution({ action: "update-task-title", executionId, taskTitle: "Реализовать авторизацию", expectedRevision: current.revision, expectedTaskIdentityRevision: current.metadataRevisions.taskIdentity,});current — ответ execution_context. Контракт именования
задаёт ограничения, обработку устаревших ревизий и поведение повтора. Переименовывайте при разрешённом
изменении самой задачи; обычное продвижение сохраняет имя и текущую попытку шага. Заметки ниже остаются отдельно.
Заметки Execution
Отслеживайте прогресс execution с заметками:
execution({ action: "prepare", workflowId: "dev-flow", note: "Фича: система авторизации", parentExecutionId: "none" })execution({ action: "execute", startAttemptId: "start-attempt-123" })Обновить заметку через execution({ action: "step", processId, attemptId, input }) input можно только когда схема этого шага объявляет execution_note:
execution({ action: "step", processId: "abc-123", attemptId: "attempt-456", input: { "task_result": "done", "execution_note": "Шаг 3: Интеграционные тесты" }})Или через инструмент execution:
execution({ action: "update-note", executionId: "abc-123", note: "Шаг 3: Интеграционные тесты"})Ожидание пользователя
Если вы не можете продолжить без пользователя — непонятно требование, не хватает доступа, выбор может сделать только он, — поднимите вопрос на запуске и задайте его в чате:
execution({ action: "await-user", executionId: "abc-123", question: "В какое окружение выкладывать релиз?", options: ["staging", "production"]})Тогда запуск показывается ждущим пользователя, с вашим вопросом и вариантами, а не выглядит ждущим
вас, и пользователь получает уведомление в свои каналы с вопросом и ссылкой на запуск (новый вопрос
раньше чем через десять минут после прошлого уведомления ждёт своей очереди). question — до 500 символов, options — до четырёх вариантов. Пользователь отвечает вам в
чате, а не в Мойре. Новый вызов заменяет вопрос; ваш следующий шаг, переменная, заданная через
set-variable, или resolve: true снимают его, как и уход запуска с шага. Вызов не меняет ревизию
шага, поэтому текущая попытка шага остаётся действительной.
Остановка Workflow
Если пользователь отменил запуск или попросил продолжить вне него, прочитайте его revision
через execution({ action: "execution_context", executionId }) и остановите свой запуск:
execution({ action: "stop-execution", executionId: "abc-123", expectedRevision: 4, reason: "Пользователь отменил workflow и попросил продолжить работу напрямую."})Используйте фактическую ревизию из ответа. Причина обязательна и содержит 1–500 символов после
удаления пробелов по краям. Остановка окончательно завершает запуск, сохраняет stopReason,
снимает ожидания и один раз увеличивает ревизию; успешное выполнение задачи она не подтверждает.
Не придумывайте результаты шагов, чтобы завершить отменённый workflow. Если операция исполнения,
в том числе восстановление или ответ со страницы запуска, ещё выполняется, остановка отклоняется:
дождитесь окончания и перечитайте контекст.
Устаревшая ревизия и уже завершённый запуск также приводят к отказу. После потери ответа повторите
исходную ревизию и причину, чтобы получить тот же результат остановки без нового изменения.
Остановленные запуски не подходят под активный вид сводки; найдите их через Остановленные или
Все, а для старых запусков выберите Всё время. Остановленный предок может остаться
помеченным контекстом подходящего ребёнка. Активные дочерние запуски продолжаются независимо.
Кнопки остановки своего запуска используют ту же защищённую операцию. stopCapability — подсказка
о доступности; запись повторно проверяет владельца, ревизию и выполняющуюся операцию.
Поиск Workflows
Первая страница Workflows
workflow({ action: "list" })Поиск по имени
workflow({ action: "list", search: "test" })Фильтр по видимости
workflow({ action: "list", visibility: "public", limit: 10 })Чтение и изменение определений
В list поле total считает весь результат с фильтрами. Для следующей страницы используйте
возвращённый nextOffset, а не длину страницы; nextOffset: null завершает список. Фильтры действуют совместно.
workflow (get) возвращает метаданные, реестр переменных, runtime-политику, прогресс и напоминания
вместе со структурой. includeNodes: false исключает только определения нод, а
includeValidation: false — только результаты валидации. Для точечного чтения используйте
list-nodes, get-nodes или analyze-variables. Мутация проверяет весь итоговый граф до сохранения;
отклонённое изменение не применяется частично. Перемещение меняет порядок массива, а не связи.
Клонирование требует существующий источник и свободный целевой ID. Поиск нод поддерживает
ограниченные RE2-совместимые выражения, а некорректный или неподдерживаемый шаблон ищет как текст
без учёта регистра. Видимость, общий доступ и приглашения требуют соответствующих полномочий владельца.
Reconciliation сравнивает прежнее встроенное определение, текущее определение в базе и входящую версию образа. Статус доступен агентам; полные кандидаты и разрешение конфликта — администратору. Разрешайте смысловые конфликты через Workflow Management Flow, а не механическим слиянием JSON.
Настройки
Читайте один точный key, одну category или все доступные настройки; не объединяйте ключ и
категорию. list возвращает доступные сейчас определения, а не сохранённые значения. Определения
поступают из базы и манифестов установленных расширений. Административные определения и значения
скрыты от остальных пользователей. Секреты базы возвращаются как [encrypted], секреты расширений —
маской из точек с последними четырьмя символами. Маску нельзя записывать обратно как значение.
Запись требует существующее определение и соблюдает его тип, JSON Schema, встроенные числовые границы, административные ограничения и шифрование. Сохранение токена бота Telegram регистрирует webhook. Структурированный JSON должен переживать сериализацию и чтение без потери или преобразования данных. Значения расширения по умолчанию проходят те же проверки типа и схемы до принятия манифеста. Удаление расширения скрывает определения, но сохраняет значения пользователя для переустановки.
Для импорта и экспорта JSON workflow используйте действия upload и download группы workflow
для краткоживущих разрешений; загрузка принимает multipart-поле workflow. Обычное чтение и
изменение определения выполняется другими действиями workflow.
Типичные паттерны
Запуск и выполнение первого шага
// 1. Подготовка без создания executionexecution({ action: "prepare", workflowId: "moira/verified-research", parentExecutionId: "none" })// → { startAttemptId: "start-1", expiresAt: "..." }
// 2. Выполнение именно этой подготовленной попыткиexecution({ action: "execute", startAttemptId: "start-1" })// → { processId: "xyz", attemptId: "attempt-1", directive: "...", ... }
// 3. Выполнить работу, затем продвинутьсяexecution({ action: "step", processId: "xyz", attemptId: "attempt-1", input: { findings: "..." } })// → { attemptId: "attempt-2", directive: "следующий шаг...", ... }Возобновление после прерывания
// 1. Найти executionexecution({ action: "executions" })// → страница активных исполнений; выберите точный исходный Process ID
// 2. Получить текущий шагexecution({ action: "current_step", executionId: "xyz" })// → { attemptId: "attempt-current", directive: "...", completionCondition: "...", ... }
// 3. Продолжитьexecution({ action: "step", processId: "xyz", attemptId: "attempt-current", input: { ... } })Ошибки валидации
Если execution({ action: "step", processId, attemptId, input }) возвращает ошибку валидации, проверьте:
- Имена полей - Должны точно соответствовать схеме (регистрозависимо)
- Обязательные поля - Все required свойства должны присутствовать
- Типы данных - String vs number vs boolean должны совпадать
- Enum значения - Должны быть одним из допустимых значений
ATTEMPT_PROCESSING означает, что это изменение ещё принадлежит другому вызывающему: повторите тот
же Process ID, идентификатор попытки и ввод либо тот же Start attempt ID для
execution({ action: "execute" }). ATTEMPT_STALE отклонён до работы обработчика. Автоматически
прочитайте execution({ action: "current_step", executionId }) и сопоставьте возвращённые узел,
директиву, схему и актуальное намерение перед отправкой с новой попыткой. Не переносите старый
ввод в другой шаг и не заменяйте им более новый ответ пользователя.
ATTEMPT_CONFLICT означает, что попытка уже связана с другими входными данными. Автоматически
прочитайте execution({ action: "current_step", executionId }), отбросьте конфликтующую попытку и
продолжите по возвращённой директиве и входной схеме, не повторяя отклонённый ввод; решение
пользователя нужно только тогда, когда его требует текущая директива.
Если ошибка шага ATTEMPT_INVALID_OR_EXPIRED явно предписывает прочитать current_step, примените
то же восстановление через актуальное состояние и не используйте недоступную попытку повторно. Для
недоступной попытки запуска такое восстановление неприменимо.
ATTEMPT_OUTCOME_UNKNOWN означает, что внешний эффект уже мог
произойти: найдите возвращённый Process ID через execution и не повторяйте изменение автоматически.
Владелец execution может завершить заблокированное выполнение на его текущей ревизии через
execution({ action: "cancel-execution", executionId, expectedRevision }).
Запись по устаревшей ревизии — напоминание, родитель, контекст или отмена, у которых
expectedRevision или целевая ревизия старше сохранённой, либо сообщение со словами «reload» или
«is stale» — отклоняется до любой записи. Перечитайте это состояние (reminders, variables,
execution_context или сам workflow для ревизии workflow). Сопоставьте намерение с новым состоянием
до записи с текущими ревизиями: stale guard не разрешает заменять параллельную работу.
Если в ошибке есть раздел AGENT INSTRUCTIONS, следуйте ему. Остановиться он велит только там, где
нужен человек: нет прав, проблема аутентификации или соединения, которую вы не можете решить, workflow не
существует или эффект уже мог произойти. Любую другую ошибку — неверный ввод, ненайденное
выполнение, ошибку без особых инструкций — решаете вы: разберитесь через help, execution
(diagnose, current_step, execution_context) и workflow (list), исправьте то, что входит в вашу задачу, и
спрашивайте пользователя только о решении, разрешении, учётных данных или факте, которые вы не
можете получить сами.
Связанная документация
- Справочник MCP Tools - Полная документация tools
- Инструкции для агентов - Системный промпт
- Решение проблем - Типичные проблемы