使用 Microsoft Foundry Toolkit for Visual Studio Code 建立託管代理程式

使用 Microsoft Foundry Toolkit for Visual Studio Code，根據 Microsoft Agent Framework 範例建立基於程式碼的工作流程。 先用 Agent Inspector 在本地執行，然後將其原始碼部署到 Foundry Agent Service，作為託管代理。 你維護程式碼及其相依關係。 Foundry 負責管理主機架構與擴展。

託管工作流程在程式碼中協調代理。 它們與即將退役的 Foundry 宣告式工作流程服務不同。 關於其他建立路由，請參見 「建立代理人」。

先決條件

  • 安裝 Microsoft Foundry Toolkit for Visual Studio Code。

  • 選擇一個 Foundry 專案，其中具有已部署的模型。 使用 支援的主機代理區域。

  • 使用模型並部署託管代理的權限。 對於原始程式碼部署，在專案範圍內，Foundry Project Manager 角色包含代理程式操作和角色指派權限。 請參閱 託管代理權限。

    這很重要

    Foundry RBAC 角色最近已重新命名。 Foundry 用戶、Foundry 擁有者、Foundry Account Owner 以及 Foundry Project Manager 先前分別被稱為 Azure AI 使用者、Azure AI 擁有者、Azure AI 帳戶擁有者及 Azure AI Project 管理者。 在更名期間，你可能還會在某些地方看到之前的名字。角色 ID 與核心權限不會因命名而改變。

  • 如需完成本文中的本機驗證步驟，請使用 Azure CLI。

  • 若要部署容器，需具備 Azure Container Registry 設定 所需的登錄和映像存取權限。 這些登錄檔要求不適用於原始碼部署。

  • 範例已設定的託管執行階段為 Python 3.13。
  • Python 擴展 用於 Visual Studio Code。

主要部署路徑使用 Code 並以 遠端 套件模式進行，且不需要本地 Docker 編譯。 本地執行仍會將模型請求傳送至 Foundry，並可能產生費用。 請檢視您所使用的 功能的服務限制與可用性 ，以及 Toolkit 的發布說明 。

建立託管代理工作流程

選擇使用 Responses 協定的 Agent Framework 範例。 你不需要先建立獨立的提示代理。 要比較範例、代理建構器與 Copilot 輔助編碼，請參閱「選擇創建路徑」。

使用 多代理工作流程（代理框架），它連結了寫手、審查者和格式化者。 最後的回應來自格式化者。 請參閱 Python 工作流程範例以了解完整實作及其模型指引。

使用 翻譯工作流程，它連結三個翻譯代理：英文轉法文、法文轉西班牙文，以及西班牙文轉英文。 請參考 C# 工作流程範例 以完整實作。

  1. 在 Foundry 工具包檢視中，選擇開發工具>建構>建立代理。

  2. 在「根據範例為代理程式編寫程式碼」下，選取「瀏覽所有範例」。

  3. 在 「從範例建立託管代理」中，依照你的 語言、 框架 = 代理框架和 協定類型 = 回應來篩選。 搜尋 workflow。

    以下截圖顯示選取 Basic Hosted Agent 作為範例的圖庫。 在此指南中，請選擇你語言的工作流程範例。

    已選取基本託管代理的範例圖庫截圖，包含工作流程範例，以及語言、框架和協定過濾器。

  4. 選擇你語言的工作流程範例。

  5. 選取 下一步。

  6. 在 建立 中，選擇 工作區資料夾。 如果資料夾已經包含檔案，請輸入資料夾 名稱 以建立新的子資料夾。

  7. 如果出現環境設定，請選擇使用 Microsoft Foundry 設定，然後選擇你的訂閱和專案。 當預設專案已被選中時，表單會使用該專案。

  8. 選擇現有且相容的 模型部署。

    以下截圖展示了隱藏本地路徑的專案範例設定。 使用您自己的目的地，以及您範例所需的模型部署。

    Create 標籤的截圖，顯示工作區資料夾、資料夾名稱、模型部署和 Create 控制項，並隱藏本地路徑。

  9. 檢視目的地，然後選擇 建立。

  10. 在 Visual Studio Code 中開啟產生的專案並閱讀其 README.md。

