Agent 365 CLI `setup` 指令參考

在每個步驟上設置你的 Agent 365 環境，並細緻地控制每個步驟。此指令管理 Agent 365 藍圖的初始設定工作流程。

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`

驗證 Agent 365 設定的前提條件。執行模組化需求檢查，並針對發現的問題提供指導。

a365 setup requirements [options]

此指令執行以下步驟：

檢查 Agent 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 租用戶識別碼。 Overrides auto-detection. 與 `--agent-name` 搭配使用。
`-v`、`--verbose`	顯示詳細的成果。
`--dry-run`	展示指令在不執行的情況下會做什麼。
`--skip-requirements`	跳過需求驗證檢查。請小心使用。
`--no-endpoint`	不要註冊訊息端點（只註冊藍圖）。
`--endpoint-only`	僅註冊訊息端點。需要現有的藍圖。
`--update-endpoint <url>`	刪除現有的訊息端點，並以指定的網址註冊一個新的端點。
`--m365`	請將此代理視為 M365 代理。透過 MCP 平台註冊訊息端點。預設是 `false` （選擇加入）。
`--show-secret`	以明文顯示儲存的藍圖客戶端秘密。不會執行任何設定步驟。在 Windows 上，需要執行安裝時使用的同一台機器和使用者帳號。
`-?`、`-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 副駕駛。

`setup permissions mcp`

設定 MCP 伺服器 OAuth2 授權與可繼承權限。

最低必要權限：全域管理員

a365 setup permissions mcp [options]

This command:

從ToolingManifest.json指定的 deploymentProjectPath讀取 a365.config.json 。
將 OAuth2 授權授權，針對每個 MCP 伺服器範圍授予代理藍圖。
設定可繼承權限，讓代理實例能存取 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 租用戶識別碼。 Overrides auto-detection. 與 `--agent-name` 搭配使用。
`-v`、`--verbose`	顯示詳細的成果。
`--dry-run`	展示指令在不執行的情況下會做什麼。
`--remove-legacy-scopes`	遷移到每台伺服器權限`McpServers.*.All`後，從藍圖中移除舊有的共享範圍（`Tools.ListInvoke.All`格式化）。只有在 V2 SDK 確認上線後才使用——V1 SDK 上的代理若提前移除會失去工具存取權。
`-?`、`-h`、`--help`	顯示說明和使用資訊。

遷移至每台伺服器的 MCP 權限

從舊有共享權限模式遷移到每伺服器權限時，請使用 --remove-legacy-scopes ：

舊有共享模型：單一資源應用程式 ID （ea9ffc3e-8a23-4a7d-836d-234d7c7565c1），具有共享的範圍，如 McpServers.Mail.AllMcpServers.Teams.All和。
每台伺服器模型：每個 MCP 伺服器都有其獨立的應用程式 ID，範圍為 Tools.ListInvoke.All。

以下範例展示了藍圖套用後，Microsoft Entra 系統管理中心中各伺服器權限的呈現方式。每個 MCP 伺服器，例如 Work IQ Calendar MCP 和 Work IQ Mail MCP，都有自己的委派 Tools.ListInvoke.All 範圍。共享 McpServersMetadata.Read.All 範圍提供對 MCP 伺服器元資料的存取。

`setup permissions bot`

配置訊息機器人 API OAuth2 授權與可繼承權限。

最低必要權限：全域管理員

前置條件：Blueprint 與 MCP 權限（先執行 a365 setup permissions mcp ）

a365 setup permissions bot [options]

`permissions bot` 選項

Option	Description
`-n`、`--agent-name <name>`	特工基地名稱。當你提供這個選項時，就不需要設定檔了。
`--tenant-id <tenantId>`	Azure AD 租用戶識別碼。 Overrides auto-detection. 與 `--agent-name` 搭配使用。
`-v`、`--verbose`	顯示詳細的成果。
`--dry-run`	展示指令在不執行的情況下會做什麼。
`-?`、`-h`、`--help`	顯示說明和使用資訊。

`setup permissions custom`

為你的代理藍圖套用自訂的 API 權限，超出代理操作所需的標準權限。使用此指令，您將授權代理人員存取更多 Microsoft Graph 範圍，如 Presence、Files 和 Chat，或是您組織 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 租用戶識別碼。 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 副駕駛。

最低必要權限：全域管理員

先決條件：先跑 a365 setup blueprint 。

a365 setup permissions copilotstudio [options]

This command:

確保 Power Platform API 服務主體存在於你的租戶中。
從藍圖建立一個 OAuth2 權限授權給 Power Platform API，並帶有 CopilotStudio.Copilots.Invoke 範圍。
設定可繼承權限，讓代理實例能呼叫 Copilot Studio 的副駕駛。

`permissions copilotstudio` 選項

Option	Description
`-n`、`--agent-name <name>`	特工基地名稱。當你提供這個選項時，就不需要設定檔了。
`--tenant-id <tenantId>`	Azure AD 租用戶識別碼。 Overrides auto-detection. 與 `--agent-name` 搭配使用。
`-v`、`--verbose`	顯示詳細的成果。
`--dry-run`	展示指令在不執行的情況下會做什麼。
`-?`、`-h`、`--help`	顯示說明和使用資訊。

當您的代理需要在執行時呼叫 Copilot Studio 副駕駛，或呼叫需要 CopilotStudio 權限的 Power Platform API 時，請使用此指令。

`setup all`

執行所有設定步驟以建立您的 Agent 365 環境

a365 setup all [options]

