Identités d’agent : modèles d’agent autonomes et interactifs

Les identités d’agent permettent des scénarios d’authentification sophistiqués où une application agent agit de manière autonome ou au nom des utilisateurs. En utilisant des identités d’agent avec le KIT de développement logiciel (SDK) Microsoft Entra pour AgentID, vous pouvez créer des agents autonomes qui fonctionnent dans leur propre contexte et des agents interactifs qui agissent pour le compte des utilisateurs. Pour faciliter ces scénarios, le SDK prend en charge des paramètres de requête spécifiques pour spécifier des identités d’agent et des contextes utilisateur.

Pour obtenir des instructions détaillées sur les identités d’agent, consultez la documentation Microsoft de la plateforme d’identités d’agent.

Aperçu

Les identités d’agent prennent en charge deux modèles principaux :

Agent autonome : l’agent fonctionne dans son propre contexte d’application.
Agent interactif : un agent interactif fonctionne pour le compte d’un utilisateur.

Le Kit de développement logiciel (SDK) accepte trois paramètres de requête facultatifs :

AgentIdentity - GUID de l’identité de l’agent.
AgentUsername - Nom d’utilisateur principal (UPN) pour un utilisateur spécifique.
AgentUserId - ID d’objet utilisateur (OID) pour un utilisateur spécifique, comme alternative à UPN.

Règles de précédence

AgentUsername et AgentUserId s’excluent mutuellement. Les demandes qui incluent les deux paramètres échouent à la validation, comme décrit dans la règle 2 : exclusivité mutuelle. Fournissez un seul de ces paramètres par requête.

configuration de Microsoft Entra ID

Avant de configurer des identités d’agent dans votre application, configurez les composants nécessaires dans Microsoft Entra ID. Pour inscrire une nouvelle application dans le tenant Microsoft Entra ID, consultez Inscrire une application.

Conditions préalables pour les identités d’agent

Enregistrement de l’application d’agent :
- Inscrivez l’application de l’agent parent dans Microsoft Entra ID.
- Configurez les autorisations d’API pour les API en aval.
- Configurez les informations d’identification du client (FIC+MSI, certificat ou secret).
Configuration de l’identité de l’agent :
- Créez des identités d’agent à l’aide du modèle d’agent.
- Attribuez les autorisations nécessaires aux identités des agents.
Autorisations d’application :
- Accordez des autorisations d’application pour les scénarios autonomes.
- Accordez des autorisations déléguées pour les scénarios de délégation d’utilisateur.
- Vérifiez que le consentement de l’administrateur est fourni si nécessaire.

Pour obtenir des instructions détaillées sur la configuration des identités d’agent dans Microsoft Entra ID, consultez la documentation Microsoft de la plateforme d’identités d’agent.

Règles sémantiques

Pour vous authentifier correctement, vous devez utiliser correctement les paramètres d’identité de l’agent. Les règles suivantes régissent l'utilisation des paramètres AgentIdentity, AgentUsername, et AgentUserId. Suivez ces règles pour éviter les erreurs de validation retournées par le Kit de développement logiciel (SDK).

Règle 1 : Exigence d’AgentIdentity

AgentUsername ou AgentUserId doit être jumelé avec AgentIdentity.

Si vous spécifiez AgentUsername ou AgentUserId sans AgentIdentity, la requête échoue avec une erreur de validation.

# INVALID - AgentUsername without AgentIdentity
GET /AuthorizationHeader/Graph?AgentUsername=user@contoso.com

# VALID - AgentUsername with AgentIdentity
GET /AuthorizationHeader/Graph?AgentIdentity=agent-client-id&AgentUsername=user@contoso.com

Règle 2 : Exclusivité mutuelle

AgentUsername et AgentUserId sont des paramètres mutuellement exclusifs.

Vous ne pouvez pas spécifier les deux AgentUsername et AgentUserId dans la même requête. Si vous fournissez les deux paramètres, la requête échoue avec une erreur de validation.

