代理 365 CLI `setup` 命令参考

设置代理 365 环境，并精细控制每个步骤。此命令管理代理 365 蓝图的初始设置工作流。

需要 Minimum 角色：Azure参与者 + Agent ID Developer

Note

你持有的角色决定了在单个运行中完成的设置量。全局管理员可以一次性完成所有步骤。代理ID管理员和代理ID开发者可以完成除OAuth2权限授权（管理员同意）外的所有步骤，后者需要全局管理员操作。设置完成后，CLI会直接在输出中打印全局管理员的下一步步骤。

Syntax

a365 setup [command] [options]

选项

Option	Description
`-?`、`-h`、`--help`	显示帮助和使用情况信息。

建议的执行顺序

# 0. Check prerequisites (optional)
a365 setup requirements

# 1. Create blueprint
a365 setup blueprint

# 2. Configure MCP permissions
a365 setup permissions mcp

# 3. Configure bot permissions
a365 setup permissions bot

# 4. Configure CopilotStudio permissions (if needed)
a365 setup permissions copilotstudio

# 5. Configure custom permissions (if needed)
a365 setup permissions custom

或者一次性运行所有步骤：

# Full setup using config file (a365.config.json)
a365 setup all

# Config-free: no a365.config.json needed
a365 setup all --agent-name "MyAgent"

如果以代理 ID 管理员或代理 ID 开发人员（而不是全局管理员）身份运行， a365 setup all 则完成除 OAuth2 权限授予之外的所有步骤。完成后，输出会包含全球管理员完成资助的下一步步骤——包括可打开的直接链接或同意网址。

`setup requirements`

验证代理 365 设置的先决条件。运行模块化要求检查，并为找到的任何问题提供指导。

a365 setup requirements [options]

此命令运行以下步骤：

检查代理 365 安装所需的所有先决条件。
报告有关详细解决指南的任何问题。
继续检查所有要求，即使某些检查失败。
提供末尾所有检查的摘要。

Tip

如果你是全局管理员，且租户中找不到那个知名 Agent 365 CLI 的客户端应用， setup requirements 它会提示你自动创建它。只需输入现有的应用ID或类型 C 即可创建应用，并一键授权管理员权限——无需手动Entra注册。

`requirements` 选项

Option	Description
`-v`、`--verbose`	启用详细日志记录。
`--category <category>`	只针对特定类别进行检查，如`Azure`、`Authentication`、`PowerShell`或`Tenant Enrollment`。
`-?`、`-h`、`--help`	显示帮助和使用情况信息。

Note

setup requirements 不需要配置文件——可以在任意目录里运行。

`setup blueprint`

创建代理蓝图（Entra ID应用程序注册）。

最低所需权限：代理 ID 开发人员角色

a365 setup blueprint [options]

`blueprint` 选项

Option	Description
`-n`、`--agent-name <name>`	特工基地名称。提供这个选项后，你就不需要配置文件了。该命令自动检测来自 `az account show`的租户 ID 。覆盖 `--tenant-id`。
`--tenant-id <tenantId>`	Azure AD 租户 ID。 Overrides auto-detection. 与 `--agent-name` 结合使用。
`-v`、`--verbose`	显示详细的输出。
`--dry-run`	显示命令在未执行的情况下执行的作。
`--skip-requirements`	跳过要求验证检查。请谨慎使用。
`--no-endpoint`	不要注册消息传送终结点（仅蓝图）。
`--endpoint-only`	仅注册消息传送终结点。需要现有蓝图。
`--update-endpoint <url>`	删除现有的消息端点，并注册一个带有指定URL的新端点。
`--m365`	把这个特工当作M365特工来对待。通过MCP平台注册消息端点。默认是 `false` （选择加入）。
`-?`、`-h`、`--help`	显示帮助和使用情况信息。

`setup permissions`

配置 OAuth2 权限授予和可继承的权限。

所需的最低权限：全局管理员

a365 setup permissions [command] [options]

选项

Option	Description
`-?`、`-h`、`--help`	显示帮助和使用情况信息。

Subcommands

