管理推論フック

Inference hooksを設定する

Copy page



Claude Enterprise組織でInference hooksを許可し、AIセキュリティサーバーを接続して、適用、障害時の処理、ロールアウトを制御します。

Inference hooksは、組織からのプロンプトを、選択した「AI security server」（AIセキュリティサーバー）に送信します。そして、Claudeが処理する前に、各リクエストを許可または拒否の「verdict」（判定）が返るまで保留します。このページでは、機能の有効化、サーバーの接続、適用の制御について順を追って説明します。Inference hooksの概要と使用すべき場面については、Inference hooksの概要を参照してください。AIセキュリティサーバー自体を構築するには、Inference hooks統合を開発するを参照してください。

始める前に

次のものが必要です。

• claude.aiでのorganization:manage権限。この権限を持つのはOwnerロールとPrimary ownerロールのみで、Adminロールにはありません。
• 判定リクエストを受け付けるAIセキュリティサーバーのHTTPSエンドポイント。ポート443のhttps:// URLで、パブリックにルーティング可能なホスト上にあり、リダイレクトなしで到達できる必要があります。リバーストンネルのホスト（ngrokや同様のトンネルサービス）はサポートされていません。Anthropicのネットワークポリシーによってブロックされるためです。トンネル経由でテストせず、自分が管理するドメインでサーバーをホストしてください。ホスティング要件の全体、およびサーバーの構築方法と署名付きリクエストの検証方法については、Inference hooks統合を開発するを参照してください。

Inference hooksをセットアップする

適用状態は3つあります。off（Enforce verdictsがオフ：AIセキュリティサーバーには一切接続されず、プロンプトは検査されません）、shadow（Enforce verdictsがオンで、ModeがShadow modeに設定されている：AIセキュリティサーバーはプロンプトを受信して判定を返しますが、何もブロックされません）、enforcing（Enforce verdictsがオンで、ModeがAllow the requestまたはBlock the requestに設定されている：拒否によってリクエストがブロックされます）です。以下の手順では、新しい設定をoffからenforcingまで進めます。

1. 1

   組織でInference hooksを許可する

   claude.ai > Organization settings > Data and privacyに移動し、Inference hooksセクションを見つけます。Allow for your organizationをオンにします。

   これをオンにするとInference hooksの設定ページが利用可能になり、Enforce verdictsは常に強制的にオフになります。そのため、機能を許可しただけで検査が開始されることはありません。以前に適用がオンになっていた設定であっても、最後の手順でEnforce verdictsを再びオンにするまでは検査されないままです。

2. 2

   Inference hooksの設定ページを開く

   引き続きData and privacyで、Inference hooksセクションを開いてInference hooksの設定ページに移動します。このページは設定ナビゲーションの独立した項目ではなくData and privacyの下にあるため、パンくずリストはData and privacy / Inference hooksと表示されます。エンドポイントを保存するまで、ページにはプロンプトがまだ検査されていないという警告が表示され、Enforce verdictsはRequires endpointバッジ付きでオフのままです。

3. 3

   エンドポイントを設定する

   ConfigureをクリックしてSet up endpointダイアログを開き、Endpoint URLを入力します。これは判定リクエストを受信するhttps:// URLです。https:// URLのみが受け付けられます。

   この時点でダイアログが求めるのはこれだけです。カスタムリクエストヘッダーは手順5で、障害時の処理は手順6で設定します。Nextをクリックして保存します。エンドポイントが保存されると、ボタンの表示はEditになります。

4. 4

   署名シークレットを保管する

   最初の保存時に「webhook signing secret」（Webhook署名シークレット）が生成され、一度だけ表示されます。Nextをクリックする前にコピーして安全に保管してください。シークレットは後から取得できず、ローテーションのみが可能です。

   AIセキュリティサーバーはこのシークレットを使用して、次の手順の接続テストを含め、受信するすべてのリクエストの署名を検証します。検証手順については、署名を検証するを参照してください。

