Создайте агент Agent 365, развернутый в Google Cloud Platform (GCP)

Узнайте, как создать, разместить, зарегистрировать и опубликовать агент Agent 365, работающий на Google Cloud Run, используя CLI. Microsoft Entra & Graph предоставляет идентификатор агента, права и чертеж, а Google Cloud Run обеспечивает среду выполнения.

Если всё, что вы хотите — это направить агента на ваш код, расположенный за AWS-конечной точкой, вам понадобится только следующий шаг: настройте для хостинга без Azure , а затем выполните все остальные шаги из Get Start with Agent 365 development.

Цели

Узнайте, как использовать Agent 365 и Microsoft 365 в качестве «управляющей плоскости» и:

• Развертывание среды выполнения агентов на Google Cloud Run
• Configure a365.config.json for non-Azure hosting
• Создать Agent Blueprint в Entra ID
• Настройте OAuth2 + наследуемые разрешения
• Конечная точка сообщений Register Bot Framework указывает на GCP
• Создать идентичность агента + Пользователь агента
• Опубликовать поверхности приложений Microsoft 365
• Взаимодействия тестов от конца до конца

Предпосылки

Перед началом убедитесь, что выполнены следующие требования Azure / Microsoft 365, Google Cloud Platform (GCP) и локальной среды.

Azure / Microsoft 365 prerequisites

Подтвердите доступ к вашему арендатору Microsoft Entra и установите следующие инструменты для создания идентичностей, чертежей и регистрации вашего агента.

• Арендатор Microsoft Entra с:

  • Разрешение или роль на создание приложений и чертежей агентов (глобальный администратор или эквивалент)
  • Чтобы получить ранний доступ к Microsoft Agent 365, вам нужно попасть в программу предварительного просмотра Frontier .
  • По крайней мере одна лицензия Microsoft 365 доступна для пользователя агента

• Установил Azure CLI и вошёл в систему.

• Установлен агент 365 CLI

Требования к GCP

• Проект GCP создан

• Включен API Cloud Run

• Установлен и аутентифицирован 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: Выберите подходящий сервис на основе конфигурации вашего агента или предпочтительного провайдера модели:

  • Ключ API OpenAI: получение ключа API OpenAI
  • Azure OpenAI: создание и развертывание ресурса Azure OpenAI для получения ключа и конечной точки API

Создать и развернуть агент Agent 365 в Cloud Run

В этом примере используется минимальный агент Agent 365, который:

• Отвечает на GET /
• Принимает деятельность Bot Framework на POST /api/messages
• Использует аутентификацию JWT через SDK Agent 365
• Содержит весь код в одном index.js файле для простоты

Создание проекта

Следуйте этим шагам, чтобы создать минимальный Node.js-агент, который работает на 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. Когда развертывание завершится, укажите публичный URL для вашего 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
   

   Этот URL используется messagingEndpoint CLI Agent 365 Dev Tools на следующем этапе.

Configure for Non-Azure Hosting

Создайте a365.config.json его вручную в папке проекта Cloud Run:

{
  "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	Ваш облачный URL + /api/messages
deploymentProjectPath	Где .env происходит штамповка

---

Агент Build 365

После развертывания кода агента на вашей GCP-конечной точке выполните оставшиеся шаги из жизненного цикла разработки агента 365 , чтобы завершить настройку вашего агента 365. Эта процесс включает:

• Создание идентичности агента в Microsoft Entra ID
• Регистрация конечной точки обмена сообщениями Bot Framework
• Создание пользователя-агента
• Публикация на поверхностях Microsoft 365

CLI Agent 365 выполняет большинство этих этапов автоматически в зависимости от вашей a365.config.json конфигурации.

Проверьте агент от конца до конца

Используйте эти проверки, чтобы убедиться, что ваш агент, размещённый в GCP, доступен, получает активности 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 Cloud Log Explorer или запустить:

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

После того как сообщение приходит к вашему агенту, вы видите записи в журнале, указывающие, что сервер получил и обработал активность через SDK Agent 365.

Испытательный агент с поверхностей Agent 365

В зависимости от вашей среды, используйте следующее:

• Детская площадка агентов
• Команды (если опубликованы)
• Агент Шелл

Теперь вы можете отправлять сообщения и проверять свои логи Cloud Run. Чтобы узнать больше, см. раздел «Узнайте, как тестировать агенты с помощью Microsoft Agent 365 SDK и проверять функциональность вашего агента с помощью инструмента тестирования Agents Playground».

Рабочий процесс разработчика

После завершения настройки следуйте следующему рабочему процессу для итеративной разработки:

1. Локальное тестирование (по желанию)

   Чтобы локально протестировать вашего агента перед развертыванием в Cloud Run, убедитесь, что в .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.

Устранение неполадок

Используйте этот раздел для диагностики распространённых проблем при развертывании и запуске вашего агента Agent 365 на Google Cloud Run. Это помогает быстро исправить проблемы с подключением, конфигурацией и лицензированием.

Tip

Руководство по устранению неполадок Agent 365 содержит рекомендации по решению неполадок на высоком уровне, лучшие практики и ссылки на контент по устранению неполадок для каждой части жизненного цикла разработки Agent 365.

Конечная точка обмена сообщениями не достигнута

Ознакомьтесь со следующими деталями:

• Конечная точка именно такая:
  https://<cloud-run-url>/api/messages
• Cloud Run позволяет получить доступ без аутентификации
• Нет правил межсетевого экрана

Передача лицензии не проходит

Назначьте действительную лицензию Microsoft 365 Frontier вручную или используйте нелицензированный пользовательский путь для пользователя, если он поддерживается.