Zbuduj agenta Agent 365 wdrożonego w Google Cloud Platform (GCP)

Dowiedz się, jak zbudować, hostować, zarejestrować i opublikować agenta Agent 365 uruchomionego na Google Cloud Run, korzystając z Agent 365 CLI. Microsoft Entra & Graph zapewnia tożsamość agenta, uprawnienia i blueprint, natomiast Google Cloud Run zapewnia środowisko uruchomieniowe.

Jeśli wszystko, co chcesz zrobić, to skierować swojego agenta do kodu znajdującego się za punktem końcowym AWS, potrzebujesz tylko tego dodatkowego kroku: Skonfiguruj pod hosting poza Azure, a następnie wykonaj wszystkie pozostałe kroki z Rozpocznij pracę z tworzeniem Agent 365.

Cele

Dowiedz się, jak używać Agent 365 i Microsoft 365 jako warstwy kontrolnej oraz:

Wdróż środowisko uruchomieniowe agenta na Google Cloud Run
Skonfiguruj a365.config.json dla hostingu poza Azure
Utwórz Agent Blueprint w Entra ID
Skonfiguruj OAuth2 oraz dziedziczne uprawnienia
Zarejestruj punkt końcowy komunikacji Bot Framework kierujący na GCP
Utwórz tożsamość agenta i użytkownika agenta
Opublikuj w obszarach aplikacji Microsoft 365
Testowanie interakcji od początku do końca

Wymagania wstępne

Przed rozpoczęciem upewnij się, że spełnione są wymagania wstępne dotyczące Azure / Microsoft 365, Google Cloud Platform (GCP) oraz środowiska lokalnego.

Wymagania wstępne dotyczące platformy Azure / Microsoft 365

Potwierdź dostęp do swojego najemcy Microsoft Entra i zainstaluj następujące narzędzia do tworzenia tożsamości, szablonów oraz rejestracji agenta.

Domena Microsoft Entra zawierająca:
- Uprawnienia lub rola do tworzenia aplikacji i szablonów agentów (Global Administrator lub równoważny)
- Aby uzyskać wczesny dostęp do aplikacji Microsoft Agent 365, musisz uczestniczyć w programie testowym Frontier.
- Co najmniej jedna licencja Microsoft 365 dostępna dla użytkownika Agent 365
Azure CLI zainstalowana i użytkownik zalogowany.
Zainstalowano Agent 365 CLI

Wymagania wstępne usługi GCP

Utworzono projekt GCP
API Cloud Run włączone

gcloud SDK zainstalowany i uwierzytelniony

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

Wymagania wstępne dotyczące środowiska lokalnego

Edytor kodu: dowolny edytor kodu Visual Studio Code jest zalecany.
(Opcjonalnie) Node.js. Możesz użyć dowolnego języka dla swojego agenta. W dalszej części artykułu używany jest Node.js w wersji 18+.
Dostęp do interfejsu API LLM: wybierz odpowiednią usługę na podstawie konfiguracji agenta lub preferowanego dostawcy modelu:
- Klucz API OpenAI: Pobierz swój klucz API OpenAI
- Azure OpenAI: Stwórz i wdroż zasób Azure OpenAI, aby uzyskać klucz API oraz punkt końcowy

Utwórz i wdroż agenta Agent 365 na Cloud Run

Ten przykład używa minimalnego agenta Agent 365, który:

Odpowiada na GET /
Obsługuje działania Bot Framework na POST /api/messages
Wykorzystuje uwierzytelnianie JWT za pomocą Agent 365 SDK
Zawiera cały kod w jednym index.js pliku dla uproszczenia

Tworzenie projektu

Postępuj zgodnie z tymi krokami, aby przygotować minimalnego agenta Node.js, który działa na Cloud Run i obsługuje aktywności Bot Framework.

Utwórz katalog projektu
```
mkdir gcp-a365-agent
cd gcp-a365-agent
```

Zainicjuj projekt Node.js

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

