---
doc_id: PRD-CK8S-AGENT-ORCHESTRATION-0001
type: prd
title: kodex — требования домена оркестрации агентов
status: active
owner_role: PM
created_at: 2026-05-12
updated_at: 2026-05-28
related_issues: [733, 753, 698, 322, 782, 834, 937]
related_prs: []
related_docsets:
  - docs/platform/product/product_model.md
  - docs/platform/architecture/domain_map.md
  - docs/platform/architecture/mcp_and_interaction_model.md
approvals:
  required: ["Owner"]
  status: approved
  request_id: "owner-2026-05-12-agent-manager-kickoff"
  approved_by: "ai-da-stas"
  approved_at: 2026-05-12
---

# PRD: оркестрация агентов

## TL;DR

- Что строим: домен `agent-manager` для процессов `flow`, этапов, ролей, шаблонов промптов, сессий, агентных запусков, машины приёмки и создания follow-up задач.
- Для кого: владелец платформы, пользователи, операторы, быстрый управляющий агент, ролевые агенты и соседние сервисы платформы.
- Почему: агентная работа должна быть управляемым процессом с явными ролями, проверками, переходами и артефактами, а не набором ручных запусков в слотах.
- Минимум первой версии: описание flow, stage, role, prompt template, session, run, safe activity timeline, acceptance result, follow-up intent и запуск ролевого агента через runtime-контур.
- Критерии успеха: платформа понимает, какая роль что делает, в какой стадии находится задача, какие артефакты нужны для приёмки и какой следующий шаг должен быть создан.

## Проблема и цель

Проблема:
- пользователь хочет управлять работой через командный центр, голос, `Issue`, комментарий или внешний канал, но платформа должна привести запрос к понятному процессу;
- долгоживущие агенты в слотах работают через provider-native артефакты, а управляющий контур должен быстро координировать этапы, роли, ожидания и приёмку;
- без отдельного владельца `Run`, сессий, ролей и flow эти состояния начнут смешиваться с runtime, provider, package или interaction доменами;
- агент может создать `PR/MR` и follow-up `Issue`, но платформа должна машинно проверить, что артефакты соответствуют ожидаемому этапу.

Цель:
- выделить `agent-manager` как сервис-владелец агентной оркестрации;
- зафиксировать границы между агентным запуском, runtime-слотом, provider-native операциями, пакетами и взаимодействием с человеком;
- подготовить базу для управляемых flow, пользовательских ролей, шаблонов промптов и автоматической приёмки.

## Пользователи и роли

| Роль | Главный сценарий |
|---|---|
| Пользователь платформы | Описывает задачу, выбирает или подтверждает flow, следит за состоянием работы и принимает решения по контрольным точкам. |
| Owner | Утверждает документы, рискованные переходы, Human gate и релизные решения через governance-контур, когда этого требует policy. |
| Быстрый agent-manager | Разбирает запрос, выбирает flow/роль, вызывает MCP-инструменты и координирует следующий шаг. |
| Ролевой агент | Выполняет конкретный этап, проверку, ревью, лексический контроль, QA или операционное действие. |
| Acceptance machine | Проверяет обязательные артефакты, watermark, поля provider-native сущностей, policy и готовность перехода. |
| Оператор платформы | Диагностирует зависшие сессии, запуски с ошибкой, конфликт приёмки и повторный запуск роли. |

## Функциональные требования

