Criar um plano de identidade do agente

Um blueprint de identidade do agente é usado para criar identidades de agente e solicitar tokens usando essas identidades de agente. Durante o processo de criação de um blueprint de identidade do agente, você define o proprietário e o patrocinador desse blueprint para estabelecer relações administrativas e de responsabilidade. Você também configurará um URI de identificador e definirá um escopo para agentes criados a partir desse blueprint se o agente for projetado para receber solicitações de entrada de outros agentes e usuários.

Você pode criar um blueprint de identidade de agente de duas maneiras:

centro de administração do Microsoft Entra, use o assistente para uma configuração rápida que cria o blueprint e a sua identidade principal.
API do Microsoft Graph ou PowerShell: crie e configure completamente o modelo programaticamente, incluindo as credenciais, as URIs do identificador, os escopos e a entidade do modelo em um único fluxo de trabalho.

Pré-requisitos

Para criar um blueprint de identidade do agente, você precisa:

A função Privileged Role Administrator é a função menos privilegiada necessária para conceder permissões do Aplicativo Microsoft Graph.
Administrador de aplicativos de nuvem ou Administrador de aplicativos é necessário para conceder permissões delegadas ao Microsoft Graph.
As funções Desenvolvedor de ID do Agente e Administrador de ID do Agente podem criar planos de identidade do agente e entidades de planos de identidade do agente.
- O Desenvolvedor de ID do Agente pode configurar credenciais de identidade federadas em um modelo de identidade do agente.
- O Administrador de ID do Agente pode configurar credenciais de identidade federadas em um modelo de identidade do agente e é necessário adicionar uma credencial de segredo ou certificado.
Se estiver usando o PowerShell, a versão 7 será necessária.

Observação

Os proprietários de um blueprint de identidade do agente ou de um principal de blueprint de identidade do agente podem criar identidades de agente para esse blueprint sem uma função de ID do agente Microsoft Entra. Os criadores do blueprint de identidade do agente são automaticamente definidos como proprietários tanto do blueprint quanto do principal associado do blueprint de identidade do agente.

Prepare o seu ambiente

Para simplificar o processo, leve alguns instantes para configurar seu ambiente para as permissões certas.

Autorizar um cliente a criar modelos de identidade de agente

Neste artigo, você usará Microsoft Graph PowerShell ou outro cliente para criar o blueprint de identidade do agente. Você deve autorizar este cliente de software a criar e configurar um blueprint de identidade do agente e criar um principal do blueprint de identidade do agente. O cliente requer as seguintes permissões de Microsoft Graph:

As etapas neste guia usam todas as permissões delegadas, mas você pode usar permissões de aplicativo para esses cenários que exigem elas.

Para se conectar a todos os escopos necessários para Microsoft Graph PowerShell, execute o seguinte comando:

Connect-MgGraph -Scopes "AgentIdentityBlueprint.Create", "AgentIdentityBlueprint.AddRemoveCreds.All", "AgentIdentityBlueprint.UpdateAuthProperties.All", "AgentIdentityBlueprintPrincipal.Create", "User.Read" -TenantId <your-tenant-id>

Criar um plano de identidade do agente

Os blueprints de identidade do agente devem ter um patrocinador, que é o usuário ou um grupo com suporte responsável pelo agente. É recomendado ter um responsável, que é o usuário ou a entidade de serviço capaz de fazer alterações no blueprint de identidade do agente. Para obter informações, consulte Relações administrativas no ID do agente Microsoft Entra.

Use o centro de administração do Microsoft Entra

Você pode criar um blueprint de identidade do agente diretamente no centro de administração do Microsoft Entra. O assistente do centro de administração cria automaticamente tanto o blueprint de identidade do agente quanto a sua entidade de blueprint.

Observação

O assistente da central de administração define o nome do blueprint e atribui proprietários e patrocinadores. Para configurar credenciais, URIs de identificador, escopos ou permissões, use o Microsoft API do Graph ou o PowerShell ou configure-as após a criação por meio das páginas de detalhes do blueprint no centro de administração.

