Microsoft Entra 代理 ID 的 AI 引导式设置

载入到Microsoft Entra 智能体 ID涉及多个步骤：创建代理标识蓝图、配置凭据、设置标识符 URI 和范围、创建蓝图主体和预配代理标识。 每个步骤都有其自身的前提条件、验证检查和决策点。

此 AI 驱动的设置通过使用 AI 编码代理（例如 VS Code 中的 GitHub Copilot）来为你执行这些步骤，从而自动化整个工作流程。 你无需在多个文档页面间切换并手动执行命令，只需给AI代理一个指令文件，它会交互式地引导你完成整个过程。 此指令文件以技能的形式提供，可通过多种方式进行访问。

Benefits

AI引导的设置相较于手动工作流程有几个优势：

• 单个入口点：一个指令文件取代了在多个文档页之间导航的需要。 AI代理按顺序执行步骤，自动处理过渡。
• Automated 先决条件验证：AI 代理验证你是否具有正确的Microsoft Entra角色、已安装所需的工具和 Graph 模块，并在进行任何 API 调用之前配置了管理员同意所需的权限。
• 智能默认值和自动检测：AI 代理会查询租户中的现有用户信息和资源详细信息，然后在收集配置输入时将这些值用作建议。
• 派生命名约定：您为代理提供一个显示名称，AI 代理将会根据一致的模式派生出所有相关的资源名称（蓝图、蓝图主体、代理标识、标识符 URI）。
• 内联错误处理：命令失败时，AI 代理会分析错误、建议修复和重试，而无需搜索故障排除文档。 此错误处理对于代理 ID 特定的陷阱（如权限传播延迟和 OData 标头要求）尤其有用。
• 幂等操作：AI 代理在创建资源之前检查资源是否已存在，因此在之前尝试中断时重新运行安装程序是安全的。

先决条件

在开始之前，请确保满足以下先决条件。

所需的工具

AI 引导式设置需要具有终端访问权限的 AI 编码代理：

• 已安装 Visual Studio CodeGitHub Copilot 和 GitHub Copilot Chat 扩展。
• 适用于 Azure 的 GitHub Copilot 扩展，可直接在 VS Code 中提供 Microsoft Entra 智能体 ID 功能。

该技能支持两个预配路径。 根据偏好安装一个或两者：

• PowerShell 方式：PowerShell 7 或更高版本，并使用 Microsoft Graph PowerShell SDK。 使用 Install-Module Microsoft.Graph.Applications -Scope CurrentUser -Force 进行安装。
• Python path：Python 3.8 或更高版本，azure-identity 和 requests。 使用 pip install azure-identity requests 进行安装。

所需账户和权限

• 访问具有以下角色之一的 Microsoft Entra 租户：
  • 代理 ID 开发人员 负责创建代理标识蓝图和代理标识。 代理标识蓝图的任何所有者都可以为该蓝图创建代理标识，而无需代理 ID 角色。
  • 代理 ID 管理员 ，用于对代理 ID 资源进行完全管理访问权限。

• 权限授予的其他角色：
  • 特权角色管理员用来授予Microsoft Graph应用程序权限。
  • Cloud 应用程序管理员或应用管理员授予 Microsoft Graph 的委派权限。

所需的Microsoft Graph 权限

使用的客户端（PowerShell 或自定义应用注册）必须使用以下委派权限进行授权：

所需的代理代码（可选）

如果已有需要代理标识的工作代理项目（Python、Node.js或.NET），请提供项目目录。 如果你还尚未拥有蓝图，你仍可以独立完成蓝图的设置。

开始

AI 引导式设置使用技能，该技能是包含所有步骤和验证检查的单个指令文件。 可以通过以下两种方式之一访问技能：

• 通过 GitHub Copilot for Azure 扩展（推荐）：安装 GitHub Copilot for Azure VS Code 扩展。 当你在 Copilot 对话助手 中询问 Agent ID 设置时，Microsoft Entra 智能体 ID 技能会自动激活。
• 从 GitHub：通过在Copilot 对话助手提示中引用它，使用独立的 Microsoft Entra 智能体 ID 技能。

步骤 1：在 VS Code 中打开项目

在Visual Studio Code中打开代理项目目录（或任何工作目录）。

步骤 2：在代理模式下打开 GitHub Copilot 对话助手

打开 GitHub Copilot 对话助手 面板并切换到 Agent 模式。 代理模式使GitHub Copilot能够运行终端命令、读取文件以及与 AI 引导式设置所需的环境交互。

步骤 3：启动引导设置

如果已安装适用于 Azure 的 GitHub Copilot 扩展，请让 Copilot 设置代理 ID。 例如：

@azure Use the Agent ID Skill to set up an agent identity blueprint and create agent identities for my project using Microsoft Entra Agent ID.

如果你没有安装该扩展，请直接从 GitHub 引用该技能：

