SKILL: Criando Usuários Agente no Microsoft Entra Agent ID

Visão Geral

Um usuário agente é uma identidade de usuário especializada no Microsoft Entra ID que permite que agentes de IA atuem como trabalhadores digitais. Ele permite que os agentes acessem APIs e serviços que exigem estritamente identidades de usuário (por exemplo, caixas de correio do Exchange, Teams, organogramas), mantendo limites de segurança apropriados.

Usuários agente recebem tokens com idtyp=user, ao contrário de identidades de agente regulares que recebem idtyp=app.

Pré-requisitos

• Um tenant do Microsoft Entra com funcionalidades do Agent ID
• Uma identidade de agente (principal de serviço do tipo ServiceIdentity) criada a partir de um blueprint de identidade de agente
• Uma das seguintes permissões:
  • AgentIdUser.ReadWrite.IdentityParentedBy (privilégio mínimo)
  • AgentIdUser.ReadWrite.All
  • User.ReadWrite.All
• O chamador deve ter no mínimo a função Administrador do Agent ID (em cenários delegados)

Importante: O identityParentId deve referenciar uma identidade de agente real (criada via blueprint de identidade de agente), NÃO um principal de serviço de aplicativo regular. Você pode verificar confirmando que o principal de serviço tem @odata.type: #microsoft.graph.agentIdentity e servicePrincipalType: ServiceIdentity.

Arquitetura

Agent Identity Blueprint (application template)
    │
    ├── Agent Identity (service principal - ServiceIdentity)
    │       │
    │       └── Agent User (user - agentUser) ← 1:1 relationship
    │
    └── Agent Identity Blueprint Principal (service principal in tenant)

Etapa 1: Verificar a Existência da Identidade de Agente

Antes de criar um usuário agente, confirme se a identidade de agente é do tipo correto agentIdentity:

GET https://graph.microsoft.com/beta/servicePrincipals/{agent-identity-id}
Authorization: Bearer <token>

Verifique se a resposta contém:

{
  "@odata.type": "#microsoft.graph.agentIdentity",
  "servicePrincipalType": "ServiceIdentity",
  "agentIdentityBlueprintId": "<blueprint-id>"
}

PowerShell

Connect-MgGraph -Scopes "Application.Read.All" -TenantId "<tenant>" -UseDeviceCode -NoWelcome
Invoke-MgGraphRequest -Method GET `
  -Uri "https://graph.microsoft.com/beta/servicePrincipals/<agent-identity-id>" | ConvertTo-Json -Depth 3

Erro comum: Usar o appId de um registro de aplicativo ou o id de um principal de serviço de aplicativo regular falhará. Apenas identidades de agente criadas a partir de blueprints funcionam.

Etapa 2: Criar o Usuário Agente

Requisição HTTP

POST https://graph.microsoft.com/beta/users/microsoft.graph.agentUser
Content-Type: application/json
Authorization: Bearer <token>

{
  "accountEnabled": true,
  "displayName": "My Agent User",
  "mailNickname": "my-agent-user",
  "userPrincipalName": "my-agent-user@yourtenant.onmicrosoft.com",
  "identityParentId": "<agent-identity-object-id>"
}

Propriedades Necessárias

PowerShell

Connect-MgGraph -Scopes "User.ReadWrite.All" -TenantId "<tenant>" -UseDeviceCode -NoWelcome

$body = @{
  accountEnabled    = $true
  displayName       = "My Agent User"
  mailNickname      = "my-agent-user"
  userPrincipalName = "my-agent-user@yourtenant.onmicrosoft.com"
  identityParentId  = "<agent-identity-object-id>"
} | ConvertTo-Json

Invoke-MgGraphRequest -Method POST `
  -Uri "https://graph.microsoft.com/beta/users/microsoft.graph.agentUser" `
  -Body $body -ContentType "application/json" | ConvertTo-Json -Depth 3

Observações Importantes

• Sem senha — usuários agente não podem ter senhas. Eles se autenticam através das credenciais de sua identidade de agente pai.
• Relação 1:1 — cada identidade de agente pode ter no máximo um usuário agente. Tentar criar um segundo retorna 400 Bad Request.
• O userPrincipalName deve ser único. Não reutilize o UPN de um usuário existente.

Etapa 3: Atribuir um Gerente (Opcional)

…