將 Agent 部署至 Azure

您已建置並在本機測試您的 Agent。 現在，讓它在雲端上線。 這個步驟是選擇性的。 如果您已將 Agent 部署到某個雲端 (甚至不必是 Azure)，則可以略過此步驟。

本指南將逐步引導您將 Agent 程式碼部署至 Azure，並將其發佈至 Microsoft 系統管理中心，使其成為貴組織已登錄的資產。

若要更新訊息端點，請參閱下列資源。 這些資源說明如果您將 Agent 部署到 Amazon Web Services 或 Google Cloud Platform 等其他雲端供應商，應如何更新訊息端點：

先決條件

開始之前，請確認您已具備下列項目：

必要的帳戶與權限

必要工具

部署至 Azure

使用 Azure CLI、Azure 入口網站或 GitHub Actions 等標準 Azure 工具，將您的 Agent 應用程式程式碼部署至 Azure。

部署 Agent 應用程式

請使用 Azure CLI 的 az webapp deploy 命令，部署您的應用程式：

# Build your project first (example for .NET)
dotnet publish -c Release -o ./publish

# Deploy to Azure Web App
az webapp deploy --name <your-web-app> --resource-group <your-resource-group> --src-path ./publish

如為 GitHub Actions，請使用 Azure Web Apps Deploy 動作。

警告

秘密管理：將環境變數 (包括 API 金鑰與秘密) 儲存為 Azure 應用程式設定，而非放在程式碼或設定檔中。 針對正式環境，敏感性秘密請使用 Azure Key Vault。 如需詳細資訊，請參閱 ASP.NET Core 開發中應用程式秘密的安全儲存和 Azure Key Vault 設定提供者。 請勿將包含敏感資訊的 .env 檔案提交至原始檔控制。

驗證部署

部署完成後，請使用此清單和下列各節中的指示來驗證部署。

✅ 部署命令已順利完成，未發生任何錯誤
✅ Web 應用程式正在執行
✅ 應用程式記錄顯示已成功啟動
✅ 已設定環境變數
✅ 訊息端點已回應

驗證部署命令已順利完成且未發生錯誤

部署完成後，請在部署記錄中確認是否成功：

  1. 在 Azure 入口網站中移至 Web 應用程式。
  2. 前往設定>組態，驗證應用程式設定。
  3. 請在部署中心查看部署記錄。

若要查看詳細的部署歷程記錄：

  1. 前往 Azure 入口網站 > 您的 Web 應用程式
  2. 部署>部署中心
  3. 檢視最新部署的記錄

如果建置失敗：

  • 請先在本機清除並重建，確認建置可正常運作。
  • 請檢查是否缺少相依性或有語法錯誤。
  • 請參閱部署命令失敗。

如果應用程式在部署後當機：

驗證 Web 應用程式是否正在執行

請使用 az webapp show 命令，驗證 Web 應用程式是否正在執行。

az webapp show --name <your-web-app> --resource-group <your-resource-group> --query state

此命令的預期輸出為 Running。

驗證應用程式記錄顯示已成功啟動

若要在 Azure 入口網站中檢視 Web 應用程式記錄：

  1. 在 Azure 入口網站中依名稱搜尋 Web 應用程式。
  2. 前往概觀>記錄>記錄資料流。

或者，您也可以使用 PowerShell 的 az webapp log tail 命令讀取 Web 應用程式記錄：

az webapp log tail --name <your-web-app> --resource-group <your-resource-group>

如果記錄中有當機或錯誤訊息，請參閱應用程式在啟動時當機。

驗證環境變數是否已設定

在 Azure 入口網站中：

  1. 前往您的 Web 應用程式。
  2. 前往設定>環境變數。
  3. 確認您的設定存在。

如果尚未設定環境變數：

驗證訊息端點是否有回應

請使用 PowerShell 或其他方式，測試您在 Web 應用程式概觀頁面中找到的端點是否存在。 否則，請參閱訊息端點傳回 404。

後續步驟

接下來，請將您的 Agent 應用程式發佈至 Microsoft 系統管理中心，以便從中建立 Agent 執行個體與使用者。

發佈您的 Agent

您的 Agent 現已在雲端上線，並已可回應 Agentic 要求。 當您的 Agent 開始處理實際要求時，請考慮為您的程式碼進行下列後續步驟：

  • 監控效能：使用可觀察性功能追蹤 Agent 行為並最佳化回應。
  • 新增更多工具：探索工具目錄，擴充您 Agent 的功能。
  • 疊代並改善：更新您的 Agent 程式碼、重新部署並重新發佈 (別忘了遞增版本號碼！)。
  • 在您的組織中擴大規模：分享您 Agent 的成功案例，以推動採用。

