使用 Dev Tunnels 測試 Agent

使用 Dev Tunnels，您可以在 Agent 於開發電腦上本機執行的同時，搭配 Microsoft 365 應用程式 (例如 Teams、Outlook 或 Word) 測試您的 Agent 365 Agent。 此做法可銜接本機開發與實際測試，讓您在部署到雲端之前，於實際的 Microsoft 365 環境中驗證 Agent 行為。

先決條件

使用 Dev Tunnels 之前，請務必先安裝 Dev Tunnels 命令列工具。

設定 Dev Tunnel

設定 Dev Tunnel，將您的本機 Agent 端點公開給 Microsoft 365 服務。

建立並啟動通道

  1. 登入 Dev Tunnel：

    devtunnel user login

  2. 建立持續性通道：

    devtunnel create --allow-anonymous

    此命令會傳回通道 ID。 請保留此識別碼，以供日後使用。

  3. 設定通道連接埠：

    指派 Agent 伺服器所使用的連接埠 (通常為 3978)：

    devtunnel port create <tunnel-id> -p <port-number>

  4. 啟動通道：

    devtunnel host <tunnel-id>

    此命令會顯示您的通道 URL (例如 https://abc123xyz.devtunnels.ms:3978)。 請複製此 URL，供下一個步驟使用。

提示

使用 devtunnel list 可檢視所有通道，使用 devtunnel delete <tunnel-id> 則可移除不再需要的通道。

設定 Agent 訊息端點

將您的 Dev Tunnel URL (例如 https://abc123xyz.devtunnels.ms:3978/api/messages) 註冊為 Agent 訊息端點，以便 Microsoft 365 知道要將訊息傳送到哪裡。 請勿忘記在端點後方加上 /api/messages 尾碼。

請參閱設定 Agent 訊息端點

使用 Microsoft 365 測試

在 Dev Tunnel 為使用中狀態且已註冊端點後，即可在 Microsoft 365 應用程式中測試您的 Agent。

在 Microsoft Teams 中測試

  1. 依照安裝相依項並啟動 Agent 應用程式伺服器中的指示，啟動您的本機 Agent。

  2. 驗證通道連線能力：

    devtunnel list

    檢查您的通道是否顯示為使用中的主機連線。 「主機連線」欄應顯示大於 0 的數字。

  3. 在 Teams 中與您的 Agent 互動：

    • 開啟 Microsoft Teams (網頁版或桌面版)
    • 在 Teams 搜尋列中，依名稱或電子郵件搜尋您的 Agent
    • 與該 Agent 開始交談
    • 傳送訊息並觀察回應
    • 檢查本機主控台，查看傳入要求和 Agent 活動

測試電子郵件通知

若您的 Agent 已設定電子郵件通知：

  1. 傳送電子郵件至您 Agent 的電子郵件地址
  2. 在電子郵件討論串中副本 (CC) 給您的 Agent
  3. 監控本機主控台，查看通知 Webhook
  4. 驗證您的 Agent 是否已處理電子郵件並做出回應

測試 Word 整合

適用於會回應 Word 註解的 Agent：

  1. 開啟您 Agent 具有存取權的 Word 文件。
  2. 新增提及您 Agent 的註解。
  3. 檢查本機主控台，查看通知。
  4. 驗證您 Agent 的回應是否已顯示在 Word 中。

監控通道活動

Dev Tunnels 提供流量檢查功能，協助偵錯連線問題並了解要求流程：

devtunnel show <tunnel-id>

此命令會顯示：

  • 使用中的連線和工作階段詳細資料。
  • 要求與回應資訊。
  • 流量統計資料。
  • 連線錯誤和警告。

您也可以觀察 devtunnel host 命令的輸出，即時監控通道活動。

維持通道連線

Dev Tunnels 需要讓 devtunnel host 處理程序持續執行。 若因閒置、網路問題或電腦進入睡眠狀態而導致連線中斷，您必須重新啟動連線。

檢查通道狀態

驗證您的通道是否為使用中狀態：

devtunnel list

輸出會顯示：

  • 通道 ID：您的通道識別碼
  • 主機連線：使用中的連線數量 (devtunnel host 執行時應為 1 或以上)
  • 連接埠：已設定的連接埠
  • 到期：通道到期時間

若主機連線顯示為 0，表示通道仍存在，但目前並未進行主控。

重新啟動已中斷連線的通道

若通道連線中斷，請使用相同的通道 ID 重新啟動：

devtunnel host <tunnel-id>

通道 URL 會保持不變，因此您不需要更新 Agent 訊息端點設定。

在開發期間保持通道為使用中狀態

若要維持穩定的連線：

  • 保持終端機視窗開啟 - 請勿關閉正在執行 devtunnel host 的終端機。
  • 避免電腦進入睡眠 - 請設定系統，使其在測試工作階段期間保持喚醒狀態。
  • 留意連線錯誤 - 監控 devtunnel host 終端機輸出，查看是否有中斷連線訊息。
  • 網路變更後請重新啟動 - 若您切換網路或重新連線至 VPN，請重新啟動通道。

提示

若您的通道經常中斷連線，請檢查網路設定和防火牆規則，確認未封鎖連線。

清理

使用 Dev Tunnels 完成測試後：

停止通道

在執行 devtunnel host 的終端機中按 Ctrl+C，即可停止通道。

此命令會從您 Agent 的訊息端點中移除 Dev Tunnel URL。 部署至正式環境時，請設定雲端裝載的端點 URL。

注意

除非您使用 devtunnel delete <tunnel-id> 明確刪除通道，否則通道會持續可供日後使用。

限制

使用 Dev Tunnels 測試時，請考慮下列限制：

  • 僅限開發用途：請將 Dev Tunnels 用於開發與測試，而非正式環境。
  • 效能：由於網路路由的關係，延遲會高於雲端裝載的 Agent。
  • 連線穩定性：通道連線可能偶爾中斷，需要手動重新啟動。
  • 安全性考量：--allow-anonymous 旗標便於測試，但請勿搭配敏感性資料使用。
  • 工作階段管理：視工作階段持續時間而定，您可能需要定期重新驗證。

後續步驟

Dev Tunnel 測試成功後：

疑難排解​​

若您在透過 Dev Tunnels 測試時遇到問題，請從這裡開始，了解常見的通道、連線和端點修正方式。 如需更廣泛的 Agent 365 疑難排解 (設定、驗證和訊息)，請參閱疑難排解。

通道連線失敗

徵狀：Dev Tunnel 無法啟動，或立即中斷連線。

解決方案：

  • 驗證您已登入：devtunnel user login
  • 檢查是否有其他處理程序正在使用相同的連接埠
  • 確認防火牆允許 Dev Tunnel 連線
  • 刪除並重新建立通道：devtunnel delete <tunnel-id>，然後建立新的通道

訊息未送達本機 Agent

徵狀：Microsoft 365 顯示訊息已傳送，但您的本機 Agent 並未收到。

解決方案：

  • 確認您的 Agent 正在本機執行
  • 驗證通道是否為使用中狀態：devtunnel list 應顯示為「已連線」
  • 檢查 a365.config.json 中的端點設定，並確認您的 Dev Tunnel URL 已設為訊息端點
  • 在執行 devtunnel host 的終端機中檢閱 Dev Tunnel 記錄，查看是否有連線錯誤
  • 確認本機連接埠與通道連接埠相符 (依預設，兩者皆應為 3978)

透過 Dev Tunnel 發生驗證錯誤

徵狀：透過 Dev Tunnel 測試時發生 401 或 403 錯誤。

解決方案：

  • 驗證是否已設定 Agent 式驗證 (持有人權杖驗證不適用於 Dev Tunnels 的 Microsoft 365 整合)。
  • 檢查 a365.generated.config.json 中的 Agent 藍圖認證。
  • 確認您的 Agent 具備您所測試作業的必要權限。
  • 確認您的驗證權杖尚未過期。

通道 URL 已變更或過期

徵狀：先前可正常運作的通道 URL，現在已無法路由至您的 Agent。

解決方案：

  • 使用 devtunnel list 檢查通道狀態。
  • 使用 devtunnel host <tunnel-id> 重新啟動通道。
  • 若 URL 已變更，請使用 a365 setup blueprint --endpoint-only 更新訊息端點。
  • Last updated on