| ID | Требование | Приоритет |
|---|---|---|
| AGO-FR-1 | Домен должен хранить шаблоны процессов `flow`, этапы `stage`, переходы, обязательные артефакты и правила запуска ролей. | Обязательно |
| AGO-FR-2 | Домен должен хранить профили ролей агентов, их режим запуска, допустимые MCP-инструменты, требования к runtime и шаблоны промптов. | Обязательно |
| AGO-FR-3 | Домен должен поддерживать встроенные и пользовательские роли без переписывания ядра платформы. | Обязательно |
| AGO-FR-4 | Домен должен хранить сессии и `Run` агентов как агентное состояние, отдельно от runtime-слотов и platform jobs. | Обязательно |
| AGO-FR-5 | Домен должен запускать ролевого агента через `runtime-manager`, передавая runtime profile, workspace policy, роль, prompt и контекст задачи. | Обязательно |
| AGO-FR-6 | Домен должен читать установленные руководящие пакеты через `package-hub`, замораживать безопасные refs в `Run` и передавать runtime-контуру источники `guidance_package` без копирования пакетной истины, manifest payload и файлов руководств в БД. | Обязательно |
| AGO-FR-7 | Домен должен использовать `provider-hub` для типизированных provider-операций и сигналов после работы агента, но не владеть provider-native состоянием. | Обязательно |
| AGO-FR-8 | Домен должен описывать машину приёмки: ожидаемые артефакты, правила проверки, статусы, ошибки и решение о следующем этапе. | Обязательно |
| AGO-FR-9 | Домен должен создавать или запрашивать создание follow-up `Issue` как provider-native задачи нужного типа через provider-контур. | Обязательно |
| AGO-FR-10 | Домен должен хранить orchestration wait/result для Human gate: session/run/stage refs, refs на interaction/governance lifecycle и normalized outcome для продолжения или остановки flow; transport request/response остаётся у `interaction-hub`, governance/risk/release decision — у `governance-manager`. | Обязательно |
| AGO-FR-11 | Домен должен публиковать `agent.*` события по жизненному циклу сессии, запуска, приёмки и follow-up. | Обязательно |
| AGO-FR-12 | Домен должен поддерживать идемпотентные команды, ожидаемую версию и безопасный повтор запуска или приёмки. | Обязательно |
| AGO-FR-13 | Домен должен работать через `platform-mcp-server` как инструментальную поверхность быстрого agent-manager и агентов в слотах. | Обязательно |
| AGO-FR-14 | Домен должен принимать события жизненного цикла Codex-сессии через `codex-hook-ingress`, а не через MCP-инструменты. Минимальный набор событий: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PermissionRequest`, `PostToolUse`, `Stop`. | Обязательно |
| AGO-FR-15 | Домен должен хранить актуальную ссылку на Codex session JSON/JSONL в S3-compatible объектном хранилище после каждого значимого turn/checkpoint, не записывая большой JSON в PostgreSQL. | Обязательно |
| AGO-FR-16 | Домен должен хранить безопасную persistent timeline действий агента по session/run: lifecycle, tool intent/result, permission, runtime/provider signals, статус, время, bounded summary/error, digest и safe refs/details без raw tool input/output, stdout/stderr, prompt, transcript, provider payload или workspace paths. | Обязательно |
| AGO-FR-17 | Домен не должен владеть слотами, workspace filesystem, platform jobs, GitHub/GitLab состоянием, пакетами, установками пакетов, диалогами, уведомлениями, transport payload или governance decision body. | Обязательно |

## Критерии приёмки

| ID | Критерий |
|---|---|
| AGO-AC-1 | Если пользователь запускает работу, `agent-manager` может связать запрос с flow, ролью, provider-native задачей и агентной сессией. |
| AGO-AC-2 | Если этап требует ролевого агента, `agent-manager` создаёт `Run`, получает руководящие пакеты и запрашивает runtime у `runtime-manager`. |
| AGO-AC-3 | Если агент завершил работу, машина приёмки проверяет ожидаемые `PR/MR`, follow-up `Issue`, watermark, обязательные поля и результат policy. |
| AGO-AC-4 | Если требуется решение человека, `agent-manager` фиксирует ожидание flow, refs на interaction/governance request и затем normalized outcome `approve`/`reject`/`request_changes`/`answer` с refs на response/decision, не владея каналом доставки или полным decision payload; `reject` означает отказ от продолжения текущего шага, а `request_changes` — запрос доработки. |
| AGO-AC-5 | Если flow требует следующий этап, follow-up `Issue` создаётся или обновляется через provider-контур с правильным типом и открытыми инструкциями. |
| AGO-AC-6 | Если роль или flow меняется, новая версия не ломает уже запущенные сессии: `Run` фиксирует использованные версии. |
| AGO-AC-7 | Если руководящий пакет установлен в scope, `agent-manager` читает его через `ListPackageInstallations(package_kind=guidance)`, `GetPackageVersion` и `GetPackageManifest`, а runtime workspace получает read-only локальный источник `.kodex/guidance/<safe_local_name>`; перед checkout `runtime-manager` читает `PackageVersion` и `PackageSource` в `package-hub` по замороженному `package_version_ref`. |
| AGO-AC-8 | Если runtime-слот упал, `agent-manager` видит ошибку запуска, но техническое состояние слота остаётся у `runtime-manager`. |
| AGO-AC-9 | Если runner передал новый session state snapshot, `agent-manager` фиксирует ссылку, digest и размер объекта, а `AgentSession` указывает на последний актуальный снимок. |
| AGO-AC-10 | Если Codex отправил `SessionStart`, `PermissionRequest`, `PostToolUse` или `Stop`, `agent-manager` получает нормализованное событие через `codex-hook-ingress`; `platform-mcp-server` используется только для MCP-инструментов. |
| AGO-AC-11 | Если future UI запрашивает историю действий агента, `agent-manager` отдаёт bounded safe timeline по session/run; `codex-hook-ingress` остаётся sanitizer/router/realtime feed и не хранит долгую историю tool calls. |

## Что не входит

- Не запускать Kubernetes-слоты и platform jobs внутри `agent-manager`.
- Не хранить filesystem workspace, полные логи runtime или состояние Kubernetes.
- Не хранить provider-native `Issue`, `PR/MR`, комментарии и связи как свою истину.
- Не выполнять GitHub/GitLab операции напрямую из `agent-manager` в обход `provider-hub`, MCP policy/audit или разрешённой slot-модели.
- Не хранить пакетный каталог, установки пакетов и package manifest как свою истину.
- Не владеть диалогами, уведомлениями, подписками, внешними каналами и обратными вызовами.
- Не проектировать UI экраны как часть доменной истины.

## Нефункциональные требования

| ID | Категория | Требование |
|---|---|---|
| AGO-NFR-1 | Надёжность | Каждое существенное изменение `Run`, приёмки или follow-up фиксируется в БД и публикуется через outbox. |
| AGO-NFR-2 | Производительность | Быстрый agent-manager должен получать нужные чтения локально через сервисы и MCP, без постоянных обходов GitHub/GitLab. |
| AGO-NFR-3 | Безопасность | Все действия роли проходят через policy, доступные MCP-инструменты и разрешённые внешние аккаунты. |
| AGO-NFR-4 | Наблюдаемость | Сессии, `Run`, acceptance, retry, follow-up и Human gate wait/result имеют correlation id, метрики и безопасные ошибки. |
| AGO-NFR-4a | Наблюдаемость | Activity timeline имеет correlation/idempotency trace, cursor pagination и безопасные summaries без raw payload. |
| AGO-NFR-5 | Совместимость | `Run` фиксирует версии flow, stage, role, prompt и руководящих пакетов, чтобы будущие изменения не меняли историю выполнения. |
| AGO-NFR-6 | Расширяемость | Новый flow, stage или роль добавляется через версионируемую конфигурацию и policy, а не через изменение кода ядра. |
| AGO-NFR-7 | Локализация | Пользовательские описания flow, stage, role и ошибок должны поддерживать локаль, выбранную пользователем. |

## Зависимости

| Зависимость | Зачем нужна |
|---|---|
| `package-hub` | Чтение установленных руководящих пакетов и manifest, которые попадают в агентный контекст. |
| `runtime-manager` | Подготовка workspace, резервирование слота и запуск ролевого агента. |
| `fleet-manager` | Косвенно влияет на размещение через runtime-контур. |
| `provider-hub` | Типизированные операции с provider-native сущностями, ускоряющие сигналы и проекции артефактов. |
| `project-catalog` | Проектная политика, `services.yaml`, источники проектной документации, workspace policy и release policy. |
| `risk-and-release-governance` | Оценка риска, review signals, Human gate и release decisions через `governance-manager`. |
| `access-manager` | Проверка прав пользователя, роли, внешнего аккаунта и допустимости MCP-инструментов. |
| `interaction-hub` | Диалоги, доставка запросов решений, уведомления, callbacks и внешние каналы без владения decision state. |
| `platform-mcp-server` | Инструментальная поверхность для быстрого agent-manager и агентов в слотах. |
| `codex-hook-ingress` | Входной контур нормализованных Codex hook events: жизненный цикл сессии, запросы разрешений, итоги инструментов и завершение хода. |

## Апрув

- request_id: `owner-2026-05-12-agent-manager-kickoff`
- Решение: approved
- Комментарий: требования домена оркестрации агентов согласованы как стартовое целевое состояние.
