Amazon Web Services (AWS) üzerinde dağıtılmış bir Agent 365 aracısı oluşturun

AWS Elastic Beanstalk ü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ımlayacağınızı öğrenin. Microsoft Entra ve Graph, aracı kimliği, izinler ve blueprint'i sağlarken, AWS Elastic Beanstalk çalışma zamanını sağlar.

Aracınızı AWS uç noktasının arkasında bulunan kodunuza yönlendirmek istiyorsanız, yalnızca şu adımı uygulamanız yeterlidir: Azure dışı barındırma için yapılandırma. Ardından, Agent 365 geliştirmeye başlama bölümündeki tüm diğer adımları takip edin.

Hedefler

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

  • Aracı çalışma zamanını AWS Elastic Beanstalk ü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
  • AWS'ye yönlendirilmiş Bot Framework mesajlaşma uç noktasını kaydet
  • Aracı Kimliği + Aracı Kullanıcısı Oluştur
  • (İsteğe bağlı) 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, AWS ve yerel ortam önkoş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.

Amazon Web Services (AWS) ön koşulları

Aşağıdaki AWS hizmetleri ve araçlarının Elastic Beanstalk ortamınızı dağıtmak ve yönetmek için kurulduğundan emin olun.

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

Aracıyı oluşturmak, çalıştırmak ve dağıtmak için aşağıdaki araçları yerel olarak kurun ve yapılandırın.

.NET aracısı oluşturun ve dağıtın

Aşağıdaki talimatlar, minimum bir aracı nasıl oluşturulacağını açıklar:

  • GET'e yanıt verir /
  • POST isteği ile Bot Framework etkinliklerini kabul eder /api/messages

Proje dizini oluştur

mkdir aws-a365-agent
cd aws-a365-agent

.NET projesini başlat

Deneyiminizi kolaylaştırmak için, bu makale önceden hazırlanmış bir örnek proje kullanmaktadır. Agent365 Samples deposunu klonlayın, DotNet\semantic-kernel\sample-agent örneğine gidin.

Semantik Çekirdek Örnek Aracıı - C#/.NET örneği şunları içerir:

  • Minimal bir ASP.NET Core Web API
  • Bot Framework mesaj işleyicisi adresinde /api/messages
  • Sağlık kontrolü uç noktası şu adreste:/
  • Yapay Zeka yetenekleri için Semantik Çekirdek entegrasyonu

dotnet\semantic-kernel\sample-agent adresine gidin ve projenin başarıyla derlendiğini doğrulayın:

dotnet restore
dotnet build

Modeli yapılandırın

Adım 2: LLM yapılandırması bölümündeki yönergeleri izleyerek projeyi Open API anahtarınızı kullanarak yapılandırın.

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

  1. AWS’ye dağıtmadan önce, aracınızı yerel olarak test edin:

    # Run the application
dotnet run

  2. Uç noktaları başka bir terminalde test edin:

    # Test agent endpoint locally
curl http://localhost:3978

  3. Yerel sunucuyu durdurmak için Ctrl+C tuşuna basın.

Derleme ve dağıtma

Bu örnek uygulamayı derleyip dağıtmak için tercih ettiğiniz seçeneği seçin:

Seçenek A: Visual Studio'dan inşa et ve dağıt

Visual Studio için AWS Toolkit'i kullanarak uygulamayı rehberli bir sihirbaz kullanarak Elastic Beanstalk'a yayınlayın.

  1. Çözüm Gezgini'nde projenize sağ tıklayın.

  2. AWS Elastic Beanstalk'a Yayınla'yı seçin.

  3. Beanstalk Dağıtım Sihirbazı'nı izleyin:

    • AWS kimlik bilgileri profilinizi seçin.
    • Bölge Seçin (örneğin, us-east-1).
    • Platform'u (.NET Core on Linux) seçin.
    • Ortam ayarlarını yapılandırın.

  4. Dağıt'ı seçin.

Sihirbaz uygulamanızı AWS'ye derler, paketler ve dağıtır.

Seçenek B: CLI ile AWS Elastic Beanstalk'a derle ve dağıt

Elastic Beanstalk CLI'yı kullanarak .NET aracısını 64 bit Amazon Linux 2 ortamına paketleyip dağıtın. AWS CLI ve EB CLI'nin kurulup yapılandırıldığından emin olun. Uygulama, Beanstalk tarafından belirlenen PORT ortam değişkenine bağlanır.

  1. .NET uygulamanızı oluşturun ve yayınlayın:

    # Publish for Linux runtime (AWS Elastic Beanstalk uses Amazon Linux)
dotnet publish -c Release -o ./publish --runtime linux-x64

    Aşağıdaki içerikle Procfile oluşturun.

    web: dotnet ./SemanticKernelSampleAgent.dll

  2. Elastic Beanstalk'ı .NET için başlatın. Bölge ve Platform seçmeniz isteniyor:

    eb init

  3. Seçin:

    • Platform: 64bit-amazon-linux-2023-v3.7.0-running-.net-8
    • Bölge: Tercih ettiğiniz AWS bölgesi (örneğin: us-east-1)

  4. Bir dağıtım paketi oluşturun ve dağıtın:

    cd publish
zip -r ../deploy.zip .
cd ..
eb create aws-a365-agent-env
eb deploy

    Bu komut:

    • Bir Elastic Beanstalk uygulaması oluşturur.
    • Yük dengeleyici ile bir ortam oluşturur.
    • Uygulamanızı dağıtır.
    • Gerekli AWS kaynaklarını sağlar.

  5. Kurulum tamamlandığında, Elastic Beanstalk uç noktasını edinin:

    eb status

    Uç noktanızı not edin. Şuna benzer şekilde görünecektir:

    http://aws-a365-agent-env.us-east-1.elasticbeanstalk.com

    Bu uç nokta, Agent 365 Geliştirici Araçları CLI tarafından kullanılan messagingEndpoint uç noktasıdır.

