API Guardrails Runtime

Версия и границы API

Описание включает профиль agentgateway-1.5.0-chat-webhook-v2 от 17 сентября 2026 года. OpenAPI 3.1 фиксирует HTTP-контракт. Прежние профили agentgateway-1.4.1-text-webhook-v1 и agentgateway-1.5.0-text-webhook-v1 сохраняются для существующих наборов. Значение заголовка должно точно совпадать с contentProfile загруженного набора.

Через Agentgateway новый профиль допускает потоковый ответ, вызовы инструментов и сообщения с изображениями. Сам Runtime по-прежнему получает только текст. Шлюз выделяет текстовые части и сохраняет вложения и служебные поля при передаче модели. Правила не анализируют изображение, аргументы инструментов и отдельные поля рассуждения. Текст результатов инструментов входит во входную проверку.

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

Имена стадий выбирают секцию политики. Они не заставляют Guardrails вызвать модель, сохранить документ или проверить обе стадии автоматически. Для RAG и Memory соответствие операции и стадии фиксируется в конфигурации адаптера.

Заголовки каждого вызова проверки

Заголовки авторизации и контекста должны быть непустыми и встречаться ровно один раз. Дублирование отклоняется. Content-Encoding на входе не поддерживается. Не копируйте эти заголовки из внешнего HTTP-запроса: они относятся к доверенной конфигурации клиента. Неверная контрольная сумма или неизвестная ревизия не переключают Guardrails на другую политику.

Тело POST /request

{
  "body": {
    "messages": [
      {"role": "user", "content": "Связаться: demo@example.org"}
    ]
  }
}

Массив messages непустой. У сообщения ровно два поля: role — непустая строка до 32 символов, content — строка. null, массив мультимодальных частей, tool_calls, name и другие дополнительные поля не поддерживаются. role не является утверждением о доверии или авторизации: даже сообщение с ролью system для классификатора остаётся проверяемыми данными.

Тело POST /response

{
  "body": {
    "choices": [
      {"message": {"role": "assistant", "content": "Связаться: demo@example.org"}}
    ]
  }
}

choices также непустой. Это нормализованный объект, а не полный ответ Chat Completions: id, model, usage, index, finish_reason и прочие поля передавать нельзя. Служебные данные и идентификаторы RAG/Memory храните рядом в адаптере, не добавляйте в тело запроса Guardrails.

Три результата завершённой проверки

Все три результата возвращаются с HTTP 200. Проверять только HTTP-статус или raise_for_status() недостаточно.

Разрешить

{"action":{"reason":"policy_pass"}}

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

Заблокировать

{
  "action": {
    "body": "Запрос отклонён политикой",
    "status_code": 403,
    "reason": "policy_denied"
  }
}

Остановите защищаемое действие. action.status_code — часть решения для вызывающей системы; HTTP-ответ самого Guardrails остаётся 200. В сервисе RAG/Memory преобразуйте решение в согласованную доменную ошибку или отказ задания. Не делайте повтор того же содержимого для «получения разрешения».

Маскировать

Для /request:

{
  "action": {
    "body": {"messages": [{"role": "user", "content": "Связаться: [EMAIL]"}]},
    "reason": "content_redacted"
  }
}

Для /response:

{
  "action": {
    "body": {"choices": [{"message": {"role": "assistant", "content": "Связаться: [EMAIL]"}}]},
    "reason": "content_redacted"
  }
}

Подставьте возвращённые строки вместо исходных. Число сообщений, порядок и роли сохраняются. Если ваш клиент обнаружил несоответствие, считайте ответ ошибочным. action.body заменяет проверяемое тело, но не весь доменный объект с его ACL, идентификаторами и метаданными. HTTP API не отдаёт смещения замен или список найденных сущностей: повторно искать совпадения в исходном тексте не нужно.

Потоковый ответ через Agentgateway

Control Plane включает promptGuard.streaming: Enabled. Клиент модели отправляет обычный запрос Chat Completions с stream: true. Заголовки контекста проверки формирует шлюз; клиент не может выбрать ими более слабый режим.