5. 5

   リクエストヘッダーを追加して接続をテストする

   署名シークレットのダイアログでNextをクリックすると、エンドポイントのダイアログが再び開き、さらに2つのコントロールが表示されます。

   • Custom request headers： すべての判定リクエストとともに送信される最大16個の静的ヘッダーで、AIセキュリティサーバーが呼び出し元を認証できるようにします。ヘッダーの値は暗号化されて保存され、二度と表示されません。保存後はヘッダー名のみが表示されます。値は書き込み専用であるため、ヘッダーへの変更を保存するにはすべての値を再入力する必要があります。エンドポイントURLを変更すると、認証情報が新しい宛先に送信されないよう、保存されているすべてのヘッダー値がクリアされます。URLを変更した後は再入力してください。ヘッダー名には標準的なHTTPトークン文字を使用し、_ではなく-を使用する必要があります。また、予約名（Content-*やHostなどのリクエストフレーミングヘッダー、プロキシおよびCookieヘッダー、X-Forwarded-*などのクライアントアドレスヘッダー、webhook-*署名ヘッダー、X-Anthropic-*プレフィックス）と衝突してはなりません。値は印字可能なASCIIである必要があります。
   • Test connection： Claudeは、保存済みの値ではなく、現在フォームに入力されているURLとヘッダーに合成テストプロンプトを送信します。そのため、テストの前に保存済みのヘッダー値を再入力してください。成功すると、AIセキュリティサーバーがテストプロンプトに対して許可と拒否のどちらの判定を返したかが結果に表示されます。これにより、適用を開始する前に、すべてを拒否するデフォルト設定に気付くことができます。

   Saveをクリックして、入力したヘッダーを保存します。

   よくある失敗結果：

   結果	確認事項
   URL rejected	URLが構造チェックに失敗しました。ポート443上のhttps:// URLを使用してください。
   Private or internal IP	URLのホストがプライベートまたは内部IPアドレス、IPv6アドレス、またはlocalhostです。パブリックにルーティング可能なホストを使用してください。
   Timeout	AIセキュリティサーバーがタイムアウト内に判定を返しませんでした。
   Transport error	DNS解決、TLSハンドシェイク、または接続が失敗したか、ホスト名がプライベートアドレスに解決されました。
   Non-200 status	AIセキュリティサーバーが200以外のステータスで応答しました。判定はHTTP 200で返す必要があります。リダイレクトは追跡されず、失敗として扱われます。
   Unparseable response	AIセキュリティサーバーは応答しましたが、本文が有効な判定ではありません。
   Signing secret required	組織に署名シークレットがないため、テストは署名なしで送信されることになります。Request signingの下にあるGenerate secretをクリックしてから、再度テストしてください。

6. 6

   障害時の処理とタイムアウトを選択する

   Failure handlingの下でModeを設定し、AIセキュリティサーバーに到達できない場合や判定がタイムアウトした場合の動作を選択します。

   • Block the request： AIセキュリティサーバーが判定を返せない場合に推論を停止します（「fail closed」（フェイルクローズ））。
   • Allow the request： 検査なしでリクエストをモデルに進めます（「fail open」（フェイルオープン））。

   ドロップダウンの3番目のオプションであるShadow modeは、障害時のポリシーではなくロールアウト用のツールです。シャドウモードを参照してください。

   次に、Prompt verdict timeout (ms)を設定します。1〜10,000msで、デフォルトは5,000msです。この時間枠はやり取り全体をカバーし、これより遅い判定はサーバーに到達できない場合と同様に扱われるため、サーバーが確実に満たせる最小の値を設定してください。

   このセクションの変更は、変更するたびに保存されます。最初の保存時のデフォルトはAllow the requestと5,000msです。

7. 7

   ロールアウト率を選択する

   Rolloutの下でRequests inspected (%)を設定すると、AIセキュリティサーバーを立ち上げている間、リクエストの一定割合に対して検査を実行できます。値の範囲は0〜100で、100ではすべてを検査し、0では検査がオフになります。

   各リクエストは会話ターン全体に対して一度だけ抽選されるため、1つの会話がターンをまたいで部分的に検査される場合があります。サンプリングされた割合に含まれないリクエストは、障害時の処理がBlock the requestに設定されている場合でも、検査なしで処理されます。

8. 8

   Enforce verdictsをオンにする

   最初は誰もブロックせずにライブトラフィックに対する判定を評価するには、適用をオンにする前にModeをShadow modeに設定します（手順6）。シャドウモードを参照してください。

   Enforce verdictsをオンにすると、管理対象のすべてのプロンプトについて、ClaudeがAIセキュリティサーバーの判定に従うようになります。その後、障害時の処理の選択内容が再表示されるダイアログで確認します。変更がすべてのAnthropicサーバーに反映されるまで約1分かかります。すでに処理中のリクエストは古い設定のまま完了します。オフにすると、同じく約1分以内にプロンプトがAIセキュリティサーバーに送信されなくなります。設定は保持されます。

   Enforce verdictsの下にあるValidate tool callsは、Claudeの各応答に含まれるツール呼び出しもAIセキュリティサーバーに送信し、実行前にその判定を待ちます。ツール呼び出しフレームを参照してください。新しい設定ではデフォルトでオンになっています。Enforce verdictsがオフの間は効果がなく、Enforce verdictsと同様に、変更がすべてのAnthropicサーバーに反映されるまで約1分かかります。