# INVALID - Both AgentUsername and AgentUserId specified
GET /AuthorizationHeader/Graph?AgentIdentity=agent-id&AgentUsername=user@contoso.com&AgentUserId=user-oid

# VALID - Only AgentUsername
GET /AuthorizationHeader/Graph?AgentIdentity=agent-id&AgentUsername=user@contoso.com

# VALID - Only AgentUserId
GET /AuthorizationHeader/Graph?AgentIdentity=agent-id&AgentUserId=user-object-id

Règle 3 : Autonome et interactif

La combinaison de paramètres détermine le modèle d’authentification :

Paramètres	Motif	Descriptif
`AgentIdentity` uniquement	Agent autonome	Acquiert le jeton d’application pour l’identité de l’agent
`AgentIdentity` + `AgentUsername`	Agent interactif	Acquiert le jeton utilisateur pour l’utilisateur spécifié (par UPN)
`AgentIdentity` + `AgentUserId`	Agent interactif	Acquiert le jeton utilisateur pour l’utilisateur spécifié (par ID d’objet)

Exemples :

# Autonomous agent - application context
GET /AuthorizationHeader/Graph?AgentIdentity=agent-id

# Interactive agent - user context by username
GET /AuthorizationHeader/Graph?AgentIdentity=agent-id&AgentUsername=user@contoso.com

# Interactive agent - user context by user ID
GET /AuthorizationHeader/Graph?AgentIdentity=agent-id&AgentUserId=user-object-id

Modèles d’utilisation

Pour chaque modèle d’utilisation, la combinaison de paramètres détermine le flux d’authentification et le type de jeton acquis.

Modèle 1 : Agent autonome

L’application de l’agent s’exécute indépendamment dans son propre contexte d’application et obtient des jetons d’application.

Scénario : service de traitement par lots qui traite les fichiers par lui-même.

GET /AuthorizationHeader/Graph?AgentIdentity=12345678-1234-1234-1234-123456789012

Caractéristiques du jeton :

Type de jeton : jeton d’application
Objet (sub) : ID d’objet de l’application agent
Jeton créé pour l’identité de l’agent
Autorisations : autorisations d’application affectées à l’identité de l’agent

Cas d’usage :

Traitement par lots automatisé
Tâches en arrière-plan
Opérations système à système
Travaux planifiés sans contexte utilisateur

Modèle 2 : Agent utilisateur autonome (par nom d’utilisateur)

L’agent s’exécute pour le compte d’un utilisateur spécifique identifié par son UPN.

Scénario : Assistant IA qui agit pour le compte d’un utilisateur dans une application de conversation.

GET /AuthorizationHeader/Graph?AgentIdentity=12345678-1234-1234-1234-123456789012&AgentUsername=alice@contoso.com

Caractéristiques du jeton :

Type de jeton : jeton utilisateur
Objet (sub) : ID d’objet de l’utilisateur
Facette d’identité de l’agent incluse dans les revendications de jeton
Autorisations : autorisations interactives limitées à l’utilisateur

Cas d’usage :

Applications d’agent interactif
Assistants IA avec délégation d’utilisateur
Automatisation délimitée par l’utilisateur
Flux de travail personnalisés

Modèle 3 : Agent utilisateur autonome (par ID d’objet)

L’agent fonctionne pour le compte d’un utilisateur spécifique identifié par son ID d’objet.

Scénario : moteur de flux de travail qui traite des tâches spécifiques à l’utilisateur à l’aide des ID utilisateur stockés.

GET /AuthorizationHeader/Graph?AgentIdentity=12345678-1234-1234-1234-123456789012&AgentUserId=87654321-4321-4321-4321-210987654321

Caractéristiques du jeton :

Type de jeton : jeton utilisateur
Objet (sub) : ID d’objet de l’utilisateur
Facette d’identité de l’agent incluse dans les revendications de jeton
Autorisations : autorisations interactives limitées à l’utilisateur

Cas d’usage :

Flux de travail de longue durée avec identificateurs d’utilisateur stockés
Opérations batch pour le compte de plusieurs utilisateurs
Systèmes qui utilisent des ID d’objet pour référence utilisateur