Преобразование выходного маскирования в запрет — явное правило нового профиля. Agentgateway 1.5.0 не применяет Mask к SSE. Поэтому Runtime в режиме sse-reject возвращает Reject вместо Mask; молчаливого пропуска исходного текста нет. Режим observe по-прежнему ничего не блокирует.

HTTP-статус уже начатого потока может быть 200, даже если дальнейшая выдача заблокирована. Клиент должен разбирать события ошибок, отмечать ответ как незавершённый и не выдавать накопленный текст за успешный результат. guardrail_error означает ошибку проверки, а не совпадение с правилом.

Шлюз проверяет текст окнами. В закреплённой версии размер окна составляет 1024 байта, перекрытие — 256 байт. Короткий ответ может появиться только в конце. Ранее выданную разрешённую часть отозвать невозможно. Проверка окон не равна проверке смысловой связи всего ответа: правило, которому нужен полный документ, следует выполнять с stream: false. Поддерживается один вариант ответа (n=1). Служебные части tool_calls и отдельные поля рассуждения не становятся проверенным пользовательским текстом; клиент должен обрабатывать их отдельно.

При входном маскировании нескольких текстовых частей одного сообщения шлюз объединяет их в одну очищенную текстовую часть. Изображения сохраняют исходные данные и порядок между собой. Байты изображений не отправляются в Runtime. Прямой PDF или произвольный файловый объект в Chat Completions этим профилем не предусмотрен: SDK-агент или узел потока сначала извлекает текст документа.

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

Алгоритм клиента

1. Зафиксировать таблицу «позиция сообщения → поле документа/факта» и выбранную политику.
2. Проверить размер сериализованного UTF-8 JSON и число сообщений.
3. Выполнить вызов с ограниченным временем ожидания. Не следовать редиректам.
4. Для любого HTTP-статуса, отличного от 200, или ошибки сети запретить защищаемое действие до успешной проверки.
5. Для 200 проверить JSON по RequestResult или ResponseResult из OpenAPI.
6. Разобрать три варианта выше. Неизвестный или неполный action считать технической ошибкой.
7. Только после успешного разрешения/маскирования передать результат дальше. Сохранять и индексировать исходник после mask запрещено логикой адаптера.

Проверенный пример клиента реализует этот разбор. Быстрый запуск показывает его использование.

Технические ошибки

{
  "code": "policy_unavailable",
  "message": "Guardrail check could not be completed",
  "traceId": "0123456789abcdef0123456789abcdef"
}

Ошибка имеет плоские поля code, message, traceId. Это не формат ошибок Control Plane или RAG/Memory. В сообщение не включаются исходный текст и провайдерские ответы. Для диагностики используйте код и traceId.

503 не всегда временная ошибка. Переходите к повторам только после классификации причины. Guardrails не предоставляет Retry-After, ключи идемпотентности и хранилище результатов проверок. Классификатор при повторе может дать другой ответ; результат не считается детерминированным даже при температуре 0. Идемпотентность записи в RAG/Memory обеспечивает ваш сервис.

Как выполняются правила

Политика содержит секции request и response. В каждой — общий deadlineMs, непустой список baseline и список additional. Сначала выполняются базовые, затем дополнительные правила в порядке списка. Все видят исходный текст этой проверки, а не результат предыдущего маскирования.

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

Базовые правила всегда enforce. Дополнительные допускают enforce или observe. Наблюдаемое правило не блокирует и не меняет текст; его срабатывание или ошибка учитываются в метриках. Общий таймаут стадии и ошибки обязательных правил всё равно запрещают продолжение.

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

Схемы конфигурации: bundle/v1 и detector/v1. Провайдер-классификатор настраивается отдельно от модели агента. Для профиля openai.chat-completions.classifier/v1 нужны строгая JSON Schema, temperature: 0, max_completion_tokens, stream: false, store: false. Одного названия «OpenAI-compatible» недостаточно: конкретный профиль нужно проверить. Другие поддержанные профили выбираются явно, автоматической смены протокола нет.

Лимиты

Схема дополнительно ограничивает каждую строку content 131072 символами, но более низкий байтовый лимит тела применяется раньше. Учитывайте обёртку JSON, экранирование и многобайтовые символы. Значения среды могут отличаться от примера: нет универсального обещания задержки, пропускной способности или размера документа.