Учебное пособие: Конфигурирование перехватчиков агента (API) в агенте Azure SRE

Подсказка

Предпочитаете интерфейс портала? Теперь вы можете создавать хуки и управлять ими непосредственно на портале без использования REST API. Портал предоставляет визуальные формы и редактор кода. Команды curl не требуются.

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

Предполагаемое время: 15 минут

Замечание

Хуки уровня агента и хуки уровня пользовательского агента: В этом руководстве создаются хуки для кастомного агента (хуки на уровне кастомного агента). Эти перехватчики активируются только во время работы этого конкретного кастомного агента.

Чтобы создать перехватчики уровня агента, которые применяются ко всему агенту (все потоки, все настраиваемые агенты), используйтеперехватчики> на портале.

Уровень	Как создать	Объем
Уровень агента	Портал: крючки построителя >	Применяется ко всем потокам и пользовательским агентам
Уровень пользовательского агента	REST API (это руководство) или Portal: Agent Canvas > пользовательский агент > Управление перехватчиками	Применяется только к одному пользовательскому агенту

В этом руководстве вы узнаете, как:

Создание пользовательского агента с хуком остановки с помощью REST API
Проверка поведения тестового хука на площадке тестирования портала
Добавьте перехватчик PostToolUse для аудита использования инструментов
Блокировать опасные команды с помощью хука политики

Необходимые условия

Агент Azure SRE в состоянии выполнения
curl для вызова REST API
Вход в Azure CLI (az login) для получения маркера доступа

Общие сведения о формате API перехватчика

В этом руководстве используется REST API v2 для создания хуков в пользовательском агенте. Вкладка редактора YAML в портале показывает формат v1 и не отображает хуки, настроенные через API, но эти хуки по-прежнему активны. Их можно проверить на странице Построителе>Перехватчики или на тестовой площадке.

Подсказка

Когда следует использовать API и портал:

Портал (крючки Builder >): лучше всего подходит для перехватчиков уровня агента в визуальном формате. Код не требуется.
API (в этом руководстве): Оптимально подходит для хуков на уровне пользовательского агента, конвейеров CI/CD или программного управления.

Поиск URL-адреса API агента

Базовый URL-адрес API агента следует этому шаблону:

https://{agent-name}--{hash}.{hash}.{region}.azuresre.ai

Чтобы найти его, выполните приведенные далее действия.

Откройте sre.azure.com и выберите агент.
На левой боковой панели выберите Builder>Панель агента.
Откройте средства разработчика браузера (F12 или щелкните правой кнопкой мыши > "Проверить").
Перейдите на вкладку "Сеть" , отфильтруйте по api и найдите запросы на URL-адрес, заканчивающийся .azuresre.ai.
Базовый URL-адрес — это все, прежде чем /api/....

Также проверьте атрибут src на вкладке Элементы. Найдите элемент, у которого <iframe>src начинается с https://{agent-name}--.

Получите токен доступа.

Выполните следующую команду, чтобы получить маркер доступа для API агента SRE:

TOKEN=$(az account get-access-token \
  --resource <RESOURCE_ID> \
  --query accessToken -o tsv)

Создайте пользовательского агента с использованием Stop hook.

На этом шаге создается пользовательский агент my_hooked_agent, у которого есть перехватчик остановки, проверяющий, заканчивается ли ответ на === RESPONSE COMPLETE ===. Если маркер отсутствует, хук отклоняет ответ и сообщает агенту добавить маркер.

AGENT_URL="https://your-agent--xxxxxxxx.yyyyyyyy.region.azuresre.ai"

curl -X PUT "${AGENT_URL}/api/v2/extendedAgent/agents/my_hooked_agent" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d @- << 'EOF'
{
  "name": "my_hooked_agent",
  "properties": {
    "instructions": "You are a helpful assistant. Be concise.",
    "handoffDescription": "",
    "handoffs": [],
    "enableVanillaMode": true,
    "hooks": {
      "Stop": [
        {
          "type": "prompt",
          "prompt": "Check the agent response below.\n\n$ARGUMENTS\n\nDoes it end with === RESPONSE COMPLETE ===?\nIf yes: {\"ok\": true}\nIf no: {\"ok\": false, \"reason\": \"Add === RESPONSE COMPLETE === at the end.\"}",
          "timeout": 30
        }
      ]
    }
  }
}
EOF

Вы получаете HTTP 202 Accepted с полной конфигурацией агента в тексте ответа.

В следующем примере показана та же конфигурация в формате YAML версии 2 для справки:

api_version: azuresre.ai/v2
kind: ExtendedAgent
metadata:
  name: my_hooked_agent
spec:
  instructions: |
    You are a helpful assistant. Be concise.
  handoffDescription: ""
  enableVanillaMode: true
  hooks:
    Stop:
      - type: prompt
        prompt: |
          Check the agent response below.

          $ARGUMENTS

          Does it end with === RESPONSE COMPLETE ===?
          If yes: {"ok": true}
          If no: {"ok": false, "reason": "Add === RESPONSE COMPLETE === at the end."}
        timeout: 30

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

Перехватчик остановки вычисляет ответ агента, прежде чем он возвращается пользователю:

Заменяет $ARGUMENTS на контекст хука JSON, который содержит финальный ответ агента.
LLM оценивает запрос и возвращает {"ok": true} или {"ok": false, "reason": "..."}.
Если отклонено, агент продолжает работать после включения причины в сообщение пользователя.
После трех отклонений (по умолчанию) агент останавливается.

Тестирование хука в портале

Выполните следующие действия, чтобы проверить перехватчик остановки:

Перейдите к вашему агенту на портале и выберите Построитель>Полотно агента.
Выберите переключатель тестовой площадки.
Выберите раскрывающийся список subagent/Tool , найдите my_hooked_agent и выберите "Применить".
Введите What is 2+2? в чате и нажмите кнопку "Отправить".

