Criar identidades de agente na plataforma de identidade do agente

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

Este artigo orienta você pelo processo de criação de um serviço Web simples que cria identidades de agente por meio de APIs do Microsoft Graph.

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

Importante

Microsoft Entra Agent ID está atualmente em VERSÃO PRÉVIA. Essas informações estão relacionadas a um produto de pré-lançamento que pode ser substancialmente modificado antes de ser lançado. A Microsoft não faz garantias, expressas ou implícitas, em relação às informações fornecidas aqui.

Pré-requisitos

A ID do Agente do Microsoft Entra faz parte do Microsoft Agent 365. Ambos estão disponíveis por meio do programa Frontier no Microsoft 365. Para acessar esses recursos, você deve ter uma licença para o Microsoft 365 Copilot e ter habilitado o Frontier para seus usuários.

Siga o guia de introdução do Frontier ou use as seguintes etapas para verificar se o Frontier está habilitado:

1. Entre no Centro de administração do Microsoft 365 como Administrador de Cobrança.
2. Navegue até Copilot>Configurações>Acesso do usuário>Copilot Frontier e verifique se está habilitado para usuários. Se você não vir essas opções, entre em contato com o administrador para verificar o licenciamento do Microsoft 365 Copilot.

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 no Azure) que hospeda a lógica de criação de identidade do agente.

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 do Microsoft Entra usando o modelo de identidade do agente:

Microsoft Graph API

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.

Microsoft.Identity.Web

Para instalar o 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 de teste. 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 Graph API

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/<id>"
    ],
}

Microsoft.Identity.Web

Para usar Microsoft.Identity.Web para executar a solicitação da API do Microsoft 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 planos de identidade do 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 Graph API

DELETE https://graph.microsoft.com/beta/serviceprincipals/<agent-identity-id>
OData-Version: 4.0
Content-Type: application/json
Authorization: Bearer <token>

Microsoft.Identity.Web

// 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;
})