API e operações de controles do agente (versão prévia)

Essa referência aborda o fluxo autônomo de política nomeada. Use o ARM para gerenciar políticas e o Rego e o ponto de extremidade do plano de dados da conta para avaliá-los.

Prerequisites

Conclua o início rápido para acesso de visualização, uma conta de serviço e permissões de criação e runtime. Os exemplos de gerenciamento usam suas variáveis de recurso e os scripts listados no guia de exemplo. Execute os exemplos do diretório que contém os scripts de gerenciamento.

Pontos de extremidade e versões

Purpose Endpoint Versão
Gerenciamento de conta e política https://management.azure.com 2026-11-15-preview
Evaluation O ponto de extremidade da conta de Segurança de Conteúdo de serviço 2026-10-15-preview

Os recursos da política são:

/subscriptions/{subscriptionId}/resourceGroups/{resourceGroup}
  /providers/Microsoft.CognitiveServices/accounts/{accountName}
    /raiRegos/{regoName}
    /raiPolicies/{policyName}

As quebras de linha acima são para legibilidade. Cada solicitação usa um único caminho de recurso.

Crie o Rego reutilizável antes da política que a referencia. Um corpo REgo PUT contém properties.encoding e properties.rego.

None significa origem simples; o contrato também define Base64. Os exemplos usam a origem UTF-8 simples.

Um corpo PUT de política contém properties.format: "ACS", properties.acse properties.acsRegos. A versão do manifesto interno não é 0.4.0-alpha.1uma versão da API.

Autenticação e autorização

Call Escopo do OAuth Access
ARM https://management.azure.com/.default Ações de gerenciamento de recursos necessárias para a conta e os recursos filho.
Moderado Unificado https://cognitiveservices.azure.com/.default Cognitive Services User na conta de serviço, com acesso de visualização habilitado.
Inferência do juiz de propriedade do cliente O público-alvo do serviço de modelo com suporte, adquirido pelo serviço Permissão de inferência para a identidade da conta de serviço na conta de modelo.

Use um ponto de extremidade de subdomínio personalizado para autenticação Microsoft Entra. Não intercambie tokens ARM e plano de dados.

O contrato de plano de dados também declara Ocp-Apim-Subscription-Key a autenticação, sujeita à configuração de autenticação local e visualização da conta. Esses guias usam as credenciais do Entra e recomendam identidades gerenciadas para aplicativos. Uma chave de assinatura não é uma identidade de aplicativo separada.

IDs do agente, metadados de ator, IDs de sessão e declarações de identidade fornecidas pelo cliente no JSON não são autorização.

Usar uma identidade gerenciada em produção

O início rápido usa uma identidade interativa do desenvolvedor. Para um aplicativo, use uma identidade gerenciada anexada à sua computação:

  1. Crie ou habilite a identidade no host do aplicativo.
  2. Conceda sua entidade de segurança Cognitive Services User na conta de Segurança de Conteúdo de serviço.
  3. Configure a credencial do aplicativo para selecionar essa identidade e obter um token para https://cognitiveservices.azure.com/.default.
  4. Verifique se uma solicitação autorizada foi bem-sucedida e se uma identidade não autorizada foi rejeitada.

Para uma identidade atribuída pelo usuário, as atribuições de função usam sua ID principal e o tipo ServicePrincipalde entidade de segurança. A seleção de credencial usa sua ID do cliente. Criar a identidade sem anexá-la ao host do aplicativo não a disponibiliza para o aplicativo.

A identidade do aplicativo é separada da identidade da conta de serviço usada por um juiz LLM de propriedade do cliente.

Chamar Unificado Moderado

Essa solicitação HTTP é esquema. {unified-moderate-url}inclui o ponto de extremidade e /contentsafety/content:unifiedModerateapi-version=2026-10-15-previewo ARM policyIdcompleto codificado uma vez.

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

Use a ID de recurso de política completa do ARM na conta de serviço como policyId. Quando uma implantação dá suporte a nomes de política curtos, a ID completa ainda é o seletor mais claro. Codificar URL uma vez usando um construtor de consultas HTTP; não concatene manualmente as IDs sem escape.