Faça login no centro de administração do Microsoft Entra.
Navegue até Entra ID>Agentes>blueprint de agentes.
Selecione o blueprint do novo agente (versão prévia).
Na guia Noções básicas, insira um nome no campo nome do blueprint do Agente e selecione Avançar.
Na guia Proprietários e Patrocinadores , opcionalmente, altere ou adicione proprietários e patrocinadores para o blueprint:
- Selecione o ícone de lápis ao lado do campo Proprietários para alterar ou adicionar usuários que podem gerenciar o blueprint.
- Selecione o ícone de lápis ao lado do campo Patrocinadores para alterar ou adicionar usuários que podem patrocinar o blueprint.
Observação

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 o blueprint do agente para exibir a página de detalhes do blueprint ou definir mais configurações.

Para obter mais informações sobre como gerenciar blueprints de identidade do agente, consulte Gerenciar blueprints de identidade do agente.

Criar programaticamente

Para criar um blueprint de identidade do agente usando código, use o Microsoft API do Graph ou o PowerShell.

Microsoft API do Graph
Microsoft Graph PowerShell

Esta etapa cria o blueprint de identidade do agente, atribui um proprietário e um patrocinador e requer os seguintes detalhes:

A AgentIdentityBlueprint.Create permissão.
O cabeçalho OData-Version deve ser definido como 4.0.
Uma ID de usuário para os campos proprietário e patrocinador no corpo da solicitação de exemplo. Um patrocinador é necessário, mas um proprietário é opcional.

POST https://graph.microsoft.com/v1.0/applications/
OData-Version: 4.0
Content-Type: application/json
Authorization: Bearer <token>

{
  "@odata.type": "Microsoft.Graph.AgentIdentityBlueprint",
  "displayName": "My Agent Identity Blueprint",
  "sponsors@odata.bind": [
    "https://graph.microsoft.com/v1.0/users/<id>",
  ],
  "owners@odata.bind": [
    "https://graph.microsoft.com/v1.0/users/<id>"
  ],
}

Depois de criar o blueprint de identidade do agente, registre o valor do appId para a próxima etapa.

Esta etapa cria o aplicativo de plano de identidade do agente, designando o usuário atual como proprietário e patrocinador, e inclui as seguintes tarefas distintas:

Conecte-se ao seu locatário com os escopos AgentIdentityBlueprint.Create e User.Read.
Adiciona o usuário atual como patrocinador e proprietário do blueprint de identidade do agente.
Crie o aplicativo de blueprint de identidade do agente.

Connect-MgGraph -Scopes "AgentIdentityBlueprint.Create","User.Read" -TenantId <your-tenant-id>

$currentUser = Get-MgContext | Select-Object -ExpandProperty Account
$user = Get-MgUser -UserId $currentUser

Write-Host "Current user: $($user.DisplayName) ($($user.Id))"
Write-Host "Sponsor user: $($user.DisplayName) ($($user.Id))"


$body = @{
    "@odata.type" = "Microsoft.Graph.AgentIdentityBlueprint"
    "displayName" = "My Agent Identity Blueprint"
    "sponsors@odata.bind" = @("https://microsoft.graph.microsoft.com/v1.0/users/$($user.Id)")
    "owners@odata.bind" = @("https://microsoft.graph.microsoft.com/v1.0/users/$($user.Id)")
} | ConvertTo-Json -Depth 5

$response = Invoke-MgGraphRequest `
    -Method POST `
    -Uri "https://graph.microsoft.com/v1.0/applications/microsoft.graph.agentIdentityBlueprint" `
    -Body $body `
    -ContentType "application/json"

$response

Depois de criar o blueprint de identidade do agente, registre o valor da appId proveniente da saída.

Configurar credenciais para o modelo de identidade do agente

Para solicitar os tokens de acesso usando o blueprint de identidade do agente, você deve adicionar uma credencial de cliente. É recomendável usar uma identidade gerenciada como uma credencial de identidade federada (FIC) para implantações de produção. As identidades gerenciadas permitem que você obtenha tokens Microsoft Entra sem precisar gerenciar credenciais. Para obter mais informações, consulte Identidades gerenciadas para recursos do Azure.

Outros tipos de credenciais de aplicativo, incluindo keyCredentials e passwordCredentials têm suporte, mas não são recomendados para produção. Eles podem ser convenientes para desenvolvimento e teste locais ou onde as identidades gerenciadas não funcionarão, mas essas opções não se alinham às práticas recomendadas de segurança. Para obter mais informações, consulte as práticas recomendadas de segurança para propriedades do aplicativo.