Modèle 4 : Agent interactif (agissant pour le compte de l’utilisateur qui l’appelle)

Une API web agent reçoit un jeton d’utilisateur, le valide et effectue des appels délégués pour le compte de cet utilisateur.

Scénario : UNE API web agissant en tant qu’agent interactif validant les jetons utilisateur entrants et en effectuant des appels délégués aux services en aval.

Flux :

L’API web agent reçoit le jeton utilisateur de l’application appelante.
Valide le jeton via le point de terminaison /Validate.
Acquiert des jetons pour les API en aval en effectuant un appel à /AuthorizationHeader en utilisant uniquement l'en-tête d'autorisation entrant AgentIdentity.

# Step 1: Validate incoming user token
GET /Validate
Authorization: Bearer <user-token>

# Step 2: Get authorization header on behalf of the user
GET /AuthorizationHeader/Graph?AgentIdentity=<agent-client-id>
Authorization: Bearer <user-token>

Caractéristiques du jeton :

Type de jeton : jeton d'utilisateur (flux OBO)
Objet (sub) : ID d’objet de l’utilisateur d’origine
L’agent agit comme intermédiaire pour l’utilisateur
Autorisations : autorisations interactives limitées à l’utilisateur

Cas d’usage :

API web qui agissent en tant qu’agents
Services d’agent interactifs
Middleware basé sur agent qui délègue aux API en aval
Services qui valident et transfèrent le contexte utilisateur

Modèle 5 : Requête régulière (aucun agent)

Lorsque vous ne fournissez pas de paramètres d’agent, le Kit de développement logiciel (SDK) utilise l’identité du jeton entrant.

Scénario : processus standard de délégation (OBO) sans identités d’agent.

GET /AuthorizationHeader/Graph
Authorization: Bearer <user-token>

Caractéristiques du jeton :

Type de jeton : dépend du jeton entrant et de la configuration
Utilise le flux d'informations d'identification des clients ou le flux standard OBO
Aucune facette d’identité d’agent

Exemples de code

Les extraits de code suivants montrent comment implémenter les différents modèles d’identité d’agent à l’aide de différents langages de programmation et comment interagir avec les points de terminaison du SDK. Le code montre comment gérer les appels hors processus au Kit de développement logiciel (SDK) pour acquérir des en-têtes d’autorisation pour les appels d’API en aval.

TypeScript : Agent autonome

const sidecarUrl = "http://localhost:5000";
const Agent ID = "12345678-1234-1234-1234-123456789012";

async function runBatchJob() {
  const response = await fetch(
    `${sidecarUrl}/AuthorizationHeader/Graph?AgentIdentity=${agentId}`,
    {
      headers: {
        'Authorization': 'Bearer system-token'
      }
    }
  );
  
  const { authorizationHeader } = await response.json();
  // Use authorizationHeader for downstream API calls
}

Python : Agent avec identité utilisateur

import requests

sidecar_url = "http://localhost:5000"
agent_id = "12345678-1234-1234-1234-123456789012"
user_email = "alice@contoso.com"

response = requests.get(
    f"{sidecar_url}/AuthorizationHeader/Graph",
    params={
        "AgentIdentity": agent_id,
        "AgentUsername": user_email
    },
    headers={"Authorization": f"Bearer {system_token}"}
)

token = response.json()["authorizationHeader"]

TypeScript : Agent interactif

async function delegateCall(userToken: string) {
  // Validate incoming token
  const validation = await fetch(
    `${sidecarUrl}/Validate`,
    {
      headers: { 'Authorization': `Bearer ${userToken}` }
    }
  );
  
  const claims = await validation.json();
  
  // Call downstream API on behalf of user
  const response = await fetch(
    `${sidecarUrl}/DownstreamApi/Graph`,
    {
      headers: { 'Authorization': `Bearer ${userToken}` }
    }
  );
  
  return await response.json();
}

C# avec HttpClient

using System.Net.Http;

var httpClient = new HttpClient();

