Adición de una aplicación de App Service como herramienta en Foundry Agent Service (Spring Boot)

En este tutorial, aprenderá a exponer la funcionalidad de una aplicación web de Spring Boot a través de OpenAPI, agregarla como una herramienta al servicio Foundry Agent y interactuar con la aplicación mediante lenguaje natural en el área de juegos de agentes.

Si la aplicación web ya tiene características útiles, como compras, reservas de hoteles o administración de datos, es fácil hacer que esas funcionalidades estén disponibles para un agente de IA en foundry Agent Service. Al agregar un esquema openAPI a la aplicación, permite que el agente comprenda y use las funcionalidades de la aplicación cuando responda a las indicaciones de los usuarios. Esto significa que cualquier cosa que pueda hacer la aplicación, el agente de IA también puede hacer, con un esfuerzo mínimo más allá de crear un punto de conexión de OpenAPI para la aplicación. En este tutorial, empezará con una sencilla aplicación de lista de tareas pendientes. Al final, podrá crear, actualizar y administrar tareas con un agente mediante inteligencia artificial conversacional.

Prerrequisitos

En este tutorial se da por supuesto que está trabajando con el ejemplo usado en Tutorial: Compilación de una aplicación web de Java Spring Boot con Azure App Service en Linux y Azure Cosmos DB.

Como mínimo, abra la aplicación de ejemplo en GitHub Codespaces e implemente la aplicación mediante la ejecución de azd up.

Adición de la funcionalidad de OpenAPI a la aplicación web

1. En el espacio de código, abra pom.xml y agregue la dependencia siguiente:

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

2. Abra src/main/java/com/microsoft/azure/appservice/examples/springbootmongodb/controller/TodoListController.java y agregue las siguientes importaciones.

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

   La TodoListController clase implementa @RestController, por lo que solo tiene que agregar algunas anotaciones para que sea compatible con OpenAPI. Además, para que las API sean compatibles con el servicio Foundry Agent, debe especificar la operationId propiedad en la @Operation anotación (consulte Uso del servicio de agente foundry con herramientas especificadas de OpenAPI: requisitos previos).

3. Busque la declaración de clase y agregue la @Tag anotación como se muestra en el siguiente fragmento de código:

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

4. Busque la declaración del getTodoItem método y agregue la @Operation anotación con description y operationId, como se muestra en el siguiente fragmento de código:

   @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. Busque la declaración del getAllTodoItems método y agregue la @Operation anotación con description y operationId, como se muestra en el siguiente fragmento de código:

   @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. Busque la declaración del addNewTodoItem método y agregue la @Operation anotación con description y operationId, como se muestra en el siguiente fragmento de código:

   @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. Busque la declaración del updateTodoItem método y agregue la @Operation anotación con description y operationId, como se muestra en el siguiente fragmento de código:

   @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. Busque la declaración del deleteTodoItem método y agregue la @Operation anotación con description y operationId, como se muestra en el siguiente fragmento de código:

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

   Esta configuración mínima proporciona las siguientes opciones, como se documenta en springdoc-openapi:

   • Interfaz de usuario de Swagger en /swagger-ui.html.
   • Especificación de OpenAPI en /v3/api-docs.

9. En el terminal de codespace, ejecute la aplicación con mvn spring-boot:run.

10. Seleccione Abrir en el explorador.

11. Vaya a la interfaz de usuario de Swagger agregando /swagger-ui.html a la dirección URL.

12. Confirme que las operaciones de API funcionan probando en la interfaz de usuario de Swagger.

13. Regrese al terminal de Codespace, implemente los cambios realizando un commit de sus cambios (método Acciones de GitHub) o ejecutando azd up (método de la CLI para desarrolladores de Azure).

14. Una vez implementados los cambios, vaya a https://<your-app's-url>/v3/api-docs y copie el esquema para más adelante.

Creación de un agente en Microsoft Foundry

1. En el portal de Foundry, en el menú superior derecho, seleccione Nuevo Foundry.

2. Si esta es la primera vez en el nuevo portal de Foundry, seleccione el nombre del proyecto y seleccione Crear nuevo proyecto.

