Перейти к основному содержанию
У вас есть ключ, который ваш агент использует на api.orcarouter.ai, и вы хотите, чтобы каждым вызовом инструмента, который делает этот ключ, управляли — блокировали, аудировали, очищали или удерживали для подтверждения — без изменений в коде агента. Это настройка agent firewall в два шага: создайте политику firewall один раз, затем направьте ключ на неё. Со следующего вызова каждый инструмент, который выпускает ключ, проверяется по политике в шлюзе. Эта страница — путь создания и привязки. Полную модель политик (поверхности, вердикты, разрешение) см. в Обзоре Firewall; грамматику правил см. в Правилах Firewall.
Вся конфигурация политик и ключей происходит в консоли (или на управляющих маршрутах /api/workspace/firewall/*, которые используют вашу сессию / access token — не relay-ключ sk-orca-…). Только вызовы /v1/* вашего агента используют relay-ключ. Создание и привязка политики — это действие Developer+.

​
1. Настройка agent firewall с первого взгляда

Политика firewall — это именованный объект в рамках рабочего пространства: упорядоченный список правил плюс default-вердикт для всего, с чем не совпало ни одно правило. Ключ подключается к политике через своё поле firewall_policy_id. Больше ничто в вашем стеке не меняется.

Создайте политику

Назовите её, выберите default-вердикт, добавьте правила — или засейте из уровня автономии / пресета и отредактируйте.

Привяжите ключ

Установите firewall_policy_id ключа на политику или отметьте политику как default рабочего пространства, чтобы каждый непривязанный ключ её наследовал.

​
2. Создайте политику в консоли

  1. Откройте Security → Firewall → Policies и выберите New policy.
  2. Назовите её (уникально в рабочем пространстве) и оставьте Enabled включённым.
  3. Выберите default-вердикт — см. §3.
  4. Добавьте правила в редакторе правил или начните с пустого и позвольте Discovered tools управлять написанием из реального трафика позже.
  5. Сохраните. Политика существует, но ничем не управляет, пока на неё не укажет ключ или вы не сделаете её default’ом рабочего пространства.
Не хотите сначала писать правила вручную? Примените уровень автономии (balanced — рекомендуемый старт) — он материализует реальные, редактируемые строки политики и guardrail, которые вы затем можете настроить. Или начните правило из встроенного пресета и отредактируйте его. В любом случае вы окажетесь в одном месте: именованная политика, которую вы привязываете к ключу.

​
3. Выберите default-вердикт

Default-вердикт — это то, что политика делает, когда вызову инструмента не соответствует ни одно правило. Это нижний предел вашей позиции. Он принимает ровно три значения:
default_verdictКогда ни одно правило не совпало…
audit (по умолчанию)Разрешить вызов, но записать его. Наблюдать всё, не блокировать ничего — безопасное место для старта.
allowРазрешить и логировать, без записи для разбора.
denyЗаблокировать всё, что правило явно не разрешает, — позиция default-deny, которую вы сочетаете с правилами allow.
deny — это default-deny: любой вызов инструмента, который ваши правила явно не разрешают, блокируется. Мощно, но он остановит вызовы, которые вы забыли добавить в список разрешённых. Разверните политику default-deny сначала под shadow-режимом и наблюдайте ленту событий, прежде чем применять её.
Вердикты, которые может производить правило (allow, audit, deny, sanitize, pending_approval, cap_cost), рассмотрены в Вердиктах — default-вердикт ограничен тремя выше.

​
4. Привяжите политику к ключу

Ключ подключается к политике через свой firewall_policy_id. В консоли:
  1. Откройте Keys, отредактируйте ключ, который использует ваш агент.
  2. Установите Firewall policy на созданную вами политику (это записывает firewall_policy_id).
  3. Сохраните. Следующий вызов, который делает этот ключ, управляется.
Привязка живёт на ключе, в шлюзе — ваш агент продолжает отправлять тот же Authorization: Bearer sk-orca-… и то же тело запроса. Нет никаких изменений в коде вызова инструментов вашего агента. 
# Relay-вызов вашего агента не изменён. Привязанная политика применяется
# в шлюзе до того, как будет диспетчеризован любой вызов инструмента в ответе.
curl https://api.orcarouter.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-orca-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "delete the staging table"}],
    "tools": [{"type": "function", "function": {"name": "db.query"}}]
  }'
Если правило отклоняет вызов инструмента на поверхности inbound, этот вызов возвращается как HTTP 400 с кодом firewall_blocked, называя инструмент и причину, — см. как выглядит блокировка.

​
5. Разрешение: привязанная → default рабочего пространства

Для любого вызова инструмента шлюз разрешает, какая политика применяется, в этом порядке:
Если firewall_policy_id вызывающего ключа указывает на политику, которая существует и включена, применяется эта политика.
Иначе применяется включённая политика is_default рабочего пространства (если она задана). Не более одной политики на рабочее пространство может быть default’ом; продвижение нового default’а понижает старый в той же транзакции.
Нет привязки и нет default’а означает отсутствие политики. При включённом observe-режиме вызов разрешается и логируется как пробел в покрытии; при выключенном вызов разрешается молча.
Отключённая привязанная политика откатывается к default’у рабочего пространства — она не выключает применение. (Это отличается от guardrails, где отключённая привязка разрешается в none.) Чтобы вывести ключ из области firewall, отвяжите его (установите firewall_policy_id в 0), а не просто отключайте его политику.
Чтобы сделать политику default’ом для каждого непривязанного ключа, отредактируйте её и установите как default рабочего пространства, а не привязывайте ключи по одному — см. Управление политиками.

​
6. Проверьте, что вступило в силу

Прежде чем полагаться на неё, убедитесь, что политика срабатывает так, как вы ожидаете:
  • Протестируйте её — песочница на вкладке Test делает dry-run политики по образцу вызова инструмента и возвращает вердикт, совпавшее правило и причину. Ничего не диспетчеризуется и не сохраняется. См. Тестирование правил.
  • Наблюдайте ленту событий — как только ключ начнёт принимать живой трафик, Events показывает каждое вычисление, фильтруемое по вердикту, поверхности, инструменту и прогону.
Разверните любую применяющую политику сначала за shadow-режимом: она вычисляется и логируется ровно так, как делала бы в production, но понижает каждый применяющий вердикт до audit и снабжает причину префиксом [shadow] would …. Выключите shadow, как только лента событий покажет, что она срабатывает на том, на чём вы ожидаете, и ни на чём, на чём не ожидаете.

​
Куда двигаться дальше

Написание правил

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

Списки разрешённых инструментов

Сочетайте default-вердикт deny с явными правилами allow.

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

Default’ы, включение/выключение, версионирование и откат.

Почему нулевое доверие

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