设置代理蓝图

重要

你需要成为Frontier 预览计划的一员，才能获取 Microsoft Agent 365 的提前访问权限。 Frontier将你直接连接到Microsoft最新的人工智能创新。 Frontier 预览版受客户协议中现有预览条款的约束。 由于这些功能仍在开发中，其可用性和功能可能会随时间而变化。

代理蓝图定义了代理的身份、权限和基础设施需求。 从这个代理蓝图创建每个代理实例。

有关365号代理身份的更多信息，请参见 365号代理身份。

先决条件

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

1. Agent 365 CLI - 参见 Agent 365 CLI 安装。

2. 所需权限：

   • 具有以下角色之一的有效租户用户：
     • 全局管理员
     • 代理身份管理员
     • 代理ID开发者
   • 访问具有创建资源权限的 Azure 订阅

   小窍门

   代理（而不是 AI 团队成员）不需要配置文件。 使用 a365 setup all --agent-name <name> 时，CLI 会自动解析您的租户和客户端应用。 AI 团队成员设置需要手动创建 a365.config.json。

创建代理蓝图

使用 a365 setup 命令创建Azure资源并注册 agent 蓝图。 蓝图定义代理的标识、权限和基础结构要求。 此步骤为在 Azure 中部署和运行代理奠定了基础。

运行安装程序

执行设置命令：

a365 setup -h

该命令有多种选项。 你可以通过使用 a365 setup all 或选择更细致的选项，在一个命令中完成整个设置。

注释

a365 setup all 默认为蓝图代理模式。 若要改为设置 AI 队友代理，请传递 --aiteammate。 对于 M365 客户端（Teams，Copilot），还要传递 --m365 以自动注册消息传送终结点。

代理设置（默认值）：

# With a config file
a365 setup all

# Config-free — no a365.config.json needed
a365 setup all --agent-name <your-agent-name>

M365 代理设置（Teams/Copilot）：

# Registers the messaging endpoint via MCP Platform
a365 setup all --m365

AI 团队成员设置：

a365 setup all --aiteammate

整个设置过程执行以下操作：

1. 创建Azure基础结构（如果尚不存在）：

   • 资源组
   • 具有指定 SKU 的App 服务计划
   • 启用托管身份验证的 Azure Web 应用

2. 登记代理模板：

   • 在 Microsoft Entra 租户中创建代理架构图
   • 创建 Microsoft Entra 应用程序注册
   • 配置代理身份，并授予所需权限
   • 在蓝图上设置 managerApplications ，这是平台可管理性所必需的

   重要

   蓝图必须将 managerApplications 设置为被平台接受。 CLI 会自动设置此值。 如果在引入此要求之前创建了现有蓝图，请将其删除并再次运行 a365 setup all，或通过图形 API手动修补该蓝图。

3. 配置 API 权限：

   • 设置 Microsoft 图形 API 权限范围
   • 配置消息传送机器人 API 权限
   • 对代理实例应用可继承的权限

4. 更新配置文件

   • 将生成的ID和端点保存到你的工作目录中新建的一个名为 a365.generated.config.json 的文件中
   • 记录托管身份和资源信息

注释

安装通常需要 3-5 分钟，并将配置自动保存到 a365.generated.config.json。 如果以全局管理员身份运行，CLI 可能会打开浏览器窗口进行管理员同意 - 完成同意流以继续操作。 如果以代理 ID 管理员或开发人员身份运行，则不会显示浏览器窗口;CLI 为全局管理员生成同意 URL，以便稍后完成。

使用代理 ID 管理员或代理 ID 开发人员进行设置

如果以代理 ID 管理员或代理 ID 开发人员（而不是全局管理员）身份运行， a365 setup all 则会自动完成大多数步骤，但 OAuth2 权限授予需要单独的全局管理员步骤。

哪些步骤会自动完成：

• Azure 基础结构（资源组、应用服务计划、Web 应用）
• 代理蓝图注册
• 代理实例的可继承权限

需要全局管理员执行哪些步骤：

• 针对 Microsoft Graph、Agent 365 Tools、消息传递机器人 API、可观测性 API 和 Power Platform API 的 OAuth2 委派权限授予（AllPrincipals许可）

如何使用非管理员帐户完成设置：

# Step 1: Run setup as Agent ID Admin or Developer
a365 setup all
# Setup completes all steps it can. The CLI displays next steps
# showing how a Global Administrator can complete the OAuth2 grants.

# Step 2: Share the config folder with a Global Administrator.
# The folder contains a365.config.json and a365.generated.config.json.

# Step 3: The Global Administrator runs:
a365 setup admin --config-dir "<path-to-config-folder>"