3. Asigne un nombre al proyecto y seleccione Crear.

4. Seleccione Iniciar compilación y, a continuación, Crear agente.

5. Asigne un nombre al agente y seleccione Crear. Cuando el agente esté listo, debería ver el área de juegos del agente.

   Tenga en cuenta los modelos que puede usar y las regiones disponibles.

6. En el área de juegos del agente, expanda Herramientas y seleccione Agregar>Personalizar>herramienta OpenAPI>Crear.

7. Asigne un nombre a la herramienta y una descripción. En el cuadro esquema OpenAPI 3.0+ , pegue el esquema que copió anteriormente.

8. Seleccione Crear herramienta.

9. Haga clic en Guardar.

Prueba del agente

1. En Instrucciones, proporcione algunas instrucciones sencillas, como "Use la herramienta todosApp para ayudar a administrar las tareas".

2. Chatee con el agente con las siguientes sugerencias de aviso:

   • Muéstrame todas las tareas.
   • Cree una tarea denominada "Inventar tres chistes sobre lechuga".
   • Cámbialo a "Inventa tres chistes de 'toc toc'".

   

Procedimientos recomendados de seguridad

Al exponer las API a través de OpenAPI en Azure App Service, siga estos procedimientos recomendados de seguridad:

• Autenticación y autorización: proteja los puntos de conexión de OpenAPI con la autenticación de Microsoft Entra. Para obtener instrucciones paso a paso, consulte Secure OpenAPI endpoints for Foundry Agent Service (Protección de puntos de conexión de OpenAPI para el servicio de agente foundry). También puede proteger los puntos de conexión detrás de Azure API Management con el identificador de Microsoft Entra y asegurarse de que solo los usuarios o agentes autorizados puedan acceder a las herramientas.
• Validar y sanear los datos de entrada: El código de ejemplo de este tutorial omite la validación y el saneamiento de entrada para simplificar y claridad. En escenarios de producción, implemente siempre la validación y la sanación adecuadas para proteger la aplicación. Para Spring, vea Spring: Validación de la entrada del formulario.
• Use HTTPS: El ejemplo se basa en Azure App Service, que aplica HTTPS de forma predeterminada y proporciona certificados TLS/SSL gratuitos para cifrar los datos en tránsito.
• Limitar CORS: Restrinja el uso compartido de recursos entre orígenes (CORS) solo a dominios de confianza. Para obtener más información, vea Habilitar CORS.
• Aplicar limitación de velocidad: Use API Management o middleware personalizado para evitar abuso y ataques de denegación de servicio.
• Ocultar puntos de conexión confidenciales: Evite exponer las API internas o administrativas en el esquema de OpenAPI.
• Revise el esquema de OpenAPI: Asegúrese de que el esquema de OpenAPI no filtra información confidencial (por ejemplo, direcciones URL internas, secretos o detalles de implementación).
• Mantener actualizadas las dependencias: Actualice periódicamente los paquetes NuGet y supervise los avisos de seguridad.
• Supervisión y actividad de registro: Habilite el registro y supervise el acceso para detectar actividades sospechosas.
• Uso de identidades administradas: Al llamar a otros servicios de Azure, use identidades administradas en lugar de credenciales codificadas de forma dura.

Para más información, consulte Protección de la aplicación de App Service y Procedimientos recomendados para la seguridad de la API REST.

Paso siguiente

Ahora has habilitado tu aplicación de App Service para que la use el Servicio de Agente de Foundry e interactúe con las API de tu aplicación a través del lenguaje natural en el entorno de prueba de agentes. Desde aquí, puede seguir agregando características al agente en el portal de Foundry, integrarla en sus propias aplicaciones mediante el SDK de Microsoft Foundry o la API REST, o implementarla como parte de una solución más grande. Los agentes creados en Microsoft Foundry se pueden ejecutar en la nube, integrados en bots de chat o insertados en aplicaciones web y móviles.

Más recursos

• Integración de la inteligencia artificial en las aplicaciones de Azure App Service
• ¿Qué es Foundry Agent Service?