Subcommand	Description
`mcp`	配置 MCP 服务器 OAuth2 授予和可继承的权限。
`bot`	配置消息传送机器人 API OAuth2 授予和可继承的权限。
`custom`	将自定义 API 权限应用于代理蓝图，这些权限超出了代理作所需的标准权限。
`copilotstudio`	配置 OAuth2 权限授予和代理蓝图的可继承权限，以通过 Power Platform API 调用Copilot Studio copilot。

`setup permissions mcp`

配置 MCP 服务器 OAuth2 授予和可继承的权限。

所需的最低权限：全局管理员

a365 setup permissions mcp [options]

This command:

ToolingManifest.json从deploymentProjectPath指定的值a365.config.json读取。
向代理蓝图授予每个 MCP 服务器范围的 OAuth2 委派权限授予。
配置可继承的权限，以便代理实例可以访问 MCP 工具。
幂等且安全的多次运行。

Important

在执行该命令之前，请确认该 deploymentProjectPath 指向包含已更新 ToolingManifest.json. 如果开发人员将 MCP 服务器添加到其他计算机上，请先与全局管理员共享更新 ToolingManifest.json 。如果没有正确的 ToolingManifest.json 运行，则不会向蓝图添加新的 MCP 服务器权限。
在开发人员运行a365 develop add-mcp-servers运行以下命令。将 MCP 服务器添加到清单并向蓝图授予权限是两个单独的步骤。此命令完成后，MCP 服务器权限在代理蓝图中可见。

`permissions mcp` 选项

Option	Description
`-n`、`--agent-name <name>`	特工基地名称。提供这个选项后，你就不需要配置文件了。
`--tenant-id <tenantId>`	Azure AD 租户 ID。 Overrides auto-detection. 与 `--agent-name` 结合使用。
`-v`、`--verbose`	显示详细的输出。
`--dry-run`	显示命令在未执行的情况下执行的作。
`--remove-legacy-scopes`	迁移到每个服务器权限后，从蓝图中删除旧的共享范围（`McpServers.*.AllTools.ListInvoke.All`格式）。只有在 V2 SDK 确认上线后才使用——V1 SDK 上的代理如果提前移除会失去工具访问权限。
`-?`、`-h`、`--help`	显示帮助和使用情况信息。

迁移到每服务器 MCP 权限

从旧版共享权限模型迁移到每服务器权限时使用 --remove-legacy-scopes ：

旧版共享模型：具有共享范围（例如ea9ffc3e-8a23-4a7d-836d-234d7c7565c1和McpServers.Mail.All）的单个资源应用 IDMcpServers.Teams.All。
每服务器模型：每个 MCP 服务器都有其自己的应用 ID 和范围 Tools.ListInvoke.All。

以下示例演示如何在应用蓝图后Microsoft Entra 管理中心显示每服务器权限。每个 MCP 服务器（如工作 IQ 日历 MCP 和工作 IQ 邮件 MCP）都有自己的委派 Tools.ListInvoke.All 范围。共享 McpServersMetadata.Read.All 范围提供对 MCP 服务器元数据的访问权限。

`setup permissions bot`

配置消息传送机器人 API OAuth2 授予和可继承的权限。

所需的最低权限：全局管理员

先决条件：蓝图和 MCP 权限（首先运行 a365 setup permissions mcp ）

a365 setup permissions bot [options]

`permissions bot` 选项

Option	Description
`-n`、`--agent-name <name>`	特工基地名称。提供这个选项后，你就不需要配置文件了。
`--tenant-id <tenantId>`	Azure AD 租户 ID。 Overrides auto-detection. 与 `--agent-name` 结合使用。
`-v`、`--verbose`	显示详细的输出。
`--dry-run`	显示命令在未执行的情况下执行的作。
`-?`、`-h`、`--help`	显示帮助和使用情况信息。

`setup permissions custom`

将自定义 API 权限应用于代理蓝图，这些权限超出了代理作所需的标准权限。使用此命令，可以向代理授予对其他Microsoft Graph范围（例如状态、文件和聊天）的访问权限，或者授予对组织Microsoft Entra ID租户中注册的自定义 API 的访问权限。

所需的最低权限：全局管理员

先决条件：首先运行 a365 setup blueprint 。

a365 setup permissions custom [options]

This command:

为每个配置的资源配置 OAuth2 委派权限授予，并授予管理员许可。
设置可继承的权限，以便代理用户可以从蓝图继承访问权限。
通过添加新权限并删除从配置中删除的任何权限来协调Microsoft Entra与当前配置。
幂等且安全的多次运行。

