チュートリアル: ポータルでフックを作成および管理する

このチュートリアルでは、ポータルを使用して 2 つのガバナンスフックを作成します。データ書式設定を適用する 停止フック (太字のヘッダーを持つマークダウンテーブル) と、危険なシェルコマンドをブロックする PostToolUse フック です。 フックは、エージェントレベル (すべてのスレッドとサブエージェントに適用) とサブエージェントレベル (1 つの特定のサブエージェントに適用) の両方で構成します。

推定時間: 10 分

このチュートリアルでは、以下の内容を学習します。

応答の書式設定を検証する Stop フックを作成する
危険なシェルコマンドをブロックする PostToolUse フックを作成する
特定のサブエージェントにフックを追加する
個々のスレッドでフックのアクティブ化を管理する

前提条件

実行中の状態の Azure SRE エージェント
SRE Agent リソースに対する共同作成者以上のロール

ヒント

REST API チュートリアルを使用して作成したフックは、ポータル UI に自動的に表示されます。何も再構成せずに視覚的に管理できます。

ポータル内でのフックの場所を把握する

フックは2つのレベルで動作します。この違いを理解することは、アーキテクチャの重要な概念です。

レベル	ポータル内の場所	Scope	次の場合に使用します。
エージェントレベル	ビルダー>フックス	エージェント全体、すべてのスレッド、およびすべてのサブエージェントに適用されます	"すべてのツール呼び出しを監査する" や "どこでも危険なコマンドをブロックする" などのエージェント全体のポリシーが必要です
サブエージェントレベル	サブエージェントビルダー> select subagent >Manage Hooks	特定のサブエージェントが実行されている場合にのみ適用されます	"このサブエージェントの出力形式を検証する" など、1 つのサブエージェントに合わせたフックが必要です

ヒント

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

エージェントレベルのフックを作成する

エージェントレベルのフックは、すべてのスレッドとすべてのサブエージェントを含め、エージェント全体に適用されます。活動するタイミングを制御する活性化モードがあります。

フックページを開く

フックページに移動するには、次の手順に従います。

sre.azure.com に移動し、エージェントを選択します。
サイドバーで[ビルダー]を展開 します。
フックを選択します。

フックの見出しには説明があり、フックを作成するボタンと、空のデータグリッド（または既存のフックの一覧）が表示されます。

ストップフックを作成する

ストップフックは、エージェントが最終的な応答を戻すときに発火します。これを使用して、応答の品質を検証し、書式設定ルールを適用します。

[ フックの作成] を選択します。

フォームのフィールドに入力してください。

フィールド	価値
名前	`require-table-format`
イベントの種類	止まれ
アクティベーションモード	いつも
説明	応答が太字のヘッダーを持つマークダウンテーブルとして構造化データを表示することを確認します

[ フックの定義] で、[ フックの種類 ] を [プロンプト] に設定したままにしておきます。
モデルを [推論速度] に設定したままにします (既定値)。

プロンプト エディターで、次のテキストを入力します。

Check the agent response below.

$ARGUMENTS

Does the response present any structured data (lists of items, comparisons, metrics) as a markdown table with **bold** column headers?
If no structured data is present, approve.
If structured data IS present as a table with bold headers: {"ok": true}
If structured data is present but NOT formatted as a table: {"ok": false, "reason": "Reformat the structured data as a markdown table with **bold** column headers."}

タイムアウト (秒) は 30、失敗モードは Allow、最大拒否数は 3 のままにします。
保存を選びます。

ダイアログが閉じ、成功通知が表示されます。フックは、イベントの種類が Stop と Activation Always のデータグリッドに表示されます。

ヒント

$ARGUMENTS プレースホルダーは、フックコンテキスト (エージェントの最終的な応答を含む) をプロンプトに挿入します。 LLM は、応答が条件を満たしているかどうかを評価し、{"ok": true}承認または{"ok": false, "reason": "..."}拒否を返します。 3 回の拒否 (既定値) の後、エージェントは停止します。

停止フックをテストする

停止フックが正しく動作することを確認するには、次の手順に従います。

サイドバーで[チャット]を選択 します。
「 マイクロサービスを構築するための Python と Go の長所と短所を比較 する」と入力し、[ 送信] を選択します。
エージェントの応答を確認します。
- エージェントは最初にプレーンテキスト比較で応答します。
- Stop フックは、データがテーブル内にないため、応答を評価して拒否します。
- エージェントは、応答を太字のヘッダーを含むマークダウンテーブルとして再フォーマットします。

最後の応答では、次の例のような書式設定されたテーブルとして比較が表示されます。

言語	長所	短所
Python	迅速な開発、豊富なエコシステム	実行速度が遅い、GIL の制限事項
Go	高速コンパイル、コンカレンシーの組み込み	** 小さいエコシステム、詳細なエラー処理

PostToolUse フックを作成する

PostToolUse フックは、ツールの実行が完了した後に発生します。ツールの使用状況を監査したり、危険なコマンドをブロックしたり、追加のコンテキストを追加したりするために使用します。

Builder>Hooks に戻ります。
[ フックの作成] を選択します。

フォームに入力します。

フィールド	価値
名前	`block-dangerous-commands`
イベントの種類	ツール使用後
アクティベーションモード	いつも
説明	シェルコマンドで rm -rf、sudo、chmod 777 をブロックします
フックの種類	命令
ツールマッチャー	`Bash\\|ExecuteShellCommand`

スクリプト言語として Python を選択します。

スクリプト エディターで、次のスクリプトを入力します。

#!/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"}))

[失敗] モードを [ブロック] に設定します (スクリプトがクラッシュした場合、ツールの結果はブロックされます)。
保存を選びます。