Follow the steps in https://github.com/microsoft/GitHub-Copilot-for-Azure/blob/main/plugin/skills/entra-agent-id/SKILL.md

AI 代理读取该技能并开始引导式配置。 它按顺序执行这些步骤：

1. 验证先决条件：检查 Microsoft Entra 角色，并验证是否已安装所需工具（带有 Microsoft Graph 模块的 PowerShell，或带有 azure-identity 的 Python）。
2. Authenticate：使用所需的权限范围连接到 Microsoft Graph。 对于 PowerShell，该技能使用 Connect-MgGraph 并采用显式的委托范围。 对于 Python，它使用专用应用程序注册并通过客户端凭据进行身份验证。
3. 创建代理标识蓝图：收集显示名称，确定发起人（即你），使用输入的终结点（/applications/microsoft.graph.agentIdentityBlueprint）创建蓝图，并记录 appId。
4. 配置凭据：将具有托管标识的联合标识凭据（用于生产）或客户端密码（用于本地开发/测试）添加到蓝图。
5. 配置标识符 URI 和范围：设置为identifierUrisapi://{appId}并创建用于代理到代理和用户到代理通信的 OAuth2 权限范围。
6. 创建蓝图主体：使用类型化终结点为蓝图创建服务主体（ 主体不是 自动创建且必须显式完成）。
7. 创建代理标识：在蓝图下创建一个或多个代理标识服务主体。

当代理读取技能时，系统可能会提示你安装扩展或其他工具。 按照提示操作，确保环境准备就绪。

步骤4：回应提示

AI代理会在特定时刻暂停，收集你的输入：

• 显示名称：这个是您的代理身份蓝图的显示名称（例如，“Contoso预算代理”）。
• 发起人：负责代理的用户或组。 默认为当前登录用户。
• 所有者：可以对蓝图进行技术更改的用户或服务主体。 可选但建议使用。
• 凭据类型：是使用托管标识（建议用于生产），还是使用证书或客户端密码（用于本地开发）。
• 代理标识计数：在此蓝图下创建的代理标识数。
• 派生值确认：在创建资源之前查看自动生成的名称和 URI。

步骤 5：在 Microsoft Entra 管理中心进行验证

安装完成后，AI 代理提供有关如何验证资源的说明：

1. 作为至少 Agent ID Developer 的身份登录到 Microsoft Entra 管理中心。
2. 浏览到 Entra ID>Agents>代理身份，以查看新的代理身份蓝图及其下创建的任何代理身份。
3. 验证蓝图是否配置了正确的凭据、标识符 URI 和范围。

AI引导设置涵盖的内容

AI 引导式设置自动执行代理 ID 集成的以下步骤：

AI 引导的设置过程中的常见陷阱

代理 ID API 接口具有由 AI 引导的安装设置自动检测和解析的几个要求，但这些要求并不明显。 如果需要调试问题或扩展设置，了解这些陷阱会很有帮助。

OData-Version 标头是必需的

所有代理 ID API 调用都需要 OData-Version: 4.0 标头。 如果省略此标头，API 可能会以无提示方式创建标准应用程序，而不是代理标识蓝图。 AI 引导式设置始终包含此标头。 该技能还使用类型化端点（例如 /applications/microsoft.graph.agentIdentityBlueprint），而不是使用带有 /applications 属性的原始 @odata.type，以降低出现此问题的风险。

蓝图主体不会自动创建

创建代理标识蓝图 （POST /applications） 不会 自动创建其蓝图主体（服务主体）。 如果没有主要蓝图，所有后续代理标识创建都会失败，具体原因如下：

400: The Agent Blueprint Principal for the Agent Blueprint does not exist.

AI 引导式设置始终在蓝图完成后立即创建蓝图主体。 它还处理幂等情况（即多次执行操作也不会改变结果的情况）。 如果以前的运行创建了蓝图，但在创建主体之前崩溃，安装程序将检测此事件并创建缺少的主体。

赞助商是必需的

发起人为必需项，可以是用户、动态成员身份组或者统一组。 创建蓝图和代理标识都需要一个 sponsors@odata.bind 字段。 如果没有它，你会收到：

400: No sponsor specified. Please provide at least one sponsor.

AI 引导式设置仅接受 用户 对象进行赞助分配，并且仅使用 /users/{objectId} URL 格式（不使用 /directoryObjects/ 或 /servicePrincipals/）。 安装程序解析当前用户的对象 ID，并将其用作默认发起人。 若要将受支持的组分配为蓝图的发起人，请直接使用 Microsoft 图形 API。

权限传播可能需要 30 到 120 秒以上

授予代理 ID 权限的管理员同意后，新授予的权限不会立即显示在令牌中。 令牌终结点提供缓存声明，传播可能需要 30-120 秒或更多时间。

AI驱动的设置通过在收到403错误时重试操作，并采用指数退避策略来处理最近更改的权限。 如果要手动编写脚本，请实现重试逻辑：

