建立代理人身份藍圖

使用代理身份藍圖來建立代理身份並使用這些代理身份請求權杖。在建立代理人身份藍圖的過程中，你會設定藍圖的擁有者和贊助人，以建立問責與行政關係。你也可以設定一個識別碼 URI，並為從此藍圖建立的代理定義一個範圍，前提是代理是設計來接收來自其他代理和使用者的來信請求。

你可以用兩種方式建立代理人身份藍圖：

Microsoft Entra 系統管理中心 — 使用精靈快速設定藍圖及其原則。
Microsoft 圖形 API 或 PowerShell — 以程式化方式建立並完整配置藍圖，包含憑證、識別碼 URI、範圍及藍圖原則，集中於單一工作流程中。

先決條件

要建立代理人身份藍圖，你需要：

特權角色管理員角色是授予Microsoft Graph應用程式權限所需的最低權限角色。
Cloud Application Administrator 或 Application Administrator 是授予Microsoft Graph委派權限的必要條件。
代理 ID開發人員與代理ID管理員角色皆可建立代理身份藍圖及代理身份藍圖主體。
- Agent ID Developer 可以在代理身份藍圖上配置聯邦身份憑證。
- 代理ID管理員可以在代理身份藍圖上設定聯邦身份憑證，並需新增秘密或憑證憑證。
如果使用 PowerShell，則需要版本 7。

備註

擁有代理身份藍圖或代理身份藍圖主體的人，即使沒有 Microsoft Entra Agent ID 角色，仍然可以為該藍圖建立代理身份。代理身份藍圖建立者會自動被設定為藍圖及其相關代理身份藍圖主體的擁有者。

準備您的環境

為了簡化流程，花點時間設定環境以取得正確的權限。

授權客戶建立代理人身份藍圖

在本文中，你將使用 Microsoft Graph PowerShell 或其他用戶端來建立你的代理身份藍圖。您必須授權此用戶端建立並設定代理身份藍圖，並建立代理身份藍圖主體。用戶端需要以下 Microsoft Graph 權限：

AgentIdentityBlueprint.Create 授權權限
AgentIdentityBlueprint.AddRemoveCreds.All 授權
AgentIdentityBlueprint.UpdateAuthProperties.All 委派的權限
AgentIdentityBlueprintPrincipal.Create 授權權限

本指南中的步驟會使用所有委派權限，但你也可以在需要授權的情況下使用應用程式權限。

要連接所有 Microsoft Graph PowerShell 所需的範圍，請執行以下指令：

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

建立代理人身份藍圖

代理人身份藍圖必須有贊助者，也就是對代理人負責的使用者或被支援團體。建議擁有者，即能修改代理身份藍圖的使用者或服務主體。如需相關資訊，請參見 Microsoft Entra Agent ID 中的行政關係。

使用 Microsoft Entra 管理中心

你可以直接在 Microsoft Entra 系統管理中心建立代理身份藍圖。管理中心精靈會自動建立代理身份藍圖及其藍圖主體。

備註

管理中心精靈負責設定藍圖名稱並指派擁有者和贊助者。要設定憑證、識別碼 URI、範圍或權限，請使用 Microsoft 圖形 API 或 PowerShell，或在建立後透過藍圖管理中心的詳細頁面進行設定。

登入 Microsoft Entra 系統管理中心。
瀏覽至 Entra ID>代理程式>代理程式藍圖。
選擇新代理藍圖（預覽）。
在基礎標籤中，請在 代理人藍圖名稱 欄位輸入一個名稱，然後選擇 「下一步」。
在 「業主與贊助者 」標籤中，可選擇性地更改或新增藍圖的擁有者與贊助者：
- 選擇擁有者欄位旁的鉛筆圖示，以更改或新增能管理藍圖的使用者。
- 請選擇贊助商欄位旁的鉛筆圖示，以更改或新增可贊助藍圖的使用者。
備註

贊助者可以是使用者、動態會員群組或 Microsoft 365 群組。安全群組與可角色指派群組不被支援作為贊助者。
選取 [下一步]。
檢視你的設定，然後選擇建立。
選擇完成以退出精靈，或選擇 前往代理藍圖 查看藍圖的詳細頁面或設定更多設定。

欲了解更多關於管理代理人身份藍圖的資訊，請參閱「管理代理人身份藍圖」。

使用程式設計來創建

