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. A criação da identidade do agente é normalmente realizada ao provisionar um novo agente de IA.

Pode criar identidades de agentes de duas formas:

centro de administração Microsoft Entra — Use o assistente do centro de administração para criação rápida e individual de identidade.
Microsoft Graph API — Construir um serviço web que crie identidades de agentes programaticamente, o que é útil para provisionamento automatizado em escala.

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

Pré-requisitos

Para criar identidades de agente, precisa de:

Um plano de identidade de agente. Regista 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. Este pré-requisito aplica-se apenas se estiveres a criar identidades de agentes de forma programática.

Utilize o centro de administração do Microsoft Entra

Pode criar uma identidade de agente diretamente no centro de administração do centro de administração Microsoft Entra, selecionando um blueprint existente e atribuindo proprietários e patrocinadores.

Entre no centro de administração do Microsoft Entra.
Navegue para Entra ID>Agentes>Identidades dos Agentes.
Selecione Nova identidade de agente (Pré-visualização).
Na guia Noções básicas:
- Em Modelo de Agente, selecione um modelo para criar a identidade do seu agente.
- Insira um nome no campo de nome de identidade do agente e selecione Próximo.
No separador Proprietários & Patrocinadores , adicione opcionalmente proprietários e patrocinadores para a identidade:
- Selecione o ícone do lápis ao lado do campo Proprietários para alterar ou adicionar utilizadores que possam gerir esta identidade de agente.
- Selecione o ícone do lápis ao lado do campo Patrocinadores para alterar ou adicionar utilizadores que possam patrocinar esta identidade de agente.
Observação

Os patrocinadores podem ser utilizadores, grupos dinâmicos de membros ou grupos Microsoft 365. Grupos de segurança e grupos atribuídos a funções não são apoiados como patrocinadores.
Selecione Seguinte.
Revise as suas definições e depois selecione Criar.
Selecione Concluir para sair do assistente ou Ir para a identidade do agente para ver a página de detalhes da identidade ou configurar mais definições.

Nos passos seguintes, vai aprender a criar identidades de agentes programaticamente usando Microsoft Graph API e Microsoft. Identidade.Web. Obtenha primeiro um token de acesso e depois ligue para a API de criação.

Microsoft Graph API
Microsoft.Identity.Web

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 da Microsoft Entra usando o seu modelo de identidade de agente.

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 Microsoft.Identity.Web:

dotnet add package Microsoft.Identity.Web

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

Criar uma identidade de agente

Usando o token de acesso adquirido na etapa anterior, pode agora criar identidades de agente no seu locatário. 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/<group-id>"
	],
}

Observação

Ao atribuir um grupo como patrocinador, apenas os tipos de grupos suportados são aceites. Os grupos não são apoiados como proprietários.

Para usar Microsoft. Identity.Web para executar o pedido de Microsoft Graph API para criar uma identidade de agente, adicione o seguinte ficheiro de configuração MISE:

Advertência

Os segredos do cliente não devem ser usados como credenciais do cliente em ambientes de produção para modelos de identidade de agentes por motivos 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;
})

Comentários

Esta página foi útil?

Last updated on 2026-05-01