このクイック スタートでは、Agent Controls REST API を使用して、Azure Resource Manager (ARM) を使用してポリシーを作成します。 次に、Unified Moderate を使用して提案されたツール呼び出しを評価します。
このポリシーでは、0 より大きく、 100以下の払い戻しが許可されます。 許可された結果を表示するには、 75 の払い戻しを送信します。 その後、 150 の払い戻しを送信して、拒否された結果を確認します。
これらの API 呼び出しは、提案された払い戻しを評価します。 ツールを実行したり、払い戻しを発行したりすることはありません。
ポリシーと介入ポイントの概要については、「 エージェント制御とは」を参照してください。
Azure サブスクリプションをお持ちでない場合は、無料でアカウントを作成してください。
Prerequisites
- Azure サブスクリプション。
- エージェントコントロールプレビューで有効になっているAzure AI Content Safetyリソース。 リソースが必要な場合は、プレビュー アクセスが有効になっているリージョンに Content Safety リソースを作成 します。 リソースの作成だけでは、エージェントコントロールは有効になりません。
- アカウントのスコープでの
Contributorなど、そのアカウントでポリシーと Rego リソースを作成するアクセス許可。 - ランタイム呼び出しのアカウントの
Cognitive Services Userロール。 セットアップ セクションでは、管理者がこのロールを付与する方法を示します。 ロールの割り当てを作成するには、ロール ベースのAccess Control管理者などの追加のアクセス許可が必要です。 - Azure CLI、cURL 7.76 以降、PowerShell 7 以降。
このチュートリアルでは、Microsoft Entra認証とアカウントのカスタム サブドメイン エンドポイントを使用します。 SDK、Node.js、または OPA は必要ありません。
Note
この例では、ARM API バージョン 2026-11-15-preview、Unified Moderate API バージョン 2026-10-15-preview、ACS マニフェスト バージョン 0.4.0-alpha.1を使用します。 お使いのアカウントとリージョンでこれらのバージョンがサポートされている必要があります。
リソースとアクセスを設定する
次の要求ファイルの作業ディレクトリで PowerShell を開きます。 同じセッションでコマンドを実行します。
サインインして、Content Safety リソースを含むサブスクリプションを選択します。
$ErrorActionPreference = 'Stop'
$SubscriptionId = '<subscription-guid>'
$ResourceGroup = '<resource-group-name>'
$AccountName = '<content-safety-account-name>'
az login
if ($LASTEXITCODE -ne 0) { throw 'Azure sign-in failed.' }
az account set --subscription $SubscriptionId
if ($LASTEXITCODE -ne 0) { throw 'Unable to select the subscription.' }
$AccountJson = az cognitiveservices account show `
--resource-group $ResourceGroup --name $AccountName --output json
if ($LASTEXITCODE -ne 0) { throw 'Unable to read the Content Safety resource.' }
$Account = ($AccountJson -join "`n") | ConvertFrom-Json
$AccountId = $Account.id
$Endpoint = $Account.properties.endpoint
if (-not $AccountId -or [string]::IsNullOrWhiteSpace($Endpoint)) {
throw 'The resource did not return an ID and endpoint.'
}
$Endpoint = $Endpoint.TrimEnd('/')
$ArmApiVersion = '2026-11-15-preview'
$DataApiVersion = '2026-10-15-preview'
$RegoId = "$AccountId/raiRegos/refund-quickstart"
$PolicyId = "$AccountId/raiPolicies/refund-quickstart"
サインインしているユーザーがまだアカウントに Cognitive Services User していない場合は、ロールの割り当てアクセス許可を持つ管理者が実行できます。
$CallerId = az ad signed-in-user show --query id --output tsv
if ($LASTEXITCODE -ne 0 -or -not $CallerId) {
throw 'Unable to resolve the signed-in user.'
}
az role assignment create `
--assignee-object-id $CallerId `
--assignee-principal-type User `
--role 'Cognitive Services User' `
--scope $AccountId `
--output none
if ($LASTEXITCODE -ne 0) { throw 'Unable to grant data-plane access.' }
割り当ては、サインインしているユーザーに適用されます。 他のユーザーにアクセス権を割り当てる管理者は、代わりにそのユーザーのオブジェクト ID を使用する必要があります。 ロールの割り当てが反映されるまでしばらく待ってください。
リソースを作成するための ARM アクセス トークンを取得します。
$ArmToken = az account get-access-token `
--resource 'https://management.azure.com/' `
--query accessToken --output tsv
if ($LASTEXITCODE -ne 0 -or -not $ArmToken) {
throw 'Unable to obtain an ARM access token.'
}
ARM と Unified Moderate では、さまざまなトークン 対象ユーザーが使用されます。 ランタイム トークンは、このチュートリアルの後半で取得します。
Rego リソースを作成する
Rego は払い戻しルールを定義します。 次のコードを refund.regoとして保存します。
package refund_guard
import rego.v1
default verdict := {"decision": "deny", "reason": "refund_not_permitted"}
verdict := {"decision": "allow"} if {
input.intervention_point == "pre_tool_call"
input.snapshot.tool_call.name == "refund_order"
amount := input.policy_target.value.amount
is_number(amount)
amount > 0
amount <= 100
}
このルールは既定で拒否されます。 許可された範囲内の数値を持つ refund_order 呼び出しのみが許可されます。
ソース ファイルから ARM 要求本文を作成します。
$RegoBody = @{
properties = @{
encoding = 'None'
rego = Get-Content -LiteralPath .\refund.rego -Raw
}
}
$RegoBody | ConvertTo-Json -Depth 10 |
Set-Content -LiteralPath .\rego-request.json -Encoding utf8
rego プロパティには、ソース テキストが含まれています。
encoding: "None" は、ソースが Base64 でエンコードされていないことを意味します。
ARM PUT 要求を使用してアップロードする:
curl.exe --request PUT `
--url "https://management.azure.com${RegoId}?api-version=$ArmApiVersion" `
--header "Authorization: Bearer $ArmToken" `
--header 'Content-Type: application/json' `
--header 'If-None-Match: *' `
--data-binary '@rego-request.json' `
--include --fail-with-body --silent --show-error --max-time 60
if ($LASTEXITCODE -ne 0) {
throw 'Rego creation failed. Check the preceding response.'
}
PUT が成功すると、HTTP 200 または 201 と ETag が返されます。
If-None-Match: * は、この要求が既存のリソースを置き換えることを防ぎます。
refund-quickstart既に存在する場合は、新しいリソース名を使用するか、ポリシー更新ガイダンスに従います。
ポリシーの作成
ポリシー マニフェストは、 pre_tool_call 介入ポイントを Rego ルールに接続し、評価用のツール引数を選択します。
この完全な ARM 要求本文を policy.jsonとして保存します。
{
"properties": {
"format": "ACS",
"acs": {
"agent_control_specification_version": "0.4.0-alpha.1",
"policies": {
"refund-guard": {
"type": "rego",
"query": "data.refund_guard.verdict"
}
},
"intervention_points": {
"pre_tool_call": {
"policy_target": "$snap.tool_call.args",
"policy_target_kind": "tool_args",
"tool_name_from": "$snap.tool_call.name",
"policy": { "id": "refund-guard" }
}
},
"tools": {
"refund_order": {
"type": "write",
"description": "Issue a refund."
}
}
},
"acsRegos": [{ "regoName": "refund-quickstart" }]
}
}
| プロパティ | Purpose |
|---|---|
format |
ACS ポリシー形式を選択します。 |
query |
verdict Rego パッケージ内の refund_guard ルールを識別します。 |
pre_tool_call |
ホストがツール呼び出しをディスパッチする前にルールを適用します。 |
policy_target |
送信されたツール引数を選択します。 |
tool_name_from |
マニフェストのツールカタログ内にあるツールのエントリを選択します。 |
acsRegos |
前の手順で作成した Rego リソースを読み込みます。 |
Rego リソース名を変更した場合は、acsRegos[0].regoName が一致するように更新してください。
ARM PUT リクエストでポリシーを作成します。
curl.exe --request PUT `
--url "https://management.azure.com${PolicyId}?api-version=$ArmApiVersion" `
--header "Authorization: Bearer $ArmToken" `
--header 'Content-Type: application/json' `
--header 'If-None-Match: *' `
--data-binary '@policy.json' `
--include --fail-with-body --silent --show-error --max-time 60
if ($LASTEXITCODE -ne 0) {
throw 'Policy creation failed. Check the preceding response.'
}
PUT が成功すると、HTTP 200 または 201が返されます。 ポリシーはコンテンツ セーフティ アカウントに保存され、同じアカウント内の Rego を参照します。
提案されたツール呼び出しを評価する
Content Safety アクセス トークンを取得し、ポリシー リソース ID を URL エンコードします。
$DataToken = az account get-access-token `
--scope 'https://cognitiveservices.azure.com/.default' `
--query accessToken --output tsv
if ($LASTEXITCODE -ne 0 -or -not $DataToken) {
throw 'Unable to obtain a Content Safety access token.'
}
$EncodedPolicyId = [Uri]::EscapeDataString($PolicyId)
$ModerateUrl = "$Endpoint/contentsafety/content:unifiedModerate"
$ModerateUrl += "?api-version=$DataApiVersion"
$ModerateUrl += "&policyId=$EncodedPolicyId"
次のリクエストを tool-call.jsonという名前で保存します。
{
"spec": "agent-hooks/0.1",
"interception_point": "pre_tool_call",
"timestamp": "2026-11-06T12:00:00Z",
"sequence": 0,
"agent": { "id": "support-agent", "framework": "custom" },
"session": { "id": "refund-example" },
"tool_call": {
"id": "refund-1",
"name": "refund_order",
"args": { "order_id": "demo-001", "amount": 75 }
},
"target": { "order_id": "demo-001", "amount": 75 }
}
| フィールド | Purpose |
|---|---|
spec |
エージェント フック コンテキスト形式を識別します。 |
interception_point |
評価するライフサイクル ポイントを選択します。 |
timestamp、sequence |
セッション内のイベント時間と順序を記録します。 |
agent、session |
エージェントを特定し、相関付けのために実行します。 アクセスは許可されません。 |
tool_call |
提案されたツール名と引数について説明します。 |
target |
評価用に選択された引数が含まれます。 この時点で、 tool_call.argsと等しい必要があります。 |
固定タイムスタンプと識別子を使用すると、この例を簡単に再現できます。 アプリケーションで、実際のイベント用にそれらを作成します。 数値を含め、引数をネイティブ JSON として保持します。
要求を送信してください:
curl.exe --request POST `
--url $ModerateUrl `
--header "Authorization: Bearer $DataToken" `
--header 'Content-Type: application/json' `
--data-binary '@tool-call.json' `
--fail-with-body --silent --show-error --max-time 30
if ($LASTEXITCODE -ne 0) {
throw 'Policy evaluation failed. Check the preceding response.'
}
policyId クエリ パラメーターは、ARM を使用して作成したポリシーを選択します。 本文には、提案されたツール呼び出しが記述されています。 ポリシー セレクターが含まれていません。
応答を解釈する
Unified Moderate は、 verdict と receiptを返します。
75の払い戻しについては、ルールの判定は次のとおりです。
{
"decision": "allow"
}
これは応答の verdict 部分であり、完全な応答ではありません。 追加の適用可能なポリシーは、最終的な決定に影響を与える可能性があります。
| 応答フィールド | 意味 |
|---|---|
verdict.decision |
ホストが適用する必要がある決定。 このルールは、 allow または denyを返します。 |
verdict.reason |
ルールが提供する場合の理由コード。 |
receipt.evaluationId |
アプリケーション レコードとの相関関係に関するこの評価を識別します。 |
receipt.evaluatedInterventionPoint |
評価されたポイントはここですpre_tool_call。 |
receipt.evaluatedPolicyLayers |
評価されるポリシーとバージョンを識別します。 |
receipt.requestBinding |
要求とポリシー セレクターに受領確認をバインドします。 |
HTTP 200 は、評価が完了したことを意味します。
verdict.decisionを確認して、呼び出しが許可されているかどうかを確認します。
上限を超えて払い戻しを試す
金額の2か所の表記を 150に変更し、新しいイベントを送信します。
$Request = Get-Content -LiteralPath .\tool-call.json -Raw |
ConvertFrom-Json -AsHashtable
$Request.tool_call.args.amount = 150
$Request.target.amount = 150
$Request.tool_call.id = 'refund-2'
$Request.sequence = 1
$Request.timestamp = [DateTime]::UtcNow.ToString('o')
$Request | ConvertTo-Json -Depth 10 |
Set-Content -LiteralPath .\tool-call.json -Encoding utf8
curl.exe --request POST `
--url $ModerateUrl `
--header "Authorization: Bearer $DataToken" `
--header 'Content-Type: application/json' `
--data-binary '@tool-call.json' `
--fail-with-body --silent --show-error --max-time 30
if ($LASTEXITCODE -ne 0) {
throw 'Policy evaluation failed. Check the preceding response.'
}
応答では引き続き HTTP 200が使用されますが、規則はこの判定を返します。
{
"decision": "deny",
"reason": "refund_not_permitted"
}
アプリケーションでは、ホストは、ツールをディスパッチする前に、判定と受領書を確認します。 拒否された、または評価に失敗した場合、呼び出しがブロックされた状態が維持されます。
許可された呼び出しの場合、ホストは評価済みの引数を実行します。 受信確認と変換処理については、 応答の解釈 を参照してください。
評価をエージェントに接続する
ツールを実行する前に、ツールをディスパッチするコードにチェック を追加します。 提案された引数を 1 回キャプチャし、評価とディスパッチの両方に同じ値を使用します。 次のコードは擬似コードであり、提供された SDK API ではありません。
context = capturePreToolContext(proposedCall)
response = evaluate(policyId, context, boundedDeadline)
validateResponseAndReceipt(response, context, policyId, servingAccountId)
if response.verdict.decision != "allow":
block the call
else:
validate the captured arguments against the tool's schema
authorize the caller using trusted application state
dispatch the registered tool with the captured arguments
評価またはレシート検証の失敗はディスパッチを停止する必要があります。 レシート検証では、正確な要求バインディング、選択されたポリシー、介入ポイント、および予想される提供側アカウントのプロデューサーが確認されます。 詳細については、レシート フィールドを参照してください。 ホストは、返されるポリシー セットで必要な各項目もすべて実装する必要があります。
この最小限のゲートは、変換と承認付きの拒否をブロックします。 これらの動作は、ホストが検証および承認コントラクトを実装する場合にのみ追加します。 評価が再試行されたからといって、べき等ではないツール アクションを再試行しないでください。
生成された出力の場合は、リリースする前に完全なコンテンツを評価します。 モデルがストリーミングする場合は、アプリケーションの制限内で出力をバッファーし、評価のために完了した出力を送信してから、許可されたコンテンツのみを解放します。 オーバーフロー時または障害時に停止します。
チェックが完了する前にユーザーにトークンを送信することは、後で拒否することで元に戻すことはできません。 この REST ウォークスルーでは、チャンクごとのストリーミング リリース プロトコルは実装しません。
リソースをクリーンアップする
完了したら、不要になった場合は refund-quickstart ポリシーを削除し、その後その Rego リソースを削除します。 ETag 保護を使用してポリシーと Rego リソースを削除し、非同期操作を処理するには、「 ポリシーとその Rego を削除する」を参照してください。
この演習用にアカウントを作成し、他のアプリケーションに必要がない場合にのみ、アカウントを個別に削除してください。
次のステップ
- 独自のルールとコンテンツの安全性分類子を追加するポリシーを作成します。
- LLM ジャッジを構成 して、記述されたルーブリックに対してコンテンツを評価します。
- 他のシナリオのポリシー テンプレートを選択します。
- 対話型の開発者 ID ではなく、運用環境でマネージド ID を使用します。
- 評価チェックとレシート チェックをアプリケーションに統合するのに役立つオプションのクライアント例については、 HTTP クライアントのサンプルを参照してください。