両方のフックが Hooks データグリッドに表示されるようになりました。

注

ツールマッチャー フィールドは正規表現を使用します。 Bash|ExecuteShellCommand は、正確に "Bash" または "ExecuteShellCommand" という名前のツールと一致します (パターンは ^(Bash|ExecuteShellCommand)$として固定されます)。 *を使用して、すべてのツールを照合します。

PostToolUse フックをテストする

PostToolUse フックが正しく動作することを確認するには、次の手順に従います。

サイドバーで[チャット]を選択 します。
安全なコマンド "Run echo hello" を実行するようにエージェントに依頼します。フックによってこのコマンドが許可されます。
"run rm -rf /tmp/test" という危険なコマンドを実行するようにエージェントに依頼します。 hook はこのコマンドをブロックします。

セーフコマンドは正常に実行されます。危険なコマンドがブロックされ、エージェントは理由を説明するメッセージを受け取ります。

エージェントレベルのフックを編集および削除する

フックデータグリッドから既存のフックを変更または削除できます。

編集: データグリッド内の任意のフック行の編集アイコンを選択し、フィールドを変更して、[ 保存] を選択します。
削除: 削除するフックの横にあるチェックボックスをオンにし、ツールバーの [ 削除 ] を選択して確定します。

データグリッドには、変更がすぐに反映されます。

サブエージェントレベルのフックを作成する

サブエージェントレベルのフックは、サブエージェントの定義で直接構成します。これらは、メインエージェントやその他のサブエージェントではなく、その特定のサブエージェントが実行されている場合にのみ適用されます。

サブエージェントフックパネルを開く

特定のサブエージェントのフック構成にアクセスするには、次の手順に従います。

サイドバーで[ ビルダー ]を展開し、[ サブエージェントビルダー]を選択します。
既存のサブエージェントを選択して編集するか、[ 作成 ] を選択して新しいサブエージェントを開始します。
サブエージェントフォームで、 Hooks セクションまで下にスクロールします。
[ フックの管理] を選択します。

サイドパネルが開き、[停止] セクションと [ツール使用後] セクションが表示されます。フックが構成されていない場合は、ガイダンステキストを含む空の状態が表示されます。

サブエージェントにフックを追加する

次の手順では、このサブエージェントが常に概要セクションで応答するように Stop フックを追加します。

[ フックの管理 ] パネルで、パネルの下部にある [ フックの追加 ] を選択します。

ダイアログで、フックフォームに入力します。

フィールド	価値
イベントの種類	止まれ
フックの種類	プロンプト
プロンプト	`Check the response below. $ARGUMENTS Does it include a clear summary section at the end? If yes: {"ok": true} If no: {"ok": false, "reason": "Add a Summary section at the end of your response."}`
タイムアウト (秒)	30
失敗モード	許可する
最大拒否数	3

フックで [保存] を選択します 。
サブエージェントの [作成 ] (または [保存]) を選択して、完全な構成を保存します。

フックは、[フックの管理 ] パネルの [停止 ] セクションに表示されます。サブエージェントフォームには、ボタンに [フックの管理] (1) が表示されます。

ヒント

サブエージェントレベルのフックをテストするには、 サブエージェントビルダーに移動し、[ テストプレイグラウンド ] ビューを選択し、ドロップダウンからサブエージェントを選択して、質問を入力します。フックは、この特定のサブエージェントが呼び出されたときにのみ実行されます。

スレッドごとのフックの管理

[常にアクティブ化] を使用したエージェントレベルのフックは、既定ですべての会話でアクティブになります。スレッドごとに オンデマンド アクティブ化を使用してフックを手動でアクティブ化する必要があります。

会話のフックを切り替える

特定のスレッドでフックをアクティブ化または非アクティブ化するには、次の手順に従います。

チャット スレッドを開きます。
チャットフッターの [ + ] ボタンを選択します。
[ フックの管理] を選択します。
現在のスレッドのフックのオン/オフを切り替えます。

一時的にAlwaysフックを非アクティブ化することができます。オンデマンド フックは 、必要に応じてアクティブ化できます。必要なシステムフックを切り替えることはできません。

フックの変更は、現在のスレッドですぐに有効になります。

Troubleshooting

次の表に、ポータルでフックを作成および管理するときの一般的な問題と解決策を示します。

問題	ソリューション
サイドバーにフックページが表示されない	フックページがビルダーの下に表示されます。エージェントが実行中の状態であることを確認します。このオプションが表示されない場合は、サポートにお問い合わせください。
"フック名が必要です"	文字、数字、ハイフン、アンダースコアのみを使用して名前を入力します。
名前は文字、数字、ハイフン、アンダースコアのみを含む必要があります。	フック名から特殊文字を削除します。
フック名は system__ から始めることはできません	`system__` プレフィックスは、システムフック用に予約されています。別の名前を選択してください。
"PostToolUse フックにはツールマッチャーが必要です"	PostToolUse フックには正規表現マッチャーが必要です。 `*`を使用して、すべてのツールを照合します。
フックが起動しない	エージェントレベルのフックについては、アクティブ化モードを確認します。オンデマンドフックは、スレッドごとにアクティブ化する必要があります。サブエージェントレベルのフックの場合は、サブエージェントが呼び出されていることを確認します。
フックを停止すると、すべてが承認されます	拒否時にプロンプトから `{"ok": false, "reason": "..."}` が返されることを確認します。 `reason`のない拒否は承認として扱われます。
スクリプトエラーによるアクションのブロック	[ 失敗モード ] を [ 許可 ] に設定して、開発中の優雅な劣化を可能にします。運用環境でブロックに切り替えます。

次のステップ

エージェントフックについて

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-03-27