Управление политиками Guardrails

Для чего нужен этот API

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

Сервисам RAG и Memory этот API не нужен для каждого документа или факта. Они вызывают API проверки текста, используя заранее подготовленную конфигурацию. API управления нужен владельцу политик и команде, которая поставляет конфигурацию.

Описано поведение ветки feature/guardrails-specification на 15.09.2026. Версия контракта управления: agent-platform.control-plane.guardrail-management/v1. Маршруты Guardrails в текущем коде исключены из автоматической схемы FastAPI через include_in_schema=False. Поэтому отсутствие маршрута в общей схеме Control Plane не означает, что он недоступен. Справочник ниже сверен с control_plane/guardrail_api.py; отдельной полной OpenAPI-схемы управления Guardrails сейчас нет. Схема Guardrails описывает только проверку текста.

Доступ и общие правила

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

Для POST и PUT обязателен Idempotency-Key: 16–128 символов из A–Z, a–z, 0–9, ., _, ~, -. Для PUT также обязателен If-Match, полученный последним чтением изменяемого ресурса, например "r3". Обновление выполняется полным телом, а не частичным PATCH.

Команды возвращают HTTP 202 и обычное представление операции Control Plane. Нужно дождаться её завершения через GET /api/v1/operations/{operationId}, а затем перечитать ресурс. Повторяйте одну и ту же команду с тем же ключом; для нового изменения используйте новый ключ. Другой запрос с прежним ключом даёт 409, устаревшая версия в If-Match — 412.

Справочник методов

Идентификаторы ресурсов Control Plane — UUIDv7. Ревизии политик в этом API — положительные целые числа, тогда как в HTTP-заголовках Guardrails они передаются строками. definitionDigest определения политики и bundleDigest набора Guardrails относятся к разным объектам и не взаимозаменяемы.

Создание и изменение политики

Тело создания:

{
  "name": "rag-write",
  "description": "Проверка текста перед индексацией",
  "definition": {
    "request": <секция проверки входа>,
    "response": <секция проверки выхода>,
    "providers": []
  }
}

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

import json
from pathlib import Path

bundle = json.loads(Path('docs/examples/guardrails-integration/policy-bundle.json').read_text())
policy = bundle['effectivePolicies'][0]
create_body = {
    'name': 'rag-write',
    'description': 'Проверка текста перед индексацией',
    'definition': {
        'request': policy['request'],
        'response': policy['response'],
        'providers': bundle['providers'],
    },
}

name — 1–128 символов, начинается с латинской буквы или цифры; далее разрешены латинские буквы, цифры, точки, дефисы и подчёркивания. description — до 2048 символов, по умолчанию пустая строка. Для PUT добавляется обязательное поле status: "draft" либо status: "archived". Неизвестные поля запрещены.

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

Ответ чтения содержит id, name, description, revision, status, definitionDigest, даты, ruleCount, ruleKinds; детальное чтение также содержит definition. Статус draft означает сохранённую редакцию. Даже если конкретная её версия применяется к модели, этот статус не становится active: состояние применения находится у привязки модели.

Архивирование создаёт новую версию и сохраняет историю. Оно не снимает ранее применённую защиту. Перед новым применением архивную политику нужно восстановить новой версией draft. Метода безвозвратного удаления политики нет.

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

1. Прочитайте GET /api/v1/models/{modelId}/guardrail-binding и сохраните ETag.
2. Выполните PUT того же адреса с этим If-Match и новым Idempotency-Key.
3. Передайте точную пару идентификатора и ревизии:

{
  "policyId": "01994670-0000-7000-8000-000000000001",
  "policyRevision": 1,
  "contentProfile": "agentgateway-1.5.0-text-webhook-v1"
}

UUID приведён только как пример формата: замените его идентификатором созданной политики. If-Match относится к модели, а не к политике.

4. Дождитесь завершения операции и перечитайте привязку. Состояние applied появляется после подтверждения нужной конфигурации на обслуживающих экземплярах Gateway. Само получение 202 не означает, что защита уже действует.

Чтение также возвращает modelId, gatewayName, modelRevision, operationId, binding и observation. В непустом binding находятся policyId, policyRevision, generationId, bundleDigest.

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

Редактирование политики после применения не меняет уже работающую версию. Привязка действует на модель, а не только на одного агента. При общей модели политику получают все её вызовы в поддержанном профиле. Текущая управляемая интеграция проверяет ответ Chat Completions целиком перед передачей клиенту; потоковая выдача, инструменты и другие неподдержанные формы не объявляются защищёнными.

Чего здесь пока нет для RAG и Memory

Нет API привязки политики к коллекции, типу памяти или операции записи; нет выдачи сервисных секретов соседним командам и загрузки произвольного набора через Guardrails. Нельзя использовать модельную привязку как неявный способ создать обслуживаемое подключение RAG/Memory.

Для первого подключения команда платформы и команда сервиса фиксируют параметры среды и явное соответствие операций политикам. Если потребуется управлять этим из Control Plane, понадобится отдельное расширение его контракта.