執行完整的 Agent 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	PowerShell fallback	PowerShell fallback

當你在沒有全域管理員的情況下執行 a365 setup all 時，CLI 會：

完成所有能完成的步驟（藍圖建立和可繼承權限）。
產生每個資源管理員的同意網址並儲存到 a365.generated.config.json。
在輸出中顯示全域管理員完成 OAuth2 授權的下一步步驟，包括直接連結或同意網址。

Tip

如果你是全域管理員，能 a365 setup all 一次性完成所有任務，無需交接。

最低必要權限：

代理 ID 開發者角色（用於藍圖創建）
全域管理員（用於 OAuth2 權限授權——若無法使用，CLI 會在輸出中列印下一步）
應用程式管理員或全域管理員（用於 S2S（伺服器對伺服器）代理身份授權—— --authmode s2s 或 both;若無法使用，CLI 會在設定摘要中列印 PowerShell 備援）

`setup all` 選項

Option	Description
`-v`、`--verbose`	顯示詳細的成果。
`--dry-run`	展示指令在不執行的情況下會做什麼。
`--skip-requirements`	跳過需求驗證檢查。使用時請小心：若未達成前提條件，設定可能會失敗。
`--aiteammate`	利用此參數指示 AI 隊友代理流程只設定藍圖與權限。若無此參數，藍圖代理流程會自動建立代理身份服務主體，且不會有 Entra 使用者。此參數覆蓋 `aiteammate` 中的 `a365.config.json`域。
`--authmode <mode>`	代理身份授權的認證模式（僅限藍圖代理）。 `obo` （預設） — 以委託為基礎的授權補助，無需行政職務。 `s2s` — 在代理身份 SP 上分配應用程式角色，需應用程式管理員或全域管理員;如果角色缺失，則會列印 PowerShell 備援。 `both` — 適用OBO（代表）及S2S補助。不支援。`--aiteammate` 也可以設定為 `authModea365.config.json`。
`--agent-registration-only`	跳過藍圖和權限步驟，只執行代理註冊。用來重試失敗的註冊步驟。
`--m365`	請將此代理視為 M365 代理。透過 MCP 平台註冊訊息端點。預設是 `false` （選擇加入）。
`-n`、`--agent-name <name>`	代理基底名稱（例如， `"MyAgent"`）。提供設定檔時，則不需要設定檔。推導出顯示名稱為 `"<name> Identity"` 和 `"<name> Blueprint"`。 TenantID 會自動偵測到（ `az account show` 覆寫為 `--tenant-id`）。 ClientAppID 是透過查詢 `Agent 365 CLI` 租戶來解決的。
`--tenant-id <tenantId>`	Azure AD 租用戶識別碼。覆蓋自動偵測。`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。

此流程依序執行以下步驟：

Requirements Validation — 檢查Azure角色與前置條件。
Blueprint creation — 建立或重用 Entra ID Agent Blueprint 應用程式。
Batch 權限 — 在藍圖上配置授權權限，適用於 Microsoft Graph、Agent 365 工具、訊息機器人 API、可觀察性 API、Power Platform 及任何自訂資源。
Agent Identity creation — 透過 Agent Identity 圖形 API 建立 Entra ID 代理身份。
代理註冊 — 透過 AgentX V2 代理註冊 API 註冊代理。
設定同步 — 將執行時連線設定和可觀察性設定寫入你的專案檔案（appsettings.json， .env）。

Note

代理程式設定需要在自訂客戶端應用程式上額外六個測試版 API 權限：AgentIdentityBlueprint.AddRemoveCreds.All、 AgentIdentityBlueprint.DeleteRestore.AllAgentInstance.ReadWrite.AllAgentIdentity.ReadWrite.AllAgentIdentity.Create.AllAgentIdentity.DeleteRestore.All、。完整清單請參閱自訂客戶端應用程式註冊。

無需設定的設定 `--agent-name`

如果你沒有檔案， 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時：

TenantID 是自動偵測的。az account show 切換 --tenant-id 到覆蓋。
ClientAppID 的解決方式是尋找租戶中指定的 Agent 365 CLI Entra 應用程式。若未找到，CLI 會以錯誤退出。請參閱「自訂客戶端應用程式註冊」了解如何註冊此應用程式。
顯示名稱 可依 "<name> Agent" 據（identity）與 "<name> Blueprint" （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 上的應用程式角色指派	應用程式管理員或全域管理員
`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`	Blueprint 用戶端 ID、用戶端秘密、租戶 ID 與 token 端點
`Agent365Observability`	`appsettings.json` / `.env`	代理識別碼（代理身份）、藍圖識別碼、租戶識別碼、用戶端 ID 及用戶端秘密以進行遙測匯出
`TokenValidation`	`appsettings.json`	令牌驗證設定（非 DW 預設停用）
`ConnectionsMap`	`appsettings.json` / `.env`	連線映射的預設服務網址

如果沒有檔案，CLI 會建立該檔案，並更新個別欄位，且不會覆蓋你設定的其他部分。

重新嘗試失敗的註冊

若設定成功完成藍圖與權限，但在代理註冊時失敗，請只 --agent-registration-only 重試該步驟，避免重複先前的工作：

a365 setup all --agent-registration-only

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-05-08

Agent 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

無需設定的設定 --agent-name

設定時的管理員同意

代理身份授予（--authmode）

Config sync

重新嘗試失敗的註冊

意見反應

其他資源

Agent 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` 選項

無需設定的設定 `--agent-name`

代理身份授予（`--authmode`）