Membangun Agent 365 yang disebarkan di Amazon Web Services (AWS)

Pelajari cara membangun, meng-host, mendaftarkan, dan memublikasikan agen Agent 365 yang berjalan di AWS Elastic Beanstalk, menggunakan Agent 365 CLI. Microsoft Entra dan Graph menyediakan identitas, izin, dan blueprint agen, sementara AWS Elastic Beanstalk menyediakan runtime.

Jika Anda ingin mengarahkan agen ke kode Anda yang berada di balik titik akhir AWS, Anda hanya perlu mengikuti langkah berikut: Konfigurasikan untuk hosting non-azure. Kemudian, ikuti semua langkah lainnya dari Memulai pengembangan Agent 365.

Sasaran

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

  • Menyebarkan runtime agen di AWS Elastic Beanstalk
  • 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 AWS
  • Buat Identitas Agen dan Pengguna Agen
  • (Opsional) Publikasikan ke area aplikasi Microsoft 365
  • Menguji interaksi menyeluruh

Prasyarat

Sebelum memulai, pastikan prasyarat lingkungan Azure / Microsoft 365, AWS, 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.

Prasyarat Amazon Web Services (AWS)

Pastikan layanan dan alat AWS berikut telah disiapkan untuk menyebarkan dan mengelola lingkungan Elastic Beanstalk Anda.

Prasyarat lingkungan pengembangan lokal

Instal dan konfigurasikan alat berikut secara lokal untuk membangun, menjalankan, dan menyebarkan agen.

Membuat dan menyebarkan agen .NET

Petunjuk berikut menjelaskan cara membuat agen minimal yang:

  • Menanggapi GET /
  • Menerima aktivitas Bot Framework di POST /api/messages

Membuat direktori proyek

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

Menginisialisasi proyek .NET

Untuk menyederhanakan pengalaman Anda, artikel ini menggunakan sampel yang sudah disiapkan. Kloning repositori Sampel Agent 365 dan buka sampel dotnet\semantic-kernel\sample-agent.

Agen Sampel Kernel Semantik - sampel C#/.NET mencakup:

Buka dotnet\semantic-kernel\sample-agent dan verifikasi bahwa proyek berhasil dibangun:

dotnet restore
dotnet build

Konfigurasikan model

Ikuti petunjuk di Langkah 2: Konfigurasi LLM untuk mengonfigurasi proyek menggunakan kunci Open API Anda.

Uji secara lokal (opsional)

  1. Sebelum menyebarkan ke AWS, uji agen Anda secara lokal:

    # Run the application
dotnet run

  2. Uji titik akhir di terminal lain:

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

  3. Tekan Ctrl+C untuk menghentikan server lokal.

Bangun dan sebar

Pilih opsi yang Anda inginkan untuk membangun dan menyebarkan aplikasi sampel ini:

Opsi A: Membangun dan menyebarkan dari Visual Studio

Gunakan AWS Toolkit untuk Visual Studio untuk menerbitkan aplikasi ke Elastic Beanstalk menggunakan wizard terpandu.

  1. Pada Penjelajah Solusi, klik kanan proyek Anda.

  2. Pilih Publikasikan ke AWS Elastic Beanstalk.

  3. Ikuti Wizard Penyebaran Beanstalk:

    • Pilih profil kredensial AWS Anda.
    • Pilih Kawasan (misalnya, us-east-1).
    • Pilih Platform (.NET Core on Linux).
    • Mengonfigurasi pengaturan lingkungan.

  4. Pilih Sebarkan.

Wizard membangun, mengemas, dan menyebarkan aplikasi Anda ke AWS.

Opsi B: Membangun dan menyebarkan ke AWS Elastic Beanstalk dengan CLI

Gunakan Elastic Beanstalk CLI untuk mengemas dan menyebarkan agen .NET ke lingkungan Amazon Linux 2 64 bit. Pastikan AWS CLI dan EB CLI telah dikonfigurasi. Aplikasi mengikat ke variabel lingkungan PORT yang ditetapkan oleh Beanstalk.

  1. Bangun dan publikasikan aplikasi .NET Anda:

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

    Buat Procfile dengan konten berikut.

    web: dotnet ./SemanticKernelSampleAgent.dll

  2. Inisialisasi Elastic Beanstalk untuk .NET. Anda diminta untuk memilih Wilayah dan Platform:

    eb init

  3. Pilih:

    • Platform: 64bit-amazon-linux-2023-v3.7.0-running-.net-8
    • Wilayah: Wilayah AWS pilihan Anda (misalnya: us-east-1)

  4. Buat paket penyebaran dan sebarkan:

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

    Perintah ini:

    • Membuat aplikasi Elastic Beanstalk.
    • Membuat lingkungan dengan load balancer.
    • Menyebarkan aplikasi Anda.
    • Menyediakan sumber daya AWS yang diperlukan.

  5. Setelah selesai, dapatkan titik akhir Elastic Beanstalk Anda:

    eb status

    Catat titik akhir Anda. Hasilnya akan terlihat seperti ini:

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

    Titik akhir ini adalah messagingEndpoint yang digunakan oleh Agent 365 Dev Tools CLI.

