1. Слой 1 — Ограниченный API-ключ
Ключ — первые ворота. Прежде чем какое-либо содержимое будет проверено или вызвана модель, шлюз разрешает вызывающий ключ и решает, разрешён ли запрос вообще. Что несёт ключ:model_limits— набор моделей, которые ключ может вызывать. Запрос модели вне списка отклоняется немедленно.allow_ips— опциональный список разрешённых IP. Запрос из незарегистрированного источника отклоняется.credit_limit_usd— жёсткий лимит расходов. Запрос, который поднял бы ключ выше лимита, отклоняется.expiry— жёсткий срок действия. Просроченные ключи отклоняются.environment— тег (production,staging,dev, …) для организации и идентификации ключа по среде развёртывания.guardrail_id— политика guardrail, привязанная к этому ключу (см. Слой 2 и Слой 4).firewall_policy_id— политика firewall, привязанная к этому ключу (см. Слой 3).is_firewall_gateway— флагирует ключ как токен с областью firewall-gateway; требуется для маршрутов evaluate и MCP gateway.
is_firewall_gateway и чтение открытого текста
ключей требуют Admin.
Полную модель ключей см. в Область, ключи, политики и рабочие пространства.
2. Слой 2 — Входные guardrails
После валидации ключа шлюз прогоняет правила входной стадии привязанного guardrail против текста запроса — до любого вызова вышестоящей модели. Что он видит: Сообщения вызывающего в том виде, в котором они отправлены. (Промпт, внедрённый из реестра промптов, добавляется позже, на этапе маршрутизации; входные правила его не видят.) Доступные типы правил:keyword, regex, pii, max_chars, external, llm_judge, grounding.
Действия, которые может выдать правило:
| Действие | Что происходит |
|---|---|
block | Запрос отклоняется — HTTP 400 guardrail_blocked. Квота не списывается. Помечается skip-retry. |
mask | Совпадение редактируется (например, jane@acme.com → [EMAIL]). Очищенный текст продолжается к модели. |
flag | Совпадение записывается; трафик не изменяется. |
block на этой стадии означает, что модель никогда не вызывается. Стоимость: ноль. Вызывающий видит структурированную ошибку с именем guardrail и правилом, которое сработало.
Где настраивать: Консоль → Guardrails или guardrail API. Требуется Developer+
для создания или изменения. См. Guardrails для полного
справочника правил.
3. Слой 3 — Запуск модели
Если ключ валиден и входные guardrails пройдены, шлюз пересылает запрос вышестоящей модели. Это единственный слой без настраиваемого применения — это просто модель, выполняющая свою работу. Firewall работает с действиями, которые производит модель (Слой 3 → Слой 4 ниже), а не с самой моделью. Маршрутизация, откаты и балансировка нагрузки происходят здесь прозрачно.4. Слой 4 — Agent Firewall (вызовы инструментов и egress)
После ответа модели — или inline, по мере выпуска вызовов инструментов — Agent Firewall оценивает каждое действие, которое запрашивает модель. Четыре поверхности применения:| Поверхность | Что видит firewall |
|---|---|
inbound | Определения инструментов, которые агент рекламирует модели. Блокировка опасного инструмента до того, как модель сможет его выбрать. |
response | tool_calls, которые модель выпускает в своём ответе. |
mcp | tools/call, диспетчеризованный через MCP gateway Firewall или оцененный через хук evaluate. |
egress | Исходящий сетевой адрес назначения (host / IP / CIDR), сообщённый инструментом — поверхность SSRF и эксфильтрации данных. |
| Вердикт | Что делает |
|---|---|
allow | Вызов продолжается. Логируется. |
audit | Вызов продолжается; записывается для разбора. Default default_verdict. |
deny | Вызов заблокирован — HTTP 400 firewall_blocked на поверхности inbound; ошибка инструмента на mcp. |
sanitize | Совпавшие подстроки редактируются из аргументов инструмента; очищенный вызов продолжается. На inbound (нет аргументов) эскалирует до deny. |
pending_approval | Вызов удерживается; проверяющий вне основного канала одобряет или отклоняет; агент повторно отправляет с одноразовым токеном подтверждения. |
cap_cost | Deny, когда накопленные расходы прогона агента превышают лимит в центах по правилу. |
deny на поверхности inbound не стоит токенов модели — блокировка срабатывает
до вышестоящего вызова. Удержание pending_approval возвращает HTTP 400
firewall_approval_pending с id подтверждения, который клиент опрашивает.
Где настраивать: Консоль → Firewall или firewall API. Требуется Developer+
для создания или изменения политик и правил. См. Firewall
и Правила Firewall для полного языка правил.
5. Слой 5 — Выходные guardrails
После ответа модели (и после завершения любого цикла вызовов инструментов) шлюз прогоняет правила выходной стадии привязанного guardrail против текста ответа до того, как он достигнет вызывающего. Те же типы правил и действия применяются, что и в Слое 2. Выходнойblock
возвращает HTTP 400 guardrail_blocked и возвращает предварительно списанную
квоту — вызывающий ничего не платит.
Стриминг и маскирование вывода. Действие
block применяется как к
стриминговым, так и к нестриминговым ответам — на потоке сканер прерывает
его на лету и выпускает замену. Действие mask на выходе сейчас применяется
только к нестриминговым ответам; на стриминговом ответе оригинальный чанк
проходит без маскирования. Проверьте комбинацию стадии/потока в песочнице
guardrail, прежде чем полагаться на неё.6. Слой 6 — Аудит
Каждое совпадение, вердикт и решение о подтверждении записывается в журнал аудита, скоррелированный с прогоном агента и сессией, которые его вызвали. Это не отдельный шаг применения — он выполняется параллельно со Слоями 2–5 — но это слой, который делает остальные подотчётными. Что логируется:- Совпадения guardrail: тип правила, действие, стадия, строка деталей и (если включён Log raw content) совпавшая подстрока.
- События firewall: поверхность, имя инструмента, вердикт, совпавшее правило, код причины, факторы риска и прогон/сессия, к которым принадлежит вызов.
- Решения о подтверждении: кто одобрил или отклонил, когда и изменилось ли базовое правило между удержанием и решением.
- Изменения политик: каждое создание, обновление, удаление и изменение уровня автономии записывает версионированную строку аудита.
7. Сводная таблица
| Слой | Что контролирует | Что видит | Результат при срабатывании | Где настраивать |
|---|---|---|---|---|
| 1. Ограниченный ключ | Идентификация, доступ к модели, расходы, IP, срок действия | Токен аутентификации запроса | HTTP 4xx до запуска чего-либо; без тарификации | Консоль → API Keys (Developer+) |
| 2. Входные guardrails | Текстовое содержимое запроса | Сообщения вызывающего | Block (HTTP 400 guardrail_blocked, без списания), mask или flag | Консоль → Guardrails (Developer+) |
| 3. Модель | — | — | — | Конфиг маршрутизации / канала |
| 4. Agent Firewall | Вызовы инструментов, диспетч MCP, egress | Имя инструмента, аргументы, назначение | allow / audit / deny / sanitize / pending_approval / cap_cost | Консоль → Firewall (Developer+) |
| 5. Выходные guardrails | Текстовое содержимое ответа | Ответ модели | Block (HTTP 400, квота возвращена), mask или flag | Консоль → Guardrails (Developer+) |
| 6. Аудит | Атрибуция и журнал | Всё вышеперечисленное | Неизменяемая запись лога | Консоль → Matches (Member) / Events & Runs (Developer+) |
8. Порядок разрешения политик
Для любого запроса активный guardrail и политика firewall разрешаются независимо:- Привязка ключа — если ключ несёт явный
guardrail_idилиfirewall_policy_id, эта политика применяется (если она существует и включена). - Default рабочего пространства — если у ключа нет привязки, применяется
включённый guardrail или политика рабочего пространства с
is_default. - Ни то, ни другое — нет применения. Запрос побайтно идентичен рабочему пространству, которое никогда не включало эту функцию.
9. Fail-open и fail-closed
Два поведения — применяются в разных случаях.Fail-open (переходные ошибки): Если разрешение политики упирается в переходную
ошибку — сбой базы данных, сетевой сбой на пути к внешнему вендору — шлюз
деградирует до отсутствия применения, а не кладёт трафик. Безопасность
деградирует; доступность сохраняется. Настройте
fail_open: false для правил
external или llm_judge, когда пропущенная проверка недопустима для вашей политики.Fail-closed (неоднозначные случаи): Там, где неприменение сводило бы на
нет правило, движок fail closed: отчёт egress с неразрешимым назначением отклоняется;
недостижимое хранилище подтверждений удерживает вызов, а не пропускает его;
навык, чьё владение не удаётся разрешить, блокируется. Доступность сохраняется
на счастливом пути; безопасность не пропускается молча в важных крайних случаях.10. Детальные обзоры
Guardrails
Полный справочник правил — типы, действия, PII-сущности, LLM judge,
grounding и тестовая песочница.
Firewall
Модель политик, вердикты, поверхности, shadow-режим, HITL-подтверждение
и детектирование аномалий.
Правила Firewall
Язык сопоставления правил — глобы инструментов, клаузы аргументов,
списки egress и очистители.
Guardrails vs. Firewall
Какой слой перехватывает какую угрозу — и когда нужны оба.
Область, ключи и политики
Полная модель ключей: что несёт ключ и как разрешаются политики.
Режимы применения
Fail-open vs. fail-closed — полное дерево решений.