或者，全局管理员可以打开 CLI 保存到 a365.generated.config.json （字段： combinedAdminConsentUrl）的合并同意 URL，并在单个浏览器访问中授予同意。 有关详细信息，请参阅 a365 setup admin。

验证设置

安装完成后，会看到一个摘要，其中显示了所有已完成的步骤。 验证已创建的资源：

1. 验证生成配置：

   在工作目录中打开 a365.generated.config.json 。 或者使用 PowerShell：

   Get-Content a365.generated.config.json | ConvertFrom-Json
   

   期望输出包括以下关键值：

   {
   "managedIdentityPrincipalId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
   "agentBlueprintId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
   "agentBlueprintObjectId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
   "agentBlueprintServicePrincipalObjectId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
   "agentBlueprintClientSecret": "xxx~xxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
   "agentBlueprintClientSecretProtected": true,
   "botId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
   "botMsaAppId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
   "messagingEndpoint": "https://your-app.azurewebsites.net/api/messages",
   "resourceConsents": [],
   "completed": true,
   "completedAt": "xxxx-xx-xxTxx:xx:xxZ",
   "cliVersion": "x.x.xx"
   }
   

   需要验证的关键字段：

   领域	Purpose	需要注意的事项
   managedIdentityPrincipalId	Azure托管身份验证	应该是有效的 GUID
   agentBlueprintId	您的代理人的唯一标识符	用于开发者门户和管理中心
   agentBlueprintObjectId	Blueprint 的 Microsoft Entra ID
   messagingEndpoint	消息路由	Teams/Outlook 向您的智能体发送消息的地址
   agentBlueprintClientSecret	认证密钥	应该存在（值被掩蔽）
   resourceConsents	API 权限	应包含 Microsoft Graph、Microsoft 365 代理工具、消息机器人 API、可观测性 API 等资源
   completed	设置状态	应该是 true

   注释

   如果您以代理 ID 管理员或代理 ID 开发人员的身份运行安装程序，resourceConsents 可能为空，而 completed 可能为 false，直到全局管理员运行 a365 setup admin 来完成 OAuth2 权限授予。

2. 在 Azure 门户 中验证 Azure 资源：

   或者用 az resource list PowerShell命令。

   # List all resources in your resource group
   az resource list --resource-group <your-resource-group> --output table
   

   请核实以下资源的创建：

   • 资源组。

     • 前往 资源组> 选择你的资源组
     • 验证它是否包含App 服务计划和 Web 应用

   • 应用服务计划

     • 转到App Services>App Service Plans
     • 查找计划并验证定价层是否与配置 SKU 匹配

   • Web 应用

     • 转到 App Services>Web 应用
     • 找到 Web 应用，然后转到设置>标识>系统分配
     • 验证状态是否为 “打开”
     • 请注意对象（主体）ID 与 managedIdentityPrincipalId 匹配。

3. 在Azure 门户中验证 Microsoft Entra 应用程序：

   转到 Azure Active Directory>应用注册>All applications：

   • 请通过以下方式搜索代理蓝图 agentBlueprintId

   • 选择应用程序，并选择“API 权限”。

   • 验证权限是否授予，查看是否有绿色勾选标记。

     • Microsoft Graph（委派权限和应用程序权限）
     • 消息机器人 API 权限

   • 所有权限均显示 “已授予[您的租户]”

4. 验证已创建的生成配置文件。

   应有一个名为 a365.generated.config.json 包含所有配置数据的文件。

   使用 Test-Path PowerShell 命令检查是否存在。

   # Check file exists
   Test-Path a365.generated.config.json
   # Should return: True
   

   重要

   保存两个 a365.config.json 和 a365.generated.config.json 文件。 需要这些值以进行部署和故障排除。

5. 验证 Web 应用程序是否启用了托管身份：

   使用命令az webapp identity show检查是否启用了托管身份。

   az webapp identity show --name <your-web-app> --resource-group <your-resource-group>
   

   预期：

   {
   "principalId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
   "tenantId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
   "type": "SystemAssigned"
   }
   

6. 验证 Microsoft Entra 中注册的代理蓝图：

   在 Microsoft Entra 管理中心 中，搜索您的 agentBlueprintId 或按名称进行搜索。

   验证：

   ✅ 应用程序注册和企业应用程序显示
   ✅ 在应用注册蓝图中， API权限 标签显示所有权限
   ✅ 状态显示“已为[您的租户]授予”

如需更多帮助，请参见：

• 自定义客户端应用问题

代理权限

在应用程序和服务代理能够读取或写入Microsoft 365数据（用户、邮件、文件、Teams、服务代理等）之前，您必须显式授予它们Microsoft Graph权限。 Microsoft Graph 权限是授权模型，用于控制应用或服务可以通过跨 Microsoft 365 和 Microsoft Entra ID Microsoft Graph API 访问哪些数据和操作。

