Bangun agen Agent 365 yang disebarkan di Google Cloud Platform (GCP)

Pelajari cara membangun, meng-host, dan memublikasikan agen Agent 365 yang berjalan di Google Cloud Run, menggunakan Agent 365 CLI. Microsoft Entra & Graph menyediakan identitas, izin, dan blueprint agen, sementara Google Cloud Run menyediakan runtime.

Jika yang ingin Anda lakukan hanyalah mengarahkan agen Anda ke kode yang berada di balik titik akhir AWS, cukup lakukan langkah tambahan berikut: Konfigurasikan untuk hosting non-Azure dan kemudian ikuti semua langkah dari Memulai pengembangan Agent 365.

Sasaran

Pelajari cara menggunakan Agent 365 dan Microsoft 365 sebagai 'sarana kontrol' dan:

Menyebarkan runtime agen di Google Cloud Run
Mengonfigurasi a365.config.json untuk hosting non-Azure
Buat Blueprint Agen di Entra ID
Konfigurasikan OAuth2 + izin yang dapat diwariskan
Daftarkan titik akhir olahpesan Bot Framework yang mengarah ke GCP
Buat Identitas Agen dan Pengguna Agen
Publikasikan ke area aplikasi Microsoft 365
Menguji interaksi menyeluruh

Prasyarat

Sebelum memulai, pastikan prasyarat lingkungan Azure/Microsoft 365, Google Cloud Platform (GCP), dan lokal berikut terpenuhi.

Prasyarat Azure / Microsoft 365

Konfirmasikan akses penyewa Microsoft Entra Anda dan instal alat berikut untuk membuat identitas, blueprint, dan mendaftarkan agen Anda.

Penyewa Microsoft Entra dengan:
- Izin atau peran untuk membuat aplikasi dan blueprint agen (Administrator Global atau setara)
- Anda perlu menjadi bagian dari program pratinjau Frontier untuk mendapatkan akses awal ke Microsoft Agent 365.
- Setidaknya satu lisensi Microsoft 365 tersedia untuk pengguna Agen
Azure CLI terinstal dan masuk.
Agent 365 CLI terinstal

Prasyarat GCP

Proyek GCP dibuat
Cloud Run API diaktifkan

gcloud SDK diinstal dan diautentikasi

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

Prasyarat lingkungan pengembangan lokal

Editor Kode: Editor kode apa pun pilihan Anda. Visual Studio Code direkomendasikan.
(Opsional) Node.js. Anda dapat menggunakan bahasa apa pun untuk agen Anda. Artikel ini menggunakan Node 18+ dalam langkah-langkah berikut.
Akses LLM API: Pilih layanan yang sesuai berdasarkan konfigurasi agen Anda atau penyedia model pilihan Anda:
- Kunci OpenAI API: Dapatkan kunci OpenAI API Anda
- Azure OpenAI: Buat dan sebarkan sumber daya Azure OpenAI untuk mendapatkan kunci API dan titik akhir Anda

Membuat dan menyebarkan agen Agent 365 ke Cloud Run

Contoh ini menggunakan agen Agent 365 minimal yang:

Menanggapi GET /
Menerima aktivitas Bot Framework di POST /api/messages
Menggunakan autentikasi JWT melalui Agent 365 SDK
Berisi semua kode dalam satu file index.js demi kesederhanaan

Membuat proyek

Ikuti langkah-langkah ini untuk membuat kerangka agen Node.js minimal yang berjalan di Cloud Run dan menerima aktivitas Bot Framework.

Membuat direktori proyek
```
mkdir gcp-a365-agent
cd gcp-a365-agent
```

Menginisialisasi proyek Node

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

