建置部署於 Amazon Web Services (AWS) 的 Agent 365 Agent

學習如何建立、託管、註冊並發佈一個在 AWS Elastic Beanstalk 上運行的 Agent 365 Agent，使用 Agent 365 CLI。 Microsoft Entra 和 Graph 提供Agent身份、權限與藍圖，而 AWS Elastic Beanstalk 提供執行階段。

如果你想讓Agent指向位於 AWS 端點後方的程式碼，只需以下步驟： 設定非 Azure 主機。 接下來，按照開始使用Agent 365開發的所有其他步驟進行。

目標

學習如何使用Agent 365和Microsoft 365作為控制平面：

  • 在AWS Elastic Beanstalk 上部署Agent執行階段
  • 為非 Azure 主機環境配置 a365.config.json
  • 在 Entra ID 中建立Agent藍圖
  • 配置OAuth2 + 可繼承的權限
  • 註冊指向AWS的Bot Framework訊息傳遞端點
  • 建立 Agent 身分 + Agent 使用者
  • (選用) 發佈到 Microsoft 365 應用程式面板
  • 測試端對端互動

先決條件

開始之前，請確認已滿足以下 Azure / Microsoft 365、AWS 及本地環境的先決條件。

Azure / Microsoft 365 先決條件

請確認您的 Microsoft Entra 租戶存取權，並安裝以下工具以建立身分、藍圖及註冊您的Agent。

Amazon Web Services (AWS) 先決條件

請確保以下AWS服務和工具已安裝並設定，以部署和管理您的 Elastic Beanstalk 環境。

本地開發環境先決條件

在本地安裝並設定以下工具，以建置、執行並部署Agent。

建立和部署 .NET Agent

以下說明如何建立一個最小Agent：

  • 回應 GET /
  • POST 接收Bot Framework活動 /api/messages

建立專案目錄

mkdir aws-a365-agent
cd aws-a365-agent

初始化 .NET 專案

為了簡化操作流程，本文使用了已準備好的範例。 複製 Agent365 範例存放庫，並前往 dotnet\semantic-kernel\sample-agent 範例。

語意核心範例Agent— C#/.NET 範例包含：

  • 精簡的 ASP.NET 核心 Web API
  • Bot Framework訊息處理程式位於 /api/messages
  • 健康檢查端點位於/
  • 整合 語意核心 以提供 AI 功能

請前往 dotnet\semantic-kernel\sample-agent，並確認專案是否成功建置：

dotnet restore
dotnet build

設定模型

請依照步驟 2：LLM 設定的指示，使用您的 Open API 金鑰來配置專案。

本機測試（選用）

  1. 在部署到AWS之前，請先在本地端測試您的Agent：

    # Run the application
dotnet run

  2. 在另一個終端機中測試端點。

    # Test agent endpoint locally
curl http://localhost:3978

  3. 按下 Ctrl+C 以停止本地伺服器。

建置和部署

請選擇您偏好的選項來建置並部署此範例應用程式：

選項 A：從 Visual Studio 建置與部署

使用AWS Toolkit for Visual Studio，透過精靈將應用程式發佈到 Elastic Beanstalk。

  1. 在解決方案資源管理器中，右擊您的專案。

  2. 選取 發佈到 AWS Elastic Beanstalk。

  3. 依照Beanstalk 部署精靈：

    • 選擇您的 AWS 認證個人檔案。
    • 選擇區域 (例如us-east-1)。
    • 選取平台（.NET Core on Linux）。
    • 設定環境設定。

  4. 選取 [部署]。

精靈會建置、封裝並部署你的應用程式到AWS。

選項 B：透過 CLI 建置並部署到 AWS Elastic Beanstalk

使用 Elastic Beanstalk CLI 將 .NET Agent 封裝並部署至 64 位 Amazon Linux 2 環境。 請確保AWS CLI 和 EB CLI 已正確設定。 這個應用程式會連結到由 Beanstalk 設定的PORT環境變數。

  1. 建置並發佈您的 .NET 應用程式：

    # Publish for Linux runtime (AWS Elastic Beanstalk uses Amazon Linux)
dotnet publish -c Release -o ./publish --runtime linux-x64

    建立 Procfile檔案，內容如下：

    web: dotnet ./SemanticKernelSampleAgent.dll

  2. 初始化 Elastic Beanstalk 的 .NET 環境。 提示您選擇區域和平台：

    eb init

  3. 選取：

    • 平台：64bit-amazon-linux-2023-v3.7.0-running-.net-8
    • 區域：您慣用的AWS區域（例如：us-east-1）

  4. 建立部署套件並部署：

    cd publish
zip -r ../deploy.zip .
cd ..
eb create aws-a365-agent-env
eb deploy

    此命令：

    • 建立 Elastic Beanstalk 應用程式。
    • 建立具有負載平衡器的環境。
    • 部署應用程式。
    • 佈建必要的 AWS 資源。

  5. 完成後，請取得您的 Elastic Beanstalk 端點：

    eb status

    記下您的端點。 您應該會看到類似下面的畫面：

    http://aws-a365-agent-env.us-east-1.elasticbeanstalk.com

    這個端點是 messagingEndpoint 被 Agent 365 開發工具 CLI 所使用。

