Menyebarkan agen ke Azure

Anda membuat agen Anda dan mengujinya secara lokal. Sekarang, wujudkan agen Anda di cloud. Langkah ini bersifat opsional. Anda dapat melewati langkah ini jika Anda sudah menyebarkan agen Anda ke salah satu layanan cloud (tidak harus Azure).

Panduan ini memandu Anda melalui penyebaran kode agen ke Azure dan menerbitkannya ke Microsoft Admin Center, di mana kode tersebut menjadi aset terdaftar untuk organisasi Anda.

Untuk memperbarui endpoint perpesanan, lihat sumber daya berikut. Sumber daya berikut menunjukkan cara Anda dapat memperbarui endpoint perpesanan jika Anda telah mendeploy agen ke penyedia cloud lain seperti Amazon Web Services atau Google Cloud Platform:

Prasyarat

Sebelum mulai, pastikan Anda memiliki item berikut:

Akun dan izin yang diperlukan

Langganan Azure dengan akses kontributor.
Kode agen yang berfungsi dengan endpoint pesan yang valid dan dapat diakses. Pastikan Anda menguji agen secara lokal dan secara opsional diuji dengan Microsoft 365 menggunakan Dev Tunnels untuk memverifikasi kode agen dapat dibuat dan berjalan seperti yang diharapkan.
Cetak biru agen yang valid dengan menyelesaikan langkah cetak biru agen penyiapan.
File konfigurasi yang terbaru a365.config.json, a365.generated.config.json, dan file konfigurasi di dalam kode (seperti file .env).

Alat yang diperlukan

Azure CLI diinstal dan diautentikasi (Instal Azure CLI)

Sebarkan ke Azure

Sebarkan kode aplikasi agen Anda ke Azure dengan menggunakan alat Azure standar seperti Azure CLI, Portal Azure, atau GitHub Actions.

Menyebarkan aplikasi agen

Gunakan az webapp deploy perintah Azure CLI untuk menyebarkan aplikasi Anda:

# Build your project first (example for .NET)
dotnet publish -c Release -o ./publish

# Deploy to Azure Web App
az webapp deploy --name <your-web-app> --resource-group <your-resource-group> --src-path ./publish

Untuk GitHub Actions, gunakan tindakan Azure Web Apps Deploy.

Peringatan

Manajemen rahasia: Simpan variabel lingkungan, termasuk kunci API dan rahasia, sebagai Azure App Settings, bukan dalam kode atau file konfigurasi. Untuk lingkungan produksi, gunakan Azure Key Vault untuk menyimpan rahasia sensitif. Pelajari lebih lanjut tentang Penyimpanan rahasia aplikasi yang aman dalam pengembangan di ASP.NET Core dan penyedia konfigurasi Azure Key Vault. Jangan pernah menerapkan .env file dengan informasi sensitif ke kontrol sumber.

Verifikasi penyebaran

Setelah penyebaran selesai, gunakan daftar ini dan petunjuk di bagian berikut untuk memverifikasi penyebaran.

✅ Perintah penyebaran selesai tanpa kesalahan
✅ Aplikasi web sedang berjalan
✅ Log aplikasi menunjukkan pengaktifan yang berhasil
✅ Variabel lingkungan dikonfigurasikan
✅ Titik akhir perpesanan merespons

Pastikan perintah penyebaran selesai tanpa kesalahan

Setelah penyebaran selesai, verifikasi keberhasilan dalam log penyebaran:

Akses aplikasi web Anda di Portal Azure.
Buka Pengaturan>Konfigurasi untuk memverifikasi pengaturan aplikasi.
Periksa log penyebaran di pusat penyebaran.

Untuk melihat riwayat penyebaran mendetail:

Buka Portal Azure > Aplikasi web Anda
Penyebaran>Pusat Penyebaran
Lihat log untuk penyebaran terbaru Anda

Jika build gagal:

Lakukan pembersihan dan build ulang secara lokal terlebih dahulu untuk memastikan build berhasil.
Periksa dependensi yang hilang atau kesalahan sintaks.
Lihat Perintah penyebaran gagal.

Jika aplikasi crash setelah penyebaran:

Periksa log untuk pesan kesalahan tertentu.
Pastikan semua variabel lingkungan yang diperlukan sudah diatur.
Lihat: Aplikasi crash saat pengaktifan.

Pastikan aplikasi web berjalan

Gunakan az webapp show perintah untuk memverikasi aplikasi web berjalan.

az webapp show --name <your-web-app> --resource-group <your-resource-group> --query state

Output yang diharapkan dari perintah ini adalah Running.

Pastikan log aplikasi menunjukkan startup yang berhasil

Untuk melihat log aplikasi web di Portal Azure:

Cari aplikasi web berdasarkan nama di Portal Azure.
Buka Ikhtisar>Log>Aliran Log.

Atau, Anda dapat menggunakan az webapp log tail perintah PowerShell untuk membaca log aplikasi web:

az webapp log tail --name <your-web-app> --resource-group <your-resource-group>

Jika terdapat pesan crash atau error dalam log, lihat Aplikasi mengalami crash saat memulai.

Verifikasikan variabel lingkungan dikonfigurasikan

Di Portal Azure:

Buka aplikasi web Anda.
Buka Pengaturan>Variabel Lingkungan.
Pastikan pengaturan Anda sudah ada.

Jika variabel lingkungan tidak ditetapkan:

Lakukan penyebaran ulang untuk menyinkronkan dari file .env.
Atau atur secara manual di Portal Azure.
Lihat Variabel lingkungan tidak diatur atau salah.

Verifikasi bahwa titik akhir Olahpesan merespons

Uji apakah endpoint yang Anda temukan di halaman Ikhtisar aplikasi web Anda benar-benar ada dengan menggunakan PowerShell atau cara lain. Jika tidak, lihat 404 pada endpoint Olahpesan.

Langkah berikutnya

Selanjutnya, publikasikan aplikasi agen Anda ke pusat admin Microsoft sehingga Anda dapat membuat instans agen dan pengguna dari pusat admin.

Terbitkan agen Anda

Agen Anda sekarang sudah berjalan di cloud dan siap merespons permintaan agentik. Saat agen Anda menangani permintaan dunia nyata, pertimbangkan langkah selanjutnya untuk kode Anda:

Pantau performa: Gunakan fitur observabilitas untuk melacak perilaku agen dan mengoptimalkan respons.
Tambahkan alat lain: Jelajahi katalog alat untuk memperluas kemampuan agen Anda.
Iterasi dan tingkatkan: Perbarui kode agen Anda, terapkan ulang, dan terbitkan ulang (ingatlah untuk menambah nomor versi!).
Tingkatkan skala di organisasi Anda: Bagikan kisah sukses agen Anda untuk mendorong adopsi.

Pemecahan masalah

Bagian ini menjelaskan masalah umum saat melakukan deployment agen ke Azure.

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.

Perintah deployment gagal

Gejala: Deploy ke Azure gagal.

Penyebab dan solusi umum:

Kesalahan build

Build ulang proyek secara lokal untuk melihat kesalahan kompilasi terperinci:

# .NET
dotnet clean
dotnet build --verbosity detailed

# Python
uv build

# Node.js
npm install
npm run build

Autentikasi Azure kedaluwarsa

Masuk lagi ke Azure:

az login
az account show  # Verify correct subscription

Aplikasi Web tidak dibuat

Tampilkan daftar Aplikasi Web untuk memastikan target ada:

# List Web Apps in resource group
az webapp list --resource-group <your-resource-group> --output table

Periksa log penyebaran

Gunakan az webapp log tail perintah untuk melihat log penyebaran terperinci:
```
az webapp log tail --name <your-app-name> --resource-group <your-resource-group>
```

Verifikasi:

# Web App should be running
az webapp show --name <your-app-name> --resource-group <your-resource-group> --query state
# Expected: "Running"

Web app dihentikan

Gejala: Penyebaran berhasil tetapi aplikasi web tidak berjalan.

Solusi: Gunakan az webapp start dan az webapp show untuk memulai aplikasi web dan verifikasi bahwa aplikasi tersebut berjalan.

# Start the Web App
az webapp start --name <your-app> --resource-group <your-resource-group>

# Verify it's running
az webapp show --name <your-app> --resource-group <your-resource-group> --query state

Aplikasi crash saat pengaktifan

Gejala: Aplikasi web dimulai tetapi langsung crash; log menunjukkan kesalahan.

Penyebab umum:

Dependensi hilang - Periksa output build untuk memastikannya mencakup semua paket yang diperlukan.
Variabel lingkungan yang hilang - Verifikasi semua pengaturan yang diperlukan telah dikonfigurasi.
Ketidakcocokan versi runtime - Pastikan runtime Azure cocok dengan lingkungan pengembangan Anda.
Kesalahan kode - Periksa log aplikasi untuk pengecualian tertentu.

Solusi: Gunakan perintah az webapp log tail, az webapp config appsettings list, dan az webapp config appsettings set untuk melihat log, memeriksa variabel lingkungan, dan mengatur variabel yang hilang.

# View application logs
az webapp log tail --name <your-app> --resource-group <your-resource-group>

# Check environment variables
az webapp config appsettings list --name <your-app> --resource-group <your-resource-group>

# Manually set a missing variable
az webapp config appsettings set --name <your-app> --resource-group <your-resource-group> --settings KEY=VALUE

404 pada endpoint pesan

Gejala: Aplikasi Web berjalan tetapi /api/messages titik akhir menghasilkan 404.

Solusi:

Verifikasi konfigurasi rute dalam kode agen Anda.
Periksa apakah handler endpoint sudah terdaftar dengan benar.
Pastikan titik masuk yang benar ditentukan dalam penyebaran.

Uji titik akhir dengan mengirim permintaan GET ke URL. Gunakan az webapp config show perintah untuk memeriksa konfigurasi aplikasi web.

curl https://<your-app-name>.azurewebsites.net/api/messages
az webapp config show --name <your-app> --resource-group <your-resource-group>

Variabel lingkungan tidak diatur atau salah

Gejala: Penyebaran berhasil tetapi agen tidak berfungsi; terdapat error konfigurasi yang hilang pada log.

Solusi: Verifikasi dan perbarui variabel lingkungan. Gunakan perintah az webapp config appsettings list dan az webapp config appsettings set untuk memeriksa variabel lingkungan, serta menetapkan variabel yang belum diatur. Kemudian sebarkan ulang.

# List all app settings
az webapp config appsettings list --name <your-app> --resource-group <your-resource-group>

# Set a specific variable
az webapp config appsettings set --name <your-app> --resource-group <your-resource-group> --settings API_KEY=your-value

Build berhasil secara lokal tetapi gagal di Azure

Gejala: Kode berhasil dibangun di komputer Anda tetapi gagal selama penyebaran Azure.