Create Agent 上的 Agent Framework、Copilot SDK 和 LangGraph 圖塊會開啟 Create 索引標籤，並預先選取 hello-world 入門範本。 用 「瀏覽所有樣本 」來選擇工作流程，而不是選擇其中一個起始流程。 你也可以從 我的資源>代理程式>託管代理程式>新增託管代理程式 開啟資源庫。

範例名稱與內容可能會隨目錄變更。 有些版本將這些範例標示 為工作流程。 請使用範例的 GitHub 連結確認你已選擇預期的工作流程。

目前 Skip 會在未完成模型設定前產生程式碼。 如果你選擇了它，請在執行樣本前先設定所需的專案和模型數值。 如果提供部署並使用新模型選項，則會佈建模型部署，而非託管代理。 建立本地專案檔案並不會部署代理程式。

設定本地專案

將包含 azure.yaml 的資料夾保持開啟，作為工作區根資料夾。 檢查該檔案中託管代理服務的 project 路徑，找到其來源目錄。

成品 Purpose
azure.yaml 宣告託管代理服務、來源目錄、執行時、協定及部署設定。
main.py 或 Program.cs 在來源目錄中 實作工作流程並啟動回應伺服器。
requirements.txt 或 .csproj 檔案 宣告所選語言的相依關係。
.env 在來源目錄中 保存本機專案和模型值。 當範例提供該檔案時，工具包會根據 .env.example 建立它。
.vscode/launch.json 與 .vscode/tasks.json 設定本地伺服器、除錯器附件和代理檢查器。

範例版面可能會變動。 請使用產生的 README.md 和 azure.yaml，不要假設程式碼和環境檔案位於工作區根目錄。

安裝依賴項

使用所產生範例的相依檔案。 保持所選直譯器或 SDK 與執行時設定一致。

  1. 從指令調色盤執行 Python： Create Environment... 建立虛擬環境，或使用 Python： Select Interpreter 選擇現有的 Python 3.13 環境。 關於環境的設定與選擇，請參見 Visual Studio Code 中的 Python 環境。

  2. 開啟一個已啟用該環境的終端機。 將 變更為包含 main.py 和 requirements.txt的來源目錄。

  3. 安裝範例的套件：

    python -m pip install -r requirements.txt

    需求包括 debugpy，產生的 F5 組態會使用它。 參考資料：Python 工作流程相依性。

  1. 執行 C#：從指令面板檢查工作空間需求 。

  2. 在終端機中，變更包含該 .csproj 檔案的來源目錄並還原其套件：

    dotnet restore

    參考資料： dotnet restore。

關於除錯器的控制項與設定，請參見 Visual Studio Code 中的 C# 除錯。

設定專案與模型

請先檢視來源目錄中的 .env 檔案。 如果沒有，就用樣本所需的數值來製作。

Variable 值
FOUNDRY_PROJECT_ENDPOINT 你的專案端點，格式為 https://<resource-name>.services.ai.azure.com/api/projects/<project-name>。
AZURE_AI_MODEL_DEPLOYMENT_NAME 該專案中模型部署名稱，而不只是模型目錄名稱。

兩個工作流程範例都會在啟動時載入 .env。 專案端點並非 Azure OpenAI 帳號端點。 不要讓檔案進入原始碼控管，也不要在應用程式代碼裡放憑證。

在地認證

範例使用 DefaultAzureCredential。 對於 Azure CLI 憑證路徑，請使用一個能存取專案模型的帳號登入：

az login

參考：使用 Azure CLI 登入。

工具包登入會選擇專案進行擴充操作。 本地代理程序也需要支援的憑證。 其他選項請參考 Python 的 DefaultAzureCredential，或 .NET 的憑證鏈。

在本地執行你的託管工作流程

使用產生的除錯設定啟動 HTTP 伺服器並開啟 代理檢查器。 單純開啟 Agent Inspector 並不會啟動伺服器。

請使用這個測試請求： Create a slogan for a new electric SUV that is affordable and fun to drive. 撰寫者、審查者和格式製作者完成後，工作流程會回傳一個格式化的標語。

