建立 Agent 執行個體

發佈 Agent 並使其在 Microsoft 系統管理中心中可用後，您就可以建立 Agent 執行個體與 Agent 使用者。 這些執行個體與使用者會使用您建立的 Agent 藍圖與 Agent 程式碼。

本文將此程序分為三個主要步驟：

  1. 在 Teams 開發人員入口網站中設定 Agent
  2. 建立 Agent 執行個體
  3. 測試已部署的 Agent

如果遇到問題，請參閱疑難排解一節。

先決條件

1. 在 Teams 開發人員入口網站中設定 Agent

發佈後，請在 Teams 開發人員入口網站中設定 Agent 藍圖，將您的 Agent 連線至 Microsoft 365 訊息收發基礎結構。 若未完成此設定，您的 Agent 將無法從 Teams、電子郵件或其他 Microsoft 365 服務接收訊息。

  1. 取得您的藍圖 ID

    在工作目錄中開啟 a365.generated.config.json，然後複製 agentBlueprintId 值。

  2. 前往開發人員入口網站

    開啟瀏覽器並前往設定頁面：

    https://dev.teams.microsoft.com/tools/agent-blueprint/<your-blueprint-id>/configuration

    將<your-blueprint-id>取代為您複製的 agentBlueprintId 值。

    注意

    如果您無法存取開發人員入口網站，請聯絡您的租用戶系統管理員，請他們授予您存取權，或代您完成此設定。

  3. 設定 Agent

    在開發人員入口網站中：

    1. 將 Agent 類型設為 API Based

    2. 將通知 URL 設為您 Agent 的訊息收發端點。 在 a365.generated.config.json 中找出 messagingEndpoint 值。

    3. 選取儲存。

    螢幕擷取畫面顯示開發人員入口網站設定頁面，其中 Agent 類型設為 API Based，並顯示通知 URL 欄位。

您必須先完成此設定，才能在 Teams 中建立 Agent 執行個體。

深入了解 Agent 身分識別藍圖與開發人員入口網站設定。

2. 建立 Agent 執行個體

現在您可以從 Teams 要求 Agent 藍圖的執行個體。 深入了解如何探索、建立及加入 Agent。

當您要求 Agent 執行個體時，Teams 會將要求傳送給您的租用戶系統管理員以供核准。 系統管理員可以從 Microsoft 系統管理中心 - 要求的 Agent 頁面檢閱並核准要求。

系統管理員核准您的要求後，Teams 會建立您的 Agent 執行個體，並使其在 Teams 中可用。

3. 測試已部署的 Agent

建立 Agent 執行個體後，請在 Microsoft 365 中測試，確保其在正式環境中能正常運作。

部署完成後，若已在 Agent 365 SDK 中啟用 Agent 通知，您的 Agent 就會與 Microsoft 365 服務整合。 它可與 Teams 搭配運作，用於交談、通道及會議；與電子郵件及行事曆搭配運作，用於傳送、接收及排程；並與 SharePoint 及 OneDrive 搭配運作，用於文件存取及檔案共用。 它也支援組織狀態、Planner 工作、文件註解等共同作業功能。

重要

如同一般使用者，Agent 使用者也需要適當的 Microsoft 365 授權才能存取服務。 常見的授權包括 Microsoft 365 E5、Teams Enterprise 和 Microsoft 365 Copilot。

在系統管理中心檢視已部署的 Agent

發佈 Agent 後，它會顯示在 Microsoft 系統管理中心中以供聘用。 可能需要一段時間才能完成傳播。

前往 Microsoft 365 系統管理中心 - Agent，執行下列作業：

  • 檢視您已發佈的 Agent
  • 管理 Agent 設定
  • 監視 Agent 使用量
  • 設定權限

在 Teams 中測試 Agent

部署、發佈並設定您的 Agent 藍圖，並建立 Agent 使用者後，請直接在 Microsoft Teams 中測試該 Agent 使用者：