`permissions custom` 选项

Option	Description
`-n`、`--agent-name <name>`	特工基地名称。提供这个选项后，你就不需要配置文件了。
`--tenant-id <tenantId>`	Azure AD 租户 ID。 Overrides auto-detection. 与 `--agent-name` 结合使用。
`-v`、`--verbose`	显示详细的输出。
`--dry-run`	显示命令在未执行的情况下执行的作。
`--resource-app-id <guid>`	资源应用ID（GUID）用于内联自定义权限。与 `--scopes` 结合使用。
`--scopes <scopes>`	逗号分隔的委托范围用于内联自定义权限。与 `--resource-app-id` 结合使用。
`-?`、`-h`、`--help`	显示帮助和使用情况信息。

在线配置自定义权限

使用 --resource-app-id 并 --scopes 直接应用自定义权限而无需编辑 a365.config.json：

# Add Microsoft Graph extended permissions
a365 setup permissions custom `
  --resource-app-id 00000003-0000-0000-c000-000000000000 `
  --scopes Presence.ReadWrite,Files.Read.All,Chat.Read

# Add custom API permissions
a365 setup permissions custom `
  --resource-app-id <your-api-app-id> `
  --scopes CustomScope.Read,CustomScope.Write

资源名称是从 Microsoft Entra 自动解析的。你不需要特别说明。

通过配置文件配置自定义权限

或者，添加customBlueprintPermissionsa365.config.json命令并执行该命令，不使用内联标志：

a365 setup permissions custom

这个命令会将 Microsoft Entra 与配置的权限进行对照——它会添加新的权限，并移除你从配置中删除的权限。

与 `setup all` 的集成

当配置包含自定义权限时，运行 a365 setup all 会自动将其配置为单个批处理权限阶段的一部分。完整的设置顺序为：

Blueprint
权限批处理（MCP、机器人 API、自定义蓝图权限 - 全部配置在一起）

`setup permissions copilotstudio`

配置 OAuth2 权限授予和代理蓝图的可继承权限，以通过 Power Platform API 调用Copilot Studio copilot。

所需的最低权限：全局管理员

先决条件：首先运行 a365 setup blueprint 。

a365 setup permissions copilotstudio [options]

This command:

确保租户中存在 Power Platform API 服务主体。
使用范围创建从蓝图到 Power Platform API CopilotStudio.Copilots.Invoke 的 OAuth2 权限授予。
设置可继承的权限，以便代理实例可以调用Copilot Studio copilot。

`permissions copilotstudio` 选项

Option	Description
`-n`、`--agent-name <name>`	特工基地名称。提供这个选项后，你就不需要配置文件了。
`--tenant-id <tenantId>`	Azure AD 租户 ID。 Overrides auto-detection. 与 `--agent-name` 结合使用。
`-v`、`--verbose`	显示详细的输出。
`--dry-run`	显示命令在未执行的情况下执行的作。
`-?`、`-h`、`--help`	显示帮助和使用情况信息。

当代理需要在运行时调用Copilot Studio copilot 或调用需要 CopilotStudio 权限的 Power Platform API 时，请使用此命令。

`setup all`

执行所有设置步骤以设置代理 365 环境

a365 setup all [options]

运行完整的代理 365 安装程序，并按顺序执行所有步骤。

包括：蓝图和权限。

完成的步骤取决于你的角色：

Step	Global Administrator	代理身份管理员	代理ID开发者
Prerequisites check	Yes	Yes	Yes
代理蓝图创建	Yes	Yes	Yes
可继承权限（仅限AI队友）	Yes	Yes	Yes
OAuth2 权限授予（管理员许可）	Yes	需要 GA 步骤	需要 GA 步骤
代理身份授予（`--authmode s2s` 或 `both`）	Yes	Yes	PowerShell fallback

在没有全局管理员的情况下运行时 a365 setup all ，CLI：

完成它可以执行的所有步骤（蓝图创建和可继承的权限）。
生成每个资源管理员同意 URL 并将其保存到 a365.generated.config.json。
在输出中显示全局管理员完成OAuth2授权的下一步步骤，包括直接链接或同意URL。

Tip