Tenha em mente que, para usar uma identidade gerenciada, você deve executar seu código em um serviço de Azure, como uma máquina virtual ou Serviço de Aplicativo do Azure. Para desenvolvimento e teste local, use um segredo ou certificado do cliente.

Microsoft API do Graph
Microsoft Graph PowerShell

Para enviar esta solicitação:

Você precisa da permissão AgentIdentityBlueprint.AddRemoveCreds.All.
Substitua o espaço reservado <agent-blueprint-id> pelo appId blueprint de identidade do agente.
Substitua o marcador <managed-identity-principal-id> pela ID da sua identidade gerida.

Adicione uma identidade gerenciada como uma credencial usando a seguinte solicitação:

POST https://graph.microsoft.com/v1.0/applications/<agent-blueprint-id>/federatedIdentityCredentials
OData-Version: 4.0
Content-Type: application/json
Authorization: Bearer <token>

{
    "name": "my-managed-identity",
    "issuer": "https://login.microsoftonline.com/<your-tenant-id>/v2.0",
    "subject": "<managed-identity-principal-id>",
    "audiences": [
        "api://AzureADTokenExchange"
    ]
}

Esta etapa inclui as seguintes tarefas distintas:

Conecte-se ao seu locatário com o escopo AgentIdentityBlueprint.AddRemoveCreds.All.
Adicione uma identidade gerenciada como credencial para o blueprint de identidade do agente, usando o principal do blueprint de identidade do agente criado anteriormente.

Install-Module Microsoft.Graph.Applications -Scope CurrentUser -Force

Connect-MgGraph -Scopes "AgentIdentityBlueprint.AddRemoveCreds.All" -TenantId <your-tenant-id>

$applicationId = "<agent-blueprint-id>"

$federatedCredential = @{
  Name             = "my-managed-identity"
  Issuer           = "https://login.microsoftonline.com/<your-tenant-id>/v2.0"
  Subject          = "<managed-identity-principal-id>"
  Audiences         = @("api://AzureADTokenExchange")
}

New-MgApplicationFederatedIdentityCredential `
  -ApplicationId $applicationId `
  -BodyParameter $federatedCredential

Outras credenciais de aplicativo

Para cenários em que as identidades gerenciadas não funcionarão ou se você estiver criando um blueprint localmente para teste, use as etapas a seguir para adicionar as credenciais.

Microsoft API do Graph
Microsoft Graph PowerShell

Para enviar essa solicitação, primeiro você precisa obter um token de acesso com a permissão delegada AgentIdentityBlueprint.AddRemoveCreds.All

POST https://graph.microsoft.com/v1.0/applications/<agent-blueprint-id>/addPassword
Content-Type: application/json
Authorization: Bearer <token>

{
  "passwordCredential": {
    "displayName": "My Secret",
    "endDateTime": "2026-08-05T23:59:59Z"
  }
}

Connect-MgGraph -Scopes "AgentIdentityBlueprint.AddRemoveCreds.All" -TenantId <your-tenant-id>

$applicationId = "<agent-blueprint-application-id>"

# Define the secret properties
$displayName = "My Secret"
$endDate = (Get-Date).AddYears(1).ToString("o")  # 1 year from now, in ISO 8601 format

# Construct the password credential
$passwordCredential = @{
    displayName = $displayName
    endDateTime = $endDate
}

# Add the password (client secret)
$response = Add-MgApplicationPassword -ApplicationId $applicationId -PasswordCredential $passwordCredential

# Output the generated secret (only returned once!)
Write-Host "Secret Text: $($response.secretText)"

Observação

Seu locatário pode ter políticas de ciclo de vida de credencial que restringem o tempo de vida máximo para segredos do cliente. Se você receber um erro sobre o tempo de vida da credencial, reduza o endDateTime valor para se alinhar à política da sua organização.

Certifique-se de armazenar com segurança os passwordCredential valores gerados. Ele não pode ser exibido após a criação inicial. Você também pode usar certificados de cliente como credenciais; consulte Adicionar uma credencial de certificado.

Se os agentes criados com o blueprint oferecerem suporte a agentes interativos, em que o agente atua em nome de um usuário, seu blueprint deverá expor um escopo para que o front-end do agente possa passar um token de acesso para o back-end do agente. Este token pode ser utilizado pelo back-end do agente para obter um token de acesso e atuar em nome do usuário.

