設定 Agent 藍圖

Agent 藍圖會定義 Agent 的身分識別、權限，以及基礎結構需求。從這個 Agent 藍圖建立每個 Agent 執行個體。

注意

設定 Agent 藍圖是啟用 Register、Work IQ 和 AI 隊友功能的必要條件。請參閱開始使用 Agent 365 開發，了解哪些功能適用於您的 Agent。

有關 Agent 365 身分識別的詳細資訊，請參閱 Agent 365 身分識別。

先決條件

在開始之前，請確定您具備下列先決條件：

Agent 365 CLI - 請參閱 Agent 365 CLI 安裝。
所需的權限：
- 具有以下角色之一的有效租用戶使用者：
  - 全域系統管理員
  - Agent 識別碼開發人員
- 存取具有權限的 Azure 訂用帳戶以建立資源
提示

Agent (非 AI 隊友) 不需要組態檔。使用 a365 setup all --agent-name <name>，CLI 會自動解析您的租用戶和用戶端應用程式。 AI 隊友設定需要手動建立的 a365.config.json。

建立 Agent 藍圖

使用 a365 setup命令來建立 Azure 資源並註冊您的 Agent 藍圖。藍圖會定義您的 Agent 身分識別、權限及基礎結構需求。此步驟為在 Azure 中部署與執行 Agent 奠定基礎。

執行安裝程式

執行設定命令：

a365 setup -h

該命令有多種選項。您可以使用 a365 setup all 或選擇更精細的選項，用單一命令完成整個設定。

注意

a365 setup all 預設為藍圖 Agent 模式。若要改為設定 AI 隊友 Agent，請傳遞 --aiteammate。對於 M365 Agent (Teams、Copilot)，也會自動傳遞 --m365 以自動註冊訊息端點。

Agent 設定 (預設)：

# With a config file
a365 setup all

# Config-free — no a365.config.json needed
a365 setup all --agent-name <your-agent-name>

M365 Agent 設定 (Teams/Copilot)：

# Registers the messaging endpoint via MCP Platform
a365 setup all --m365

AI 隊友設定：

a365 setup all --aiteammate

整個設定流程會執行以下作業：

建立 Azure 基礎結構 (如尚未存在)
- 資源群組
- 具有指定 SKU 的應用程式服務方案
- 啟用受控身分識別的 Azure Web 應用程式
註冊 Agent 藍圖：
- 在您的 Microsoft Entra 租用戶中建立 Agent 藍圖
- 建立 Microsoft Entra 應用程式註冊
- 使用必要權限，設定 Agent 身分識別
- 在藍圖上設定平台可管理性所必需的 managerApplications
重要

藍圖必須設定 managerApplications，平台才會接受。 CLI 會自動設定此項目。如果您有在這項需求引入前建立的藍圖，請將其刪除並重新執行 a365 setup all，或透過圖形 API 手動修補。
設定 API 權限
- 設定 Microsoft 圖形 API 範圍
- 設定訊息機器人 API 權限
- 為 Agent 執行個體套用可繼承的權限
更新組態檔：
- 將產生的識別碼和端點儲存至您工作目錄中的新檔案，名為 a365.generated.config.json
- 紀錄受控識別與資源資訊

注意

設定通常需要 3 到 5 分鐘，且會自動將組態儲存為 a365.generated.config.json。如果您以全域管理員身分執行，CLI 可能會開啟瀏覽器視窗進行管理員同意 - 完成同意流程即可繼續。如果您以 Agent 識別碼開發人員身分執行，不會出現瀏覽器視窗，CLI會產生同意網址，供全域管理員於稍後完成。

使用 Agent 識別碼開發人員來設定

如果您 Agent 識別碼開發人員 (非全域管理員) 身分執行，a365 setup all 會自動完成大部分步驟，但 OAuth2 權限授與需要由全域管理員另外完成步驟。

哪些步驟會自動完成：

Azure 基礎架構 (資源群組、應用程式服務方案、Web 應用程式)
Agent 藍圖註冊
Agent 執行個體的可繼承權限

哪些步驟需要全域管理員：

針對 Microsoft Graph、Agent 365 工具、傳訊機器人 API、可檢視性 API 和 Power Platform API 的 OAuth2 委派權限授與 (AllPrincipals 同意)

如何使用非管理員帳戶完成設定：

薪級	何人	動作
1	開發人員	執行 `a365 setup all`。 CLI 會完成所有能完成的步驟，並顯示後續步驟，包括一個讓全域管理員可以開啟的同意網址。
2	開發人員	請將 CLI 輸出中的同意網址與您的全域管理員共用。
3	全域系統管理員	在以全域管理員身分登入的瀏覽器中開啟同意網址並授與所需權限。