如果你是全局管理员，请在单个运行中完成所有内容， a365 setup all 无需交接。

所需的最低权限：

代理 ID 开发人员角色（用于创建蓝图）
全局管理员（用于OAuth2权限授权——如果无法使用，CLI会在输出中打印下一步步骤）
代理ID管理员、应用管理员或全局管理员（用于S2S（服务器间）代理身份授予—— --authmode s2s 或者 both;如果无法使用，CLI会在设置摘要中打印PowerShell备份）

`setup all` 选项

Option	Description
`-v`、`--verbose`	显示详细的输出。
`--dry-run`	显示命令在未执行的情况下执行的作。
`--skip-requirements`	跳过要求验证检查。请谨慎使用：如果未满足先决条件，安装程序可能会失败。
`--aiteammate`	使用该参数指示 AI Teamate 代理流程仅配置蓝图和权限。没有该参数，蓝图代理流程会自动创建代理身份服务主体，且没有 Entra 用户。该参数覆盖 `aiteammate` 了中的 `a365.config.json`域。
`--authmode <mode>`	用于授予代理身份权限的认证模式（仅限蓝图代理）。 `obo` （默认）——以委托为核心范围的授权，无需行政角色。 `s2s` — 代理身份SP上的应用角色分配，需要代理ID管理员、应用管理员或全局管理员;如果没有角色，则打印PowerShell备份。 `both` —— 应用OBO（代表者）和S2S资助。不支持 `--aiteammate`。也可以设为 `authModea365.config.json`。
`--agent-registration-only`	跳过蓝图和权限步骤，只运行代理注册。用于重试失败的注册步骤。
`--m365`	把这个特工当作M365特工来对待。通过MCP平台注册消息端点。默认是 `false` （选择加入）。
`-n`、`--agent-name <name>`	代理基名称（例如， `"MyAgent"`）。提供时，无需配置文件。将显示名称派生为 `"<name> Identity"` 和 `"<name> Blueprint"`。从（使用替代） `az account show`自动检测到 `--tenant-id` TenantId。通过在租户中查找 `Agent 365 CLI` 来解析 ClientAppId。
`--tenant-id <tenantId>`	Azure AD 租户 ID。重写从 `az account show`中自动检测。在非交互式环境中运行时或面向特定租户时使用 `--agent-name` 。
`-?`、`-h`、`--help`	显示帮助和使用情况信息。

Agent setup

默认情况下，运行 a365 setup all 蓝图代理流程。此流创建没有 Dataverse 或 AI 团队成员依赖项的代理。它适用于直接与Agent 365平台通信的代理。

# Default: uses a365.config.json
a365 setup all

# Or explicitly (same result)
a365 setup all --aiteammate false

要运行AI队友代理流程，请传给 --aiteammate。

此流按顺序执行以下步骤：

验证 - 检查Azure角色和先决条件。
Blueprint 创建 - 创建或重复使用Entra ID代理蓝图应用程序。
Batch 权限 - 针对Microsoft Graph、代理 365 工具、消息传递机器人 API、可观测性 API、Power Platform 和任何自定义资源的蓝图配置委派权限授予。
代理标识创建 - 通过代理标识图形 API在Entra ID中创建代理标识。
代理注册 - 通过 AgentX V2 代理注册 API 注册代理。
配置同步 - 将运行时连接设置和可观测性配置写入项目文件（appsettings.json， .env）。

Note

代理设置要求对自定义客户端应用拥有六个额外的 beta API 权限：AgentIdentityBlueprint.AddRemoveCreds.All、、AgentIdentityBlueprint.DeleteRestore.AllAgentInstance.ReadWrite.All、AgentIdentity.ReadWrite.All、和AgentIdentity.Create.AllAgentIdentity.DeleteRestore.All。有关完整列表，请参阅自定义客户端应用注册。

使用

如果没有 a365.config.json 文件，则用于 --agent-name 在没有文件的情况下运行安装程序。 CLI 通过查找租户中的已知 Agent 365 CLI 应用注册来自动检测租户并解析客户端应用。

# Preview what would happen (no changes made)
a365 setup all --agent-name "MyAgent" --dry-run

# Run the full setup
a365 setup all --agent-name "MyAgent"

使用 --agent-name 时：

