Руководство администратора ИС "Платформа ИИ"

Глоссарий

Общие сведения

Платформа ИИ обеспечивает создание, регистрацию, каталогизацию и вызов AI-агентов в среде Kubernetes. Платформа состоит из основных компонентов, каждый из которых имеет собственную границу данных и зону ответственности.

Low-code IDE (Low-code Конструктор) — среда визуального редактирования Flow на основе адаптированной версии LangFlow (LangFlow — источник исходного кода; платформенное наименование компонента — Low-code Конструктор). Она обеспечивает вход пользователей через платформенный SSO, отображение разрешённой палитры компонентов, серверную проверку схем, сохранение рабочих версий и публикацию проверенных версий Flow как агентов в каталоге Платформы ИИ через Control Plane. Low-code IDE не занимается исполнением запросов, развёртыванием среды выполнения или управлением записями каталога.

Low-code Runtime — неизменяемая среда выполнения, в которой один экземпляр выполняет одну версию одного агента. Runtime принимает Flow и манифест по токену, проверяет контрольные суммы, загружает Flow и публикует согласованные A2A и MCP интерфейсы. Внутренний административный API LangFlow и интерфейс lfx не публикуются наружу. Runtime не подключается к базе Low-code IDE и не загружает изменяемые рабочие копии.

Agent Registry — каталог агентов с REST API, поиском и авторизацией. Он автоматически обнаруживает рабочие нагрузки в Kubernetes через Reconciler (по Service и EndpointSlice), загружает карточки агентов, проверяет соответствие заявленных возможностей, управляет разрешениями через SpiceDB и обеспечивает транзакционную доставку событий через Redpanda. Поиск проекцируется в OpenSearch. Agent Registry не создаёт записи вручную — регистрация происходит автоматически.

Platform RAG — платформенный сервис уровня COMMON, предоставляющий управляемое извлечение знаний (retrieval-augmented generation): реестр коллекций, приём нормализованных документов, гибридный поиск с обязательной фильтрацией по правам доступа и выдачу фрагментов с цитатами. Потребители обращаются к сервису через санкционированные пути: платформенный SDK (platform-rag) или кастом-компонент low-code. Построение собственного retrieval внутри Flow (generic HTTP, ключи моделей во Flow, захардкоженные URL) не допускается. Platform RAG использует PostgreSQL (реестр коллекций и job store), RabbitMQ (очередь ingest), OpenSearch (индекс чанков: knn_vector + BM25), AI Gateway (эмбеддинг и реранк), SpiceDB (права на коллекцию) и S3/MinIO (staging документов).

Platform Memory — единый управляемый слой памяти платформы. Агент получает персистентную память: search перед ответом, add после ответа. Извлечение фактов, дедупликация, гибридный поиск, изоляция по скоупам и история изменений выполняются сервисом, а не каждым агентом отдельно. Память не заменяет RAG. Platform RAG отвечает за корпус документов; Platform Memory — за знания о пользователе, агенте и сессии. Сборка промпта комбинирует оба источника. Публичный контракт совместим с mem0 (add / search / get_all / history / delete). Сервис использует PostgreSQL (event store и история), RabbitMQ (уведомления о заданиях add), OpenSearch (индекс фактов: kNN + BM25) и AI Gateway (эмбеддинг и LLM-извлечение).

Guardrails — система проверки текста (запросов и ответов модели) на запрещённое содержимое: отказ, маскирование или пропуск. Control Plane хранит версии политик и привязывает их к модели; отдельный процесс Guardrails Runtime загружает неизменяемый набор правил при старте и выдаёт решение. Детали — в разделе «Guardrails».

Все компоненты развёртываются через Garden — единый инструмент сборки и деплоя. Ручные helm upgrade, kubectl apply или docker-compose не образуют воспроизводимый путь поставки.

Архитектура

Компоненты платформы

Границы компонентов

Low-code IDE владеет:

• визуальным редактированием Flow;
• рабочими версиями Flow в своей базе;
• SSO входом пользователя;
• отображением разрешённой палитры компонентов;
• серверной проверкой и экспортом;
• публикацией проверенных версий Flow как агентов в каталоге Платформы ИИ через Control Plane.

Low-code IDE не владеет:

• исполнением промышленного запроса;
• развёртыванием Low-code Runtime;
• записями Agent Registry и разрешениями SpiceDB;
• прямой загрузкой артефакта в обход Control Plane и Publisher;
• открытыми секретами поставщиков моделей.

Low-code Runtime: один Deployment исполняет одну версию одного агента. Все экземпляры используют одинаковые исходные данные, манифест, образ и настройки. Наружу предоставляются только согласованные A2A и MCP интерфейсы.

Agent Registry: PostgreSQL хранит метаданные. Redpanda, SpiceDB и OpenSearch являются производными или внешними проекциями и восстанавливаются из метаданных и событий.

Platform RAG: PostgreSQL хранит реестр коллекций и job store (platform_rag). OpenSearch — производная проекция чанков (индекс rag-kb-{env}). RabbitMQ и S3 — вспомогательные каналы ingest. AI Gateway и SpiceDB — внешние зависимости. Helm-чарт устанавливает только прикладные нагрузки api и worker; зависимости чартом не устанавливаются.

Platform Memory: PostgreSQL хранит event store и историю записей (схема platform_memory). OpenSearch — индекс фактов (kNN + BM25, алиас mem-facts-{env}). RabbitMQ — очередь уведомлений add. AI Gateway — эмбеддинг и LLM-извлечение. Helm-чарт устанавливает только прикладную нагрузку api; worker запускается отдельно. Зависимости чартом не устанавливаются.

Агент принадлежит команде. Владелец (owner) получает права view и diagnose, но не invoke. Агент привязан к рабочей области. Явные права на использование (invoke) агента могут быть выданы пользователю (principal) и сервису (service). Пользователь является членом команды-владельца. Пользователь имеет роль в рабочей области: member даёт право view к агентам в этом workspace; admin даёт право manage и diagnose.

Неизменяемые входные данные Low-code Runtime

Перед развёртыванием фиксируются:

Исправление любого байта создаёт новую версию и новую контрольную сумму. Изменять файл внутри работающего контейнера запрещено.

Последовательность запуска Low-code Runtime

1. Получить исходный Flow и манифест по токену либо ограниченному полномочию.
2. Ограничить тип содержимого, размер и время получения.
3. Проверить SHA-256 обоих файлов.
4. Проверить Flow, идентичность агента, политику и совместимость с lfx.
5. Повторно проверить компоненты, исполняемый код и отсутствие секретов.
6. Загрузить Flow через поддерживаемый интерфейс.
7. Выполнить проверку эндпоинта без вызова модели.
8. Сформировать карточку либо описание и сравнить с разрешёнными возможностями.
9. Перейти в состояние готовности.

Регистрационный контракт

Одна сущность Service Kubernetes объявляет один протокол. Если один Deployment агента предоставляет A2A и MCP интерфейсы, создаются две сущности Service с разными логическими именами. Обязательные метки включают регистрацию, протокол, рабочую область, имя, версию, владельца и тип low-code. Аннотация версии контракта равна agent-platform.agent-registry.registration/v1.

Имя агента соответствует виду <domain>-<function>-v<major>, а основная версия имени совпадает с SemVer версии рабочей нагрузки.

Технический стек

Платформенные зависимости

Примечание: В окружении ST Redpanda и OpenSearch развёрнуты. Компоненты Outbox Relay и Search Indexer в базовом развёртывании отключены, так как зависят от этих служб и включаются отдельным решением.

Зафиксированные версии

Основное обновление PostgreSQL на существующем постоянном томе требует отдельной проверки pg_upgrade. В одноразовой среде разработки том можно пересоздать после удаления выпуска Garden; данные промышленной среды так обрабатывать нельзя.

Среда развёртывания

Garden — единственный поддерживаемый инструмент сборки и развёртывания компонентов. Ручные helm upgrade, kubectl apply не образуют воспроизводимый путь поставки.

Образы платформы публикуются в корпоративный реестр артефактов nexus.inno.tech:19108, доступный из узлов кластера ai-dev.

Среды

В настоящее время Платформа ИИ развёрнута только в окружении ST.

ST использует одно пространство имён ap-st и один управляемый Keycloak. Все релизы агентов разворачиваются в этом же пространстве имён. Изменять чужое пространство имён и кластерные ресурсы запрещено.

Параметры окружения ST

Внешняя шлюзовая инфраструктура ST

TLS, DNS, шлюзы и сертификаты принадлежат DevOps. Развёртывание создаёт только HTTPRoutes в пространстве имён ap-st.

Наблюдаемые внешние родители (ListenerSets) в пространстве имён agentgateway-system, секция https:

• api-gw.ai-dev.inno.tech-listeners — API, Keycloak, low-code runtime;
• ide.ai-dev.inno.tech-listeners — Low-code Конструктор;
• docs.ai-dev.inno.tech-listeners — Team Docs.

Важно: наличие и условия внешних родителей нужно заново подтвердить перед каждым развёртыванием. Внешняя инфраструктура может измениться независимо от поставки.

Включённые и отключённые компоненты в st

Развертывание

Примечание: Инструкция приведена для кластера ai-dev (ST). Для других сред порядок аналогичен с учётом соответствующего профиля Garden.

Предварительные условия

• Kubernetes: кластер с контекстом ai-dev и доступом к записи в пространство имён ap-st.
• StorageClass longhorn существует в кластере.
• Docker доступен текущему пользователю (локальная сборка и кросс-сборка образов).
• Garden версии 0.14.20 установлен.
• Helm версии 3.x или новее.
• kubectl — для диагностики; curl и jq — для проверок; Python 3 — для вспомогательных скриптов.
• Файл kubeconfig для кластера ai-dev доступен по пути ~/.kube/ai-dev и содержит контекст ai-dev.
• Команды выполняются из корня репозитория agent-platform.

Важно: Команды Garden используют ${local.usernameLowerCase} для формирования пространства имён ap-dev-${local.usernameLowerCase}. Убедитесь, что вы работаете под своей учётной записью.

RBAC-проверки

Перед развёртыванием убедитесь, что учётная запись имеет необходимые права:

kubectl --kubeconfig ~/.kube/ai-dev --context ai-dev auth can-i create deployments -n ap-st
kubectl --kubeconfig ~/.kube/ai-dev --context ai-dev auth can-i create serviceaccounts -n ap-st
kubectl --kubeconfig ~/.kube/ai-dev --context ai-dev auth can-i create secrets -n ap-st
kubectl --kubeconfig ~/.kube/ai-dev --context ai-dev auth can-i create httproutes.gateway.networking.k8s.io -n ap-st
kubectl --kubeconfig ~/.kube/ai-dev --context ai-dev auth can-i patch httproutes.gateway.networking.k8s.io -n ap-st
kubectl --kubeconfig ~/.kube/ai-dev --context ai-dev auth can-i delete httproutes.gateway.networking.k8s.io -n ap-st
kubectl --kubeconfig ~/.kube/ai-dev --context ai-dev auth can-i create roles.rbac.authorization.k8s.io -n ap-st
kubectl --kubeconfig ~/.kube/ai-dev --context ai-dev auth can-i create rolebindings.rbac.authorization.k8s.io -n ap-st
kubectl --kubeconfig ~/.kube/ai-dev --context ai-dev \
  -n agentgateway-system get listenersets.gateway.networking.k8s.io

Проверка внешних родителей

Перед каждым развёртыванием подтвердите наличие, hostnames и условия внешних ListenerSets:

kubectl --kubeconfig ~/.kube/ai-dev --context ai-dev \
  -n agentgateway-system get listenerset \
  api-gw.ai-dev.inno.tech-listeners \
  ide.ai-dev.inno.tech-listeners \
  docs.ai-dev.inno.tech-listeners -o yaml

Остановитесь, если любой родитель отсутствует, не имеет условий Accepted=True и Programmed=True, не принимает маршруты из ap-st или обслуживает другой hostname.

