Identità degli agenti: modelli di agente autonomi e interattivi

Le identità dell'agente consentono scenari di autenticazione sofisticati in cui un'applicazione agente agisce in modo autonomo o per conto degli utenti. Usando le identità degli agenti con l'SDK di Microsoft Entra per AgentID, è possibile creare agenti autonomi che operano nel proprio contesto e agenti interattivi che agiscono per conto degli utenti. Per facilitare questi scenari, l'SDK supporta parametri di query specifici per specificare le identità degli agenti e i contesti utente.

Per indicazioni dettagliate sulle identità degli agenti, vedere la documentazione di Microsoft Agent Identity Platform.

Informazioni generali

Le identità dell'agente supportano due modelli principali:

• Agente autonomo: l'agente opera nel proprio contesto dell'applicazione.
• Interactive Agent: un agente interattivo opera per conto di un utente.

L'SDK accetta tre parametri di query facoltativi:

• AgentIdentity - GUID dell'identità dell'agente.
• AgentUsername - Nome principale utente (UPN) per un determinato utente.
• AgentUserId - ID oggetto utente (OID) per un utente specifico, come alternativa all'UPN.

Regole di precedenza

AgentUsername e AgentUserId si escludono a vicenda. Le richieste che includono entrambi i parametri non superano la convalida, come descritto nella regola 2: esclusività reciproca. Specificare solo uno di questi parametri per ogni richiesta.

configurazione Microsoft Entra ID

Prima di configurare le identità dell'agente nell'applicazione, configurare i componenti necessari in Microsoft Entra ID. Per registrare una nuova applicazione nel tenant Microsoft Entra ID, vedere Registrare un'applicazione.

Prerequisiti per le identità dell'agente

1. Registrazione dell'applicazione agente:

   • Registrare l'applicazione agente padre in Microsoft Entra ID.
   • Configurare le autorizzazioni API per le API downstream.
   • Configurare le credenziali client (FIC+MSI, certificato o segreto).

2. Configurazione dell'identità dell'agente:

   • Creare identità dell'agente utilizzando il modello agente.
   • Assegnare le autorizzazioni necessarie alle identità degli agenti.

3. Autorizzazioni dell'applicazione:

   • Concedere le autorizzazioni dell'applicazione per scenari autonomi.
   • Concedere autorizzazioni delegate per gli scenari di delega utente.
   • Assicurarsi che il consenso dell'amministratore sia fornito dove necessario.

Per istruzioni dettagliate sulla configurazione delle identità degli agenti in Microsoft Entra ID, vedere la documentazione di Microsoft agent Identity Platform.

Regole semantiche

Per eseguire correttamente l'autenticazione, è necessario usare correttamente i parametri identity dell'agente. Le regole seguenti regolano l'uso dei AgentIdentityparametri , AgentUsernamee AgentUserId . Seguire queste regole per evitare errori di convalida restituiti dall'SDK.

Regola 1: Requisito di AgentIdentity

AgentUsername o AgentUserId deve essere associato a AgentIdentity.

Se si specifica AgentUsername o AgentUserId senza AgentIdentity, la richiesta ha esito negativo con un errore di convalida.

# 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

Regola 2: Esclusività reciproca

AgentUsername e AgentUserId sono parametri che si escludono a vicenda.

Non è possibile specificare sia che AgentUsernameAgentUserId nella stessa richiesta. Se si specificano entrambi i parametri, la richiesta ha esito negativo con un errore di convalida.

# 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

Regola 3: Autonomo e interattivo

La combinazione di parametri determina il modello di autenticazione:

Esempi:

# 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

Modelli di utilizzo

Per ogni modello di utilizzo, la combinazione di parametri determina il flusso di autenticazione e il tipo di token acquisito.

Modello 1: agente autonomo

L'applicazione agente viene eseguita in modo indipendente nel proprio contesto dell'applicazione e ottiene i token dell'applicazione.

Scenario: servizio di elaborazione batch che elabora i file autonomamente.

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

Caratteristiche del token:

• Tipo di token: token dell'applicazione
• Oggetto (sub): ID oggetto dell'applicazione Agent
• Token creato per l'identità dell'agente
• Autorizzazioni: autorizzazioni dell'applicazione assegnate all'identità dell'agente

Casi d'uso:

• Elaborazione batch automatizzata
• Attività in background
• Operazioni da sistema a sistema
• Processi pianificati senza contesto utente

Modello 2: agente utente autonomo (per nome utente)

L'agente viene eseguito per conto di un utente specifico identificato dal relativo UPN.

Scenario: assistente di intelligenza artificiale che agisce per conto di un utente in un'applicazione di chat.

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

Caratteristiche del token:

• Tipo di token: token utente
• Subject (sub): ID oggetto dell'utente
• Facet dell'identità dell'agente incluse nelle attestazioni del token
• Autorizzazioni: autorizzazioni interattive limitate all'utente

Casi d'uso:

• Applicazioni dell'agente interattivo
• Assistenti di intelligenza artificiale con delega utente
• Automazione a livello utente
• Flussi di lavoro personalizzati

Modello 3: agente utente autonomo (tramite ID oggetto)

L'agente funziona per conto di un utente specifico identificato dal relativo ID oggetto.

Scenario: motore del flusso di lavoro che elabora attività specifiche dell'utente usando GLI ID utente archiviati.

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

Caratteristiche del token:

• Tipo di token: token utente
• Subject (sub): ID oggetto dell'utente
• Facet dell'identità dell'agente incluse nelle attestazioni del token
• Autorizzazioni: autorizzazioni interattive limitate all'utente

Casi d'uso:

• Flussi di lavoro a esecuzione prolungata con identificatori utente archiviati
• Operazioni batch per conto di più utenti
• Sistemi che usano ID oggetto per informazioni di riferimento sugli utenti

Modello 4: Agente interattivo (che agisce per conto dell'utente che lo chiama)

Un'API Web dell'agente riceve un token utente, lo convalida e effettua chiamate delegate per conto di tale utente.

Scenario: un'API Web che funge da agente interattivo che convalida i token utente in ingresso e effettua chiamate delegate ai servizi downstream.

Flusso:

1. L'API Web di Agent riceve il token utente dall'applicazione chiamante.
2. Convalida il token tramite l'endpoint /Validate .
3. Acquisisce i token per le API downstream chiamando /AuthorizationHeader con solo AgentIdentity e l'intestazione di autorizzazione in ingresso.

# 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>

Caratteristiche del token:

• Tipo di token: token utente (flusso OBO)
• Subject (sub): ID oggetto dell'utente originale
• Agent funge da intermediario per l'utente
• Autorizzazioni: autorizzazioni interattive destinate all'utente

Casi d'uso:

• API Web che fungono da agenti
• Servizi interattivi dell'agente
• Middleware basato su agente che delega alle API downstream
• Servizi che convalidano e inoltrano il contesto utente

Modello 5: richiesta regolare (nessun agente)

Quando non si forniscono parametri dell'agente, l'SDK usa l'identità del token in ingresso.

Scenario: flusso OBO (Standard on-behalf-of) senza identità dell'agente.

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

Caratteristiche del token:

• Tipo di token: dipende dal token e dalla configurazione in ingresso
• Usa lo standard OBO o il flusso di credenziali client
• Nessun aspetto di identità dell'agente

Esempi di codice

I frammenti di codice seguenti illustrano come implementare i diversi modelli di identità dell'agente usando vari linguaggi di programmazione e come interagire con gli endpoint SDK. Il codice illustra come gestire le chiamate out-of-process all'SDK per acquisire le intestazioni di autorizzazione per le chiamate API downstream.

TypeScript: agente autonomo

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: agente con identità utente

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: Agente interattivo

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# con 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);

Scenari di errore

Quando si configurano in modo errato i parametri di identità dell'agente o li si usa in modo non corretto, l'SDK restituisce errori di convalida. Le sezioni seguenti descrivono gli scenari di errore comuni e le risposte corrispondenti. Per altre informazioni sulla gestione degli errori, vedere la Guida alla risoluzione dei problemi.

AgentIdentity mancante con AgentUsername

Richiesta:

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

Risposta:

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

Sia AgentUsername che AgentUserId specificati

Richiesta:

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

Risposta:

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

Formato AgentUserId non valido

Richiesta:

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

Risposta:

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

Procedure consigliate

1. Convalidare l'input: convalidare sempre i parametri identity dell'agente prima di effettuare richieste.
2. Usa ID oggetto quando disponibili: gli ID oggetto sono più stabili.
3. Implementare la gestione degli errori corretta: gestire gli errori di convalida dell'identità dell'agente normalmente.
4. Proteggi le credenziali degli agenti: Proteggi gli ID client dell'identità degli agenti e le credenziali.
5. Operazioni dell'agente di controllo: registrare e monitorare l'utilizzo delle identità dell'agente per la sicurezza e la conformità.
6. Testare entrambi i modelli: convalidare scenari autonomi e delegati nei test.
7. Scopo del documento: documentare chiaramente quale modello di agente è appropriato per ogni caso d'uso.

Contenuti correlati

• Informazioni di riferimento sugli endpoint
• Informazioni di riferimento sulla configurazione
• Scenario: Elaborazione batch automatizzata dell'agente
• Microsoft Agent Identity Platform