將 Agent 部署至 Azure

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

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

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

• 使用部署在 Amazon Web Services 中的 Agent 程式碼
• 使用部署在 Google Cloud Platform 中的 Agent 程式碼

先決條件

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

必要的帳戶與權限

• 具有參與者存取權的 Azure 訂用帳戶。
• 可運作的 Agent 程式碼，且具有有效且可連線的訊息端點。 請確認您已在本機測試您的 Agent，並視需要使用 Dev Tunnels 搭配 Microsoft 365 進行測試，以驗證 Agent 程式碼可以建置並依預期執行。
• 完成設定 Agent 藍圖步驟，取得有效的 Agent 藍圖。
• 最新的設定檔 a365.config.json、a365.generated.config.json，以及程式碼中的設定檔 (例如 .env 檔案)。

必要工具

• 已安裝並驗證 Azure CLI (安裝 Azure CLI)

部署至 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 動作。

驗證部署

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

✅ 部署命令已順利完成，未發生任何錯誤
✅ 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. 確認您的設定存在。

如果尚未設定環境變數：

• 重新執行部署，從 .env 檔案同步。
• 或在 Azure 入口網站中手動設定。
• 請參閱未設定環境變數或環境變數不正確。

驗證訊息端點是否有回應

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

後續步驟

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

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

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

疑難排解​​

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

部署命令失敗

徵狀：部署至 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 執行階段比較：設定>組態>一般設定>堆疊設定。

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