O seletor autônomo é um parâmetro de consulta. Nenhuma associação de recursos ou seletor de recurso adicional é necessário.

Corpo da solicitação

Este exemplo avalia os argumentos da ferramenta antes da expedição:

{
  "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 }
}

Para a execução real, use um carimbo de data/hora atual, a ID da sessão e o número de sequência crescente e a ação exata que seu host está prestes a executar. O serviço valida a carga específica do ponto e a igualdade de destino.

Mantenha valores como JSON nativo. Um objeto de argumento de ferramenta não deve ser codificado como uma cadeia de caracteres JSON. Preservar números, boolianos, matrizes, objetos e nulos em que o contrato permite.

O mapeamento de destino está listado nas políticas de Autor. Os construtores de contexto do SDK ajudam a manter esses campos consistentes.

Limits

As solicitações e respostas são limitadas a 1.048.576 bytes JSON UTF-8 decodificados e profundidade de contêiner 64, incluindo a raiz. Use nomes de membroS JSON válidos e Unicode inequívoco. Membros duplicados, seletores conflitantes e solicitações de limite excessivo são erros, não avaliações bem-sucedidas truncadas.

Um tamanho de conteúdo HTTP com suporte não garante que um determinado classificador ou modelo possa inspecionar essa quantidade de conteúdo. Os recursos necessários têm seus próprios limites de entrada e execução.

Limites de criação do ARM

Os artefatos de política armazenados têm limites separados do contexto de runtime:

Item Limite de contas de visualização habilitadas Medição
Manifesto do ACS 256 KiB (262.144 bytes) Compactar o JSON UTF-8 serializado para properties.acs.
Recurso rego 512 KiB (524.288 bytes) Origem UTF-8 decodificada, inclusive quando carregada com encoding: "Base64".
Corpo completo do ARM PUT 1 MiB (1.048.576 bytes) Todo o corpo da solicitação, incluindo wrappers JSON e fonte codificada.

Esses limites dependem da implantação de visualização. Algumas implantações impõem 48 manifestos KiB e 200 KiB decodificados Rego. Confirme os limites habilitados para sua conta antes de depender dos limites maiores.

Os limites de artefato e de solicitação inteira se aplicam. Base64 expande a origem transportada e o escape JSON de origem simples também contribui para o tamanho do corpo. Uma solicitação menor que 1 MiB ainda pode exceder o limite de manifesto ou decodificado-Rego.

Interpretar a resposta

Uma resposta bem-sucedida contém:

Membro Meaning
verdict A agregação allowou denytransform a decisão.
receipt Metadados que identificam a avaliação e as políticas e solicitações avaliadas exatas.

HTTP 200 significa avaliação concluída. Isso não significa que a ação seja permitida.

Por exemplo, o verdict membro pode ser:

{
  "decision": "deny",
  "reason": "tool_request_not_permitted",
  "message": "Use approved tools. Refund amounts must be numeric: >0 and <=100."
}

O host deve:

  1. Valide a resposta e o recibo.
  2. Parar, denydados malformados ou falha operacional.
  3. Aplique e valide um suporte transform antes de usar seu valor de substituição.
  4. Execute ou libere apenas o valor avaliado e permitido.
  5. Registre o que realmente aconteceu.

As transformações de inicialização e desligamento não têm suporte. O caminho do juiz nestes guias também não dá suporte a veredictos de transformação. Se o aplicativo não puder implementar uma transformação retornada ou um fluxo de trabalho de aprovação com segurança, mantenha a ação bloqueada.

Solicitações de aprovação

Uma decisão de revisão é uma negação até que seu host a resolva. Uma política pode retornar, por exemplo:

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

O conteúdo do objeto de aprovação deve corresponder a um fluxo de trabalho que seu aplicativo implementa; este exemplo não provisiona um. Associe qualquer aprovação à ação exata e aos valores avaliados. Não trate a presença como approval permissão para executar e não deixe que uma aprovação substitua uma negação incondicional independente.

