建置部署於 Google Cloud Platform (GCP) 的 Agent 365 Agent

了解如何建置、託管、註冊及發佈在 Google Cloud Run 上執行的 Agent 365 Agent，並使用 Agent 365 CLI。 Microsoft Entra & Graph 提供Agent身份、權限及藍圖，而 Google Cloud Run 則提供執行階段。

如果你只想讓Agent指向位於AWS端點後方的程式碼，只需執行這個額外步驟：設定非Azure代管，然後依序進行開始使用Agent 365開發的所有步驟。

目標

學習如何將Agent 365和Microsoft 365作為「控制平面」並：

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

先決條件

開始前，請確保符合以下 Azure / Microsoft 365、Google Cloud Platform（GCP）及本地環境的先決條件。

Azure / Microsoft 365 先決條件

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

• 具備以下項目的 Microsoft Entra 租戶：

  • 具備建立應用程式和Agent藍圖的權限或角色（全域管理員或同等角色）
  • 必須參與Frontier 預覽計劃，才能搶先體驗 Microsoft Agent 365。
  • 至少有一個Microsoft 365授權可供Agent使用者使用

• 已安裝 Azure CLI，並已登入。

• 已安裝Agent 365 CLI

GCP 必要條件

• 建立 GCP 專案

• Cloud Run API 已啟用

• gcloud SDK 已安裝並完成認證

  gcloud auth login
  gcloud config set project <GCP_PROJECT_ID>
  gcloud config set run/region us-central1   # or your preferred region
  

本地開發環境先決條件

• 程式碼編輯器：您選擇的任何程式碼編輯器。 建議使用Visual Studio Code。

• （選用）Node.js 你可以使用任何語言來開發你的Agent。 本文在以下步驟中使用 Node 18 以上版本。

• LLM API 存取：根據您的Agent設定或您慣用的模型提供者選擇適當的服務：

  • OpenAI API 金鑰：取得您的 OpenAI API 金鑰
  • Azure OpenAI：建立並部署 Azure OpenAI 資源以取得您的 API 金鑰與端點

在 Cloud Run 上建立與部署Agent 365 Agent

此範例使用一個最精簡的 Agent 365 Agent：

• 回應 GET /
• POST 接收Bot Framework活動 /api/messages
• 透過 Agent 365 SDK 使用 JWT 驗證
• 為簡化起見，將所有程式碼集中於單一 index.js檔案中

建立專案

請依照以下步驟建立一個精簡的 Node.js Agent，該 Agent 可在 Cloud Run 上運行，並處理 Bot Framework 活動。

1. 建立專案目錄

   mkdir gcp-a365-agent
   cd gcp-a365-agent
   

2. 初始化Node專案

   npm init -y
   npm install express @microsoft/agents-hosting dotenv
   

3. 建立 index.js

      // Load environment variables from .env file (for local development)
   require('dotenv').config();
   
   const { 
   CloudAdapter, 
   Application, 
   authorizeJWT, 
   loadAuthConfigFromEnv 
   } = require('@microsoft/agents-hosting');
   const express = require('express');
   
   // Loads clientId, clientSecret, tenantId from environment variables
   // These map to your Agent Blueprint App Registration in Entra ID:
   //   clientId     = Blueprint Application (client) ID
   //   clientSecret = Blueprint client secret value  
   //   tenantId     = Your Microsoft Entra tenant ID
   const authConfig = loadAuthConfigFromEnv();
   
   // Pass authConfig to adapter so outbound replies can authenticate
   const adapter = new CloudAdapter(authConfig);
   
   const agentApplication = new Application({ adapter });
   
   // Handle incoming messages
   agentApplication.onMessage(async (context, next) => {
   await context.sendActivity(`You said: ${context.activity.text}`);
   await next();
   });
   
   // Handle conversation updates
   agentApplication.onConversationUpdate(async (context, next) => {
   if (context.activity.membersAdded) {
      for (const member of context.activity.membersAdded) {
         if (member.id !== context.activity.recipient.id) {
         await context.sendActivity('Welcome! This agent is running on GCP.');
         }
      }
   }
   await next();
   });
   
   // Required: handle agentLifecycle events sent by Agent 365 platform
   // Without this handler, the SDK throws on first conversation initiation
   agentApplication.on('agentLifecycle', async (context, next) => {
   await next(); // acknowledge silently — do NOT call sendActivity here
   });
   
   const server = express();
   server.use(express.json());
   
   // Health check — no auth required
   server.get('/', (req, res) => res.status(200).send('GCP Agent is running.'));
   
   // JWT validation applied only to /api/messages
   // Bot Framework Service sends a Bearer token signed by botframework.com
   // This is required even on GCP — the control plane is still Microsoft
   server.post('/api/messages', authorizeJWT(authConfig), (req, res) => {
   adapter.process(req, res, async (context) => {
      await agentApplication.run(context);
   });
   });
   
   const port = process.env.PORT || 8080;
   server.listen(port, () => console.log(`Agent listening on port ${port}`));
   

