Dodaj aplikację App Service jako narzędzie w usłudze Foundry Agent Service (Spring Boot)

W tym samouczku dowiesz się, jak uwidocznić funkcjonalność aplikacji internetowej Spring Boot za pomocą OpenAPI, dodać ją jako narzędzie do usługi Foundry Agent Service i wchodzić w interakcje z aplikacją przy użyciu języka naturalnego w placu zabaw dla agentów.

Jeśli aplikacja internetowa ma już przydatne funkcje, takie jak zakupy, rezerwacja hotelowa lub zarządzanie danymi, można łatwo udostępnić te możliwości agentowi sztucznej inteligencji w usłudze Agent usługi Foundry. Po prostu dodając schemat interfejsu OpenAPI do aplikacji, możesz umożliwić agentowi zrozumienie możliwości aplikacji i korzystanie z nich podczas odpowiadania na monity użytkowników. Oznacza to, że wszystko, co może zrobić twoja aplikacja, agent sztucznej inteligencji może również zrobić, przy minimalnym nakładzie pracy poza tworzeniem punktu końcowego interfejsu OpenAPI dla aplikacji. W tym samouczku zaczniesz od prostej aplikacji typu lista to-do. Na koniec będziesz mieć możliwość tworzenia, aktualizowania i zarządzania zadaniami za pomocą agenta za pośrednictwem konwersacyjnej sztucznej inteligencji.

Wymagania wstępne

W tym samouczku założono, że pracujesz z przykładem używanym w artykule Samouczek: tworzenie aplikacji internetowej Java Spring Boot przy użyciu usługi Azure App Service w systemie Linux i usłudze Azure Cosmos DB.

Otwórz co najmniej przykładową aplikację w usłudze GitHub Codespaces i wdróż aplikację, uruchamiając polecenie azd up.

Dodawanie funkcji interfejsu OpenAPI do aplikacji internetowej

1. W przestrzeni kodu otwórz pom.xml i dodaj następującą zależność:

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

2. Otwórz plik src/main/java/com/microsoft/azure/appservice/examples/springbootmongodb/controller/TodoListController.java i dodaj następujące importy.

   import io.swagger.v3.oas.annotations.Operation;
   import io.swagger.v3.oas.annotations.tags.Tag;
   

   Klasa TodoListController implementuje @RestController, więc wystarczy dodać kilka adnotacji, aby była zgodna z OpenAPI. Ponadto, aby interfejsy API były kompatybilne z Usługą Agenta Foundry, należy określić operationId właściwość w @Operation adnotacji (zobacz Jak używać Usługi Agenta Foundry z określonymi narzędziami OpenAPI: Wymagania wstępne).

3. Znajdź deklarację klasy i dodaj adnotację @Tag , jak pokazano w poniższym fragmencie kodu:

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