疑難排解​​

本節說明將 Agent 部署至 Azure 時的常見問題。

提示

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

部署命令失敗

徵狀：部署至 Azure 失敗。

常見成因與解決方法：

  • 建置錯誤

    請在本機重建專案，以查看詳細的編譯錯誤：

    # .NET
dotnet clean
dotnet build --verbosity detailed

# Python
uv build

# Node.js
npm install
npm run build

  • Azure 驗證已過期

    請重新登入 Azure：

    az login
az account show  # Verify correct subscription

  • 尚未建立 Web 應用程式

    請列出 Web 應用程式，確認目標存在：

    # List Web Apps in resource group
az webapp list --resource-group <your-resource-group> --output table

  • 查看部署記錄

    請使用 az webapp log tail 命令，檢視詳細的部署記錄：

    az webapp log tail --name <your-app-name> --resource-group <your-resource-group>

  • 驗證：

    # Web App should be running
az webapp show --name <your-app-name> --resource-group <your-resource-group> --query state
# Expected: "Running"

Web 應用程式已停止

徵狀：部署成功，但 Web 應用程式未在執行。

解決方法：使用 az webapp start 和 az webapp show，啟動 Web 應用程式並驗證其是否正在執行。

# Start the Web App
az webapp start --name <your-app> --resource-group <your-resource-group>

# Verify it's running
az webapp show --name <your-app> --resource-group <your-resource-group> --query state

應用程式在啟動時當機

徵狀： Web 應用程式啟動後立即當機；記錄中顯示錯誤。

常見原因：

  • 缺少相依性 - 請檢查建置輸出，確認其中包含所有必要的套件。
  • 缺少環境變數 - 請確認已設定所有必要的設定。
  • 執行階段版本不相符 - 請確認 Azure 執行階段與您的開發環境相符。
  • 程式碼錯誤 - 請查看應用程式記錄中的特定例外狀況。

解決方法：使用 az webapp log tail、az webapp config appsettings list 和 az webapp config appsettings set 命令，檢視記錄、檢查環境變數，並設定缺少的變數。

# View application logs
az webapp log tail --name <your-app> --resource-group <your-resource-group>

# Check environment variables
az webapp config appsettings list --name <your-app> --resource-group <your-resource-group>

# Manually set a missing variable
az webapp config appsettings set --name <your-app> --resource-group <your-resource-group> --settings KEY=VALUE

訊息端點傳回 404

徵狀： Web 應用程式正在執行，但 /api/messages 端點傳回 404。

解決方案：

  1. 請驗證您 Agent 程式碼中的路由設定。
  2. 請檢查端點處理常式是否已正確登錄。
  3. 請確認部署時已指定正確的進入點。

請傳送 GET 要求至該 URL，測試該端點。 請使用 az webapp config show 命令，檢查 Web 應用程式組態。

curl https://<your-app-name>.azurewebsites.net/api/messages
az webapp config show --name <your-app> --resource-group <your-resource-group>

未設定環境變數或環境變數不正確

徵狀：部署成功，但 Agent 無法運作；記錄中顯示缺少設定的錯誤。

解決方法：請驗證並更新環境變數。 使用 az webapp config appsettings list 和 az webapp config appsettings set 命令，檢查環境變數並設定缺少的變數。 然後重新部署。

# List all app settings
az webapp config appsettings list --name <your-app> --resource-group <your-resource-group>

# Set a specific variable
az webapp config appsettings set --name <your-app> --resource-group <your-resource-group> --settings API_KEY=your-value

在本機建置成功，但在 Azure 中失敗

徵狀：程式碼在您的電腦上可正常建置，但在 Azure 部署過程中失敗。

解決方案：

  • 檢查平台特定的相依性

    • 部分套件具有平台特定的建置版本。
    • 請確認相依性支援 Linux (Azure Web Apps 預設在 Linux 上執行)。

  • 驗證執行階段版本是否相符

    執行以下命令：

    # Check your local version
dotnet --version  # .NET
node --version    # Node.js
python --version  # Python

    請在入口網站中與 Azure 執行階段比較：設定>組態>一般設定>堆疊設定。

如需其他協助，請參閱：訊息端點疑難排解。

  • Last updated on