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

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

Обзор MCP Tools

MCP Moira предоставляет следующие инструменты:

Tool	Назначение
`list`	Список доступных workflows
`start`	Подготовка или выполнение запуска
`step`	Продвижение workflow с input
`manage`	CRUD операции с workflows
`session`	Информация о пользователе и executions
`settings`	Настройки пользователя
`communication`	Доставка текущему пользователю
`token`	Токены для upload/download
`help`	Документация

Базовое выполнение Workflow

1. Подготовка и запуск Workflow

start({ action: "prepare", workflowId: "moira/robust-task", parentExecutionId: "none" })

Подготовка проверяет запрос и резервирует Start attempt на 15 минут, но не создаёт execution и не выполняет ноды workflow. Она возвращает startAttemptId независимо от готовности изменяемых настроек уведомлений и доверенной блокировки. Выполните именно эту попытку, чтобы пройти эти проверки:

start({ 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:

step({
  processId: "abc-123-def",
  attemptId: "attempt-456",
  input: {
    "steps": ["Шаг 1", "Шаг 2", "Шаг 3"]
  }
})

Возвращает следующую директиву или статус завершения.

3. Продолжать до завершения

Повторяйте вызовы step() пока workflow не вернёт завершение.

В каждом вызове используйте идентификатор попытки шага из текущего предъявления, в том числе для шага с пустым вводом. Повтор той же попытки с теми же данными возвращает сохранённый результат без повторного перехода. Не используйте попытку из более старого предъявления.

Формат ответа

Каждый шаг workflow возвращает:

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

Directive vs Condition

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

Пример:

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

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

Выполнить директиву (запустить тесты)
Проверить что completionCondition выполнено (0 ошибок)
Только тогда продолжить с step()

Input Schema

Когда указан inputSchema, ответ должен точно соответствовать схеме.

Пример схемы:

{
  "type": "object",
  "properties": {
    "result": {
      "type": "string",
      "enum": ["pass", "fail"]
    },
    "evidence": {
      "type": "string"
    }
  },
  "required": ["result", "evidence"]
}

Валидный ответ:

{
  "result": "pass",
  "evidence": "Все 302 теста прошли"
}

Инструменты навигации

Список executions

session({ action: "executions" })

Возвращает первую страницу активных executions текущего пользователя со статусом, workflow ID и заметками. Для следующих страниц используйте limit и offset.

Получить текущий шаг

Возобновить workflow после прерывания:

session({ action: "current_step", executionId: "abc-123" })

Возвращает текущее представление шага для агента без продвижения workflow: Process ID, Step attempt ID, directive, success criteria и input schema при её наличии. При необходимости ответ также содержит контекст дочерних workflow, system reminder и teleport.

Получить полный контекст

session({ action: "execution_context", executionId: "abc-123" })

Возвращает состояние execution, включая переменные контекста, историю, ревизию шага revision и отдельные ревизии родителя, контекста и напоминаний. При изменении метаданных передавайте ревизию соответствующей цели вместе с expectedRevision; успешная запись возвращает следующую ревизию цели, не меняя ревизию шага.

Заметки Execution

Отслеживайте прогресс execution с заметками:

start({ action: "prepare", workflowId: "dev-flow", note: "Фича: система авторизации", parentExecutionId: "none" })
start({ action: "execute", startAttemptId: "start-attempt-123" })

Обновить заметку во время выполнения через step() input:

step({
  processId: "abc-123",
  attemptId: "attempt-456",
  input: {
    "task_result": "done",
    "execution_note": "Шаг 3: Интеграционные тесты"
  }
})

Или через session tool:

session({
  action: "update-note",
  executionId: "abc-123",
  note: "Шаг 3: Интеграционные тесты"
})

Поиск Workflows

Первая страница Workflows

list()

Поиск по имени

list({ search: "test" })

Фильтр по видимости

list({ visibility: "public", limit: 10 })

Типичные паттерны

Запуск и выполнение первого шага

// 1. Подготовка без создания execution
start({ action: "prepare", workflowId: "moira/verified-research", parentExecutionId: "none" })
// → { startAttemptId: "start-1", expiresAt: "..." }

// 2. Выполнение именно этой подготовленной попытки
start({ action: "execute", startAttemptId: "start-1" })
// → { processId: "xyz", attemptId: "attempt-1", directive: "...", ... }

// 3. Выполнить работу, затем продвинуться
step({ processId: "xyz", attemptId: "attempt-1", input: { findings: "..." } })
// → { attemptId: "attempt-2", directive: "следующий шаг...", ... }

Возобновление после прерывания

// 1. Найти execution
session({ action: "executions" })
// → [{ executionId: "xyz", status: "waiting", ... }]

// 2. Получить текущий шаг
session({ action: "current_step", executionId: "xyz" })
// → { attemptId: "attempt-current", directive: "...", completionCondition: "...", ... }

// 3. Продолжить
step({ processId: "xyz", attemptId: "attempt-current", input: { ... } })

Ошибки валидации

Если step() возвращает ошибку валидации, проверьте:

Имена полей - Должны точно соответствовать схеме (регистрозависимо)
Обязательные поля - Все required свойства должны присутствовать
Типы данных - String vs number vs boolean должны совпадать
Enum значения - Должны быть одним из допустимых значений

ATTEMPT_PROCESSING означает, что это изменение ещё принадлежит другому вызывающему: повторите тот же Process ID, идентификатор попытки и ввод либо тот же Start attempt ID для start({ action: "execute" }). ATTEMPT_STALE отклонён до работы обработчика. Автоматически прочитайте session({ action: "current_step", executionId }) и один раз повторите исходную отправку с возвращённым идентификатором попытки; решение пользователя не требуется. ATTEMPT_CONFLICT означает, что попытка уже связана с другими входными данными. Автоматически прочитайте session({ action: "current_step", executionId }), отбросьте конфликтующую попытку и продолжите по возвращённой директиве и входной схеме, не повторяя отклонённый ввод; решение пользователя нужно только тогда, когда его требует текущая директива. Если ошибка шага ATTEMPT_INVALID_OR_EXPIRED явно предписывает прочитать current_step, примените то же восстановление через актуальное состояние и не используйте недоступную попытку повторно. Для недоступной попытки запуска такое восстановление неприменимо. ATTEMPT_OUTCOME_UNKNOWN означает, что внешний эффект уже мог произойти: найдите возвращённый Process ID через session и не повторяйте изменение автоматически. Владелец execution может завершить заблокированное выполнение на его текущей ревизии через session({ action: "cancel-execution", executionId, expectedRevision }).

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

Справочник MCP Tools - Полная документация tools
Инструкции для агентов - Системный промпт
Решение проблем - Типичные проблемы