代理程式控制 API 與操作(預覽版)

本參考文獻涵蓋獨立命名政策流程。 使用 ARM 管理政策與 Rego,並透過帳戶的資料平面端點來評估它們。

Prerequisites

完成 快速入門 程序以取得預覽權限、服務帳戶,以及撰寫與執行權限。 管理範例使用其資源變數及 範例指南中列出的腳本。 從包含管理腳本的目錄執行範例。

端點與版本

Purpose Endpoint 版本
帳戶與政策管理 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}

上方的換行是為了讓讀者更易讀。 每個請求使用單一資源路徑。

在引用該 Rego 的政策之前建立可重複使用的 Rego。 Rego PUT 體包含 properties.encoding 和 properties.rego。

None 意指純源;契約也定義 Base64了 。 範例中使用純 UTF-8 原始碼。

政策 PUT 主體包含 properties.format: "ACS"、 、 properties.acsproperties.acsRegos及 。 內部清單版本為 0.4.0-alpha.1,而非任一 API 版本。

身份驗證與授權

Call OAuth 範圍 存取
ARM https://management.azure.com/.default 帳戶及子資源所需的資源管理操作。
統一溫和黨 https://cognitiveservices.azure.com/.default Cognitive Services User 在服務帳戶上,並啟用預覽存取。
客戶擁有的法官推論 服務所取得的支援模型服務受眾 模型帳戶上提供提供服務帳戶身份的推論權限。

使用自訂子網域端點進行 Microsoft Entra 驗證。 請勿互換 ARM 與資料平面標記。

資料平面合約也會宣 Ocp-Apim-Subscription-Key 告驗證,但須依帳戶的本地驗證與預覽設定而定。 這些指南使用 Entra 憑證,並建議應用程式使用受管理身份。 訂閱金鑰並非獨立的應用程式識別碼。

代理程式 ID、演員元資料、工作階段 ID 以及客戶提供的 JSON 身份聲明不屬於授權。

在生產環境中使用受管理身份

快速啟動使用互動式開發者身份。 對於應用程式,請使用附加在其運算上的受管理身份:

  1. 在應用程式主機上建立或啟用該身份。
  2. 將其本金 Cognitive Services User 用於服務內容安全帳戶。
  3. 設定應用程式的認證以選擇該身份並取得 https://cognitiveservices.azure.com/.default。
  4. 確認授權請求是否成功,且未授權的身份是否被拒絕。

對於使用者指派的身份,角色指派會使用其 主體 ID 與主體類型 ServicePrincipal。 憑證選擇使用其 用戶端 ID。 建立身份但未將其附加至應用程式主機,並不會讓該應用程式可用。

該應用程式的身份與客戶擁有的 LLM 評審所使用的服務帳戶身份是分開的。

呼叫統一 中等

此 HTTP 請求為示意圖。 {unified-moderate-url} 包含您的端點、 /contentsafety/content:unifiedModerate、 api-version=2026-10-15-preview、以及完整的 ARM policyId,並以一次 URL 編碼。

POST {unified-moderate-url}
Authorization: Bearer <access-token>
Content-Type: application/json

在服務帳戶下使用完整的 ARM 政策資源 ID,作為 policyId。 當部署支援簡短的政策名稱時,完整 ID 仍然是較清晰的選擇器。 使用 HTTP 查詢建構器對其進行一次 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

請求與回應各自限制為 1,048,576 個解碼後的 UTF-8 JSON 位元組 ,以及 容器深度 64,包括根節點。 使用有效的 Unicode 及明確的 JSON 成員名稱。 重複成員、選擇器衝突及超限請求屬於錯誤,而非截斷的成功評估。

支援的 HTTP 有效載荷大小並不保證特定分類器或模型能檢查該數量的內容。 所需功能有其自身的輸入與執行限制。

ARM 著作限制

儲存的政策產物與執行時上下文有不同的限制:

Item 啟用預覽帳戶的限制 測量
ACS 清單 256 KiB (262,144 位元節) 精簡序列化的 UTF-8 JSON 用於 properties.acs。
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."
}

主持人必須:

  1. 驗證回應與收件。
  2. 停止、 deny資料格式錯誤或操作失敗。
  3. 在使用替換值之前,請套用並驗證支援 transform 值。
  4. 只執行或釋放已評估且允許的值。
  5. 記錄實際發生了什麼。

啟動與關機轉換不支援。 這些指南中的法官路線也不支援轉換判決。 如果您的應用程式無法安全地實作回傳的轉換或核准工作流程,請將該動作封鎖。

