Краткое руководство. Оценка вызова средства с помощью элементов управления агентом (предварительная версия)

В этом кратком руководстве вы используете интерфейсы REST API Agent Controls для создания политики с помощью Azure Resource Manager (ARM). Затем вы оцениваете предлагаемый вызов средства с помощью unified Moderate.

Политика разрешает возврат средств больше нуля и не превышает 100. Отправьте возврат на сумму 75, чтобы увидеть допустимый результат. Затем отправьте возмещение 150 , чтобы увидеть отклоненный результат.

Эти вызовы API оценивают предлагаемые возвраты средств. Они не выполняют инструмент или выдают возврат средств.

Общие сведения о политиках и точках вмешательства см. в разделе "Что такое элементы управления агентом"?

Если у вас нет подписки Azure, создайте её бесплатно.

Prerequisites

  • Подписка на Azure.
  • Ресурс Безопасность содержимого ИИ Azure, включенный для предварительной версии Agent Controls. Если вам нужен ресурс, создайте ресурс Content Safety в регионе, доступном для вашего доступа к предварительной версии. Само по себе создание ресурсов не включает Agent Controls.
  • Разрешение на создание политики и ресурсов Rego в этой учетной записи, например Contributor в области учетной записи.
  • Роль Cognitive Services User в учетной записи для вызовов среды выполнения. В разделе настройки показано, как администратор может предоставить эту роль. Для создания назначений ролей требуется дополнительное разрешение, например роль Role Based контроль доступа Administrator.
  • Azure CLI, cURL 7.76 или более поздней версии и PowerShell 7 или более поздней версии.

В этом пошаговом руководстве используется Microsoft Entra аутентификация и конечная точка пользовательского поддомена учетной записи. Для этого не требуется пакет SDK, Node.jsили OPA.

Note

В этом примере используется версия 2026-11-15-previewAPI ARM, версия 2026-10-15-previewединого умеренного API и версия 0.4.0-alpha.1манифеста ACS. Ваша учетная запись и регион должны поддерживать эти версии.

Настройка ресурса и доступа

Откройте 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.' }

Назначение применяется к пользователю, вошедшему в систему. Вместо этого администратор, назначающий доступ другому пользователю, должен использовать идентификатор объекта этого пользователя. Подождите, пока назначения ролей распространятся.

Получите маркер доступа 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" }]
  }
}
Property Purpose
format Выбирает ACS формат политики.
query Определяет verdict правило в пакете refund_guard Rego.
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. Политика хранится в учетной записи Content Safety и ссылается на Rego из той же учетной записи.

Оценка предлагаемого вызова средства

Получите маркер доступа Content Safety и выполните 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 }
}
Field 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 часть ответа, а не полный ответ. Дополнительные применимые политики могут повлиять на окончательное решение.

Поле ответа Meaning
verdict.decision Решение, которое должен применять узел. Это правило возвращает allow или deny.
verdict.reason Код причины, если правило указывает его.
receipt.evaluationId Определяет эту оценку для корреляции с записями приложений.
receipt.evaluatedInterventionPoint Оцениваемая точка указана здесь pre_tool_call.
receipt.evaluatedPolicyLayers Определяет политики и версии, оцененные.
receipt.requestBinding Привязывает квитанцию к запросу и селектору политики.

HTTP 200 означает, что оценка завершена. Проверьте verdict.decision, чтобы определить, разрешен ли вызов.

Попробуйте выполнить возврат сверх лимита

Измените обе копии суммы на 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"
}

В приложении хост проверяет вердикт и квитанцию перед отправкой инструмента. Отклоненная или неудачная оценка сохраняет блокировку вызова.

Для разрешенного вызова узел выполняет вычисленные аргументы. См. Интерпретацию ответа для проверки квитанций и сведений об обработке преобразований.

Подключите оценку к вашему агенту

Добавьте проверку в код, который вызывает инструмент, перед его выполнением. Захватить предложенные аргументы один раз и использовать это же значение для оценки и отправки. Следующий код является псевдокодом, а не предоставленным API пакета SDK:

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, если они больше не нужны. Сведения о том, как удалить политику и ресурс Rego с защитой ETag и обработать асинхронные операции, см. в статье Удаление политики и связанного с ней Rego.

Удалите учетную запись отдельно, только если вы создали ее для этого упражнения, а другое приложение не нуждается в нем.

Дальнейшие действия