Глава 4. Инструментальный шлюз, подтверждения и журнал аудита¶

1. Где на самом деле происходят дорогие инциденты¶

Самые дорогие сбои в агентных системах обычно случаются не тогда, когда модель “не так подумала”, а тогда, когда система перешла к действию:

• что-то записала;
• что-то отправила;
• что-то изменила;
• куда-то выгрузила данные.

Именно поэтому граница исполнения важнее, чем многим кажется.

В нашем сквозном кейсе поддержки это выглядит очень приземленно: агент уже проверил статус заявки и теперь собирается создать срочный тикет. До этого момента система еще могла ошибаться “внутри себя”. С этого момента она начинает менять внешний мир.

2. Инструментальный шлюз должен быть скучным и жестким¶

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

Минимальные требования:

• принимать только разрешенные инструменты;
• валидировать аргументы;
• знать риск-класс операции;
• уметь останавливать вызов до побочного эффекта;
• отправлять опасные операции на подтверждение человеком;
• журналировать и решение, и факт исполнения.

Ниже очень практичный шаблон политики для исполнения инструментов:

tools:
  read_kb:
    risk: low
    approval: none
    allowed_roles: ["agent_runtime"]
  create_ticket:
    risk: medium
    approval: manager
    allowed_roles: ["agent_runtime"]
  prod_db_write:
    risk: critical
    approval: security_and_owner
    allowed_roles: []
    environments: ["staging"]

В этом YAML нет ничего “умного”, и именно это хорошо. Контур безопасности любит обозримые правила.

2.1. Шлюз должен знать не только инструмент, но и субъекта¶

Если шлюз валидирует только имя инструмента и аргументы, этого мало. Ему еще нужно понимать, кто именно пытается вызвать возможность.

Минимально полезная модель запроса к шлюзу обычно включает:

• actor_id;
• actor_type;
• tenant_id;
• requested_capability;
• risk_class;
• approval_state.

Тогда шлюз может принимать решения не только по правилу “этот инструмент разрешен”, но и по правилу “этот инструмент разрешен именно этому субъекту и именно в этом контексте”.

Это и есть момент, где идентичность превращается в исполняемую границу доступа, а не остается просто записью в IAM-таблице.²³

3. Подтверждение человеком должно быть нормальным процессом¶

Есть действия, которые агент не должен завершать самостоятельно вообще:

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

Для них нужен не просто переключатель “требуется подтверждение”, а нормальный сценарий подтверждения.

sequenceDiagram
    autonumber
    participant R as Рантайм агента
    participant P as Движок политик
    participant H as Подтверждающий человек
    participant T as Шлюз инструментов
    participant A as След аудита

    R->>P: Запросить рискованное действие
    P-->>R: Требуется подтверждение
    R->>H: Запросить подтверждение с контекстом
    H-->>R: Подтвердить / отклонить
    R->>T: Исполнить только после подтверждения
    T->>A: Сохранить действие и запись подтверждения

Разные продукты будут реализовывать это по-разному, но полезно иметь не один шаблон подтверждения, а несколько. Cloudflare Agents SDK прямо разделяет подтверждение долговечного рабочего процесса, подтверждение для чат-инструментов AI, клиентское подтверждение инструмента, запрос ввода MCP и легкие подтверждения через состояние или WebSocket.¹ Это хорошая практическая подсказка: граница подтверждения должна соответствовать тому, где реально живет побочный эффект.

Если подтверждение относится к долгому рабочему процессу, ему нужен тайм-аут, эскалация и долговечное возобновление. Если это браузерный или клиентский инструмент, рантайм должен понимать, что часть проверки и результата пришла с клиентской границы. Если это запрос ввода MCP, подтверждение похоже не на “да/нет”, а на запрос структурированного ввода с собственной схемой.

Хороший поток подтверждения всегда хранит:

• кто запросил действие;
• какой был класс риска;
• что именно собирались сделать;
• кто подтвердил;
• в какое время;
• были ли переопределены проверочные ворота политики.

4. На выходе тоже нужна защита¶

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

Утечка чаще всего происходит на выходе:

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

Минимальный чеклист выхода:

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

5. Журнал аудита должен быть пригоден для расследования¶

Просто “включить трассировку” недостаточно. Для безопасности тебе нужен след, по которому можно восстановить историю события.

На один рискованный запуск полезно хранить:

• входной идентификатор запроса;
• субъект и арендатор;
• решение политики;
• метаданные сборки подсказки;
• аргументы вызова инструмента в безопасно отредактированном виде;
• записи подтверждений;
• итоговое событие на выходе.

Если после инцидента команда видит только “модель вызвала инструмент X”, расследование уже наполовину проиграно.

5.1. Что именно должно связываться в следе аудита¶

У хорошего следа аудита есть не только события, но и связки между ними:

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

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

По сути, след аудита должен отвечать на четыре вопроса:

1. Кто инициировал действие?
2. Кто разрешил его исполнение?
3. Под какой идентичностью оно реально ушло наружу?
4. Какой побочный эффект или ответ это произвело?

Если на любой из этих вопросов нет ответа, у тебя, скорее всего, уже не след аудита, а просто наблюдаемость без достаточной подотчетности.³

6. Контур безопасности как набор привычек¶

Очень хочется найти одну волшебную библиотеку, которая “сделает безопасность”. Но на практике периметр состоит из набора привычек:

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

Это и есть взрослая безопасность для агентной платформы.

7. Частые ошибки¶

Здесь чаще всего повторяются одни и те же ошибки:

• шлюз обходят ради “временной” интеграции;
• подтверждение запрашивают слишком поздно, когда опасное действие уже почти готово к запуску;
• правила выхода живут в голове команды, а не в явной поверхности контракта;
• след аудита не хранит решение политики, субъекта или контекст подтверждения;
• действия записи и действия чтения описаны одинаково, хотя их риск разный.

8. Что сделать сразу¶

Сначала пройди по короткому списку и отдельно отметь все ответы «нет»:

• Есть ли у агента отдельная модель идентичности?
• Разделены ли доверенные инструкции и недоверенное содержимое?
• Все ли инструменты проходят через шлюз?
• Есть ли список разрешений и проверка аргументов?
• Есть ли поток подтверждения для высокорисковых действий?
• Есть ли фильтрация на выходе?
• Достаточен ли след аудита для расследования?
• Видно ли в трассах, какие проверочные ворота политики сработали?
• Видно ли, какой субъект реально исполнил внешний вызов?

Если на несколько пунктов подряд ответ “нет”, значит эту главу ты открыл очень вовремя.

9. Что делать дальше¶

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

• Глава 3. Контур безопасности и границы доверия
• Глава 5. Зачем агенту память и почему она опасна
• Часть II. Контур безопасности
• Источники