Catatan

Untuk lingkungan produksi, konfigurasikan HTTPS dengan menambahkan sertifikat SSL/TLS di Elastic Beanstalk. Bot Framework memerlukan HTTPS untuk titik akhir produksi.

Konfigurasi hosting non-Azure

Buat a365.config.json secara manual di folder proyek Elastic Beanstalk Anda:

Penting

Untuk hosting non-Azure, atur nilai messagingEndpoint ke URL Elastic Beanstalk Anda dengan jalur /api/messages.

File a365.config.json seharusnya akan terlihat seperti ini:

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

Tabel berikut merangkum bidang konfigurasi penting dan tujuannya.

Bidang Makna
messagingEndpoint URL Elastic Beanstalk Anda + /api/messages
deploymentProjectPath Tempat terjadinya proses stamping .env

Buat agen Agent 365

Setelah kode agen Anda berjalan pada titik akhir AWS, ikuti langkah-langkah berikut dari Memulai pengembangan Agent 365 untuk menyiapkan agen Agent 365 Anda.

Verifikasi agen secara menyeluruh

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

Verifikasi konektivitas Elastic Beanstalk

Kirim permintaan GET ke titik akhir Elastic Beanstalk Anda.

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

Permintaan harus mengembalikan pesan ini:

AWS Agent is running.

Periksa log Elastic Beanstalk untuk pesan Bot Framework yang masuk

Gunakan pengelogan Elastic Beanstalk untuk memastikan agen Anda menerima aktivitas Bot Framework dan merespons dengan tepat.

eb logs

Atau lakukan streaming log secara real-time:

eb logs --stream

Ketika pesan diterima oleh agen Anda, Anda akan melihat:

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

Agen uji dari permukaan Agent 365

Tergantung pada lingkungan, Anda dapat menguji agen Anda dari berbagai permukaan:

  • Agents Playground
  • Teams (jika dipublikasikan)
  • Agent Shell
  • Permukaan federasi

Anda dapat mengirim pesan dan memverifikasi log Elastic Beanstalk Anda. Pelajari 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:

Kembangkan dan uji secara lokal

Gunakan mode tonton untuk pengembangan cepat dengan pemuatan ulang otomatis:

# Automatically rebuild and restart on file changes
dotnet watch run

Lakukan perubahan pada kode Anda, simpan, dan uji secara lokal sebelum melakukan penyebaran.

Membangun dan menyebarkan ulang ke AWS Elastic Beanstalk

Saat siap untuk menyebarkan perubahan Anda:

# 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

Menguji dan memantau

Uji menggunakan permukaan Agent 365 dan pantau log Elastic Beanstalk:

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

Anda tidak perlu membuat ulang identitas, blueprint, titik akhir bot, atau izin.

Pemecahan masalah

Gunakan bagian ini untuk mendiagnosis dan menyelesaikan masalah umum saat menyebarkan dan menjalankan agen Agent 365 di AWS Elastic Beanstalk. Ini mencakup konektivitas dan pemeriksaan kesehatan. Juga membahas masalah pengikatan port, kesalahan build, dan masalah 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 menerima permintaan

Periksa rincian berikut:

  • Titik akhir Anda tepatnya:
    http://<your-app>.elasticbeanstalk.com/api/messages
  • Lingkungan Elastic Beanstalk Anda sehat. Gunakan pemeriksaan menggunakan eb health.
  • Grup keamanan Anda mengizinkan trafik HTTP atau HTTPS masuk.
  • Tidak ada aturan firewall atau batasan VPC.

Masalah kesehatan aplikasi

Periksa kesehatan lingkungan:

eb health --refresh

Lihat detail log:

eb logs

Masalah ikatan port

Pastikan aplikasi Anda berjalan pada port yang ditentukan oleh variabel lingkungan PORT. Nilai ini ditetapkan secara otomatis oleh Elastic Beanstalk.

Masalah build atau runtime .NET

Periksa kesalahan build menggunakan perintah berikut:

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

Verifikasi versi .NET:

dotnet --version
dotnet --list-sdks

Periksa masalah paket:

# List installed packages
dotnet list package

# Update packages
dotnet restore --force

Penetapan lisensi gagal

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

  • Last updated on