若要使用程式碼建立代理身份藍圖，請使用 Microsoft 圖形 API 或 PowerShell。

Microsoft 圖形 API
Microsoft Graph PowerShell

此步驟建立代理人身份藍圖，指派擁有者與贊助人，並需具備以下細節：

許可 AgentIdentityBlueprint.Create 。
OData-Version 標頭必須設為 4.0。
範例請求主體中擁有者與贊助者欄位的使用者 ID。需要有贊助人，但擁有者是可選的。

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

建立代理身份藍圖後，記錄下一步驟的值 appId 。

此步驟建立代理身份藍圖應用程式，使用目前使用者作為擁有者與贊助者，並包含以下不同任務：

與您的租戶建立連結，使用 AgentIdentityBlueprint.Create 及 User.Read 權限。
新增目前使用者為代理人身分藍圖的贊助人和擁有者。
建立代理身份藍圖應用程式。

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://graph.microsoft.com/v1.0/users/$($user.Id)")
    "owners@odata.bind" = @("https://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" `
    -Headers @{ "OData-Version" = "4.0" } `
    -Body $body `
    -ContentType "application/json"

$response

建立代理身份藍圖後，記錄輸出中的值 appId 。

設定代理身份藍圖的憑證

若要使用 agent identity blueprint 來請求 access token，則必須新增客戶端憑證。我們建議在生產部署中使用管理身份作為聯邦身份憑證（FIC）。受管理身份讓你無需管理任何憑證即可取得 Microsoft Entra 令牌。欲了解更多資訊，請參閱Azure 資源的受控身分識別。

其他類型的應用程式憑證，包括 keyCredentials 和 passwordCredentials 支援，但不建議在生產環境中使用。它們對於本地開發與測試或管理身份無法運作的情況來說可能很方便，但這些選項與安全最佳實務並不一致。欲了解更多資訊，請參閱應用程式屬性的安全最佳實務。

請記住，要使用受管理身份，必須在 Azure 服務上執行程式碼，例如虛擬機或 Azure App 服務。在本地開發與測試時，請使用用戶端秘密或憑證。

Microsoft 圖形 API
Microsoft Graph PowerShell

要發送此請求：

您需要 AgentIdentityBlueprint.AddRemoveCreds.All 權限。
將<agent-blueprint-id>佔位符替換為appId代理人身份藍圖。
用你的受管理的身分識別碼取代占位符<managed-identity-principal-id>。

請使用以下請求新增一個受管理身份作為憑證：

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

此步驟包含以下不同任務：

藉由 AgentIdentityBlueprint.AddRemoveCreds.All 範圍連接到你的租戶。
使用先前建立的代理身份藍圖主體，將一個受管理的身份新增為代理身份藍圖的憑證。

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

其他應用程式憑證

對於管理身份無法運作的情況，或是你在本地建立藍圖進行測試，請依照以下步驟新增憑證。

Microsoft 圖形 API
Microsoft Graph PowerShell

要發送此請求，首先，需取得具有委派權限的存取令牌 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)"

備註

你的租戶可能有憑證生命週期政策，限制用戶端秘密的最大壽命。如果你收到關於憑證壽命的錯誤，請降低該 endDateTime 值以符合組織政策。

務必妥善儲存所產生的 passwordCredential 數值。初始建立後就無法查看。你也可以將客戶端憑證作為憑證使用;請參見新增憑證憑證。

如果用藍圖建立的代理會支援互動代理，代理代表使用者行動，你的藍圖必須公開一個範圍，讓代理前端能將 access token 傳給代理後端。這個令牌接著可以被代理程式後端用來取得一個存取權杖，代表使用者執行操作。

設定識別碼 URI 與作用域

要接收來自使用者及其他代理的請求，就像任何網頁 API 一樣，你需要為代理身份藍圖定義識別碼 URI 和 OAuth 範圍：

Microsoft 圖形 API
Microsoft Graph PowerShell

要發送此請求：

你需要得到許可 AgentIdentityBlueprint.UpdateAuthProperties.All。
將<agent-blueprint-id>佔位符替換為appId代理人身份藍圖。
你需要一個全球唯一識別碼（GUID）。在 PowerShell 裡，執行 [guid]::NewGuid() 或使用線上 GUID 產生器。複製產生的 GUID，並用它來取代佔位符 <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"
        }
      ]
  }
}

成功呼叫會產生 204 回應。

此步驟包含以下不同任務：

如果還沒安裝所需的模組，請先安裝。
藉由 AgentIdentityBlueprint.UpdateAuthProperties.All 範圍連接到你的租戶。
為新的代理身份藍圖設定 URI 與範圍。

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

建立代理藍圖主體

在此步驟中，你建立代理程式身份藍圖的主體。欲了解更多資訊，請參閱代理身份、服務主體與應用程式。

Microsoft 圖形 API
Microsoft Graph PowerShell

請將<agent-blueprint-app-id>佔位符替換為appId，此appId是你從前一步的結果中複製而來。

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

建立代理人身份藍圖後，使用新建立的代理人身份藍圖 appId建立代理人身份藍圖主體。

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)

你的代理人藍圖現在已經準備好，並顯示在Microsoft Entra 系統管理中心中。下一步，你將使用這個藍圖來建立代理人身份。

將代理人登記在代理人365登記冊中

建立代理身份藍圖後，請將其註冊到 Agent 365 登錄檔，讓管理員能從Microsoft 365 系統管理中心發現、管理和管理代理。本節亦提供新增可能尚未出現在 Agent 365 登錄檔中的現有代理人身份藍圖的指示。

建議使用 Microsoft 365 Agents SDK

Microsoft 365 Agents SDK 現已普遍可用，是建置與配置代理的推薦方式。 SDK SDK 會幫你在 Agent 365 登錄檔中建立和註冊代理身份，所以你的代理身份會自動顯示，不會有額外的程式碼。如果你要開始新的代理專案，或有彈性遷移現有程式碼，請使用 SDK。這是最簡單、最耐用的路徑，也避免了自己協調多個 API 呼叫的需求。

使用 Agent 365 CLI

Agent 365 CLI 是另一個幫你設定的選項，包括代理註冊。依照建議的執行順序執行設定說明。使用下列命令：

a365 setup all

如果註冊失敗，你可以只重跑註冊步驟，而不必經歷整個流程。使用下列命令：

a365 setup all --agent-registration-only

直接呼叫代理登錄 API

例如，如果你必須用 Microsoft 圖形 API 程式化建立代理身份藍圖，例如因為已有的身份發行工作流程無法立即更改，你需要對代理登錄 API after 新增明確呼叫，建立代理身份藍圖以貼出對應的代理卡。此步驟會將代理卡註冊至 Agent 365 登錄檔，讓管理員能看到。

使用Microsoft 圖形 API建立代理身份藍圖（如前述章節所示）。
接著立即呼叫 Agent Registry API，發布對應的代理卡，並附上管理員需要管理的元資料。
以安全的重試方式處理雙重呼叫模式，確保當任一通話出現暫時性故障時，環境仍能保持在可恢復狀態。

關於請求與回應結構、所需權限及程式碼範例，請參閱代理登錄 API 參考。

Tip

如果你有現有的代理身份藍圖，但不在代理 365 登錄檔中，請使用代理註冊 API 來註冊。對於批量取得代理身份藍圖，請使用批次端點。欲了解更多資訊，請參閱代理人註冊局與Microsoft代理人365的合併。

現有但未在 Agent 365 註冊中的代理人身份藍圖

對於先前使用 Microsoft Entra Agent ID 圖形 API 建立但目前未在 Agent 365 登錄檔中顯示的代理身份藍圖，您可以使用代理註冊 API 來註冊。此步驟確保他們出現在 Agent 365 登記冊中。

刪除代理人身份藍圖

當代理被除役時，刪除相關的代理身份藍圖。刪除藍圖會自動清理所有子代理的身份和使用者帳號。關於逐步刪除與還原的步驟，請參見「刪除與還原代理身份物件」。

下一個步驟

建立與刪除代理身份

意見反應

此頁面對您有幫助嗎？

上次更新時間： 2026-05-09

建立代理人身份藍圖

先決條件

準備您的環境

授權客戶建立代理人身份藍圖

建立代理人身份藍圖

使用 Microsoft Entra 管理中心

使用程式設計來創建

設定代理身份藍圖的憑證

其他應用程式憑證

設定識別碼 URI 與作用域

建立代理藍圖主體

將代理人登記在代理人365登記冊中

建議使用 Microsoft 365 Agents SDK

使用 Agent 365 CLI

直接呼叫代理登錄 API

現有但未在 Agent 365 註冊中的代理人身份藍圖

刪除代理人身份藍圖

下一個步驟

意見反應

其他資源