Шаг 1. Проверка конфигурации

Из корня репозитория выполните валидацию:

garden validate --env st

Проверка должна завершиться до сборки образов. Если ошибка не исправлена, развёртывание будет прервано. Возможные причины ошибок:

• неверное пространство имён;
• занят один из фиксированных портов 18080–18083;
• отсутствует файл kubeconfig;
• недоступен реестр образов.

Шаг 2. Аутентификация в реестре образов

Garden автоматически выполняет действие run.image-registry-auth перед сборкой. Он:

1. Выполняет вход в реестр.
2. Создаёт или обновляет секрет ap-image-pull-secret в целевом пространстве имён для возможности загрузки образов.

Ручная аутентификация не требуется. Учётные данные реестра не выводятся в журналы.

Шаг 3. Развёртывание

Запустите развёртывание среды выполнения:

garden deploy all --env st --yes

Команда последовательно поднимает:

1. Образы приложений (сборка и публикация в реестре).
2. Общий поставщик идентичности (Keycloak) и базовые настройки realm.
3. Идентификацию Платформы ИИ (clients, роли, пользователи).
4. Идентификацию Low-code Конструктора.
5. Runtime Платформы ИИ, включая Control Plane, если он включён.
6. Low-code Runtime.
7. Low-code Конструктор.

Повторный запуск является штатным способом восстановления после частичного сбоя.

Примечание: Control Plane отключён по умолчанию (controlPlane.enabled=false). Для его активации необходимо явное включение в Helm-значениях; он активируется совместно с LLM Gateway. Подробности — в разделе «Control Plane».

Развёртывание тестовых данных

Тестовые агенты и пользователи создаются отдельными целями; обычный garden deploy тестовые данные не создаёт:

# Только Платформа ИИ с тестовыми данными
garden deploy agent-platform-fixtures --env st --yes

# Полное развёртывание тестового стенда (рекомендуется)
garden deploy all-fixtures --env st --yes

Цель all-fixtures выполняет все зависимости all и дополнительно согласует тестовых пользователей, тестовых агентов, разрешения Low-code Конструктора и явные разрешения agent#invoker для lowcode-linguist-v1 (субъекты workspace-admin и agent-invoker).

Шаг 4. Проверка развёртывания

Проверка подов

kubectl --kubeconfig ~/.kube/ai-dev --context ai-dev -n ap-st \
  get pods,deploy,statefulset,job,svc,pvc,httproute

Ожидаемые поды:

Проверка готовности компонентов

kubectl -n ap-st rollout status statefulset/ap-agent-registry-keycloak --timeout=10m
kubectl -n ap-st rollout status statefulset/ap-agent-registry-postgresql --timeout=10m
kubectl -n ap-st rollout status statefulset/ap-agent-registry-spicedb --timeout=10m
kubectl -n ap-st rollout status statefulset/ap-agent-registry-opensearch --timeout=10m
kubectl -n ap-st rollout status statefulset/ap-agent-registry-redpanda --timeout=10m
kubectl -n ap-st rollout status deployment/ap-agent-registry-api --timeout=10m
kubectl -n ap-st rollout status deployment/langflow-backend --timeout=10m
kubectl -n ap-st rollout status deployment/langflow-frontend --timeout=10m

Проверка маршрутов

kubectl -n ap-st \
  get httproute ap-agent-registry-api ap-agent-registry-keycloak \
  ap-agent-linguist ap-team-docs-web langflow-frontend -o yaml

У всех HTTPRoutes должны быть условия Accepted=True и ResolvedRefs=True; у каждого внешнего ListenerSet — Accepted=True и Programmed=True. Статус маршрута должен ссылаться на ожидаемого родителя: API/Keycloak/low-code — на api-gw...-listeners, Low-code Конструктор — на ide...-listeners, Team Docs — на docs...-listeners.

Проверка Swagger UI

1. Откройте браузером https://api-gw.ai-dev.inno.tech/agent-registry/docs.
2. Нажмите кнопку Authorize.
3. Выберите тип аутентификации oauth2Password.
4. Укажите имя пользователя workspace-admin и пароль workspace-admin.
5. Укажите client_id=agent-registry-dev, секрет клиента оставьте пустым.
6. Выполните запрос GET /api/v1/agents?workspaceId=ap-st.

Ожидаемый результат — как минимум два агента:

• st-smoke-v1 с типом реализации sdk;
• lowcode-linguist-v1 с типом реализации low-code.

Обнаружение агентов выполняется асинхронно. Первый пустой ответ допустимо повторить через несколько секунд.

Проверка Low-code Runtime

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

1. Неразрушающая проверка (/health/live) возвращает 200.
2. Проверка готовности (/health/ready) возвращает 200.
3. Карточка агента A2A содержит регистрационные метки.
4. Версия агента автоматически появляется в каталоге Agent Registry.

Примечание: Проверка вызова модели требует действительного ключа AI Gateway. Без ключа допустима только проверка обнаружения и связности.

Публичные проверки HTTP

curl -fsS https://api-gw.ai-dev.inno.tech/agent-registry/health/ready | jq
curl -fsS \
  https://api-gw.ai-dev.inno.tech/keycloak/realms/ap-dev/.well-known/openid-configuration |
  jq -e '.issuer == "https://api-gw.ai-dev.inno.tech/keycloak/realms/ap-dev"'
curl -fsS \
  https://api-gw.ai-dev.inno.tech/a2a/lowcode-linguist-v1/health/ready |
  jq -e '.status == "ready"'
curl -fsS \
  https://api-gw.ai-dev.inno.tech/a2a/lowcode-linguist-v1/.well-known/agent-card.json |
  jq -e '.supportedInterfaces[0].url == "https://api-gw.ai-dev.inno.tech/a2a/lowcode-linguist-v1"'
curl -fsS https://ide.ai-dev.inno.tech/config.js >/dev/null
curl -fsS https://docs.ai-dev.inno.tech/health/ready

Доступные адреса

Правила работы в среде

• Писать только в пространство имён ap-st.
• Запрещено изменять GatewayClass, Gateway, IngressClass, cluster-операторы и чужие пространства имён.
• Cluster-scoped RBAC выключен в Helm-значениях.
• Создание и ротация секретов требуют отдельного подтверждения человека.
• Garden system-метаданные направляются в целевое пространство имён, а не в общий garden-system.

Устранение неполадок

Поды не переходят в состояние Running

1. Проверьте статус подов:

   kubectl -n ap-st get pods --sort-by=.metadata.creationTimestamp

2. Просмотрите журналы проблемного пода:

   kubectl -n ap-st logs <pod-name> --tail=200

3. Проверьте события:

   kubectl -n ap-st get events --sort-by=.lastTimestamp

4. Наиболее частая причина — pods не готовы, а не сбой Helm. Повторите garden deploy после устранения причины.

Занятые порты

Garden использует фиксированные локальные порты 18080–18083. Если один из них занят, развёртывание завершается ошибкой до начала rollout. Освободите порт или завершите процесс, использующий его.

Ошибка аутентификации реестра

Если действие run.image-registry-auth завершается ошибкой:

1. Проверьте доступность nexus.
2. Убедитесь, что учётные данные реестра корректны.
3. Проверьте, что kubeconfig содержит контекст ai-dev.

Ошибка миграции базы данных

1. Остановите развёртывание.
2. Сохраните журнал миграции Alembic.
3. Восстановите совместимый образ приложения.
4. Убедитесь, что alembic check не выдаёт ошибок перед повторной попыткой.

Фикстуры пользователей

При развёртывании создаются ролеориентированные пользователи Keycloak:

Пароль каждого фикстурного пользователя совпадает с именем. Эти учётные записи создаются только в non-production средах и не переносятся в промышленную эксплуатацию.

Фикстуры агентов

По умолчанию создаются два тестовых агента:

Завершение работы

Для полного удаления развёртывания:

garden deploy --env st --uninstall

Или удалите пространство имён вручную:

kubectl delete namespace ap-st

Примечание: При удалении пространства имён все данные PostgreSQL, SpiceDB, OpenSearch и Redpanda будут безвозвратно удалены.

Откат

Процесс обновления и отката не является атомарным. Для регрессии конфигурации или образа:

1. возьмите предыдущий проверенный коммит композиции;
2. повторите тот же target — reconcilers и релизы Helm идемпотентны.

Откат по Git/Garden не откатывает автоматически миграции базы данных, изменения realm или содержимое PVC.

Деструктивная очистка

Порядок деструктивной очистки, если она явно разрешена:

фикстуры → приложения → идентификация приложения → realm-base → Keycloak/PVC

• Автоматических точек очистки тестовых данных нет;
• Удаление данных ST выполняется только версионированной миграцией с точным селектором владения и подтверждением человека;
• Не удаляйте ap-st, Keycloak PVC или тестовые данные как «откат».

Сводная таблица команд

Материалы для фиксации результата

При развёртывании сохраните:

• точную команду, среду и время выполнения;
• версии Garden, Docker и Kubernetes;
• пространство имён и версии действий Garden;
• идентификаторы собранных образов;
• результаты миграций базы данных;
• проверки работоспособности подов;
• результаты тестирования API;
• ограничения среды (отключённые компоненты, внутрикластерные DNS).

Не сохраняйте в журнале учётные данные, токены и пользовательские запросы.

Развертывание SDK агента

Как работает регистрация

В Agent Registry нет отдельной операции создания агента. Регистрация выполняется автоматически после развёртывания рабочей нагрузки и k8s сущности Service с регистрационными метками в доверенном пространстве имён Kubernetes.

Agent Registry:

1. обнаруживает Service;
2. проверяет метки, аннотации и привязку пространства имён к рабочему пространству;
3. дожидается готового адреса из принадлежащей службе EndpointSlice;
4. загружает карточку агента по внутреннему адресу службы;
5. проверяет A2A 1.0, имя, версию, навыки и заявленные возможности;
6. добавляет разрешённую проекцию агента в каталог.

Объектом регистрации является Service, а не Deployment или отдельный Pod. Перезапуск экземпляра не создаёт новую запись, пока служба и логическая версия агента остаются прежними.

Что подготовить заранее

До развёртывания запросите у владельца среды:

• точное пространство имён, включённое в состав доверенных в Agent Registry;
• идентификатор рабочего пространства для регистрационной метки;
• идентификатор команды из доверенного каталога владельцев;
• разрешённый способ доставки через Garden и Helm;
• требования среды к внутреннему TLS и публичному маршруту;
• права на просмотр и, при необходимости, вызов зарегистрированного агента.

Имя агента имеет форму <domain>-<function>-v<major> и должно быть допустимым DNS именем длиной не более 63 символов. Суффикс имени должен совпадать с основной частью SemVer: версии 1.0.0 соответствует суффикс -v1.

Подготовка карточки агента

Агент должен возвращать карточку по адресу /.well-known/agent-card.json, если в аннотации службы не указан другой безопасный абсолютный путь.

Минимальный пример для A2A 1.0 HTTP+JSON:

{
  "name": "finance-invoice-v1",
  "description": "Проверяет счет и извлекает структурированные поля.",
  "supportedInterfaces": [
    {
      "url": "https://agent.example/a2a/finance-invoice-v1",
      "protocolBinding": "HTTP+JSON",
      "protocolVersion": "1.0"
    }
  ],
  "version": "1.2.0",
  "capabilities": {
    "streaming": true,
    "pushNotifications": false,
    "extendedAgentCard": false
  },
  "defaultInputModes": ["application/json", "text/plain"],
  "defaultOutputModes": ["application/json"],
  "skills": [
    {
      "id": "invoice_parsing",
      "name": "Разбор счета",
      "description": "Извлекает нормализованные поля из счета.",
      "tags": ["invoice", "finance"],
      "examples": ["Извлеки поставщика, сумму и НДС из этого счета"]
    }
  ]
}

Значения name и version должны точно совпадать с метками службы. В поставке 2026.3.5 для HTTP+JSON подтверждена возможность streaming. Не объявляйте неподдерживаемую возможность: Agent Registry не запускает агент для пробного вызова во время регистрации и полагается на правдивую неизменяемую карточку и проверку совместимости до развёртывания.

