Udostępnij przez

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

Tożsamości agentów umożliwiają zaawansowane scenariusze uwierzytelniania, w których aplikacja agenta działa autonomicznie lub w imieniu użytkowników. Używanie tożsamości agentów z zestawem Microsoft Entra SDK for AgentID umożliwia korzystanie zarówno z 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 firmy 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

Jeśli zarówno AgentUsername jak i AgentUserId są obecne, mimo że weryfikacja temu zapobiegnie, implementacja daje pierwszeństwo nazwie użytkownika.

AgentUsername > AgentUserId

Należy jednak unikać podawania zarówno AgentUsername, jak i AgentUserId, co spowoduje błąd walidacji w trybie ścisłej walidacji.

Konfiguracja identyfikatora Entra firmy Microsoft

Przed skonfigurowaniem tożsamości agentów w aplikacji należy skonfigurować niezbędne składniki w usłudze Microsoft Entra ID. Aby zarejestrować nową aplikację w dzierżawie Microsoft Entra ID, odwiedź Rejestrowanie aplikacji aby uzyskać więcej informacji.

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

  1. Rejestracja aplikacji agenta:

    • Zarejestruj aplikację agenta nadrzędnego w Microsoft Entra ID
    • Skonfiguruj uprawnienia API dla API poniżej w łańcuchu
    • Skonfiguruj poświadczenia klienta (FIC+MSI lub certyfikat lub klucz tajny)

  2. Konfiguracja tożsamości agenta:

    • Tworzenie tożsamości agentów przy użyciu strategii agenta
    • Przypisywanie niezbędnych uprawnień do tożsamości agentów

  3. Uprawnienia aplikacji:

    • Przyznawanie uprawnień aplikacji na potrzeby scenariuszy autonomicznych
    • Udzielanie 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 usłudze Microsoft Entra ID, zobacz dokumentację platformy tożsamości agenta firmy Microsoft

Reguły semantyczne

Zapewnienie poprawnego użycia parametrów tożsamości agenta ma kluczowe znaczenie dla pomyślnego uwierzytelniania. Poniższe reguły określają użycie parametrów AgentIdentity, AgentUsernamei AgentUserId i powinny być przestrzegane, aby uniknąć błędów walidacji zwracanych przez zestaw SDK.

Reguła 1. Wymaganie dotyczące tożsamości agenta

AgentUsername lub AgentUserId musi być sparowany z AgentIdentity.

W przypadku określenia AgentUsername lub AgentUserId bez AgentIdentity żądanie zakończy się niepowodzeniem z błędem walidacji.

# 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ć zarówno AgentUsername, jak i AgentUserId w tym samym żądaniu. Jeśli oba te elementy zostaną podane, żą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, uzyskując tokeny aplikacji.

Scenariusz: usługa wsadowa, która autonomicznie obsługuje przetwarzanie plików.

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

Charakterystyki tokenu:

  • Typ tokenu: token aplikacji
  • Temat (sub): identyfikator obiektu aplikacji agenta
  • Token dla identyfikacji 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 działa w imieniu określonego użytkownika zidentyfikowanego przez nazwę UPN.

Scenariusz: Asystent sztucznej inteligencji działający w imieniu użytkownika w aplikacji do czatu.

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

Charakterystyki 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 identyfikator obiektu.

Scenariusz: aparat przepływu pracy 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

Charakterystyki 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, wywołując /AuthorizationHeader z AgentIdentity oraz przychodzącym nagłówkiem 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>

Charakterystyki 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 (brak agenta)

Jeśli nie podano 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>

Charakterystyki 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 agentId = "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

Jeśli parametry tożsamości agenta są nieprawidłowo skonfigurowane lub są niepoprawnie używane, zestaw SDK zwraca błędy walidacji. Poniżej przedstawiono 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 praktyki

  1. Weryfikowanie danych wejściowych: zawsze weryfikuj parametry tożsamości agenta przed wykonaniem żądań
  2. Użyj identyfikatorów obiektów, gdy są dostępne: identyfikatory obiektów są bardziej stabilne
  3. Implementowanie prawidłowej obsługi błędów: płynnie obsługuj błędy weryfikacji tożsamości agenta
  4. Poświadczenia bezpiecznego agenta: Ochrona identyfikatorów i poświadczeń 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. Testowanie obu wzorców: weryfikowanie scenariuszy autonomicznych i delegowanych w testach
  7. Intencja dokumentu: jasno udokumentować, który wzorzec agenta jest odpowiedni dla każdego przypadku użycia

Zobacz też

  • Last updated on