開始測試

  1. 在 Teams 中搜尋您的新 Agent 使用者。

    注意

    Agent 使用者的建立程序是非同步的。 建立 Agent 使用者後，可能需要幾分鐘到幾小時的時間，該使用者才能被搜尋到。

  2. 與您新建立的 Agent 執行個體開始新的交談。

  3. 傳送測試訊息以驗證 Agent 功能。

測試訊息範例

如果您已為 Agent 設定電子郵件，請傳送此訊息以測試電子郵件功能。 更新收件者的 recipient@contoso.com 電子郵件值。

Send an email to <recipient@contoso.com> with subject "Hello from Teams" and message "This is a test message from my agent!"

Agent 會處理要求並傳送電子郵件，不需要進一步確認。

驗證檢查清單

建立 Agent 執行個體後，請驗證其在 Teams 中是否正常運作。

✅ 開發人員入口網站設定已儲存
✅ Agent 顯示在 Teams 應用程式搜尋結果中
✅ 您可以在 Teams 中建立 Agent 執行個體
✅ Agent 執行個體已建立
✅ Agent 使用者顯示在組織中
✅ Agent 會回應訊息
✅ Agent 可以執行動作
✅ 應用程式記錄未顯示任何錯誤
✅ 系統管理中心中的可觀察性正常運作

如果您的 Agent 執行個體未如預期運作，請參閱疑難排解一節，取得常見問題的詳細解決方案。

驗證開發人員入口網站設定已儲存

前往：https://dev.teams.microsoft.com/tools/agent-blueprint/<your-blueprint-id>/configuration

✅ Agent 類型顯示：API Based✅ 通知 URL 與您 Agent 的訊息收發端點相符✅顯示已成功儲存訊息

驗證 Agent 顯示在 Teams 中

  1. 開啟 Teams> 應用程式

  2. 搜尋您的 Agent 名稱

    ✅Agent 顯示在搜尋結果中✅顯示您的 Agent 圖示與描述

驗證您可以在 Teams 中建立 Agent 執行個體

在 Teams 應用程式中選取您的 Agent

✅ 要求執行個體/建立執行個體按鈕已啟用✅可順利要求執行個體，不會發生錯誤

驗證 Agent 執行個體已建立

選取要求執行個體後：

✅要求已成功傳送給系統管理員

驗證 Agent 使用者顯示在組織中

在 Microsoft 365 系統管理中心中：

  1. 前往： https://admin.cloud.microsoft/#/agents/all
  2. 前往所有 Agent 底下的要求索引標籤

✅您的 Agent 執行個體要求會列出，狀態顯示為等待審查✅系統管理員可以核准該 Agent 執行個體供使用✅使用者可以從 Teams 建立執行個體，並為其命名。

驗證 Agent 會回應訊息

在 Teams 與您的 Agent 交談中，傳送測試訊息：Hello!

✅Agent 顯示輸入指示器✅ Agent 會在幾秒內回應✅回應內容連貫且相關

驗證 Agent 可以執行動作

如果您已設定工具，請測試工具功能。 例如，如果您新增了 Mail MCP 伺服器，請傳送一封測試電子郵件給自己。

Agent 應：

✅確認收到要求✅執行工具呼叫✅確認已成功完成

您應該驗證電子郵件是否已送達您的收件匣。

確認正常運作

下列檢查清單提供有系統的方式來測試您的 Agent：

基本功能：

✅Agent 會回應簡單的問候。 ✅Agent 可以處理多步驟交談。 ✅Agent 會提供相關的回應。

工具功能：

視 MCP 伺服器設定而定

✅可以傳送電子郵件。 ✅可以存取行事曆。 ✅可以搜尋文件。 ✅可以執行已設定的動作。

錯誤處理：

✅可以妥善處理無效的要求。 ✅會提供有幫助的錯誤訊息。 ✅遇到未預期的輸入不會當機。

效能：

