Tutorial: Membangun aplikasi web agenik di Azure App Service dengan LangGraph atau Foundry Agent Service (Python)

Tutorial ini menunjukkan cara menambahkan kemampuan agenik ke aplikasi FastAPI CRUD berbasis data yang ada. Ini dilakukan menggunakan dua pendekatan berbeda: LangGraph 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 dalam plugin (untuk LangGraph) 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.

LangGraph

Layanan Agen Foundry

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

Pertimbangan	LangGraph atau Microsoft Agent Framework	Layanan Agen Pengecoran
Performance	Cepat (berjalan secara lokal)	Lebih lambat (terkelola, layanan jarak jauh)
Pengembangan	Kode penuh, kontrol maksimum	Kode rendah, integrasi cepat
Testing	Pengujian manual/unit pada kode	Taman bermain bawaan untuk pengujian cepat
Skalabilitas	Dikelola oleh aplikasi	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:

• Konversikan fungsionalitas aplikasi yang ada menjadi plugin untuk LangGraph.
• Tambahkan plugin ke agen LangGraph 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.

Prasyarat

• 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-langgraph-foundry-python.

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:

   python3 -m venv venv
   source venv/bin/activate
   pip install -r requirements.txt
   uvicorn src.app:app --host 0.0.0.0 --port 3000
   

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

   Agen belum sepenuhnya dikonfigurasi sehingga belum berfungsi. Anda akan mengonfigurasinya nanti.

Meninjau kode agen

Kedua pendekatan menggunakan pola implementasi yang sama, di mana agen diinisialisasi pada aplikasi dimulai, dan merespons pesan pengguna berdasarkan permintaan POST.

LangGraph

LangGraphTaskAgent diinisialisasi oleh konstruktor di src/agents/langgraph_task_agent.py. Kode inisialisasi melakukan hal berikut:

• Mengonfigurasi klien AzureChatOpenAI menggunakan variabel lingkungan.
• Membuat agen ReAct bawaan dengan memori dan sekumpulan alat CRUD untuk manajemen tugas (lihat mulai cepat LangGraph).

# Initialize Azure OpenAI client
credential = DefaultAzureCredential()
azure_ad_token_provider = get_bearer_token_provider(
    credential, "https://cognitiveservices.azure.com/.default"
)

self.llm = AzureChatOpenAI(
    azure_endpoint=endpoint,
    azure_deployment=deployment_name,
    azure_ad_token_provider=azure_ad_token_provider,
    api_version="2024-10-21"
)

# Define tools
tools = [
    self._create_task_tool(),
    self._get_tasks_tool(),
    self._get_task_tool(),
    self._update_task_tool(),
    self._delete_task_tool()
]

# Create the agent
self.agent = create_react_agent(self.llm, tools, checkpointer=self.memory)
print("LangGraph Task Agent initialized successfully")

Saat memproses pesan pengguna, agen dipanggil menggunakan ainvoke() dengan pesan pengguna dan ID utas untuk kelangsungan percakapan:

result = await self.agent.ainvoke(
    {"messages": [("user", message)]},
    config=config
)

Layanan Agen Foundry

FoundryTaskAgent diinisialisasi dalam konstruktor src/agents/foundry_task_agent.py. Kode inisialisasi melakukan hal berikut:

• Membuat AIProjectClient menggunakan kredensial Azure.
• Mendapatkan klien OpenAI dari klien proyek.
• Mengambil agen dari Foundry berdasarkan nama.
• Membuat percakapan baru untuk sesi tersebut.

# Create the project client using Azure credentials
self.project_client = AIProjectClient(
    endpoint=endpoint,
    credential=DefaultAzureCredential()
)

# Get the OpenAI client for conversation operations
self.openai_client = self.project_client.get_openai_client()

# Find the existing agent by name
self.agent = self.project_client.agents.get(agent_name)

if not self.agent:
    print(f"Agent with name '{agent_name}' not found in project.")
    return
            
# Create a conversation for this session
conversation = self.openai_client.conversations.create()
self.conversation_id = conversation.id
print("Foundry agent initialized successfully")

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 ditampilkan di Menambahkan aplikasi App Service sebagai alat di Foundry Agent Service (Python), dan membuat fungsionalitas CRUD-nya tersedia sebagai titik akhir OpenAPI. Ini memungkinkan Anda menambahkannya nanti ke agen sebagai alat yang dapat dipanggil.

Kode OpenAPI didefinisikan dalam src/routes/api.py. Misalnya, rute "GET /tasks" mendefinisikan parameter kustom operation_id , seperti yang diperlukan oleh alat spesifikasi OpenAPI di Microsoft Foundry, dan description membantu agen menentukan cara memanggil API:

@router.get(
    "/tasks",
    response_model=List[TaskItem],
    operation_id="getAllTasks",
    description="Retrieve all tasks in the task list."
)
async def get_all_tasks():
    """Get all tasks"""
    try:
        tasks = await task_service.get_all_tasks()
        return tasks
    except Exception as e:
        print(f"Error getting tasks: {e}")
        import traceback
        traceback.print_exc()
        raise HTTPException(status_code=500, detail=f"Failed to get tasks: {str(e)}")

Saat memproses pesan pengguna, agen dipanggil dengan menambahkan pesan pengguna ke percakapan dan memanggil responses.create() dengan referensi agen:

# Add user message to the conversation
self.openai_client.conversations.items.create(
    conversation_id=self.conversation_id,
    items=[{"type": "message", "role": "user", "content": message}],
)

# Create response using the agent
response = self.openai_client.responses.create(
    conversation=self.conversation_id,
    extra_body={"agent": {"name": self.agent.name, "type": "agent_reference"}},
    input="",
)

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:

   Pertanyaan	Jawaban
   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 terlihat seperti ini dalam output AZD:

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

5. Buka skema OpenAPI yang dibuat secara otomatis di path https://....azurewebsites.net/openapi.json. Anda membutuhkan skema ini nanti.

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

Membuat dan mengonfigurasi sumber daya Microsoft Foundry

LangGraph

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

LangGraph

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 .env. Menggunakan nilai yang Anda salin sebelumnya dari portal Foundry, konfigurasikan variabel berikut:

   LangGraph

   Variable	Description
   AZURE_OPENAI_ENDPOINT	Endpoint Azure OpenAI (disalin dari portal Foundry klasik).
   AZURE_OPENAI_DEPLOYMENT_NAME	Nama model dalam penggelaran (disalin dari ruang percobaan model di portal Foundry yang baru).

   Nota

   Agar tutorial ini tetap sederhana, Anda akan menggunakan variabel ini di .env alih-alih menggantinya dengan pengaturan aplikasi di App Service.

   Layanan Agen Foundry

   Variable	Description
   AZURE_AI_FOUNDRY_PROJECT_ENDPOINT	Titik akhir proyek dari Microsoft Foundry di portal Foundry baru.
   AZURE_AI_FOUNDRY_AGENT_NAME	Nama agen (dari kawasan uji coba agen di portal Foundry).

   Nota

   Agar tutorial ini tetap sederhana, Anda akan menggunakan variabel-variabel ini dalam .env alih-alih menggantinya 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:

   npm run build
   npm start
   

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

5. Pilih tautan Agen LangGraph dan tautan Agen Foundry 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. Buka kembali aplikasi yang telah di-deploy dan uji agen chat.

LangGraph

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?
• LangGraph - Mulai Cepat
• Pustaka klien Azure AI Projects untuk Python