4. Znajdź deklarację getTodoItem metody i dodaj adnotację @Operation z elementami description i operationId, jak pokazano w poniższym fragmencie kodu:

   @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) {
   

5. Znajdź deklarację getAllTodoItems metody i dodaj adnotację @Operation z elementami description i operationId, jak pokazano w poniższym fragmencie kodu:

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

6. Znajdź deklarację addNewTodoItem metody i dodaj adnotację @Operation z elementami description i operationId, jak pokazano w poniższym fragmencie kodu:

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

7. Znajdź deklarację updateTodoItem metody i dodaj adnotację @Operation z elementami description i operationId, jak pokazano w poniższym fragmencie kodu:

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

8. Znajdź deklarację deleteTodoItem metody i dodaj adnotację @Operation z elementami description i operationId, jak pokazano w poniższym fragmencie kodu:

   @Operation(description = "Deletes a todo item by ID", operationId = "deleteTodoItem")
   @DeleteMapping("/api/todolist/{id}")
   public String deleteTodoItem(@PathVariable("id") String id) {
   

   Ta minimalna konfiguracja zapewnia następujące ustawienia, jak opisano w pliku springdoc-openapi:

   • Swagger UI pod /swagger-ui.html.
   • Specyfikacja interfejsu OpenAPI pod adresem /v3/api-docs.

9. W terminalu usługi Codespace uruchom aplikację za pomocą mvn spring-boot:run polecenia.

10. Kliknij pozycję Otwórz w przeglądarce.

11. Przejdź do interfejsu Swagger, dodając /swagger-ui.html do adresu URL.

12. Upewnij się, że operacje interfejsu API działają, wypróbowując je w Swagger UI.

13. W terminalu usługi Codespace wdróż zmiany, zatwierdzając zmiany (metodę GitHub Actions) lub uruchamiając azd up (metoda interfejsu wiersza polecenia dewelopera platformy Azure).

14. Po wdrożeniu zmian przejdź do https://<your-app's-url>/v3/api-docs i skopiuj schemat do późniejszego użycia.

Tworzenie agenta w rozwiązaniu Microsoft Foundry

1. W portalu Foundry w prawym górnym menu wybierz pozycję New Foundry.

2. Jeśli jest to twój pierwszy raz w nowym portalu Foundry, wybierz nazwę projektu i wybierz pozycję Utwórz nowy projekt.

3. Nadaj projektowi nazwę i wybierz pozycję Utwórz.

4. Wybierz pozycję Rozpocznij kompilowanie, a następnie pozycję Utwórz agenta.

5. Nadaj agentowi nazwę i wybierz pozycję Utwórz. Gdy agent jest gotowy, powinien zostać wyświetlony plac zabaw agenta.

   Zwróć uwagę na modele, których można użyć, i dostępnych regionów.

6. Na placu zabaw dla agentów rozwiń Narzędzia i wybierz Dodaj>Niestandardowe>narzędzie OpenAPI>Utwórz.

7. Nadaj narzędziu nazwę i opis. W polu schematu OpenAPI 3.0+ wklej skopiowany wcześniej schemat.

8. Wybierz pozycję Utwórz narzędzie.

9. Wybierz Zapisz.

Przetestuj agenta

1. W obszarze Instrukcje podaj proste instrukcje, takie jak "Użyj narzędzia todosApp, aby ułatwić zarządzanie zadaniami".

2. Porozmawiaj z agentem, wykorzystując następujące podpowiedzi.

   • Pokaż mi wszystkie zadania.
   • Utwórz zadanie o nazwie „Wymyśl trzy żarty o sałacie”.
   • Zmień to na "Wymyśl trzy dowcipy knock-knock."

   

Najlepsze rozwiązania dotyczące zabezpieczeń

W przypadku uwidaczniania interfejsów API za pośrednictwem interfejsu OpenAPI w usłudze Azure App Service postępuj zgodnie z następującymi najlepszymi rozwiązaniami w zakresie zabezpieczeń:

• Uwierzytelnianie i autoryzacja: ochrona punktów końcowych interfejsu OpenAPI przy użyciu uwierzytelniania firmy Microsoft Entra. Aby uzyskać instrukcje krok po kroku, zobacz Secure OpenAPI endpoints for Foundry Agent Service. Możesz również chronić punkty końcowe za pomocą usługi Azure API Management przy użyciu identyfikatora Microsoft Entra ID i upewnić się, że tylko autoryzowani użytkownicy lub agenci mogą uzyskiwać dostęp do narzędzi.
• Weryfikowanie i oczyszczanie danych wejściowych: Przykładowy kod w tym samouczku pomija walidację i oczyszczanie danych wejściowych dla celów prostoty i przejrzystości. W scenariuszach produkcyjnych zawsze implementuj poprawną walidację i oczyszczanie, aby chronić aplikację. W przypadku platformy Spring zobacz Spring: Weryfikowanie danych wejściowych formularza.
• Użyj protokołu HTTPS: Przykład opiera się na usłudze Azure App Service, która domyślnie wymusza protokół HTTPS i udostępnia bezpłatne certyfikaty TLS/SSL do szyfrowania danych przesyłanych.
• Ogranicz mechanizm CORS: Ogranicz udostępnianie zasobów między źródłami (CORS) tylko do zaufanych domen. Aby uzyskać więcej informacji, zobacz Włączanie mechanizmu CORS.
• Zastosuj ograniczanie szybkości: Użyj usługi API Management lub niestandardowego oprogramowania pośredniczącego, aby zapobiec nadużyciom i atakom typu "odmowa usługi".
• Ukryj poufne punkty końcowe: Unikaj uwidaczniania wewnętrznych lub administracyjnych interfejsów API w schemacie interfejsu OpenAPI.
• Przejrzyj schemat OpenAPI: Upewnij się, że schemat interfejsu OpenAPI nie wycieka poufnych informacji (takich jak wewnętrzne adresy URL, wpisy tajne lub szczegóły implementacji).
• Zachowaj zaktualizowane zależności: Regularnie aktualizuj pakiety NuGet i monitoruj je pod kątem biuletynów zabezpieczeń.
• Monitorowanie i rejestrowanie aktywności: Włącz rejestrowanie i monitoruj dostęp do wykrywania podejrzanych działań.
• Użyj tożsamości zarządzanych: Podczas wywoływania innych usług platformy Azure użyj tożsamości zarządzanych zamiast zakodowanych na stałe poświadczeń.

Aby uzyskać więcej informacji, zobacz Zabezpieczanie aplikacji usługi App Service i Najlepsze rozwiązania dotyczące zabezpieczeń interfejsu API REST.

Następny krok

Aplikacja App Service została teraz włączona do użytku jako narzędzie przez Foundry Agent Service, umożliwiając interakcję z interfejsami API aplikacji za pomocą języka naturalnego w środowisku testowym agentów. W tym miejscu możesz nadal dodawać funkcje do agenta w portalu Foundry, integrować je z własnymi aplikacjami przy użyciu zestawu Microsoft Foundry SDK lub interfejsu API REST albo wdrażać je w ramach większego rozwiązania. Agentów utworzonych w rozwiązaniu Microsoft Foundry można uruchamiać w chmurze, integrować z czatbotami lub osadzać w aplikacjach internetowych i mobilnych.

Więcej zasobów

• Integrowanie sztucznej inteligencji z aplikacjami usługi Azure App Service
• Co to jest usługa agenta programu Foundry?