Tutorial: Membangun aplikasi web agenik di Azure App Service dengan Microsoft Agent Framework atau Foundry Agent Service (.NET)

Tutorial ini menunjukkan cara menambahkan kemampuan agenik ke aplikasi CRUD inti ASP.NET berbasis data yang ada. Ini dilakukan menggunakan dua pendekatan berbeda: Microsoft Agent Framework dan Foundry Agent Service.

Jika aplikasi web Anda sudah memiliki fitur yang berguna, seperti belanja, pemesanan hotel, atau manajemen data, relatif mudah untuk menambahkan fungsionalitas agen ke aplikasi web Anda dengan membungkus fungsionalitas tersebut sebagai alat (untuk Microsoft Agent Framework) atau sebagai titik akhir OpenAPI (untuk Foundry Agent Service). Dalam tutorial ini, Anda mulai dengan aplikasi daftar to-do sederhana. Pada akhirnya, Anda akan dapat membuat, memperbarui, dan mengelola tugas dengan agen di aplikasi App Service.

Microsoft Agent Framework

Layanan Agen Foundry

Microsoft Agent Framework dan Foundry Agent Service memungkinkan Anda membangun aplikasi web agenik dengan kemampuan berbasis AI. Tabel berikut menunjukkan beberapa pertimbangan dan kompromi:

Consideration	Kerangka Kerja Agen Microsoft	Layanan Agen Pengecoran
Performance	Cepat (beroperasi secara lokal)	Lebih lambat (terkelola, layanan jarak jauh)
Development	Kode penuh, kontrol maksimum	Kode rendah, integrasi cepat
Testing	Pengujian manual/unit dalam kode	Taman bermain bawaan untuk pengujian cepat
Scalability	App-managed	Dikelola Azure, diskalakan otomatis
Pagar pembatas keamanan	Implementasi kustom diperlukan	Keamanan dan moderasi konten bawaan
Identitas	Implementasi kustom diperlukan	ID dan autentikasi agen bawaan
Enterprise	Integrasi kustom diperlukan	Penyebaran Microsoft 365/Teams bawaan dan panggilan alat terintegrasi Microsoft 365.

Dalam tutorial ini, Anda akan belajar cara:

• Mengonversi fungsionalitas aplikasi yang ada menjadi alat untuk Microsoft Agent Framework.
• Tambahkan alat ke agen Microsoft Agent Framework dan gunakan di aplikasi web.
• Mengonversi fungsionalitas aplikasi yang ada menjadi titik akhir OpenAPI untuk Foundry Agent Service.
• Panggil agen Foundry di aplikasi web.
• Tetapkan izin yang diperlukan untuk konektivitas identitas terkelola.

Prerequisites

• Akun Azure dengan langganan aktif - Buat akun secara gratis.
• Akun GitHub untuk menggunakan GitHub Codespaces - Pelajari selengkapnya tentang GitHub Codespaces.

Buka sampel dengan Codespace

Cara term mudah untuk memulai adalah dengan menggunakan GitHub Codespaces, yang menyediakan lingkungan pengembangan lengkap dengan semua alat yang diperlukan yang telah diinstal sebelumnya.

1. Navigasikan ke repositori GitHub di https://github.com/Azure-Samples/app-service-agentic-semantic-kernel-ai-foundry-agent.

2. Pilih tombol Kode , pilih tab Codespaces , dan pilih Buat codespace di utama.

3. Tunggu beberapa saat agar Codespace Anda diinisialisasi. Setelah siap, Anda akan melihat lingkungan pengembangan yang dikonfigurasi sepenuhnya di browser Anda.

4. Jalankan aplikasi secara lokal:

   dotnet run
   

5. Saat Anda melihat Aplikasi Anda yang berjalan di port 5280 tersedia, pilih Buka di Browser dan tambahkan beberapa tugas.

Meninjau kode agen

Kedua pendekatan menggunakan pola implementasi yang sama, di mana agen diinisialisasi sebagai layanan (dalam Program.cs) dalam penyedia dan disuntikkan ke komponen Blazor masing-masing.

Microsoft Agent Framework

AgentFrameworkProvider diinisialisasi dalam Layanan/AgentFrameworkProvider.cs. Kode inisialisasi melakukan hal berikut:

• Membuat IChatClient menggunakan AzureOpenAIClient dari Azure OpenAI.
• Mendapatkan instans TaskCrudTool yang merangkum fungsionalitas aplikasi CRUD (di Alat/TaskCrudTool.cs). Atribut Description pada metode alat membantu agen menentukan cara memanggilnya.
• Membuat agen AI menggunakan CreateAIAgent() dengan instruksi serta alat yang telah terdaftar melalui AIFunctionFactory.Create().
• Membuat thread bagi agen untuk mempertahankan percakapan selama navigasi.

// Create IChatClient
IChatClient chatClient = new AzureOpenAIClient(
        new Uri(endpoint),
        new DefaultAzureCredential())
    .GetChatClient(deployment)
    .AsIChatClient();

// Get TaskCrudTool instance from service provider
var taskCrudTool = sp.GetRequiredService<TaskCrudTool>();

// Create agent with tools
var agent = chatClient.CreateAIAgent(
    instructions: @"You are an agent that manages tasks using CRUD operations. 
        Use the provided functions to create, read, update, and delete tasks. 
        Always call the appropriate function for any task management request.
        Don't try to handle any requests that are not related to task management.
        When handling requests, if you're missing any information, don't make it up but prompt the user for it instead.",
    tools:
    [
        AIFunctionFactory.Create(taskCrudTool.CreateTaskAsync),
        AIFunctionFactory.Create(taskCrudTool.ReadTasksAsync),
        AIFunctionFactory.Create(taskCrudTool.UpdateTaskAsync),
        AIFunctionFactory.Create(taskCrudTool.DeleteTaskAsync)
    ]);

// Create thread for this scoped instance (persists across navigation)
var thread = agent.GetNewThread();

return (agent, thread);

Setiap kali pengguna mengirim pesan, komponen Blazor (di Komponen/Halaman/AgentFrameworkAgent.razor) memanggil Agent.RunAsync() dengan masukan pengguna dan utas agen. Utas agen melacak riwayat obrolan.

var response = await this.Agent.RunAsync(sentInput, this.agentThread);

Layanan Agen Foundry

Penyedia FoundryAgentProvider diinisialisasi dalam Layanan/FoundryAgentProvider.cs. Kode inisialisasi melakukan hal berikut:

• Membuat AIProjectClient menggunakan endpoint proyek Foundry.
• Mendapatkan agen yang sudah ada dari Microsoft Foundry berdasarkan nama.
• Membuat percakapan untuk sesi browser.
• Mendapatkan ProjectResponsesClient dari agen dan percakapan.

// Create project client
var projectClient = new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential());

// Get an existing agent from Microsoft Foundry
var agent = projectClient.Agents.GetAgent(agentName);

// Get conversations client for retrieving history
var conversationsClient = projectClient.OpenAI.Conversations;

// Create conversation for this browser session
var conversation = conversationsClient.CreateProjectConversation().Value;

// Get response client for this agent and conversation
var responseClient = projectClient.OpenAI.GetProjectResponsesClientForAgent(agentName, conversation.Id);

return (responseClient, conversation, conversationsClient);

Kode inisialisasi ini tidak menentukan fungsionalitas apa pun untuk agen, karena Anda biasanya akan membangun agen di portal Foundry. Sebagai bagian dari skenario contoh, ini juga mengikuti pola OpenAPI yang ditunjukkan di Menambahkan aplikasi App Service sebagai alat di Foundry Agent Service (.NET), dan membuat fungsionalitas CRUD-nya tersedia sebagai titik akhir OpenAPI. Ini memungkinkan Anda menambahkannya ke agen nanti sebagai alat yang dapat dipanggil.

Kode OpenAPI didefinisikan dalam Program.cs. Misalnya, API "dapatkan tugas" menentukan ID operasi dengan WithName(), seperti yang diperlukan oleh alat spesifikasi OpenAPI di Microsoft Foundry, dan WithDescription() membantu agen menentukan cara memanggil API:

app.MapOpenApi();

app.MapGet("/api/tasks", async (TaskService taskService) =>
{
    return Results.Ok(await taskService.GetAllTasksAsync());
})
.WithDescription("Gets all tasks.")
.WithName("GetAllTasks");

Setiap kali pengguna mengirim pesan, komponen Blazor (dalam Components/Pages/FoundryAgent.razor) memanggil ResponseClient.CreateResponseAsync() dengan masukan pengguna. Klien respons menggunakan ID percakapan untuk melacak riwayat obrolan.