O approval campo não abre uma fila de revisão nem concede permissão.

Campos de recebimento

Field Verificação ou uso do host
receiptVersion Corresponda ao contrato de transporte, aqui 2026-10-15-preview.
profile Espere namedPolicy por esse fluxo.
evaluationId, attempt Correlacionar registros de avaliação de serviço e execução de host.
requestBinding Exija algorithm: "sha256" e canonicalization: "rfc8785"compare digest com o hash do material exato da solicitação abaixo.
evaluatedPolicyLayers Verifique a política nomeada esperada; mantenha sua revisão, resumo semântico, resumo de artefato ativado e decisão.
evaluatedInterventionPoint Corresponda ao ponto enviado nesta solicitação.
requiredInterventionPoints Verifique se o host implementa todos os pontos necessários. Isso não prova que o host os chamou.
hostProfileVersion Registre o perfil de avaliação do serviço.
authenticatedProducerResourceId Para esse namedPolicy fluxo, corresponda à ID da conta de serviço da configuração confiável, não a um valor copiado da resposta.
harmResults, quando presente Resumos do classificador público, não a entrada rego ou o diagnóstico de modelo interno completo.

Por exemplo, uma resposta completa de negação de política nomeada tem essa forma. As IDs de recurso, revisão, ID de avaliação e resumos são espaços reservados ilustrativos, não valores a serem copiados em um validador. Reais policyResourceId e authenticatedProducerResourceId valores são IDs completas do ARM para a política e a conta de serviço, respectivamente:

{
  "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>"
  }
}

Cada resumo real contém sha256: 64 caracteres hexadecimal minúsculos. evaluatedPolicyLayers pode conter camadas aplicáveis adicionais; não suponha que haja sempre exatamente um. Verifique se a política nomeada selecionada está presente, preserve as outras camadas e imponha o veredicto agregado em vez de permitir uma camada individual.

O resumo da associação de solicitação é o hash SHA-256 do JSON UTF-8 canônico RFC 8785 para:

{
  "apiVersion": <the exact Unified Moderate API version>,
  "context": <the exact decoded request body>,
  "selectors": { "policyId": <the exact accepted selector value> }
}

A cadeia de caracteres digest é prefixada com sha256:. Use uma biblioteca de canonicalização em vez de supondo que a serialização JSON comum tenha a ordem e a representação numérica necessárias. O cliente de exemplo implementa essa verificação.

O resumo associa metadados de avaliação a uma solicitação; não é uma assinatura de confirmação ou uma prova de que uma ferramenta foi executada. Mantenha-o com um resultado de host separado.

Lidar com erros

Status ou condição HTTP Action
400, InvalidRequest Corrija o contexto, os tipos JSON, o emparelhamento ponto/destino, o seletor ou o tamanho da carga.
401 Verifique a aquisição de credenciais, o público-alvo do token e a expiração.
403 Verifique a função de plano de dados, o escopo da conta, o acesso à visualização e a autorização de política do chamador selecionado.
404, NativeRouteDisabled Verifique o ponto de extremidade, a versão da API, a conta e a habilitação da região. Não altere para um formato de solicitação mais antigo como um fallback automático.
409, PolicyFenceChanged A política foi alterada durante a avaliação. Reconciliar a versão pretendida antes de uma repetição limitada.
UnsupportedCapability ou política/dependência necessária indisponíveis Restaure a funcionalidade ou a política necessária. Não ignore a verificação.
429 Honrá-lo Retry-After quando for fornecido e reduzir a carga. Mantenha a ação bloqueada.
500, 503erro de transporte ou tempo limite Mantenha a ação bloqueada. Tente novamente somente dentro de um prazo de aplicativo limitado.
200 com deny Um resultado da política, não uma falha de transporte. Não tente novamente até que se torne uma permissão.
Veredito inválido ou incompatibilidade de recibo Não aja. Registre a falha e investigue.

