Hinzufügen einer App Service-App als Tool im Foundry Agent Service (Node.js)

In diesem Lernprogramm erfahren Sie, wie Sie die Funktionalität einer Express.js App über OpenAPI verfügbar machen, sie als Tool zum Foundry Agent Service hinzufügen und mit Ihrer App mit natürlicher Sprache im Agents-Playground interagieren.

Wenn Ihre Webanwendung bereits nützliche Funktionen wie Shopping, Hotelbuchung oder Datenverwaltung aufweist, ist es einfach, diese Funktionen einem KI-Agenten im Foundry Agent Service zur Verfügung zu stellen. Indem Sie Ihrer App einfach ein OpenAPI-Schema hinzufügen, ermöglichen Sie dem Agenten, die Funktionen Ihrer App zu verstehen und zu nutzen, wenn er auf die Eingabeaufforderungen der Benutzer reagiert. Dies bedeutet, dass ihre App alles tun kann, was Ihr KI-Agent auch tun kann, mit minimalem Aufwand, der über das Erstellen eines OpenAPI-Endpunkts für Ihre App hinausgeht. In dieser Anleitung beginnen Sie mit einer einfachen To-Do-Listen-App. Letztendlich können Sie Aufgaben mithilfe eines virtuellen Assistenten über konversationsfähige KI erstellen, aktualisieren und verwalten.

Prerequisites

In diesem Lernprogramm wird davon ausgegangen, dass Sie mit dem Beispiel arbeiten, das im Lernprogramm verwendet wird: Bereitstellen einer Node.js + MongoDB-Web-App in Azure.

Öffnen Sie mindestens die Beispielanwendung in GitHub Codespaces, und stellen Sie die App durch Ausführen azd upbereit.

Hinzufügen von OpenAPI-Funktionen zu Ihrer Web-App

1. Fügen Sie im Codespace-Terminal das NuGet swagger-jsdoc NPM-Paket zu Ihrem Projekt hinzu:

   npm install swagger-jsdoc
   

2. Öffnen Sie Routen/index.js. Am Ende der Datei, oberhalb von module.exports = router;, fügen Sie die folgenden API-Funktionen hinzu. Um sie mit dem Foundry Agent Service kompatibel zu machen, müssen Sie die operationId Eigenschaft in der @swagger Anmerkung angeben (siehe Verwendung des Foundry Agent Service mit OpenAPI Specified Tools: Prerequisites).

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

   Dieser Code dupliziert die Funktionalität der vorhandenen Routen, was nicht erforderlich ist, sie wird jedoch zur Vereinfachung beibehalten. Es empfiehlt sich, die App-Logik auf freigegebene Funktionen zu verschieben und diese sowohl über die MVC-Routen als auch über die OpenAPI-Routen aufzurufen.

3. Führen Sie im Codespace-Terminal die Anwendung mit npm start aus.

4. Wählen Sie "Im Browser öffnen" aus.

5. Zeigen Sie das OpenAPI-Schema an, indem Sie /schema zur URL hinzufügen.

6. Stellen Sie ihre Änderungen wieder im Codespace-Terminal bereit, indem Sie Änderungen übernehmen (GitHub Actions-Methode) oder azd up ausführen (Azure Developer CLI-Methode).

7. Nachdem Ihre Änderungen bereitgestellt wurden, navigieren Sie zu https://<your-app's-url>/schema und kopieren Sie das Schema, um es später zu verwenden.

Erstellen eines Agents in Microsoft Foundry

1. Wählen Sie im Findry-Portal im oberen rechten Menü die Option "Neue Gießerei" aus.

2. Wenn Dies Ihr erstes Mal im neuen Foundry-Portal ist, wählen Sie den Projektnamen und dann "Neues Projekt erstellen" aus.

3. Geben Sie Ihrem Projekt einen Namen, und wählen Sie "Erstellen" aus.

4. Wählen Sie "Erstellen beginnen" und dann "Agent erstellen" aus.

5. Geben Sie Ihrem Agent einen Namen, und wählen Sie "Erstellen" aus. Wenn der Agent bereit ist, sollten Sie den Agent-Playground sehen.

   Beachten Sie die Modelle, die Sie verwenden können, und die verfügbaren Regionen.

6. Erweitern Sie im Agent-Playground Tools und wählen Sie Hinzufügen>Benutzerdefiniertes>OpenAPI-Tool>Erstellen aus.

7. Geben Sie dem Tool einen Namen und eine Beschreibung. Fügen Sie im Feld "OpenAPI 3.0+" das Zuvor kopierte Schema ein.

