Добавить приложение App Service как инструмент в службу агента Foundry (Spring Boot)

В этом руководстве вы узнаете, как предоставить функциональные возможности веб-приложения Spring Boot с помощью OpenAPI, добавить его в службу агента Foundry и взаимодействовать с приложением с помощью естественного языка в песочнице агентов.

Если веб-приложение уже имеет полезные функции, такие как покупки, бронирование отелей или управление данными, это легко сделать эти возможности доступными агенту ИИ в Службе агента Foundry. Просто добавив в приложение схему OpenAPI, агент может понять и использовать возможности приложения при реагировании на запросы пользователей. Это означает, что ваше приложение может сделать все, что может сделать агент ИИ, с минимальными усилиями, помимо создания конечной точки OpenAPI для вашего приложения. В этом руководстве вы начнёте с простого приложения для списков to-do. К концу вы сможете создавать, обновлять и управлять задачами с агентом с помощью общения ИИ.

Предпосылки

В этом руководстве предполагается, что вы работаете с примером, используемым в руководстве. Создание веб-приложения Java Spring Boot с помощью Службы приложений Azure в Linux и Azure Cosmos DB.

По крайней мере, откройте образец приложения в GitHub Codespaces и разверните приложение, запустив команду azd up.

Добавление функций OpenAPI в веб-приложение

1. В пространстве кода откройте pom.xml и добавьте следующую зависимость:

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

2. Откройте src/main/java/com/microsoft/azure/appservice/examples/springbootmongodb/controller/TodoListController.java и добавьте следующие импорты.

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

   Класс TodoListController реализует @RestController, поэтому необходимо добавить только несколько заметок, чтобы сделать его совместимым с OpenAPI. Кроме того, чтобы обеспечить совместимость API с службой агента Foundry, необходимо указать operationId свойство в заметке @Operation (см. раздел "Использование службы агента Foundry" с указанными средствами OpenAPI: предварительные требования).

3. Найдите объявление класса и добавьте аннотацию @Tag, как показано в следующем фрагменте кода.

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

4. getTodoItem Найдите объявление метода и добавьте заметку @Operation с description иoperationId, как показано в следующем фрагменте кода:

   @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. getAllTodoItems Найдите объявление метода и добавьте заметку @Operation с description иoperationId, как показано в следующем фрагменте кода:

   @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. addNewTodoItem Найдите объявление метода и добавьте заметку @Operation с description иoperationId, как показано в следующем фрагменте кода:

   @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. updateTodoItem Найдите объявление метода и добавьте заметку @Operation с description иoperationId, как показано в следующем фрагменте кода:

   @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. deleteTodoItem Найдите объявление метода и добавьте заметку @Operation с description иoperationId, как показано в следующем фрагменте кода:

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

   Эта минимальная конфигурация дает следующие параметры, как описано в springdoc-openapi:

   • Пользовательский интерфейс Swagger в /swagger-ui.html.
   • Спецификация OpenAPI по адресу /v3/api-docs.

9. В терминале пространства кода запустите приложение, используя mvn spring-boot:run.

10. Выберите Открыть в браузере.

11. Перейдите на Swagger UI, добавив /swagger-ui.html к URL.

12. Убедитесь, что операции API работают, пробуя их в пользовательском интерфейсе Swagger.

13. Вернитесь в терминал codespace, зафиксируйте изменения (метод GitHub Actions) или запустите azd up (метод Azure Developer CLI).

14. После развертывания изменений перейдите к https://<your-app's-url>/v3/api-docs схеме и скопируйте ее позже.

Создание агента в Microsoft Foundry

1. На портале Foundry в правом верхнем меню выберите New Foundry.

2. Если это первый раз на новом портале Foundry, выберите имя проекта и нажмите кнопку "Создать проект".

3. Присвойте проекту имя и нажмите кнопку "Создать".

4. Нажмите кнопку "Начать сборку", а затем создайте агент.

