设置代理蓝图

重要

需要成为 Frontier 预览计划的一部分，才能获得 抢先体验Microsoft Agent 365。边界将你直接与Microsoft最新的 AI 创新联系起来。 Frontier 预览版受客户协议中现有预览条款的约束。由于这些功能仍在开发中，其可用性和功能可能会随时间而变化。

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

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

先决条件

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

Agent 365 CLI - 参见 Agent 365 CLI 安装。
所需权限：
- 具有以下角色之一的有效租户用户：
  - 全局管理员
  - 智能体 ID 管理员
  - 代理 ID 开发人员
- 访问具有创建资源权限的 Azure 订阅
工作目录中的有效 a365.config.json 文件，通过以下步骤设置：设置Agent 365配置。

创建代理蓝图

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

运行安装程序

执行设置命令：

a365 setup -h

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

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

创建Azure基础结构（如果尚不存在）：
- 资源组
- 具有指定 SKU 的App 服务计划
- 启用了托管身份的 Azure Web 应用
登记代理模板：
- 在 Microsoft Entra 租户中创建代理蓝图
- 创建 Microsoft Entra 应用程序注册
- 配置代理身份，并授予所需权限
配置 API 权限：
- 设置 Microsoft Graph API 范围
- 配置消息传送机器人 API 权限
- 对代理实例应用可继承的权限
更新配置文件
- 将生成的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、代理 365 工具、消息机器人 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。

验证设置

设置完成后，你会看到一个总结，显示所有已完成的步骤。验证已创建的资源：

验证生成配置：

a365 config display -g

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

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

需要验证的关键字段：

字段	目的	需要注意的事项
`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 权限授予。

验证 Azure 资源在 Azure Portal 中：

或者用 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 Apps
  - 找到 Web 应用，然后转到设置>标识>系统分配
  - 验证状态是否为 “打开”
  - 请注意对象（主体）ID 与 managedIdentityPrincipalId 匹配。
在Azure Portal中验证 Microsoft Entra 应用程序：

转到 Azure Active Directory>App registrations>All applications：
- 通过 agentBlueprintId 搜索您的智能体蓝图
- 选择应用程序，并选择“API 权限”。
- 验证权限是否授予，查看是否有绿色勾选标记。
  - Microsoft Graph（委派权限和应用程序权限）
  - 消息机器人 API 权限
- 所有权限均显示 “已授予[您的租户]”
验证已创建的生成配置文件。

应有一个名为 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 文件。需要这些值以进行部署和故障排除。

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

验证在 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 config permissions 将所需的资源权限添加到您的配置中，然后运行 a365 setup permissions custom 以在 Microsoft Entra 中应用到您的蓝图。

# Add resource permissions to config
a365 config permissions `
  --resource-app-id 00000003-0000-0000-c000-000000000000 `
  --scopes Mail.Read,Mail.Send,Chat.Read,Chat.ReadWrite,Chat.Create,User.Read

# Apply permissions to your blueprint
a365 setup permissions custom

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

后续步骤

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

Troubleshooting

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

小窍门

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

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

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

权限不足错误

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

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

全局管理员
智能体 ID 管理员
代理 ID 开发人员

以及 Azure 订阅的贡献者或所有者访问权限。

解决方案： 验证在 Microsoft Entra 中是否具有所需的权限。

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

备注

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

缺少Azure CLI身份验证

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

解决方案： 确保已连接到 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 资源，然后使用命令重新运行安装程序。

警告

运行 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)
a365 config display -g

配置文件缺失或无效

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

Solution:

确认 a365.config.json 文件存在。
使用 a365 配置显示命令显示当前配置。
如果缺少或无效，请使用 a365 config init 命令重新初始化。

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

# Display current configuration
a365 config display

# If missing or invalid, re-initialize
a365 config init

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

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

Solution:

使用命令a365 config display -g检查已创建的资源。
使用 az resource list 命令验证是否存在Azure资源。
如果缺少资源，请检查安装输出中的错误，并使用 a365 setup all 命令重新运行安装程序。

# Check created resources
a365 config display -g

# 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:

请使用 a365 config display -g 命令从生成的配置中获取蓝图 ID。
```
a365 config display -g
# Look for: agentBlueprintId
```
在Microsoft Entra管理中心中进行搜索：
1. 转到：Microsoft Entra管理中心。
2. 导航到 “应用注册>所有应用程序”。
3. 搜索你的 agentBlueprintId.
如果未找到，请使用 a365 setup all 命令重新运行安装程序。
```
a365 setup all
```

未授予API权限

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

Solution:

打开Microsoft Entra 管理中心。
查找代理蓝图应用程序注册。
转到 API 权限。
授予管理员同意：
1. 选择 授予[您的租户]的管理员同意。
2. 确认该操作。
验证所有权限是否显示绿色对勾符号。

未启用托管身份

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

Solution:

使用 az webapp identity show 命令检查托管标识状态。
如果未启用，请使用 az webapp identity assign 命令手动启用它。
使用 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:

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

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

# Check generated config
a365 config display -g

# Check Azure resources
az resource list --resource-group <your-resource-group>

清理并重试。
```
a365 cleanup
a365 setup all
```

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

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

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

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

反馈

此页面是否有帮助？

Last updated on 2026-03-25

通过

设置代理蓝图

先决条件

创建代理蓝图

运行安装程序

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

验证设置

代理权限

为蓝图应用权限

后续步骤

Troubleshooting

权限不足错误

缺少Azure CLI身份验证

资源已经存在了

管理员同意未完成

配置文件缺失或无效

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

代理蓝图未在 Microsoft Entra 中注册

未授予API权限

未启用托管身份

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

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

反馈

其他资源