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

En este tutorial, aprenderá a exponer una funcionalidad de Express.js aplicación a través de OpenAPI, agregarla como una herramienta al servicio Foundry Agent e 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 aplicación de lista de tareas pendientes sencilla. Al final, podrá crear, actualizar y administrar tareas con un agente mediante inteligencia artificial conversacional.

Prerequisites

En este tutorial se da por supuesto que está trabajando con el ejemplo que se usa en Tutorial: Implementación de una aplicación web de Node.js + MongoDB en Azure.

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 el paquete NPM de NuGet swagger-jsdoc al proyecto:

   npm install swagger-jsdoc
   

2. Abra routes/index.js. En la parte inferior del archivo, encima de module.exports = router;, agregue las siguientes funciones de API. Para que sean compatibles con el servicio foundry Agent, debe especificar la operationId propiedad en la @swagger anotación (consulte Uso del servicio foundry Agent con herramientas especificadas de OpenAPI: requisitos previos).

   router.get('/schema', function(req, res, next) {
     try {
       const swaggerJsdoc = require('swagger-jsdoc');
   
       res.json(
         swaggerJsdoc(
           {
             definition: {
               openapi: '3.0.0',
               servers: [
                 {
                   url: `${req.protocol}://${req.get('host')}`,
                   description: 'Task API',
                 },
               ],
             },
             apis: ['./routes/*.js'],
           }
         )
       );
     } catch (error) {
       res.status(500).json({ error: error.message });
     }
   });
   
   /**
    * @swagger
    * /api/tasks:
    *   get:
    *     summary: Get all tasks
    *     operationId: getAllTasks
    *     responses:
    *       200:
    *         description: List of tasks
    */
   router.get('/api/tasks', async function(req, res, next) {
     try {
       const tasks = await Task.find();
       res.json(tasks);
     } catch (error) {
       res.status(500).json({ error: error.message });
     }
   });
   
   /**
    * @swagger
    * /api/tasks/{id}:
    *   get:
    *     summary: Get task by ID
    *     operationId: getTaskById
    *     parameters:
    *       - in: path
    *         name: id
    *         required: true
    *         schema:
    *           type: string
    *     responses:
    *       200:
    *         description: Task details
    */
   router.get('/api/tasks/:id', async function(req, res, next) {
     try {
       const task = await Task.findById(req.params.id);
       res.json(task);
     } catch (error) {
       res.status(404).json({ error: error.message });
     }
   });
   
   /**
    * @swagger
    * /api/tasks:
    *   post:
    *     summary: Create a new task
    *     operationId: createTask
    *     requestBody:
    *       required: true
    *       content:
    *         application/json:
    *           schema:
    *             type: object
    *             properties:
    *               taskName:
    *                 type: string
    *     responses:
    *       201:
    *         description: Task created
    */
   router.post('/api/tasks', async function(req, res, next) {
     try {
       // Set createDate to current timestamp when creating a task
       const taskData = {
         ...req.body,
         createDate: new Date()
       };
   
       const task = new Task(taskData);
       await task.save();
       res.status(201).json(task);
     } catch (error) {
       res.status(400).json({ error: error.message });
     }
   });
   
   /**
    * @swagger
    * /api/tasks/{id}:
    *   put:
    *     summary: Update a task
    *     operationId: updateTask
    *     parameters:
    *       - in: path
    *         name: id
    *         required: true
    *         schema:
    *           type: string
    *     requestBody:
    *       required: true
    *       content:
    *         application/json:
    *           schema:
    *             type: object
    *             properties:
    *               taskName:
    *                 type: string
    *               completed:
    *                 type: boolean
    *     responses:
    *       200:
    *         description: Task updated
    */
   router.put('/api/tasks/:id', async function(req, res, next) {
     try {
       // If completed is being set to true, also set completedDate
       if (req.body.completed === true) {
         req.body.completedDate = new Date();
       }
   
       const task = await Task.findByIdAndUpdate(req.params.id, req.body, { new: true });
       res.json(task);
     } catch (error) {
       res.status(400).json({ error: error.message });
     }
   });
   
   /**
    * @swagger
    * /api/tasks/{id}:
    *   delete:
    *     summary: Delete a task
    *     operationId: deleteTask
    *     parameters:
    *       - in: path
    *         name: id
    *         required: true
    *         schema:
    *           type: string
    *     responses:
    *       200:
    *         description: Task deleted
    */
   router.delete('/api/tasks/:id', async function(req, res, next) {
     try {
       const task = await Task.findByIdAndDelete(req.params.id);
       res.json({ message: 'Task deleted successfully', task });
     } catch (error) {
       res.status(404).json({ error: error.message });
     }
   });
   

   Este código duplica la funcionalidad de las rutas existentes, lo 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 funciones compartidas y, a continuación, llamarlas desde las rutas de MVC y desde las rutas de OpenAPI.

3. En el terminal de codespace, ejecute la aplicación con npm start.

4. Seleccione Abrir en el explorador.

5. Para ver el esquema de OpenAPI, agregue /schema a la dirección URL.

6. 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).

7. Una vez implementados los cambios, vaya a https://<your-app's-url>/schema 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: Valide siempre los datos entrantes para evitar entradas no válidas o malintencionadas. Para Node.js aplicaciones, use bibliotecas como el validador rápido para aplicar reglas de validación de datos. Consulte su documentación para conocer los procedimientos recomendados y los detalles de implementación.
• 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 la aplicación de App Service para que se use como herramienta en Foundry Agent Service e interactúe con las API de la aplicación a través de lenguaje natural en el área de juegos 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?