SKILL: Creating Agent Users in Microsoft Entra Agent ID

Overview

エージェントユーザーは、AI エージェントがデジタルワーカーとして機能することを可能にする Microsoft Entra ID の特殊なユーザーアイデンティティです。エージェントがユーザーアイデンティティを厳密に要求する API やサービス (Exchange メールボックス、Teams、組織図など) にアクセスできるようにしながら、適切なセキュリティ境界を維持します。

エージェントユーザーは idtyp=user を含むトークンを受け取ります。一方、通常のエージェントアイデンティティは idtyp=app を受け取ります。

---

Prerequisites

• Agent ID 機能を備えた Microsoft Entra テナント
• エージェントアイデンティティブループリントから作成された エージェントアイデンティティ (タイプ ServiceIdentity のサービスプリンシパル)
• 次のいずれかの 権限:
  • AgentIdUser.ReadWrite.IdentityParentedBy (最小権限)
  • AgentIdUser.ReadWrite.All
  • User.ReadWrite.All
• 呼び出し元は最小限、Agent ID Administrator ロール (委任シナリオの場合) を持っている必要があります

重要: identityParentId は、通常のアプリケーションサービスプリンシパルではなく、真のエージェントアイデンティティ (エージェントアイデンティティブループリント経由で作成) を参照する必要があります。サービスプリンシパルに @odata.type: #microsoft.graph.agentIdentity と servicePrincipalType: ServiceIdentity があるかを確認して検証できます。

---

Architecture

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)

Component	Type	Token Claim	Purpose
Agent Identity	Service Principal	idtyp=app	バックエンド/API 操作
Agent User	User (agentUser)	idtyp=user	M365 におけるデジタルワーカーとしての動作

---

Step 1: Verify the Agent Identity Exists

エージェントユーザーを作成する前に、エージェントアイデンティティが適切な agentIdentity タイプであることを確認します:

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

レスポンスに以下の内容が含まれていることを確認します:

{
  "@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

よくある間違い: アプリ登録の appId または通常のアプリケーションサービスプリンシパルの id を使用すると失敗します。ブループリントから作成されたエージェントアイデンティティのみが機能します。

---

Step 2: Create the Agent User

HTTP Request

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>"
}

Required Properties

Property	Type	Description
accountEnabled	Boolean	アカウントを有効にするには true
displayName	String	ユーザーフレンドリーな名前
mailNickname	String	メールエイリアス (スペースや特殊文字なし)
userPrincipalName	String	UPN — テナント内で一意である必要があります (alias@verified-domain)
identityParentId	String	親エージェントアイデンティティのオブジェクト ID

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

Key Notes

• パスワードなし — エージェントユーザーはパスワードを持つことはできません。親エージェントアイデンティティの認証情報を使用して認証します。
• 1:1 の関係 — 各エージェントアイデンティティは最大 1 つのエージェントユーザーを持つことができます。2 番目の作成を試みると 400 Bad Request が返されます。
• userPrincipalName は一意である必要があります。既存のユーザーの UPN を再利用しないでください。

---

Step 3: Assign a Manager (Optional)

マネージャーを割り当てることで、エージェントユーザーが組織図 (Teams など) に表示されるようにできます。

PUT https://graph.microsoft.com/beta/users/{agent-user-id}/manager/$ref
Content-Type: application/json
Authorization: Bearer <token>

{
  "@odata.id": "https://graph.microsoft.com/beta/users/{manager-user-id}"
}

PowerShell

$managerBody = '{"@odata.id":"https://graph.microsoft.com/beta/users/<manager-user-id>"}'
Invoke-MgGraphRequest -Method PUT `
  -Uri "https://graph.microsoft.com/beta/users/<agent-user-id>/manager/`$ref" `
  -Body $managerBody -ContentType "application/json"

---

Step 4: Set Usage Location and Assign Licenses (Optional)

エージェントユーザーがメールボックス、Teams プレゼンスなどを持つには、ライセンスが必要です。使用場所を最初に設定する必要があります。

Set Usage Location

PATCH https://graph.microsoft.com/beta/users/{agent-user-id}
Content-Type: application/json
Authorization: Bearer <token>

{
  "usageLocation": "US"
}

List Available Licenses

GET https://graph.microsoft.com/beta/subscribedSkus?$select=skuPartNumber,skuId,consumedUnits,prepaidUnits
Authorization: Bearer <token>

Organization.Read.All 権限が必要です。

Assign a License

POST https://graph.microsoft.com/beta/users/{agent-user-id}/assignLicense
Content-Type: application/json
Authorization: Bearer <token>

{
  "addLicenses": [
    { "skuId": "<sku-id>" }
  ],
  "removeLicenses": []
}

PowerShell (all in one)

Connect-MgGraph -Scopes "User.ReadWrite.All","Organization.Read.All" -TenantId "<tenant>" -NoWelcome

# Set usage location
Invoke-MgGraphRequest -Method PATCH `
  -Uri "https://graph.microsoft.com/beta/users/<agent-user-id>" `
  -Body '{"usageLocation":"US"}' -ContentType "application/json"

# Assign license
$licenseBody = '{"addLicenses":[{"skuId":"<sku-id>"}],"removeLicenses":[]}'
Invoke-MgGraphRequest -Method POST `
  -Uri "https://graph.microsoft.com/beta/users/<agent-user-id>/assignLicense" `
  -Body $licenseBody -ContentType "application/json"

Tip: Entra 管理者センター から Identity → Users → All users → エージェントユーザーを選択 → Licenses and apps でライセンスを割り当てることもできます。

---

Provisioning Times

Service	Estimated Time
Exchange mailbox	5–30 分
Teams availability	15 分 – 24 時間
Org chart / People search	24–48 時間以内
SharePoint / OneDrive	5–30 分
Global Address List	24 時間以内

---

Agent User Capabilities

• ✅ Microsoft Entra グループに追加 (動的グループを含む)
• ✅ ユーザー専用 API にアクセス (idtyp=user トークン)
• ✅ メールボックス、カレンダー、連絡先を所有
• ✅ Teams チャットおよびチャネルに参加
• ✅ 組織図および People 検索に表示
• ✅ 管理単位に追加
• ✅ ライセンス割り当て

Agent User Security Constraints

• ❌ パスワード、パスキー、またはインタラクティブサインインを持つことはできません
• ❌ 特権管理者ロールを割り当てることはできません
• ❌ ロール割り当て可能なグループに追加することはできません
• ❌ デフォルトではゲストユーザーと同様の権限
• ❌ カスタムロール割り当ては利用できません

---

Troubleshooting

Error	Cause	Fix
Agent user IdentityParent does not exist	identityParentId が存在しないまたは非エージェントアイデンティティオブジェクトを指しています	ID が通常のアプリではなく agentIdentity サービスプリンシパルであることを確認します
400 Bad Request (identityParentId already linked)	エージェントアイデンティティがすでにエージェントユーザーを持っています	各エージェントアイデンティティは 1 つのエージェントユーザーのみをサポートします
409 Conflict on UPN	userPrincipalName がすでに使用されています	一意の UPN を使用してください
License assignment fails	使用場所が設定されていません	ライセンスを割り当てる前に usageLocation を設定します

---

References

• Agent identities
• Agent users
• Agent service principals
• Create agent identity blueprint
• Create agent identities
• agentUser resource type (Graph API)
• Create agentUser (Graph API)