在 Google Cloud Platform（GCP）上部署一个 Agent 365 服务代理

学习如何使用 Agent 365 CLI 在 Google Cloud Run 上构建、托管、注册和发布运行的 Agent 365 代理。 Microsoft Entra和Graph 提供代理标识、权限和蓝图，而 Google Cloud Run 提供运行时。

如果您只想将代理指向驻留在 AWS 终结点后的代码，只需完成以下附加步骤：为非 Azure 托管进行配置，然后按照Agent 365 开发中的所有其他步骤操作。

目标

了解如何将 Agent 365 和 Microsoft 365 用作“控制平面”，并：

• 在 Google Cloud Run 上部署代理运行时
• 为非Azure托管配置 a365.config.json
• 在Entra ID中创建代理蓝图
• 配置 OAuth2 + 继承权限
• 配置机器人框架消息终端指向GCP
• 创建代理身份 + 代理用户
• 发布到Microsoft 365应用界面
• 测试端到端的交互过程

先决条件

在开始之前，请确保满足以下Azure/Microsoft 365、Google Cloud Platform （GCP）和本地环境先决条件。

Azure/Microsoft 365先决条件

确认Microsoft Entra租户访问权限并安装以下工具来创建标识、蓝图和注册代理。

• 一个 Microsoft Entra 租户，其中包含：

  • 创建应用程序和代理蓝图的权限或角色（全局管理员或同等职务）
  • 您需要加入 Frontier 预览计划 ，才能提前获得 Microsoft Agent 365 的访问权限。
  • 至少有一个适用于代理用户的 Microsoft 365 许可证可用

• 已安装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。 你可以用任何语言来描述你的代理人。 本文在以下步骤中使用节点18+。

• LLM API 访问：根据你的代理配置或你偏好的模型提供商选择合适的服务：

  • OpenAI API 密钥： 获取 OpenAI API 密钥
  • Azure OpenAI：创建并部署 Azure OpenAI 资源以获取 API 密钥和终结点

创建 Agent 365 代理并将其部署到 Cloud Run

此示例使用了简化版的 Agent 365，该代理：

• 响应GET /
• 接受POST上的机器人框架活动 /api/messages
• 通过代理 365 SDK 使用 JWT 身份验证
• 为简单起见，在单个 index.js 文件中包含所有代码

创建项目

按照这些步骤搭建一个最小 Node.js 代理，运行在Cloud Run上并接受机器人框架活动。

1. 创建项目目录

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

2. 初始化 Node.js 项目

   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公共 URL。

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
   

   该 URL 是 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"
}

下表总结了重要的配置字段及其用途。

领域	Meaning
messagingEndpoint	你的云运行URL + /api/messages
deploymentProjectPath	冲压发生的地方.env

---

构建代理365代理

将代理代码部署到 GCP 终结点后，请按照 代理 365 开发生命周期 中的剩余步骤完成代理 365 代理的设置。 此过程通常包括：

• 在 Microsoft Entra ID 中创建代理标识
• 注册 Bot Framework 消息传送终结点
• 创建代理用户
• 发布到 Microsoft 365 界面

代理 365 CLI 会根据 a365.config.json 配置自动处理大部分这些步骤。

端到端验证代理

使用这些检查来确认 GCP 托管的代理是否可访问、能否接收 Bot Framework 活动，并在 Agent 365 平台上做出正确响应。

验证云运行连接情况

从你的GET向messagingEndpoint值发送a365.config.json请求。

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

响应机构应包括：

GCP Agent is running.

查看云运行日志中的传入的机器人框架消息

你可以查看 Google Cloud 日志浏览器或运行：

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

收到消息后，会看到日志条目，这些条目指示服务器通过代理 365 SDK 接收和处理了活动。

365代理的测试代理上线

根据环境，使用：

• 代理操场
• Teams（如已发布）
• 特工壳牌

你现在可以发送消息并验证你的云运行日志。 若要了解详细信息，请参阅 Learn 如何使用 Microsoft Agent 365 SDK 测试代理，以及使用 Agents Playground 测试工具验证代理的功能。

开发者工作流程

设置完成后，按照以下工作流程进行迭代开发：

1. 本地考试（可选）

   若要在部署到云运行之前在本地测试代理，请确保 .env 文件包含正确的凭据：

   # Start the agent locally
   node index.js
   

   您的代理在 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 365 故障排除指南 包含高层次的故障排除建议、最佳实践以及针对 Agent 365 开发生命周期各阶段的故障排除内容链接。

未达到消息传送终结点

请查看以下详情：

• 端点正是：
  https://<cloud-run-url>/api/messages
• Cloud Run 允许无需认证的访问
• 没有防火墙规则

许可证转让失败

手动分配有效的Microsoft 365边界许可证，或者使用未经许可的用户路径（如果受支持）。