Os códigos de erro operacionais podem ser diferentes entre as configurações de serviço. Preserve o código retornado real, o status HTTP e as informações de correlação de solicitação/avaliação sem registrar conteúdos confidenciais em log.

Novas tentativas e cotas

Uma única avaliação pode invocar vários detectores ou juízes necessários. Os limites de conta e os limites de implantação de modelo são separados; A contagem de solicitações HTTP de uma avaliação não estabelece seu detector interno ou uso de inferência.

Use as cotas atribuídas à sua conta habilitada e à implantação do modelo ao definir a simultaneidade. Não suponha um limite universal de solicitações por segundo deste guia.

Uma repetição de avaliação não é permissão para repetir uma ação de ferramenta não idempotente. Mantenha a ação original pendente, limite novas tentativas por tempo e contagem e impeça a expedição duplicada. Não reutilize uma permissão anterior para argumentos alterados, saída alterada, um ponto de ciclo de vida diferente ou uma ação posterior.

Atualizar e distribuir políticas

Publique novas versões de política nomeada para uma distribuição em etapas. Use a substituição condicional somente quando você atualizar intencionalmente um recurso existente.

Preferir uma nova versão nomeada

Crie uma nova política e recurso rego com um novo nome, teste-a e altere deliberadamente o seletor configurado do aplicativo. Por exemplo, use publish-policy.ps1:

$Candidate = .\publish-policy.ps1 -AccountId $AccountId `
    -TemplateDirectory .\refund-guard -PolicyName 'refund-guard-v2'

Mantenha a versão anterior disponível durante a distribuição. Mover o seletor de volta é uma reversão de configuração; ele não desfaz ações já executadas.

Substituição condicional in-loco

Se você substituir intencionalmente uma política, OBTENHA sua ETag atual e use If-Match. O exemplo a seguir usa 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

Use um corpo de solicitação aceito, não a resposta GET completa com campos somente leitura. Uma falha de pré-condição requer revisão e reconciliação; não tente novamente uma substituição incondicional.

As alterações no Rego reutilizável podem afetar as políticas que fazem referência a ela. A publicação de novos recursos de origem e política nomeados evita o tratamento de atualizações de vários recursos como uma operação atômica.

Chamadas de política nomeada selecionam a política autorizada por ID; o formato de solicitação mostrado aqui não fixa um ETag. Use versões nomeadas distintas para distribuição deliberada e registre a revisão real retornada em cada recibo.

Monitorar a avaliação e a imposição

Registro:

  • IDs de sessão, ação, ponto e avaliação.
  • IDs de recursos de política, revisões e resumos.
  • Decisão e motivo, incluindo aprovações não resolvidas.
  • Latência de serviço, tempos limite, falhas e limitação.
  • Se a ação foi bloqueada, expedida, transformada ou liberada.

Uma asserção de host útil é zero expedições ou versões protegidas após negação/erro. Verifique também a cobertura do ponto de verificação; O tratamento de resposta perfeito não protege uma ação que nunca chamou o serviço.

Evite prompts brutos, argumentos de ferramenta, saída de modelo, tokens de acesso e avaliação de rubrices em logs de rotina. Os metadados de recebimento são úteis para correlação, mas não substituem uma política de tratamento de dados.

Excluir uma política e seu Rego

  1. Interrompa ou reconfigure clientes usando a política.
  2. Verifique se há outras referências ao Rego reutilizável.
  3. Exclua a política com sua ETag atual.
  4. Se a exclusão for assíncrona, aguarde até que a operação arm seja bem-sucedida.
  5. Exclua o Rego somente depois que ele não for mais referenciado.

Para recursos criados pelo script de publicação:

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

O remove-policy.ps1 script verifica se ambas as IDs pertencem à mesma conta, usa ETags, aguarda operações assíncronas e exclui apenas esses dois recursos. Um conflito ou uma exclusão com falha é um erro; ele não prossegue à força.

O script não exclui a conta de serviço, a conta de modelo, as atribuições de função ou o grupo de recursos. Examine e remova os recursos não utilizados separadamente.