从中自动检测到 az account show。传递给 --tenant-id 替代。
通过查找租户中命名的 Entra 应用来解析 Agent 365 CLI。如果未找到，CLI 将退出并显示错误。有关如何注册此应用的自定义客户端应用注册。
显示名称 派生为 "<name> Agent" （标识）和 "<name> Blueprint" （蓝图）。
始终跳过基础结构 （假定外部托管）。
由于没有配置项目路径，因此跳过了配置同步（写入appsettings.json）。

如果客户端应用没有对所需权限的 AllPrincipals 管理员许可，CLI 将检测此权限，并提示你以交互方式授予许可：

The following permissions require admin consent:
  AgentIdentity.ReadWrite.All
  AgentIdentity.Create.All
  ...
Grant admin consent for these permissions now? [y/N]:

输入 y 以内联授予同意。如果您不是全局管理员，请拒绝——CLI 会在设置摘要中打印全局管理员的下一步步骤。

智能体身份授予（`--authmode`）

默认情况下，在 a365 setup all 代理身份服务主体（obo 模式）上创建基于主体范围的委托授权。这些资助不需要管理员角色。

用于 --authmode 控制资助类型：

Value	Behavior	Minimum role
`obo`（默认值）	代理人身份SP 的委托范围授权	无（任何认证用户）
`s2s`	代理身份 SP 上的应用角色分配	代理ID管理员、应用管理员或全局管理员
`both`	OBO都委派了资助和S2S应用的角色分配	S2S角色（上图）关于S2S部分

# Default — OBO delegated grants (no admin role needed)
a365 setup all

# S2S app role assignments
a365 setup all --authmode s2s

# Both OBO and S2S
a365 setup all --authmode both

当登录用户缺乏获得S2S授权所需的角色时，CLI会在设置摘要中打印PowerShell备份块。管理员可以运行它来完成作业。

设置authModea365.config.json成每次无旗号的运行都适用：

{
  "authMode": "s2s"
}

Note

--authmode --aiteammate不支持。 AI队友代理通过代理用户身份自动使用OBO。

Config sync

成功运行后，CLI 会自动将运行时设置写入项目文件：

Setting	Written to	Description
`Connections.ServiceConnection`	`appsettings.json` / `.env`	蓝图客户端 ID、客户端密码、租户 ID 和令牌终结点
`Agent365Observability`	`appsettings.json` / `.env`	用于遥测导出的代理 ID（代理标识）、蓝图 ID、租户 ID、客户端 ID 和客户端密码
`TokenValidation`	`appsettings.json`	令牌验证设置（默认情况下为非 DW 禁用）
`ConnectionsMap`	`appsettings.json` / `.env`	连接映射的默认服务 URL

如果文件不存在，CLI 将创建该文件，并在不覆盖其余配置的情况下更新单个字段。

重试失败的注册

如果安装程序成功完成蓝图和权限但在代理注册期间失败，则用于 --agent-registration-only 仅重试该步骤而不重复先前的工作：

a365 setup all --agent-registration-only

反馈

此页面是否有帮助？

Last updated on 2026-05-01

代理 365 CLI setup 命令参考

Syntax

选项

建议的执行顺序

setup requirements

requirements 选项

setup blueprint

blueprint 选项

setup permissions

选项

Subcommands

setup permissions mcp

permissions mcp 选项

迁移到每服务器 MCP 权限

setup permissions bot

permissions bot 选项

setup permissions custom

permissions custom 选项

在线配置自定义权限

通过配置文件配置自定义权限

与 setup all 的集成

setup permissions copilotstudio

permissions copilotstudio 选项

setup all

setup all 选项

Agent setup

使用

安装过程中的管理员同意

智能体身份授予（--authmode）

Config sync

重试失败的注册

反馈

其他资源

代理 365 CLI `setup` 命令参考

`setup requirements`

`requirements` 选项

`setup blueprint`

`blueprint` 选项

`setup permissions`

`setup permissions mcp`

`permissions mcp` 选项

`setup permissions bot`

`permissions bot` 选项

`setup permissions custom`

`permissions custom` 选项

与 `setup all` 的集成

`setup permissions copilotstudio`

`permissions copilotstudio` 选项

`setup all`

`setup all` 选项

智能体身份授予（`--authmode`）