Публикация Service

Рабочая нагрузка должна иметь именованный порт и проверку готовности. Рядом с ней опубликуйте службу с селектором:

apiVersion: v1
kind: Service
metadata:
  name: finance-invoice-v1
  namespace: finance
  labels:
    agent-platform.inno.tech/registrable: "true"
    agent-platform.inno.tech/protocol: a2a
    agent-platform.inno.tech/workspace: finance
    agent-platform.inno.tech/agent-name: finance-invoice-v1
    agent-platform.inno.tech/version: "1.2.0"
    agent-platform.inno.tech/owner: team-finance-ai
    agent-platform.inno.tech/implementation-type: sdk
  annotations:
    agent-platform.inno.tech/registration-contract: agent-platform.agent-registry.registration/v1
    agent-platform.inno.tech/card-path: /.well-known/agent-card.json
    agent-platform.inno.tech/service-port: a2a
spec:
  type: ClusterIP
  selector:
    app.kubernetes.io/name: finance-invoice-v1
  ports:
    - name: a2a
      protocol: TCP
      port: 8443
      targetPort: a2a

Обязательные значения:

Поддерживается служба ClusterIP с селектором. Не используйте ExternalName, службу без селектора, созданный вручную EndpointSlice или publishNotReadyAddresses: true.

Проверка регистрации

Сначала проверьте готовность рабочей нагрузки и принадлежность адреса службе:

kubectl --namespace finance get service/finance-invoice-v1 --output=wide
kubectl --namespace finance get endpointslice \
  --selector kubernetes.io/service-name=finance-invoice-v1 \
  --output=wide

Для диагностики в непроизводственной среде получите у владельца среды разрешённый тестовый адрес и проверьте карточку:

curl --fail --silent --show-error \
  "${AGENT_TEST_URL}/.well-known/agent-card.json" \
| jq '{name, version, supportedInterfaces, capabilities, skills}'

Схему внутреннего соединения и доверенный сертификат выбирает среда. Не отключайте проверку TLS ради диагностики.

После асинхронного обнаружения запросите каталог с пользовательским токеном:

curl --fail --silent --show-error \
  "${REGISTRY_URL}/api/v1/agents?workspaceId=finance&protocol=a2a&implementationType=sdk&limit=20" \
  --header "Authorization: Bearer [REDACTED]" \
| jq '.items[] | select(.name == "finance-invoice-v1") | {
    id,
    name,
    implementationType,
    lifecycleStatus,
    selectedVersion
  }'

Успешная запись имеет состояние active, тип реализации sdk и выбранную версию, совпадающую с карточкой. Отсутствие публичного интерфейса при этом означает, что доверенный маршрут ещё не готов; это не ошибка регистрации.

Проверка потоковой передачи A2A

Если карточка содержит streaming: true, до публикации версии проверьте фактический HTTP+JSON SSE-путь. Для контролируемой непроизводственной среды:

message_id="$(python3 -c 'import uuid; print(uuid.uuid4())')"

curl --no-buffer --fail-with-body --show-error \
  --request POST "${AGENT_TEST_URL}/message:stream" \
  --header 'A2A-Version: 1.0' \
  --header 'Accept: text/event-stream' \
  --header 'Content-Type: application/a2a+json' \
  --data-binary @- <<JSON
{
  "message": {
    "messageId": "${message_id}",
    "role": "ROLE_USER",
    "parts": [
      {
        "text": "Проверь тестовый документ",
        "mediaType": "text/plain"
      }
    ]
  }
}
JSON

Поток должен начинаться отправленной задачей, содержать рабочее состояние и последовательные обновления результата, а завершаться терминальным состоянием. Разрыв соединения, повторная подписка и получение завершенной задачи должны соответствовать A2A 1.0. Agent Registry сохраняет возможность потоковой передачи в каталоге, но не выполняет этот тест вместо разработчика.

Разбор ошибки регистрации

Важно: При обращении в поддержку передавайте имя агента, версию, пространство имён, время развёртывания и безопасный traceId. Не передавайте токен, секрет модели, внутренние учётные данные и полный закрытый запрос.

Обновление зарегистрированного агента

Карточка и возможности опубликованной версии неизменяемы. При изменении поведения, навыков, входных данных или возможностей:

1. назначьте новую SemVer;
2. согласованно обновите карточку, образ и метку версии службы;
3. повторите проверки A2A и готовности;
4. дождитесь появления новой выбранной версии в Agent Registry;
5. сохраняйте предыдущую версию как явную точку отката на принятый срок.

При переходе с 1.x на 2.x измените суффикс логического имени с -v1 на -v2. Не меняйте содержимое уже опубликованной версии без изменения SemVer.

Граница безопасности

• Не помещайте ключи, токены и внутренние адреса в метки или описание карточки.
• Не публикуйте сырой адрес Service как пользовательский интерфейс.
• Не считайте регистрацию разрешением на просмотр или вызов.
• Не передавайте исходный пользовательский токен непосредственно SDK-агенту.
• В производственной среде вызывайте агент только через интерфейс Platform Agent Gateway, возвращенный Agent Registry после проверки прав.

Обновление и откат

Поддерживаемая граница

Для версии 2026.3.5 подтверждается установка в непромышленных средах. Порядок промышленного обновления не считается принятым до появления всех неизменяемых артефактов, проверки внешних зависимостей и испытанного отката.

Обновление рассматривается как согласованное изменение трёх компонентов, даже если они поставляются разными проектами. Нельзя обновлять Low-code IDE, Low-code Runtime без проверки уже сохраненных и пригодных для отката Flow.

Подготовка

Зафиксируйте текущее и целевое состояние:

Проверьте резервное копирование и фактическую возможность восстановления PostgreSQL Agent Registry и базы Low-code IDE. Для OpenSearch достаточно пересоздания из метаданных.

Проверка совместимости Flow Low-code

Для каждого активного и пригодного для отката Flow:

1. экспортируйте исходные данные прежней версией Low-code IDE;
2. проверьте их целевым проверяющим модулем и политикой;
3. загрузите и выполните путь целевой версией Low-code Runtime;
4. сравните входы, выходы, карточку A2A, описание MCP и контрольные примеры;
5. зафиксируйте необходимость миграции либо заблокируйте обновление;
6. не изменяйте сохранённый источник автоматически при запуске.

Если PlatformRAG или PlatformMemory появляются в новой политике, это отдельное изменение возможностей с собственными контрактами и не может включаться только обновлением версии.

Проверка Agent Registry

До обновления:

1. выполните сравнение OpenAPI и машинных схем;
2. проверьте применение и понижение версии Alembic на одноразовой базе;
3. подтвердите совместимость схемы SpiceDB и читателей/писателей;
4. проверьте повторную доставку Redpanda и пересоздание OpenSearch;
5. выполните разрешённые, запрещённые, межпространственные запросы и отказ SpiceDB;
6. проверьте регистрацию службы Low-code Runtime целевой формы.

Порядок обновления

1. Остановите развёртывание новых версий Flow пользователями.
2. Создайте резервные копии метаданных и зафиксируйте текущее состояние.
3. Выполните все проверки совместимости Flow Low-code.
4. Обновите репозиторий до новой версии поставки.
5. Запустите garden validate --env TARGET.
6. Запустите garden deploy --env TARGET --yes для компонентов этого репозитория.
7. Дождитесь миграции PostgreSQL, схемы SpiceDB, топиков Redpanda и поисковой схемы.
8. Дождитесь готовности всех процессов Agent Registry, Low-code IDE и проверочного Low-code Runtime.
9. Выполните вход, создание, сохранение, проверку и повторяемый экспорт.
10. Воспроизведите общий путь от создания Flow агента до автоматического обнаружения и вызова.
11. Разрешите создание новых рабочих версий Flow только после успешной проверки.

Условия немедленной остановки

Остановите обновление, если:

• миграция данных завершилась ошибкой;
• прежний Flow Low-code не проходит целевую проверку;
• карточка или описание агента объявляет отсутствующую возможность;
• Low-code IDE может передать непроверенный или содержащий секрет источник;
• Agent Registry возвращает недоступный объект;
• новый экземпляр Reconciler не получил свежее полное наблюдение;
• поисковая проекция не сходится с метаданными.

Критерии завершения

Обновление завершено только когда:

• образы, настройки, схемы данных и внешние зависимости совместимы;
• активные и откатные Flow Low-code прошли проверку;
• Low-code IDE создаёт повторяемый Flow;
• Low-code Runtime готов и исполняет принятый профиль;
• Agent Registry автоматически обнаруживает его и соблюдает отрицательные проверки доступа;
• сохранены контрольные суммы и очищенные результаты проверки;
• подтверждён применимый путь отката.

Откат

Принцип: Откат возвращает всю систему к заранее проверенной комбинации образов, настроек, схем данных, артефактов агента и внешних зависимостей. Возврат одного образа без проверки совместимости данных и Flow Low-code не считается безопасным.

Исходный файл Flow не исправляется во время отката. Выбирается предыдущая версия с известной контрольной суммой и подтверждённой совместимостью.

Ограничение текущего релиза: Ввиду того, что текущий релиз является первым, процедура отката к предыдущей версии не предусмотрена.

Мониторинг состояния и обслуживание

Ежедневная проверка состояния

Agent Registry

Проверьте:

1. работоспособность и готовность API;
2. актуальность данных мониторинга Service и EndpointSlice в Kubernetes;
3. лидера сервиса Kubernetes Reconciler;
4. возраст самой старой неопубликованной записи транзакционной очереди;
5. отставание обработчика Redpanda;
6. состояние SpiceDB и OpenSearch;
7. завершение задания хранения и удаления устаревших данных.

Low-code Runtime

Для каждой поставленной версии проверьте:

1. идентификатор образа;
2. SHA-256 исходного Flow и манифеста;
3. ответ эндпоинта проверки работоспособности процесса;
4. ответ эндпоинта проверки готовности Flow;
5. соответствие карточки A2A и описания MCP фактическим возможностям агента;
6. отсутствие перезапусков, таймаутов и ошибок AI Gateway;
7. отсутствие секретов и содержимого запросов в журналах.

Low-code IDE

Проверьте:

1. идентификаторы клиентского и серверного образов;
2. доступность входа через платформенный SSO;
3. запрет доступа для пользователя без нужной роли;
4. согласованную версию клиентской и серверной частей;
5. доступность хранилища рабочих версий;
6. версию политики компонентов и проверяющего модуля;
7. отсутствие внешних поставщиков и открытых секретов в экспортируемой схеме;
8. доступность Control Plane и api-gw, через которые выполняется публикация агентов.

Значение проверок состояния

• Проверка работоспособности сообщает только о живом процессе. Она не должна выполнять дорогой вызов модели.
• Готовность Agent Registry требует исправной БД с метаданными, настройки удостоверений и функционирующего процесса мониторинга развёрнутых в Kubernetes агентов.
• Готовность Low-code Runtime требует успешно загруженной Flow, манифеста, рабочего эндпоинта, карточки и критической конфигурации.
• Доступность клиентской части Low-code IDE не доказывает готовность серверной проверки, хранилища и входа.
• Отказ SpiceDB запрещает защищённые операции. Отказ AI Gateway или OpenSearch отключает поиск, но не обязан останавливать просмотр списка.

Безопасный сбор сведений

После явного выбора контекста и пространства имён допустимы команды чтения:

kubectl -n "$REGISTRY_NAMESPACE" get deploy,pod,svc,endpointslice,job,lease
kubectl -n "$REGISTRY_NAMESPACE" get events --sort-by=.lastTimestamp
kubectl -n "$REGISTRY_NAMESPACE" logs \
  deploy/ap-agent-registry-kubernetes-reconciler --all-pods --tail=200
kubectl -n "$REGISTRY_NAMESPACE" logs \
  deploy/ap-agent-registry-api --all-pods --tail=200

