Ajouter une application App Service en tant qu’outil dans Foundry Agent Service (Node.js)

Dans ce tutoriel, vous allez apprendre à exposer les fonctionnalités d’une application Express.js via OpenAPI, à l’ajouter en tant qu’outil au service Foundry Agent et à interagir avec votre application à l’aide du langage naturel dans le terrain de jeu des agents.

Si votre application web dispose déjà de fonctionnalités utiles, telles que le shopping, la réservation d’hôtels ou la gestion des données, il est facile de rendre ces fonctionnalités disponibles pour un agent IA dans le service De l’agent Foundry. En ajoutant simplement un schéma OpenAPI à votre application, vous pouvez permettre à l’agent de comprendre et d’utiliser les fonctionnalités de votre application lorsqu’elle répond aux invites des utilisateurs. Cela signifie que tout ce que votre application peut faire, votre agent IA peut également faire, avec un effort minimal au-delà de la création d’un point de terminaison OpenAPI pour votre application. Dans ce tutoriel, vous commencez par une application de liste to-do simple. À la fin, vous pourrez créer, mettre à jour et gérer des tâches avec un agent via l’IA conversationnelle.

Prerequisites

Ce didacticiel part du principe que vous utilisez l’exemple utilisé dans le didacticiel : Déployer une application web Node.js + MongoDB sur Azure.

Au minimum, ouvrez l’exemple d’application dans GitHub Codespaces et déployez l’application en exécutant azd up.

Ajouter des fonctionnalités OpenAPI à votre application web

1. Dans le terminal codespace, ajoutez le package NPM NuGet swagger-jsdoc à votre projet :

   npm install swagger-jsdoc
   

2. Ouvrez routes/index.js. En bas du fichier, au-dessus de module.exports = router;, ajoutez les fonctions API suivantes. Pour les rendre compatibles avec le service De l’agent Foundry, vous devez spécifier la operationId propriété dans l’annotation @swagger (voir Comment utiliser le service De l’agent Foundry avec les outils spécifiés OpenAPI : Prérequis).

   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 });
     }
   });
   

   Ce code consiste à dupliquer les fonctionnalités des itinéraires existants, ce qui n’est pas nécessaire, mais vous le conserverez par souci de simplicité. Une bonne pratique consisterait à déplacer la logique d’application vers des fonctions partagées, puis à les appeler à partir des itinéraires MVC et des itinéraires OpenAPI.

3. Dans le terminal codespace, exécutez l’application avec npm start.

4. Sélectionnez Ouvrir dans le navigateur.

5. Affichez le schéma OpenAPI en ajoutant /schema à l’URL.

6. De retour dans le terminal Codespace, déployez vos modifications en commitant vos modifications (méthode GitHub Actions) ou en exécutant azd up (méthode CLI du développeur Azure).

7. Une fois vos modifications déployées, accédez au https://<your-app's-url>/schema schéma et copiez-le ultérieurement.

Créer un agent dans Microsoft Foundry

1. Dans le portail Foundry, dans le menu supérieur droit, sélectionnez New Foundry.

2. S’il s’agit de votre première fois dans le nouveau portail Foundry, sélectionnez le nom du projet et sélectionnez Créer un projet.

3. Donnez un nom à votre projet, puis sélectionnez Créer.

4. Sélectionnez Démarrer la génération, puis Créer un agent.

5. Donnez un nom à votre agent et sélectionnez Créer. Lorsque l’agent est prêt, vous devriez voir l’agent playground.

   Notez les modèles que vous pouvez utiliser et les régions disponibles.

6. Dans l’agent playground, développez Tools (Outils) et sélectionnez Add (Ajouter)>Custom (Personnalisé)>OpenAPI tool (Outil OpenAPI)>Create (Créer).

7. Donnez un nom à l’outil et une description. Dans la zone de schéma OpenAPI 3.0+ , collez le schéma que vous avez copié précédemment.

8. Sélectionnez Créer un outil.

9. Cliquez sur Enregistrer.

Tester l’agent

1. Dans Instructions, donnez des instructions simples, telles que « Utilisez l’outil todosApp pour aider à gérer les tâches ».

2. Conversez avec l’assistant à l’aide des suggestions de requête suivantes :

   • Affichez-moi toutes les tâches.
   • Créez une tâche appelée « Trouver trois blagues de laitue ».
   • Changez-la par « Reviens avec de bonnes blagues ».

   

Bonnes pratiques de sécurité

Lors de l’exposition d’API via OpenAPI dans Azure App Service, suivez les bonnes pratiques de sécurité suivantes :

• Authentification et autorisation : Protégez vos points de terminaison OpenAPI avec l’authentification Microsoft Entra. Pour obtenir des instructions pas à pas, consultez points de terminaison OpenAPI sécurisés pour le Foundry Agent Service. Vous pouvez également protéger vos points de terminaison derrière Gestion des API Azure avec l’ID Microsoft Entra et garantir que seuls les utilisateurs ou agents autorisés peuvent accéder aux outils.
• Valider les données d’entrée : Validez toujours les données entrantes pour empêcher les entrées non valides ou malveillantes. Pour Node.js applications, utilisez des bibliothèques telles que le validateur express pour appliquer des règles de validation des données. Reportez-vous à leur documentation pour connaître les meilleures pratiques et les détails de l’implémentation.
• Utilisez HTTPS : L’exemple s’appuie sur Azure App Service, qui applique HTTPS par défaut et fournit des certificats TLS/SSL gratuits pour chiffrer les données en transit.
• Limiter CORS : Limitez le partage de ressources cross-origin (CORS) aux domaines approuvés uniquement. Pour plus d’informations, consultez Activer CORS.
• Appliquez la limitation du débit : Utilisez Gestion des API ou intergiciel personnalisé pour empêcher les attaques par abus et par déni de service.
• Masquer les points de terminaison sensibles : Évitez d’exposer des API internes ou d’administration dans votre schéma OpenAPI.
• Passez en revue le schéma OpenAPI : Vérifiez que votre schéma OpenAPI ne fuite pas d’informations sensibles (telles que les URL internes, les secrets ou les détails de l’implémentation).
• Conservez les dépendances mises à jour : Mettez régulièrement à jour les packages NuGet et surveillez les avis de sécurité.
• Surveiller et journaliser l’activité : Activez la journalisation et surveillez l’accès pour détecter les activités suspectes.
• Utilisez des identités managées : Lors de l’appel d’autres services Azure, utilisez des identités managées plutôt que des informations d’identification codées en dur.

Pour plus d’informations, consultez Sécuriser votre application App Service et les meilleures pratiques pour la sécurité des API REST.

Étape suivante

Vous avez maintenant activé l’utilisation de votre application App Service en tant qu’outil par Foundry Agent Service et interagir avec les API de votre application via le langage naturel dans le terrain de jeu des agents. À partir de là, vous pouvez continuer à ajouter des fonctionnalités à votre agent dans le portail Foundry, l’intégrer à vos propres applications à l’aide du Kit de développement logiciel (SDK) Microsoft Foundry ou de l’API REST, ou la déployer dans le cadre d’une solution plus grande. Les agents créés dans Microsoft Foundry peuvent être exécutés dans le cloud, intégrés à des chatbots ou incorporés dans des applications web et mobiles.

Pour effectuer l’étape suivante et découvrir comment exécuter votre agent directement dans Azure App Service, consultez le tutoriel suivant :

Plus de ressources

• Intégrer l’IA à vos applications Azure App Service
• Qu’est-ce que le Service de l’agent Foundry ?