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 de prueba. Normalmente, la creación de identidades del agente se realiza al aprovisionar un nuevo agente de IA.

Este artículo le guía por el proceso de creación de un servicio web sencillo que crea identidades de agente a través de las API de Microsoft Graph.

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

Prerrequisitos

Antes de crear identidades de agente, asegúrese de que tiene:

Descripción de las identidades del agente
Un plano técnico de identidad del agente configurado (consulte Creación de un plano técnico del agente). Registrar el ID de aplicación del esquema de identidad del agente desde el proceso de creación
Un servicio web o una aplicación (que se ejecuta localmente o se implementa en Azure) que hospedan la lógica de creación de identidades del agente

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 de Microsoft Entra mediante el plano técnico de identidad del agente:

API de Microsoft Graph
Microsoft.Identity.Web

Al usar una identidad administrada como credencial, primero debe obtener un token de acceso mediante la 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 adjunta 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 de prueba. 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/<id>"
    ],
}

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 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 2025-11-19