API и операции управления агентами (предварительная версия)

Эта ссылка охватывает автономный поток именованных политик. Используйте ARM для управления политиками и Rego, а также конечной точкой плоскости данных учетной записи для их оценки.

Prerequisites

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

Конечные точки и версии

Purpose Конечная точка Версия
Управление учетными записями и политиками 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 PUT содержит properties.encoding и properties.rego.

None означает обычный источник; Контракт также определяет Base64. В примерах используется обычный источник UTF-8.

Текст PUT политики содержит properties.format: "ACS"и properties.acsproperties.acsRegos. Внутренняя версия манифеста — 0.4.0-alpha.1это не версия API.

Проверка подлинности и авторизация

Call Область OAuth Access
ARM https://management.azure.com/.default Действия по управлению ресурсами, необходимые для учетных записей и дочерних ресурсов.
Унифицированный умеренный https://cognitiveservices.azure.com/.default Cognitive Services User в учетной записи обслуживания с включенным предварительным доступом.
Вывод судьи, принадлежащий клиенту Поддерживаемая аудитория службы моделей, приобретенная службой. Разрешение на вывод для удостоверения учетной записи обслуживания в учетной записи модели.

Используйте конечную точку пользовательского поддомена для проверки подлинности Microsoft Entra. Не обменяйтесь маркерами ARM и плоскости данных.

Контракт плоскости данных также объявляет Ocp-Apim-Subscription-Key проверку подлинности, при условии локальной проверки подлинности и предварительной версии учетной записи. В этих руководствах используются учетные данные Entra и рекомендуются управляемые удостоверения для приложений. Ключ подписки не является отдельным удостоверением приложения.

Идентификаторы агента, метаданные субъекта, идентификаторы сеансов и утверждения удостоверения, предоставленные клиентом в JSON, не являются авторизацией.

Использование управляемого удостоверения в рабочей среде

В кратком руководстве используется интерактивное удостоверение разработчика. Для приложения используйте управляемое удостоверение, подключенное к вычислительным ресурсам:

  1. Создайте или включите удостоверение на узле приложения.
  2. Предоставьте субъекту Cognitive Services User отлужебную учетную запись безопасности содержимого.
  3. Настройте учетные данные приложения, чтобы выбрать это удостоверение и получить маркер для https://cognitiveservices.azure.com/.default.
  4. Убедитесь, что авторизованный запрос успешно выполнен, и несанкционированное удостоверение отклонено.

Для удостоверения, назначаемого пользователем, назначения ролей используют свой идентификатор субъекта и тип ServicePrincipalсубъекта. Выбор учетных данных использует свой идентификатор клиента. Создание удостоверения без его подключения к узлу приложения не делает его доступным для приложения.

Удостоверение приложения отличается от удостоверения учетной записи обслуживания, используемой судьей LLM, принадлежащей клиенту.

Вызов единого модерации

Этот HTTP-запрос является схематичным. {unified-moderate-url}включает конечную точку, /contentsafety/content:unifiedModerateapi-version=2026-10-15-previewи полную кодировку ARMpolicyId, закодированную один раз.

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

Используйте полный идентификатор ресурса политики ARM в качестве учетной записи policyIdобслуживания. Если развертывание поддерживает короткие имена политик, полный идентификатор по-прежнему является более четким селектором. URL-кодирование после использования построителя HTTP-запросов; не сцепляйте идентификаторы без ввода вручную.

Автономный селектор — это параметр запроса. Привязка ресурсов или дополнительный селектор ресурсов не требуется.

Текст запроса

В этом примере вычисляется аргументы инструментов перед отправкой:

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

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

Сохраняйте значения как собственные JSON. Объект аргумента инструмента не должен быть закодирован как строка JSON. Сохраняйте числа, логические элементы, массивы, объекты и null, где контракт разрешает их.

Целевое сопоставление отображается в политиках author. Конструкторы контекстов ПАКЕТА SDK помогают обеспечить согласованность этих полей.

Limits

Запросы и ответы ограничены 1048 576 декодированных байтами JSON UTF-8 и глубиной контейнера 64, включая корневой. Используйте допустимые имена членов Юникода и однозначные имена элементов JSON. Повторяющиеся члены, конфликтующие селекторы и запросы чрезмерного ограничения — это ошибки, а не усеченные успешные оценки.

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