#pragma warning disable OPENAI001
var response = await FoundryProvider.ResponseClient.CreateResponseAsync(sentInput);
#pragma warning restore OPENAI001

Menyebarkan aplikasi sampel

Repositori sampel berisi templat Azure Developer CLI (AZD), yang membuat aplikasi App Service dengan identitas terkelola dan menyebarkan aplikasi sampel Anda.

1. Di terminal, masuk ke Azure menggunakan Azure Developer CLI:

   azd auth login
   

   Ikuti instruksi untuk menyelesaikan proses autentikasi.

2. Sebarkan aplikasi Azure App Service dengan templat AZD:

   azd up
   

3. Saat diminta, berikan jawaban berikut:

   Question	Answer
   Masukkan nama lingkungan baru:	Ketik nama unik.
   Pilih Langganan Azure untuk digunakan:	Pilih langganan.
   Pilih grup sumber daya yang akan digunakan:	Pilih Buat grup sumber daya baru.
   Pilih lokasi untuk membuat grup sumber daya di:	Pilih Swedia Tengah.
   Masukkan nama untuk grup sumber daya baru:	Ketik Enter.

4. Di output AZD, temukan URL aplikasi Anda dan navigasikan ke url tersebut di browser. URL tampak seperti ini dalam keluaran AZD:

    Deploying services (azd deploy)
   
      (✓) Done: Deploying service web
      - Endpoint: <URL>
    

5. Pilih item skema OpenAPI untuk membuka skema OpenAPI yang dibuat secara otomatis di jalur default /openapi/v1.json . Anda membutuhkan skema ini nanti.

6. Setelah penyebaran berhasil, Anda akan melihat URL untuk aplikasi yang disebarkan.

   Anda sekarang memiliki aplikasi App Service dengan identitas terkelola yang ditetapkan sistem.

Membuat dan mengonfigurasi sumber daya Microsoft Foundry

Microsoft Agent Framework

1. Di portal Foundry, pastikan tombol radio New Foundry teratas diatur ke aktif dan buat proyek.

2. Menyebarkan model yang Anda inginkan (lihat Mulai Cepat Microsoft Foundry: Buat sumber daya).

3. Dari atas taman bermain model, salin nama model.

4. Cara termudah untuk mendapatkan endpoint Azure OpenAI dapat dari portal klasik. Pilih tombol radio New Foundry , lalu Azure OpenAI, lalu salin URL di titik akhir Azure OpenAI untuk nanti.

   

Layanan Agen Foundry

1. Di portal Foundry, pastikan tombol radio New Foundry teratas diatur ke aktif dan buat proyek.

2. Di beranda, salin titik akhir Proyek untuk nanti.

3. Pilih Mulai buat>agen dan ikuti perintah.

4. Di lingkungan kerja agen baru, buat alat OpenAPI Kustom untuk memanggil aplikasi web Anda dengan memilih Alat>Tambahkan>OpenAPI Kustom>alat>Buat. Di panel Penyiapan , tambahkan tindakan dengan alat spesifikasi OpenAPI. Gunakan skema OpenAPI yang Anda dapatkan dari aplikasi web yang disebarkan dan autentikasi anonim . Untuk langkah-langkah terperinci, lihat Cara menggunakan alat spesifikasi OpenAPI.

   Kode aplikasi Anda sudah dikonfigurasi untuk menyertakan server url dan operationId, yang diperlukan oleh agen. Untuk informasi selengkapnya, lihat Menyambungkan ke Spesifikasi OpenAPI.

5. Pastikan untuk memilih Simpan.

6. Pilih Coba di playground dan uji agen Foundry Anda dengan perintah seperti "Tampilkan semua tugas" dan "Harap tambahkan tugas."

   Jika Anda mendapatkan respons yang valid, agen melakukan panggilan alat ke titik akhir OpenAPI di aplikasi web yang Anda sebarkan.

Menetapkan izin yang diperlukan

Microsoft Agent Framework

1. Dari menu atas portal Foundry baru, pilih Operasikan, lalu pilih Admin. Di baris untuk proyek Foundry Anda, Anda akan melihat dua tautan. Yang ada di kolom Nama adalah sumber daya proyek Foundry, dan yang ada di kolom Sumber daya induk adalah sumber daya Foundry.

   