了解详细信息： Microsoft Graph 权限概述

若要对代理 365 代理实例使用 Graph 权限，开发人员必须在代理蓝图中声明它们。 当管理员在 Microsoft 365 管理中心激活蓝图时，门户会审查蓝图的 Graph 权限，并提示管理员同意这些权限。

若要了解和验证 Graph 权限如何启用代理，可以：

• 查看所有可用的 Graph 权限 。
• 访问 Graph 资源管理器 以尝试查询、检查响应和了解权限。
• 使用 Microsoft 365 Agents Playground 在部署之前在本地测试代理。

为蓝图应用权限

使用 a365 setup permissions custom 将自定义 API 权限内联应用于Microsoft Entra中的蓝图。

a365 setup permissions custom `
  --resource-app-id 00000003-0000-0000-c000-000000000000 `
  --scopes Mail.Read,Mail.Send,Chat.Read,Chat.ReadWrite,Chat.Create,User.Read

有关配置和删除自定义权限的完整详细信息，请参阅 setup permissions custom。

后续步骤

将您的代理代码部署到云端：

Azure

亚马逊网络服务（AWS）

谷歌云平台（GCP）

将代理发布到Microsoft管理中心

故障排除

本节描述了设置代理蓝图时的常见问题。

小窍门

Agent 365 故障排除指南 包含高层次的故障排除建议、最佳实践以及针对 Agent 365 开发生命周期各阶段的故障排除内容链接。

注册期间有时会发生这些问题：

• 权限不足错误
• 缺少 Azure CLI身份验证
• 资源已经存在了
• 管理员授权未完成
• 配置文件缺失或无效
• 设置完成了，但资源没有生成
• 代理设计蓝图未在 Microsoft Entra 中注册
• 未授予API权限
• 未启用托管身份
• 安装程序花费的时间过长或停止响应
• 清理无配置代理
• 无法在 Teams 中发送第一条消息

权限不足错误

症状：命令执行过程中a365 setup权限不足错误。

您需要在 Microsoft Entra 租户中具备以下角色之一：

• 全局管理员
• 代理身份管理员
• 代理ID开发者

Azure订阅参与者或所有者访问权限。

Solution：验证你在Microsoft Entra中是否具有所需的权限。

• 转到：Microsoft Entra 管理中心>您的个人资料>分配的角色
• 使用 az account show PowerShell 命令检查 Azure 订阅访问权限

注释

如果你有代理 ID 管理员或代理 ID 开发人员角色（而不是全局管理员）， a365 setup all 仍会成功，但会跳过 OAuth2 权限授予。 安装完成后，全局管理员必须运行 a365 setup admin 才能完成剩余的授权。 这种工作流适用于代理开发人员和全局管理员为不同人员的组织。

缺少Azure CLI身份验证

症状： 设置失败，伴随着认证错误。

Solution：请确保已连接到Azure并验证帐户和订阅。

# Authenticate with Azure
az login

# Verify correct account and subscription
az account show

资源已经存在了

症状： 安装失败，资源组 Resource already exists 、应用服务计划或 Web 应用出错。

解决 方案： 选择以下解决方案之一。

• 利用现有资源

  如果资源存在且你想使用它们，确保它们与你的配置相匹配。 使用 az resource list PowerShell命令。

  az resource list --resource-group <your-resource-group>
  

• 删除冲突资源

  删除资源组或重命名资源 a365.config.json ，然后重新运行安装程序。

  az group delete使用 PowerShell 命令删除资源组。

  # WARNING: This command deletes all resources in it
  az group delete --name <your-resource-group>
  

• 使用清理命令重新开始

  使用命令删除所有 Agent 365 资源，然后使用命令重新运行安装程序。

  Warning

  运行 a365 cleanup 具有破坏性。

  a365 cleanup
  a365 setup all
  

管理员同意未完成

症状： 在设置过程中打开浏览器窗口，但未完成同意便将其关闭，或设置已完成但 OAuth2 权限授予仍然挂起。

解决 方案： 根据角色选择：

• 全局管理员：再次运行 a365 setup all 。 CLI 会请求管理员同意。 在出现的浏览器窗口中完成同意流程。

• 代理 ID 管理员或开发人员：无法直接完成 OAuth2 授权。 使用移交工作流：

  # Option 1: Global Admin runs setup admin
  a365 setup admin --config-dir "<path-to-config-folder>"
  
  # Option 2: Global Admin opens the combined consent URL
  # Find the URL in a365.generated.config.json (combinedAdminConsentUrl field)
  Get-Content a365.generated.config.json | ConvertFrom-Json | Select-Object combinedAdminConsentUrl
  