執行命令：

# 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 顯示的下一步與您的全域管理員共用。他們可以打開提供的連結或同意網址以完成 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`	Agent 的唯一識別碼	用於開發人員入口網站與系統管理中心
`agentBlueprintObjectId`	藍圖的 Microsoft Entra ID
`messagingEndpoint`	訊息路由	Teams 或 Outlook 傳送訊息到您的 Agent
`agentBlueprintClientSecret`	驗證機密	應該存在 (值遭到遮蔽)
`resourceConsents`	API 權限	應該包含 Microsoft Graph、Agent 365 工具、傳訊機器人 API、可檢視性 API 等資源
`completed`	設定狀態	應該是 `true`

注意

如果您以 Agent 識別碼管理員或Agent 識別碼開發人員身分執行設定，resourceConsents 可能會是空的，completed 可能會顯示為 false，直到全域管理員使用 CLI 所顯示的下一步完成 OAuth2 權限授與。

驗證 Azure 入口網站中的 Azure 資源：

或使用 az resource listPowerShell 命令。
```
# List all resources in your resource group
az resource list --resource-group <your-resource-group> --output table
```
驗證以下資源已建立：
- 資源群組：
  - 移至資源群組>選取您的資源群組
  - 驗證它包含您的應用程式服務方案和 Web 應用程式
- 應用程式服務方案：
  - 移至應用程式服務>應用程式服務方案
  - 找到您的方案，並驗證定價層符合您的組態 SKU
- Web 應用程式：
  - 移至應用程式服務>Web 應用程式
  - 尋找您的 Web 應用程式，然後移至設定>身分識別>系統指派
  - 驗證狀態為啟用
  - 請注意物件 (主體) 識別碼符合 managedIdentityPrincipalId
在 Azure 入口網站中驗證 Microsoft Entra 應用程式：

移至 Azure Active Directory>應用程式註冊>所有應用程式：
- 依 agentBlueprintId 搜尋您的 Agent 藍圖
- 開啟應用程式並選取 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"
}

驗證 Agent 藍圖在 Microsoft Entra 中註冊：

在 Microsoft Entra 系統管理中心中，搜尋您的 agentBlueprintId 或依名稱搜尋。

請確認：

✅ 會出現應用程式註冊與企業應用程式
✅ 在應用程式註冊藍圖上，API 權限索引標籤會顯示所有權限
✅ 狀態會顯示已授與 [您的租用戶]

如需更多協助，請參閱：

自訂用戶端應用程式問題

Agent 權限

在應用程式和 Agent 能夠讀取或寫入Microsoft 365資料 (使用者、郵件、檔案、Teams、Agent等) 之前，您必須明確授與它們 Microsoft Graph 權限。 Microsoft Graph 權限是一套授權模型，會控制應用程式或服務能夠透過 Microsoft Graph API 在 Microsoft 365 和 Microsoft Entra ID 中存取哪些資料與執行哪些動作。

深入了解：Microsoft Graph 權限概觀

若要使用 Agent 365 Agent執行個體的 Graph權限，開發人員必須在 Agent 藍圖中宣告這些權限。當管理員在 Microsoft 365 系統管理中心中啟動藍圖時，入口網站會審查藍圖的 Graph 權限，並提示管理員同意這些權限。

若要了解並確認 Graph 權限如何啟用您的Agent，您可以：

檢視所有可用的 Graph 權限
瀏覽 Graph 總管以嘗試查詢、檢視回覆，和了解權限。
部署前，請使用 Microsoft 365 Agent 遊樂場，在本機測試您的 Agent。

將權限套用至您的藍圖

請使用 a365 setup permissions custom，在 Microsoft Entra 中套用內嵌至您的藍圖的自訂 API 權限。

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。

後續步驟

將您的 Agent 程式碼部署至雲端：

Azure

Amazon Web Services (AWS)

Google Cloud Platform (GCP)

將 Agent 發佈至 Microsoft 365 系統管理中心

疑難排解

本區段會說明設定 Agent 藍圖時常見的問題。

提示

Agent 365 疑難排解指南包含高階疑難排解建議、最佳做法，以及每個階段的疑難排解連結，涵蓋 Agent 365 開發生命週期的所有部分。

這些問題有時會在註冊時發生：

權限不足錯誤
缺少 Azure CLI 驗證
資源已存在
管理員同意尚未完成
組態檔遺失或無效
設定完成，但資源未建立
Agent 藍圖未在 Microsoft Entra 中註冊
未授與 API 權限
未啟用受控識別
設定花費時間過長或停止回應
清理無組態的 Agent
無法在 Teams 中發送第一則訊息