Configurar o URI do identificador e o seu escopo

Para receber solicitações de entrada de usuários e outros agentes, como para qualquer API Web, você precisa definir um URI de identificador e um escopo OAuth para o blueprint de identidade do agente:

Microsoft API do Graph
Microsoft Graph PowerShell

Para enviar esta solicitação:

Você precisa da permissão AgentIdentityBlueprint.UpdateAuthProperties.All.
Substitua o espaço reservado <agent-blueprint-id> pelo appId blueprint de identidade do agente.
Você precisa de um GUID (Identificador Global exclusivo). No PowerShell, você pode executar [guid]::NewGuid() ou usar um gerador de GUID online. Copie o GUID gerado e use-o para substituir o marcador de posição <generate-a-guid>.

PATCH https://graph.microsoft.com/v1.0/applications/<agent-blueprint-id>
OData-Version: 4.0
Content-Type: application/json
Authorization: Bearer <token>

{
    "identifierUris": ["api://<agent-blueprint-id>"],
    "api": {
      "oauth2PermissionScopes": [
        {
          "adminConsentDescription": "Allow the application to access the agent on behalf of the signed-in user.",
          "adminConsentDisplayName": "Access agent",
          "id": "<generate-a-guid>",
          "isEnabled": true,
          "type": "User",
          "value": "access_agent"
        }
      ]
  }
}

Uma chamada bem-sucedida gera uma resposta 204.

Esta etapa inclui as seguintes tarefas distintas:

Instale o módulo necessário se ainda não tiver feito isso.
Conecte-se ao seu locatário com o escopo AgentIdentityBlueprint.UpdateAuthProperties.All.
Configure o URI e o escopo do novo modelo de identidade do agente.

Connect-MgGraph -Scopes "AgentIdentityBlueprint.UpdateAuthProperties.All" -TenantId <your-tenant-id>

$AppId = "<agent-blueprint-id>"
$IdentifierUri = "api://<agent-blueprint-id>"
$ScopeId = [guid]::NewGuid()

# Construct the OAuth2 permission scope
$scope = @{
    adminConsentDescription = "Allow the application to access the agent on behalf of the signed-in user."
    adminConsentDisplayName = "Access agent"
    id = $ScopeId
    isEnabled = $true
    type = "User"
    value = "access_agent"
}

Update-MgApplication -ApplicationId $AppId `
    -IdentifierUris @($IdentifierUri) `
    -Api @{ oauth2PermissionScopes = @($scope) }

Criar um blueprint de entidade de agente

Nesta etapa, você criará uma entidade para o blueprint de identidade do agente. Para obter mais informações, consulte identidades do Agente, entidades de serviço e aplicativos.

Microsoft API do Graph
Microsoft Graph PowerShell

Substitua o marcador de posição <agent-blueprint-app-id> pelo appId que você copiou dos resultados da etapa anterior.

POST https://graph.microsoft.com/v1.0/serviceprincipals/microsoft.graph.agentIdentityBlueprintPrincipal
OData-Version: 4.0
Content-Type: application/json
Authorization: Bearer <token>

{
  "appId": "<agent-blueprint-app-id>"
}

Depois de criar o blueprint de identidade do agente, crie uma entidade do blueprint de identidade do agente usando o blueprint appId de identidade do agente recém-criado.

Connect-MgGraph -Scopes "AgentIdentityBlueprintPrincipal.Create" -TenantId <your-tenant-id>