// Autonomous agent
var autonomousUrl = $"http://localhost:5000/AuthorizationHeader/Graph" +
    $"?AgentIdentity={agentClientId}";
var response = await httpClient.GetAsync(autonomousUrl);

// Delegated agent with username
var delegatedUrl = $"http://localhost:5000/AuthorizationHeader/Graph" +
    $"?AgentIdentity={agentClientId}" +
    $"&AgentUsername={Uri.EscapeDataString(userPrincipalName)}";
response = await httpClient.GetAsync(delegatedUrl);

// Delegated agent with user ID
var delegatedByIdUrl = $"http://localhost:5000/AuthorizationHeader/Graph" +
    $"?AgentIdentity={agentClientId}" +
    $"&AgentUserId={userObjectId}";
response = await httpClient.GetAsync(delegatedByIdUrl);

Scénarios d’erreur

Lorsque vous ne configurez pas les paramètres d’identité de l’agent ou que vous les utilisez de manière incorrecte, le SDK retourne des erreurs de validation. Les sections suivantes décrivent les scénarios d’erreur courants et leurs réponses correspondantes. Pour plus d’informations sur la gestion des erreurs, consultez le Guide de résolution des problèmes.

L'identité de l'agent est manquante avec le nom d'utilisateur de l'agent.

Requête :

GET /AuthorizationHeader/Graph?AgentUsername=user@contoso.com

Réponse :

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "Bad Request",
  "status": 400,
  "detail": "AgentUsername requires AgentIdentity to be specified"
}

AgentUsername et AgentUserId spécifiés

Requête :

GET /AuthorizationHeader/Graph?AgentIdentity=agent-id&AgentUsername=user@contoso.com&AgentUserId=user-oid

Réponse :

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "Bad Request",
  "status": 400,
  "detail": "AgentUsername and AgentUserId are mutually exclusive"
}

Format AgentUserId non valide

Requête :

GET /AuthorizationHeader/Graph?AgentIdentity=agent-id&AgentUserId=invalid-guid

Réponse :

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "Bad Request",
  "status": 400,
  "detail": "AgentUserId must be a valid GUID"
}

Bonnes pratiques

Valider l’entrée : validez toujours les paramètres d’identité de l’agent avant d’effectuer des requêtes.
Utilisez des ID d’objet lorsqu’ils sont disponibles : les ID d’objet sont plus stables.
Implémentez une gestion appropriée des erreurs : gérez correctement les erreurs de validation d’identité de l’agent.
Informations d’identification sécurisées de l’agent : Protéger les identifiants et informations d'identification de l’agent.
Opérations de l’agent d’audit : journaliser et surveiller l’utilisation de l’identité de l’agent pour la sécurité et la conformité.
Testez les deux modèles : validez les scénarios autonomes et délégués dans vos tests.
Intention du document : documentez clairement le modèle d’agent approprié pour chaque cas d’usage.

Commentaires

Cette page a-t-elle été utile ?

Last updated on 2026-04-19

Identités d’agent : modèles d’agent autonomes et interactifs

Aperçu

Règles de précédence

configuration de Microsoft Entra ID

Conditions préalables pour les identités d’agent

Règles sémantiques

Règle 1 : Exigence d’AgentIdentity

Règle 2 : Exclusivité mutuelle

Règle 3 : Autonome et interactif

Modèles d’utilisation

Modèle 1 : Agent autonome

Modèle 2 : Agent utilisateur autonome (par nom d’utilisateur)

Modèle 3 : Agent utilisateur autonome (par ID d’objet)

Modèle 4 : Agent interactif (agissant pour le compte de l’utilisateur qui l’appelle)

Modèle 5 : Requête régulière (aucun agent)

Exemples de code

TypeScript : Agent autonome

Python : Agent avec identité utilisateur

TypeScript : Agent interactif

C# avec HttpClient

Scénarios d’erreur

L'identité de l'agent est manquante avec le nom d'utilisateur de l'agent.

AgentUsername et AgentUserId spécifiés

Format AgentUserId non valide

Bonnes pratiques

Contenu connexe

Commentaires

Ressources supplémentaires