2. Pilih sumber daya Foundry di sumber daya Induk lalu pilih Kelola sumber daya ini di portal Microsoft Azure. Dari portal Microsoft Azure, Anda dapat menetapkan akses berbasis peran untuk sumber daya ke aplikasi web yang disebarkan.

3. Tambahkan peran berikut untuk identitas terkelola aplikasi App Service:

   Sumber daya target	Peran yang diperlukan	Diperlukan untuk
   Pengecoran	Pengguna Layanan Kognitif OpenAI	Layanan penyelesaian obrolan di Microsoft Agent Framework.

   Untuk petunjuknya, lihat Menetapkan peran Azure menggunakan portal Microsoft Azure.

Layanan Agen Foundry

1. Dari menu atas portal Foundry baru, pilih Operasikan, lalu pilih Admin. Di baris untuk proyek Foundry Anda, Anda akan melihat dua tautan. Yang ada di kolom Nama adalah sumber daya proyek Foundry, dan yang ada di kolom Sumber daya induk adalah sumber daya Foundry.

   

2. Pilih sumber daya proyek Foundry di kolom Nama lalu pilih Kelola sumber daya ini di portal Microsoft Azure. Dari portal Microsoft Azure, Anda dapat menetapkan akses berbasis peran untuk sumber daya ke aplikasi web yang disebarkan.

3. Tambahkan peran berikut untuk identitas terkelola aplikasi App Service:

   Sumber daya target	Peran yang diperlukan	Diperlukan untuk
   Proyek Foundry	Pengguna Foundry	Membaca dan memanggil agen Foundry.

   Untuk petunjuknya, lihat Menetapkan peran Azure menggunakan portal Microsoft Azure.

Mengonfigurasi variabel koneksi di aplikasi sampel Anda

1. Buka appsettings.json. Menggunakan nilai yang Anda salin sebelumnya dari portal Foundry, konfigurasikan variabel berikut:

   Microsoft Agent Framework

   Variable	Description
   AzureOpenAIEndpoint	Titik akhir Azure OpenAI (disalin dari portal klasik Foundry).
   ModelDeployment	Nama model dalam penyebaran (disalin dari taman bermain model di portal Foundry baru).

   Note

   Agar tutorial tetap sederhana, Anda akan menggunakan variabel ini di appsettings.json alih-alih menimpanya dengan pengaturan aplikasi di App Service.

   Layanan Agen Foundry

   Variable	Description
   FoundryProjectEndpoint	Titik akhir proyek Microsoft Foundry dari portal Foundry baru.
   FoundryAgentName	Nama agen (dari taman bermain agen di portal Foundry).

   Note

   Agar tutorial tetap sederhana, Anda akan menggunakan variabel ini di appsettings.json alih-alih menimpanya dengan pengaturan aplikasi di App Service.

2. Masuk ke Azure dengan Azure CLI:

   az login
   

   Ini memungkinkan pustaka klien Azure Identity dalam kode sampel menerima token autentikasi untuk pengguna yang masuk. Ingatlah bahwa Anda menambahkan peran yang diperlukan untuk pengguna ini sebelumnya.

3. Jalankan aplikasi secara lokal:

   dotnet run
   

4. Saat Anda melihat Aplikasi Anda yang berjalan di port 5280 tersedia, pilih Buka di Browser.

5. Pilih tautan Agen Kerangka Kerja Agen Microsoft dan tautan Foundry Agent Service untuk mencoba antarmuka obrolan. Jika Anda mendapatkan respons, aplikasi Anda berhasil tersambung ke sumber daya Microsoft Foundry.

6. Kembali ke ruang kode GitHub, sebarkan perubahan aplikasi Anda.

   azd up
   

7. Navigasikan ke aplikasi yang disebarkan lagi dan uji agen obrolan.

Microsoft Agent Framework

Layanan Agen Foundry

Membersihkan sumber daya

Setelah selesai dengan aplikasi, Anda dapat menghapus sumber daya App Service untuk menghindari timbulnya biaya lebih lanjut:

azd down --purge

Karena templat AZD tidak menyertakan sumber daya Microsoft Foundry, Anda perlu menghapusnya secara manual jika diinginkan.

Sumber daya lainnya

• Mengintegrasikan AI ke dalam aplikasi Azure App Service Anda
• Apa itu Foundry Agent Service?
• Dokumentasi Microsoft Agent Framework