このリファレンスでは、スタンドアロンの名前付きポリシー フローについて説明します。 ARM を使用してポリシーと Rego を管理し、アカウントのデータ プレーン エンドポイントを評価します。
Prerequisites
プレビュー アクセス、サービス アカウント、作成とランタイムのアクセス許可の クイック スタート を完了します。 管理例では、そのリソース変数と サンプル ガイドに記載されているスクリプトを使用します。 管理スクリプトを含むディレクトリから例を実行します。
エンドポイントとバージョン
| Purpose | Endpoint | Version |
|---|---|---|
| アカウントとポリシーの管理 | https://management.azure.com |
2026-11-15-preview |
| Evaluation | サービスコンテンツセーフティアカウントのエンドポイント | 2026-10-15-preview |
ポリシー リソースは次のとおりです。
/subscriptions/{subscriptionId}/resourceGroups/{resourceGroup}
/providers/Microsoft.CognitiveServices/accounts/{accountName}
/raiRegos/{regoName}
/raiPolicies/{policyName}
上記の改行は読みやすさを目的としています。 各要求では、1 つのリソース パスが使用されます。
再利用可能な Rego を参照するポリシーの前に作成します。 Rego PUT 本文には、 properties.encoding と properties.regoが含まれています。
None はプレーンソースを意味します。コントラクトは Base64も定義します。 この例では、プレーン UTF-8 ソースを使用します。
ポリシー PUT 本文には、 properties.format: "ACS"、 properties.acs、および properties.acsRegosが含まれています。 内部マニフェストのバージョンは、API バージョンではなく、 0.4.0-alpha.1です。
認証と承認
| Call | OAuth スコープ | Access |
|---|---|---|
| ARM | https://management.azure.com/.default |
アカウントと子リソースに必要なリソース管理アクション。 |
| Unified Moderate | https://cognitiveservices.azure.com/.default |
Cognitive Services User プレビュー アクセスが有効な状態で、サービス アカウントに対して〘 |
| 顧客所有のジャッジ推論 | サポートされているモデル サービスの対象ユーザー (サービスによって取得されます) | モデル アカウントのサービス アカウント ID の推論アクセス許可。 |
Microsoft Entra認証にはカスタム サブドメイン エンドポイントを使用します。 ARM トークンとデータ プレーン トークンを交換しないでください。
データ プレーン コントラクトでは、アカウントのローカル認証とプレビュー構成に従って、 Ocp-Apim-Subscription-Key 認証も宣言されます。 これらのガイドでは、Entra 資格情報を使用し、アプリケーションのマネージド ID を推奨します。 サブスクリプション キーは別のアプリケーション ID ではありません。
JSON でのエージェント ID、アクター メタデータ、セッション ID、および顧客指定の ID 要求は承認されません。
運用環境でマネージド ID を使用する
このクイック スタートでは、対話型の開発者 ID を使用します。 アプリケーションの場合は、そのコンピューティングにアタッチされたマネージド ID を使用します。
- アプリケーション ホストで ID を作成または有効にします。
- サービング コンテンツ セーフティ アカウントのプリンシパル
Cognitive Services Userを付与します。 - アプリケーションの資格情報を構成して、その ID を選択し、
https://cognitiveservices.azure.com/.defaultのトークンを取得します。 - 承認された要求が成功し、承認されていない ID が拒否されたことを確認します。
ユーザー割り当て ID の場合、ロールの割り当てでは 、そのプリンシパル ID とプリンシパル の種類 ServicePrincipalを使用します。 資格情報の選択では、 そのクライアント ID が使用されます。 ID をアプリケーション ホストにアタッチせずに作成しても、アプリケーションで使用することはできません。
アプリケーションの ID は、顧客所有の LLM ジャッジによって使用されるサービス アカウント ID とは別です。
Unified Moderate を呼び出す
この HTTP 要求は概略的です。
{unified-moderate-url} には、エンドポイント、 /contentsafety/content:unifiedModerate、 api-version=2026-10-15-preview、および完全な ARM policyId (URL エンコードが 1 回) が含まれます。
POST {unified-moderate-url}
Authorization: Bearer <access-token>
Content-Type: application/json
サービス アカウントの完全な ARM ポリシー リソース ID を policyIdとして使用します。 デプロイで短いポリシー名がサポートされている場合でも、完全な ID がより明確なセレクターです。 HTTP クエリ ビルダーを使用して 1 回だけ URL エンコードします。エスケープされていない ID を手動で連結しないでください。
スタンドアロン セレクターはクエリ パラメーターです。 リソース バインドや追加のリソース セレクターは必要ありません。
リクエスト本文
この例では、ディスパッチの前にツール引数を評価します。
{
"spec": "agent-hooks/0.1",
"interception_point": "pre_tool_call",
"timestamp": "2026-11-04T12:00:00Z",
"sequence": 2,
"agent": { "id": "support-agent", "framework": "custom" },
"session": { "id": "sample-tool" },
"tool_call": {
"id": "refund-1",
"name": "refund_order",
"args": { "order_id": "demo-001", "amount": 100 }
},
"target": { "order_id": "demo-001", "amount": 100 }
}
実際の実行には、現在のタイムスタンプ、セッションの ID、シーケンス番号の増加、ホストが実行しようとしている正確なアクションを使用します。 サービスは、ポイント固有のペイロードとターゲットの等価性を検証します。
値はネイティブ JSON として保持します。 ツール引数オブジェクトを JSON 文字列としてエンコードすることはできません。 コントラクトで許可されている場合は、数値、ブール値、配列、オブジェクト、および null を保持します。
ターゲット マッピングは、[ 作成者ポリシー] に一覧表示されます。 SDK コンテキスト ビルダーは、これらのフィールドの一貫性を維持するのに役立ちます。
Limits
要求と応答はそれぞれ、デコードされた UTF-8 JSON バイトとコンテナー深度 64 (ルートを含む) 1,048,576 個に制限されます。 有効な Unicode および明確な JSON メンバー名を使用します。 重複するメンバー、競合するセレクター、および制限超過要求はエラーであり、成功した評価は切り捨てません。
サポートされている HTTP ペイロード サイズでは、特定の分類子またはモデルがその量のコンテンツを検査できることを保証しません。 必要な機能には、独自の入力と実行の制限があります。
ARM 作成の制限
保存されたポリシー成果物には、ランタイム コンテキストとは別の制限があります。
| Item | 有効なプレビュー アカウントの制限 | 測定 |
|---|---|---|
| ACS マニフェスト | 256 KiB (262,144 バイト) |
properties.acs用のコンパクトなシリアル化 UTF-8 JSON。 |
| Rego リソース | 512 KiB (524,288 バイト) | デコードされた UTF-8 ソース ( encoding: "Base64"でアップロードされた場合を含む)。 |
| 完全な ARM PUT ボディ | 1 MiB (1,048,576 バイト) | JSON ラッパーとエンコードされたソースを含む要求本文全体。 |
これらの制限は、プレビューのデプロイによって異なります。 一部のデプロイでは、48 の KiB マニフェストと 200 KiB デコードされた Rego が適用されます。 大きな上限に依存する前に、アカウントで有効になっている制限を確認します。
成果物と要求全体の両方の制限が適用されます。 Base64 は転送されたソースを拡張し、プレーンソースの JSON エスケープも本文のサイズに影響します。 1 MiB 未満の要求は、マニフェストまたはデコードされた Rego の制限を超える可能性があります。
応答を解釈する
成功した応答には、次のものが含まれます。
| メンバー | Meaning |
|---|---|
verdict |
集計 allow、 deny、または transform 決定。 |
receipt |
評価と正確に評価された要求とポリシーを識別するメタデータ。 |
HTTP 200 は、評価が完了したことを意味します。 これは、アクションが許可されるという意味ではありません。
たとえば、 verdict メンバーは次のようになります。
{
"decision": "deny",
"reason": "tool_request_not_permitted",
"message": "Use approved tools. Refund amounts must be numeric: >0 and <=100."
}
ホストは次の手順を実行する必要があります。
- 応答と受信を検証します。
-
deny、形式が正しくないデータ、または運用エラーで停止します。 - 置換値を使用する前に、サポートされている
transformを適用して検証します。 - 評価された許可された値のみを実行または解放します。
- 実際に何が起こったかを記録します。
スタートアップ変換とシャットダウン変換はサポートされていません。 これらのガイドのジャッジ パスでは、変換の判定もサポートされていません。 返された変換または承認ワークフローをアプリケーションで安全に実装できない場合は、アクションをブロックしたままにします。
承認要求
レビューの決定は、ホストが解決するまでの拒否です。 ポリシーは、次の例を返すことができます。
{
"decision": "deny",
"reason": "human_review_required",
"approval": {
"workflow": "transaction-review"
}
}
承認オブジェクトの内容は、アプリケーションが実装するワークフローと一致する必要があります。この例ではプロビジョニングされません。 承認を正確なアクションと評価された値にバインドします。
approvalの存在を実行するアクセス許可として扱わないでください。また、承認が独立した無条件拒否をオーバーライドしないようにしてください。
approval フィールドは、レビュー キューを開いたり、アクセス許可を付与したりしません。
[受信確認] フィールド
| フィールド | ホストのチェックまたは使用 |
|---|---|
receiptVersion |
ここでは、トランスポート コントラクトと一致 2026-10-15-preview。 |
profile |
このフローには namedPolicy が必要です。 |
evaluationId、attempt |
サービス評価レコードとホスト実行レコードを関連付けます。 |
requestBinding |
algorithm: "sha256"とcanonicalization: "rfc8785"を要求し、digestを以下の正確な要求資料のハッシュと比較します。 |
evaluatedPolicyLayers |
予期される名前付きポリシーを確認します。リビジョン、セマンティック ダイジェスト、アクティブ化されたアーティファクト ダイジェスト、および決定を保持します。 |
evaluatedInterventionPoint |
この要求で送信されたポイントと一致します。 |
requiredInterventionPoints |
ホストが必要なすべてのポイントを実装していることを確認します。 これは、ホストがそれらを呼び出したことを証明するものではありません。 |
hostProfileVersion |
サービス評価プロファイルを記録します。 |
authenticatedProducerResourceId |
この namedPolicy フローでは、応答からコピーされた値ではなく、信頼された構成のサービス アカウント ID と一致します。 |
harmResults、存在する場合 |
Rego 入力または完全な内部モデル診断ではなく、パブリック分類子の概要。 |
たとえば、完全な名前付きポリシー拒否応答には、この図形があります。 リソース ID、リビジョン、評価 ID、ダイジェストは、検証コントロールにコピーする値ではなく、例示のプレースホルダーです。 実際の policyResourceId と authenticatedProducerResourceId の値は、それぞれポリシーとサービス アカウントの完全な ARM ID です。
{
"verdict": { "decision": "deny", "reason": "refund_not_permitted" },
"receipt": {
"receiptVersion": "2026-10-15-preview",
"profile": "namedPolicy",
"evaluationId": "evaluation-<unique-id>",
"attempt": 1,
"requestBinding": {
"algorithm": "sha256",
"canonicalization": "rfc8785",
"digest": "sha256:<request-digest>"
},
"evaluatedPolicyLayers": [
{
"kind": "namedPolicy",
"policyResourceId": "<full-policy-resource-id>",
"policyRevision": "<policy-revision>",
"policySemanticDigest": "sha256:<semantic-digest>",
"manifestRegoDigest": "sha256:<artifact-digest>",
"decision": "deny"
}
],
"evaluatedInterventionPoint": "pre_tool_call",
"requiredInterventionPoints": ["pre_tool_call"],
"hostProfileVersion": "<host-profile-version>",
"authenticatedProducerResourceId": "<serving-account-resource-id>"
}
}
各実ダイジェストには、 sha256: の後に 64 文字の小文字の 16 進文字が続きます。
evaluatedPolicyLayers 追加の適用可能なレイヤーを含めることができます。常に 1 つがあるとは限りません。 選択した名前付きポリシーが存在することを確認し、他のレイヤーを保持し、個々のレイヤーの許可ではなく集計判定を適用します。
要求バインド ダイジェストは、RFC 8785 標準 UTF-8 JSON の SHA-256 ハッシュです。
{
"apiVersion": <the exact Unified Moderate API version>,
"context": <the exact decoded request body>,
"selectors": { "policyId": <the exact accepted selector value> }
}
ダイジェスト文字列の先頭には sha256:が付きます。 通常の JSON シリアル化に必要な順序と数値表現があることを前提とするのではなく、正規化ライブラリを使用します。 サンプル クライアントは、このチェックを実装します。
ダイジェストは、評価メタデータを要求にバインドします。これは、ツールが実行したレシート署名や証明ではありません。 別のホストの結果と共に保持します。
エラーを処理する
| HTTP の状態または条件 | アクション |
|---|---|
400、InvalidRequest |
コンテキスト、JSON の種類、ポイント/ターゲットのペアリング、セレクター、またはペイロード のサイズを修正します。 |
401 |
資格情報の取得、トークンの対象ユーザー、有効期限を確認します。 |
403 |
選択した呼び出し元のデータ プレーン ロール、アカウント スコープ、プレビュー アクセス、およびポリシー承認を確認します。 |
404、NativeRouteDisabled |
エンドポイント、API のバージョン、アカウント、リージョンの有効化を確認します。 自動フォールバックとして古い要求形式に変更しないでください。 |
409、PolicyFenceChanged |
評価中にポリシーが変更されました。 有界再試行の前に、目的のバージョンを調整します。 |
UnsupportedCapability または使用できない必要なポリシー/依存関係 |
必要な機能またはポリシーを復元します。 チェックをスキップしないでください。 |
429 |
指定時に Retry-After を受け入れ、負荷を軽減します。 アクションをブロックしたままにしておきます。 |
500、 503、トランスポート エラー、またはタイムアウト |
アクションをブロックしたままにしておきます。 制限付きアプリケーションの期限内にのみ再試行してください。 |
200 と deny |
トランスポート障害ではなく、ポリシーの結果。 許可になるまで再試行しないでください。 |
| 無効な判定またはレシートの不一致 | 行動しないでください。エラーを記録し、調査します。 |
動作エラー コードは、サービス構成によって異なる場合があります。 機密性の高いペイロードをログに記録せずに、実際に返されたコード、HTTP 状態、および要求/評価の相関関係情報を保持します。
再試行とクォータ
1 つの評価で、複数の必要な検出器またはジャッジを呼び出すことができます。 アカウントの制限とモデルデプロイの制限は別々です。評価の HTTP 要求数では、内部検出または推論の使用が確立されません。
コンカレンシーを設定するときは、有効なアカウントとモデルのデプロイに割り当てられたクォータを使用します。 このガイドの 1 秒あたりのユニバーサル要求数の制限は想定しないでください。
評価の再試行は、べき等ではないツール アクションを再試行するためのアクセス許可ではありません。 元のアクションを保留中のままにし、時間と回数で再試行をバインドし、ディスパッチの重複を防ぎます。 変更された引数、変更された出力、別のライフサイクル ポイント、またはそれ以降のアクションに対して以前の許可を再利用しないでください。
ポリシーの更新とロールアウト
段階的なロールアウト用に新しい名前付きポリシー バージョンを発行します。 条件付き置換は、既存のリソースを意図的に更新する場合にのみ使用します。
新しい名前付きバージョンを優先する
新しい名前で新しいポリシーと Rego リソースを作成し、テストし、アプリケーションの構成済みセレクターを意図的に変更します。 たとえば、 publish-policy.ps1を使用します。
$Candidate = .\publish-policy.ps1 -AccountId $AccountId `
-TemplateDirectory .\refund-guard -PolicyName 'refund-guard-v2'
ロールアウト中は、以前のバージョンを使用できるようにします。 セレクターを戻すのは、構成のロールバックです。既に実行されているアクションは元に戻しません。
条件付きインプレース置換
ポリシーを意図的に置き換える場合は、現在の ETag を取得し、 If-Matchを使用します。
arm.ps1 の使用例を次に示します。
. .\arm.ps1
$Current = Invoke-AgentControlArm -Method GET -ResourceId $PolicyId
if (-not $Current.ETag) { throw 'The current policy has no ETag.' }
$Replacement = Get-Content .\refund-guard\policy.json -Raw |
ConvertFrom-Json -AsHashtable
# Preserve or deliberately change the same-account Rego references.
$Replacement.properties.acsRegos[0].regoName = '<intended-existing-Rego-name>'
$Updated = Invoke-AgentControlArm -Method PUT -ResourceId $PolicyId `
-Headers @{ 'If-Match' = $Current.ETag } -Body $Replacement
読み取り専用フィールドを含む完全な GET 応答ではなく、受け入れられた要求本文を使用します。 前提条件の失敗には、レビューと調整が必要です。無条件上書きを再試行しないでください。
再利用可能な Rego に対する変更は、それを参照するポリシーに影響する可能性があります。 新しい名前付きソース リソースとポリシー リソースを発行すると、複数リソースの更新をアトミック操作として扱うのを回避できます。
名前付きポリシー呼び出しでは、ID によって承認されたポリシーが選択されます。ここで示す要求形式では、ETag はピン留めされません。 意図的なロールアウトには個別の名前付きバージョンを使用し、各レシートで返された実際のリビジョンを記録します。
評価と適用を監視する
レコード:
- セッション、アクション、ポイント、および評価 ID。
- ポリシー リソース ID、リビジョン、ダイジェスト。
- 未解決の承認を含む、決定と理由。
- サービスの待機時間、タイムアウト、エラー、調整。
- アクションがブロック、ディスパッチ、変換、または解放されたかどうか。
便利なホスト アサーションは、 拒否/エラー後に保護されたディスパッチまたはリリースがゼロです。 チェック ポイントのカバレッジも含まれます。完全な応答処理では、サービスを呼び出さなかったアクションは保護されません。
生のプロンプト、ツール引数、モデル出力、アクセス トークンを避け、ルーチン ログでルーブリックを判断します。 レシート メタデータは相関関係に役立ちますが、データ処理ポリシーに代わるものではありません。
ポリシーとその Rego を削除する
- ポリシーを使用してクライアントを停止または再構成します。
- 再利用可能な Rego への他の参照を確認します。
- 現在の ETag を使用してポリシーを削除します。
- 削除が非同期の場合は、ARM 操作が成功するまで待ちます。
- Rego は、参照されなくなった後にのみ削除します。
発行スクリプトによって作成されたリソースの場合:
.\remove-policy.ps1 -PolicyId $Published.PolicyId -RegoId $Published.RegoId
remove-policy.ps1 スクリプトは、両方の ID が同じアカウントに属していることを確認し、ETag を使用し、非同期操作を待機し、これら 2 つのリソースのみを削除します。 競合または失敗した削除はエラーです。力で進まない。
このスクリプトでは、サービス アカウント、モデル アカウント、ロールの割り当て、またはリソース グループは削除されません。 未使用のリソースを個別に確認して削除します。