配置文件缺失或无效

症状： 设置失败时出现“未找到配置”或验证错误。

Solution:

1. 确认 a365.config.json 文件存在。
2. 如果缺失或无效，请手动创建该项目，或者仅限代理使用 a365 setup all --agent-name <name>。

# Verify a365.config.json exists
Test-Path a365.config.json

设置完成了，但资源没有生成

Symptom： 安装程序命令成功，但Azure资源不存在。

Solution:

1. 通过在工作目录中打开 a365.generated.config.json 来检查已创建的资源。
2. 使用 az resource list 命令验证Azure资源是否存在。
3. 如果缺少资源，请检查安装输出中的错误，并使用 a365 setup all 命令重新运行安装程序。

# Check created resources
Get-Content a365.generated.config.json | ConvertFrom-Json

# Verify Azure resources exist
az resource list --resource-group <your-resource-group> --output table

# If resources missing, check for errors in setup output and re-run
a365 setup all

代理蓝图未在 Microsoft Entra 中注册

症状： 安装程序已完成，但无法在 Microsoft Entra 管理中心中找到代理蓝图。

Solution:

1. 从 a365.generated.config.json中获取蓝图 ID。

   Get-Content a365.generated.config.json | ConvertFrom-Json | Select-Object agentBlueprintId
   

2. 在Microsoft Entra管理中心中进行搜索：

   1. 转到：Microsoft Entra 管理中心。
   2. 导航到 “应用注册>所有应用程序”。
   3. 搜索你的 agentBlueprintId.

3. 如果未找到，请使用 a365 setup all 命令重新运行安装程序。

   a365 setup all
   

未授予API权限

症状： 安装程序完成，但权限在 Microsoft Entra 中显示为“未授予”。

Solution:

1. 打开Microsoft Entra 管理中心。

2. 查找您的智能体蓝图应用注册。

3. 转到 API 权限。

4. 授予管理员同意：

   1. 选择 授予[您的租户]的管理员同意。
   2. 确认该操作。

5. 验证所有权限是否显示绿色对勾符号。

未启用托管身份

症状： Web 应用存在，但未启用托管标识。

Solution:

1. 使用 az webapp identity show 命令检查托管标识状态。
2. 如果未启用，请使用 az webapp identity assign 命令手动启用它。
3. 使用 az webapp identity show 命令验证是否已启用。

# Check managed identity status
az webapp identity show --name <your-web-app> --resource-group <your-resource-group>

# If not enabled, enable it manually
az webapp identity assign --name <your-web-app> --resource-group <your-resource-group>

# Verify it's enabled
az webapp identity show --name <your-web-app> --resource-group <your-resource-group>

安装程序花费的时间过长或停止响应

症状： 设置命令运行超过10分钟都没完成。

Solution:

1. 如果以全局管理员身份运行，请检查浏览器窗口是否正在等待管理员同意。 完成同意流以取消阻止设置。

2. 如果设置真正停止响应，请取消它（Ctrl+C），并检查已创建的内容。

   # Check generated config
   Get-Content a365.generated.config.json | ConvertFrom-Json
   
   # Check Azure resources
   az resource list --resource-group <your-resource-group>
   

3. 清理并重试。

   a365 cleanup
   a365 setup all
   

清理无配置的代理

症状： 你预配 a365 setup all --agent-name <name> 了一个代理，现在想要将其删除，但你没有文件 a365.config.json 。

解决方案：使用a365 cleanup --agent-name来删除代理，而不需要配置文件。 命令行界面 (CLI) 从启动设置期间写入的全局生成的配置文件中读取资源 ID。

a365 cleanup --agent-name <your-agent-name>

小窍门

如果命令在身份验证时停止，它会自动回退到设备代码流。 按照终端中打印的说明完成登录。

如果您不再具有全局生成的配置（例如，在重新安装 CLI 后），可以使用手动创建的最小配置与a365 cleanup一起使用，或者直接通过a365.config.json和Microsoft Entra 管理中心删除资源。

无法在 Teams 中发送第一条消息

症状： 预配代理实例后，无法将消息作为欢迎消息发送到代理管理器。

解决 方案： 创建新聊天对象需要 [Chat.Create][perm-chatcreate] 权限。 如果一对一聊天已存在，此作将返回现有聊天，并且不会创建新的聊天。

• 若要实现， 请将蓝图的可继承权限 配置为包含范围 Chat.Create 。
• 配置 Teams 聊天消息，以在预配代理实例后发送。
• 从蓝图创建新的代理实例并测试首次运行消息。