Google Cloud Platform (GCP)'de konuşlandırılmış bir Agent 365 aracıyı oluşturun

Google Cloud Run üzerinde çalışan bir Agent 365 aracısını Agent 365 CLI kullanarak nasıl oluşturacağınızı, barındıracağınızı, kaydedeceğinizi ve yayınlayacağınızı öğrenin. Microsoft Entra & Graph aracı kimliği, izinler ve blueprint'i sağlarken, Google Cloud Run çalışma zamanını sağlar.

Eğer tek yapmak istediğiniz, aracınızı AWS uç noktasının arkasındaki kodunuza yönlendirmekse, yalnızca şu ek adımı uygulamanız gerekir: Azure olmayan barındırma için yapılandırın ve ardından Agent 365 geliştirmeye başlama adımından itibaren tüm diğer adımları takip edin.

Hedefler

Agent 365 ve Microsoft 365'i 'kontrol düzlemi' olarak kullanmayı öğrenin ve şunları yapın:

  • Aracı çalışma zamanını Google Cloud Run üzerinde dağıtın
  • Azure dışı barındırma için a365.config.json yapılandırın
  • Entra ID'de Aracı Taslağı oluşturun
  • OAuth2 + kalıtılabilir izinleri yapılandır
  • GCP'ye yönlendirilmiş Bot Framework mesajlaşma uç noktasını kaydet
  • Aracı Kimliği + Aracı Kullanıcısı Oluştur
  • Microsoft 365 uygulama yüzeylerine yayınla
  • Uçtan uca etkileşimleri test edin

Ön koşullar

Başlamadan önce, aşağıdaki Azure / Microsoft 365, Google Cloud Platform (GCP) ve yerel ortam ön koşullarının karşılandığından emin olun.

Azure / Microsoft 365 ön koşulları

Microsoft Entra kiracınıza erişiminizi doğrulayın ve kimlikler, şablonlar oluşturmak ve aracınızı kaydetmek için aşağıdaki araçları yükleyin.

GCP önkoşulları

  • GCP projesi oluşturuldu

  • Cloud Run API etkinleştirilmiş

  • gcloud SDK yüklenmiş ve kimliği doğrulanmış

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

Yerel geliştirme ortamı için ön koşullar

Agent 365 aracını oluşturun ve Cloud Run'a dağıtın

Bu örnek, aşağıdaki gibi minimal bir Agent 365 aracıyı kullanır:

  • GET'e yanıt verir /
  • POST isteği ile Bot Framework etkinliklerini kabul eder /api/messages
  • Agent 365 SDK ile JWT kimlik doğrulaması kullanır
  • Sadelik için tüm kod tek bir index.js dosyada içerir

Proje oluşturma

Cloud Run üzerinde çalışan ve Bot Framework aktivitelerini kabul eden minimal bir Node.js aracının iskeletini oluşturmak için bu adımları izleyin.

  1. Proje dizinini oluştur

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

  2. Node projesini başlatın

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

  3. index.js oluştur

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

Projenizi Google Cloud Run'a dağıtın

Cloud Run'da hizmeti oluşturmak ve çalıştırmak için gcloud run deploy kullanın. Dağıtım tamamlandığında, messagingEndpoint için herkese açık URL'yi not edin.

  1. Projenizi Google Cloud Run'a dağıtmak için aşağıdaki komutları kullanın:

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

  2. Tamamladığınızda, uç noktanızı not edin:

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

    Bu URL, Agent 365 Dev Tools CLI'nin bir sonraki adımda kullanacağı messagingEndpoint'dir.

Azure dışı barındırma için yapılandırma

Cloud Run proje klasörünüzde a365.config.json'i elle oluşturun:

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

Aşağıdaki tablo, önemli yapılandırma alanlarını ve amaçlarını özetlemektedir.

Alan Anlamı
messagingEndpoint Cloud Run URL'niz + /api/messages
deploymentProjectPath .env damgalama işleminin gerçekleştiği yer

Agent 365 aracısı oluştur

