Модули перехвата в Azure SRE Agent

Хуки — это пользовательские контрольные точки, которые перехватывают и управляют поведением агента в ключевые моменты. Используйте перехватчики для принудительного применения контрольных точек качества на ответах агента, использования инструментов аудита и контроля, блокирования опасных операций путем применения политик и предотвращения раннего завершения задач путем проверки результатов работы агента.

Проблема, которую решают перехватчики агента

Агент выполняет задачи автономно, исследуя инциденты, запуская инструменты и формируя ответы. Но автономия без надзора создает риск:

Неполные ответы: агент говорит "готово", прежде чем ответить на все, что вы попросили.
Использование инструментов без аудита: вы не видите, какие инструменты вызывает агент и какие результаты он получает.
Нет применения политик: опасные операции (разрушительные команды, несанкционированные изменения) выполняются без проверки.
Пробелы в качестве: ответы пропускают критически важные сведения, так как нет шага проверки.

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

Как работают перехватчики агента

Хуки — это кастомные контрольные точки, которые вы присоединяете к определенным событиям агента. Когда событие срабатывает, ваш хук оценивает ситуацию и решает, следует ли разрешать или блокировать действие.

Agent about to stop → Stop hook evaluates response → Allow or reject
Agent uses a tool   → PostToolUse hook checks result → Allow, block, or inject context

В настоящее время поддерживаются два хука-события:

Event	Срабатывает, когда	Что можно сделать
Остановить	Агент будет возвращать окончательный ответ	Проверьте полноту, отклоните и принудьте агента продолжать.
PostToolUse	Инструмент успешно завершил выполнение	Аудит использования, блокировка результатов, внедрение дополнительного контекста

Два уровня крючков

Хуки работают на двух уровнях:

Уровень	Где настроить	Объем
Уровень агента	Конструктор → Перехватчики на портале	Применяется ко всему агенту, включая все потоки и все пользовательские агенты
Уровень пользовательского агента	Холст агента → пользовательский агент → управление хуками или с помощью REST API версии 2	Применяется только в том случае, если запускается конкретный пользовательский агент

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

Типы выполнения

Вы можете реализовать хуки с помощью как LLM, так и shell-скрипта:

Тип	Принцип работы	лучше всего подходит для
Подсказка	LLM оценивает запрос и возвращает результат в формате JSON	Нюансная проверка ("Завершен ли этот ответ?")
Command	Скрипт bash или Python выполняется в изолированной среде	Детерминированные проверки, применение политик, аудит

Инструменты оценки как Prompt hooks являются мощными для субъективной проверки — например, чтобы выяснить, отвечает ли ответ на все вопросы пользователя или убедиться, что расследование проведено достаточно тщательно. Они используют заполнитель $ARGUMENTS для получения полного контекста hook. Если $ARGUMENTS в запросе нет, контекст добавляется автоматически. Когда расшифровка беседы доступна, хуки запроса также получают ReadFile и GrepSearch средства, что позволяет LLM анализировать полную историю беседы.

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

Поведение агента с хуками и без них

В следующей таблице сравнивается поведение агента с перехватчиками и без них.

Без крючков	С крючками
Агент решает, когда задача выполнена	Вы определяете, что означает "готово"
Использование инструмента невидимо	Каждый вызов инструмента может быть проверен
Опасные команды выполняются без предупреждения.	Принудительное применение политики блокирует их автоматически
Качество зависит только от разработки запросов	Автоматические контрольные точки качества выявляют недостатки

Хуки не заменяют механизмы безопасности режима выполнения. Вместо этого они дополняют их. Режимы выполнения управляют тем , что может сделать агент. Перехватчики контролируют, насколько хорошо это выполняется, и что происходит с результатами.

До и после добавления перехватчиков агента

Сценарий	До	После
Качество отклика	Агент останавливается, когда считает, что его работа выполнена.	Ваш перехватчик остановки проверяет полноту до того, как ответ достигнет пользователей
Видимость инструментов	Нет журнала аудита выполнения инструмента	Перехватчики PostToolUse логируют и проверяют каждый вызов средства
Применение политик	Опасные команды выполняются без проверки.	Сценарии блокируют `rm -rf`, `sudo` и другие рискованные шаблоны автоматически.
Обеспечение качества	Проектирование запросов — ваш единственный инструмент воздействия	Обработчики на базе LLM оценивают нюансы; скрипты выполняют детерминированные правила.

Настройка хуков агента

Создайте хуки через интерфейс портала:

Перехватчики уровня агента: Перейдите в Builder → Перехватчики → выберите Создать перехватчик.
Перехватчики на уровне пользовательского агента: Перейдите на холст агента → выберите настраиваемый агент → управление перехватчиками.

Пошаговые инструкции см. в разделе Создание хуков и управление ими на портале.

Подсказка

