Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
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
Contributorno escopo da conta. - A função
Cognitive Services Userna 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
- Redigir políticas para adicionar suas próprias regras e classificadores de Segurança de Conteúdo.
- Configure um avaliador LLM para avaliar o conteúdo em relação a uma rubrica escrita.
- Escolha um modelo de política para outros cenários.
- Use uma identidade gerenciada em produção em vez de uma identidade interativa do desenvolvedor.
- Para obter exemplos opcionais de cliente que ajudam a integrar verificações de avaliação e recebimento em seu aplicativo, consulte o exemplo de cliente HTTP.