Aracı kodunuzu GCP uç noktanıza dağıttıktan sonra, Agent 365 Geliştirme Yaşam Döngüsü'ndeki kalan adımları izleyerek Agent 365 aracınızın kurulumunu tamamlayın. Bu süreç şunları içerir:

  • Microsoft Entra ID'de aracı kimliğinin oluşturulması
  • Bot Framework mesajlaşma uç noktasının kaydedilmesi
  • Aracı kullanıcısının oluşturulması
  • Microsoft 365 platformlarına yayınlama

Agent 365 CLI, a365.config.json yapılandırmanıza göre bu adımların çoğunu otomatik olarak gerçekleştirir.

Aracının uçtan uca doğrulanmasını sağlayın

GCP üzerinde barındırılan Agent 365 aracınızın ulaşılabilir olduğunu, Bot Framework etkinliklerini aldığını ve Agent 365 yüzeylerinde doğru şekilde yanıt verdiğini doğrulamak için bu denetimleri kullanın.

Cloud Run bağlantısı doğrulama

a365.config.json'ünüzden messagingEndpoint değerine GET isteği gönderin:

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

Yanıt gövdesi şunları içermelidir:

GCP Agent is running.

Cloud Run günlüklerinde gelen Bot Framework mesajlarını kontrol edin

Google Cloud Log Explorer'ı inceleyebilir veya ilgili komutu çalıştırabilirsiniz:

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

Bir mesaj aracınıza ulaştıktan sonra, sunucunun Agent 365 SDK üzerinden etkinliği alıp işlediğini gösteren günlük kayıtlarını görebilirsiniz.

Agent 365 yüzeylerinden test aracısı

Ortamınıza bağlı olarak aşağıdaki seçenekleri kullanabilirsiniz:

  • Aracı Deneme Alanı
  • Teams (yayınlanırsa)
  • Aracı Kabuğu

Artık mesaj gönderebilir ve Cloud Run günlüklerinizi inceleyebilirsiniz. Daha fazla bilgi için, Microsoft Agent 365 SDK kullanarak aracıları nasıl test edeceğinizi ve Agents Playground test aracıyla aracınızın işlevselliğini nasıl doğrulayacağınızı öğrenin.

Geliştirici iş akışı

Kurulum tamamlandıktan sonra, yinelemeli geliştirme için bu iş akışını izleyin:

  1. Yerelde test et (isteğe bağlı)

    Cloud Run'a dağıtmadan önce aracınızı yerel olarak test etmek için, .env dosyanızda doğru kimlik bilgileri bulunduğundan emin olun:

    # Start the agent locally
node index.js

    Aracınız http://localhost:8080 adresinden ulaşılabilir. Sağlık uç noktasını test edebilirsiniz:

    curl http://localhost:8080/

  2. Kod değişikliklerinizi yapın

    index.js'i düzenleyin ve değişikliklerinizi kaydedin.

  3. Google Cloud Run'a yeniden dağıtın

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

  4. Test etme ve izleme

    Agent 365 yüzeylerinde test edin ve Google Cloud Run günlüklerini izleyin.

Sorun giderme

Bu bölümü, Google Cloud Run üzerinde Agent 365 aracısını dağıtırken ve çalıştırırken karşılaşabileceğiniz yaygın sorunları teşhis etmek için kullanın. Bağlantı, yapılandırma ve lisanslama sorunları için hızlıca düzeltmeleri uygulamanıza yardımcı olur.

İpucu

Agent 365 Sorun Giderme Kılavuzu yüksek seviyeli sorun giderme önerileri, en iyi uygulamalar ve Agent 365 geliştirme yaşam döngüsünün her aşamasına yönelik sorun giderme içeriğine bağlantılar sunar.

Mesajlaşma uç noktasına erişilemiyor

Lütfen aşağıdaki ayrıntıları inceleyin:

  • Uç nokta tam olarak şudur:
    https://<cloud-run-url>/api/messages
  • Cloud Run kimlik doğrulamasız erişime izin verir
  • Güvenlik duvarı kuralları yok

Lisans ataması başarısız olur

Geçerli bir Microsoft 365 Frontier lisansını manuel olarak atayın veya destekleniyorsa lisanssız kullanıcı yolunu kullanın.

  • Last updated on