Важно: Не помещайте значение токена, текст карточки, запрос поиска, вектор и внутренний адрес в запрос.

Диагностика Agent Registry

Устаревшие данные мониторинга Kubernetes

Признак: алерт AgentRegistryObservationCoverageStale, потеря готовности Reconciler или исчезновение доступных интерфейсов.

1. Проверьте возраст покрытия, ошибки данных мониторинга, ответы 410, ограничение запросов Kubernetes и лидера сервисов Reconciler.

2. Убедитесь, что потоки Service и EndpointSlice свежие для каждого явно сопоставленного пространства имён.
3. Проверьте только права get/list/watch через RoleBinding. Чтение Secret, Pod, Deployment и всего кластера не требуется.
4. При 410 Gone дождитесь полного повторного списка.
5. При перезапуске лидера сервисов Reconciler новый владелец должен сначала выполнить полную синхронизацию и только потом считать покрытие свежим.

Потеря готовности агента

Проверьте все EndpointSlice, принадлежащие сервису агента: управляющий контроллер, тип адреса, порт и признаки ready, serving, terminating.

При отсутствии доступного EndpointSlice:

• агент не доступен из обычной выдачи для вызова;
• удаляется публичный интерфейс;
• инициируется отзыв разрешений доступа (SpiceDB) и поисковой проекции.

Восстанавливайте исходный агентский сервис или Low-code Runtime. Пересозданный сервис получает новый UID и проходит полную проверку.

Ошибка разрешений SpiceDB

Признак: AgentRegistryPermissionCleanupFailing или ответы authorization_unavailable.

1. Считайте затронутый агент недоступным до завершения восстановления.
2. Проверьте состояние SpiceDB и код ошибки авторизационного запроса.
3. После восстановления дождитесь повторной операции Reconciler.
4. Убедитесь, что разрешения владельца и рабочей области удалены либо созданы в соответствии с текущим состоянием.

Откат БД SpiceDB не приведёт к восстановлению.

Отказ поиска

• При отказе AI Gateway поиск возвращает 503.
• При отказе OpenSearch поиск возвращает 503.
• Просмотр списка и одной записи продолжается, если PostgreSQL и SpiceDB исправны.
• После восстановления создайте новое поколение индекса.
• Переключайте псевдоним только после проверки количества, контрольного набора и догонки потока событий.
• Храните прежнее поколение не менее семи дней для быстрого возврата.

Не редактируйте отдельные документы OpenSearch вручную.

Задержка транзакционной очереди

Признак: AgentRegistryOutboxPublishFailing или рост возраста самой старой неопубликованной записи.

1. Проверьте Redpanda, права на топик, срок хранения и владельца блокировки.
2. Не меняйте published_at вручную.
3. После истечения периода блокировки запись должна стать доступной повторной попытки.
4. Повторная доставка допустима: Search Indexer устраняет повторы по идентификатору события и версии агрегата.
5. После восстановления убедитесь, что очередь сокращается, а группа потребителя продвигается.

Миграции и восстановление

Задание миграции и проверка при запуске используют транзакционную блокировку PostgreSQL. При ошибке:

1. остановите развёртывание версии;
2. сохраните номер Alembic и ошибку базы;
3. верните совместимый образ приложения;
4. выполняйте понижение версии схемы только после проверки сохранности данных;
5. не запускайте разрушительный SQL из интерактивного контейнера.

Цели восстановления: Agent Registry — RTO 60 минут и RPO 5 минут; SpiceDB — RTO 30 минут и RPO 5 минут.

OpenSearch восстанавливается из метаданных и не имеет внутреннего механизма, гарантирующего сохранность.

Диагностика Low-code Runtime

Проверки состояния

Проверка готовности не должна выполнять тяжёлый запрос к модели. Фактическая готовность AI Gateway подтверждается отдельной сквозной проверкой.

Типичные причины неготовности

Наблюдаемость

Для диагностики достаточно идентификатора агента и версии, версии Flow, хеш-префикса, traceId, кода ошибки.

Условие успешной эксплуатации

Версия считается исправной, когда готовность агента устойчива, карточка соответствует поведению, A2A и MCP проходят согласованный набор проверок, неверные FileRef и права отклоняются до выполнения, а Agent Registry автоматически обнаруживает рабочую нагрузку развёрнутого агента.

Диагностика Low-code IDE

Предварительные проверки

Перед открытием доступа пользователям зафиксируйте:

1. идентификаторы клиентского и серверного образов;
2. полный SBOM обоих образов и отчёт чистой сборки;
3. версию LangFlow, версию адаптации и совместимую версию схемы данных;
4. версию политики компонентов;
5. версию проверяющего модуля и JSON Schema Flow и манифеста;
6. адрес и конфигурацию платформенного поставщика токенов доступа;
7. карту ролей Low-code IDE к рабочим областям;
8. доступность базы рабочих версий;
9. доступность Control Plane и api-gw, через которые выполняется публикация агентов.

Вход и доступ

Проверьте четыре состояния:

Идентификатор пользователя, рабочая область и роли из формы, URL или неподписанного заголовка не являются источником полномочий.

Политика компонентов

Запрет должен действовать на двух уровнях:

1. клиентская палитра не показывает недоступный компонент;
2. серверная проверка отклоняет вручную добавленный или изменённый JSON.

| Platform RAG | Платформенный сервис retrieval-augmented generation: реестр коллекций, приём нормализованных документов, гибридный поиск с фильтрацией по правам доступа |

После изменения политики повторно проверьте все активные и пригодные для отката версии Flow. Нельзя автоматически изменять уже зафиксированные исходные данные.

Сохранение

Серверная часть должна:

• сохранять рабочую версию в правильной рабочей области;
• предотвращать перезапись зафиксированной версии;
• формировать устойчивую SHA-256;
• возвращать версию проверяющего модуля и политики;
• отделять предупреждение от блокирующей ошибки;
• не включать секрет в исходные данные и сообщение об ошибке.

Повторный экспорт одной неизменённой версии должен давать те же байты и контрольную сумму.

Первичная диагностика

Клиент открывается, но данные не загружаются. Проверьте совместимость клиентской и серверной версий, состояние API, срок сеанса и права рабочей области.

Сохранение не работает. Проверьте доступность базы, миграцию, ограничение размера и конфликт версии. Сохраните рабочую копию пользователя безопасным способом; не записывайте JSON в произвольную таблицу вручную.

Публикация недоступна. Сохраните проверенную версию и контрольные суммы. Не выполняйте прямую загрузку артефакта. Проверьте доступность Control Plane и api-gw, срок токена доступа и права рабочей области; при повторном сбое передайте идентификатор операции публикации администратору Платформы ИИ.

Первичная диагностика происшествия

1. Зафиксируйте среду, контекст, пространство имён, версию выпуска и время.
2. Определите затронутый пользовательский шаг: вход, редактирование, проверка, запуск среды исполнения, обнаружение, поиск или вызов.
3. Зафиксируйте идентификаторы образов, версии схемы и манифеста без их чувствительного содержимого.
4. Проверьте компонент-владелец, затем его непосредственные зависимости.
5. Сохраните события, показатели и очищенные журналы с traceId.
6. Убедитесь, что отказ доступа, устаревшие данные мониторинга или неверный маршрут не обходятся временной настройкой.
7. Остановите развёртывание версии, если нарушены граница доступа, контрольная сумма, регистрационный контракт или соответствие заявленных возможностей.
8. Откатывайте только заранее проверенную совместимую комбинацию образов, конфигурации, схем данных и внешних зависимостей.

Данные, которые нельзя сохранять

Не включайте в журналы, трассировки и материалы проверки:

• исходный пользовательский токен и короткоживущие полномочия;
• ключи, пароли и значения Vault;
• текст пользовательского запроса и ответа модели;
• содержимое файлов и подписанный FileRef;
• полный экспорт схемы, если в нём могут быть закрытые данные;
• вектор запроса и закрытые внутренние адреса;
• карточки и описания протокола без очистки чувствительных полей.

Для связи событий используйте безопасные идентификаторы агента, версии, Flow, хеш-префикс, traceId и время.

Безопасное восстановление

• Исправляйте исходную рабочую нагрузку или конфигурацию и дожидайтесь согласования состояния.
• После ответа Kubernetes 410 Gone разрешите Reconciler выполнить полную повторную синхронизацию.
• Не помечайте запись транзакционной очереди опубликованной вручную.
• Повреждённый поисковый индекс заменяйте новым поколением и переключайте псевдоним только после проверки количества и контрольного набора.
• При несовпадении артефакта Low-code Runtime создавайте новую версию; не исправляйте файл внутри контейнера.
• При ошибке Low-code IDE сохраняйте рабочую версию и результат проверки; не передавайте непроверенный JSON оператору.
• При ошибке миграции остановите развёртывание и следуйте плану миграции.

Control Plane

Control Plane — центральный управляющий компонент Платформы ИИ. Он предоставляет управление политиками моделей, виртуальными ключами LLM и публикацией low-code агентов. Компонент владеет желаемым состоянием и длительными операциями, но не участвует в путях инференса LLM и вызова агентов (A2A): каталог агентов и их вызов — это Agent Registry и Platform Agent Gateway.

Control Plane отключён по умолчанию (controlPlane.enabled=false) и активируется отдельным решением вместе с LLM Gateway. Platform API Gateway (api-gw) монтирует компонент по пути /control-plane: публичное API — /control-plane/api/v1, документация — /control-plane/docs.

Важно: Все изменяющие состояние операции асинхронные. Запрос возвращает 202 Accepted со ссылкой на Operation — это подтверждение принятия намерения, а не факта выполнения. Фактическое применение отслеживается через поле verifiedState ресурса и GET /api/v1/operations/{operationId}.

Назначение и состав

Control Plane состоит из прикладного API, фоновых воркеров оркестрации и транзакционной базы данных. Управление внешними ресурсами (Kubernetes, LLM Gateway, Agent Registry) выполняется асинхронно через фоновые согласующие воркеры.

Права доступа

Проверка выполняется прямо на целевом ресурсе. Недоступность или неопределённый результат SpiceDB приводит к отказу (fail-closed), а не к частичному доступу.

Управление моделями

Управление моделями строится на трёх связанных сущностях: Tier (профиль скорости и квот), Provider (внешний LLM-провайдер) и Model (конкретная модель, привязанная к провайдеру). Все операции, изменяющие состояние, возвращают 202 Accepted. Чтение ресурса возвращает заголовок ETag вида "r<revision>", который обязателен в If-Match для PATCH и DELETE.

Tier (Уровень)

Профиль обслуживания ключа: лимит запросов в минуту и квота токенов в минуту. Tier не имеет членов, владельцев или унаследованных прав.

Удаление выполняется только для неиспользуемого уровня; при наличии зависимостей возвращается 409 Conflict. Рекомендуемые примеры: standard (100 запросов/мин, 50K токенов/мин) и premium (500 запросов/мин, 200K токенов/мин).

Provider (Поставщик)

