Adición de una aplicación de App Service como herramienta en Foundry Agent Service (.NET)

En este tutorial, aprenderá a exponer la funcionalidad de una aplicación ASP.NET Core 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 que se usa en Tutorial: Implementación de una aplicación de ASP.NET Core y Azure SQL Database en Azure App Service.

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

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

1. En el terminal de codespace, agregue los paquetes Swashbuckle de NuGet al proyecto:

   dotnet add package Swashbuckle.AspNetCore --version 6.5.0
   dotnet add package Swashbuckle.AspNetCore.Annotations --version 6.5.0
   

2. En Controllers/TodosController.cs, agregue los siguientes métodos de API. Para que sean compatibles con el servicio foundry Agent, debe especificar la OperationId propiedad en el SwaggerOperation atributo (consulte Uso del servicio foundry Agent con herramientas especificadas de OpenAPI: requisitos previos).

       // GET: api/todos
       [HttpGet("api/todos")]
       [SwaggerOperation(Summary = "Gets all Todo items", OperationId = "GetTodos")]
       [ProducesResponseType(typeof(IEnumerable<Todo>), 200)]
       public async Task<ActionResult<IEnumerable<Todo>>> GetTodos()
       {
           return await _context.Todo.ToListAsync();
       }
   
       // GET: api/todos/5
       [HttpGet("api/todos/{id}")]
       [SwaggerOperation(Summary = "Gets a Todo item by ID", OperationId = "GetTodoById")]
       [ProducesResponseType(typeof(Todo), 200)]
       [ProducesResponseType(404)]
       public async Task<ActionResult<Todo>> GetTodo(int id)
       {
           var todo = await _context.Todo.FindAsync(id);
   
           if (todo == null)
           {
               return NotFound();
           }
   
           return todo;
       }
   
   
   // POST: api/todos
   [HttpPost("api/todos")]
   [ProducesResponseType(StatusCodes.Status201Created)]
   [ProducesResponseType(StatusCodes.Status400BadRequest)]
   [SwaggerOperation(Summary = "Creates a new todo item.", Description = "Creates a new todo item and returns it.", OperationId = "CreateTodo")]
   public async Task<IActionResult> CreateTodo([FromBody] Todo todo)
   {
       if (!ModelState.IsValid)
       {
           return BadRequest(ModelState);
       }
       _context.Add(todo);
       await _context.SaveChangesAsync();
       return CreatedAtAction(nameof(GetTodo), new { id = todo.ID }, todo);
   }
   
   // PUT: api/todos/{id}
   [HttpPut("api/todos/{id}")]
   [ProducesResponseType(StatusCodes.Status204NoContent)]
   [ProducesResponseType(StatusCodes.Status400BadRequest)]
   [ProducesResponseType(StatusCodes.Status404NotFound)]
   [SwaggerOperation(Summary = "Updates a todo item.", Description = "Updates an existing todo item by ID.", OperationId = "UpdateTodo")]
   public async Task<IActionResult> UpdateTodo(int id, [FromBody] Todo todo)
   {
       // Use the id from the URL fragment only, ignore mismatching check
       if (!TodoExists(id))
       {
           return NotFound();
       }
       todo.ID = id;
       _context.Entry(todo).State = EntityState.Modified;
       await _context.SaveChangesAsync();
       return NoContent();
   }
   
   // DELETE: api/todos/{id}
   [HttpDelete("api/todos/{id}")]
   [ProducesResponseType(StatusCodes.Status204NoContent)]
   [ProducesResponseType(StatusCodes.Status404NotFound)]
   [SwaggerOperation(Summary = "Deletes a todo item.", Description = "Deletes a todo item by ID.", OperationId = "DeleteTodo")]
   public async Task<IActionResult> DeleteTodo(int id)
   {
       var todo = await _context.Todo.FindAsync(id);
       if (todo == null)
       {
           return NotFound();
       }
       _context.Todo.Remove(todo);
       await _context.SaveChangesAsync();
       return NoContent();
   }
   

3. En la parte superior de Controladores/TodosController.cs, agregue lo siguiente mediante:

   using Swashbuckle.AspNetCore.Annotations;
   

   Este código duplica la funcionalidad del controlador existente, que no es necesario, pero lo mantendrá por motivos de simplicidad. Un procedimiento recomendado sería mover la lógica de la aplicación a una clase de servicio y, a continuación, llamar a los métodos de servicio desde las acciones de MVC y desde los métodos de API.

4. En Program.cs, registre el servicio generador de Swagger. Esto habilita la documentación de OpenAPI para la API, lo que permite a Foundry Agent Service comprender las API. Asegúrese de especificar la dirección URL del servidor. Foundry Agent Service necesita un esquema que contenga la dirección URL del servidor.

   builder.Services.AddSwaggerGen(c =>
   {
       c.EnableAnnotations();
       var websiteHostname = Environment.GetEnvironmentVariable("WEBSITE_HOSTNAME");
       if (!string.IsNullOrEmpty(websiteHostname))
       {
           c.AddServer(new Microsoft.OpenApi.Models.OpenApiServer { Url = $"https://{websiteHostname}" });
       }
   });
   

5. En Program.cs, habilite el middleware de Swagger. Este middleware sirve la documentación de OpenAPI generada en tiempo de ejecución, lo que hace que sea accesible a través de un explorador.

   app.UseSwagger();
   app.UseSwaggerUI();
   

6. En el terminal de codespace, ejecute la aplicación con dotnet run.

7. Seleccione Abrir en el explorador.

8. Vaya a la interfaz de usuario de Swagger agregando /swagger/index.html a la dirección URL.

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

10. De nuevo en el terminal de codespace, implemente los cambios confirmando los cambios (método Acciones de GitHub) o ejecute azd up (método de la CLI para desarrolladores de Azure).

11. Una vez implementados los cambios, vaya a https://<your-app's-url>/swagger/v1/swagger.json 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>la herramienta>OpenAPI personalizada>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 los datos de entrada: El código de ejemplo comprueba ModelState.IsValid en el CreateTodo método , lo que garantiza que los datos entrantes coincidan con los atributos de validación del modelo. Para obtener más información, consulte Validación de modelos en ASP.NET Core.
• 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 ha habilitado su aplicación de servicio de aplicaciones para que la use el Servicio de Agente de Foundry e interactúe con las API de su aplicación a través del lenguaje natural en el entorno de pruebas 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.

Para realizar el siguiente paso y aprender a ejecutar el agente directamente en Azure App Service, consulte el siguiente tutorial:

Más recursos

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