Tożsamości agentów: wzorce agentów autonomicznych i interakcyjnych

Tożsamości agentów umożliwiają zaawansowane scenariusze uwierzytelniania, w których aplikacja agenta działa autonomicznie lub w imieniu użytkowników. Korzystając z tożsamości agentów w zestawie SDK uwierzytelniania Microsoft Entra ID (sidecar), można tworzyć zarówno agentów autonomicznych działających we własnym kontekście, jak i agentów interaktywnych działających w imieniu użytkowników. Aby ułatwić te scenariusze, zestaw SDK obsługuje określone parametry zapytania w celu określenia tożsamości agenta i kontekstów użytkownika.

Aby uzyskać szczegółowe wskazówki dotyczące tożsamości agentów, zobacz dokumentację platformy tożsamości agenta Microsoft.

Przegląd

Tożsamości agentów wspierają dwa podstawowe wzorce:

  • Agent autonomiczny: agent działa we własnym kontekście aplikacji.
  • Agent interaktywny: agent interaktywny działa w imieniu użytkownika.

Zestaw SDK akceptuje trzy opcjonalne parametry zapytania:

  • AgentIdentity - Identyfikator GUID tożsamości agenta.
  • AgentUsername - Główna nazwa użytkownika (UPN) dla określonego użytkownika.
  • AgentUserId - Identyfikator obiektu użytkownika (OID) dla określonego użytkownika, jako alternatywa dla nazwy UPN.

Reguły pierwszeństwa

AgentUsername i AgentUserId wzajemnie się wykluczają. Żądania, które zawierają oba parametry, nie przechodzą walidacji, jak opisano w regule 2: wzajemnej wyłączności. Podaj tylko jeden z tych parametrów na żądanie.

konfiguracja Microsoft Entra ID

Przed skonfigurowaniem tożsamości agentów w aplikacji skonfiguruj niezbędne składniki w Microsoft Entra ID. Aby zarejestrować nową aplikację w dzierżawie Microsoft Entra ID, zobacz sekcję Zarejestruj aplikację.

Wymagania wstępne dotyczące tożsamości agentów

  1. Rejestracja aplikacji agenta:

    • Zarejestruj aplikację agenta nadrzędnego w Microsoft Entra ID.
    • Konfigurowanie uprawnień interfejsu API dla API podrzędnych.
    • Skonfiguruj poświadczenia klienta (FIC+MSI, certyfikat lub tajne hasło).
  2. Konfiguracja tożsamości agenta:

    • Tworzenie tożsamości agenta przy użyciu strategii agenta.
    • Przypisz niezbędne uprawnienia do tożsamości agenta.
  3. Uprawnienia aplikacji:

    • Przyznawanie uprawnień aplikacji w scenariuszach autonomicznych.
    • Przyznawanie delegowanych uprawnień dla scenariuszy delegowania użytkowników.
    • Upewnij się, że zgoda administratora jest podana tam, gdzie jest to wymagane.

Aby uzyskać szczegółowe instrukcje krok po kroku dotyczące konfigurowania tożsamości agentów w Microsoft Entra ID, zobacz dokumentację platformy tożsamości agenta Microsoft.

Reguły semantyczne

Aby pomyślnie przeprowadzić uwierzytelnianie, należy prawidłowo użyć parametrów tożsamości agenta. Poniższe reguły określają użycie parametrów AgentIdentity, AgentUsernamei AgentUserId . Postępuj zgodnie z tymi regułami, aby uniknąć błędów walidacji zwracanych przez zestaw SDK.

Reguła 1: Wymaganie dotyczące AgentIdentity

AgentUsername lub AgentUserId musi być sparowany z AgentIdentity.

W przypadku określenia AgentUsername lub AgentUserId bez AgentIdentity, żądanie zakończy się niepowodzeniem z powodu błędu weryfikacji.

# 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

Reguła 2. Wzajemne wyłączność

