測試、部署與整合代理

  • 9 分鐘

小提示

有關更多詳細信息，請參閱 文本和圖像 選項卡！

測試、部署與發布代理程式是從開發到生產的關鍵步驟。 Microsoft Foundry 提供全面的功能，用於驗證代理行為、部署至您的 Foundry 專案，並將代理作為可呼叫端點發佈，供外部消費者與應用程式使用。

代理人的測試策略

徹底測試能確保您的代理程序在多種情境下可靠運作，然後才面向用戶。 Foundry 入口網站與 Visual Studio Code 擴充功能皆提供互動測試的遊樂場。

有效利用遊樂場：

  • Happy Path 測試 - 確認代理程式正確處理常見且預期的請求。
  • 邊緣案例測試 ——嘗試模糊輸入、不完整資訊及異常請求，以揭示代理人如何處理不確定性。
  • 邊界測試 - 透過測試範圍外的請求，確認代理遵守其指令中定義的邊界。
  • 多回合對話測試 ——驗證代理在多個交換中維持上下文，並建立在先前回應之上。
  • 工具調用測試 ——確認代理人員在正確的時間呼叫正確的工具，並正確整合結果。

記錄測試結果以追蹤改善並捕捉回歸現象。

把代理程式部署於你的專案

Microsoft Foundry 支援從入口網站或 Visual Studio Code 部署代理程式。 部署會將你的代理設定存到 Foundry 專案，方便你測試和迭代。

從 Foundry 入口部署

  1. 在 Foundry Portal 中導覽到您的代理程式
  2. 驗證配置與測試結果是否令人滿意
  3. 從代理人頁面選擇儲存
  4. 確認版本與部署設定

從 Visual Studio Code 部署

  1. 在 AI 工具包中開啟你的代理
  2. 選擇 「儲存至 Foundry 」以推送設定變更
  3. 對於託管代理，請在開發者工具中開啟 +Build 選單，選擇 部署至 Microsoft Foundry
  4. 選擇你的容器設定並確認

這兩種方法都能讓你的代理程式留在專案工作空間內，讓團隊成員能夠存取並測試。

將代理發佈至端點

發佈會將代理從你的專案工作區移到一個稱為 代理應用程式的管理 Azure 資源中。 這個步驟使你的代理能透過穩定的終端機外部呼叫。

出版所創造的

當你發布代理版本時，Foundry 會建立：

  • 代理應用程式 - 一個具有自身調用 URL、認證政策及 Entra 代理身份的 Azure 資源。
  • 部署 - 應用程式內特定代理版本的執行實例，具備生命週期的開始/停止管理。

部署與發布的主要差異在於範圍。 部署能讓代理留在您的專案中。 發佈會建立一個專用的端點，讓外部使用者無需存取你的 Foundry 專案即可進行呼叫。

從 Foundry 入口網站發佈

  1. 在入口網站中，選擇你想發佈的代理版本
  2. 選擇 發佈 以建立代理應用程式與部署

從 Visual Studio Code 發佈

  1. 打開指令面板（Ctrl+Shift+P），執行 Microsoft Foundry：部署 Hosted Agents 以部署託管代理程式
  2. 選擇目標工作區與容器配置
  3. 確認並部署

發佈後，代理會出現在 AI 工具包擴充樹檢視的 託管代理（預覽） 區塊中。

代理應用程式端點

已發佈的代理程式使用 Responses API 協定來公開穩定端點：

https://<foundry-resource-name>.services.ai.azure.com/api/projects/<project-name>/applications/<app-name>/protocols/openai/responses

即使你推出新的代理版本，這個網址也會保持不變，讓下游消費者不會被更新打斷。

驗證和身分識別

代理應用程式使用 Microsoft Entra ID 進行認證。 來電者必須在代理應用程式資源中擁有 Azure AI 使用者 角色。 API 金鑰驗證不支援代理應用程式。

這很重要

當您發佈 Agent 時，它會收到自己的專用 Entra 身分識別，與專案的共用身分識別分開。 權限不會自動轉移。 對於 Agent 存取的任何資源，您都必須將 RBAC 角色重新指派給新的 Agent 身分識別。 如果你跳過這個步驟，開發期間的工具呼叫會在代理程式發佈後因授權錯誤而失敗。

驗證端點

發佈後，請驗證端點正常運作：

  1. 取得存取權杖：

    az account get-access-token --resource https://ai.azure.com

  2. 呼叫代理應用程式端點：

    curl -X POST \
  "https://<foundry-resource-name>.services.ai.azure.com/api/projects/<project-name>/applications/<app-name>/protocols/openai/responses?api-version=2025-11-15-preview" \
  -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json" \
  -d '{"input":"Say hello"}'

如果你收到 403 Forbidden，請確認來電者在代理應用程式資源中擁有 Azure AI 使用者 角色。

更新已發佈代理

若要推出新的 Agent 版本：

  1. 對開發環境進行修改並徹底測試
  2. 在 Foundry 入口網站中，選擇從代理試驗區發佈更新
  3. 代理應用程式會自動將 100% 流量導向新版本

端點網址保持不變，因此現有的整合仍能正常運作。

產生整合碼

Microsoft Foundry VS Code 擴充功能會產生範例整合程式碼，將您的應用程式連接到已發佈的代理程式：

  1. 在「我的資源」檢視中選擇已部署的代理
  2. 選擇 檢視代碼
  3. 選擇你的資料夾
  4. 擴充功能產生用於驗證、連線、傳送訊息及處理回應的程式碼

整合模式

整合已發表代理人的常見模式包括：

  • 網頁應用程式 - 將使用者訊息傳送到 Responses API 端點，並在你的 UI 中顯示回應。 將對話紀錄儲存在客戶端，方便多回合互動。
  • API 驅動的工作流程 - 從由事件或排程觸發的後端服務呼叫 Agent 端點。 程式化處理回應以驅動下游行動。
  • 聊天機器人介面 - 將使用者會話映射到對話。 透過端點處理即時訊息交換。
  • 背景自動化 - 排程代理人撥打電話以執行重複任務。 將系統資料輸入代理並處理輸出以更新業務系統。

生產考量

在生產環境中運行代理程式需要關注多個操作領域：

  • 監控 - 利用 Application Insights 整合追蹤回應時間、工具調用成功率、錯誤模式及令牌消耗情況。
  • 安全性 - 使用受管理身份進行驗證，套用最低權限存取，並定義資料保留政策。
  • 成本管理 - 監控代幣使用情況，設定回應長度限制，並實施速率限制以防止意外激增。
  • 錯誤處理 - 實作帶有指數回退的重試邏輯以處理暫態故障。 用退讓策略來處理速率限制。 在傳送給代理前，先驗證輸入。
  • 對話管理 - 代理應用程式端點目前僅支援無狀態回應 API。 在客戶端儲存對話紀錄，方便多回合體驗。