Microsoft Entra Agent ID

Создавайте и управляйте OAuth 2.0-идентификаторами для AI-агентов через Microsoft Graph. Каждый экземпляр агента получает отдельный идентификатор, журнал аудита и независимо ограниченные права.

Быстрый справочник

Когда использовать

• Создание нового Agent Identity Blueprint и BlueprintPrincipal
• Создание экземпляров Agent Identity в рамках Blueprint
• Настройка учётных данных (FIC, Managed Identity, client secret) на Blueprint
• Реализация двухшагового fmi_path runtime-обмена токенов (автономный или OBO)
• Кросс-тенантные потоки токенов агента
• Развёртывание sidecar-а Microsoft Entra SDK for AgentID для polyglot-агентов
• Выдача прав на уровне Agent Identity (appRoleAssignments или oauth2PermissionGrants)
• Диагностика ошибок: AADSTS82001, AADSTS700211, PropertyNotCompatibleWithAgentIdentity

Концептуальная модель

Agent Identity Blueprint (application)         ← один на тип/проект агента
  └── BlueprintPrincipal (service principal)    ← ОБЯЗАТЕЛЬНО создавать явно
        ├── Agent Identity (SP): agent-1        ← по одному на экземпляр агента
        ├── Agent Identity (SP): agent-2
        └── Agent Identity (SP): agent-3

Аутентификация

DefaultAzureCredential не поддерживается. Токены Azure CLI содержат Directory.AccessAsUser.All, что жёстко отклоняется (403) API Agent Identity. Используйте выделенную регистрацию приложения с client_credentials.

PowerShell (делегированный)

Connect-MgGraph -Scopes @(
    "AgentIdentityBlueprint.Create",
    "AgentIdentityBlueprint.ReadWrite.All",
    "AgentIdentityBlueprintPrincipal.Create",
    "AgentIdentity.Create.All",
    "User.Read"
)

Python (приложение)

from azure.identity import ClientSecretCredential
import requests, os

credential = ClientSecretCredential(
    tenant_id=os.environ["AZURE_TENANT_ID"],
    client_id=os.environ["AZURE_CLIENT_ID"],
    client_secret=os.environ["AZURE_CLIENT_SECRET"],
)
token = credential.get_token("https://graph.microsoft.com/.default")
GRAPH = "https://graph.microsoft.com/v1.0"
headers = {
    "Authorization": f"Bearer {token.token}",
    "Content-Type": "application/json",
    "OData-Version": "4.0",
}

Основной рабочий процесс

Шаг 1: Создать Agent Identity Blueprint

blueprint_body = {
    "displayName": "My Agent Blueprint",
    "sponsors@odata.bind": [
        f"https://graph.microsoft.com/v1.0/users/{user_id}"
    ],
}
resp = requests.post(
    f"{GRAPH}/applications/microsoft.graph.agentIdentityBlueprint",
    headers=headers, json=blueprint_body,
)
resp.raise_for_status()
blueprint = resp.json()
app_id = blueprint["appId"]

Шаг 2: Создать BlueprintPrincipal

Обязательно. Создание Blueprint НЕ создаёт автоматически service principal. Пропуск этого шага даёт: 400: The Agent Blueprint Principal for the Agent Blueprint does not exist.

resp = requests.post(
    f"{GRAPH}/servicePrincipals/microsoft.graph.agentIdentityBlueprintPrincipal",
    headers=headers, json={"appId": app_id},
)
resp.raise_for_status()

Шаг 3: Создать Agent Identity

agent_body = {
    "displayName": "my-agent-instance-1",
    "agentIdentityBlueprintId": app_id,
    "sponsors@odata.bind": [f"https://graph.microsoft.com/v1.0/users/{user_id}"],
}
resp = requests.post(
    f"{GRAPH}/servicePrincipals/microsoft.graph.agentIdentity",
    headers=headers, json=agent_body,
)
resp.raise_for_status()
agent_sp_id = resp.json()["id"]

Runtime-аутентификация

Агенты аутентифицируются через учётные данные, настроенные на Blueprint (не на Agent Identity — они не могут хранить учётные данные).

.NET: используйте Microsoft.Identity.Web.AgentIdentities — обрабатывает FIC и двухшаговый обмен автоматически.

Выдача прав (на уровне Agent Identity)

Права приложения (автономный)

requests.post(
    f"{GRAPH}/servicePrincipals/{agent_sp_id}/appRoleAssignments",
    headers=headers,
    json={
        "principalId": agent_sp_id,
        "resourceId": graph_sp["id"],
        "appRoleId": user_read_all["id"],
    },
).raise_for_status()

Делегированные права (OBO)

requests.post(
    f"{GRAPH}/oauth2PermissionGrants",
    headers=headers,
    json={
        "clientId": agent_sp_id,
        "consentType": "AllPrincipals",
        "resourceId": graph_sp["id"],
        "scope": "User.Read Tasks.ReadWrite Mail.Send",
        "expiryTime": expiry,
    },
).raise_for_status()

Браузерные URL admin consent не работают для Agent Identities — используйте oauth2PermissionGrants для программного делегированного согласия.

Кросс-тенантные Agent Identities

Шаг 1 обмена родительского токена ДОЛЖЕН нацеливаться на home-тенант Agent Identity, а не Blueprint. Неверный тенант → AADSTS700211: No matching federated identity record found.

API-справочник

Устранение неполадок

Лучшие практики

1. Всегда создавайте BlueprintPrincipal после Blueprint — не создаётся автоматически
2. Используйте типизированные эндпоинты (/applications/microsoft.graph.agentIdentityBlueprint)
3. Учётные данные — только на Blueprint (Agent Identities не могут хранить секреты)
4. Включайте OData-Version: 4.0 в каждый запрос к Graph
5. WIF для продакшна, client secrets — только для локальной разработки
6. Никогда не используйте токены Azure CLI для API Agent Identity
7. Используйте fmi_path с client_credentials, а не RFC 8693
8. Всегда используйте scope /.default в обоих шагах обмена
9. Выдавайте права на уровне каждого Agent Identity, а не BlueprintPrincipal
10. Обрабатывайте задержки распространения прав — повторяйте 403 с паузой 30–120 с
11. Держите Entra SDK for AgentID на localhost — никогда не открывайте через LoadBalancer