Bagikan melalui

Membuat dan menjalankan agen tangguh

Tutorial ini menunjukkan kepada Anda cara membuat dan menjalankan agen AI yang tahan lama menggunakan ekstensi tugas tahan lama untuk Microsoft Agent Framework. Anda akan membuat aplikasi Azure Functions yang menghosting agen stateful dengan titik akhir HTTP bawaan, dan mempelajari cara memantaunya menggunakan dasbor Durable Task Scheduler.

Agen tahan lama menyediakan hosting tanpa server dengan manajemen status otomatis, memungkinkan agen Anda mempertahankan riwayat percakapan di beberapa interaksi tanpa mengelola infrastruktur.

Prasyarat

Sebelum memulai, pastikan Anda memiliki prasyarat berikut:

Nota

Microsoft Agent Framework didukung dengan semua versi .NET yang didukung secara aktif. Untuk tujuan sampel ini, kami merekomendasikan .NET 9 SDK atau versi yang lebih baru.

Unduh proyek siap-guna

Gunakan Azure Developer CLI untuk menginisialisasi proyek baru dari templat panduan memulai cepat agen durable.

  1. Buat direktori baru untuk proyek Anda dan navigasikan ke direktori tersebut:

    mkdir MyDurableAgent
cd MyDurableAgent

  1. Inisialisasi proyek dari templat:

    azd init --template durable-agents-quickstart-dotnet

    Saat dimintai nama lingkungan, masukkan nama seperti my-durable-agent.

Ini mengunduh proyek quickstart dengan semua file yang diperlukan, termasuk konfigurasi Azure Functions, kode agen, dan template infrastruktur sebagai kode.

  1. Buat direktori baru untuk proyek Anda dan navigasikan ke direktori tersebut:

    mkdir MyDurableAgent
cd MyDurableAgent

  1. Inisialisasi proyek dari templat:

    azd init --template durable-agents-quickstart-python

    Saat dimintai nama lingkungan, masukkan nama seperti my-durable-agent.

  2. Membuat dan mengaktifkan lingkungan virtual:

    python3 -m venv .venv
source .venv/bin/activate

  1. Instal paket yang diperlukan:

    python -m pip install -r requirements.txt

Ini mengunduh proyek quickstart dengan semua file yang diperlukan, termasuk konfigurasi Azure Functions, kode agen, dan template infrastruktur sebagai kode. Ini juga menyiapkan lingkungan virtual dengan dependensi yang diperlukan.

Penyediaan sumber daya Azure

Gunakan Azure Developer CLI untuk membuat sumber daya Azure yang diperlukan untuk agen tahan lama Anda.

  1. Provisikan infrastruktur:

    azd provision

    Perintah ini membuat:

    • Layanan Azure OpenAI dengan implementasi gpt-4o-mini
    • Aplikasi Azure Functions dengan skema hosting Flex Consumption
    • Akun Azure Storage untuk menjalankan Azure Functions dan penyimpanan yang berkelanjutan
    • Instans Durable Task Scheduler (Skema konsumsi) untuk mengelola status agen
    • Konfigurasi jaringan dan identitas yang diperlukan

  2. Saat diminta, pilih langganan Azure Anda dan pilih lokasi untuk sumber daya.

Proses provisi membutuhkan waktu beberapa menit. Setelah selesai, azd menyimpan informasi sumber daya yang dibuat di lingkungan Anda.

Meninjau kode agen

Sekarang mari kita periksa kode yang mendefinisikan agen tahan lama Anda.

Buka Program.cs untuk melihat konfigurasi agen:

using Azure.AI.OpenAI;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Agents.AI.Hosting.AzureFunctions;
using Microsoft.Azure.Functions.Worker.Builder;
using Microsoft.Extensions.AI;
using Microsoft.Extensions.Hosting;
using OpenAI;

var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") 
    ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT environment variable is not set");
var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT") ?? "gpt-4o-mini";

// Create an AI agent following the standard Microsoft Agent Framework pattern
AIAgent agent = new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential())
    .GetChatClient(deploymentName)
    .CreateAIAgent(
        instructions: "You are a helpful assistant that can answer questions and provide information.",
        name: "MyDurableAgent");

