代理藍圖與實例設定

代理認證流程使代理能以自身身份行動。 在這個流程中：

• 代理使用自身的憑證（代理藍圖憑證）進行認證
• 代理程式獨立運作，擁有自己分配的權限
• 代理有自己的身份，與任何使用者分開
• 這種流程非常適合不需要使用者上下文的自主代理操作

使用案例：

• 自主代理操作（排程任務、監控）
• 從代理人的信箱發送電子郵件或建立會議
• 建立與管理代理人擁有的資源
• 背景處理，無需使用者互動

建立你的代理身份

要開發並測試你的代理程式，使用代理認證，你需要建立代理身份並註冊給 Microsoft 365。 這個身份允許你在建置代理時測試其功能，例如工具、可觀察性和通知。

代理建立過程包含三個關鍵步驟：

1. 設定 - 初始化 Agent 365 CLI 設定
2. 設定 - 建立 Azure 資源與代理藍圖
3. 建立實例 - 建立代理式應用程式 ID 與使用者

先決條件

開始前，請先確保下列事項：

• Agent 365 CLI - 請參閱 Agent 365 CLI 安裝

所需的權限：

• 具有下列其中一個角色的使用者或服務：
  • 全域系統管理員
  • 代理識別管理員
  • 代理 ID 開發者
• 存取 Azure 訂用帳戶，其具有建立資源和指派角色的權限。

步驟 4：設定 Agent 設定檔

此 a365 config init 指令 建立 a365.config.json，為所有 Agent 365 CLI 指令所共用的中央設定檔。 CLI 提供互動式精靈，包含 Azure CLI 整合及智慧預設，以減少手動輸入。

使用 Azure 進行驗證

在初始化設定前，請使用 az login 以下指令與 Azure 進行認證：

az login

選取適當的訂用帳戶和專案。 設定精靈使用 Azure CLI 來查詢可用的訂閱、資源群組及應用程式服務方案。

初始化；基礎；設定

執行下列命令，以在容器中啟動互動式 Bash 工作階段：

a365 config init

精靈使用 Azure CLI 整合和智慧預設，以減少手動輸入。 系統會提示您 。

精靈會自動產生相關的資源名稱、身份，並驗證你的專案類型。

高可用性限制

目前僅支援的 Azure 區域為：

• centralindia
• westeurope
• westus

如果你選擇不同的區域，或手動編輯 location 檔案中的 a365.config.json 屬性，當你嘗試建立代理人藍圖時，會出現以下錯誤。

The selected region ('{location}') is not supported by the Agent 365 CLI. Choose a supported region and ensure your web app name ('{webAppName}') is globally unique

了解更多關於組態檔案結構的資訊

驗證組態

請使用a365 config display顯示你的設定指令來驗證所有值是否正確：

a365 config display

步驟 2：建立代理人藍圖

這個指令會建立 Azure 資源並註冊你的代理藍圖。a365 setup 藍圖定義了您的代理人身份、權限及基礎設施需求。 此步驟為部署與執行 Azure 代理奠定基礎。

執行安裝程式

執行 命令：

a365 setup

設定過程執行以下操作：

1. 建立 Azure 基礎設施（如果還不存在的話）：

   • 資源群組
   • 指定 SKU 的 App Service Plan
   • Azure Web App with managed identity enabled

2. 登記代理人藍圖：

   • 在您的 Microsoft Entra 租戶中建立代理藍圖
   • 建立 Microsoft Entra 應用程式註冊。
   • 配置代理身份並取得必要的權限

3. 設定 API 權限

   • 設定 Microsoft Graph API 範圍
   • 設定訊息機器人 API 權限
   • 對代理實例套用可繼承的權限

4. 更新設定檔

   • 儲存產生的 ID 與端點至 a365.generated.config.json
   • 紀錄管理身份與資源資訊

驗證設定

設定成功完成後，你會看到一個包含所有完成步驟的摘要。 驗證已建立的資源：

1. 檢視產生的配置：

   a365 config display -g
   

   確認這些數值存在：

   • agentBlueprintId - 你的探員藍圖申請ID
   • agentBlueprintObjectId - Blueprint 的 Microsoft Entra ID
   • managedIdentityPrincipalId - 系統指派的管理身份主體識別碼

2. Review Azure Portal 中的 Azure 資源：

   確認下列 Azure 資源已建立。

   • 資源群組

     • 移至資源群組，並選取所需的資源群組。
     • 確認它包含你的 App Service Plan 和 Web App。

   • App Service 方案

     • 前往 App Services>App Service Plans
     • 找到你的方案，確認價格層級是否符合你的配置 SKU

   • Web 應用程式

     • 前往 App Services>網頁應用程式
     • 找到你的網頁應用程式，然後進入設定>身份系統>
     • 驗證狀態為 開啟
     • 注意物件（主體）ID相符 managedIdentityPrincipalId

3. Verify Microsoft Entra applications in Azure Portal：

   前往 Azure Active Directory應用程式註冊。

   • 透過搜尋您的代理人藍圖 agentBlueprintId
   • 打開應用程式並選擇 API 權限
   • 驗證權限以綠色勾勾標示：
     • 依序選取 [Microsoft Graph] 和 [應用程式權限]。
     • 訊息機器人 API 權限
   • 所有權限都應該顯示 「已授予[您的租戶]」

步驟 3：建立 執行個體。

此指令會a365 create-instance為你的代理藍圖建立代理應用程式 ID 和代理使用者，啟用認證與權限。 這會建立一個擁有自身身份與憑證的特定代理實例，使其能在 Microsoft 365 環境中進行驗證與運作。

建立執行個體

執行以下命令：

a365 create-instance

它的用途：

1. 為此代理實例建立代理應用程式 ID - Microsoft Entra ID
2. 建立代理使用者 - 代理實例的服務主體
3. 使用 agent blueprint ID - 來自產生的設定 （a365.generated.config.json）
4. 授予管理員同意 - 自動套用從藍圖繼承的權限
5. 更新設定 - 將新的代理憑證儲存到本地環境

預期的輸出

您將看到每個階段的進度訊息：

• 第一階段：建立代理身份與代理使用者
• 管理員同意請求（瀏覽器視窗將開啟）
• 第二階段：授權
• 組態更新

驗證實例

1. 檢視產生的配置：

   a365 config display -g
   

   確認下列檔案存在：

   • AgenticAppId - 您的代理實例應用程式識別碼
   • AgenticUserId - 你的代理人使用者識別碼

2. Validate in Azure Portal：

   • 前往 Azure Active Directory>應用程式註冊。
   • 找到你的代理應用程式 ID（查看已產生的 ID 設定）
   • 驗證 API 權限已授予並獲得同意

後續步驟

您的代理人身份現在已註冊並準備好。 下一步：

1. 新增工具功能 - 啟用 Microsoft 365 工具（建議用於驗證測試）
2. 測試您的代理 程式 - 使用 Agent Playground 驗證