注意

在正式環境中，請透過於 Elastic Beanstalk 中新增 SSL/TLS 憑證來啟用 HTTPS 設定。 Bot Framework要求生產環境的端點使用 HTTPS。

設定非 Azure 託管環境

在你的 Elastic Beanstalk 專案資料夾中手動建立 a365.config.json。

重要

對於非Azure託管，請將 messagingEndpoint 的值設定為你的 Elastic Beanstalk 網址，並包含 /api/messages 路徑。

a365.config.json檔案應該會如下所示：

{
  "tenantId": "YOUR_TENANT_ID",
  "environment": "prod",

  "messagingEndpoint": "http://aws-a365-agent-env.us-east-1.elasticbeanstalk.com/api/messages",

  "agentIdentityDisplayName": "MyAwsAgent Identity",
  "agentBlueprintDisplayName": "MyAwsAgent Blueprint",
  "agentUserDisplayName": "MyAwsAgent User",
  "agentUserPrincipalName": "myawsagent@testTenant.onmicrosoft.com",
  "agentUserUsageLocation": "US",
  "managerEmail": "myManager@testTenant.onmicrosoft.com",

  "deploymentProjectPath": ".",
  "agentDescription": "AWS-hosted Agent 365 Agent"
}

下資料表總結了重要的設定欄位及其用途。

欄位 意義
messagingEndpoint 你的 Elastic Beanstalk 網址 + /api/messages
deploymentProjectPath .env標記發生的位置

建置 Agent 365 Agent

當您的Agent程式碼在AWS端點上執行後，請按照 開始使用 Agent 365 開發的剩餘步驟，完成Agent 365 Agent的設定。

端對端驗證 Agent

請使用以下檢查來確認您的 AWS 託管 Agent 是否可連接、能接收 Bot Framework 活動，並能在 Agent 365 各個平台上正確回應。

驗證 Elastic Beanstalk 的連線能力

向 Elastic Beanstalk 端點發送 GET 請求。

curl http://aws-a365-agent-env.us-east-1.elasticbeanstalk.com/

請求應傳回下列訊息：

AWS Agent is running.

檢查 Elastic Beanstalk 日誌中收到的Bot Framework訊息

使用 Elastic Beanstalk 日誌以確認您的 Agent 是否正確接收 Bot Framework 活動並回應。

eb logs

或即時流式傳輸日誌：

eb logs --stream

當訊息傳送到你的Agent後，你會看到：

POST 200 /api/messages
Received activity: { ... }

從 Agent 365 各介面測試 Agent

根據您的環境，您可以從不同的介面測試您的Agent：

  • Agent 遊樂場
  • Teams（若已發佈）
  • Agent 殼層
  • 聯合表面

您可以傳送訊息並確認您的 Elastic Beanstalk 日誌。 了解如何利用Microsoft Agent 365 SDK測試Agent，並透過Agents Playground測試工具驗證Agent的功能。

開發人員工作流程

設定完成後，請依照以下工作流程進行迭代開發：

本地開發與測試

使用 watch 模式，透過自動重新載入進行快速開發：

# Automatically rebuild and restart on file changes
dotnet watch run

先修改程式碼變更、儲存並在本地測試，然後再部署。

建置並重新部署到 AWS Elastic Beanstalk

當你準備好部署變更時：

# Clean previous builds (optional but recommended)
dotnet clean

# Publish optimized release build
dotnet publish -c Release -o ./publish --runtime linux-x64

# Create deployment package
cd publish
zip -r ../deploy.zip .
cd ..

# Deploy to AWS
eb deploy

測試與監視

使用Agent 365各種介面進行測試，並監控 Elastic Beanstalk 日誌：

# Stream logs in real-time
eb logs --stream

無需重新建立身份、藍圖、機器人端點或權限。

疑難排解​​

透過本區段診斷與排除在 AWS Elastic Beanstalk 部署及執行 Agent 365 Agent時的常見問題。 它涵蓋了連線和健康情況檢查。 同時也涵蓋了埠繫結、建置錯誤和軟體授權相關問題。

提示

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

訊息端點未收到請求

檢查以下詳細資料：

  • 您的端點必須完全為：
    http://<your-app>.elasticbeanstalk.com/api/messages
  • 您的 Elastic Beanstalk 環境健康情況良好。 請使用 eb health 進行檢查。
  • 您的安全性群組允許 HTTP 或 HTTPS 的入站流量。
  • 沒有防火牆規則或 VPC 限制。

應用程式健康情況問題

檢查環境健康狀態：

eb health --refresh

檢視詳細記錄：

eb logs

埠繫結問題

請確保您的應用程式監聽依環境變數 PORT 指定的埠。 Elastic Beanstalk 會自動設定這個值。

.NET 建置或執行階段問題

請依以下命令檢查建置錯誤：

# Clean and rebuild
dotnet clean
dotnet build --verbosity detailed

確認 .NET 版本：

dotnet --version
dotnet --list-sdks

檢查套件問題：

# List installed packages
dotnet list package

# Update packages
dotnet restore --force

授權指派失敗

手動指派有效的Microsoft 365授權，或若支援則使用未授權的使用者路徑。

  • Last updated on