Посмотрите, что происходит:

Агент сначала отвечает с 4.
Крючок остановки оценивает и отклоняет ответ (без маркера завершения).
Отображается шаг мыслительного процесса, где агент продолжает двигаться.
Появится окончательный ответ: 4 === RESPONSE COMPLETE ====.

Крючок работал. Это заставило агента добавить маркер перед остановкой.

Добавьте перехватчик PostToolUse для аудита

Добавьте перехватчик PostToolUse, который регистрирует каждый инструмент, который использует агент. Обновите того же агента, отправив новый PUT запрос с обоими хуками:

curl -X PUT "${AGENT_URL}/api/v2/extendedAgent/agents/my_hooked_agent" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d @- << 'EOF'
{
  "name": "my_hooked_agent",
  "properties": {
    "instructions": "You are a helpful assistant. Be concise.",
    "handoffDescription": "",
    "handoffs": [],
    "enableVanillaMode": true,
    "hooks": {
      "Stop": [
        {
          "type": "prompt",
          "prompt": "Check the agent response below.\n\n$ARGUMENTS\n\nDoes it end with === RESPONSE COMPLETE ===?\nIf yes: {\"ok\": true}\nIf no: {\"ok\": false, \"reason\": \"Add === RESPONSE COMPLETE === at the end.\"}",
          "timeout": 30
        }
      ],
      "PostToolUse": [
        {
          "type": "command",
          "matcher": "*",
          "timeout": 30,
          "failMode": "allow",
          "script": "#!/usr/bin/env python3\nimport sys, json\ncontext = json.load(sys.stdin)\ntool = context.get('tool_name', 'unknown')\nprint(json.dumps({'decision': 'allow', 'hookSpecificOutput': {'additionalContext': f'[AUDIT] {tool} executed.'}}))"
        }
      ]
    }
  }
}
EOF

matcher: "*" означает, что этот перехватчик выполняется для каждого вызова инструмента. Скрипт записывает имя инструмента и внедряет [AUDIT] сообщение в беседу.

Чтобы протестировать хук, задайте агенту вопрос, который активирует инструмент (например, "Выполнить echo hello").

Блокировать опасные команды

Добавьте второй перехватчик PostToolUse, который блокирует rm -rf, sudo и chmod 777:

PostToolUse:
  # Audit hook (runs for all tools)
  - type: command
    matcher: "*"
    timeout: 30
    failMode: allow
    script: |
      #!/usr/bin/env python3
      import sys, json
      context = json.load(sys.stdin)
      tool = context.get('tool_name', 'unknown')
      print(json.dumps({"decision": "allow",
        "hookSpecificOutput": {"additionalContext": f"[AUDIT] {tool} executed."}}))

  # Policy hook (only for shell tools)
  - 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', '')
      for pattern in [r'\brm\s+-rf\b', r'\bsudo\b', r'\bchmod\s+777\b']:
          if re.search(pattern, command):
              print(json.dumps({"decision": "block", "reason": f"Blocked: {pattern}"}))
              sys.exit(0)
      print(json.dumps({"decision": "allow"}))

Основные отличия от контрольной точки аудита:

matcher: "Bash|ExecuteShellCommand" выполняется только для утилит командной оболочки (шаблон привязан как ^(Bash|ExecuteShellCommand)$).
failMode: block блокирует результат средства, если сам скрипт аварийно завершает работу (строгий режим).
Возвращается "block" с причиной, когда обнаружен опасный шаблон.

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

Перехватчики запросов и перехватчики команд используют различные форматы отклика.

Подсказочные зацепки

Перехватчики запроса возвращают простой КОД JSON:

{"ok": true}

{"ok": false, "reason": "Please fix X."}

Командные крючки

Перехватчики команд возвращают развернутый JSON:

{"decision": "allow"}

{"decision": "block", "reason": "Dangerous command."}

{"decision": "allow", "hookSpecificOutput": {"additionalContext": "Audit note."}}

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

Код выхода	Поведение
`0` без выходных данных	Allow
`0` с JSON	Анализ JSON
`2`	Блокировать (stderr становится причиной)
Other	Возвращается в `failMode`

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

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

Verify

После настройки и проверки хуков убедитесь, что выполняются следующие условия:

Вы настраиваете хуки на уровне пользовательского агента с помощью REST API v2. Они применяются только к пользовательскому агенту.
Вы создаете перехватчики уровня агента в системе > хуков Builder. Они применяются ко всему агенту.
Причина останова стоп-хука заключается в добавлении маркера === RESPONSE COMPLETE === перед остановкой агента.
Перехватчик аудита PostToolUse регистрирует сообщения для вызовов [AUDIT] инструментов.
Механизм политики блокирует опасные команды, такие как rm -rf и sudo.

Troubleshooting

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

Проблема.	Решение
Хуки не отображаются на вкладке YAML портала	Ожидается, что вкладка YAML отображает только версию 1. Пользовательские хуки уровня агента, созданные с помощью API, активны и видны в Builder>Hooks или в Playgrounds.
`Unsupported kind: ExtendedAgent`	Используйте конечную точку версии 2: `PUT /api/v2/extendedAgent/agents/{name}`.
`Handoffs cannot be null`	Добавьте `"handoffs": []` к полезной нагрузке JSON.
Крюк не оказывает никакого эффекта	При отклонении добавьте поле `reason`. Без него отказ рассматривается как утверждение.
Агент зацикливается бесконечно	Ниже `maxRejections` (по умолчанию: 3, диапазон: 1–25).

Следующий шаг

Узнайте о перехватчиках агента.

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

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

Last updated on 2026-03-28