Criar identidades de agente na plataforma de identidade do agente

Depois de criar um blueprint de identidade do agente, a próxima etapa é criar uma ou mais identidades de agente que representem agentes de IA em seu locatário. A criação de identidade do agente normalmente é executada ao provisionar um novo agente de IA.

Você pode criar identidades de agente de duas maneiras:

centro de administração do Microsoft Entra — use o assistente do centro de administração para criação rápida de identidade individual.
Microsoft API do Graph — Crie um serviço Web que crie identidades de agente programaticamente, o que é útil para provisionamento automatizado em escala.

Se você quiser criar rapidamente identidades de agente para fins de teste, considere usar essa Microsoft Entra módulo do PowerShell para criar e usar identidades de agente.

Pré-requisitos

Para criar identidades de agente, você precisa:

Um blueprint de identidade do agente. Registre a ID do aplicativo blueprint de identidade do agente do processo de criação.
Um serviço Web ou aplicativo (em execução local ou implantado em Azure) que hospeda a lógica de criação de identidade do agente. Esse pré-requisito se aplica somente se você estiver criando identidades de agente programaticamente.

Use o centro de administração do Microsoft Entra

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

Faça login no centro de administração do Microsoft Entra.
Navegue até Entra ID>Agentes>Identidades dos agentes.
Selecione Nova identidade do agente (versão prévia).
Na guia Noções básicas :
- Sob modelo do Agente, selecione um modelo para criar sua identidade de agente.
- Insira um nome no campo Nome da identidade do Agente e selecione Avançar.
Na guia Proprietários e Patrocinadores , opcionalmente, adicione proprietários e patrocinadores para a identidade:
- Selecione o ícone de lápis ao lado do campo Proprietários para alterar ou adicionar usuários que podem gerenciar essa identidade de agente.
- Selecione o ícone de lápis ao lado do campo Patrocinadores para alterar ou adicionar usuários que podem patrocinar essa identidade de agente.
Note

Os patrocinadores podem ser usuários, grupos de associação dinâmica ou grupos de Microsoft 365. Não há suporte para grupos de segurança e grupos atribuíveis a funções como patrocinadores.
Selecione Avançar.
Examine as configurações e selecione Criar.
Selecione Concluído para sair do assistente ou ir para a identidade do agente para exibir a página de detalhes da identidade ou definir mais configurações.

Nas etapas a seguir, você aprenderá a criar identidades de agente programaticamente usando Microsoft API do Graph e Microsoft. Identity.Web. Primeiro, obtenha um token de acesso e chame a API de criação.

Microsoft API do Graph
Microsoft. Identity.Web

Obter um token de acesso usando o modelo de identidade do agente

Use um modelo de identidade do agente para criar cada identidade do agente. Solicite um token de acesso da Microsoft Entra usando seu blueprint de identidade de agente:

Ao usar uma identidade gerenciada como uma credencial, primeiro você deve obter um token de acesso usando sua identidade gerenciada. Os tokens de identidade gerenciada podem ser solicitados de um endereço IP exposto localmente no ambiente de computação. Consulte a documentação de identidade gerenciada para obter 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 gerenciada, solicite um token para o modelo 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_typequando um segredo do cliente está sendo 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 solicitações HTTP de saída. Ao usar Microsoft. Identity.Web, você pode pular para a próxima etapa.

Criar uma identidade de agente

Usando o token de acesso adquirido na etapa anterior, agora você pode criar identidades de agente em seu locatário. A criação de identidade do agente pode ocorrer em resposta a vários eventos ou gatilhos diferentes, como um usuário selecionando um botão para criar um novo agente. Recomendamos que você crie uma identidade de agente para cada agente, mas pode escolher uma abordagem diferente com base em suas necessidades.

Microsoft API do Graph
Microsoft. Identity.Web

Sempre inclua 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>"
	],
}

Note

Ao atribuir um grupo como patrocinador, somente tipos de grupo com suporte são aceitos. Não há suporte para grupos como proprietários.

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

Aviso

Segredos do cliente não devem ser usados como credenciais de cliente em ambientes de produção para esquemas de identidade de agente devido a riscos de segurança. Em vez disso, use métodos de autenticação mais seguros, como fic (credenciais de identidade federadas) com identidades gerenciadas ou certificados de cliente. Esses métodos fornecem segurança aprimorada eliminando a necessidade de armazenar segredos confidenciais diretamente na configuração do aplicativo.

{
  "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 do aplicativo 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();

Excluir uma identidade de agente

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

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

Comentários

Esta página foi útil?

Last updated on 2026-05-01