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

重要

你需要成为Frontier 预览计划的一员，才能获取 Microsoft Agent 365 的提前访问权限。边界将你直接与Microsoft最新的 AI 创新联系起来。 Frontier 预览版受客户协议中现有预览条款的约束。由于这些功能仍在开发中，其可用性和功能可能会随时间而变化。

学习如何使用 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 的 Bot Framework 消息终结点
创建代理身份 + 代理用户
发布到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 上的 Bot Framework 活动/api/messages
通过代理 365 SDK 使用 JWT 身份验证
为简单起见，在单个 index.js 文件中包含所有代码

创建项目

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

创建项目目录
```
mkdir gcp-a365-agent
cd gcp-a365-agent
```

初始化 Node.js 项目

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

创造 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。

请使用以下命令将您的项目部署到 Google Cloud Run：

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

完成后，记下你的终点：
```
https://gcp-a365-agent-XXXX-uc.run.app
```
此 URL 是 Agent 365 Dev Tools CLI 在下一步中使用的 messagingEndpoint。

为非 Azure 托管配置

在你的 Cloud Run 项目文件夹中，通过运行 a365.config.json 创建 a365 config init。

{
  "tenantId": "YOUR_TENANT_ID",
  "subscriptionId": "YOUR_AZURE_SUBSCRIPTION_ID",
  "resourceGroup": "a365-gcp-demo",
  "location": "westus",
  "environment": "prod",

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

  "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`	您的 Cloud Run URL + `/api/messages`
`"needDeployment"=false`	告知 CLI'我托管自己的服务器;不要部署到 Azure'
`deploymentProjectPath`	`.env` 处将进行标记

生成 Agent 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.

在云运行日记中查看传入的 Bot Framework 消息

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

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

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

从 Agent 365 界面中测试智能体

根据环境，使用：

智能体操场
Teams（如已发布）
智能体 Shell

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

开发者工作流程

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

本地考试（可选）

若要在部署到云运行之前在本地测试代理，请确保 .env 文件包含正确的凭据：
```
# Start the agent locally
node index.js
```
您的代理在 http://localhost:8080 可用。您可以测试健康状态端点：
```
curl http://localhost:8080/
```
进行代码更改

编辑 index.js 并保存更改。

重新部署到 Google Cloud Run

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

测试和监视

通过 Agent 365 界面测试并监视 Google 云运行日志。

Troubleshooting

使用此部分诊断在 Google Cloud Run 上部署和运行 Agent 365 代理时出现的常见问题。它能帮助你迅速应用修复，以解决连接问题、配置问题和许可问题。

小窍门

Agent 365 故障排除指南包含高层次的故障排除建议、最佳实践以及针对 Agent 365 开发生命周期各阶段的故障排除内容链接。

未达到消息传送终结点

请查看以下详情：

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

许可证转让失败

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

反馈

此页面是否有帮助？

Last updated on 2026-04-08