Ограничения разработки ARM

Сохраненные артефакты политики имеют отдельные ограничения от контекста среды выполнения:

Item Ограничение на включенные учетные записи предварительной версии Измерение
Манифест ACS 256 КиБ (262 144 байта) Компактный сериализованный json UTF-8 для properties.acs.
Ресурс Rego 512 КиБ (524 288 байт) Декодирован источник UTF-8, в том числе при отправке с encoding: "Base64"помощью .
Полный текст ARM PUT 1 MiB (1 048 576 байт) Весь текст запроса, включая оболочки JSON и закодированный источник.

Эти ограничения зависят от развертывания предварительной версии. Некоторые развертывания применяют 48 манифестов KiB и 200 КиБ декодированных Rego. Подтвердите ограничения, включенные для учетной записи, прежде чем полагаться на более крупные ограничения.

Применяются как артефакты, так и ограничения всего запроса. Base64 расширяет транспортированную исходную папку и экранирование JSON с открытым исходным кодом также способствует размеру тела. Запрос меньше 1 МиБ по-прежнему может превышать манифест или декодировано ограничение Rego.

Интерпретируйте ответ

Успешный ответ содержит следующее:

Член Meaning
verdict Агрегат allowили denytransform решение.
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 потока соответствует идентификатор учетной записи обслуживания из доверенной конфигурации, а не значение, скопированное из ответа.
harmResults, когда присутствует Общие сводки классификатора, а не входные данные Rego или полная внутренняя диагностика модели.

Например, полный ответ запрета именованной политики имеет эту фигуру. Идентификаторы ресурсов, редакция, идентификатор оценки и дайджесты являются иллюстрированными заполнителями, а не значениями для копирования в проверяющий элемент. Реальные policyResourceId и authenticatedProducerResourceId значения являются полными идентификаторами ARM для политики и учетной записи обслуживания соответственно:

{
  "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 может содержать дополнительные применимые слои; Не предполагайте, что всегда есть именно один. Проверьте наличие выбранной именованной политики, сохраните другие слои и примените агрегированный вердикт, а не разрешить отдельный слой.

Дайджест привязки запроса — это хэш SHA-256 канонического RFC 8785 UTF-8 JSON для:

{
  "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 могут повлиять на политики, ссылающиеся на него. Публикация новых именованных ресурсов источника и политики позволяет избежать обработки обновлений с несколькими ресурсами как атомарной операции.

Вызовы именованной политики выбирают авторизованную политику по идентификатору; Формат запроса, показанный здесь, не закрепляет ETag. Используйте отдельные именованные версии для преднамеренного развертывания и запишите фактическую редакцию, возвращенную в каждой квитанции.

Мониторинг оценки и принудительного применения

Записи:

  • Идентификаторы сеанса, действия, точки и оценки.
  • Идентификаторы ресурсов политики, редакции и дайджесты.
  • Решение и причина, включая неразрешенные утверждения.
  • Задержка службы, время ожидания, сбои и регулирование.
  • Будет ли действие заблокировано, отправлено, преобразовано или выпущено.

Полезное утверждение узла равно нулю защищенным диспетчерам или выпускам после запрета или ошибки. Кроме того, покрытие контрольной точки; Идеальная обработка ответов не защищает действие, которое никогда не вызывало службу.

Избегайте необработанных запросов, аргументов инструментов, выходных данных модели, маркеров доступа и рубрик судьи в журналах подпрограмм. Метаданные квитанции полезны для корреляции, но она не заменяет политику обработки данных.

Удаление политики и его rego

  1. Остановите или перенастроите клиенты с помощью политики.
  2. Проверьте наличие других ссылок на его повторно используемый Rego.
  3. Удалите политику с текущим ETag.
  4. Если удаление является асинхронным, дождитесь успешной операции ARM.
  5. Удалить Rego только после того, как он больше не ссылается.

Для ресурсов, созданных скриптом публикации:

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

Сценарий remove-policy.ps1 проверяет, принадлежат ли оба идентификатора к одной учетной записи, используют ETags, ожидает асинхронных операций и удаляет только эти два ресурса. Конфликт или сбой удаления является ошибкой; он не продолжается силой.

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