✅會在幾秒內回應。 ✅沒有逾時錯誤。 ✅回應時間一致。

驗證應用程式記錄

若要查看您的 Agent 目前的動作，請使用 az webapp log tail 命令檢查應用程式記錄。

# Real-time logs from Azure
az webapp log tail --name <your-web-app> --resource-group <your-resource-group>

記錄中要查看的項目：

✅來自 Teams 的傳入要求✅驗證成功✅正在執行的工具呼叫✅已傳送的回應❌錯誤訊息或例外狀況

驗證系統管理中心中的可觀察性

您的 Agent 開始執行後：

  1. 移至: https://admin.cloud.microsoft/#/agents/all。

  2. 選取您的 Agent，然後開啟活動索引標籤。

    您應該會看到：

    ✅ 工作階段已顯示。 ✅每個工作階段都會顯示觸發程序與動作。 ✅工具呼叫會與時間戳記一併記錄。

後續步驟

您的 Agent 現在已在雲端上線，可以在 Microsoft 365 中與您的團隊一起運作。 原本只是本機程式碼的內容，現在已成為經過登錄、可供企業使用的小幫手，讓使用者能在您的組織中建立 Agent 執行個體。

您 Agent 的開發生命週期已經完成，但其影響才正要開始。 您在 Agent 365 開發人員生命週期中建置的許多內容都是開放原始碼，歡迎社群貢獻。 提出錯誤回報、功能要求和提取要求：

  • Agent 365 Samples：您有有趣好玩的範例 Agent 嗎？ 在這裡與開放原始碼社群分享您的 Agent 程式碼！
  • Node.js SDK：適用於 Node.js 的 Agent 365 SDK。
  • Python SDK：適用於 Python 的 Agent 365 SDK。
  • .NET SDK：適用於 C# (.NET) 的 Agent 365 SDK。
  • Agent 365 DevTools CLI：協助您完成整個 Agent 365 開發生命週期的 CLI。

疑難排解​​

本節包含建立和測試 Agent 執行個體時的常見問題。

提示

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

Agent 未顯示在 Teams 中

徵狀：Agent 顯示在系統管理中心中，但您在 Teams 應用程式中找不到它。

根本原因：缺少開發人員入口網站設定。

解決方案：

  1. 從 a365.generated.config.json 取得您的藍圖 ID—尋找 agentBlueprintId。

  2. 在開發人員入口網站中設定：

    1. 前往： https://dev.teams.microsoft.com/tools/agent-blueprint/<your-blueprint-id>/configuration

    2. 將 Agent 類型設為 API Based

    3. 將通知 URL 設為您 Agent 的訊息收發端點。 在 a365.generated.config.json 中找出 messagingEndpoint 值。

    4. 選取儲存。

  3. 等待 5 至 10 分鐘以完成傳播。

驗證：

  • 開啟 Teams> 應用程式>搜尋您的 Agent。
  • Agent 隨即顯示，且可供新增。

無法在 Teams 中建立 Agent 執行個體

徵狀：Agent 顯示在 Teams 中，但您無法新增或建立執行個體；要求執行個體按鈕沒有作用。

根本原因：租用戶未啟用 Microsoft Agent 365 Frontier。

解決方法：請聯絡您的租用戶系統管理員，確認租用戶已啟用 Microsoft Agent 365 Frontier。

深入了解 Frontier。

驗證：

只要您的授權與系統管理設定允許，Frontier 功能就會顯示在 Microsoft 365 Copilot 及 Microsoft 365 應用程式中。

Agent 不會回應訊息

徵狀：您建立了 Agent 執行個體，但它不會回應訊息。 應用程式中看不到任何記錄。

根本原因：可能有多種原因，例如訊息收發端點問題、驗證問題或設定錯誤。

基本疑難排解

  1. 驗證 Web App 是否正在執行：

    az webapp show --name <your-app-name> --resource-group <your-resource-group> --query state