Конфигурация внешнего LLM-провайдера. Создание выполняется в отключённом состоянии: POST /api/v1/providers принимает name, kind (единственное значение openai_compatible), endpoint (только https://) и desiredState: "disabled".

Учётные данные задаются отдельным ресурсом PUT /api/v1/providers/{providerId}/credential. Значение поля credential (16–8192 символов) не возвращается API. Провайдер можно включить только после проверки учётных данных. Удаление возможно, только когда на провайдера не ссылаются модели. Учётные данные провайдера удалить нельзя — их можно только установить или заменить.

Model (Модель)

Конкретная модель с именем для шлюза, привязкой к провайдеру и профилем. Наличие модели не создаёт права доступа — доступ выдаётся только явными привязками моделей к ключам.

В PATCH входят только upstreamModel, profile и desiredState: сменить gatewayName или провайдера нельзя — можно только сменить модель, на которую указывает upstreamModel. Удаление возможно, только когда модель не требуется активными ключами или маршрутами, иначе 409 Conflict. Массовая смена состояния — через пакетные операции set_model_state.

Управление ключами

Ключи доступа к моделям управляются двумя сущностями: KeyIssuancePolicy (политика выдачи) и ApiKey (виртуальный ключ). Все операции, изменяющие состояние, асинхронные и возвращают 202 Accepted; фактическое применение отслеживается через verifiedState ресурса и статус операции.

KeyIssuancePolicy (Политика выдачи ключей)

Настройка самообслуживающейся выдачи ключей людям и сервисам. Это синглтон — единичный объект на всю установку. Изменение политики влияет только на будущие выдачи и не изменяет ранее выданные ключи.

Управление через GET /api/v1/key-issuance-policy (получение) и PATCH /api/v1/key-issuance-policy (обновление). При enabled=true требуются не менее одного уровня и одной модели, иначе обновление отклоняется.

ApiKey (Ключ API)

Виртуальный ключ доступа к моделям: один владелец (человек, сервис или агент), один уровень и непустой набор разрешённых моделей.

Особенности жизненного цикла:

• секретный материал ключа (oneTimeSecret, формат cpk_<base64url>) возвращается только один раз при создании или ротации; повторный запрос по тому же Idempotency-Key возвращает лишь метаданные;
• ключи с владельцем-агентом (owner.type = "agent") не управляются через административные методы — их жизненный цикл принадлежит публикации агента; попытка завершается 409 Conflict;
• при отзыве ключ верифицируется через LLM Gateway; если Gateway не отвечает в пределах таймаута, возвращается 504 VerificationTimeout.

Типовые сценарии администратора

Настройка провайдера и моделей. Администратор последовательно создаёт Provider (адаптер, HTTPS-адрес, зашифрованные учётные данные), Tier (имя, лимиты requestsPerMinute/tokensPerMinute, состояние enabled) и Model (уникальное gatewayName, привязка к провайдеру, профиль). Для дополнительных уровней и моделей шаги повторяются; каждая модель привязывается к одному провайдеру. После этого платформа готова обслуживать подключённых поставщиков.

Настройка политики выдачи ключей. Администратор обновляет синглтон PATCH /api/v1/key-issuance-policy: включает выдачу (enabled: true), выбирает разрешённые уровни и модели, задаёт лимит активных ключей на субъекта. После сохранения пользователи и сервисы самостоятельно выпускают ключи через POST /api/v1/me/keys в рамках заданных ограничений.

Выдача ключа администратором. По запросу субъекта администратор создаёт ключ через POST /api/v1/keys, указав владельца, уровень и разрешённые модели, затем передаёт секретный материал субъекту по защищённому каналу. Полный аудит-трейл выдачи доступен администратору.

Управление ключами. Администратор может:

Публикация low-code агента. В этом релизе low-code агент публикуется прямо из интерфейса Low-code Конструктора: пользователь инициирует публикацию проверенной версии Потока (Flow) в самом Конструкторе, без обращения к Control Plane напрямую. Провайдер agent-platform экспортирует версию Потока в канонический формат и вызывает Control Plane через api-gw от имени пользователя.

Признаки успешной публикации: 202 Accepted означает принятую операцию, а не завершение; конечная готовность — publicationState = active в статусе публикации и статус операции succeeded в GET /api/v1/operations/{operationId}. Ограничения: изменяемые Flow.data не публикуются; неизвестный или изменённый вручную компонент отклоняется; прямая загрузка схемы в OCI, Kubernetes или Agent Registry запрещена.

Настройка политики публикации. Администратор задаёт синглтон PATCH /api/v1/agent-publication-policy — допустимый уровень и набор моделей для новых версий агентов. Версия замораживает разрешённые модели, уровень и ревизию политики; изменения политики не действуют задним числом.

Platform RAG — платформенный сервис уровня COMMON, предоставляющий управляемое извлечение знаний (retrieval-augmented generation): реестр коллекций, приём нормализованных документов, гибридный поиск с обязательной фильтрацией по правам доступа и выдачу фрагментов с цитатами.

Архитектура

Сервис состоит из двух прикладных нагрузок без локального состояния: API и воркер ingest. Всё состояние хранится во внешних сервисах данных. Модели вызываются только через AI Gateway. Авторизация коллекций — SpiceDB; видимость чанков — ACL документа, выведенный из act-цепочки вызывающего.

Helm-чарт helm/platform-rag создаёт Deployment *-api, Deployment *-worker, Service (ClusterIP, порт 8090), ConfigMap, ServiceAccount и опционально Ingress и KEDA ScaledObject. Зависимости чартом не устанавливаются.

Потоки данных

Приём документа. Клиент вызывает POST /v1/documents:submit. API проверяет право записи в коллекцию, регистрирует задание в PostgreSQL (PENDING), сохраняет канонический JSON в S3 и публикует уведомление в RabbitMQ. Воркер захватывает задание (RUNNING), выполняет чанкинг, эмбеддинг через AI Gateway и bulk-индексацию в OpenSearch, затем переводит задание в DONE или FAILED. Повторная отправка с тем же (tenant, collection, doc_id, content_hash, idempotency_key) возвращает DEDUPLICATED.

Поиск. Клиент вызывает POST /v1/query. API авторизует доступ к коллекции (SEC prior), строит эмбеддинг запроса через AI Gateway, выполняет гибридный поиск (kNN + BM25) со слиянием RRF, обязательно фильтрует выдачу по tenant_id и ACL вызывающего (SEC posterior) и возвращает цитаты (doc_id, chunk_id, фрагмент, оценка).

Идемпотентность и надёжность очереди. Источник истины — PostgreSQL. RabbitMQ доставляет уведомление; при потере сообщения фоновая сверка выбирает зависшие PENDING и публикует повторно. Воркеры идемпотентны.

Минимальные ресурсы

Запросы чарта по умолчанию: API — 100m CPU / 256Mi RAM (лимит 1Gi); worker — 250m CPU / 512Mi RAM (лимит 2Gi).

Развёртывание

Предварительные требования

• Linux x86-64; Docker Engine и Docker Compose v2 или кластер Kubernetes с Helm 3.
• Доступ к реестру образов либо возможность собрать образ из исходного кода.
• Для полного цикла ingest/query: доступные PostgreSQL 16, RabbitMQ 3, OpenSearch 2.x, объектное хранилище S3-совместимое, AI Gateway, SpiceDB.

Проверка Docker:

docker --version
docker compose version

Проверка Kubernetes / Helm:

kubectl version --client
helm version

Получение дистрибутива

Исходный код и чарт поставляются репозиторием сервиса. Сборка образа:

docker build -t platform-rag:<tag> .

В контуре заказчика используется согласованный реестр. После сборки образ публикуется в реестр, доступный узлам кластера.

Настройка конфигурации

Образец — config/config_template.yaml. Рабочий файл — config/config.yaml (путь задаётся RAG_CONFIG). Секреты (DSN, пароли, ключи) не хранятся в Git.

Обязательные группы параметров до запуска:

Переопределение из окружения (примеры):

export RAG_CONFIG=/app/config/config.yaml
export RAG__POSTGRES__DSN='postgresql+asyncpg://[REDACTED]@postgres:5432/platform_rag'
export RAG__RABBITMQ__PASSWORD='[REDACTED]'
export RAG__S3__ACCESS_KEY_ID='<key>'
export RAG__S3__SECRET_ACCESS_KEY='<secret>'
export RAG__OPENSEARCH__USERNAME='<user>'
export RAG__OPENSEARCH__PASSWORD='[REDACTED]'
export RAG__AI_GATEWAY__API_KEY='[REDACTED]'
export RAG__SPICEDB__ENABLED=true
export RAG__AUTH__ENABLED=true

При app.create_schema_on_startup: true API при старте создаёт схему PostgreSQL. Для промышленного контура порядок миграций согласовывается отдельно; откат Helm не откатывает схему БД.

Внимание. Профиль эмбеддинга (model + dimension) закрепляется за коллекцией. Смена профиля без версионируемой переиндексации сделает векторный поиск несовместимым.

Развёртывание в Docker Compose

Файл docker-compose.yml поднимает прикладные сервисы и зависимости: PostgreSQL, RabbitMQ, OpenSearch, SpiceDB (с отдельной БД и миграцией схемы). MinIO и AI Gateway в Compose не входят: для пилота без объектного хранилища используется s3.dry_run: true.

Публикуемые порты Compose:

Вариант A. Инфраструктура в Docker, приложение на хосте:

docker compose up -d postgres rabbitmq opensearch spicedb-postgres
docker compose up spicedb-migrate
docker compose up -d spicedb

# из корня репозитория, Python 3.11+
pip install -e .
export RAG_CONFIG=config/config.yaml
platform-rag-api
# во втором терминале:
platform-rag-worker

Проверка:

curl -fsS http://127.0.0.1:8090/health

Ожидается "status": "ok" по компонентам postgres, rabbitmq, s3, opensearch. При s3.dry_run: true проверка S3 считается успешной без реального бакета.

Вариант B. Полный стек в Compose:

docker compose up -d --build
docker compose ps
docker compose logs -f api worker
curl -fsS http://127.0.0.1:8095/health

Остановка:

docker compose down
# с удалением томов данных:
docker compose down -v

Развёртывание в Kubernetes (Helm)

Чарт: helm/platform-rag. Канонические команды также приведены в helm/platform-rag/README.md и docs/helm-deployment.md.

Подготовка

1. Собрать и опубликовать образ.
2. Проверить сетевую доступность PostgreSQL, RabbitMQ, S3, OpenSearch, AI Gateway и SpiceDB из целевого пространства имён.
3. Создать Secret с учётными данными (не помещать их в values):

kubectl -n <namespace> create secret generic platform-rag-secrets \
  --from-literal=postgres-dsn='postgresql+asyncpg://[REDACTED]@host:5432/platform_rag' \
  --from-literal=postgres-dsn-sync='postgresql://[REDACTED]@host:5432/platform_rag' \
  --from-literal=rabbitmq-password='[REDACTED]' \
  --from-literal=s3-access-key-id='<access-key>' \
  --from-literal=s3-secret-access-key='<secret-key>' \
  --from-literal=opensearch-username='<username>' \
  --from-literal=opensearch-password='[REDACTED]' \
  --from-literal=ai-gateway-api-key='[REDACTED]'

4. Подготовить values окружения (образцы: helm/platform-rag/values.yaml, values-dev.yaml, values-prod.example.yaml).

Установка

helm lint helm/platform-rag
helm template platform-rag helm/platform-rag -n <namespace> -f values-<env>.yaml

helm upgrade --install platform-rag helm/platform-rag \
  -n <namespace> --create-namespace \
  -f values-<env>.yaml \
  --atomic --wait --timeout 10m

kubectl -n <namespace> rollout status deployment/platform-rag-api --timeout=5m
kubectl -n <namespace> rollout status deployment/platform-rag-worker --timeout=5m
kubectl -n <namespace> get pods,svc

Проверка с порта кластера:

kubectl -n <namespace> port-forward svc/platform-rag 8090:8090
curl -fsS http://127.0.0.1:8090/health

При включённом Ingress (ingress.enabled: true) задайте ingress.hosts[].host и при необходимости TLS. Снаружи публикуется только API; воркер наружу не выставляется.

Особенности промышленного контура

• Образы запускаются от UID/GID 10001, runAsNonRoot, без привилегий, read-only root filesystem, /tmp — emptyDir.
• Конфиг монтируется ConfigMap по пути /app/config/config.yaml.
• Probes API: startup/liveness/readiness на GET /health.
• terminationGracePeriodSeconds: 60 — чтобы воркер успел завершить текущее задание.
• При полной замене блока config сохраните секции api, embedding_profiles, rerank_profiles, chunking, paths, log из значений чарта, если не меняете их намеренно.

Автомасштабирование воркеров (KEDA)

Источник истины backlog — SQL, не глубина очереди RabbitMQ:

SELECT COUNT(*) FROM platform_rag.ingest_job WHERE status = 'PENDING'

Включение в values (см. values-prod.example.yaml):

worker:
  autoscaling:
    enabled: true
    minReplicas: 1
    maxReplicas: 10
    targetQueryValue: "4"
    authentication:
      existingSecret: [REDACTED]
      connectionKey: postgres-dsn-sync

Требования: KEDA в кластере; ключ Secret с libpq-строкой postgresql://… (SQLAlchemy postgresql+asyncpg://… скейлер не принимает). При включённом autoscaling поле replicas у Deployment воркера не задаётся — число реплик принадлежит KEDA.

Подключение моделей

Сервис не содержит собственной языковой модели. Все вызовы эмбеддинга и реранка идут через AI Gateway. Ключи инференса хранятся у шлюза; в конфигурации RAG задаётся только URL шлюза и ключ доступа к нему.

Профили задаются в конфигурации:

embedding_profiles:
  text-default-v1:
    profile_id: text-default-v1
    model: bge-m3
    dimension: 1024
    normalize: true

rerank_profiles:
  rerank-default-v1:
    profile_id: rerank-default-v1
    model: bge-m3
    candidates: 20

Для закрытого контура используется шлюз в контуре заказчика. Передача содержимого документов во внешние сетевые сервисы без правовых оснований недопустима.

ai_gateway.dry_run: true возвращает нулевые векторы фиксированной размерности — только для проверки конвейера без модели. Для приёмки качества поиска dry-run не используется.

Авторизация и доступ

Две плоскости идентичности

Каждый вызов несёт тенант и идентичность вызывающего. В режиме разработки (auth.enabled: false) идентичность передаётся заголовками. В промышленном режиме (auth.enabled: true) обязателен Authorization: Bearer [REDACTED].

Фильтр выдачи строится по правам пользователя, а не агента: один и тот же агент для разных пользователей возвращает разный набор чанков.

SpiceDB

Модель прав:

• collection.owner — пользователь-владелец;
• collection.reader — пользователь, группа или агент (чтение / поиск);
• collection.writer — интеграционный сервис (запись / submit_documents);
• document.view — член viewer_group или parent->read.

При недоступности SpiceDB сервис отвечает 503 authz_unavailable (fail-closed), а не «пропускает» запрос.

ACL документа

В приватной коллекции пустой ACL при upsert недопустим: документ отклоняется (empty_acl_policy: reject) либо индексируется с самой строгой видимостью (strictest). Политика задаётся на коллекции и значением app.empty_acl_policy.

Отзыв прав действует на следующем запросе: ACL перепроверяются в момент retrieval, переиндексация для отзыва не требуется.

Безопасность

Секреты

В Secret / защищённом хранилище: DSN PostgreSQL, пароль RabbitMQ, ключи S3, учётные данные OpenSearch, ключ AI Gateway, preshared key SpiceDB. Файл values и ConfigMap не содержат паролей.

Права на локальный config.yaml с секретами:

chmod 600 config/config.yaml

Сетевые ограничения

Наружу публикуется только API (ClusterIP + Ingress, порт 8090 / TLS). Воркер, PostgreSQL, RabbitMQ, OpenSearch, SpiceDB во внешнюю сеть не публикуются.

Хранение данных

Документы и чанки хранятся в контуре: PostgreSQL (метаданные, jobs), OpenSearch (текст и векторы), S3 (staging). Каждая операция ingest и query подлежит аудиту (минимум: trace_id, операция, идентичность обеих плоскостей, тенант, коллекция).

Резервное копирование

Объекты копирования: PostgreSQL (реестр и job store), индексы OpenSearch, при необходимости бакет staging, файл/Secret конфигурации. RabbitMQ некритичен как SoT.

Логическая выгрузка БД (Compose):

docker compose exec -T postgres \
  pg_dump -U postgres platform_rag > platform_rag_db_$(date +%F).sql

В Kubernetes:

kubectl -n <namespace> exec -T <под_postgresql> -- \
  pg_dump -U <user> platform_rag > platform_rag_db_$(date +%F).sql

Снимки OpenSearch выполняются штатными средствами кластера (snapshot repository). Копии хранятся отдельно от контура приложения; периодически проверяется восстановление.

Восстановление

1. Развернуть ту же версию сервиса с прежними секретами и профилями эмбеддинга.
2. Восстановить PostgreSQL (схема platform_rag).
3. Восстановить снимки OpenSearch (алиас rag-kb-<env>).
4. Запустить API и worker; проверить /health, список коллекций и контрольный query.

Обновление сервиса

Перед обновлением — резервное копирование и окно обслуживания.

Docker Compose

docker compose down
# обновить код / тег образа
docker compose build
docker compose up -d
docker compose logs -f api worker

Сверить config_template.yaml с рабочим конфигом на предмет новых параметров.

Kubernetes (Helm)

helm upgrade --install platform-rag helm/platform-rag \
  -n <namespace> \
  -f values-<env>.yaml \
  --atomic --wait --timeout 10m

Схема базы данных

При app.create_schema_on_startup: true API создаёт/догоняет объекты схемы при старте. Эксплуатация начинается после успешного /health и отсутствия ошибок создания схемы в журнале API.

Откат Helm не отменяет изменения схемы и данных внешних хранилищ.

Откат

helm -n <namespace> history platform-rag
helm -n <namespace> rollback platform-rag <REVISION> --wait --timeout 10m
kubectl -n <namespace> rollout status deployment/platform-rag-api --timeout=5m
kubectl -n <namespace> rollout status deployment/platform-rag-worker --timeout=5m

При несовместимых миграциях откат версии выполняется вместе с восстановлением БД из копии, снятой до обновления.

Мониторинг

Состояние сервисов

Docker Compose

docker compose ps
docker compose logs -f api
docker compose logs -f worker
curl -fsS http://127.0.0.1:8095/health

Kubernetes

kubectl -n <namespace> get pods -l app.kubernetes.io/instance=platform-rag
kubectl -n <namespace> logs deploy/platform-rag-api --tail=200
kubectl -n <namespace> logs deploy/platform-rag-worker --tail=200
kubectl -n <namespace> top pods

GET /health возвращает status: ok | degraded и статусы postgres, rabbitmq, s3, opensearch. Probes Kubernetes используют этот путь.

Дополнительно контролируются: число PENDING/FAILED в ingest_job, глубина DLQ rag.ingest.dlq, латентность query, ошибки AI Gateway.

Журналы

Уровень задаётся log.level (по умолчанию INFO). Воркер пишет о старте listener, захвате job, ошибках эмбеддинга и индексации. Корреляция — trace_id.

Типовые нарушения

Производительность и масштабирование

Воркеры ingest

Основной потребитель ресурсов при загрузке знаний. Число реплик — worker.replicaCount или KEDA по PENDING (целевое значение targetQueryValue, по умолчанию 4 задания на реплику). Параллелизм внутри процесса — app.worker_concurrency (по умолчанию 4). Prefetch RabbitMQ — rabbitmq.prefetch (16).

API

Stateless: увеличивайте api.replicaCount. Пул БД — postgres.pool_size. Эмбеддинг запроса на каждый query идёт в AI Gateway — фактический предел латентности часто определяется шлюзом, а не API.

OpenSearch

Индексу выделяются CPU/RAM; mapping knn_vector требователен к памяти. Смена размерности эмбеддинга требует нового шаблона и переиндексации.

Аварийные ситуации

Недоступность сервиса

1. Проверить /health и Ingress/Service.
2. По details определить отказавший компонент (БД, очередь, S3, OpenSearch).
3. Проверить поды API и worker, события Kubernetes, журналы.
4. Перезапуск:

# Compose
docker compose restart api worker

# Kubernetes
kubectl -n <namespace> rollout restart deploy/platform-rag-api
kubectl -n <namespace> rollout restart deploy/platform-rag-worker

5. При переполнении диска — очистка журналов/образов, расширение PVC OpenSearch/PostgreSQL.
6. При повреждении данных — восстановление из копии.
7. Зафиксировать время, признаки, trace_id, выдержки журналов, выполненные действия.

Эскалация

Перед эскалацией: версия образа/чарта, описание, затронутые коллекции, trace_id, журналы, время, уже выполненные действия.

Platform Memory

Назначение и область применения

Platform Memory — единый управляемый слой памяти платформы. Агент получает персистентную память: search перед ответом, add после ответа. Извлечение фактов, дедупликация, гибридный поиск, изоляция по скоупам и история изменений выполняются сервисом, а не каждым агентом отдельно.

Память не заменяет RAG. Platform RAG отвечает за корпус документов; Platform Memory — за знания о пользователе, агенте и сессии. Сборка промпта комбинирует оба источника.

Публичный контракт совместим с mem0 (add / search / get_all / history / delete). Пути платформы — /v1/*. Платформенные отличия: идентичность вызывающего не берётся из тела запроса, запись асинхронна, инференс и эмбеддинг идут только через AI Gateway.

Архитектура сервиса

Сервис состоит из двух прикладных нагрузок без локального состояния: API (синхронное чтение и приём записи) и воркер извлечения (асинхронный write-path). Состояние хранится во внешних сервисах данных. Модели вызываются только через AI Gateway.

Потоки данных

Запись (POST /v1/memories). Клиент передаёт messages и минимум один скоуп (agent_id или run_id). Идентичность (workspace_id, user_id) берётся из заголовков, не из тела. API создаёт событие PENDING в PostgreSQL, публикует уведомление в RabbitMQ и сразу отвечает 202 с event_id. Если публикация в очередь не удалась, событие помечается FAILED, клиент получает 503 queue_unavailable.

Воркер захватывает событие (RUNNING), вызывает Flow mem0: при infer: true — LLM через AI Gateway с дедупликацией; при infer: false — сохранение сообщений без LLM. Результат пишется в OpenSearch и историю PostgreSQL; статус события — SUCCEEDED или FAILED.

Поиск (POST /v1/memories/search). Синхронно: эмбеддинг запроса через AI Gateway, гибридный поиск в OpenSearch (семантика + BM25), упаковка результатов в token_budget. Обязательны фильтры со скоупом.

Список и забвение. GET /v1/memories возвращает факты по agent_id / run_id в рамках workspace и пользователя. DELETE /v1/memories удаляет записи по фильтру (право на забвение); user_id в запросе не может отличаться от идентичности вызывающего.

История. GET /v1/memories/{memory_id}/history отдаёт журнал ADD / UPDATE / DELETE из PostgreSQL.

Минимальные ресурсы

Значения ориентировочные и уточняются по нагрузке. Для пилотного стенда (проверка API и одного агента):

Языковые модели и эмбеддинги размещаются за AI Gateway, вне сервиса. Требования к GPU определяются выбранной моделью, а не Platform Memory.

Установка и развёртывание

Основной способ пилотных и локальных стендов — Docker Compose. Для промышленных сред — Kubernetes + Helm.

Предварительные требования

• Linux x86-64.
• Docker Engine и Docker Compose версии 2 или кластер Kubernetes с Helm 3.
• Доступ к реестру образов либо возможность собрать образ из исходного кода.
• Для полного цикла add/search: доступные PostgreSQL 16, RabbitMQ 3, OpenSearch 2.x, AI Gateway.

Получение дистрибутива

Сборка образа:

docker build -t platform-memory:<tag> .

Образ запускается от UID/GID 10001 (non-root), корневая ФС в Kubernetes — read-only. В контуре заказчика используется согласованный реестр. После сборки образ публикуется в реестр, доступный узлам кластера.

Настройка конфигурации

Образец — config/config_template.yaml. Рабочий файл задаётся MEMORY_CONFIG. Секреты (DSN, пароли, ключ AI Gateway) не хранятся в Git; для локального стенда допустимы dev-значения только во внутреннем контуре.

Обязательные группы параметров до запуска:

Переопределение из окружения (примеры):

export MEMORY_CONFIG=/app/config/config.yaml
export MEMORY__POSTGRES__DSN='postgresql+asyncpg://[REDACTED]@postgres:5432/platform_memory'
export MEMORY__RABBITMQ__HOST=rabbitmq
export MEMORY__RABBITMQ__PASSWORD='[REDACTED]'
export MEMORY__OPENSEARCH__USERNAME='<user>'
export MEMORY__OPENSEARCH__PASSWORD='[REDACTED]'
export MEMORY__AI_GATEWAY__URL='https://<ai-gateway>/v1'
export MEMORY__AI_GATEWAY__API_KEY='[REDACTED]'

При app.create_schema_on_startup: true API при старте создаёт схему PostgreSQL. Для промышленного контура порядок миграций согласовывается отдельно; откат Helm не откатывает схему БД.

Внимание. Размерность эмбеддинга (embedding.dimension и opensearch.embedding_dimension) закрепляется за индексом. Смена модели/размерности без переиндексации сделает векторный поиск несовместимым.

Развёртывание в Docker Compose

Файл docker-compose.yml поднимает API, worker и зависимости: PostgreSQL, RabbitMQ, OpenSearch. AI Gateway в Compose не входит.

Публикуемые порты Compose:

Проверка:

curl -fsS http://127.0.0.1:8091/health

Ожидается "status": "ok" по компонентам postgres, opensearch, rabbitmq.

Развёртывание в Kubernetes (Helm)

Чарт: helm/platform-memory.

Подготовка

1. Собрать и опубликовать образ.
2. Проверить сетевую доступность PostgreSQL, RabbitMQ, OpenSearch и AI Gateway из целевого пространства имён.
3. Создать Secret с учётными данными:

kubectl -n <namespace> create secret generic platform-memory-secrets \
  --from-literal=postgres-dsn='postgresql+asyncpg://[REDACTED]@host:5432/platform_memory' \
  --from-literal=opensearch-username='<username>' \
  --from-literal=opensearch-password='[REDACTED]' \
  --from-literal=ai-gateway-api-key='[REDACTED]'

4. Подготовить values окружения (образцы: values.yaml, values-dev.yaml, values-prod.example.yaml).

Секция rabbitmq в values.yaml чарта по умолчанию может отсутствовать — её необходимо задать в values окружения, иначе API возьмёт значения по умолчанию (127.0.0.1), непригодные в кластере.

Установка

helm lint helm/platform-memory
helm template platform-memory helm/platform-memory -n <namespace> -f values-<env>.yaml

helm upgrade --install platform-memory helm/platform-memory \
  -n <namespace> --create-namespace \
  -f values-<env>.yaml \
  --atomic --wait --timeout 10m

kubectl -n <namespace> rollout status deployment/platform-memory --timeout=5m

Проверка с порта кластера:

kubectl -n <namespace> port-forward svc/platform-memory 8091:8091
curl -fsS http://127.0.0.1:8091/health

Воркер в Kubernetes

Без platform-memory-worker запросы POST /v1/memories принимаются (202), но события остаются в PENDING. До появления Deployment воркера в чарте воркер запускают тем же образом с командой platform-memory-worker и тем же ConfigMap/Secret, что и API (уточняется при внедрении). В Docker Compose воркер уже описан сервисом worker.

Особенности промышленного контура

• Образы запускаются от UID/GID 10001, runAsNonRoot, без привилегий, read-only root filesystem, /tmp — emptyDir.
• Конфиг монтируется ConfigMap по пути /app/config/config.yaml (MEMORY_CONFIG).
• Probes: startup/liveness/readiness на GET /health.
• terminationGracePeriodSeconds: 30.

Подключение моделей

Сервис не содержит собственной языковой модели. Все вызовы эмбеддинга и LLM-извлечения идут через AI Gateway. Для закрытого контура используется шлюз в контуре заказчика. Передача фактов о пользователях во внешние сетевые сервисы без правовых оснований недопустима.

infer: false позволяет записать готовый факт без вызова LLM (миграция, системные факты, явное «запомни это») — дешевле и предсказуемее для нагрузочных проверок записи.

Доступ и изоляция памяти

Идентичность вызывающего

На текущем релизе идентичность передаётся заголовками. Поля workspace_id / user_id в теле запроса не доверяются.

Без заголовков API отвечает 422. Целевой контракт (JWT платформы + SpiceDB check на memory_collection, fail-closed) описан в PRD и в текущем API не включён.

Скоупы

Факты изолируются по комбинации workspace, user_id, agent_id, run_id. Для add и list обязателен минимум один из agent_id / run_id. Поиск требует filters со скоупом. Удаление по фильтру не позволяет указать чужой user_id (403 Wrong user ID).

Право на забвение

DELETE /v1/memories с фильтром удаляет релевантные факты в OpenSearch и пишет события DELETE в историю. В ответе — deleted_count и confirmation_id для журнала операций.

Безопасность

Секреты

В Secret / защищённом хранилище: DSN PostgreSQL, пароль RabbitMQ, учётные данные OpenSearch, ключ AI Gateway. Файл values и ConfigMap не содержат паролей.

Права на локальный конфиг с секретами:

chmod 600 config/config.yaml

Ключи выдаются по принципу наименьших полномочий; при компрометации отзываются и перевыпускаются.

Сетевые ограничения

Наружу публикуется только API (ClusterIP + Ingress, порт 8091 / TLS). Воркер, PostgreSQL, RabbitMQ, OpenSearch во внешнюю сеть не публикуются.

Management-порт RabbitMQ (15672) на промышленных контурах наружу не публикуется.

Хранение данных

Факты хранятся в контуре: PostgreSQL (события, история), OpenSearch (текст и векторы). Персональные факты в долговременной памяти обрабатываются в контуре заказчика. Передача во внешние LLM без шлюза и правовых оснований недопустима.

Резервное копирование

Объекты копирования: PostgreSQL (event store и история), индексы OpenSearch, файл/Secret конфигурации. RabbitMQ некритичен как источник истины.

Логическая выгрузка БД (Compose):

docker compose exec -T postgres \
  pg_dump -U postgres platform_memory > platform_memory_db_$(date +%F).sql

В Kubernetes (внешний кластер PostgreSQL — штатными средствами кластера):

kubectl -n <namespace> exec -T <под_postgresql> -- \
  pg_dump -U <user> platform_memory > platform_memory_db_$(date +%F).sql

Снимки OpenSearch выполняются штатными средствами кластера (snapshot repository) для алиаса mem-facts-<env>.

Восстановление

1. Развернуть ту же версию сервиса с прежними секретами и той же размерностью эмбеддинга.
2. Восстановить PostgreSQL (схема platform_memory).
3. Восстановить снимки OpenSearch (алиас mem-facts-<env>).
4. Запустить API и worker; проверить /health, контрольный add/search.

Обновление сервиса

Перед обновлением — резервное копирование (п. 5.4) и окно обслуживания.

Docker Compose

docker compose down
# обновить код / тег образа
docker compose build
docker compose up -d
docker compose logs -f api worker

Сверить config_template.yaml с рабочим конфигом на предмет новых параметров.

Kubernetes (Helm)

helm upgrade --install platform-memory helm/platform-memory \
  -n <namespace> \
  -f values-<env>.yaml \
  --atomic --wait --timeout 10m

Откат

helm -n <namespace> history platform-memory
helm -n <namespace> rollback platform-memory <REVISION> --wait --timeout 10m
kubectl -n <namespace> rollout status deployment/platform-memory --timeout=5m

При несовместимых миграциях откат версии выполняется вместе с восстановлением БД и индекса из копии, снятой до обновления.

Мониторинг и журналы

Состояние сервисов

Docker Compose

docker compose ps
docker compose logs -f api
docker compose logs -f worker
curl -fsS http://127.0.0.1:8093/health

Kubernetes

kubectl -n <namespace> get pods -l app.kubernetes.io/instance=platform-memory
kubectl -n <namespace> logs deploy/platform-memory --tail=200
kubectl -n <namespace> top pods

GET /health возвращает status: ok | degraded и статусы postgres, opensearch, rabbitmq. Probes Kubernetes используют этот путь.

Дополнительно контролируются: число событий PENDING/FAILED в memory_event, глубина DLQ memory.add.dlq, латентность search, отставание извлечения (время PENDING → SUCCEEDED).

Журналы

Уровень задаётся log.level (по умолчанию INFO). API пишет о приёме add (event_id, infer) и ошибках публикации в очередь. Воркер пишет о старте listener, захвате события (RUNNING), ошибках mem0/AI Gateway/индексации.

Типовые нарушения

Производительность и масштабирование

Воркеры извлечения

Основной потребитель ресурсов при infer: true (LLM на каждый add). Параллелизм внутри процесса — worker.concurrency (по умолчанию 4). Prefetch RabbitMQ — rabbitmq.prefetch (16). После rabbitmq.delivery_limit (5) неуспешных доставок сообщение уходит в DLQ.

Горизонтальное масштабирование в Compose:

docker compose up -d --scale worker=3

В Kubernetes число экземпляров воркера задаётся отдельно от API (уточняется при внедрении). API при росте search масштабируется увеличением replicaCount.

API

Stateless: увеличивайте число реплик Deployment. Пул БД — postgres.pool_size. Эмбеддинг запроса на каждый search идёт в AI Gateway — фактический предел латентности часто определяется шлюзом, а не API.

Ограничения

Аварийные ситуации

Недоступность сервиса

1. Проверить /health и Ingress/Service.
2. По details определить отказавший компонент (БД, очередь, OpenSearch).
3. Проверить поды API и worker, события Kubernetes, журналы.
4. Перезапуск:

# Compose
docker compose restart api worker

# Kubernetes
kubectl -n <namespace> rollout restart deploy/platform-memory

5. При переполнении диска — очистка журналов/образов, расширение томов OpenSearch/PostgreSQL.
6. При повреждении данных — восстановление из копии (п. 5.5).
7. Зафиксировать время, признаки, event_id, выдержки журналов, выполненные действия.

Эскалация

Перед эскалацией: версия образа/чарта, описание, затронутые workspace/agent_id, event_id, журналы, время, уже выполненные действия.

Примеры запросов для проверки системы

Базовый URL локального Compose: http://127.0.0.1:8093. При запуске API на хосте с портом из конфига: http://127.0.0.1:8091. При port-forward Helm: http://127.0.0.1:8091. Ниже $BASE — выбранный URL.

export BASE=http://127.0.0.1:8093
export WS=ws-admin-check
export USER=user-admin-check
export AGENT=procurement-assistant-v1

Все вызовы кроме /health требуют заголовков X-Workspace-Id и X-User-Id.

Живучесть

curl -fsS "$BASE/health"

Ожидается HTTP 200 и JSON вида:

{
  "status": "ok",
  "components": {
    "postgres": "ok",
    "opensearch": "ok",
    "rabbitmq": "ok"
  },
  "details": {}
}

Запись памяти (async add, infer)

curl -sS -X POST "$BASE/v1/memories" \
  -H "Content-Type: application/json" \
  -H "X-Workspace-Id: $WS" \
  -H "X-User-Id: $USER" \
  -d '{
    "messages": [
      {"role": "user", "content": "Я работаю в отделе закупок, отчёты нужны в xlsx"},
      {"role": "assistant", "content": "Понял, буду присылать xlsx"}
    ],
    "agent_id": "'"$AGENT"'",
    "run_id": "run-admin-check-1",
    "infer": true,
    "metadata": {"source": "admin-check"}
  }'

Ожидается 202:

{
  "event_id": "<uuid>",
  "status": "PENDING"
}

Без agent_id и run_id — 400. Без заголовков идентичности — 422. При недоступном RabbitMQ — 503 с error: queue_unavailable.

Статус события

export EVENT_ID='<uuid из ответа>'

curl -sS "$BASE/v1/events/$EVENT_ID" \
  -H "X-Workspace-Id: $WS" \
  -H "X-User-Id: $USER"

Ожидается 200. Цепочка: PENDING → SUCCEEDED | FAILED.

Список фактов

curl -sS "$BASE/v1/memories?agent_id=$AGENT&page_size=20" \
  -H "X-Workspace-Id: $WS" \
  -H "X-User-Id: $USER"

Ожидается 200, объект с count и массивом results (id, memory, скоупы, created_at).

Поиск

curl -sS -X POST "$BASE/v1/memories/search" \
  -H "Content-Type: application/json" \
  -H "X-Workspace-Id: $WS" \
  -H "X-User-Id: $USER" \
  -d '{
    "query": "в каком формате присылать отчёт",
    "filters": {"agent_id": "'"$AGENT"'"},
    "top_k": 5,
    "token_budget": 400,
    "threshold": 0.1,
    "explain": true
  }'

Ожидается 200: массив results с фактами, score и tokens_returned.

История записи

export MEMORY_ID='<uuid из list или search>'

curl -sS "$BASE/v1/memories/$MEMORY_ID/history" \
  -H "X-Workspace-Id: $WS" \
  -H "X-User-Id: $USER"

Ожидается 200 и массив записей с event: ADD / UPDATE / DELETE.

Удаление по скоупу (право на забвение)

curl -sS -X DELETE "$BASE/v1/memories?agent_id=$AGENT" \
  -H "X-Workspace-Id: $WS" \
  -H "X-User-Id: $USER"

Ожидается 200: deleted_count и confirmation_id.

Попытка ?user_id=other-user при заголовке X-User-Id: $USER — 403.

Негативные проверки

Ключевые параметры конфигурации

Guardrails

Назначение и область применения

Guardrails — система проверки текста (запросов и ответов модели) на запрещённое содержимое. Она отклоняет запрос или ответ либо маскирует чувствительные данные (например, email) до того, как текст попадёт в модель или вернётся клиенту.

Функционал разделён на два слоя с чёткой границей ответственности:

• Control Plane — хранение версий политик, проверка структуры, компиляция в «generation», доставка в Kubernetes и привязка политики к модели.
• Guardrails Runtime — отдельный процесс. Загружает неизменяемый набор правил при старте, выполняет /request и /response и выдаёт вердикт pass / deny / mask.

Ключевой принцип: Control Plane не вызывается на каждый запрос. Он один раз доставляет неизменяемый набор правил в отдельный процесс Runtime, который уже на лету проверяет текст. Недоступность управления не останавливает уже работающие проверки.

Два способа применения

1. Через шлюз (Agentgateway). Политика привязывается к модели в Control Plane. Шлюз сам вызывает Runtime (promptGuard как webhook с failureMode: FailClosed). Защищает текстовые вызовы /v1/chat/completions.
2. Прямой HTTP-вызов из сервиса. Адаптер RAG/Memory сам вызывает Runtime перед индексацией, записью или выдачей. Этот путь можно проверить локально без Kubernetes; для общей среды нужно отдельно согласовать адрес, доступ и версии.

Автоматических привязок вида «политика → коллекция RAG / память агента» в Control Plane нет. Для первого подключения команда платформы и команда сервиса фиксируют параметры среды и явное соответствие операций политикам.

Виды правил

Параметры правила: mode (enforce/observe), onMatch (deny/redact), timeoutMs (1–5000 мс). Базовые правила (baseline) всегда enforce; дополнительные (additional) допускают enforce или observe. Наблюдаемое правило не блокирует и не меняет текст — его срабатывание фиксируется в метриках.

Структура политики

Политика состоит из двух стадий — request (проверка входа) и response (проверка выхода). Каждая стадия включает:

• deadlineMs — общий бюджет стадии (максимум 5000 мс);
• baseline — обязательные правила (всегда enforce), до 64;
• additional — дополнительные правила, до 64.

Модель сущностей: Policy → Stage → Rule[] плюс список providers (до 32). Идентификаторы и ревизии правил/провайдеров — строки вида [a-zA-Z0-9][a-zA-Z0-9._-]* (до 128 символов).

Логика проверки в Runtime

Движок последовательно прогоняет текст через правила выбранной стадии, соблюдая общий бюджет времени стадии. Для каждого правила:

• правило сработало в режиме enforce с действием deny — проверка останавливается, возвращается deny;
• правило в режиме enforce с действием redact — замена накапливается, в конце текст возвращается уже замаскированным (mask);
• правило в режиме observe — срабатывание только фиксируется, решение не меняется.

Если после всех правил замены не накоплены, результат pass.

Надёжность (FailClosed). Таймаут правила или стадии, недоступность внешнего провайдера и неопределённый ответ классификатора трактуются как запрет, а не как пропуск. Ответ формируется только после успешного завершения всей проверки; маска применяется атомарно (пересечение замен или выход за границы — техническая ошибка).

Входные проверки. Прежде чем текст попадёт в движок, Runtime проверяет: один сервисный токен в заголовке Authorization: Bearer; четыре обязательных заголовка контекста; тип application/json без сжатия; конкурентность и размер тела.

Важно про маскирование. Все правила одной проверки видят исходный текст, а не результат предыдущего маскирования. Поэтому маска email первым правилом не скрывает email от следующего LLM-классификатора. Если классификатор не должен получать исходные данные, нужны две отдельные проверки: сначала локальное маскирование, затем вызов классификатора с уже обработанным текстом. Это решение адаптера, а не режим внутри одной политики.

API проверки текста (Guardrails Runtime)

Универсальных маршрутов /v1/check, /evaluate, /batch нет. Guardrails принимает только нормализованные текстовые сообщения; PDF, URL документов, изображения и потоки SSE не поддерживаются. Извлечение текста и обратное сопоставление полей выполняет вызывающий сервис.

Политика не указывается в теле запроса — она задаётся заголовками:

Каждый заголовок должен встречаться ровно один раз; дублирование и пустые значения отклоняются (403 untrusted_context).

Три результата проверки — все возвращаются с HTTP 200:

Проверять только HTTP-статус недостаточно. Техническая ошибка (401, 403, 413, 415, 422, 503, таймаут) трактуется как запрет: защищаемое действие не выполняется до успешной проверки.

Управление политиками (API Control Plane)

Control Plane хранит определения политик и историю их изменений. Сохранение политики создаёт новую версию, но само по себе не включает проверку запросов. Применение к модели — отдельная операция.

Все методы, включая чтение, требуют действующей аутентификации Control Plane и разрешения control_plane:control-plane#administer. Используется токен платформы; сервисный токен проверки текста здесь не подходит.

Для POST и PUT обязателен Idempotency-Key (16–128 символов). Для PUT также обязателен If-Match из последнего чтения изменяемого ресурса. Обновление выполняется полным телом, а не частичным PATCH. Команды возвращают 202; до завершения операции (GET /api/v1/operations/{operationId}) ресурс перечитывают.

Архивирование создаёт новую версию и сохраняет историю, но не снимает ранее применённую защиту. Метода безвозвратного удаления политики нет.

Применение политики к модели

1. Прочитать GET /api/v1/models/{modelId}/guardrail-binding и сохранить ETag.
2. Выполнить PUT того же адреса с этим If-Match и новым Idempotency-Key.
3. Передать точную пару идентификатора и ревизии вместе с contentProfile.
4. Дождаться завершения операции и перечитать привязку. Состояние applied появляется только после подтверждения конфигурации на экземплярах Gateway.

Для отката применяют ранее сохранённую ревизию тем же методом. Для снятия защиты передают policyId: null и policyRevision: null, сохранив contentProfile. Редактирование политики после применения не меняет уже работающую версию — привязка действует на модель целиком.

Настройки процесса Runtime

Токен содержит от 32 до 4096 печатных ASCII-символов без пробелов. Секреты не хранятся внутри политики, примера запроса или Git; правило содержит только credentialRef. Ограничения сети и TLS обеспечивает среда: сам HTTP-процесс запускается на заданном адресе/порту и не настраивает сертификаты. Разрешены только нужные источники вызовов и назначения провайдеров.

HTTP-клиент Guardrails проверяет TLS, не следует редиректам и не использует прокси из переменных окружения. Вызов собственной защищённой модели через Gateway создаст рекурсию: проверка снова вызовет саму себя. Текст уходит внешнему провайдеру только для правил, которые его вызывают; локальные стоп-листы и регулярные выражения внешнюю модель не используют.

Обновление набора политик

Набор политик имеет schemaVersion: agent-platform.guardrail-runtime.bundle/v1 и содержит обе стадии, список провайдеров и общие ограничения. Guardrails читает и проверяет его при старте. Изменение файла на диске не приводит к перечитыванию; управляющего метода перезагрузки нет.

Для обновления нужны новый проверенный набор, его контрольная сумма и новый процесс (поколение). Клиент переключает связку «адрес, политика, ревизия, контрольная сумма, профиль» как единое целое. Пока один Service распределяет запросы между старыми и новыми наборами, часть вызовов с новой контрольной суммой получит 503. Старое поколение сохраняют, пока завершаются его запросы и пока нужен откат. В управляемой доставке через Control Plane есть предел 32 поколения и нет автоматического удаления по возрасту.

Ограничения нагрузки

У Guardrails нет внутренней очереди: при заполнении лимита одновременных проверок возвращается 503 overloaded. Число параллельных вызовов ограничивают со стороны обработчиков RAG/Memory; суммарная нагрузка всех процессов и повторов важнее ограничения одного обработчика.

Наблюдение и диагностика

GET /readyz возвращает {"ready":true}, если набор загружен. Это не проверка качества правил, доступности внешней модели или применения конфигурации Gateway. После запуска выполняют синтетические проверки разрешения, маскирования и запрета.

GET /metrics требует сервисного токена и содержит ограниченные счётчики проверок, ошибок, наблюдаемых срабатываний и длительности. Метки не содержат текст, ключи, адреса провайдеров или имена политик. Это показатели процесса, сбрасываемые при перезапуске; хранилища результатов или журнальных записей каждого решения Guardrails не предоставляет.

Не включают запись тел запросов в прокси и журналы ради диагностики. Используют код ошибки, идентификатор задания, ревизию политики и длительность.

Развёртывание

Важно: Развёртывание Guardrails реализовано только для локального контура разработки (Kind). Активация в среде ST и в промышленном контуре — отдельное решение. В текущем развёртывании ST Guardrails не поставляется: его включение, адрес и учётные данные согласуются отдельно.

Guardrails поставляется не отдельным Helm-чартом, а связкой действий Garden:

1. Сборка образа — нативный образ guardrail-runtime собирается из src/guardrail-runtime/Dockerfile и публикуется в реестр по неизменяющему digest.
2. Доставка конфигурации — сценарий доставки управляет неизменяемой TLS-идентичностью транспорта (Secret + неизменяемый ConfigMap CA) с именем сервера guardrails.agent-platform.internal, проверяет срок действия сертификата и доставляет одобренный каталог классификаторов в Control Plane.
3. Патч шлюза — контроллер Agentgateway (Helm-релиз agentgateway в agentgateway-system) патчится проверенным по SHA-256 источником, чтобы inline-webhook promptGuard модели получал политики TLS, аутентификации и таймаутов.

Профиль текущего контура — v1.5.0-ap-gr1. Роллаут выполняется garden run agentgateway-controller --env dev-local (атомарный Helm-upgrade; CRD, Secret и PVC не удаляются).

Для прямого вызова из RAG/Memory (без Kubernetes) достаточно запустить процесс guardrail-runtime serve с согласованными переменными окружения (см. «Настройки процесса Runtime») и файлом набора политик.

Ввод в работу

1. Обе команды согласуют точки записи/чтения и поля, которые нужно проверять.
2. Владелец политики готовит правила и синтетический корпус; платформа — конфигурацию и доступ.
3. Команда сервиса проверяет локальные примеры и обработку всех трёх решений (разрешить, заблокировать, маскировать).
4. На общей тестовой среде выполняются сквозные сценарии, включая недоступность Guardrails и повтор задания.
5. Проверяются новое поколение, переключение и откат, затем согласуется включение для реальных данных.

Готовность интеграции в сервисе подтверждается только испытанием его реальной записи и выдачи вместе с хранилищами, очередями и проверками доступа.