设置代理蓝图

重要提示

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

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

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

先决条件

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

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

创建代理蓝图

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

运行安装程序

执行设置命令：

a365 setup -h

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

整个建立过程执行以下作：

创建 Azure 基础结构（如果尚不存在）：
- 资源组
- 具有指定 SKU 的App 服务计划
- 已启用托管标识的 Azure Web 应用
注册代理蓝图：
- 在 Microsoft Entra 租户中创建代理蓝图
- 创建 Microsoft Entra 应用程序注册
- 配置具有所需权限的代理标识
配置 API 权限：
- 设置Microsoft图形 API 范围
- 配置消息传送机器人 API 权限
- 对代理实例应用可继承的权限
更新配置文件
- 将生成的ID和端点保存到你工作目录中一个名为 a365.generated.config.json
- 记录托管标识和资源信息

备注

在设置过程中，该命令会打开浏览器窗口以获取管理员同意。完成这些同意流以继续。安装程序通常需要 3-5 分钟才能自动保存配置。a365.generated.config.json

验证设置

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

验证生成配置：

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",
"botMessagingEndpoint": "https://your-app.azurewebsites.net/api/messages",
"resourceConsents": [],
"completed": true,
"completedAt": "xxxx-xx-xxTxx:xx:xxZ",
"cliVersion": "x.x.xx"
}

需要验证的关键字段：

领域	目的	需要注意的事项
`managedIdentityPrincipalId`	Azure managed identity authentication	应该是有效的 GUID
`agentBlueprintId`	您的代理人的唯一标识符	用于开发者门户和管理中心
`agentBlueprintObjectId`	Blueprint的Microsoft Entra ID
`botMessagingEndpoint`	消息路由	Teams/Outlook向你的客服发送消息的地方
`agentBlueprintClientSecret`	认证秘密	应该存在（值被掩蔽）
`resourceConsents`	API 权限	应包含 Microsoft Graph、Agent 365 工具、消息机器人 API、可观测性 API 等资源
`completed`	设置状态	应该是 `true`

Verify Azure Portal 中的 Azure 资源：

或者用 az resource list PowerShell命令。
```
# List all resources in your resource group
az resource list --resource-group <your-resource-group> --output table
```
请核实以下资源的创建：
- 资源组。
  - 前往 资源组> 选择你的资源组
  - 验证它是否包含App 服务计划和 Web 应用
- 应用服务计划
  - 转到>
  - 查找计划并验证定价层是否与配置 SKU 匹配
- Web 应用
  - 转到App 服务>Web 应用
  - 找到 Web 应用，然后转到“设置>标识>系统分配”
  - 验证状态是否为 “打开”
  - 请注意对象（主体）ID 匹配项 managedIdentityPrincipalId
在 Azure 门户中验证Microsoft Entra 应用程序：

选择“Azure Active Directory”“应用注册”>“所有应用程序” 。
- 按以下方式搜索代理蓝图 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 文件。部署和排查需要这些值。

Verify Web App 启用了托管身份：

使用命令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"
}

验证在Entra注册的代理蓝图：

在 Microsoft Entra 管理中心，搜索你的 agentBlueprintId 或按姓名搜索。

验证：

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

如需更多帮助，请参见：

配置问题
自定义客户端应用问题

后续步骤

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

Troubleshooting

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

小窍门

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

这些问题有时会出现在注册过程中：

权限不足错误
缺少 Azure CLI 认证
资源已经存在了
管理员同意未完成
配置文件缺失或无效
设置完成了，但资源没有生成
代理人蓝图未在Entra注册
未授予API权限
未启用托管身份
设置太慢或者卡住

权限不足错误

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

你需要在 Microsoft Entra 租户中扮演以下角色之一：

全局管理员
代理 ID 管理员
代理 ID 开发人员

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

解决方案： 确认你在Entra中有所需的权限。

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

缺少 Azure CLI 认证

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

解决方案： 确保你已经连接了Azure，并验证你的账户和订阅。

# Authenticate with Azure
az login

# Verify correct account and subscription
az account show

资源已经存在了

症状： 设置失败时，资源 Resource already exists 组、应用服务计划或网页应用都会出现错误。

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

利用现有资源

如果资源存在且你想使用它们，确保它们与你的配置相匹配。使用 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>
```
使用清理命令重新开始

使用cleanup命令移除所有 Agent 365 资源，然后重新a365 setup all运行安装。

警告

跑步 a365 cleanup 是破坏性的
```
a365 cleanup
a365 setup all
```

症状： 浏览器窗口在设置时打开，但你关闭时没有完成同意。

解决方案：执行命令a365 setup all。 CLI会重新提示管理员同意：

完成浏览器窗口中出现的所有同意流程。

配置文件缺失或无效

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

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

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

症状： 设置命令成功了，但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

代理人蓝图未在Entra注册

症状： 设置已完成，但在 Microsoft Entra 管理中心找不到代理蓝图。

Solution:

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

未授予API权限

症状： 设置已完成，但在 Entra 中权限显示为“未授予”。

Solution:

打开 Microsoft Entra 管理中心
查找您的代理人Blueprint应用注册
转到 API 权限
授予管理员同意：
1. 选择 授予[您的租户]的管理员同意
2. 确认行动
验证所有权限，显示绿色勾选

未启用托管身份

症状： 网页应用存在，但没有启用托管身份。

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
```

反馈

此页面是否有帮助？

Last updated on 2026-01-30

通过

设置代理蓝图

先决条件

创建代理蓝图

运行安装程序

验证设置

后续步骤

Troubleshooting

权限不足错误

缺少 Azure CLI 认证

资源已经存在了

管理员同意未完成

配置文件缺失或无效

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

代理人蓝图未在Entra注册

未授予API权限

未启用托管身份

设置太慢或者卡住

反馈

其他资源