在這個快速入門中，你會部署一個容器化的 AI 代理，該代理會呼叫 Foundry 模型，並在 Foundry Agent Service 中使用 Foundry 工具。 範例代理使用網頁搜尋，並可選擇性地使用模型上下文協定（MCP）工具來回答問題。 最後你會有一個運行中的託管代理程式，可以透過 Foundry 工作環境進行互動。 選擇您偏好的部署方式開始。
在此快速入門中，您將：
- 用 Foundry 工具設置一個代理範例專案
- 在本地測試該代理
- 將應用部署到 Foundry 代理服務
- 在操場上與你的經紀人互動
- 清理資源
先決條件
在開始之前，你需要：
- Azure訂閱 - 免費建立
- （可選）如果你有 MCP 工具，想用的話。
- Python 3.10 或更高
- Azure 開發者 CLI版本 1.24.0 或更新版本
註
託管代理程式目前處於預覽階段。
所需許可
你需要在 project 範圍內使用 Azure AI Project Manager 來建立和部署託管代理。 此角色擁有建立代理的資料平面權限，並具備將 Azure AI 使用者角色指派給平台所建立的代理身分的能力。 代理身份需要專案中的 Azure AI 使用者，才能在執行時存取模型與產物。
如果你使用 azd 或 VS Code 擴充功能，該工具會自動處理大多數 RBAC 指派，包括：
請確認 Foundry Project 的管理身份在 Azure Container Registry 中具有你使用的 ACR 拉取權限。 如果你偏好且擁有擁有者或「使用者存取管理員」的權限，azd/vscode 工具也能幫你完成這項任務。 平臺創建代理身份的 Azure AI 使用者（執行階段模型和工具存取）
步驟 1：設置範例專案
警告
本文件適用於新後端的託管代理，且需要 azd AI 代理 0.1.27-preview 版本或更新版本。 對於使用 Azure 容器應用程式 的舊有體驗，請繼續使用 0.1.25-preview。
安裝 Azure Developer CLI 代理擴充功能，並初始化一個新的託管代理專案。
安裝 Azure 開發者 CLI 的
ai agent擴充功能：azd ext install azure.ai.agents要確認擴充功能已安裝，請執行：
azd ext list在空目錄中初始化一個新的託管代理專案：
azd ai agent init互動式流程會引導你完成以下配置：
- Language — 選擇你想要範例程式碼的程式語言，C# 或 Python。
- 代理人範本 - 選擇一個範例作為起點。
- Model Configuration - 選擇在 Foundry 部署新模型，或使用現有 Foundry Project的現有模型。
- Azure 訂閱 — 選擇你想建立 Foundry 資源的訂閱。
- 地點 — 選擇資源的區域。
- 模型SKU — 選擇您所在地區及訂閱的可用SKU。
- 部署名稱 — 輸入模型部署名稱。
- 容器大小 — 選擇 CPU 與記憶體配置，或接受預設值。
重要
如果你用工具選擇範例，且沒有使用 MCP 伺服器，請註解或刪除檔案中的
agent.yaml以下行：- name: AZURE_AI_PROJECT_TOOL_CONNECTION_ID value: <CONNECTION_ID_PLACEHOLDER>提示
如果你是在非互動環境（如 CI/CD 管線或 SSH 會話）執行，請使用
--no-prompt帶有azd ai agent init的旗標。 你也必須以命令列旗標方式提供所有所需值，而不是回應互動式提示。配置所需的 Azure 資源：
註
你需要在Azure訂閱上取得Contributor權限才能提供資源。
azd provision此指令需時幾分鐘，並產生以下資源：
資源 目的 成本 資源群組 將所有相關資源集中於同一區域 免費 模型部署 代理人所使用的模型 請參閱 Foundry 定價 鑄造廠計畫 託管您的代理人並提供 AI 功能 以消費為基礎; 參見 Foundry 價格模式 Azure Container Registry 儲存你的代理容器影像 基本層級;請參見 ACR定價 Log Analytics 工作區 將所有日誌資料集中管理 沒有直接費用。 請參見Log Analytics成本 Application Insights 監控代理程式效能與日誌 隨用付費；請參見 Azure 監視器 價格 管理身份 將你的代理程式認證到 Azure 服務 免費 提示
完成快速入門後，執行
azd down以刪除資源並避免產生費用。
步驟二：在本地測試代理人
部署前，請確認代理程式在本地運作。
在本地啟動代理人：
azd ai agent run此指令會自動設定環境、安裝相依關係並啟動代理程式。 它透過
startupCommand中定義的azure.yaml來啟動你的代理。註
預覽套件在設定時可能會產生 pip 依賴版本衝突警告。 這些警告是非阻塞性的——代理程式會正常啟動並回應。
如果客服無法啟動，請檢查以下常見問題：
錯誤 解法 AuthenticationError或DefaultAzureCredential失敗運行 azd auth logout然後azd auth login以刷新你的會話。ResourceNotFound請確認你的端點網址與 Foundry 入口網站的數值相符。 DeploymentNotFound請查看Build>Deployments中的部署名稱。 Connection refused確保沒有其他程序使用 8088 埠。 在另一個終端機中，向本地代理發送測試訊息。
對於使用 Responses API 的代理，你可以發送一個字串作為有效載荷：
azd ai agent invoke --local "What is Microsoft Foundry?"對於使用 Invocations API 的代理，請檢查
README.md以獲取預期的有效負載。 範例通常需要 JSON 有效負載，但請查看該範例的README.md，以獲得具體範例：你應該會看到客服的回覆。
步驟 3：部署至 Foundry 代理服務
既然你在第一步已經配置好基礎架構，請將你的代理程式碼部署到 Azure：
azd deploy
代理容器是遠端建置的，所以你的電腦不需要 Docker Desktop。
註
azd deploy 指令會為代理的代理身份分配Azure RBAC 角色。 此角色指派需要您的訂閱具有 擁有者 或 使用者存取權限管理員 權限，以及佈建所需的 貢獻者 角色。
警告
你的託管代理在部署期間會產生費用。 測試結束後，執行清理資源以刪除資源並停止費用。
完成後，輸出會顯示一個連結到代理遊樂場（Agent Playground）及程式呼叫代理的端點：
Deploying services (azd deploy)
(✓) Done: Deploying service af-agent-with-foundry-tools
- Agent playground (portal): https://ai.azure.com/nextgen/.../build/agents/af-agent-with-foundry-tools/build?version=1
- Agent endpoint: https://ai-account-<name>.services.ai.azure.com/api/projects/<project>/agents/af-agent-with-foundry-tools/versions/1
重要
請確保你使用的是 Microsoft Foundry Toolkit 擴充套件的 prelease 版本，以及 VS Code 中的 Foundry 擴充功能。
在你的 VS Code 擴充套件頁面，選擇 Foundry Toolkit 擴充功能和 Foundry 擴充功能，並切換到預發布版本。
步驟一：建立鑄造廠專案
在 VS Code 中使用 Microsoft Foundry Toolkit 擴充功能，建立一個新的 Microsoft Foundry Project 資源。
打開指令面板（Ctrl+Shift+P），選擇 Microsoft Foundry：建立 Project。
選擇您的 Azure 訂閱。
建立新的資源群組或選擇現有的。
輸入 Foundry Project 資源的名稱。
專案建立完成後，繼續下一步部署模型。
步驟二：部署模型
使用 VS Code 中的 Microsoft Foundry Toolkit 擴充功能，將模型部署到 Foundry。
打開指令面板（Ctrl+Shift+P），選擇 Microsoft Foundry： Open Model Catalog。
瀏覽型號目錄或搜尋 gpt-4.1，然後選擇 部署 按鈕。
在模型部署頁面，選擇 部署至 Microsoft Foundry 按鈕。
模型成功部署後，進入下一步，建立一個託管代理專案
步驟 3：建立託管代理專案
在 VS Code 中使用 Microsoft Foundry Toolkit 擴充功能來搭建新的託管代理專案。
打開指令面板（Ctrl+Shift+P），選擇 Microsoft Foundry：建立新的託管代理程式。
選擇你想使用的框架。
選擇一種程式語言，Python 或 C#。
選擇回應 API 或調用 API。
選擇你想使用的範例程式碼。
選擇你想儲存專案檔案的資料夾。
輸入託管代理人的名稱。
一個新的 VS Code 視窗會啟動，新的代理專案資料夾會成為活動工作區。
步驟 4：安裝相依性
建議使用虛擬環境來隔離專案的相依項目。
macOS/Linux：
python -m venv .venv
source .venv/bin/activate
Windows （PowerShell）：
python -m venv .venv
.\.venv\Scripts\Activate.ps1
安裝相依性套件
使用 pip 安裝所需的 Python 套件依賴：
pip install -r requirements.txt
請參閱 requirement.txt 以了解所需包裹清單。
步驟五：在本地測試代理人
部署前先執行並測試代理。
選項一：按 F5（建議）
在 VS Code 中按 F5 開始除錯。 或者，你也可以使用 VS Code 除錯選單：
- 開啟 執行與除錯 檢視（Ctrl+Shift+D / Cmd+Shift+D）
- 從下拉選單選擇「偵錯本機工作流程 HTTP 伺服器」
- 點擊綠色的 開始除錯 按鈕（或按 F5）
這將：
- 啟動 HTTP 伺服器時啟用除錯
- 開啟 Foundry 工具包 Agent Inspector 進行互動測試
- 讓你設定中斷點並檢視工作流程
選項二：在終端機執行
預設以 HTTP 伺服器方式執行：
python main.py
這會讓託管代理在 http://localhost:8088/本地啟動。
PowerShell （Windows）：
$body = @{
input = "I need a hotel in Seattle from 2025-03-15 to 2025-03-18, budget under `$200 per night"
stream = $false
} | ConvertTo-Json
Invoke-RestMethod -Uri http://localhost:8088/responses -Method Post -Body $body -ContentType "application/json"
Bash/curl（Linux/macOS）：
curl -sS -H "Content-Type: application/json" -X POST http://localhost:8088/responses \
-d '{"input": "Find me hotels in Seattle for March 20-23, 2025 under $200 per night","stream":false}'
代理人會利用此 get_available_hotels 工具搜尋符合您條件的可租飯店。
步驟 6：部署至 Foundry 代理服務
直接從 VS Code 部署代理程式。
打開指令面板（ctrl+shift+p），選擇 Microsoft Foundry：部署 Hosted Agent。
選擇「預設ACR」
選擇 Hosted Agent 容器的 CPU 與記憶體配置。
請選擇左側圖示切換至 Microsoft Foundry 工具包總覽。 部署完成後，代理會出現在 託管代理（預覽） 樹狀檢視側邊欄。
驗證並測試你的代理人
部署完成後，確認你的代理程式正在執行。
查詢代理人狀態
檢查你的代理程式狀態，確認它是否在運作。
從託管代理（預覽）樹狀圖中選擇你的託管代理。
選擇你剛部署的代理
詳細頁面在容器詳細資料區塊下方顯示狀態。
在操場上使用 VS Code 進行測試
Microsoft Foundry VS Code 工具包包含一個整合的遊樂場，方便與您的代理進行聊天與互動。
從託管代理（預覽）樹狀圖中選擇你的託管代理。
選擇 Playground 選項，輸入訊息後發送，測試你的代理人。
確認代理人狀態
請檢查您已部署的代理人狀態：
azd ai agent show
將輸出顯示為表格格式：
azd ai agent show --output table
如果你的專案有多個代理服務，請指定代理名稱作為位置參數：
azd ai agent show <agent-name>
提示
在<agent-name>章節的azure.yaml檔案中找到services:。
測試已部署的代理程式
用之前用過的 invoke 相同指令，但不使用 --local 標記，向已部署的代理發送測試訊息：
對於使用 Responses API 的代理，你可以發送一個字串作為有效載荷：
azd ai agent invoke <payload>
你應該會在幾秒後看到客服回覆。
查看代理日誌
監控你經紀人的即時日誌：
# Fetch recent container console logs
azd ai agent monitor
# Fetch the last N lines of console logs
azd ai agent monitor --tail 20
# Fetch system event logs (container start and stop events)
azd ai agent monitor --type system
# Stream session logs in real time
azd ai agent monitor --session <session-id> --follow
如果你的專案有多個代理服務，請指定代理名稱作為位置參數：
azd ai agent monitor <agent-name> --follow
鑄造廠操場測試
在鑄造廠平台中導航到代理：
開啟 Foundry 入口網站並用你的Azure帳號登入。
從「近期專案」列表中選擇您的專案，或選擇「所有專案」以找到該專案。
在左側導覽中，選擇 「建構 」展開選單，然後選擇 「代理人」。
在代理程式清單中，找到你已部署的代理（它與你部署中的代理名稱相符）。
選擇代理人名稱以開啟其詳細頁面，然後在頂方工具列選擇 「在遊樂場開啟 」。
在聊天介面中，輸入測試訊息如「What is Microsoft Foundry？」並按Enter。
確認客服是否回應網路搜尋結果的資訊。 回應可能需要幾秒鐘，因為代理會查詢外部來源。
提示
如果遊樂場無法載入或代理程式沒有回應，請使用上述的容器詳細資料頁面確認代理狀態是否正確 Started 。
清理資源
為了避免收費，完成後刪除資源。
警告
此指令會永久刪除資源群組中所有 Azure 資源，包括 Foundry 專案、模型部署、容器登錄檔、應用程式洞察以及你的託管代理。 這個行動無法撤銷。 如果你使用的是包含其他資源的現有資源群組，請小心—— azd down 移除群組中的所有資源，而非僅是這個快速啟動所產生的資源。
要預覽將被刪除的內容，請執行 down 以下指令：
azd down
完成後， azd 會顯示所有將被刪除的資源，並提示你確認。 選擇 yes 繼續或 no 取消。
清理過程大約需要2到5分鐘。
警告
刪除資源會永久移除此快速入門中所有 Azure 資源，包括 Foundry 專案、容器登錄檔、應用程式洞察以及你的託管代理。 這個行動無法撤銷。
要刪除資源，請開啟 Azure portal，進入資源群組，刪除該群組及所有包含的資源。
要確認資源已被刪除，請開啟Azure入口，進入你的資源群組，確認資源不再顯示。 如果資源群組是空的，你也可以刪除它。
故障排除
如果你遇到問題，可以試試以下常見問題的解決方案：
| 問題 | 解法 |
|---|---|
SubscriptionNotRegistered 錯誤 |
註冊供應商：az provider register --namespace Microsoft.CognitiveServices |
AuthorizationFailed 配置期間 |
申請在您的訂閱或資源群組上擔任 貢獻者 角色。 |
| 代理程式無法在本地啟動 | 確認環境變數已設定並執行 az login 以刷新憑證。 |
AcrPullUnauthorized 錯誤 |
指派AcrPull角色給專案的管理識別在容器註冊表上。 |
關於所有權限與角色分配的完整細節，請參閱「託管代理權限參考」。
| 問題 | 解法 |
|---|---|
azd ai agent init 失敗 |
執行 azd version 以驗證版本 1.24.0+。 更新為 winget upgrade Microsoft.Azd（Windows）或 brew upgrade azd（macOS）。 確認已安裝代理程式擴充套件 azd ext list。 請確保您使用的擴充功能為最新版本，azd ext upgrade azure.ai.agents的版本為 0.1.27-preview 或更新版本。 |
查看你的代理程式的容器紀錄
你可以查看容器的主控台和系統日誌來排查問題。
從託管代理（預覽）樹狀圖中選擇你的託管代理。
選擇你託管代理人的「Playground」標籤
在會話詳情中選擇「日誌」區塊。
查看您的代理人的會話檔案
你可以查看儲存在你 ADC 代理主目錄上的所有檔案
從託管代理（預覽）樹狀檢視中選擇您的託管代理。
選擇你託管代理人的「Playground」標籤
在會話詳情中選擇「檔案」區塊。
你可以下載、上傳並建立現有資料夾，點擊資料夾會進入該資料夾，點擊上方導航列則會回到該資料夾。
| 問題 | 解法 |
|---|---|
| 未找到擴充功能 | 從 VS Code 市集安裝 Microsoft Foundry Toolkit for VS Code 擴充功能。 |
你學到了什麼
在這個快速入門中，您將會：
- 使用 Foundry 工具（網頁搜尋與 MCP）建立託管代理範例
- 在當地測試了該藥劑
- 部署至鑄造廠代理服務
- 在 Foundry 遊樂場驗證你的代理人
下一步
現在你已經部署了第一個託管代理，請學習如何：
以額外功能客製化您的經紀人：
- 連接 MCP 工具 以擴展代理功能
- 使用函式呼叫 來整合自訂邏輯
- 新增檔案搜尋 以搜尋您的文件
- Enable code interpreter 以執行Python程式碼
你可以在 工具目錄 文章中看到完整的可用工具清單。