5. Присвойте агенту имя и нажмите кнопку "Создать". Когда агент будет готов, вы увидите игровую площадку агента.

   Обратите внимание на модели, которые можно использовать и доступные регионы.

6. На игровой площадке агента разверните Инструменты и выберите Добавить>Настраиваемый инструмент>OpenAPI>Создать.

7. Присвойте инструменту имя и описание. В поле схемы OpenAPI 3.0+ вставьте скопированную ранее схему.

8. Нажмите кнопку "Создать".

9. Нажмите кнопку "Сохранить".

Протестируйте агент

1. В инструкциях приведены некоторые простые инструкции, например "Используйте средство todosApp для управления задачами".

2. Свяжитесь с агентом с учетом следующих вариантов запроса:

   • Показать мне все задачи.
   • Создайте задачу под названием "Придумать три шутки салата".
   • Измените это на "Придумать с тремя шутками стука-стука".

   

Рекомендации по обеспечению безопасности

При предоставлении API-интерфейсов с помощью OpenAPI в Службе приложений Azure следуйте приведенным ниже рекомендациям по обеспечению безопасности.

• Проверка подлинности и авторизация. Защита конечных точек OpenAPI с помощью проверки подлинности Microsoft Entra. Пошаговые инструкции см. в разделе "Безопасные конечные точки OpenAPI" для службы агента Foundry. Кроме того, вы можете защитить свои конечные точки с помощью Azure API Management и идентификатора Microsoft Entra ID, обеспечив доступ только для авторизованных пользователей или агентов.
• Проверка и очистка входных данных: Пример кода, приведенный в этом руководстве, исключает проверку входных данных и очистку для простоты и ясности. В рабочих сценариях всегда реализуйте правильную проверку и очистку для защиты приложения. Сведения о Spring см. в разделе Spring: Проверка входных данных формы.
• Используйте ПРОТОКОЛ HTTPS: В примере используется служба приложений Azure, которая по умолчанию применяет ПРОТОКОЛ HTTPS и предоставляет бесплатные СЕРТИФИКАТЫ TLS/SSL для шифрования данных во время передачи.
• Ограничение CORS: Ограничить общий доступ к ресурсам между источниками (CORS) только доверенным доменам. Дополнительные сведения см. в разделе "Включение CORS".
• Применение ограничения скорости:Используйте службу управления API или службу пользовательского промежуточного слоя, чтобы предотвратить злоупотребления и атаки типа "отказ в обслуживании".
• Скрытие конфиденциальных конечных точек: Избегайте предоставления внутренних или административных API в схеме OpenAPI.
• Просмотрите схему OpenAPI: Убедитесь, что схема OpenAPI не раскрывает конфиденциальную информацию (например, внутренние ссылки, секреты или детали реализации).
• Обновление зависимостей: Регулярно обновляйте пакеты NuGet и отслеживайте рекомендации по безопасности.
• Ведение журнала и мониторинг активности: Включите ведение журнала и мониторинг доступа для обнаружения подозрительной активности.
• Используйте управляемые удостоверения: При вызове других служб Azure используйте управляемые удостоверения вместо жестко закодированных учетных данных.

Дополнительные сведения см. в статье "Защита приложения службы приложений " и рекомендации по обеспечению безопасности REST API.

Следующий шаг

Теперь вы настроили приложение App Service для использования в качестве инструмента для службы агента Foundry. Взаимодействуйте с API вашего приложения через естественный язык на платформе для агентов. Здесь вы можете продолжать добавлять функции в агент на портале Foundry, интегрировать его в собственные приложения с помощью пакета SDK Microsoft Foundry или REST API или развернуть его в составе более крупного решения. Агенты, созданные в Microsoft Foundry, можно запускать в облаке, интегрировать в чат-боты или внедрять в веб-приложения и мобильные приложения.

Дополнительные ресурсы

• Интеграция ИИ в приложения Службы приложений Azure
• Что такое служба агента Foundry?