Início Rápido: Avaliar uma chamada de ferramenta com controles de agente (versão prévia)

Neste início rápido, você usará as APIs REST de Controles do Agente para criar uma política por meio do ARM (Azure Resource Manager). Em seguida, você avalia uma chamada de ferramenta proposta com o Unified Moderate.

A política permite reembolsos maiores que zero e não maiores que 100. Envie um reembolso para 75 ver um resultado permitido. Em seguida, envie um reembolso 150 para ver um resultado negado.

Essas chamadas à API avaliam os reembolsos propostos. Eles não executam uma ferramenta ou emitem um reembolso.

Para obter uma introdução a políticas e pontos de intervenção, consulte O que são Agent Controls?

Se você não tiver uma assinatura do Azure, crie uma gratuitamente.

Prerequisites

  • Uma assinatura do Azure.
  • Um recurso de Segurança de Conteúdo de IA do Azure habilitado para a visualização dos Controles do Agente. Se você precisar de um recurso, crie um recurso de Segurança de Conteúdo em uma região habilitada para seu acesso de visualização. Somente a criação de recursos não habilita Agent Controls.
  • Permissão para criar recursos de política e Rego sob essa conta, como Contributor no escopo da conta.
  • A função Cognitive Services User na conta para chamadas de runtime. A seção de instalação mostra como um administrador pode conceder essa função. A criação de atribuições de função requer permissão adicional, como Administrador do Controle de Acesso baseado em função.
  • CLI do Azure, cURL 7.76 ou posterior e PowerShell 7 ou posterior.

Este passo a passo usa autenticação do Microsoft Entra e o ponto de extremidade de subdomínio personalizado da conta. Ele não requer um SDK, Node.jsou OPA.

Note

Este exemplo usa a versão 2026-11-15-previewda API do ARM, a versão 2026-10-15-previewda API Unificada Moderada e a versão 0.4.0-alpha.1do manifesto do ACS. Sua conta e região devem dar suporte a essas versões.

Configure seu recurso e o acesso

Abra o PowerShell em um diretório de trabalho para os arquivos de solicitação abaixo. Execute os comandos na mesma sessão.

Entre e selecione a assinatura que contém seu recurso de Segurança de Conteúdo:

$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"

Se o usuário conectado ainda não tiver Cognitive Services User na conta, um administrador com permissão de atribuição de função poderá executar:

$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.' }

A atribuição se aplica ao usuário conectado. Em vez disso, um administrador que atribui acesso a outra pessoa deve usar a ID do objeto dessa pessoa. Permitir tempo para que as atribuições de função se propaguem.

Obtenha um token de acesso do ARM para criar os recursos:

$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 e Unified Moderate usam audiências de token diferentes. Você obterá o token de runtime mais adiante neste passo a passo.

Criar um recurso do Rego

O Rego define a regra de reembolso. Salve o seguinte código como 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
}

Essa regra nega por padrão. Ele permite apenas uma refund_order chamada com um valor numérico no intervalo permitido.

Crie o corpo da solicitação ARM do arquivo de origem:

$RegoBody = @{
    properties = @{
        encoding = 'None'
        rego = Get-Content -LiteralPath .\refund.rego -Raw
    }
}
$RegoBody | ConvertTo-Json -Depth 10 |
    Set-Content -LiteralPath .\rego-request.json -Encoding utf8

A propriedade rego contém o texto de origem. encoding: "None" significa que o texto de origem não é codificado em Base64.

Carregue-o com uma solicitação 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.'
}

Um PUT bem-sucedido retorna HTTP 200 ou 201 e uma ETag. If-None-Match: * impede que essa solicitação substitua um recurso existente. Se refund-quickstart já existir, use um novo nome de recurso ou siga as diretrizes de atualização de política.

Criar a política

O manifesto da política conecta o pre_tool_call ponto de intervenção à regra Rego e seleciona os argumentos da ferramenta para avaliação.

Salve este corpo completo da solicitação do ARM como 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 Seleciona o formato de ACS política.
query Identifica a verdict regra no refund_guard pacote Rego.
pre_tool_call Aplica a regra antes que o host envie uma chamada de ferramenta.
policy_target Seleciona os argumentos enviados da ferramenta.
tool_name_from Seleciona a entrada da ferramenta no catálogo de ferramentas do manifesto.
acsRegos Carrega o recurso Rego criado na etapa anterior.

Se você alterou o nome do recurso Rego, atualize acsRegos[0].regoName para que corresponda.

Crie a política com uma solicitação 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.'
}