using IHost app = FunctionsApplication
    .CreateBuilder(args)
    .ConfigureFunctionsWebApplication()
    .ConfigureDurableAgents(options => options.AddAIAgent(agent))
    .Build();
app.Run();

kode ini:

  1. Mengambil konfigurasi Azure OpenAI Anda dari variabel lingkungan.
  2. Membuat klien Azure OpenAI menggunakan kredensial Azure.
  3. Membuat agen AI dengan instruksi dan nama.
  4. Mengonfigurasi aplikasi Azure Functions untuk menghosting agen dengan pengelolaan thread yang andal.

Buka function_app.py untuk melihat konfigurasi agen:

import os
from agent_framework.azure import AzureOpenAIChatClient, AgentFunctionApp
from azure.identity import DefaultAzureCredential

endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
if not endpoint:
    raise ValueError("AZURE_OPENAI_ENDPOINT is not set.")
deployment_name = os.getenv("AZURE_OPENAI_DEPLOYMENT_NAME", "gpt-4o-mini")

# Create an AI agent following the standard Microsoft Agent Framework pattern
agent = AzureOpenAIChatClient(
    endpoint=endpoint,
    deployment_name=deployment_name,
    credential=DefaultAzureCredential()
).create_agent(
    instructions="You are a helpful assistant that can answer questions and provide information.",
    name="MyDurableAgent"
)

# Configure the function app to host the agent with durable thread management
app = AgentFunctionApp(agents=[agent])

kode ini:

  • Mengambil konfigurasi Azure OpenAI Anda dari variabel lingkungan.
  • Membuat klien Azure OpenAI menggunakan kredensial Azure.
  • Membuat agen AI dengan instruksi dan nama.
  • Mengonfigurasi aplikasi Azure Functions untuk menghosting agen dengan manajemen utas yang andal.

Agen sekarang siap untuk dihosting di Azure Functions. Ekstensi tugas yang tahan lama secara otomatis membuat titik akhir HTTP untuk berinteraksi dengan agen Anda dan mengelola status percakapan sepanjang beberapa permintaan.

Mengonfigurasi pengaturan lokal

Buat local.settings.json file untuk pengembangan lokal berdasarkan file sampel yang disertakan dalam proyek.

  1. Salin file pengaturan sampel:

    cp local.settings.sample.json local.settings.json

  1. Dapatkan titik akhir Azure OpenAI Anda dari sumber daya yang disediakan:

    azd env get-value AZURE_OPENAI_ENDPOINT

  2. Buka local.settings.json dan ganti <your-resource-name> dalam nilai AZURE_OPENAI_ENDPOINT dengan titik akhir dari perintah sebelumnya.

Anda local.settings.json akan terlihat seperti ini:

{
  "IsEncrypted": false,
  "Values": {
    // ... other settings ...
    "AZURE_OPENAI_ENDPOINT": "https://your-openai-resource.openai.azure.com",
    "AZURE_OPENAI_DEPLOYMENT": "gpt-4o-mini",
    "TASKHUB_NAME": "default"
  }
}

Nota

File local.settings.json hanya digunakan untuk pengembangan lokal dan tidak disebarkan ke Azure. Untuk penyebaran produksi, pengaturan ini secara otomatis dikonfigurasi di aplikasi Azure Functions Anda oleh templat infrastruktur.

Memulai dependensi pengembangan lokal

Untuk menjalankan agen tahan lama secara lokal, Anda perlu memulai dua layanan:

  • Azurite: Meniru layanan Azure Storage (digunakan oleh Azure Functions untuk mengelola pemicu dan status internal).
  • Durable Task Scheduler (DTS) Emulator: Mengelola status stabil (riwayat percakapan, status orkestrasi) dan penjadwalan untuk agen-agen Anda

Mulai Azurite