請使用此測試請求： The quick brown fox jumps over the lazy dog. 工作流程執行其翻譯鏈並回傳回應。

  1. 返回已產生的專案工作區。
  2. 如果你想檢查執行，可以在工作流程程式碼中設定一個中斷點。
  3. 請按 F5。 若有提示，請選擇 除錯本地代理 HTTP 伺服器。
  4. 等伺服器啟動並開啟 Agent Inspector 。
  5. 寄出你的樣本檢測申請。
  6. 檢查回應，然後重複另一個請求。 如果你設定了斷點，檢查這些值並繼續執行。

樣本完成後，修改工作流程並重複本地測試。 如果你新增工具，請發送需要真實工具結果的請求並檢查通話內容。 僅用模型回答或模擬回應，並不能證明這個即時工具有效。

截圖顯示的是支援工具的本地代理，而非任一工作流程範例。 Agent Inspector 會透過延遲瀑布圖和執行時間軸顯示其回應與工具呼叫。 可用的檢查詳細資料取決於正在執行的 Agent 及其檢測。

Agent Inspector 連線至 localhost 的 8088 連接埠時的螢幕擷圖，畫面中顯示 Responses 通訊協定、工具呼叫、延遲瀑布圖和執行時間軸。

如果你使用 GitHub Copilot，便可在 Copilot Chat 中執行 /validate-microsoft-foundry-hosted-agent，根據 Foundry 最佳做法審查專案。 此聊天指令會開啟一份報告;它不是終端機指令，也不是執行工作流程的替代品。

產生的任務會使用代理伺服器的埠 8088 。 Python 除錯也使用 port 5679. 如果啟動程式報告有埠衝突，請停止你擁有的衝突程序，或持續調整產生的任務設定。

不使用除錯器執行

若要手動執行，請在範例的來源目錄中開啟一個終端機，裡面有相依關係、環境值和 Azure 憑證。

python main.py

參考資料：Python 工作流程入口。

為本地伺服器設定 HTTP 位址，然後執行：

$env:ASPNETCORE_URLS = "http://localhost:8088"
dotnet run

參閱：ASP.NET Core 伺服器 URL和 dotnet run。

接著從指令面板執行 Foundry Toolkit： Open Agent Inspector ，並連接到埠 8088口的本地伺服器。 使用 python 或 dotnet run 執行範例時，會啟動本機程序，而不是容器。

視覺化託管代理工作流程執行

使用 Agent Inspector 來檢查你執行中的 Agent 發出的事件、回應和工具呼叫。 當執行時發出工作流程事件，請使用工作流程視覺化來檢查步驟順序。

可得的細節取決於樣本的儀器配置。 請依照範例中的遙測設定指示，以符合執行階段特定需求。

這些步驟使用回應協定。 其他範例則需要符合其協定的客戶端：HTTP Invocations 視圖並非 WebSocket 客戶端，而 Python 活動範例則使用 Microsoft 365 Agents Playground。 請依照所選樣本的在地檢測指示進行。 在設定中更改協定名稱並不會把該協定加入你的伺服器。 請參見 「選擇託管代理協定」。

部署託管代理

當本地工作流程如預期運作後，從專案工作區部署。 Python 和 C# 共享部署程序。 先用 程式碼 和 遠端 套件模式上傳原始碼，讓 Foundry 還原相依性。

準備部署配置

檢閱並儲存 azure.yaml 中的代管代理程式服務。 保留範例的協定設定，並宣告模型部署及其他必要的執行時設定。

部署會從來源目錄中的 .env 或程序環境解析已宣告的環境值。 它不會轉發所有本地 .env 資料。 平台提供保留的執行時值，例如 FOUNDRY_PROJECT_ENDPOINT;不要將它們重新宣告為部署設定。 參見 平台注入環境變數。

打包前請先檢視來源目錄的忽略規則。 請將.env、認證、虛擬環境和快取排除在套件之外。 對於 ZIP 部署，source-root .agentignore 檔案會取代 .dockerignore 和 .gitignore 中的規則，因此如果您新增該檔案，請保留必要的排除規則。

這很重要

不要提交或打包機密資訊。 本地登入不會把使用者的權限轉移給已部署的代理。 設定代理的執行時身份及支援連線的存取權限。 請參閱 託管代理權限。

以遠端封裝模式部署原始碼