С помощью PUT /api/v2/extendedAgent/agents/{agentName} можно также настроить перехватчики. Формат YAML в следующем разделе показывает полную схему конфигурации. Дополнительные сведения см. в руководстве по API.

Вкладка Agent Canvas YAML отображает формат v1 и не показывает хуки. Используйте страницу хуков в Builder для просмотра и управления хуками.

В следующем примере показана полная конфигурация хука:

api_version: azuresre.ai/v2
kind: ExtendedAgent
metadata:
  name: my_hooked_agent
spec:
  instructions: |
    You are a helpful assistant.
  handoffDescription: ""
  enableVanillaMode: true
  hooks:
    Stop:
      - type: prompt
        prompt: |
          Check if the response ends with "Task complete."
          $ARGUMENTS
          Respond with:
          - {"ok": true} if it does
          - {"ok": false, "reason": "End your response with 'Task complete.'"} if not
        timeout: 30

    PostToolUse:
      - type: command
        matcher: "Bash|ExecuteShellCommand"
        timeout: 30
        failMode: block
        script: |
          #!/usr/bin/env python3
          import sys, json, re

          context = json.load(sys.stdin)
          command = context.get('tool_input', {}).get('command', '')

          dangerous = [r'\brm\s+-rf\b', r'\bsudo\b', r'\bchmod\s+777\b']
          for pattern in dangerous:
              if re.search(pattern, command):
                  print(json.dumps({"decision": "block", "reason": f"Blocked: {pattern}"}))
                  sys.exit(0)

          print(json.dumps({"decision": "allow"}))

Формат отклика перехватчика

Перехватчики должны выводить JSON. Поддерживаются два формата:

Простой формат (рекомендуется для хуков подсказок):

{"ok": true}
{"ok": false, "reason": "Please include more details."}

Расширенный формат (рекомендуется для хуков команд):

{"decision": "allow"}
{"decision": "block", "reason": "Dangerous command detected."}
{"decision": "allow", "hookSpecificOutput": {"additionalContext": "Tool audit logged."}}

Перехватчики команд также могут использовать коды выхода вместо выходных данных JSON:

Код выхода	Поведение
`0` без выходных данных	Разрешить (нет возражений)
`0` с JSON	Анализ JSON для принятия решения
`2`	Всегда блокировать. stderr становится причиной
Other	Использует `failMode` параметр (`allow` или `block`)

Предостережение

Для условий остановки отказ без причины приравнивается к утверждению, и агент останавливается обычным образом. Всегда предоставляйте поле reason при отклонении.

Замечание

Вы можете определить несколько крючков для одного и того же события. Для PostToolUse каждый хук с соответствующим matcher шаблоном работает независимо. Если предоставляется additionalContext несколько перехватчиков, в беседу внедряется контекст последнего перехватчика.

Справочник по конфигурации

В следующей таблице описаны все доступные параметры конфигурации хуков.

Опция	Тип	По умолчанию	Описание
`type`	струна	`prompt`	`prompt` или `command`
`prompt`	струна	(нет)	Текст запроса LLM (требуется для промежуточной обработки запросов). Используйте `$ARGUMENTS` для внедрения контекста.
`command`	струна	(нет)	Команда встроенной оболочки (для перехватчиков команд, взаимоисключающая с `script`).
`script`	струна	(нет)	Многострочный скрипт (для командных хуков, которые взаимоисключаются с `command`).
`matcher`	струна	(нет)	Шаблон regex для имен инструментов (требуется для перехватчиков PostToolUse). `*` соответствует всем инструментам. Шаблоны привязаны как `^(pattern)$` и соответствуют регистру. Пустое или null ничему не соответствует.
`timeout`	int	`30`	Время ожидания выполнения в секундах (должно быть положительным; значения выше 300 помечены во время проверки CLI).
`failMode`	струна	`allow`	Как обрабатывать ошибки хука: `allow` или `block`.
`model`	струна	`ReasoningFast`	Модель для перехватчиков запросов (имя сценария или имя развертывания).
`maxRejections`	int	`3` (агент по умолчанию)	Максимальное количество отказов перед принудительной остановкой. Диапазон: от 1 до 25. Применяется только к перехватчикам типа остановки. Хуки типа 'Stop' команд не имеют неявного ограничения. Если несколько перехватчиков запроса указывают разные значения, используется максимальное значение.

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

Перехватчики получают структурированный контекст JSON о текущем событии. Перехватчики запроса получают контекст через $ARGUMENTS заполнитель в тексте запроса. Перехватчики команд получают контекст в формате JSON stdin.

Для обоих типов хуков поле execution_summary содержит путь к файлу стенограммы беседы (не встроенному содержимому). Для хуков подсказок LLM получает ReadFile и GrepSearch инструменты для доступа к этому файлу. Для командных хуков файл доступен по указанному пути в песочнице.

Общие поля

Все хуки получают следующие поля:

{
  "hook_event_name": "Stop",
  "agent_name": "my_agent",
  "current_turn": 5,
  "max_turns": 50,
  "execution_summary": "/path/to/transcript.txt"
}

Остановка полей хука

Стоп-перехватчики получают дополнительные поля о конечных выходных данных агента.

{
  "final_output": "Here is my response...",
  "stop_hook_active": false,
  "stop_rejection_count": 0
}

Поля хуков PostToolUse

Хуки PostToolUse получают дополнительные поля о выполнении инструмента.

{
  "tool_name": "ExecutePythonCode",
  "tool_input": { "code": "print(2+2)" },
  "tool_result": "4",
  "tool_succeeded": true
}

Уровни моделей

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

Уровень	лучше всего подходит для	Компромисс
Reasoning	Сложные проверки политики, многоэтапная проверка, нюансы проверки соответствия требованиям	Высокое качество, более высокая стоимость и задержка
Быстрое рассуждение (по умолчанию)	Большинство хуков, валидация ответов, аудиторские проверки, обеспечение безопасности	Качественное рассуждение с низкой задержкой
Категория общего назначения	Простые проверки формата, базовая проверка соответствия	Балансировка точности, стоимости и скорости
Быстрый	Упрощенные проверки, проверка присутствия, проверка формата	Наименьшая стоимость, самый быстрый ответ
Длинный контекст	Хуки, обрабатывающие большие объёмы выходных данных, полный анализ документа, подробные результаты работы инструментов	Обрабатывает более крупные входные данные, более высокие затраты

Подсказка

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

Ограничения

Следующие ограничения применяются к хукам агента.

Ограничение	Ценность
Размер скрипта	Максимум 64 КБ
Таймаут	От 1 до 300 секунд
Максимальное количество отклонений (перехватчики запроса)	От 1 до 25 (по умолчанию: 3)
Поддерживаемые сценарии шебанги	`#!/bin/bash`, `#!/usr/bin/env python3`
Среда выполнения скрипта	Интерпретатор изолированного кода

Пример: аудит использования всех инструментов

Следующие перехватчики PostToolUse регистрируют каждый вызов средства и добавляют сообщение контекста аудита:

hooks:
  PostToolUse:
    - type: command
      matcher: "*"
      timeout: 30
      failMode: allow
      script: |
        #!/usr/bin/env python3
        import sys, json

        context = json.load(sys.stdin)
        tool_name = context.get('tool_name', 'unknown')

        print(f"Tool used: {tool_name}", file=sys.stderr)

        output = {
            "decision": "allow",
            "hookSpecificOutput": {
                "additionalContext": f"[AUDIT] Tool '{tool_name}' was executed."
            }
        }
        print(json.dumps(output))

Поле additionalContext добавляется как сообщение пользователя в беседу, предоставляя агенту видимость аудита.

Пример: Необходим маркер завершения

Следующий хук остановки отклоняет ответы, которые не заканчиваются на «Задача завершена».

hooks:
  Stop:
    - type: command
      timeout: 30
      failMode: allow
      script: |
        #!/bin/bash
        CONTEXT=$(cat)
        FINAL_OUTPUT=$(echo "$CONTEXT" | jq -r '.final_output // empty')

        if [[ "$FINAL_OUTPUT" == *"Task complete."* ]]; then
          exit 0
        else
          echo "Please end your response with 'Task complete.'" >&2
          exit 2
        fi

Лучшие практики

При настройке хуков агента:

Всегда предоставьте причину при отклонении. Относиться к отказам без причин как к одобрениям.
Используйте подходящие тайм-ауты: длительные хуки замедляют выполнение агента.
Корректная обработка ошибок: используйте , если не требуется строгое принудительное применение.
Будьте конкретными с сопоставлениями: чрезмерно широкие сопоставления PostToolUse могут вызвать проблемы с производительностью.
Тщательно тестируйте перехватчики: перехватчики, которые всегда отклоняют, могут вызвать циклы (ослабленные maxRejections).
Вход в stderr: используйте stderr для отладки выходных данных. Система анализирует stdout в качестве результата хука.

Попробуйте использовать перехватчики агента самостоятельно

На следующем снимке экрана показан хук остановки в действии. Агент изначально реагирует лишь "4", но хук отклоняет ответ, так как маркер завершения отсутствует. Затем агент продолжает и добавляет маркер.

Начало работы

Ресурс	Что вы узнаете
Создание хуков и управление ими (портал)	Создавайте хуки визуально в интерфейсе портала — без вызовов API.
Настройка хуков агента (API)	Настройте хуки с помощью REST API v2 и YAML.

Функциональность	Как она связана
Режимы выполнения	Перехватчики дополняют элементы управления безопасностью в режиме выполнения программ. Режимы управляют запуском, хуки управляют тем, насколько хорошо это работает.
Средства Python	Создайте пользовательские средства, которые перехватчики могут проверять и валидировать.

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2026-06-04