AgentUsername i AgentUserId są wzajemnie wykluczające się parametry.

Nie można określić jednocześnie AgentUsername i AgentUserId w tym samym żądaniu. Jeśli podasz oba parametry, żądanie zakończy się niepowodzeniem z powodu błędu weryfikacji.

# 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

Reguła 3. Autonomiczna a interaktywna

Kombinacja parametrów określa wzorzec uwierzytelniania:

Parametry Wzór Description
AgentIdentity tylko Agent autonomiczny Uzyskuje token aplikacji dla tożsamości agenta
AgentIdentity + AgentUsername Agent interaktywny Uzyskuje token użytkownika dla określonego użytkownika (według UPN)
AgentIdentity + AgentUserId Agent interaktywny Uzyskuje token użytkownika dla określonego użytkownika (według identyfikatora obiektu)

Przykłady:

# 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

Wzorce użycia

Dla każdego wzorca użycia kombinacja parametrów określa przepływ uwierzytelniania i typ uzyskanego tokenu.

Wzorzec 1. Agent autonomiczny

Aplikacja agenta działa niezależnie w kontekście własnej aplikacji i pobiera tokeny aplikacji.

Scenariusz: usługa przetwarzania wsadowego, która przetwarza pliki samodzielnie.

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

Cechy tokenu:

  • Typ tokenu: token aplikacji
  • Temat (sub): identyfikator obiektu aplikacji agenta
  • Token utworzony dla tożsamości agenta
  • Uprawnienia: uprawnienia aplikacji przypisane do tożsamości agenta

Przypadki użycia:

  • Automatyczne przetwarzanie wsadowe
  • Zadania w tle
  • Operacje między systemami
  • Zaplanowane zadania bez kontekstu użytkownika

Wzorzec 2: autonomiczny agent użytkownika (według nazwy użytkownika)

Agent jest uruchamiany w imieniu określonego użytkownika zidentyfikowanego przez UPN.

Scenariusz: Asystent sztucznej inteligencji, który działa w imieniu użytkownika w aplikacji do czatu.

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

Cechy tokenu:

  • Typ tokenu: token użytkownika
  • Temat (sub): identyfikator obiektu użytkownika
  • Aspekt tożsamości agenta uwzględniony w żądaniach tokenu
  • Uprawnienia: uprawnienia interakcyjne ograniczone do użytkownika

Przypadki użycia:

  • Aplikacje agentów interaktywnych
  • Asystenci sztucznej inteligencji z delegowaniem użytkowników
  • Automatyzacja w zakresie użytkownika
  • Spersonalizowane przepływy pracy

Wzorzec 3: autonomiczny agent użytkownika (według identyfikatora obiektu)

Agent działa w imieniu określonego użytkownika zidentyfikowanego przez jego identyfikator obiektu.

Scenariusz: aparat przepływu pracy, który przetwarza zadania specyficzne dla użytkownika przy użyciu przechowywanych identyfikatorów użytkowników.

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

Cechy tokenu:

  • Typ tokenu: token użytkownika
  • Temat (sub): identyfikator obiektu użytkownika
  • Aspekt tożsamości agenta uwzględniony w żądaniach tokenu
  • Uprawnienia: uprawnienia interakcyjne ograniczone do użytkownika

Przypadki użycia:

  • Długotrwałe przepływy pracy z przechowywanymi identyfikatorami użytkowników
  • Operacje wsadowe wykonywane w imieniu wielu użytkowników
  • Systemy korzystające z identyfikatorów obiektów na potrzeby dokumentacji użytkownika

Wzorzec 4: Agent interaktywny (działający w imieniu użytkownika wywołującego go)

Internetowy interfejs API agenta odbiera token użytkownika, weryfikuje go i wykonuje delegowane wywołania w imieniu tego użytkownika.