Buat 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}`));

Menyebarkan ke Google Cloud Run

Gunakan gcloud run deploy untuk membangun dan menjalankan layanan di Cloud Run. Setelah penyebaran selesai, catat URL publik untuk messagingEndpoint.

Gunakan perintah berikut untuk menyebarkan proyek Anda ke Google Cloud Run:

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

Setelah selesai, catat titik akhir Anda:
```
https://gcp-a365-agent-XXXX-uc.run.app
```
URL ini adalah messagingEndpoint yang digunakan oleh CLI Agent 365 Dev Tools pada langkah berikutnya.

Konfigurasi untuk Hosting Non-Azure

Buat a365.config.json secara manual di folder proyek Cloud Run Anda:

{
  "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"
}

Tabel berikut merangkum bidang konfigurasi penting dan tujuannya.

Bidang	Makna
`messagingEndpoint`	URL Cloud Run Anda + `/api/messages`
`deploymentProjectPath`	Tempat terjadinya proses stamping `.env`

Buat agen Agent 365

Setelah menyebarkan kode agen ke titik akhir GCP Anda, ikuti langkah-langkah yang tersisa dari Siklus Pengembangan Agent 365 untuk menyelesaikan penyiapan agen Agent 365 Anda. Prosesnya meliputi:

Membuat identitas agen di Microsoft Entra ID
Mendaftarkan titik akhir olahpesan Bot Framework
Membuat pengguna agen
Memublikasikan ke permukaan Microsoft 365

Agent 365 CLI menangani sebagian besar langkah ini secara otomatis berdasarkan konfigurasi a365.config.json Anda.

Verifikasi agen secara menyeluruh

Gunakan pemeriksaan berikut untuk memastikan agen yang di-host di GCP dapat dijangkau, menerima aktivitas Bot Framework, dan merespons dengan benar di seluruh permukaan Agent 365.

Verifikasi konektivitas Cloud Run

Kirim permintaan GET ke nilai messagingEndpoint dari a365.config.json:

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

Badan respons harus berisi:

GCP Agent is running.

Periksa log Cloud Run untuk pesan Bot Framework yang masuk

Anda dapat memeriksa Google Cloud Log Explorer atau menjalankan:

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

Setelah pesan masuk ke agen Anda, Anda akan melihat entri log yang menunjukkan bahwa server telah menerima dan memproses aktivitas melalui Agent 365 SDK.

Agen uji dari permukaan Agent 365

Tergantung pada lingkungan Anda, gunakan:

Agents Playground
Teams (jika dipublikasikan)
Agent Shell

Sekarang Anda dapat mengirim pesan dan memverifikasi log Cloud Run Anda. Untuk mempelajari selengkapnya, lihat Cara menguji agen menggunakan Microsoft Agent 365 SDK dan memvalidasi fungsionalitas agen Anda dengan alat pengujian Agents Playground.

Alur kerja pengembang

Setelah penyiapan selesai, ikuti alur kerja ini untuk pengembangan berulang:

Uji secara lokal (opsional)

Untuk menguji agen secara lokal sebelum penyebaran ke Cloud Run, pastikan file .env Anda berisi kredensial yang benar:
```
# Start the agent locally
node index.js
```
Agen Anda tersedia di http://localhost:8080. Anda dapat menguji titik akhir kesehatan:
```
curl http://localhost:8080/
```
Buat perubahan kode Anda

Edit index.js dan simpan perubahan Anda.

Menyebarkan ulang ke Google Cloud Run

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

Menguji dan memantau

Uji melalui platform Agent 365 dan pantau log Google Cloud Run.

Pemecahan masalah

Gunakan bagian ini untuk mendiagnosis masalah umum saat melakukan penyebaran dan menjalankan agen Agent 365 di Google Cloud Run. Ini membantu Anda dengan cepat menerapkan perbaikan untuk masalah konektivitas, konfigurasi, dan lisensi.

Kiat

Panduan Pemecahan Masalah Agent 365 berisi rekomendasi pemecahan masalah tingkat tinggi, praktik terbaik, dan tautan ke konten pemecahan masalah untuk setiap bagian dari siklus hidup pengembangan Agent 365.

Titik akhir olahpesan tidak tercapai

Periksa rincian berikut:

Titik akhir tepatnya:
https://<cloud-run-url>/api/messages
Cloud Run mengizinkan akses tanpa autentikasi
Tidak ada aturan firewall

Penetapan lisensi gagal

Tetapkan lisensi frontier Microsoft 365 yang valid secara manual, atau gunakan jalur pengguna tanpa lisensi jika didukung.

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2026-07-31