Agentidentiteter: autonoma och interaktiva agentmönster

Agentidentiteter möjliggör avancerade autentiseringsscenarier där ett agentprogram agerar självständigt eller för användarnas räkning. Genom att använda agentidentiteter med Microsoft Entra SDK för AgentID kan du skapa både autonoma agenter som fungerar i sin egen kontext och interaktiva agenter som agerar för användarnas räkning. För att underlätta dessa scenarier stöder SDK specifika frågeparametrar för att ange agentidentiteter och användarkontexter.

Detaljerad vägledning om agentidentiteter finns i dokumentationen Microsoft agentidentitetsplattform.

Översikt

Agentidentiteter stöder två primära mönster:

Autonom agent: Agenten fungerar i sin egen programkontext.
Interaktiv agent: En interaktiv agent fungerar för en användares räkning.

SDK:et accepterar tre valfria frågeparametrar:

AgentIdentity – GUID för agentidentiteten.
AgentUsername – Användarens huvudnamn (UPN) för en specifik användare.
AgentUserId – Användarobjekt-ID (OID) för specifik användare, som ett alternativ till UPN.

Prioritetsregler

AgentUsername och AgentUserId är ömsesidigt uteslutande. Begäranden som innehåller båda parametrarna misslyckas, enligt beskrivningen i regel 2: ömsesidig exklusivitet. Ange endast en av dessa parametrar per begäran.

Microsoft Entra ID konfiguration

Innan du konfigurerar agentidentiteter i ditt program konfigurerar du nödvändiga komponenter i Microsoft Entra ID. Information om hur du registrerar ett nytt program i Microsoft Entra ID klientorganisation finns i Registrera ett program.

Krav för agentidentiteter

Registrering av agentprogram:
- Registrera det överordnade agentprogrammet i Microsoft Entra ID.
- Konfigurera API-behörigheter för underordnade API:er.
- Konfigurera klientautentiseringsuppgifter (FIC+MSI, certifikat eller hemlighet).
Agentidentitetskonfiguration:
- Skapa agentidentiteter med hjälp av agentritningen.
- Tilldela nödvändiga behörigheter till agentidentiteter.
Programbehörigheter:
- Bevilja programbehörigheter för autonoma scenarier.
- Bevilja delegerade behörigheter för scenarier med användardelegering.
- Se till att administratörsmedgivande tillhandahålls där det behövs.

Detaljerade stegvisa instruktioner om hur du konfigurerar agentidentiteter i Microsoft Entra ID finns i dokumentationen Microsoft agentidentitetsplattform.

Semantiska regler

Om du vill autentisera måste du använda agentidentitetsparametrar korrekt. Följande regler styr användningen av AgentIdentityparametrarna , AgentUsernameoch AgentUserId . Följ dessa regler för att undvika valideringsfel som SDK:et returnerar.

Regel 1: AgentIdentity-krav

AgentUsername eller AgentUserId måste parkopplas med AgentIdentity.

Om du anger AgentUsername eller AgentUserId utan AgentIdentitymisslyckas begäran med ett verifieringsfel.

# 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

Regel 2: Ömsesidig exklusivitet

AgentUsername och AgentUserId är ömsesidigt uteslutande parametrar.

Du kan inte ange både AgentUsername och AgentUserId i samma begäran. Om du anger båda parametrarna misslyckas begäran med ett verifieringsfel.

# 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

Regel 3: Autonom kontra interaktiv

Kombinationen av parametrar avgör autentiseringsmönstret:

Parameterar	Mönster	Description
`AgentIdentity` bara	Autonom agent	Hämtar programtoken för agentidentiteten
`AgentIdentity` + `AgentUsername`	Interaktiv agent	Hämtar användartoken för den angivna användaren (per UPN)
`AgentIdentity` + `AgentUserId`	Interaktiv agent	Hämtar användartoken för den angivna användaren (efter objekt-ID)

Exempel:

# 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

Användningsmönster

För varje användningsmönster avgör kombinationen av parametrar autentiseringsflödet och vilken typ av token som hämtas.

Mönster 1: Autonom agent

Agentprogrammet körs oberoende av varandra i sin egen programkontext och hämtar programtoken.

Scenario: En batchbearbetningstjänst som bearbetar filer på egen hand.

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

Tokenegenskaper:

Tokentyp: Programtoken
Ämne (sub): Agentprogrammets objekt-ID
Token som skapats för agentens identitet
Behörigheter: Programbehörigheter som tilldelats agentidentitet

Användningsfall:

Automatiserad batchbearbetning
Bakgrundsaktiviteter
System-till-system-åtgärder
Schemalagda jobb utan användarkontext

Mönster 2: Autonom användaragent (efter användarnamn)

Agenten körs för en specifik användare som identifieras av deras UPN.

Scenario: En AI-assistent som agerar för en användares räkning i ett chattprogram.

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

Tokenegenskaper:

Tokentyp: Användartoken
Ämne (sub): Användarens objekt-ID
Agentidentitetsaspekt som ingår i tokenkrav
Behörigheter: Interaktiva behörigheter som är begränsade till användaren

Användningsfall:

Interaktiva agentapplikationer
AI-assistenter med användardelegering
Automatisering på användarnivå
Anpassade arbetsflöden

Mönster 3: Autonom användaragent (efter objekt-ID)

Agenten fungerar för en specifik användare som identifieras av deras objekt-ID.

Scenario: En arbetsflödesmotor som bearbetar användarspecifika uppgifter med hjälp av lagrade användar-ID:t.

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

Tokenegenskaper:

Tokentyp: Användartoken
Ämne (sub): Användarens objekt-ID
Agentidentitetsaspekt som ingår i tokenkrav
Behörigheter: Interaktiva behörigheter som är begränsade till användaren

Användningsfall:

Långvariga arbetsflöden med lagrade användaridentifierare
Batch-åtgärder på uppdrag av flera användare
System som använder objekt-ID:er för användarreferens

Mönster 4: Interaktiv agent (agerar på uppdrag av användaren som anropar den)

Ett agentwebb-API tar emot en användartoken, validerar den och gör delegerade anrop åt den användaren.

Scenario: Ett webb-API som fungerar som en interaktiv agent som validerar inkommande användartoken och gör delegerade anrop till underordnade tjänster.

Flöde:

Agentwebb-API:et tar emot användartoken från det anropande programmet.
Validerar token via slutpunkten /Validate.
Hämtar token för underordnade API:er genom att anropa /AuthorizationHeader med endast AgentIdentity och det inkommande auktoriseringshuvudet.

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

Tokenegenskaper:

Tokentyp: Användartoken (OBO-flöde)
Ämne (sub): Den ursprungliga användarens objekt-ID
Agenten fungerar som mellanhand för användare
Behörigheter: Interaktiva behörigheter som är begränsade till användaren

Användningsfall:

Webb-API:er som fungerar som agenter
Interaktiva agenttjänster
Agentbaserad mellanprogram som delegerar till underordnade API:er
Tjänster som validerar och vidarebefordrar användarkontext

Mönster 5: Vanlig begäran (ingen agent)

När du inte anger agentparametrar använder SDK:t den inkommande tokens identitet.

Scenario: OBO-flöde (Standard on-behalf-of) utan agentidentiteter.

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

Tokenegenskaper:

Tokentyp: Beror på inkommande token och konfiguration
Använder standardflöde för OBO- eller klientautentiseringsuppgifter
Inga fasetter av agentidentitet

Kodexempel

Följande kodfragment visar hur du implementerar de olika agentidentitetsmönstren med olika programmeringsspråk och hur du interagerar med SDK-slutpunkterna. Koden visar hur du hanterar out-of-process-anrop till SDK för att hämta auktoriseringshuvuden för underordnade API-anrop.

TypeScript: Autonom agenten

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 med användaridentitet

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: Interaktiv agent

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

Felscenarier

När du felkonfigurerar agentidentitetsparametrar eller använder dem felaktigt returnerar SDK:t verifieringsfel. I följande avsnitt beskrivs vanliga felscenarier och deras motsvarande svar. Mer information om felhantering finns i felsökningsguiden.

AgentIdentity saknas för AgentUsername

Begäran:

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

Svar:

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

Både AgentUsername och AgentUserId har angetts

Begäran:

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

Svar:

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

Ogiltigt AgentUserId-format

Begäran:

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

Svar:

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

Metodtips

Verifiera indata: Verifiera alltid agentidentitetsparametrar innan du gör begäranden.
Använd objekt-ID:t när det är tillgängligt: Objekt-ID:t är stabilare.
Implementera korrekt felhantering: Hantera agentidentitetsverifieringsfel på ett korrekt sätt.
Säkra agentens autentiseringsuppgifter: Skydda agentens klient-ID:n och autentiseringsuppgifter.
Granskning av agentverksamhet: Logga och övervaka användningen av agentidentiteter för säkerhet och efterlevnad.
Testa båda mönstren: Verifiera både autonoma och delegerade scenarier i dina tester.
Dokumentsyfte: Dokumentera tydligt vilket agentmönster som är lämpligt för varje användningsfall.

Feedback

Var den här sidan till hjälp?

Last updated on 2026-04-19

Agentidentiteter: autonoma och interaktiva agentmönster

Översikt

Prioritetsregler

Microsoft Entra ID konfiguration

Krav för agentidentiteter

Semantiska regler

Regel 1: AgentIdentity-krav

Regel 2: Ömsesidig exklusivitet

Regel 3: Autonom kontra interaktiv

Användningsmönster

Mönster 1: Autonom agent

Mönster 2: Autonom användaragent (efter användarnamn)

Mönster 3: Autonom användaragent (efter objekt-ID)

Mönster 4: Interaktiv agent (agerar på uppdrag av användaren som anropar den)

Mönster 5: Vanlig begäran (ingen agent)

Kodexempel

TypeScript: Autonom agenten

Python: Agent med användaridentitet

TypeScript: Interaktiv agent

C# med HttpClient

Felscenarier

AgentIdentity saknas för AgentUsername

Både AgentUsername och AgentUserId har angetts

Ogiltigt AgentUserId-format

Metodtips

Relaterat innehåll

Feedback

Ytterligare resurser