使用產生的工作區根目錄，讓工具包能讀取服務設定並定位其來源目錄。

  1. 停止本地除錯會話。

  2. 選擇開發者工具>建置>部署至 Microsoft Foundry。 你也可以從指令面板執行 Foundry Toolkit: Deploy Hosted Agent。

    Foundry Toolkit 的 [開發人員工具] 區段中 [建置] 底下 [部署到 Microsoft Foundry] 的螢幕擷取畫面。

  3. 如果出現 Foundry Project Setup，請選取訂閱和專案，然後選取 下一步。 否則，請確認預設專案是預期目的地。

  4. 在 基礎模式中，選擇 「程式碼 」作為 部署方式 ，「 遠端 」作為 套件模式。

  5. 選擇 「新代理」 並輸入 託管代理名稱。 要更新已部署的代理，請選擇「 現有代理 」並選擇該代理。

    基礎程式碼截圖，包含部署程式碼、遠端套件模式及選擇新代理，代理名稱隱藏。

  6. 選取 下一步。

  7. 在 Review + Deploy 中，對照範例檢查 Language、Runtime Version、Entry Point 和 CPU and Memory。 確認來源目錄是否與服務 project 路徑相符。

    以下截圖展示了一個使用 Python 3.14 且入口點隱藏的範例，而非這些工作流程範例的設定。 對於 Python，請使用 Python 3.13 並搭配 python3 main.py。 對於 C#，請使用 .NET 10 和偵測到的輸入點來處理你產生的專案。

    Review + Deploy 的截圖，展示 Python 3.14 作為範例、隱藏入口點、CPU 與記憶體，以及 Deploy 控制項。

  8. 請選擇 部署。 在通知和 輸出中追蹤進度。

  9. 繼續 測試已部署的工作流程。

將執行時間與你的範例配置及本地環境相匹配。 不要只因為那是精靈的預設值，就接受不同的執行階段。

Toolkit 在提交表單時會儲存部署選項。 這些本地設定並不能證明雲端部署成功。 更新現有代理會建立新版本，而非更改先前的版本。

選擇其他 ZIP 套件模式

工具包提供以下原始碼打包選項：

封裝模式 會發生什麼事 準備什麼
遠端 工具包的原始碼。 Foundry 會在配置過程中還原 Python 需求或 .NET 專案。 來源、相依宣告，以及相容的入口點。
捆綁 Toolkit 會先分階段原始碼並在本地執行 Package 指令 ，然後再建立 ZIP。 Foundry 會執行已備妥的套件。 相容的 Linux 相依套件，以及該命令所需的本機工具。 預設的 Python 指令會在 packages/ 中安裝相容的相依性；.NET 指令則會建立發佈輸出內容。

可選的 ZIP 執行環境有 Python 3.13、Python 3.14 和 .NET 10。 將執行時間與你的程式碼及相依關係相匹配。 關於版面配置、限制與服務需求，請參見 從原始碼部署。 關於執行時支援政策，請參見支援的託管代理執行時。

部署容器映像

當你需要自訂執行映像檔或已經有相容映像檔時，請選擇 Container on Basics 。

登錄選擇 工具包行為
預設ACR 為所選專案建立或重用登錄檔，然後透過 Azure Container Registry（ACR）建立並推送映像檔。
自訂 ACR 它會使用你選擇的現有登錄檔，然後建立並推送映像檔到 ACR。
自訂 ACR 映像檔 使用預先建構的 ACR 映像參考，無需建置或推送原始碼。

關於建置選項，部署前請先檢視 Docker 檔案和建置上下文。 如果你在精靈中產生 Dockerfile，請檢視該檔案並選擇 繼續並部署。 這些選項使用遠端 ACR 建置，而非本地 Docker 建置。

自訂登錄檔選項會使用所選訂閱中的登錄檔。 自訂登錄檔建置路徑需要公共網路存取;預建映像路徑有獨立的私人網路需求。 選擇映像檔並不會設定網路連線。

在使用自訂登錄檔前，請先閱讀 容器需求 和 私人網路指引 。 這些部署的目標是 Foundry Agent Service，而非已淘汰的 Azure 容器應用程式 託管代理程式路徑。 若要移轉舊版代理程式，請參閱 從 hosted-agent 預覽移轉。

測試已部署的工作流程