# Example: Retry with backoff after admin consent
$maxRetries = 5
for ($i = 0; $i -lt $maxRetries; $i++) {
    try {
        # Attempt the operation
        $result = Invoke-MgGraphRequest -Method POST -Uri $uri -Body $body
        break
    } catch {
        if ($_.Exception.Response.StatusCode -eq 403 -and $i -lt $maxRetries - 1) {
            $wait = 20 * ($i + 1)
            Write-Host "Permission not yet propagated. Retrying in $wait seconds..."
            Start-Sleep -Seconds $wait
            # Disconnect and reconnect to force a fresh token
            Disconnect-MgGraph
            Connect-MgGraph -Environment China -ClientId 'YOUR_CLIENT_ID' -TenantId 'YOUR_TENANT_ID' -Scopes $scopes
        } else {
            throw
        }
    }
}

代理标识不能具有密码凭据

代理标识是服务主体，无需支持应用程序对象。 尝试将 passwordCredential 直接添加到代理标识会导致：

PropertyNotCompatibleWithAgentIdentity

必须在 蓝图上配置凭据，而不是在单个代理标识上配置凭据。 使用托管身份联合（推荐）或将密钥/证书添加到蓝图中，代理身份通过模拟继承这些凭据。

必须显式设置标识符 URI

默认情况下，蓝图的 identifierUris 字段未设置。 如果没有它，OAuth2 范围 api://{appId}/.default 将无法解析，代理的令牌获取将失败。 AI 引导式设置始终将此值配置为作用域设置步骤的一部分。

蓝图的联合标识凭据路径

为托管标识联合添加联合标识凭据 (FIC) 时，您必须使用特定于代理的 API 路径：

POST /applications/{blueprint-obj-id}/microsoft.graph.agentIdentityBlueprint/federatedIdentityCredentials

使用/applications/{id}/federatedIdentityCredentials路径可能适用于代理标识蓝图，但这种做法不受支持，且不建议使用。

令牌颁发者因端点版本而异

在您的代理后端验证令牌时，请注意以下变化：

• 使用颁发者 https://sts.chinacloudapi.cn/{tenant-id}/ 的 v1.0 令牌
• v2.0 令牌使用颁发者 https://login.partner.microsoftonline.cn/{tenant-id}/v2.0

在令牌验证逻辑中接受这两种格式。

Troubleshooting

AI 代理不运行终端命令

如果 AI 代理描述命令但未执行命令，请确保在 GitHub Copilot 对话助手 中使用 代理模式 。 询问和编辑模式没有终端访问。

AI 代理跳过验证步骤

指令文件强制执行严格的步序顺序。 如果AI代理似乎跳过了某个步骤，提醒它从头开始就遵循指令。 例如：

Please start from Step 1 in the setup instructions and work through each step in order.

Graph 命令失败，出现 403-Forbidden

最常见的 403 错误原因：

• 使用 Azure CLI 或 DefaultAzureCredential 令牌：Azure CLI 令牌包含 Directory.AccessAsUser.All，而 Agent Identity API 会直接拒绝此类令牌。 使用具有明确委托范围的 Connect-MgGraph，或使用带有 client_credentials 的专用应用注册。 请参阅先决条件中的 身份验证警告 。
• 权限传播延迟：在管理员同意后等待 1-2 分钟，然后重试。 AI 引导式设置使用重试逻辑自动处理此问题。
• 缺少管理员许可：请验证在 Microsoft Entra 管理中心 的 应用注册 下，所需权限是否已授予管理员许可，以及检查您的客户端应用的>。

蓝图创建成功，但生成的是标准应用程序

当缺少 OData-Version: 4.0 标头时，就会出现这种结果。 使用类型化终结点 （/applications/microsoft.graph.agentIdentityBlueprint） 而不是原始 /applications 终结点 @odata.type 以避免此问题。

代理标识创建失败，出现“蓝图主体不存在”

蓝图主项必须在蓝图之后作为单独的步骤来创建。 运行：

POST https://microsoftgraph.chinacloudapi.cn/v1.0/servicePrincipals/microsoft.graph.agentIdentityBlueprintPrincipal
OData-Version: 4.0
Content-Type: application/json

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

凭据有效期策略错误

租户可能具有凭据生命周期策略，用于限制客户端机密的最长有效期。 如果在添加密码时收到有关凭据生存期的错误，请减少 endDateTime 值以符合组织的策略。

配置值需要更改

如果需要在设置后更改配置值，可以：

• 使用更新的值重新运行 AI 引导式设置。 幂等检查会跳过那些已经正确存在的资源。
• 使用 Microsoft Graph PowerShell 通过 PATCH 请求更新特定属性。

后续步骤

• 创建和删除代理标识
• 代理 ID 中的管理关系（所有者、赞助商和经理）
• 代理标识、服务主体和应用程序
• 代理标识蓝图概念