Creación de identidades de agente en la plataforma de identidad del agente

Después de crear un plano técnico de identidad del agente, el siguiente paso consiste en crear una o varias identidades de agente que representen agentes de IA en el inquilino. Normalmente, la creación de identidades del agente se realiza al aprovisionar un nuevo agente de IA.

Puede crear identidades de agente de dos maneras:

Centro de administración Microsoft Entra: use el asistente del Centro de administración para la creación rápida e individual de identidades.
Microsoft Graph API: cree un servicio web que cree identidades de agente mediante programación, lo que resulta útil para el aprovisionamiento automatizado a escala.

Si desea crear rápidamente identidades de agente con fines de prueba, considere la posibilidad de usar este Microsoft Entra módulo de PowerShell para crear y usar identidades de agente.

Prerrequisitos

Para crear identidades de agente, necesita:

Un plano técnico de identidad del agente. Registre el identificador de aplicación del plano técnico de identidad del agente desde el proceso de creación.
Un servicio web o aplicación (que se ejecuta localmente o se implementa en Azure) que hospeda la lógica de creación de identidades del agente. Este requisito previo solo se aplica si va a crear identidades de agente mediante programación.

Uso del Centro de administración Microsoft Entra

Puede crear una identidad de agente directamente en el Centro de administración Microsoft Entra seleccionando un plano técnico existente y asignando propietarios y patrocinadores.

Inicie sesión en el Centro de administración de Microsoft Entra.
Navegue a Entra ID>Agentes>Identidades de agentes.
Seleccione Nueva identidad del agente (versión preliminar).
En la pestaña Aspectos básicos:
- En Plano técnico del agente, seleccione un plano técnico para crear la identidad del agente.
- Escriba un nombre en el campo Nombre de identidad del agente y seleccione Siguiente.
En la pestaña Propietarios y patrocinadores, opcionalmente, agregue propietarios y patrocinadores para la identidad:
- Seleccione el icono de lápiz situado junto al campo Propietarios para cambiar o agregar usuarios que puedan administrar esta identidad del agente.
- Seleccione el icono de lápiz situado junto al campo Patrocinadores para cambiar o agregar usuarios que puedan patrocinar esta identidad del agente.
Nota:

Los patrocinadores pueden ser usuarios, grupos de pertenencia dinámica o grupos de Microsoft 365. Los grupos de seguridad y los grupos asignables de roles no se admiten como patrocinadores.
Seleccione Siguiente.
Revise la configuración y, a continuación, seleccione Crear.
Seleccione Listo para salir del asistente o Ir a la identidad del agente para ver la página de detalles de la identidad o configurar más opciones.

En los pasos siguientes, aprenderá a crear identidades de agente mediante programación mediante Microsoft Graph API y Microsoft. Identity.Web. Obtenga primero un token de acceso y llame a la API de creación.

API de Microsoft Graph
Microsoft. Identity.Web

Obtener un token de acceso utilizando el esquema de identidad del agente

Usas la plantilla de identidad del agente para crear cada una de las identidades del agente. Solicite un token de acceso desde Microsoft Entra mediante el plano técnico de identidad del agente:

Al utilizar una identidad administrada como credencial, primero debe obtener un token de acceso mediante su identidad administrada. Los tokens de identidad administrada se pueden solicitar desde una dirección IP expuesta localmente en el entorno de proceso. Consulte la documentación de identidad administrada para obtener más información.

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

Después de obtener un token para la identidad administrada, solicite un token para el plano técnico de identidad del 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

También se puede usar un parámetro client_secret en lugar de client_assertion y client_assertion_type cuando se está utilizando un secreto de cliente en el desarrollo local.

Para instalar Microsoft. Identity.Web:

dotnet add package Microsoft.Identity.Web

Microsoft. Identity.Web incluye una interfaz que solicita automáticamente un token de acceso y lo asocia a las solicitudes HTTP salientes. Al usar Microsoft. Identity.Web, puede ir directamente al paso siguiente.

Creación de una identidad de agente

Con el token de acceso adquirido en el paso anterior, ahora puede crear identidades de agente en el inquilino. La creación de identidades del agente puede producirse en respuesta a muchos eventos o desencadenadores diferentes, como un usuario que selecciona un botón para crear un nuevo agente. Se recomienda crear una identidad de agente para cada agente, pero puede elegir un enfoque diferente en función de sus necesidades.

API de Microsoft Graph
Microsoft. Identity.Web

Incluya siempre el encabezado OData-Version al usar @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>"
	],
}

Nota:

Al asignar un grupo como patrocinador, solo se aceptan los tipos de grupo admitidos . No se admiten grupos como propietarios.

Para usar Microsoft. Identity.Web para ejecutar la solicitud de Microsoft Graph API para crear una identidad del agente, agregue el siguiente archivo de configuración de MISE:

Advertencia

Los secretos de cliente no se deben usar como credenciales de cliente en entornos de producción para planos técnicos de identidad del agente debido a riesgos de seguridad. En su lugar, use métodos de autenticación más seguros, como credenciales de identidad federada (FIC) con identidades administradas o certificados de cliente. Estos métodos proporcionan seguridad mejorada eliminando la necesidad de almacenar secretos confidenciales directamente dentro de la configuración de la aplicación.

{
  "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
	}
  }
}

El código de la aplicación de ASP.NET Core (Program.cs) es el ejemplo siguiente:

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

Eliminación de una identidad de agente

Cuando se desasigna o destruye un agente, el servicio también debe eliminar la identidad del agente asociada:

API de Microsoft 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;
})

Comentarios

¿Le ha resultado útil esta página?

Last updated on 2026-05-01