Menambahkan aplikasi App Service sebagai alat di Foundry Agent Service (Spring Boot)

Dalam tutorial ini, Anda akan mempelajari cara mengekspos fungsionalitas aplikasi web Spring Boot melalui OpenAPI, menambahkannya sebagai alat ke Foundry Agent Service, dan berinteraksi dengan aplikasi Anda menggunakan bahasa alami di taman bermain agen.

Jika aplikasi web Anda sudah memiliki fitur yang berguna, seperti belanja, pemesanan hotel, atau manajemen data, mudah untuk membuat kemampuan tersebut tersedia untuk agen AI di Foundry Agent Service. Dengan hanya menambahkan skema OpenAPI ke aplikasi, Anda memungkinkan agen untuk memahami dan menggunakan kemampuan aplikasi Anda saat menanggapi permintaan pengguna. Ini berarti apa pun yang dapat dilakukan aplikasi Anda, agen AI Anda juga dapat melakukannya, dengan upaya minimal selain membuat titik akhir OpenAPI untuk aplikasi Anda. Dalam tutorial ini, Anda mulai dengan aplikasi daftar to-do sederhana. Pada akhirnya, Anda akan dapat membuat, memperbarui, dan mengelola tugas dengan agen melalui AI percakapan.

Cuplikan layar memperlihatkan taman bermain agen di tengah percakapan yang mengambil tindakan dengan menggunakan alat OpenAPI.

Tambahkan fungsionalitas OpenAPI ke aplikasi web Anda.
Pastikan skema OpenAPI kompatibel dengan Foundry Agent Service.
Daftarkan aplikasi Anda sebagai alat OpenAPI di Foundry Agent Service.
Uji agen Anda di taman bermain agen.

Prasyarat

Tutorial ini mengasumsikan Anda bekerja dengan sampel yang digunakan dalam Tutorial: Membangun aplikasi web Java Spring Boot dengan Azure App Service di Linux dan Azure Cosmos DB.

Minimal, buka aplikasi sampel di GitHub Codespaces dan sebarkan aplikasi dengan menjalankan azd up.

Menambahkan fungsionalitas OpenAPI ke aplikasi web Anda

Petunjuk / Saran

Anda dapat membuat semua perubahan berikut dengan memberi tahu GitHub Copilot dalam mode Agen:

I'd like to generate OpenAPI functionality using Spring Boot OpenAPI. Please also generate the server URL and operation ID in the schema.

Di codespace, buka pom.xml dan tambahkan dependensi berikut:

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.6.0</version>
</dependency>

Buka src/main/java/com/microsoft/azure/appservice/examples/springbootmongodb/controller/TodoListController.java dan tambahkan impor berikut.
```
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
```
Kelas mengimplementasikan TodoListController@RestController, jadi Anda hanya perlu menambahkan beberapa anotasi untuk membuatnya kompatibel dengan OpenAPI. Selain itu, untuk membuat API kompatibel dengan Foundry Agent Service, Anda harus menentukan operationId properti dalam @Operation anotasi (lihat Cara menggunakan Foundry Agent Service dengan OpenAPI Specified Tools: Prasyarat).

Temukan deklarasi kelas dan tambahkan @Tag anotasi seperti yang ditunjukkan dalam cuplikan berikut:

@RestController
@Tag(name = "Todo List", description = "Todo List management APIs")
public class TodoListController {

Temukan metode deklarasi getTodoItem dan tambahkan anotasi @Operation dengan description dan operationId, seperti yang ditunjukkan dalam cuplikan berikut:

@Operation(description = "Returns a single todo item", operationId = "getTodoItem")
@GetMapping(path = "/api/todolist/{index}", produces = {MediaType.APPLICATION_JSON_VALUE})
public TodoItem getTodoItem(@PathVariable("index") String index) {

Temukan metode deklarasi getAllTodoItems dan tambahkan anotasi @Operation dengan description dan operationId, seperti yang ditunjukkan dalam cuplikan berikut:

@Operation(description = "Returns a list of all todo items", operationId = "getAllTodoItems")
@GetMapping(path = "/api/todolist", produces = {MediaType.APPLICATION_JSON_VALUE})
public List<TodoItem> getAllTodoItems() {

Temukan metode deklarasi addNewTodoItem dan tambahkan anotasi @Operation dengan description dan operationId, seperti yang ditunjukkan dalam cuplikan berikut:

@Operation(description = "Creates a new todo item", operationId = "addNewTodoItem")
@PostMapping(path = "/api/todolist", consumes = MediaType.APPLICATION_JSON_VALUE)
public String addNewTodoItem(@RequestBody TodoItem item) {

Temukan metode deklarasi updateTodoItem dan tambahkan anotasi @Operation dengan description dan operationId, seperti yang ditunjukkan dalam cuplikan berikut:

@Operation(description = "Updates an existing todo item", operationId = "updateTodoItem")
@PutMapping(path = "/api/todolist", consumes = MediaType.APPLICATION_JSON_VALUE)
public String updateTodoItem(@RequestBody TodoItem item) {

Temukan metode deklarasi deleteTodoItem dan tambahkan anotasi @Operation dengan description dan operationId, seperti yang ditunjukkan dalam cuplikan berikut:
```
@Operation(description = "Deletes a todo item by ID", operationId = "deleteTodoItem")
@DeleteMapping("/api/todolist/{id}")
public String deleteTodoItem(@PathVariable("id") String id) {
```
Konfigurasi minimal ini memberi Anda pengaturan berikut, seperti yang didokumenkan dalam springdoc-openapi:
- UI Swagger di /swagger-ui.html.
- Spesifikasi OpenAPI di /v3/api-docs.
Di terminal codespace, jalankan aplikasi dengan mvn spring-boot:run.
Pilih Buka di Browser.
Navigasikan ke antarmuka pengguna Swagger dengan menambahkan /swagger-ui.html ke URL.
Konfirmasikan bahwa operasi API berfungsi dengan mencobanya di antarmuka pengguna Swagger.
Kembali ke terminal codespace, sebarkan perubahan Anda dengan menerapkan perubahan Anda (metode GitHub Actions) atau jalankan azd up (metode Azure Developer CLI).
Setelah perubahan Anda disebarkan, navigasikan ke https://<your-app's-url>/v3/api-docs dan salin skema untuk nanti.

Membuat agen di Microsoft Foundry

Nota

Langkah-langkah ini menggunakan portal Foundry baru.

Di portal Foundry, di menu kanan atas, pilih New Foundry.
Jika ini pertama kalinya Anda berada di portal Foundry baru, pilih nama proyek dan pilih Buat proyek baru.
Beri nama proyek Anda dan pilih Buat.
Pilih Mulai membangun, lalu Buat agen.
Beri nama agen Anda dan pilih Buat. Ketika agen siap, Anda akan melihat taman bermain agen.

Perhatikan model yang dapat Anda gunakan dan wilayah yang tersedia.
Di taman bermain agen, perluas Alat dan pilih Tambahkan>alat> OpenAPI>Buat.
Beri nama dan deskripsi pada alat ini. Dalam kotak skema OpenAPI 3.0+ , tempelkan skema yang Anda salin sebelumnya.
Pilih Buat alat.
Pilih Simpan.

Petunjuk / Saran

Dalam tutorial ini, alat OpenAPI dikonfigurasi untuk memanggil aplikasi Anda secara anonim tanpa autentikasi. Untuk skenario produksi, Anda harus mengamankan perangkat dengan autentikasi identitas yang terkelola. Untuk instruksi langkah demi langkah, lihat Titik akhir OpenAPI Aman untuk Foundry Agent Service.

Menguji agen

Dalam Instruksi, berikan beberapa instruksi sederhana, seperti "Silakan gunakan alat todosApp untuk membantu mengelola tugas."
Mengobrol dengan agen dengan saran prompt berikut:
- Perlihatkan saya semua tugas.
- Buat tugas yang disebut "Ciptakan tiga lelucon tentang selada."
- Ubah itu menjadi "Buatlah tiga lelucon knock-knock."

Praktik terbaik keamanan

Saat mengekspos API melalui OpenAPI di Azure App Service, ikuti praktik terbaik keamanan berikut:

Autentikasi dan Otorisasi: Lindungi titik akhir OpenAPI Anda dengan autentikasi Microsoft Entra. Untuk instruksi langkah demi langkah, lihat Titik akhir OpenAPI Aman untuk Foundry Agent Service. Anda juga dapat melindungi titik akhir di belakang Azure API Management dengan ID Microsoft Entra dan memastikan hanya pengguna atau agen yang berwenang yang dapat mengakses alat.
Memvalidasi dan membersihkan data input: Contoh kode dalam tutorial ini menghilangkan validasi input dan sanitasi untuk kesederhanaan dan kejelasan. Dalam skenario produksi, selalu terapkan validasi dan sanitasi yang tepat untuk melindungi aplikasi Anda. Untuk Spring, lihat Spring: Memvalidasi Input Formulir.
Gunakan HTTPS: Sampel bergantung pada Azure App Service, yang memberlakukan HTTPS secara default dan menyediakan sertifikat TLS/SSL gratis untuk mengenkripsi data saat transit.
BATAS CORS: Batasi Berbagi Sumber Daya Lintas Asal (CORS) ke domain tepercaya saja. Untuk informasi selengkapnya, lihat Mengaktifkan CORS.
Menerapkan pembatasan tarif: Gunakan API Management atau middleware kustom untuk mencegah penyalahgunaan dan penolakan serangan layanan.
Sembunyikan titik akhir sensitif: Hindari mengekspos API internal atau admin dalam skema OpenAPI Anda.
Tinjau skema OpenAPI: Pastikan skema OpenAPI Anda tidak membocorkan informasi sensitif (seperti URL internal, rahasia, atau detail implementasi).
Terus perbarui dependensi: Perbarui paket NuGet secara teratur dan pantau saran keamanan.
Memantau dan mencatat aktivitas: Aktifkan pengelogan dan pantau akses untuk mendeteksi aktivitas yang mencurigakan.
Gunakan identitas terkelola: Saat memanggil layanan Azure lainnya, gunakan identitas terkelola alih-alih kredensial yang dikodekan secara permanen.

Untuk informasi selengkapnya, lihat Mengamankan aplikasi App Service anda dan Praktik terbaik untuk keamanan REST API.

Langkah selanjutnya

Anda sekarang telah mengaktifkan aplikasi App Service untuk digunakan sebagai alat oleh Foundry Agent Service dan berinteraksi dengan API aplikasi Anda melalui bahasa alami di taman bermain agen. Dari sini, Anda dapat terus menambahkan fitur ke agen Anda di portal Foundry, mengintegrasikannya ke dalam aplikasi Anda sendiri menggunakan Microsoft Foundry SDK atau REST API, atau menyebarkannya sebagai bagian dari solusi yang lebih besar. Agen yang dibuat di Microsoft Foundry dapat dijalankan di cloud, diintegrasikan ke dalam chatbot, atau disematkan di aplikasi web dan seluler.

Nota

Foundry Agent Service saat ini tidak memiliki Java SDK. Untuk melihat bagaimana Anda dapat menggunakan agen yang Anda buat, lihat Tutorial: Membangun aplikasi web agenik di Azure App Service dengan Microsoft Semantic Kernel atau Foundry Agent Service (.NET).

Sumber daya lainnya

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2025-12-16