Creare identità agente nella piattaforma Agent Identity

Dopo aver creato un progetto di identità agente, il passaggio successivo consiste nel creare una o più identità agente che rappresentano gli agenti di intelligenza artificiale nel tenant. La creazione dell'identità dell'agente viene in genere eseguita durante il provisioning di un nuovo agente di intelligenza artificiale.

È possibile creare identità agente in due modi:

Interfaccia di amministrazione di Microsoft Entra : usare la procedura guidata dell'interfaccia di amministrazione per la creazione rapida delle identità personali.
Microsoft API Graph: creare un servizio Web che crea identità agente a livello di codice, utile per il provisioning automatizzato su larga scala.

Se si vogliono creare rapidamente identità agente a scopo di test, è consigliabile usare questo modulo di PowerShell Microsoft Entra per la creazione e l'uso delle identità dell'agente.

Prerequisiti

Per creare identità agente, è necessario:

Un progetto di identità dell'agente. Registrare l'ID dell'app del modello di identità agente dal processo di creazione.
Un servizio Web o un'applicazione (in esecuzione in locale o distribuita in Azure) che ospita la logica di creazione dell'identità dell'agente. Questo prerequisito si applica solo se si creano identità dell'agente a livello di codice.

Usare il Interfaccia di amministrazione di Microsoft Entra

È possibile creare un'identità agente direttamente nel Interfaccia di amministrazione di Microsoft Entra selezionando un progetto esistente e assegnando proprietari e sponsor.

Accedi all'interfaccia di amministrazione di Microsoft Entra.
Passare a Entra ID>Agenti>Identità degli agenti.
Selezionare Nuova identità agente (anteprima).
Nella scheda Informazioni di base :
- In Progetto agente selezionare un progetto da cui creare l'identità dell'agente.
- Immettere un nome nel campo Nome identità agente e selezionare Avanti.
Nella scheda Proprietari e sponsor aggiungere facoltativamente proprietari e sponsor per l'identità:
- Selezionare l'icona a forma di matita accanto al campo Proprietari per modificare o aggiungere utenti che possono gestire l'identità dell'agente.
- Selezionare l'icona a forma di matita accanto al campo Sponsors per modificare o aggiungere utenti che possono sponsorizzare l'identità dell'agente.
Note

Gli sponsor possono essere utenti, gruppi di appartenenze dinamici o gruppi di Microsoft 365. I gruppi di sicurezza e i gruppi assegnabili a ruoli non sono supportati in qualità di sponsor.
Selezionare Avanti.
Esaminare le impostazioni e quindi selezionare Crea.
Selezionare Fine per uscire dalla procedura guidata o Passare all'identità dell'agente per visualizzare la pagina dei dettagli dell'identità o configurare altre impostazioni.

Nei passaggi seguenti si apprenderà come creare identità dell'agente a livello di codice usando Microsoft API Graph e Microsoft. Identity.Web. Ottenere prima un token di accesso, quindi chiamare l'API di creazione.

Microsoft API Graph
Microsoft. Identity.Web

Ottieni un token di accesso utilizzando il modello di identità dell'agente

Si usa il progetto di identità dell'agente per creare ogni identità dell'agente. Richiedere un token di accesso da Microsoft Entra utilizzando il modello di identità dell'agente.

Quando si usa un'identità gestita come credenziale, è prima necessario ottenere un token di accesso usando l'identità gestita. I token di identità gestiti possono essere richiesti da un indirizzo IP esposto localmente nell'ambiente di calcolo. Fare riferimento alla documentazione sull'identità gestita per informazioni dettagliate.

GET http://169.254.169.254/metadata/identity/oauth2/token?api-version=2019-08-01&resource=api://AzureADTokenExchange/.default
Metadata: True

Dopo aver ottenuto un token per l'identità gestita, richiedere un token per il progetto di identità dell'agente:

POST https://login.microsoftonline.com/<my-test-tenant>/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

client_id=<agent-blueprint-id>
scope=https://graph.microsoft.com/.default
client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
client_assertion=<msi-token>
grant_type=client_credentials

Un client_secret parametro può essere usato anche invece di client_assertion e client_assertion_type, quando viene usato un segreto client nello sviluppo locale.

Per installare Microsoft. Identity.Web:

dotnet add package Microsoft.Identity.Web

Microsoft. Identity.Web include un'interfaccia che richiede automaticamente un token di accesso e la collega alle richieste HTTP in uscita. Quando si usa Microsoft. Identity.Web, è possibile passare al passaggio successivo.

Creare un'identità di agente

Usando il token di accesso acquisito nel passaggio precedente, è ora possibile creare identità agente nel tenant. La creazione dell'identità dell'agente può verificarsi in risposta a molti eventi o trigger diversi, ad esempio un utente che seleziona un pulsante per creare un nuovo agente. È consigliabile creare un'identità agente per ogni agente, ma è possibile scegliere un approccio diverso in base alle esigenze.

Microsoft API Graph
Microsoft. Identity.Web

Includere sempre l'intestazione OData-Version quando si usa @odata.type.