8. Wählen Sie "Tool erstellen" aus.

9. Wählen Sie Speichern aus.

Testen des Agents

1. Geben Sie in Den Anweisungen einige einfache Anweisungen an, z. B. "Verwenden Sie das TodosApp-Tool, um Aufgaben zu verwalten."

2. Chatten Sie mit dem Agent mit den folgenden Prompt-Empfehlungen:

   • Alle Aufgaben anzeigen.
   • Erstellen Sie eine Aufgabe, genannt "Drei Witze über Salat machen".
   • Ändern Sie dies in "Erfinden Sie drei 'Knock-Knock'-Witze."

   

Bewährte Sicherheitsmethoden

Befolgen Sie beim Verfügbarmachen von APIs über OpenAPI in Azure App Service die folgenden bewährten Sicherheitsmethoden:

• Authentifizierung und Autorisierung: Schützen Sie Ihre OpenAPI-Endpunkte mit der Microsoft Entra-Authentifizierung. Schrittweise Anleitungen finden Sie unter Secure OpenAPI-Endpunkte für Foundry Agent Service. Sie können Ihre Endpunkte auch hinter Azure API Management mit Microsoft Entra ID schützen und sicherstellen, dass nur autorisierte Benutzer oder Agents auf die Tools zugreifen können.
• Überprüfen von Eingabedaten: Überprüfen Sie eingehende Daten immer, um ungültige oder böswillige Eingaben zu verhindern. Verwenden Sie für Node.js Apps Bibliotheken wie Express validator , um Datenüberprüfungsregeln zu erzwingen. Weitere Informationen zu bewährten Methoden und Implementierungsdetails finden Sie in der Dokumentation.
• Https verwenden: Das Beispiel basiert auf Azure App Service, der STANDARDMÄßIG HTTPS erzwingt und kostenlose TLS/SSL-Zertifikate zum Verschlüsseln von Daten während der Übertragung bereitstellt.
• CORS begrenzen: Beschränken Sie die ursprungsübergreifende Ressourcenfreigabe (Cross-Origin Resource Sharing, CORS) nur auf vertrauenswürdige Domains. Weitere Informationen finden Sie unter Aktivieren von CORS.
• Anwenden von Ratenbeschränkungen: Verwenden Sie API-Verwaltung oder benutzerdefinierte Middleware, um Missbrauch und Denial-of-Service-Angriffe zu verhindern.
• Vertrauliche Endpunkte ausblenden: Vermeiden Sie die Bereitstellung interner oder Administrator-APIs in Ihrem OpenAPI-Schema.
• OpenAPI-Schema überprüfen: Stellen Sie sicher, dass Ihr OpenAPI-Schema keine vertraulichen Informationen (z. B. interne URLs, geheime Schlüssel oder Implementierungsdetails) verloren geht.
• Halten Sie Abhängigkeiten aktuell: Aktualisieren Sie NuGet-Pakete regelmäßig und überwachen Sie Sicherheitshinweise.
• Überwachen und Protokollieren von Aktivitäten: Aktivieren Sie die Protokollierung und überwachen Sie den Zugriff, um verdächtige Aktivitäten zu erkennen.
• Verwaltete Identitäten verwenden: Verwenden Sie beim Aufrufen anderer Azure-Dienste verwaltete Identitäten anstelle von hartcodierten Anmeldeinformationen.

Weitere Informationen finden Sie unter Secure your App Service app and Best Practices for REST API security.

Nächster Schritt

Dank der Aktivierung Ihrer App Service-App kann letztere künftig vom Foundry Agent Service als Tool verwendet werden und mit den APIs Ihrer App im App-Playground über natürliche Sprache interagieren. Von hier aus können Sie Ihrem Agent weiterhin Features im Foundry-Portal hinzufügen, sie mithilfe des Microsoft Foundry SDK oder der REST-API in Ihre eigenen Anwendungen integrieren oder als Teil einer größeren Lösung bereitstellen. In Microsoft Foundry erstellte Agents können in der Cloud ausgeführt, in Chatbots integriert oder in Web- und mobile Apps eingebettet werden.

Wenn Sie den nächsten Schritt ausführen und erfahren möchten, wie Sie Ihren Agent direkt in Azure App Service ausführen, lesen Sie das folgende Lernprogramm:

Weitere Ressourcen

• Integrieren von KI in Ihre Azure App Service-Anwendungen
• Was ist Foundry Agent Service?