# Should be: "Running"

  2. 檢查訊息收發端點：

    • 應該是：https://<your-app-root-url>/api/messages
    • 在 a365.config.json 和 a365.generated.config.json 中驗證此項目

  3. 直接測試端點：

    curl https://<your-app-root-url>/api/messages
# Should not return 404

  4. 檢查應用程式記錄：

    az webapp log tail --name <your-app-name> --resource-group <your-resource-group>
# Look for incoming requests and errors

進階診斷

  1. 確認驗證：

    • 檢查權杖是否已過期。 如有需要，請更新權杖。
    • 在 Web App 設定中驗證認證資料。

  2. 檢查工具/MCP 設定：

    • 驗證 MCP 伺服器是否已設定。
    • 檢查是否已授與權限。

  3. 在本機測試：

    • 使用相同的設定在本機執行 Agent。
    • 使用 Agents Playground 測試。
    • 如果在本機可以運作，但在雲端無法運作>部署問題

常見的解決方案

  • 訊息收發端點不正確：請在 Azure 入口網站和開發人員入口網站中更新。
  • Web App 已停止：請使用 Azure 入口網站或 CLI 啟動。
  • 權杖已過期：請在 Web App 環境變數中更新權杖。
  • 缺少環境變數：請檢查 Azure 入口網站中的應用程式設定。
  • MCP 伺服器問題：請驗證服務主體與權限。
  • 程式碼錯誤：請檢查應用程式記錄中的例外狀況。

驗證

在 Teams 中傳送訊息給您的 Agent，並檢查應用程式記錄中的傳入要求。

您也可以嘗試：

工具呼叫失敗

徵狀：Agent 會回應訊息，但工具呼叫失敗。 您會看到權限遭拒或逾時錯誤。

根本原因：可能是缺少 MCP 伺服器權限、未設定服務主體、網路連線問題，或工具設定不正確。

方案

工具呼叫失敗時，請嘗試下列解決方法：

  • 在系統管理中心中驗證權限

    檢閱並核准所需的 MCP 伺服器權限：

    • 前往： https://admin.cloud.microsoft/#/agents/all
    • 選取您的 Agent> 權限
    • 確認清單中包含並已核准所需的 MCP 伺服器

  • 檢查服務主體

    如果您先前未執行過，請執行一次性的設定指令碼：

    # Download and run:
# https://github.com/microsoft/Agent365-devTools/blob/main/scripts/cli/Auth/New-Agent365ToolsServicePrincipalProdPublic.ps1

  • 驗證 MCP 端點設定

    確認您使用的是正式環境的 MCP 端點：

    # Should be production endpoint, not mock
MCP_PLATFORM_ENDPOINT=https://agent365.svc.cloud.microsoft

  • 檢查受控識別

    驗證您的 Web App 是否已啟用受控識別：

    # Verify managed identity is enabled
az webapp identity show --name <your-app-name> --resource-group <your-resource-group>

驗證

透過 Teams 測試工具呼叫，並檢查記錄以確認執行成功。

您也可以嘗試下列步驟：

授權指派失敗

徵狀：您無法將授權指派給 Agent 使用者。 您在系統管理中心中看到授權錯誤。

根本原因：可用授權不足、授權類型不正確，或權限問題。

方案

授權指派失敗時，請嘗試下列解決方法：

  1. 驗證是否有可用的授權：

    • 檢查 Microsoft 365 系統管理中心>帳單>授權。
    • 確認租用戶已啟用 Microsoft Agent 365 Frontier。

  2. 手動指派授權：

    • 前往 Microsoft 365 系統管理中心>使用者。
    • 找到該 Agent 使用者。
    • 指派適當的授權。

  3. 完整功能所需的授權：

    • Microsoft 365 E5 (或同等項目)。
    • Teams Enterprise。
    • Microsoft 365 Copilot (適用於 Copilot 功能)。

驗證

檢查系統管理中心中的使用者設定檔是否顯示已指派的授權。

  • Last updated on