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

現在、次の 2 つのフック イベントがサポートされています。

2つのレベルのフック

フックは次の 2 つのレベルで動作します。

両方のレベルが共存できます。 エージェント レベルのフックとカスタム エージェント レベルのフックの両方が同じイベントと一致する場合は、 両方とも実行されます。 エージェント レベルのフックが最初に起動します。

実行の種類

フックは、LLM またはシェル スクリプトを使用して実装できます。

プロンプト フック は、応答がすべてのユーザーの懸念に対処しているかどうかを確認したり、調査が十分に行われたかどうかを確認したりするなど、主観的な評価に強力です。 $ARGUMENTS プレースホルダーを使用して、完全なフック コンテキストを受け取ります。 $ARGUMENTSがプロンプトに存在しない場合、コンテキストは自動的に追加されます。 会話のトランスクリプトが使用可能になると、プロンプトフックも ReadFile および GrepSearch のツールを受け取り、LLM は完全な会話履歴について理由をつけることができます。

コマンド フック は、応答に必要なマーカーが含まれていることの検証、危険なコマンドのブロック、外部システムへのツールの使用状況のログ記録など、決定的なチェックに適しています。

このアプローチの違い

次の表では、フックの有無に関するエージェントの動作を比較します。

フックは実行モードの安全コントロールを置き換えるのではなく、補完します。 実行モードは、エージェントが 実行できる操作 を制御します。 フックは、それが どれだけうまく 機能し、結果で 何が起こるかを 制御します。

前と後

フックの構成

フックを作成する最も簡単な方法は、ポータル UI を使用することです。

1. エージェント レベルのフック:[Builder → Hooks] に移動→、[フックの作成] を選択します。
2. カスタム エージェント レベルのフック:[エージェント キャンバス] に移動→、カスタム エージェント→フックの管理を選択します。

次の例は、完全なフック構成を示しています。

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 を出力する必要があります。 2 つの形式がサポートされています。

単純な形式 (プロンプト フックに推奨):

{"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 出力の代わりに終了コードを使用することもできます。

構成のリファレンス

次の表では、使用可能なすべてのフック構成オプションについて説明します。

フック コンテキスト スキーマ

フックは、現在のイベントに関する構造化された JSON コンテキストを受け取ります。 プロンプト フックは、プロンプト テキストの $ARGUMENTS プレースホルダーを介してコンテキストを受信します。 コマンド フックは、stdinの JSON としてコンテキストを受け取ります。

どちらの種類のフックでも、 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
}

制限

エージェント フックには、次の制限が適用されます。

例: すべてのツールの使用状況を監査する

次の 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

ベスト プラクティス

エージェント フックを構成するときは、次のガイドラインに従います。

1. 拒否する場合は、常に理由を指定してください。 理由なく却下を承認として扱います。
2. 適切なタイムアウトを使用する: 実行時間の長いフックにより、エージェントの実行速度が低下します。
3. エラーを適切に処理する: 厳密な強制が必要な場合を除き、 failMode: allow を使用します。
4. マッチャーに固有にする: 広範な PostToolUse マッチャーは、パフォーマンスの問題を引き起こす可能性があります。
5. フックを徹底的にテストする: 常に拒否するフックはループを引き起こす可能性があります ( maxRejectionsによって軽減されます)。
6. stderr にログを記録する: 出力のデバッグに stderr を使用します。 システムは、フックの結果として stdout を解析します。

実際に試してみる

次のスクリーンショットは、停止フックの動作を示しています。 エージェントは最初は "4" だけで応答しますが、完了マーカーがないため、フックは応答を拒否します。 エージェントは続行し、マーカーを追加します。

概要

関連するコンテンツ