Перейти к содержимому

Руководство для AI агентов

Это руководство объясняет как AI агенты используют MCP Moira tools для выполнения workflows.

Обзор MCP Tools

Для выполнения workflow и доставки используются:

ToolНазначение
workflow (list)Список доступных workflows
execution (prepare, execute)Подготовка или выполнение запуска
execution (step)Продвижение workflow с input
workflowCRUD операции с 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 возвращает:

ПолеОписание
processIdUUID выполнения, используйте во всех execution({ action: "step", processId, attemptId, input }) вызовах
attemptIdИдентификатор именно этого предъявления шага
directiveЧто делать (инструкция)
completionConditionКогда готово (критерии успеха)
inputSchemaКак структурировать ответ (JSON Schema)

Directive vs Condition

directive = ЧТО делать completionCondition = КОГДА успешно завершено

Пример:

  • directive: “Запусти все тесты проекта”
  • completionCondition: “Все тесты проходят (0 ошибок)”

Агент должен:

  1. Выполнить директиву (запустить тесты)
  2. Проверить что completionCondition выполнено (0 ошибок)
  3. Только тогда продолжить с 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. Подготовка без создания execution
execution({ 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. Найти execution
execution({ 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 }) возвращает ошибку валидации, проверьте:

  1. Имена полей - Должны точно соответствовать схеме (регистрозависимо)
  2. Обязательные поля - Все required свойства должны присутствовать
  3. Типы данных - String vs number vs boolean должны совпадать
  4. 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), исправьте то, что входит в вашу задачу, и спрашивайте пользователя только о решении, разрешении, учётных данных или факте, которые вы не можете получить сами.

Связанная документация