核准申請

審查決定在房東解決之前即為拒絕。 政策可以回傳,例如:

{
  "decision": "deny",
  "reason": "human_review_required",
  "approval": {
    "workflow": "transaction-review"
  }
}

核准物件的內容必須與您的應用程式實作的工作流程相符;此範例未提供此選項。 將任何核准綁定於具體行動及評估後的數值。 不要把 的 approval 存在視為執行許可,也不要讓核准凌駕於獨立且無條件的拒絕之上。

此 approval 欄位不會開啟審核佇列或授予權限。

收據欄位

Field 主機檢查或使用
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 個小寫十六進位字元。 evaluatedPolicyLayers 可以包含額外的適用圖層;不要假設總是有恰好一個。 確認所選命名政策是否存在,保留其他層,並強制執行彙總判定而非單一層的允許。

請求綁定摘要是 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 狀態或條件 Action
400,InvalidRequest 修正上下文、JSON 類型、點/目標配對、選擇器或有效載荷大小。
401 檢查憑證取得、令牌受眾及到期時間。
403 檢查所選呼叫者的資料平面角色、帳戶範圍、預覽存取權及政策授權。
404,NativeRouteDisabled 檢查端點、API 版本、帳戶及區域啟用情況。 請勿將舊請求格式自動切換為備援。
409,PolicyFenceChanged 評估期間政策有所改變。 在進行有界重試前,先調和預期版本。
UnsupportedCapability 或不可用的必要政策/依賴 還原所需的功能或政策。 不要跳過檢查。
429 供應時就尊重 Retry-After ,減輕負荷。 保持動作被阻擋。
500、、 503傳輸錯誤或逾時 保持動作被阻擋。 僅在有限制的申請截止日前重試。
200 和 deny 這是政策上的結果,而非運輸失敗。 在它變成許可之前不要重試。
判決無效或收據不符 不要行動。記錄失敗並進行調查。

操作錯誤代碼可能因服務配置而異。 保留實際回傳的程式碼、HTTP 狀態以及請求/評估相關資訊,而不記錄敏感的有效載荷。

重試與配額

單一評估可能觸發多個必要的偵測器或法官。 帳戶限制與模型部署限制是分開的;評估的 HTTP 請求次數並不能確定其內部偵測器或推論的使用情況。

設定並發時,請使用您已啟用帳戶及模型部署所指派的配額。 請勿根據本指南假設所有的每秒請求數限制。

評估重試並不等於允許重試非冪等工具動作。 保持原始動作待處理狀態,重試時間與計數綁定,並防止重複派遣。 不要重複使用先前允許變更參數、變更輸出、不同的生命週期點或後續動作。

更新並推出政策

發佈新的命名政策版本以進行分階段部署。 僅在您有意更新現有資源時使用條件式替換。

偏好新命名版本

建立一個新的政策與 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。 在有意識的推出時,使用不同的命名版本,並在每張收據中記錄實際回傳的修訂內容。

監控評估與執行情況

紀錄:

  • Session、Action、Point 與 Evaluation ID。
  • 政策資源 ID、修訂版與摘要。
  • 決定與理由,包括未解決的核准。
  • 服務延遲、逾時、故障與節流。
  • 動作是被阻擋、派遣、轉換或釋放。

一個有用的主機斷言是在 拒絕/錯誤後,零受保護的派遣或釋放。 檢查點的覆蓋範圍也包括;完美回應處理無法保護從未呼叫服務的動作。

避免使用原始提示、工具參數、模型輸出、存取權杖,並在例行日誌中判斷評分標準。 收據元資料有助於關聯,但無法取代資料處理政策。

刪除政策及其 Rego

  1. 使用政策停止或重新設定用戶端。
  2. 查查其他關於它可重複使用的 Rego 的參考資料。
  3. 刪除帶有目前 ETag 的政策。
  4. 如果刪除是非同步的,請等待 ARM 操作成功。
  5. 只有在不再被引用後才刪除 Rego。

對於由發佈腳本建立的資源:

.\remove-policy.ps1 -PolicyId $Published.PolicyId -RegoId $Published.RegoId

腳本會 remove-policy.ps1 檢查兩個 ID 是否屬於同一帳戶,使用 ETag,等待非同步操作,並只刪除這兩個資源。 衝突或刪除失敗即為錯誤;它並非以武力推動。

此指令碼不會刪除服務帳戶、模型帳戶、角色指派或資源群組。 請分別檢視並移除未使用的資源。