Microsoft Entra Agent ID

Créez et gérez des identités compatibles OAuth2 pour les agents IA en utilisant l'API Microsoft Graph beta.

API en préversion — Tous les endpoints Agent Identity se trouvent uniquement sous /beta. Non disponible dans /v1.0.

Avant de commencer

Recherchez microsoft-docs MCP pour la dernière documentation Agent ID :

• Requête : « Microsoft Entra agent identity setup »
• Vérification : Les paramètres API correspondent au comportement de préversion actuel

Modèle conceptuel

Agent Identity Blueprint (application)        ← un par type/projet d'agent
  └── BlueprintPrincipal (service principal)   ← DOIT être créé explicitement
        ├── Agent Identity (SP): agent-1       ← un par instance d'agent
        ├── Agent Identity (SP): agent-2
        └── Agent Identity (SP): agent-3

Prérequis

PowerShell (recommandé pour la configuration interactive)

# Requires PowerShell 7+
Install-Module Microsoft.Graph.Beta.Applications -Scope CurrentUser -Force

Python (pour le provisionnement programmatique)

pip install azure-identity requests

Rôles Entra requis

L'un des rôles suivants : Agent Identity Developer, Agent Identity Administrator, ou Application Administrator.

Variables d'environnement

AZURE_TENANT_ID=<your-tenant-id>
AZURE_CLIENT_ID=<app-registration-client-id>
AZURE_CLIENT_SECRET=<app-registration-secret>

Authentification

⚠️ DefaultAzureCredential n'est PAS supporté. Les tokens Azure CLI contiennent Directory.AccessAsUser.All, que les API Agent Identity rejettent explicitement (403). Vous DEVEZ utiliser une app registration dédiée avec le flux client_credentials ou vous connecter via Connect-MgGraph avec des scopes délégués explicites.

PowerShell (permissions délégués)

Connect-MgGraph -Scopes @(
    "AgentIdentityBlueprint.Create",
    "AgentIdentityBlueprint.ReadWrite.All",
    "AgentIdentityBlueprintPrincipal.Create",
    "User.Read"
)
Set-MgRequestContext -ApiVersion beta

$currentUser = (Get-MgContext).Account
$userId = (Get-MgUser -UserId $currentUser).Id

Python (permissions application)

import os
import requests
from azure.identity import ClientSecretCredential

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/beta"
headers = {
    "Authorization": f"Bearer {token.token}",
    "Content-Type": "application/json",
    "OData-Version": "4.0",  # Required for all Agent Identity API calls
}

Flux de travail principal

Étape 1 : Créer un Agent Identity Blueprint

Les sponsors sont obligatoires et doivent être des objets User — les ServicePrincipals et Groups sont rejetés.

import subprocess

# Get sponsor user ID (client_credentials has no user context, so use az CLI)
result = subprocess.run(
    ["az", "ad", "signed-in-user", "show", "--query", "id", "-o", "tsv"],
    capture_output=True, text=True, check=True,
)
user_id = result.stdout.strip()

blueprint_body = {
    "@odata.type": "Microsoft.Graph.AgentIdentityBlueprint",
    "displayName": "My Agent Blueprint",
    "sponsors@odata.bind": [
        f"https://graph.microsoft.com/beta/users/{user_id}"
    ],
}
resp = requests.post(f"{GRAPH}/applications", headers=headers, json=blueprint_body)
resp.raise_for_status()

blueprint = resp.json()
app_id = blueprint["appId"]
blueprint_obj_id = blueprint["id"]

Étape 2 : Créer un BlueprintPrincipal

Cette étape est obligatoire. Créer un Blueprint ne crée PAS automatiquement son service principal. Sans cela, la création d'Agent Identity échoue avec : 400: The Agent Blueprint Principal for the Agent Blueprint does not exist.

sp_body = {
    "@odata.type": "Microsoft.Graph.AgentIdentityBlueprintPrincipal",
    "appId": app_id,
}
resp = requests.post(f"{GRAPH}/servicePrincipals", headers=headers, json=sp_body)
resp.raise_for_status()

Si vous implémentez des scripts idempotents, vérifiez et créez le BlueprintPrincipal même si le Blueprint existe déjà (une exécution précédente peut avoir créé le Blueprint mais échoué avant la création du SP).

Étape 3 : Créer des Agent Identities

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

Référence API

Tous les endpoints utilisent l'URL de base : https://graph.microsoft.com/beta

Permissions requises

Il y a 18 permissions application spécifiques à Agent Identity. Découvrez toutes :

az ad sp show --id 00000003-0000-0000-c000-000000000000 \
  --query "appRoles[?contains(value, 'AgentIdentity')].{id:id, value:value}" -o json

Accorder le consentement administrateur (requis pour les permissions application) :

az ad app permission admin-consent --id <client-id>

Le consentement administrateur peut échouer avec 404 si le service principal n'a pas été répliqué. Réessayez avec un backoff de 10–40s.

Nettoyage

# Delete Agent Identity
requests.delete(f"{GRAPH}/servicePrincipals/{agent['id']}", headers=headers)

# Delete BlueprintPrincipal (get SP ID first)
sps = requests.get(
    f"{GRAPH}/servicePrincipals?$filter=appId eq '{app_id}'",
    headers=headers,
).json()
for sp in sps.get("value", []):
    requests.delete(f"{GRAPH}/servicePrincipals/{sp['id']}", headers=headers)

# Delete Blueprint
requests.delete(f"{GRAPH}/applications/{blueprint_obj_id}", headers=headers)

Bonnes pratiques

1. Toujours créer BlueprintPrincipal après Blueprint — pas de création automatique ; implémentez des vérifications idempotents sur les deux
2. Utiliser des objets User comme sponsors — les ServicePrincipals et Groups sont rejetés
3. Gérer les délais de propagation des permissions — après le consentement administrateur, attendre 30–120s ; réessayer avec backoff sur 403
4. Inclure l'en-tête OData-Version: 4.0 sur chaque requête Graph
5. Utiliser Workload Identity Federation pour l'authentification en production — pour le développement local, utiliser un client secret sur le Blueprint (voir references/oauth2-token-flow.md)
6. Définir identifierUris sur Blueprint avant d'utiliser la portée OAuth2 (api://{app-id})
7. Ne jamais utiliser les tokens Azure CLI pour les appels API — ils contiennent Directory.AccessAsUser.All qui est rejeté catégoriquement
8. Vérifier les ressources existantes avant de créer — implémentez un provisionnement idempotent

Références

Liens externes