创建代理标识蓝图

代理标识蓝图用于使用这些代理标识创建代理标识和请求令牌。在创建代理标识蓝图的过程中，设置该蓝图的所有者和发起人，以建立责任和管理关系。如果代理旨在接收来自其他代理和用户的传入请求，则还可以配置标识符 URI，并定义从此蓝图创建的代理的范围。

可以通过两种方式创建代理标识蓝图：

Microsoft Entra 管理中心 - 使用向导进行快速设置，以创建蓝图和其主要组件。
Microsoft 图形 API 或 PowerShell — 以编程方式创建和完全配置蓝图，包括凭据、标识符 URI、范围和单个工作流中的蓝图主体。

先决条件

若要创建代理标识蓝图，需要：

特权角色管理员角色是授予Microsoft Graph应用程序权限所需的最低特权角色。
需要由云应用程序管理员或应用程序管理员授予 Microsoft Graph 委派权限。
代理 ID 开发人员和代理 ID 管理员角色都可以创建代理标识蓝图和代理标识蓝图主体。
- 代理 ID 开发人员可以在代理标识蓝图上配置联合标识凭据。
- 代理 ID 管理员可以在代理标识蓝图上配置联合标识凭据，并且需要添加机密或证书凭据。
如果使用 PowerShell，则需要版本 7。

注释

代理标识蓝图或代理标识蓝图主体的所有者可以为该蓝图创建代理标识，而无需Microsoft Entra 智能体 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 智能体 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://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

创建代理标识蓝图后，记录输出中的值 appId 。

为代理身份蓝图配置凭据

若要使用代理标识蓝图请求访问令牌，必须添加客户端凭据。建议在生产部署中使用托管身份作为联合身份凭据（FIC）。托管标识允许你获取Microsoft Entra令牌，而无需管理任何凭据。有关详细信息，请参阅 Azure 资源的托管标识。

支持的其他类型的应用凭据包括keyCredentials和passwordCredentials，但不建议用于生产环境。它们在本地开发和测试时或托管标识不可用的情况下可能很方便，但这些选择与安全最佳实践不符。有关详细信息，请参阅应用程序属性的安全最佳做法。

请记住，若要使用托管标识，必须在Azure服务（例如虚拟机或Azure 应用服务）上运行代码。对于本地开发和测试，请使用客户端机密或证书。

Microsoft 图形 API
Microsoft Graph PowerShell

若要发送此请求，请执行下列步骤：

你需要 AgentIdentityBlueprint.AddRemoveCreds.All 权限。
将 <agent-blueprint-id> 占位符替换为 appId 代理标识蓝图。
将 <managed-identity-principal-id> 占位符替换为托管身份的 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 生成的值。初始创建后无法查看它。还可以使用客户端证书作为凭据;请参阅添加证书凭据。

如果使用蓝图创建的代理将支持交互式代理（代理代表用户执行作），则蓝图必须公开范围，以便代理前端可以将访问令牌传递给代理后端。然后，代理后端可以使用此令牌来获取代表用户执行操作的访问令牌。

配置标识符 URI 和范围

若要接收来自用户和其他代理的传入请求，例如对于任何 Web 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 占位符。

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 管理中心中可见。在下一步中，你将使用此蓝图创建代理标识。

删除代理标识蓝图

当停用代理时，删除关联的代理身份蓝图。删除蓝图会触发自动清理所有子代理标识和代理用户帐户。有关分步删除和还原说明，请参阅 “删除和还原代理标识对象”。

后续步骤

创建和删除代理标识

反馈

此页面是否有帮助？

Last updated on 2026-05-01

创建代理标识蓝图

先决条件

准备好你的环境

授权客户端创建代理标识蓝图

创建代理标识蓝图

使用Microsoft Entra管理中心

以编程方式创建

为代理身份蓝图配置凭据

其他应用凭据

配置标识符 URI 和范围

创建代理蓝图主体

删除代理标识蓝图

后续步骤

反馈

其他资源