成功的創建請求並不代表執行環境已準備好，或其模型與工具可被存取。 測試實際部署的確切版本。

  1. 在 我的資源>代理程式>託管代理程式 底下，選取代理程式名稱。
  2. 選擇你剛部署的編號版本。
  3. 在 詳細資料 中，等待部署狀態顯示代理程式正在執行。 如果失敗，請先檢查部署輸出再嘗試。
  4. 打開 Playground ，並發送你在本地測試過的同樣請求。
  5. 請審閱回應。 如果你新增了工具，請發送需要這些工具的請求並檢查通話內容。

本地與雲端執行使用不同的憑證、相依環境和網路路徑。 成功的本地回應並不保證遠端回應也成功。

檢查並更新已部署的代理程式

使用遠端測試環境來測試並檢視您已部署的代理。 與 使用 Agent Inspector 進行本機測試不同，這個測試場中的請求會傳送至 Foundry 中託管的代理。

  1. 在 Foundry Toolkit 中，選擇 「開發者工具>建構>託管代理遊樂場」。

    Foundry Toolkit 開發工具區中 Build 底下的 Hosted Agent Playground 截圖。

  2. 在 「託管代理」 下拉選單中，選擇已部署的代理程式及要檢查的版本。 開啟 Playground 發送請求並查看回應及場次細節。

    以下截圖顯示的是部署代理的回應範例，並非任一工作流程範例的預期輸出。 代理程式與會話識別碼皆被隱藏。

    遠端託管代理遊玩場的截圖，包含回應、會話細節和檢查分頁，且代理與會話識別碼隱藏。

利用這些控制項檢查並更新代理。 可用的分頁取決於其協定及相關服務。

Task Action
檢閱部署詳細資料 開啟 詳細資料 以查看狀態、設定及可複製的端點。
測試一個版本 選取編號版本以進行遊樂場要求。 自動 會依循服務端點所選擇的版本，但所選版本不一定是最新版本。 選取器不會變更其他用戶端的路由。
檢視執行時日誌 開啟 會話，選擇會話，並查看其日誌。 執行階段日誌需要工作階段；建置輸出是分開的。 停止日誌串流或取消請求並不會停止託管代理。
擷取已部署的程式碼 使用 下載程式碼資產 進行 ZIP 部署。 映像部署會公開映像參照，而非可下載的來源專案。
更新行為 編輯並測試本地程式碼，然後用現有代理重複部署程序建立新版本。

若可用，請使用 追蹤 和 評估，以進行調查與品質評估，而非僅依據單次成功回應。 請遵循 託管代理程式追蹤與 託管代理程式評估的先決條件。

部署為代理提供一個用於程式化使用的終端。 API 存取不需要另外的發佈步驟。 發佈到 Teams 或 Microsoft 365 則是另一項工作。 請參閱 目前的代理端點與發佈模型。

Troubleshooting

利用報告的錯誤和範例配置來找出失敗步驟。

癥狀 Action
本地啟動失敗是因為缺少一個套件。 確認所選直譯器或 SDK，然後從範例的來源目錄安裝相依性。
找不到專案的終點或模型。 檢查FOUNDRY_PROJECT_ENDPOINT和 AZURE_AI_MODEL_DEPLOYMENT_NAME。 不要用帳戶端點或模型目錄名稱來取代。
驗證或授權失敗。 請檢查當地的憑證和專案存取權限。 檢視 託管代理權限 以符合部署及執行時身份要求。
探員督察無法連線。 確認伺服器已啟動且 8088 埠號可用。 單純開啟 Inspector 並不會啟動伺服器。
部署失敗。 檢視部署錯誤並建立輸出。 程式碼方面，檢查執行時、入口點、套件模式，並忽略規則。 對於容器，請檢查映像和登錄庫的權限。
本地回應是正常的，但已部署的版本失敗。 將已部署的環境與身份權限與本地配置進行比較。 重新測試部署的精確版本。

清理資源

完成後停止本地除錯。 如果你不再需要已部署的測試代理，請依 照管理託管代理 移除它。

刪除代理程式會刪除其所有版本，並終止使用中的工作階段。 它不會移除所有相關的 Azure 資源。

只刪除為此練習而建立、其他應用程式不使用的雲端資源。 不要刪除共用的 Foundry 專案、模型部署或容器登錄檔。

相關內容

請參考這些指南來擴展您的工作流程：

  • Last updated on