Connect-MgGraph -Scopes "AgentIdentityBlueprintPrincipal.Create" -TenantId
$body = @{
    appId   = "<agent-blueprint-client-id>"
}
Invoke-MgGraphRequest -Method POST `
        -Uri "https://graph.microsoft.com/v1.0/serviceprincipals/microsoft.graph.agentIdentityBlueprintPrincipal" `
        -Headers @{ "OData-Version" = "4.0" } `
        -Body ($body | ConvertTo-Json)

O plano do agente agora está pronto e visível no centro de administração Microsoft Entra. Na próxima etapa, você usará esse blueprint para criar identidades de agente.

Registrar agentes no registro do Agente 365

Depois de criar um blueprint de identidade do agente, registre-o no registro Agent 365 para que os administradores possam descobrir, governar e gerenciar o agente do Centro de administração do Microsoft 365. Esta seção também fornece instruções para adicionar modelos de identidade de agente existentes que podem não aparecer atualmente no registro do Agente 365.

Usar o SDK de Agentes do Microsoft 365 (recomendado)

O SDK de Agentes do Microsoft 365 agora está disponível em geral e é a maneira recomendada de criar e provisionar agentes. O SDK O SDK manipula a criação e o registro de identidade do agente no registro do Agente 365 para você, de modo que as identidades do agente serão exibidas automaticamente sem código extra. Se você estiver iniciando um novo projeto de agente ou tiver flexibilidade para migrar o código existente, use o SDK. É o caminho mais simples e durável e evita a necessidade de coordenar várias chamadas à API por conta própria.

Usar a CLI do Agent 365

A CLI do Agente 365 é outra opção que manipula a configuração para você, incluindo o registro do agente. Siga as instruções de instalação usando a ordem de execução recomendada. Use o seguinte comando:

a365 setup all

Se o registro falhar, você poderá executar novamente apenas a etapa de registro sem precisar passar por todo o processo. Use o seguinte comando:

a365 setup all --agent-registration-only

Chamar a API do Registro do Agente diretamente

Se você precisar criar modelos de identidade de agente programaticamente com a Microsoft API do Graph, por exemplo, se você tem fluxos de trabalho de emissão de identidade existentes que não podem ser alterados imediatamente, será necessário adicionar uma chamada explícita à API do Registro do Agente após criar o modelo de identidade de agente para publicar o cartão do agente correspondente. Esta etapa registra o cartão do agente no Registro do Agente 365 para que ele apareça para os administradores.

Crie o blueprint de identidade do agente usando o microsoft API do Graph (conforme mostrado nas seções anteriores).
Siga imediatamente com uma chamada à API do Registro do Agente para postar o cartão do agente correspondente, incluindo os metadados de que seus administradores precisam para governá-lo.
Trate o padrão de duas chamadas de forma de repetição segura de forma que uma falha transitória em qualquer uma das chamadas deixe o ambiente em um estado recuperável.

Para obter esquemas de solicitação e resposta, permissões necessárias e exemplos de código, consulte a referência da API do Registro do Agente.

Tip

Se você tiver modelos de identidade de agente existentes que não aparecem no registro do Agent 365, registre-os usando a API do Registro do Agente. Para blueprints de identidade de agente em massa, use o ponto de extremidade em lote. Para obter mais informações, consulte Convergência do Registro do Agente com o Microsoft Agent 365.

Modelos de identidade de agentes existentes que não estão no registro do Agente 365

Para blueprints de identidade de agente que foram criados anteriormente usando-se a API do Graph da ID do Agente do Microsoft Entra mas não estão visíveis no momento no Registro do Agent 365, você pode registrá-los usando a API do Registro do Agente. Esta etapa garante que eles apareçam no registro do Agente 365.

Excluir um blueprint de identidade do agente

Quando um agente for desativado, exclua o blueprint de identidade do agente associado. A exclusão do blueprint dispara a limpeza automática de todas as identidades de agentes subordinados e das contas de usuário dos agentes. Para obter instruções passo a passo de exclusão e restauração, consulte Excluir e restaurar objetos de identidade do agente.

Próxima etapa

Criar e excluir identidades do agente

Comentários

Esta página foi útil?

Last updated on 2026-05-09

Criar um plano de identidade do agente

Pré-requisitos

Prepare o seu ambiente

Autorizar um cliente a criar modelos de identidade de agente

Criar um plano de identidade do agente

Use o centro de administração do Microsoft Entra

Criar programaticamente

Configurar credenciais para o modelo de identidade do agente

Outras credenciais de aplicativo

Configurar o URI do identificador e o seu escopo

Criar um blueprint de entidade de agente

Registrar agentes no registro do Agente 365

Usar o SDK de Agentes do Microsoft 365 (recomendado)

Usar a CLI do Agent 365

Chamar a API do Registro do Agente diretamente

Modelos de identidade de agentes existentes que não estão no registro do Agente 365

Excluir um blueprint de identidade do agente

Próxima etapa

Comentários

Recursos adicionais