シャドウモード

「shadow mode」（シャドウモード）は、何もブロックせずにライブトラフィックに対してフックを実行します。AIセキュリティサーバーは、適用時とまったく同じように管理対象のプロンプトを受信して判定を返しますが、何もブロックされません。サーバーが拒否した場合や到達できない場合でも、すべてのリクエストはモデルに進み、エンドユーザーには何も表示されません。適用を開始する前に、組織の実際のトラフィックに対してポリシーを調整するために使用してください。Validate tool callsがオンの場合、シャドウモードでもサーバーはツール呼び出しフレームを受信し、ツール呼び出しはブロックされません。

シャドウモードを使用するには、Failure handlingの下でModeをShadow modeに設定し、Enforce verdictsをオンにしてプロンプトがAIセキュリティサーバーに送られるようにします。有効な間、設定ページにはShadow mode — not blockingバッジが表示されます。シャドウモードを終了するには、ModeをAllow the requestまたはBlock the requestに戻します。適用がオンになっていれば、判定が再び適用されます。

除外

Exclusionsの下で、Inference hooksの対象外とするメンバーのロールを選択します。これらのメンバーのプロンプトはAIセキュリティサーバーに送信されません。除外できるのは組織が作成したカスタムロールのみで、組み込みロールは選択肢に表示されません。プレースホルダーにSelect roles to excludeと表示されるロールセレクターでロールを選択し、各ロールを持つユーザーはロール管理ページ（Manage roles）で管理します。除外の変更にはID管理権限が必要です。リストはデフォルトで空で、除外されたロールがない場合、管理対象のすべてのリクエストが検査されます。

除外はユーザーのインタラクティブセッションに適用されます。除外リストへの変更は、組織のActivity Feedにロール権限の変更（rbac_role_permission_addedおよびrbac_role_permission_removed）として記録されます。

ブロック時のカスタムメッセージ

Custom blocked prompt messageの下で、最大500文字のカスタムテキストを設定できます。このテキストは、AIセキュリティサーバーがリクエストを拒否したときにエンドユーザーに表示されるエラーに追加されます。通常は、連絡先や例外の申請先を記載します。

最終的なメッセージは、次の順で構成されます。

1. AIセキュリティサーバーがリクエストごとに返すdeny_reason（存在する場合）
2. 空行
3. このカスタムテキスト

カスタムテキストが設定されていない場合は、管理者に連絡するようユーザーに案内する組み込みのデフォルトメッセージが使用されます。追加メッセージを完全にオフにして、ユーザーにdeny_reasonのみを表示することもできます。

AIセキュリティサーバーを監視する

Inference hooks設定ページのエンドポイントヘルス領域には、以下が表示されます。

• Endpoint status： Healthy、Tripped、Not enforcing、またはエンドポイントが保存される前はNot configured。
• Failures per minute： 直近2分間のWebhook失敗の平均。
• Block rate： AIセキュリティサーバーの判定に占める拒否の割合。ロールアウト率が100未満の場合に表示されます。
• Circuit breaker tripped： サーキットブレーカーが作動したことがある場合、最後に作動した日時。
• Recent errors： 各エントリには、失敗が発生した日時、エラータイプ、カテゴリが表示されます。カテゴリは、エンドポイントまたはエンドポイントへの接続に問題がある場合はwebhook_error、Anthropicのシステム内部での失敗の場合はrelay_errorです。エントリにリクエストの内容やエンドポイントURLが含まれることはありません。リストには直近10件の失敗が保持され、最後の失敗から1時間後にクリアされます。

Recent errorsのエラータイプの意味は次のとおりです。

シャドウモードでは、どのエラーもサーキットブレーカーのカウント対象になりません。

このパネルはベストエフォートです。Anthropicがカウンターを読み取れない場合、パネル自体のエラーではなく、失敗ゼロ・エラーなしと表示されます。そのため、パネルが正常に見えることだけでは、AIセキュリティサーバーが正常であることの証明にはなりません。Failures per minuteは、サーキットブレーカーを作動させることのないネットワークエラーやDNSエラーを含むすべての失敗をカウントするため、Circuit breaker trippedが空のままでも高い値になる場合があります。