Azurite mengemulasi layanan Azure Storage secara lokal. Azure Functions menggunakannya untuk mengelola status internal. Anda harus menjalankan ini di jendela terminal baru dan membuatnya tetap berjalan saat Anda mengembangkan dan menguji agen tahan lama Anda.

  1. Buka jendela terminal baru dan tarik gambar Azurite Docker:

    docker pull mcr.microsoft.com/azure-storage/azurite

  2. Mulai Azurite di jendela terminal:

    docker run -p 10000:10000 -p 10001:10001 -p 10002:10002 mcr.microsoft.com/azure-storage/azurite

    Azurite akan memulai dan mendengarkan port default untuk layanan Blob (10000), Antrean (10001), dan Tabel (10002).

Biarkan jendela terminal ini tetap terbuka saat Anda mengembangkan dan menguji agen tahan lama Anda.

Petunjuk / Saran

Untuk informasi selengkapnya tentang Azurite, termasuk metode penginstalan alternatif, lihat Menggunakan emulator Azurite untuk pengembangan Azure Storage lokal.

Mulai emulator Durable Task Scheduler

Emulator DTS menyediakan backend tahan lama untuk mengelola status agen dan orkestrasi. Ini menyimpan riwayat percakapan dan memastikan status agen Anda tetap ada di seluruh restart. Ini juga memicu orkestrasi dan agen yang tahan lama. Anda harus menjalankan ini di jendela terminal baru yang terpisah dan membuatnya tetap berjalan saat Anda mengembangkan dan menguji agen tahan lama Anda.

  1. Buka jendela terminal baru lainnya dan tarik gambar Docker emulator DTS:

    docker pull mcr.microsoft.com/dts/dts-emulator:latest

  2. Jalankan emulator DTS:

    docker run -p 8080:8080 -p 8082:8082 mcr.microsoft.com/dts/dts-emulator:latest

    Perintah ini memulai emulator dan mengekspos:

    • Port 8080: Titik akhir gRPC untuk Durable Task Scheduler (digunakan oleh aplikasi Functions Anda)
    • Port 8082: Dasbor administratif

  3. Dasbor akan tersedia di http://localhost:8082.

Biarkan jendela terminal ini tetap terbuka saat Anda mengembangkan dan menguji agen tahan lama Anda.

Petunjuk / Saran

Untuk mempelajari selengkapnya tentang emulator DTS, termasuk cara mengonfigurasi beberapa hub tugas dan mengakses dasbor, lihat Mengembangkan dengan Durable Task Scheduler.

Menjalankan aplikasi fungsi

Sekarang Anda siap untuk menjalankan aplikasi Azure Functions anda dengan agen yang tahan lama.

  1. Di jendela terminal baru (menjaga emulator Azurite dan DTS berjalan di jendela terpisah), navigasikan ke direktori proyek Anda.

  2. Jalankan runtime Azure Functions:

    func start

  3. Anda akan melihat output yang menunjukkan bahwa aplikasi fungsi Anda berjalan, termasuk titik akhir HTTP untuk agen Anda:

    Functions:
     http-MyDurableAgent: [POST] http://localhost:7071/api/agents/MyDurableAgent/run
     dafx-MyDurableAgent: entityTrigger

Titik akhir ini mengelola status percakapan secara otomatis - Anda tidak perlu membuat atau mengelola objek utas sendiri.

Menguji agen di lingkungan lokal

Sekarang Anda dapat berinteraksi dengan agen tahan lama Anda menggunakan permintaan HTTP. Agen mempertahankan status percakapan di beberapa permintaan, memungkinkan percakapan berkelanjutan.

Memulai percakapan baru

Buat utas baru dan kirim pesan pertama Anda:

curl -i -X POST http://localhost:7071/api/agents/MyDurableAgent/run \
  -H "Content-Type: text/plain" \
  -d "What are three popular programming languages?"

Contoh respons (perhatikan x-ms-thread-id header berisi ID utas):

HTTP/1.1 200 OK
Content-Type: text/plain
x-ms-thread-id: @dafx-mydurableagent@263fa373-fa01-4705-abf2-5a114c2bb87d
Content-Length: 189

Three popular programming languages are Python, JavaScript, and Java. Python is known for its simplicity and readability, JavaScript powers web interactivity, and Java is widely used in enterprise applications.

