Criar identidades de agentes na plataforma de identidade de agente

Depois de criar um blueprint de identidade de agente, o passo seguinte é criar uma ou mais identidades de agentes que representem agentes de IA no seu tenant de teste. A criação da identidade do agente é normalmente realizada ao provisionar um novo agente de IA.

Este artigo orienta-o no processo de construção de um serviço web simples que cria identidades de agentes através das APIs Microsoft Graph.

Se quiser criar rapidamente identidades de agentes para fins de teste, considere usar este módulo PowerShell para criar e usar identidades de agentes.

Pré-requisitos

Antes de criar identidades de agente, certifique-se de que tem:

Compreender as identidades dos agentes
Um modelo de identidade de agente configurado (ver Criar um modelo de agente). Registar o ID da aplicação de blueprint de identidade do agente durante o processo de criação
Um serviço web ou aplicação (a correr localmente ou implementado no Azure) que aloja a lógica de criação da identidade do agente

Obtenha um token de acesso usando o esquema de identidade do agente

Usas o modelo de identidade do agente para criar cada identidade de agente. Solicite um token de acesso ao Microsoft Entra usando o seu modelo de identidade de agente:

Microsoft Graph API
Microsoft.Identity.Web

Ao usar uma identidade gerida como credencial, deve primeiro obter um token de acesso usando a sua identidade gerida. Tokens de identidade gerida podem ser solicitados a partir de um endereço IP localmente exposto no ambiente de computação. Consulte a documentação sobre managed identity para mais detalhes.

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

Depois de obter um token para a identidade gerida, solicite um token para o plano de identidade do 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

Um client_secret parâmetro também pode ser usado em vez de client_assertion e client_assertion_type, quando um cliente secreto está a ser usado no desenvolvimento local.

Para instalar o Microsoft.Identity.Web:

dotnet add package Microsoft.Identity.Web

O Microsoft.Identity.Web inclui uma interface que solicita automaticamente um token de acesso e o anexa a pedidos HTTP de saída. Ao usar o Microsoft.Identity.Web, pode saltar para o passo seguinte.

Criar uma identidade de agente

Usando o token de acesso adquirido no passo anterior, pode agora criar identidades de agente no seu tenant de teste. A criação de identidade de agente pode ocorrer em resposta a muitos eventos ou gatilhos diferentes, como um utilizador a selecionar um botão para criar um novo agente.

Recomendamos que crie uma identidade de agente para cada agente, mas pode optar por uma abordagem diferente com base nas suas necessidades.

Microsoft Graph API
Microsoft.Identity.Web

Inclua sempre o cabeçalho OData-Version ao 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 o Microsoft.Identity.Web para executar o pedido da API Microsoft Graph para criar uma identidade de agente, adicione o seguinte ficheiro de configuração MISE:

Advertência

Segredos de cliente não devem ser usados como credenciais de cliente em ambientes de produção para modelos de identidade de agentes devido a riscos de segurança. Em vez disso, utilize métodos de autenticação mais seguros, como credenciais de identidade federada (FIC) com identidades geridas ou certificados de cliente. Estes métodos proporcionam maior segurança ao eliminar a necessidade de armazenar segredos sensíveis diretamente na configuração da sua aplicação.

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

O código da aplicação ASP.NET Core (Program.cs) é o seguinte exemplo:

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

Eliminar uma identidade de agente

Quando um agente é desalocado ou destruído, o seu serviço também deve eliminar a identidade associada do agente:

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

Feedback

Esta página foi útil?

Last updated on 2025-11-19