Scenariusz: internetowy interfejs web API działający jako agent interaktywny, weryfikując przychodzące tokeny użytkownika i wykonując delegowane wywołania do usług docelowych.

Przepływ:

  1. Internetowy interfejs API agenta odbiera token użytkownika z aplikacji wywołującej.
  2. Weryfikuje token za pośrednictwem punktu końcowego /Validate .
  3. Uzyskuje tokeny dla podrzędnych interfejsów API przez wywołanie /AuthorizationHeader, używając AgentIdentity oraz nagłówka autoryzacji.
# 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>

Cechy tokenu:

  • Typ tokenu: token użytkownika (przepływ OBO)
  • Temat (sub): identyfikator obiektu oryginalnego użytkownika
  • Agent działa jako pośrednik dla użytkownika
  • Uprawnienia: uprawnienia interakcyjne ograniczone do użytkownika

Przypadki użycia:

  • Internetowe interfejsy API, które działają jako agenty
  • Usługi agenta interaktywnego
  • Oprogramowanie pośredniczące oparte na agencie, które przesyła zadania do interfejsów API położonych niżej w hierarchii
  • Usługi weryfikujące i przekazujące kontekst użytkownika

Wzorzec 5: Regularne żądanie (bez agenta)

Jeśli nie podasz parametrów agenta, zestaw SDK używa tożsamości tokenu przychodzącego.

Scenariusz: standardowy przepływ „w imieniu” (OBO) bez użycia tożsamości agenta.

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

Cechy tokenu:

  • Typ tokenu: zależy od tokenu przychodzącego i konfiguracji
  • Używa standardowego przepływu OBO lub przepływu poświadczeń klienta
  • Brak aspektów tożsamości agenta

Przykłady kodu

W poniższych fragmentach kodu pokazano, jak zaimplementować różne wzorce tożsamości agenta przy użyciu różnych języków programowania i jak korzystać z punktów końcowych zestawu SDK. Kod pokazuje, jak obsługiwać wywołania międzyprocesowe do pakietu SDK w celu uzyskania nagłówków autoryzacyjnych dla kolejnych wywołań API.

TypeScript: agent autonomiczny

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 z tożsamością użytkownika

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 interaktywny

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();
}

Język C# z klientem 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);

Scenariusze błędów

W przypadku błędnej konfiguracji parametrów tożsamości agenta lub nieprawidłowego użycia zestaw SDK zwraca błędy walidacji. W poniższych sekcjach opisano typowe scenariusze błędów i odpowiadające im odpowiedzi. Aby uzyskać więcej informacji na temat obsługi błędów, zobacz Przewodnik rozwiązywania problemów.

Brak elementu AgentIdentity z elementem AgentUsername

Żądanie:

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

Odpowiedź:

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

Określono zarówno agentUsername, jak i AgentUserId

Żądanie:

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

Odpowiedź:

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

Nieprawidłowy format AgentUserId

Żądanie:

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

Odpowiedź:

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

Najlepsze rozwiązania

  1. Sprawdź poprawność danych wejściowych: zawsze weryfikuj parametry tożsamości agenta przed wykonaniem żądań.
  2. Użyj identyfikatorów obiektów, jeśli są dostępne: identyfikatory obiektów są bardziej stabilne.
  3. Implementowanie prawidłowej obsługi błędów: Sprawnie obsługiwanie błędów weryfikacji tożsamości agenta.
  4. Bezpieczne poświadczenia agenta: Chroń identyfikatory klientów i poświadczenia tożsamości agenta.
  5. Operacje agenta inspekcji: Rejestrowanie i monitorowanie użycia tożsamości agenta pod kątem zabezpieczeń i zgodności.
  6. Przetestuj oba wzorce: zweryfikuj zarówno scenariusze autonomiczne, jak i delegowane w testach.
  7. Intencja dokumentu: jasno udokumentować, który wzorzec agenta jest odpowiedni dla każdego przypadku użycia.