Um PUT bem-sucedido retorna HTTP 200 ou 201. A política é armazenada na conta de Segurança de Conteúdo e faz referência ao Rego dessa mesma conta.

Avaliar uma chamada de ferramenta proposta

Obtenha um token de acesso do Content Safety e codifique em URL o ID do recurso de política:

$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"

Salve a seguinte solicitação como 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 Identifica o formato de contexto Agent Hooks.
interception_point Seleciona o ponto de ciclo de vida a ser avaliado.
timestamp, sequence Registre a hora e a ordem do evento dentro da sessão.
agent, session Identifique o agente e execute para fazer a correlação. Eles não concedem acesso.
tool_call Descreve o nome da ferramenta e os argumentos propostos.
target Contém os argumentos selecionados para avaliação. Neste ponto, ele deve ser igual a tool_call.args.

O carimbo de data/hora fixo e os identificadores facilitam a reprodução deste exemplo. Em um aplicativo, construa-os para o evento real. Mantenha os argumentos como JSON nativo, incluindo o valor numérico.

Envie a solicitação:

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.'
}

O policyId parâmetro de consulta seleciona a política que você criou por meio do ARM. O corpo descreve a chamada de ferramenta proposta. Ele não contém um seletor de política.

Interpretando a resposta

Unified Moderate retorna um verdict e um receipt. Para um reembolso de 75, o veredicto da regra é:

{
  "decision": "allow"
}

Essa é a verdict parte da resposta, não a resposta completa. Políticas adicionais aplicáveis podem afetar a decisão final.

Campo de resposta Meaning
verdict.decision A decisão que o hospedeiro deve aplicar. Essa regra retorna allow ou deny.
verdict.reason Um código de motivo, quando a regra fornece um.
receipt.evaluationId Identifica essa avaliação para correlação com registros de aplicativo.
receipt.evaluatedInterventionPoint O ponto avaliado, aqui pre_tool_call.
receipt.evaluatedPolicyLayers Identifica as políticas e versões avaliadas.
receipt.requestBinding Associa o recibo à solicitação e ao seletor de política.

HTTP 200 significa avaliação concluída. Verifique verdict.decision para determinar se a chamada é permitida.

Experimente um reembolso acima do limite

Altere ambas as cópias do valor para 150, em seguida, envie um novo evento:

$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.'
}

A resposta ainda usa HTTP 200, mas a regra retorna este veredicto:

{
  "decision": "deny",
  "reason": "refund_not_permitted"
}

Em um aplicativo, o host verifica o veredito e o comprovante antes de executar a ferramenta. Uma avaliação negada ou com falha mantém a chamada bloqueada.

Para uma chamada permitida, o host executa os argumentos avaliados. Consulte Interpretar a resposta para verificações de recebimento e tratamento de transformação.

Conectar a avaliação ao seu agente

Adicione a verificação no código que despacha a ferramenta, antes da execução da ferramenta. Capture os argumentos propostos uma vez e use esse mesmo valor para avaliação e despacho. O código a seguir é pseudocódigo, não uma API do SDK fornecida:

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

Uma avaliação ou falha de validação de recibo deve interromper o envio. A validação de recibo verifica o vínculo exato da solicitação, a política selecionada, o ponto de intervenção e o produtor esperado da conta de serviço. Para obter mais informações, consulte os campos recibo. O host também deve implementar todos os pontos exigidos pelo conjunto de políticas retornado.

Esse mecanismo mínimo bloqueia transformações e negações com aprovação. Adicione esses comportamentos somente quando o host implementar seus contratos de validação e aprovação. Não tente novamente uma ação de ferramenta não idempotente apenas porque a avaliação foi repetida.

Para a saída gerada, avalie o conteúdo completo antes de liberá-lo. Se o modelo transmitir dados em fluxo, armazene a saída em buffer dentro do limite do aplicativo, envie a saída completa para avaliação e, em seguida, libere apenas o conteúdo permitido. Pare em caso de overflow ou falha.

O envio de tokens para o usuário antes da conclusão da verificação não pode ser desfeito por uma negação posterior. Este passo a passo REST não implementa um protocolo de liberação de streaming por bloco.

Limpar os recursos

Depois de concluir, exclua a refund-quickstart policy e, em seguida, o recurso Rego se eles não forem mais necessários. Para excluir a política e o recurso Rego com a proteção ETag e lidar com operações assíncronas, consulte Excluir uma política e seu Rego.

Exclua a conta separadamente somente se você a tiver criado para este exercício e nenhum outro aplicativo precisar dela.

Próximas Etapas