Simpan ID utas dari x-ms-thread-id header (misalnya, @dafx-mydurableagent@263fa373-fa01-4705-abf2-5a114c2bb87d) untuk permintaan berikutnya.

Melanjutkan percakapan

Kirim pesan tindak lanjut ke utas yang sama dengan menyertakan ID utas sebagai parameter kueri:

curl -X POST "http://localhost:7071/api/agents/MyDurableAgent/run?thread_id=@dafx-mydurableagent@263fa373-fa01-4705-abf2-5a114c2bb87d" \
  -H "Content-Type: text/plain" \
  -d "Which one is best for beginners?"

Ganti @dafx-mydurableagent@263fa373-fa01-4705-abf2-5a114c2bb87d dengan ID thread yang sebenarnya dari header respons sebelumnya x-ms-thread-id.

Contoh respons:

Python is often considered the best choice for beginners among those three. Its clean syntax reads almost like English, making it easier to learn programming concepts without getting overwhelmed by complex syntax. It's also versatile and widely used in education.

Perhatikan bahwa agen mengingat konteks dari pesan sebelumnya (tiga bahasa pemrograman) tanpa Anda harus menentukannya lagi. Karena status percakapan disimpan dengan durably oleh Durable Task Scheduler, riwayat ini tetap ada bahkan jika Anda memulai ulang aplikasi fungsi atau percakapan dilanjutkan oleh instans yang berbeda.

Memantau dengan dasbor Durable Task Scheduler

Durable Task Scheduler menyediakan dasbor bawaan untuk memantau dan memecahkan masalah agen durabel Anda. Dasbor menawarkan visibilitas mendalam ke dalam operasi agen, riwayat percakapan, dan alur eksekusi.

Akses dasbor

  1. Buka dasbor untuk emulator DTS lokal Anda di http://localhost:8082 browser web Anda.

  2. Pilih hub tugas default dari daftar untuk menampilkan detailnya.

  3. Pilih ikon roda gigi di sudut kanan atas untuk membuka pengaturan, dan pastikan bahwa opsi Aktifkan halaman Agen di bawah Fitur Pratinjau dipilih.

Menjelajahi percakapan agen

  1. Di dasbor, navigasikan ke tab Agen .

  2. Pilih utas agen tahan lama Anda (misalnya, mydurableagent - 263fa373-fa01-4705-abf2-5a114c2bb87d) dari daftar.

    Anda akan melihat tampilan terperinci utas agen, termasuk riwayat percakapan lengkap dengan semua pesan dan respons.

    Cuplikan layar dasbor Durable Task Scheduler memperlihatkan riwayat percakapan utas agen.

Dasbor menyediakan tampilan garis waktu untuk membantu Anda memahami alur percakapan. Informasi utama meliputi:

  • Tanda waktu dan durasi untuk setiap interaksi
  • Konten perintah dan respons
  • Jumlah token yang digunakan

Petunjuk / Saran

Dasbor DTS menyediakan pembaruan real time, sehingga Anda dapat melihat perilaku agen saat berinteraksi dengannya melalui titik akhir HTTP.

Sebarkan ke Azure

Sekarang setelah Anda menguji agen tahan lama Anda secara lokal, sebarkan ke Azure.

  1. Sebarkan aplikasi:

    azd deploy

    Perintah ini mengemas aplikasi Anda dan meng-deploy-nya ke aplikasi Azure Functions yang dibuat selama proses provisi.

  2. Tunggu hingga penerapan selesai. Output akan mengonfirmasi kapan agen Anda berjalan di Azure.

Menguji agen yang terpasang

Setelah penyebaran, uji agen Anda yang berjalan di Azure.

Mendapatkan kunci fungsi

Azure Functions memerlukan kunci API untuk fungsi yang dipicu HTTP dalam produksi:

API_KEY=`az functionapp function keys list --name $(azd env get-value AZURE_FUNCTION_NAME) --resource-group $(azd env get-value AZURE_RESOURCE_GROUP) --function-name http-MyDurableAgent --query default -o tsv`

Memulai percakapan baru

