entra-agent-id

Microsoft Entra Agent ID — это официальный навык Microsoft для предварительной версии механизма идентичностей AI-агентов. Он описывает создание OAuth2-совместимых идентичностей через beta API Microsoft Graph и связывает эту задачу с объектами Microsoft Entra: Agent Identity Blueprint, BlueprintPrincipal и отдельными Agent Identities. Blueprint представляет тип агента или проект, BlueprintPrincipal является обязательным service principal для этого blueprint, а Agent Identity представляет конкретный экземпляр агента. В исходном skill отдельно подчёркнуто, что создание blueprint само по себе не создаёт его service principal: если пропустить BlueprintPrincipal, последующее создание идентичности завершается ошибкой API. Поэтому этот материал полезен как краткая карта ресурсов и последовательности provisioning, а не как обещание стабильности preview-функции. Перед началом нужно учитывать состояние API и окружения. Все Agent Identity endpoints доступны только под базовым URL https://graph.microsoft.com/beta и не относятся к версии /v1.0. Навык рекомендует сверять актуальные инструкции Microsoft Entra Agent ID и текущие параметры API перед настройкой. Для интерактивного сценария предусмотрен PowerShell 7+ с модулем Microsoft.Graph.Beta.Applications; для программного provisioning — Python с пакетами azure-identity и requests. В переменных окружения используются идентификаторы tenant и приложения, а также секрет приложения, если выбран локальный client-secret сценарий. Для доступа нужны одна из ролей Agent Identity Developer, Agent Identity Administrator или Application Administrator. Главное ограничение касается аутентификации. DefaultAzureCredential в описанном потоке не поддерживается: токены Azure CLI содержат Directory.AccessAsUser.All, который Agent Identity API отклоняет с HTTP 403. Для application permissions нужен отдельный app registration и поток client_credentials; для delegated-сценария в PowerShell используется Connect-MgGraph с явно заданными scopes. В Python навык показывает ClientSecretCredential, получение токена для https://graph.microsoft.com/.default и запросы с Authorization, Content-Type application/json и обязательным OData-Version: 4.0. Для production Microsoft рекомендует Workload Identity Federation, а client secret оставляет вариантом локальной разработки. Базовый процесс состоит из трёх операций. Сначала POST /applications создаёт объект Microsoft.Graph.AgentIdentityBlueprint; в запросе передаётся displayName и sponsor через sponsors@odata.bind. Sponsor должен быть именно объектом User: ServicePrincipal и Group для этого поля отклоняются. Затем POST /servicePrincipals создаёт Microsoft.Graph.AgentIdentityBlueprintPrincipal с appId blueprint. Этот шаг нужно проверять и при повторном запуске, потому что предыдущий процесс мог создать blueprint и завершиться до создания service principal. После этого POST /servicePrincipals создаёт Microsoft.Graph.AgentIdentity с displayName, ссылкой на blueprint и sponsor. Идемпотентный provisioning должен сначала искать существующие объекты и не создавать дубликаты. В API-справочнике также перечислены GET /servicePrincipals с фильтром для списка идентичностей, DELETE /servicePrincipals/{id} для удаления Agent Identity и BlueprintPrincipal, а также DELETE /applications/{id} для удаления blueprint. До OAuth2-scoping нужно задать blueprint поле identifierUris в форме api://{app-id}. Для регистрации приложения и идентичностей требуются разрешения Application.ReadWrite.All, AgentIdentityBlueprint.Create, AgentIdentityBlueprint.ReadWrite.All, AgentIdentityBlueprintPrincipal.Create, AgentIdentity.Create.All и AgentIdentity.ReadWrite.All. В исходном материале указано, что в Graph существует 18 специфичных Agent Identity application permissions; полный список можно получить через appRoles service principal Microsoft Graph и выбрать значения с AgentIdentity. Сценарии применения зависят от типа интеграции. PowerShell подходит для интерактивной настройки с delegated scopes и явным переключением Graph на beta API. Python-поток подходит для автоматического создания объектов с application permissions и последующего OAuth2-доступа. Для polyglot-агентов описан Microsoft Entra SDK for AgentID в виде контейнеризованного sidecar, который можно подключать в Docker или Kubernetes; рядом указаны сценарии интеграции стороннего агента, автономного агента и интерактивного агента. Для production-авторизации следует рассматривать федерацию рабочей нагрузки, а секрет приложения — только как локальный вариант с контролем хранения и ротации. У preview есть практические ограничения. После выдачи admin consent разрешения могут распространяться с задержкой; исходный skill рекомендует ждать 30–120 секунд и повторять запрос с backoff при HTTP 403. Admin consent иногда возвращает 404 до репликации service principal. Удаление требует правильного порядка: сначала найти и удалить Agent Identity, затем связанные service principals, затем blueprint. Перед созданием нужно проверить уже существующие ресурсы, sponsor User, beta-версию API, OData-Version и набор разрешений. Официальная документация Microsoft для setup, AI-guided setup и SDK вынесена в ссылки исходного репозитория; текущая карточка пересказывает проверяемые положения опубликованного SKILL.md и не заменяет документацию Microsoft или проверку preview API в конкретном tenant.