Not

Üretim ortamları için, Elastic Beanstalk'ta SSL/TLS sertifikası ekleyerek HTTPS'yi yapılandırın. Bot Framework, üretim uç noktaları için HTTPS gerektirir.

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

Elastic Beanstalk proje klasörünüzde a365.config.json dosyasını manuel olarak oluşturun.

Önemli

Azure dışı barındırma için, messagingEndpoint değerini /api/messages yolu ile Elastic Beanstalk URL'nize ayarlayın.

a365.config.json dosyası şöyle görünmelidir:

{
  "tenantId": "YOUR_TENANT_ID",
  "environment": "prod",

  "messagingEndpoint": "http://aws-a365-agent-env.us-east-1.elasticbeanstalk.com/api/messages",

  "agentIdentityDisplayName": "MyAwsAgent Identity",
  "agentBlueprintDisplayName": "MyAwsAgent Blueprint",
  "agentUserDisplayName": "MyAwsAgent User",
  "agentUserPrincipalName": "myawsagent@testTenant.onmicrosoft.com",
  "agentUserUsageLocation": "US",
  "managerEmail": "myManager@testTenant.onmicrosoft.com",

  "deploymentProjectPath": ".",
  "agentDescription": "AWS-hosted Agent 365 Agent"
}

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

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

Agent 365 aracısı oluştur

Aracı kodunuz bir AWS uç noktasında çalıştıktan sonra, Agent 365 geliştirme ile başlama rehberindeki kalan adımları takip ederek Agent 365 aracınızı kurun.

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

AWS ü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.

Elastic Beanstalk bağlantısını doğrulayın

Elastic Beanstalk endpoint'inize bir GET isteği gönderin.

curl http://aws-a365-agent-env.us-east-1.elasticbeanstalk.com/

İstek şu mesajı döndürmelidir:

AWS Agent is running.

Gelen Bot Framework mesajları için Elastic Beanstalk loglarını kontrol edin.

Elastic Beanstalk loglarını kullanarak, aracınızın Bot Framework etkinliklerini alıp doğru şekilde yanıt verdiğini doğrulayın.

eb logs

Ya da günlük kayıtlarını gerçek zamanlı olarak izleyebilirsiniz:

eb logs --stream

Bir mesaj aracınıza ulaştığında şunları göreceksiniz:

POST 200 /api/messages
Received activity: { ... }

Agent 365 yüzeylerinden test aracısı

Ortamınıza bağlı olarak, aracınızı farklı platformlardan test edebilirsiniz:

  • Aracı Deneme Alanı
  • Teams (yayınlanırsa)
  • Aracı Kabuğu
  • Federasyonlu yüzeyler

Mesaj gönderebilir ve Elastic Beanstalk kayıtlarınızı kontrol edebilirsiniz. Microsoft Agent 365 SDK'yi kullanarak aracıları nasıl test edeceğinizi ve Aracılar 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:

Yerel olarak geliştirin ve test edin

watch mode'u otomatik yeniden yükleme ile hızlı geliştirme için kullanın:

# Automatically rebuild and restart on file changes
dotnet watch run

Kod değişikliklerinizi yapın, kaydedin ve dağıtmadan önce yerel olarak test edin.

Derleyin ve AWS Elastic Beanstalk'a yeniden dağıtın

Değişiklikleri dağıtmaya hazır olduğunuzda:

# Clean previous builds (optional but recommended)
dotnet clean

# Publish optimized release build
dotnet publish -c Release -o ./publish --runtime linux-x64

# Create deployment package
cd publish
zip -r ../deploy.zip .
cd ..

# Deploy to AWS
eb deploy

Test etme ve izleme

Agent 365 yüzeylerini kullanarak test edin ve Elastic Beanstalk loglarını izleyin:

# Stream logs in real-time
eb logs --stream

Kimliğinizi, blueprint'i, bot uç noktanızı veya izinlerinizi yeniden oluşturmanıza gerek yok.

Sorun giderme

Bu bölümü, AWS Elastic Beanstalk üzerinde bir Agent 365 aracıı dağıtıp çalıştırırken sık karşılaşılan sorunları teşhis etmek ve çözmek için kullanın. Bağlantı ve sağlık kontrollerini kapsar. Ayrıca port bağlama, derleme hataları ve lisanslama sorunlarını da kapsar.

İ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ı istekleri almıyor

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

  • Uç noktanız tam olarak şudur:
    http://<your-app>.elasticbeanstalk.com/api/messages
  • Elastic Beanstalk ortamınız sağlıklı. eb health kullanarak kontrolü gerçekleştirin.
  • Güvenlik grubunuz giriş HTTP veya HTTPS trafiğine izin verir.
  • Güvenlik duvarı kuralları veya VPC kısıtlamaları bulunmamaktadır.

Uygulama sağlığı sorunları

Ortam sağlığı kontrolü:

eb health --refresh

Ayrıntılı kayıtları görüntüle:

eb logs

Port bağlama sorunları

Uygulamanızın PORT ortam değişkeniyle belirtilen bağlantı noktasında dinlediğinden emin olun. Elastic Beanstalk bu değeri otomatik olarak ayarlıyor.

.NET derleme veya çalışma zamanı sorunları

Bu komutları kullanarak derleme hatalarını kontrol edin:

# Clean and rebuild
dotnet clean
dotnet build --verbosity detailed

.NET sürümünü doğrulayın:

dotnet --version
dotnet --list-sdks

Paket sorunlarını kontrol edin:

# List installed packages
dotnet list package

# Update packages
dotnet restore --force

Lisans ataması başarısız olur

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

  • Last updated on