Utwórz element 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}`));

Wdróż do Google Cloud Run

Użyj gcloud run deploy do budowy i uruchomienia usługi w Cloud Run. Po zakończeniu wdrożenia zapisz publiczny adres URL dla swojego messagingEndpoint.

Użyj następujących poleceń, aby wdrożyć swój projekt w Google Cloud Run:

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

Po zakończeniu zwróć uwagę na swój punkt końcowy:
```
https://gcp-a365-agent-XXXX-uc.run.app
```
Ten adres URL jest messagingEndpoint używany przez narzędzie Agent 365 Dev Tools CLI w następnym kroku.

Konfiguracja dla hostingu spoza Azure

Utwórz a365.config.json ręcznie w folderze projektu 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"
}

Poniższa tabela podsumowuje ważne pola konfiguracyjne i ich przeznaczenie.

Pole	Znaczenie
`messagingEndpoint`	Twój adres URL Cloud Run + `/api/messages`
`deploymentProjectPath`	Miejsce, gdzie następuje `.env` stemplowanie

Budowanie agenta Agent 365

Po wdrożeniu kodu agenta na punkt końcowy GCP, wykonaj pozostałe kroki z cyklu rozwoju Agent 365 aby ukończyć konfigurację swojego agenta Agent 365. Ten proces obejmuje:

Tworzenie tożsamości agenta w Microsoft Entra ID
Rejestracja punktu końcowego komunikatów Bot Framework
Tworzenie użytkownika agenta
Publikowanie na powierzchniach Microsoft 365

Agent 365 CLI wykonuje większość tych kroków automatycznie na podstawie konfiguracji a365.config.json.

Sprawdź działanie agenta od początku do końca

Użyj tych kontroli, aby potwierdzić, że Twój agent hostowany na GCP jest osiągalny, odbiera aktywności Bot Framework i poprawnie odpowiada na różnych platformach Agent 365.

Zweryfikuj łączność Cloud Run

Wyślij żądanie GET do wartości messagingEndpoint z a365.config.json:

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

Treść odpowiedzi powinna zawierać:

GCP Agent is running.

Sprawdź logi Cloud Run pod kątem przychodzących wiadomości Bot Framework

Możesz skorzystać z Google Cloud Log Explorer lub uruchomić:

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

Po otrzymaniu wiadomości przez agenta zobaczysz wpisy w logach wskazujące, że serwer otrzymał i przetworzył aktywność za pomocą Agent 365 SDK.

Agent testowy z powierzchni Agent 365

W zależności od środowiska użyj:

Środowisko testowe agentów
Teams (jeśli zostały opublikowane)
Agent Shell

Możesz teraz wysyłać wiadomości i sprawdzać logi Cloud Run. Aby uzyskać więcej informacji, zobacz: Dowiedz się, jak testować agentów za pomocą Microsoft Agent 365 SDK i weryfikować funkcjonalność swojego agenta przy użyciu narzędzia testowego Agents Playground.

Przebieg pracy dewelopera

Po zakończeniu konfiguracji postępuj zgodnie z tym przepływem pracy dla iteracyjnego rozwoju:

Test lokalny (opcjonalnie)

Aby przetestować agenta lokalnie przed wdrożeniem do Cloud Run, upewnij się, że plik .env zawiera poprawne dane uwierzytelniające:
```
# Start the agent locally
node index.js
```
Twój agent jest dostępny pod adresem http://localhost:8080. Możesz przetestować punkt końcowy health:
```
curl http://localhost:8080/
```
Wprowadź zmiany w kodzie

Edytuj index.js i zapisz zmiany.

Wdróż ponownie do Google Cloud Run

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

Testowanie i monitorowanie

Przetestuj przez Agent 365 Surface i monitoruj logi Google Cloud Run.

Rozwiązywanie problemów

Skorzystaj z tej sekcji, aby zdiagnozować typowe problemy podczas wdrażania i uruchamiania agenta Agent 365 w Google Cloud Run. Pomaga szybko wdrożyć poprawki dotyczące problemów z łącznością, konfiguracją i licencjonowaniem.

Wskazówka

Przewodnik po rozwiązywaniu problemów Agent 365 zawiera wysokopoziomowe zalecenia dotyczące rozwiązywania problemów, najlepsze praktyki oraz odnośniki do treści dotyczących rozwiązywania problemów dla każdego etapu cyklu rozwoju Agent 365.

Punkt końcowy komunikacji jest nieosiągalny

Sprawdź poniższe informacje:

Punkt końcowy to dokładnie:
https://<cloud-run-url>/api/messages
Cloud Run umożliwia nieuwierzytelniony dostęp
Brak reguł zapory sieciowej

Przypisanie licencji kończy się niepowodzeniem

Przypisz prawidłową licencję Microsoft 365 Frontier ręcznie lub użyj ścieżki dla użytkownika bez licencji, jeśli jest to obsługiwane.

Opinia

Czy ta strona była pomocna?

Last updated on 2026-07-30