POST https://graph.microsoft.com/beta/serviceprincipals/Microsoft.Graph.AgentIdentity
OData-Version: 4.0
Content-Type: application/json
Authorization: Bearer <token>
{
	"displayName": "My Agent Identity",
	"agentIdentityBlueprintId": "<my-agent-blueprint-id>",
	"sponsors@odata.bind": [
		"https://graph.microsoft.com/v1.0/users/<id>",
		"https://graph.microsoft.com/v1.0/groups/<group-id>"
	],
}

Note

Quando si assegna un gruppo come sponsor, vengono accettati solo i tipi di gruppo supportati . I gruppi non sono supportati come proprietari.

Per usare Microsoft. Identity.Web per eseguire la richiesta di Microsoft API Graph per creare un'identità dell'agente, aggiungere il file di configurazione MISE seguente:

Avvertimento

I segreti client non devono essere usati come credenziali client negli ambienti di produzione per i progetti di identità agente a causa di rischi per la sicurezza. Usare invece metodi di autenticazione più sicuri, ad esempio le credenziali di identità federate (FIC) con identità gestite o certificati client. Questi metodi offrono una sicurezza avanzata eliminando la necessità di archiviare segreti sensibili direttamente all'interno della configurazione dell'applicazione.

{
  "AzureAd": {
	"Instance": "https://login.microsoftonline.com/",
	"TenantId": "<my-test-tenant>",
	"ClientId": "<my-agent-blueprint-id>",
	"Scopes": "access_agent",
	"ClientCredentials": [
		{
			"SourceType": "ClientSecret",
			"ClientSecret": "your-client-secret"
		}
	]
  },

  "DownstreamApis": {
	"agent-identity": {
	  "BaseUrl": "https://graph.microsoft.com",
	  "RelativePath": "/beta/serviceprincipals/Microsoft.Graph.AgentIdentity",
	  "Scopes": ["00000003-0000-0000-c000-000000000000/.default"],
	  "RequestAppToken": true
	}
  }
}

Il codice per l'app ASP.NET Core (Program.cs) è l'esempio seguente:

using Microsoft.Identity.Abstractions;
using Microsoft.Identity.Web.Resource;
using Microsoft.IdentityModel.S2S.Extensions.AspNetCore;
using MyAgent;

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddMicrosoftIdentityWebApiAuthentication(builder.Configuration)
	.EnableTokenAcquisitionToCallDownstreamApi();
builder.Services.AddInMemoryTokenCaches();
var app = builder.Build();

app.UseHttpsRedirection();
app.UseAuthentication();
app.UseAuthorization();

public class AgentIdentity
{
	[JsonPropertyName("@odata.type")]
	public string @odata_type { get; set; } = "#Microsoft.Graph.AgentIdentity";

	[JsonPropertyName("displayName")]
	public string? displayName { get; set; }

	[JsonPropertyName("agentIdentityBlueprintId")]
	public string? agentIdentityBlueprintId { get; set; }

	[JsonPropertyName("id")]
	public string? id { get; set; }

  [JsonPropertyName("sponsors@odata.bind")]
	public string[]? sponsorsOdataBind { get; set; }

  [JsonPropertyName("owners@odata.bind")]
	public string[]? ownersOdataBind { get; set; }
}

// Create an Agent identity
app.MapGet("/create-agent-identity", async (HttpContext httpContext) =>
{
	try
	{
		// Get the service to call the downstream API (preconfigured in the appsettings.json file)
		IDownstreamApi downstreamApi = httpContext.RequestServices.GetRequiredService<IDownstreamApi>();

		// Call the downstream API with a POST request to create an Agent Identity
		var jsonResult = await downstreamApi.PostForAppAsync<AgentIdentity, AgentIdentity>(
			"agent-identity",
			new AgentIdentity {
				displayName = "My agent identity",
				agentIdentityBlueprintId = "<my-agent-blueprint-id>",
		  sponsorsOdataBind = new [] { "https://graph.microsoft.com/v1.0/users/<id>" }
			}
		  );
		return jsonResult?.id;
	}
	catch (Exception ex)
	{
		return ex.Message;
	}

})

app.Run();

Eliminare un'identità dell'agente

Quando un agente viene deallocato o eliminato definitivamente, il servizio deve eliminare anche l'identità dell'agente associata:

Microsoft API Graph
Microsoft. Identity.Web

DELETE https://graph.microsoft.com/beta/serviceprincipals/<agent-identity-id>
OData-Version: 4.0
Content-Type: application/json
Authorization: Bearer <token>

// Delete an Agent identity
app.MapGet("/delete-agent-identity", async (HttpContext httpContext, string id) =>
{
	// Get the service to call the downstream API (preconfigured in the appsettings.json file)
	IDownstreamApi downstreamApi = httpContext.RequestServices.GetRequiredService<IDownstreamApi>();

	// Call the downstream API with a DELETE request to remove an Agent Identity
	var jsonResult = await downstreamApi.DeleteForAppAsync<string, string>(
		"agent-identity",
		null!,
		options =>
		{
			options.RelativePath += $"/{id}"; // Specify the ID of the agent identity to delete
		});
	return jsonResult;
})

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2026-05-01