部署到 Google Cloud Run

使用 gcloud run deploy 在 Cloud Run 上建置並執行服務。 部署完成後，請記下您的 messagingEndpoint 的公開網址。

1. 請使用以下指令將您的專案部署到 Google Cloud Run：

   gcloud run deploy gcp-a365-agent `
   --source . `
   --region us-central1 `
   --platform managed `
   --allow-unauthenticated
   

2. 完成後，請記下您的端點：

   https://gcp-a365-agent-XXXX-uc.run.app
   

   此網址是 messagingEndpoint，Agent 365開發工具 CLI 在下一步驟所使用的。

設定非 Azure 託管環境

請在你的 Cloud Run 專案資料夾中手動建立 a365.config.json：

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

  "messagingEndpoint": "https://gcp-a365-agent-XXXX-uc.run.app/api/messages",

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

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

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

欄位	意義
messagingEndpoint	您的 Cloud Run URL + /api/messages
deploymentProjectPath	.env標記發生的位置

---

建置 Agent 365 Agent

將您的Agent程式碼部署到 GCP端點後，請依照 Agent 365 開發生命週期的剩餘步驟，完成 Agent 365 Agent的設定。 此程序包括：

• 在Microsoft Entra ID中建立Agent身份
• 註冊Bot Framework訊息端點
• 建立Agent使用者
• 發佈至Microsoft 365平台

Agent 365 CLI 會根據你的 a365.config.json設定自動處理大部分這些步驟。

端對端驗證 Agent

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

驗證 Cloud Run 連線

傳送 GET 請求至 messagingEndpoint 值，該值來自您的 a365.config.json。

curl https://gcp-a365-agent-XXXX.run.app/

回應內容應包括：

GCP Agent is running.

檢查Cloud Run日誌中的傳入Bot Framework訊息

您可以查看Google雲端 Log Explorer 或執行：

gcloud run services logs read gcp-a365-agent --region <your region> --limit 50

當訊息到達您的Agent後，您會在日誌條目中看到伺服器透過Agent 365 SDK接收並處理該活動的記錄。

從 Agent 365 各介面測試 Agent

根據您的環境，使用：

• Agent 遊樂場
• Teams（若已發佈）
• Agent 殼層

您現在可以發送訊息並確認您的 Cloud Run 日誌。 如需詳細資訊，請參閱 了解如何使用 Microsoft Agent 365 SDK 測試Agent，並透過Agents Playground測試工具驗證Agent的功能。

開發人員工作流程

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

1. 本機測試（選用）

   要在部署到 Cloud Run 前於本地測試你的Agent，請確保你的 .env檔案包含正確的認證：

   # Start the agent locally
   node index.js
   

   您的Agent位於 http://localhost:8080。 您可以測試健康狀態端點：

   curl http://localhost:8080/
   

2. 變更您的程式碼

   編輯 index.js 並儲存您的變更。

3. 重新部署到 Google Cloud Run

   gcloud run deploy gcp-a365-agent --source .
   

4. 測試與監視

   透過Agent 365相關介面進行測試，並監控Google Cloud Run日誌。

疑難排解​​

請使用本區段來診斷在Google Cloud Run 部署及運行Agent 365 Agent時的常見問題。 協助您迅速套用修正，解決連線、設定及授權問題。

提示

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

訊息端點無法到達

檢查以下詳細資料：

• 您的端點必須完全為：
  https://<cloud-run-url>/api/messages
• Cloud Run 允許未經認證的存取
• 沒有防火牆規則

授權指派失敗

請手動指派有效的 Microsoft 365 Frontier 授權，或在支援時使用未授權使用者路徑。