设置智能体蓝图

智能体蓝图定义智能体的标识、权限和基础结构要求。根据此智能体蓝图创建每个智能体实例。

备注

若要启用注册表、Work IQ 和 AI 队友功能，需要先设置智能体蓝图。请参阅 Agent 365 开发入门，了解哪些功能适用于您的智能体。

有关 Agent 365 标识的详细信息，请参阅 Agent 365 标识。

必备条件

开始之前，请确保具备以下先决条件：

Agent 365 CLI - 请参阅 Agent 365 CLI 安装。
所需的权限：
- 具有以下角色之一的有效租户用户：
  - 全局管理员
  - 智能体 ID 开发人员
- 访问具有创建资源权限的 Azure 订阅
提示

智能体（非 AI 队友）无需配置文件。使用 a365 setup all --agent-name <name>，CLI 会自动解析您的租户和客户端应用。 AI 队友设置需要手动创建 a365.config.json。

创建智能体蓝图

使用 a365 setup 命令创建 Azure 资源并注册您的智能体蓝图。蓝图定义智能体的标识、权限和基础结构要求。此步骤为在 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

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

创建 Azure 基础结构（如果尚不存在）：
- 资源组
- 带有指定 SKU 的应用服务计划
- 启用了托管身份的 Azure Web 应用
注册智能体蓝图：
- 在 Microsoft Entra 租户中创建智能体蓝图
- 创建 Microsoft Entra 应用程序注册
- 配置智能体标识及所需权限
- 在蓝图上设置 managerApplications，这是平台可管理性所必需的
重要提示

蓝图必须设置 managerApplications，才能被平台接受。 CLI 会自动进行此设置。如果您有在引入此要求之前创建的现有蓝图，请将其删除并再次运行 a365 setup all，或通过图形 API 手动修补。
配置 API 权限：
- 设置 Microsoft 图形 API 范围
- 配置消息机器人 API 权限
- 为智能体实例应用可继承权限
更新配置文件：
- 将生成的 ID 和终结点保存到工作目录中名为 a365.generated.config.json 的新文件中
- 记录托管身份和资源信息

备注

设置通常需要 3-5 分钟，配置会自动保存到 a365.generated.config.json。如果您以全局管理员身份运行，CLI 可能会打开浏览器窗口以请求管理员同意 - 完成同意流即可继续。如果您以智能体 ID 开发人员身份运行，不会显示浏览器窗口；CLI 会生成同意 URL 以供全局管理员稍后完成。

使用智能体 ID 开发人员进行安装

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

哪些步骤会自动完成：

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

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

Microsoft Graph、Agent 365 Tools、Messaging Bot API、Observability API 和 Power Platform API 的 OAuth2 委托权限授予（AllPrincipals 同意）

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

步骤	用户	变动
1	开发人员	运行 `a365 setup all`。 CLI 完成可完成的所有步骤，并打印后续步骤，包括可供全局管理员打开的同意 URL。
2	开发人员	与您的全局管理员共享 CLI 输出中的同意 URL。
3	全局管理员	在以全局管理员登录的浏览器中打开同意 URL，并授予所请求的权限。

运行命令：

# Developer runs:
a365 setup all
# Setup completes all steps it can. The CLI prints the next steps
# for a Global Administrator directly in the output, including a
# direct link or consent URL they can open to complete the grants.

与您的全局管理员共享 CLI 打印的后续步骤。他们可以打开提供的链接或同意 URL，以完成 OAuth2 权限授予。

验证设置

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

验证生成的配置：

在您的工作目录中打开 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"
}

要验证的关键字段：

字段	用途	检查项
`managedIdentityPrincipalId`	Azure 托管身份验证	应为有效的 GUID
`agentBlueprintId`	智能体的唯一标识符	在开发人员门户和管理中心中使用
`agentBlueprintObjectId`	蓝图的 Microsoft Entra ID
`messagingEndpoint`	消息路由	Teams/Outlook 向您的智能体发送消息的地址
`agentBlueprintClientSecret`	身份验证密码	应该存在（值已进行掩码）
`resourceConsents`	API 权限	应包含 Microsoft Graph、Agent 365 工具、消息机器人 API、可观测性 API 等资源
`completed`	设置状态	应该是 `true`

备注

如果您以智能体 ID 管理员或智能体 ID 开发人员身份运行了设置，resourceConsents 可能为空，completed 可能为 false，直到全局管理员使用 CLI 打印的后续步骤完成 OAuth2 权限授予。

在 Azure 门户中验证 Azure 资源：

或使用 az resource list PowerShell 命令。
```
# List all resources in your resource group
az resource list --resource-group <your-resource-group> --output table
```
验证是否创建了以下资源：
- 资源组：
  - 转到资源组>并选择您的资源组
  - 验证它包含您的应用服务计划和 Web 应用
- 应用服务计划：
  - 转到应用服务>应用服务计划
  - 找到您的服务计划，并验证定价层是否与您的配置 SKU 匹配