サーキットブレーカー

AIセキュリティサーバーに起因するWebhookの失敗が続くと、「circuit breaker」（サーキットブレーカー）が作動し、適用が停止します。サーバーには接続されなくなり、検査対象のすべてのリクエストにFailure handlingの選択が適用されます。Block the requestを選択している場合、ブレーカーがリセットされるまで、組織のユーザーはブロックされます。ブレーカーが作動すると、claude.aiの通知センターで管理者にも通知されます。

各作動は、組織のActivity Feedにもinference_hooks_circuit_breaker_trippedアクティビティとして記録されます。これにより、セキュリティチームやベンダーは、すでに運用している監視の仕組みで作動時にアラートを出せます。たとえば、フィードを取り込むSIEMなどです。アクティビティは、影響を受けたリクエストごとではなく、作動ごとに1件記録されます。記録するには、組織でCompliance APIが有効になっている必要があります。Compliance APIをセットアップするを参照してください。

復旧するには、サーバーを修正してからEnforce verdictsを再びオンにして、ブレーカーをリセットします。

ブレーカーは自動的にリセットされることもあります。作動から10分後以降、Anthropicはバックグラウンドでサーバーにテストリクエストを送信し、サーバーが復旧したかどうかを確認します。確認の頻度は最大で約1分に1回で、ユーザーのリクエストは使用されません。サーバーが有効な判定（許可または拒否）で応答すると、ブレーカーはリセットされ、適用が再開されます。それ以外の場合、ブレーカーは作動したままで、確認が続けられます。

自動復旧が実行されるのは、作動以降にInference hooksの設定が変更されていない間のみです。作動後にInference hooksの設定を変更すると、確認は停止し、ブレーカーは自動的にリセットされなくなります。これには署名シークレットのローテーションも含まれます。その場合は、サーバーを修正したらEnforce verdictsを再びオンにしてください。

また、自動復旧が適用されるのは作動時のみです。自分でEnforce verdictsをオフにした場合、再びオンにするまで適用はオフのままです。

署名シークレットをローテーションする

署名シークレットを置き換えるには、Request signingの下にあるRotate secretをクリックします。組織にまだシークレットがない場合、同じボタンはGenerate secretと表示され、最初のシークレットを作成します。

ローテーションは即時に切り替わります。

• 新しいシークレットが生成され、一度だけ表示されます。
• 古いシークレットは取得できなくなります。
• 両方のシークレットで署名されるリクエストはありません。そのため、頼りにできる重複期間はありません。

ローテーション後も、以前のシークレットで署名されたリクエストが短時間届くことがあります。AIセキュリティサーバーでの切り替えの処理方法については、署名を検証するを参照してください。

監査証跡

Inference hooksのアクティビティは、組織のActivity Feedに記録されます。設定の変更、拒否、サーキットブレーカーの作動、および判定を取得できなかったために検査なしで処理されたリクエストが対象です。最後の種類は、Enforce verdictsがオンでModeがAllow the requestの場合にのみ記録されます。その理由は、endpoint_timeout、AIセキュリティサーバーの呼び出しにおけるその他の問題の場合はendpoint_error、Anthropic側の失敗の場合はinternal_errorです。Block the requestまたはShadow modeでは、失敗したリクエストは個別に記録されません。サーキットブレーカーの自動復旧は、どのモードでも記録されません。サーキットブレーカーが作動している間は、リクエストごとのInference hooksアクティビティは記録されません。作動アクティビティが、その期間に関するフィードの記録となります。拒否の記録には、各拒否を自社システム内の対応する記録と結合できる識別子が含まれます。

Inference hooksをオフにする

オフには2つのレベルがあります。

• Enforce verdictsをオフにする（Inference hooks設定ページ）：約1分以内に、組織からのプロンプトはAIセキュリティサーバーに送信されなくなります。すでに処理中のリクエストは、以前の設定のまま完了します。設定ページは引き続き利用できるため、AIセキュリティサーバーの作業中に適用を一時停止する場合に使用してください。
• Allow for your organizationをオフにする（Data and privacy設定）：プロンプトは検査されなくなり、再びオンにするまでInference hooksの設定は利用できなくなります。どちらの場合も、エンドポイントの設定、カスタムヘッダー、署名シークレットは保持されます。再びオンにすると、Enforce verdictsは強制的にオフになり、作動中のサーキットブレーカーはクリアされます。準備ができたら、適用を再びオンにしてください。

次のステップ