權限不足錯誤

症狀：執行a365 setup命令期間，出現權限不足錯誤。

您需要在 Microsoft Entra 租用戶中具備以下其中一個角色：

全域系統管理員
Agent 識別碼開發人員

以及 Azure 訂用帳戶參與者或擁有者存取權。

解決方案：驗證您在 Microsoft Entra 中擁有所需權限。

移至：Microsoft Entra 系統管理中心> 您的個人檔案 > 指派的角色
使用az account showPowerShell 命令檢查 Azure 訂用帳戶存取權

注意

如果您具有 Agent 識別碼管理員或 Agent 識別碼開發人員角色 (非全域管理員)，a365 setup all 仍然會成功，但會跳過 OAuth2 權限授與。設定完成後，CLI 會顯示全域管理員的下一個步驟以完成剩餘授與。這種工作流程預期用於 Agent 開發人員與全域管理員為不同人員的組織。

缺少 Azure CLI 驗證

症狀：設定失敗並出現驗證錯誤。

解決方案：確保您已連接 Azure，並驗證您的帳戶和訂用帳戶。

# Authenticate with Azure
az login

# Verify correct account and subscription
az account show

資源已存在

症狀：設定因資源群組、應用程式服務方案或 Web 應用程式的 Resource already exists 錯誤而失敗。

解決方案：請選擇下列其中一個解決方案。

使用現有的資源

如果資源已存在且您希望使用它們，請確保這些資源符合您的組態。使用 az resource listPowerShell 命令。
```
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 提示。在出現的瀏覽器視窗中完成同意流程。
Agent 識別碼管理員或開發人員：您無法直接完成 OAuth2 權限授與。執行 a365 setup all — 設定摘要會顯示全域管理員的下一步，包括直接連結或同意 URL 以完成授與。請將那些詳細資料與您的全域管理員共用。

組態檔遺失或無效

症狀：設定失敗，並出現「未找到組態」或確認錯誤。

解決方案：

驗證 a365.config.json 檔案存在。
如果缺少或無效，請手動建立或使用 a365 setup all --agent-name <name> (僅適用於 Agent)。

# 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

Agent 藍圖未在 Microsoft Entra 中註冊

症狀：設定完成，但您在 Microsoft Entra 系統管理中心找不到 Agent 藍圖。

解決方案：

從 a365.generated.config.json 取得藍圖識別碼。

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 系統管理中心。
尋找您的 Agent 藍圖應用程式註冊。
移至 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
```

清理無組態的 Agent

症狀：您已透過a365 setup all --agent-name <name> 佈建 Agent ，現在想要移除它，但您沒有 a365.config.json 檔案。

解決方案：使用 a365 cleanup --agent-name 來移除沒有組態檔的 Agent。 CLI 會從在 Bootstrap 設定過程中寫入的全域組態檔讀取資源識別碼。

a365 cleanup --agent-name <your-agent-name>

提示

如果命令在驗證過程中停滯，系統會自動回退到裝置程式碼流程。請按照終端機顯示的指示完成登入。

如果您不再擁有全域產生的組態 (例如重新安裝 CLI 後)，請使用 a365 cleanup搭配手動建立的最小 a365.config.json，或直接透過 Azure 入口網站和 Microsoft Entra 系統管理中心移除資源。

無法在 Teams 中發送第一則訊息

症狀：佈建 Agent 執行個體後，無法向 Agent 管理員發送歡迎訊息。

解決方案：建立新聊天物件需要 [Chat.Create][perm-chatcreate] 權限。如果已存在一對一聊天，此作業會傳回現有聊天，而不會建立新的聊天。

實作時，請設定藍圖的可繼承權限以包含範圍 Chat.Create。
設定 Teams 聊天訊息，使其於 Agent 執行個體佈建後自動發送。
從藍圖建立一個新的 Agent 執行個體，並測試首次執行訊息。

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-07-30

設定 Agent 藍圖

先決條件

建立 Agent 藍圖

執行安裝程式

使用 Agent 識別碼開發人員來設定

驗證設定

Agent 權限

將權限套用至您的藍圖

後續步驟

疑難排解​​

權限不足錯誤

缺少 Azure CLI 驗證

資源已存在

管理員同意尚未完成

組態檔遺失或無效

設定完成，但資源未建立

Agent 藍圖未在 Microsoft Entra 中註冊

未授與 API 權限

未啟用受控識別

設定花費時間過長或停止回應

清理無組態的 Agent

無法在 Teams 中發送第一則訊息

意見反應

其他資源

疑難排解