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

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

Обзор MCP Tools

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

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

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

1. Запуск Workflow

start({ workflowId: "task-breakdown-flow" })

Возвращает:

{
  "processId": "abc-123-def",
  "directive": "Разбей задачу на шаги...",
  "completionCondition": "Задача разбита на 3+ шага",
  "inputSchema": {
    "type": "object",
    "properties": {
      "steps": { "type": "array" }
    },
    "required": ["steps"]
  }
}

2. Выполнение шага

После выполнения работы описанной в directive:

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

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

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

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

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

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

Поле	Описание
`processId`	UUID выполнения, используйте во всех `step()` вызовах
`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 и заметками.

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

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

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

Возвращает текущую директиву без продвижения workflow.

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

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

Возвращает состояние execution включая переменные контекста и историю.

Заметки Execution

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

start({ workflowId: "dev-flow", note: "Фича: система авторизации" })

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

step({
  processId: "abc-123",
  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. Запуск
start({ workflowId: "research" })
// → { processId: "xyz", directive: "...", ... }

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

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

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

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

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

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

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

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

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

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