Buat utas baru dan kirim pesan pertama Anda ke agen yang telah di-deploy.

curl -i -X POST "https://$(azd env get-value AZURE_FUNCTION_NAME).azurewebsites.net/api/agents/MyDurableAgent/run?code=$API_KEY" \
  -H "Content-Type: text/plain" \
  -d "What are three popular programming languages?"

Perhatikan ID utas yang dikembalikan di x-ms-thread-id tajuk respons.

Melanjutkan percakapan

Kirim pesan tindak lanjut di utas yang sama. Ganti <thread-id> dengan ID utas dari respons sebelumnya:

THREAD_ID="<thread-id>"
curl -X POST "https://$(azd env get-value AZURE_FUNCTION_NAME).azurewebsites.net/api/agents/MyDurableAgent/run?code=$API_KEY&thread_id=$THREAD_ID" \
  -H "Content-Type: text/plain" \
  -d "Which is easiest to learn?"

Agen mempertahankan konteks percakapan di Azure seperti yang dilakukan secara lokal, menunjukkan durabilitas status agen.

Memantau agen yang disebarkan

Anda dapat memantau agen yang disebarkan melalui dasbor Durable Task Scheduler di Azure.

  1. Dapatkan nama instans Durable Task Scheduler Anda:

    azd env get-value DTS_NAME

  2. Buka portal Microsoft Azure dan cari nama Durable Task Scheduler dari langkah sebelumnya.

  3. Di bilah gambaran umum sumber daya Durable Task Scheduler, pilih hub tugas default dari daftar.

  4. Pilih Buka Dasbor di bagian atas halaman hub tugas untuk membuka dasbor pemantauan.

  5. Lihat percakapan agen Anda seperti yang Anda lakukan dengan emulator lokal.

Dasbor yang dihosting Azure menyediakan kemampuan penelusuran kesalahan dan pemantauan yang sama dengan emulator lokal, memungkinkan Anda memeriksa riwayat percakapan, melacak panggilan alat, dan menganalisis performa di lingkungan produksi Anda.

Memahami fitur agen tahan lama

Agen tahan lama yang baru saja Anda buat menyediakan beberapa fitur penting yang membedakannya dari agen standar:

Percakapan stateful (yang mempertahankan kondisi)

Agen secara otomatis mempertahankan status percakapan di seluruh interaksi. Setiap utas memiliki riwayat percakapan terisolasi masing-masing, disimpan secara berkelanjutan di Durable Task Scheduler. Tidak seperti API stateless di mana Anda perlu mengirim riwayat percakapan lengkap dengan setiap permintaan: agen tahan lama mengelola proses ini untuk Anda secara otomatis.

Hosting tanpa server

Agen Anda berjalan di Azure Functions dengan harga prabayar berbasis peristiwa. Saat disebarkan ke Azure dengan paket Konsumsi Flex, agen Anda dapat menskalakan ke ribuan instans selama lalu lintas tinggi atau turun ke nol saat tidak digunakan, memastikan Anda hanya membayar untuk penggunaan aktual.

Titik akhir HTTP bawaan

Ekstensi tugas tahan lama secara otomatis membuat titik akhir HTTP untuk agen Anda, menghilangkan kebutuhan untuk menulis handler HTTP kustom atau kode API. Ini termasuk titik akhir untuk membuat utas, mengirim pesan, dan mengambil riwayat percakapan.

Manajemen keadaan durabel

Semua status agen dikelola oleh Durable Task Scheduler, memastikan bahwa:

  • Percakapan bertahan dari kerusakan proses dan restart.
  • Status didistribusikan di beberapa instans untuk ketersediaan tinggi.
  • Setiap contoh kasus dapat melanjutkan eksekusi agen setelah terjadi gangguan.
  • Riwayat percakapan dipelihara dengan andal bahkan selama peristiwa peningkatan skala.

Langkah selanjutnya

Sekarang setelah Anda memiliki agen yang andal dan berfungsi, Anda dapat menjelajahi fitur-fitur yang lebih canggih:

Pelajari tentang fitur agen tahan lama

Sumber daya tambahan:

  • Last updated on