- Web 应用：
  - 转到应用服务>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 文件。在进行部署和故障排除时需要这些值。

验证 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 Graph API 在 Microsoft 365 和 Microsoft Entra ID 中可以访问哪些数据和操作的授权模型。

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

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

若要理解并验证 Graph 权限如何向您的智能体赋能，您可以：

查看可用的所有 Graph 权限。
访问 Graph 浏览器，以尝试查询、检查回复并了解权限。
在部署前，使用 Microsoft 365 智能体操场在本地测试您的智能体。

将权限应用到您的蓝图

使用 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

Amazon Web Services (AWS)

Google Cloud Platform (GCP)

将智能体发布到 Microsoft 管理中心

故障排除

本部分介绍了设置智能体蓝图时的常见问题。

提示

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

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

权限不足错误
缺少 Azure CLI 身份验证
资源已存在
未完成管理员同意
配置文件缺失或无效
设置完成，但未创建资源
智能体蓝图未在 Microsoft Entra 中注册
API 权限未授予
托管标识未启用
设置耗时过长或无响应
清理无配置的智能体
无法在 Teams 中发送第一条消息

权限不足错误

症状：执行 a365 setup 命令期间权限不足错误。

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

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

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

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

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

备注

如果您拥有智能体 ID 管理员或智能体 ID 开发人员角色（而不是全局管理员），a365 setup all 仍可成功，但会跳过 OAuth2 权限授予。完成设置后，CLI 会打印后续步骤，以供全局管理员完成剩余的授予。此工作流适用于智能体开发人员与全局管理员由不同人员担任的组织。

缺少 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>
```
使用清理命令重新开始

使用 cleanup 命令删除所有 Agent 365 资源，然后使用 a365 setup all 命令重新运行设置。

警告

运行 a365 cleanup 具有破坏性。
```
a365 cleanup
a365 setup all
```

症状：您在设置过程中打开了浏览器窗口，但在未完成同意的情况下将其关闭，或者设置已完成但 OAuth2 权限授予仍处于待处理状态。

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

全局管理员：再次运行 a365 setup all。 CLI 提示进行管理员同意。在出现的浏览器窗口中完成同意流。
智能体 ID 管理员或开发人员：您不能直接完成 OAuth2 授予。运行 a365 setup all — 安装摘要会打印全局管理员的后续步骤，其中包含完成授权的直接链接或同意 URL。与您的全局管理员共享这些详细信息。

配置文件缺失或无效

症状：设置失败，并具有“未找到配置”或验证错误。

解决方案：

验证 a365.config.json 文件是否存在。
如果缺失或无效，手动进行创建或使用 a365 setup all --agent-name <name>（仅智能体）。

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

设置完成，但未创建资源

症状：设置命令成功，但 Azure 资源不存在。

解决方案：

通过在您的工作目录中打开 a365.generated.config.json 来检查创建的资源。
使用 az resource list 命令验证 Azure 资源是否存在。
如果资源缺失，请检查设置输出中是否有错误，然后使用 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 管理中心中找不到智能体蓝图。

解决方案：

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

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

在 Microsoft Entra 管理中心中搜索：
1. 转到：Microsoft Entra 管理中心。
2. 导航到应用注册>所有应用程序。
3. 搜索您的 agentBlueprintId。
如果找不到，请使用 a365 setup all 命令重新运行设置。
```
a365 setup all
```

API 权限未授予

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

解决方案：

打开 Microsoft Entra 管理中心。
查找您的智能体蓝图应用注册。
转到 API 权限。
授权管理员同意：
1. 选择为 [您的租户] 授予管理员同意。
2. 确认操作。
验证所有权限是否都显示绿色复选标记。

托管标识未启用

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

解决方案：

通过使用 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 分钟未能完成。

解决方案：

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

如果设置完全无响应，请取消它 (Ctrl+C)，然后检查已创建的内容。

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

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

清理并重试。
```
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 结合使用，或者直接通过 Azure 门户和 Microsoft Entra 管理中心移除资源。

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

症状：在预配智能体实例后，无法向智能体管理器发送一条消息作为欢迎消息。

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

若要实施，请配置蓝图的可继承权限以包括 Chat.Create 范围。
配置 Teams 聊天消息，以在预配智能体实例后发送。
从蓝图中创建新的智能体实例，并测试首次运行消息。

反馈

此页面是否有帮助？

Last updated on 2026-07-29

设置智能体蓝图

必备条件

创建智能体蓝图

运行安装程序

使用智能体 ID 开发人员进行安装

验证设置

代理权限

将权限应用到您的蓝图

后续步骤

故障排除

权限不足错误

缺少 Azure CLI 身份验证

资源已存在

未完成管理员同意

配置文件缺失或无效

设置完成，但未创建资源

智能体蓝图未在 Microsoft Entra 中注册

API 权限未授予

托管标识未启用

设置耗时过长或无响应

清理无配置的智能体

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

反馈

其他资源