Dodaj aplikację usługi App Service jako narzędzie w usłudze agenta Foundry (Node.js)

W tym samouczku dowiesz się, jak udostępnić funkcjonalność aplikacji Express.js za pomocą OpenAPI, dodać ją jako narzędzie do usługi agenta Foundry i wchodzić w interakcje z aplikacją przy użyciu języka naturalnego w środowisku testowym agentów.

Jeśli aplikacja internetowa ma już przydatne funkcje, takie jak zakupy, rezerwacja hotelowa lub zarządzanie danymi, można łatwo udostępnić te możliwości agentowi sztucznej inteligencji w usłudze Agent usługi Foundry. Po prostu dodając schemat interfejsu OpenAPI do aplikacji, możesz umożliwić agentowi zrozumienie możliwości aplikacji i korzystanie z nich podczas odpowiadania na monity użytkowników. Oznacza to, że wszystko, co może zrobić twoja aplikacja, agent sztucznej inteligencji może również zrobić, przy minimalnym nakładzie pracy poza tworzeniem punktu końcowego interfejsu OpenAPI dla aplikacji. W tym samouczku zaczniesz od prostej aplikacji typu lista to-do. Na koniec będziesz mieć możliwość tworzenia, aktualizowania i zarządzania zadaniami za pomocą agenta za pośrednictwem konwersacyjnej sztucznej inteligencji.

Prerequisites

W tym samouczku założono, że pracujesz z przykładem używanym w artykule Samouczek: wdrażanie aplikacji internetowej Node.js + MongoDB na platformie Azure.

Otwórz co najmniej przykładową aplikację w usłudze GitHub Codespaces i wdróż aplikację, uruchamiając polecenie azd up.

Dodawanie funkcji interfejsu OpenAPI do aplikacji internetowej

1. W terminalu usługi Codespace dodaj pakiet NPM nuGet swagger-jsdoc do projektu:

   npm install swagger-jsdoc
   

2. Otwórz ścieżki/index.js. W dolnej części pliku powyżej module.exports = router; dodaj następujące funkcje API. Aby zapewnić ich zgodność z usługą agenta foundry, należy określić operationId właściwość w @swagger adnotacji (zobacz How to use Foundry Agent Service with OpenAPI Specified Tools: Prerequisites (Jak używać usługi agenta foundry z określonymi narzędziami OpenAPI: Wymagania wstępne).

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

   Ten kod duplikuje funkcjonalność istniejących tras, co jest niepotrzebne, ale zachowasz je dla uproszczenia. Najlepszym rozwiązaniem jest przeniesienie logiki aplikacji do funkcji udostępnionych, a następnie wywołanie ich zarówno z tras MVC, jak i z tras interfejsu OpenAPI.

3. W terminalu usługi Codespace uruchom aplikację za pomocą npm start polecenia.

4. Kliknij pozycję Otwórz w przeglądarce.

5. Wyświetl schemat interfejsu OpenAPI, dodając /schema go do adresu URL.

6. W terminalu usługi Codespace wdróż zmiany, zatwierdzając zmiany (metodę GitHub Actions) lub uruchamiając azd up (metoda interfejsu wiersza polecenia dewelopera platformy Azure).

7. Po wdrożeniu zmian przejdź do https://<your-app's-url>/schema i skopiuj schemat do późniejszego użycia.

Tworzenie agenta w rozwiązaniu Microsoft Foundry

1. W portalu Foundry w prawym górnym menu wybierz pozycję New Foundry.

2. Jeśli jest to twój pierwszy raz w nowym portalu Foundry, wybierz nazwę projektu i wybierz pozycję Utwórz nowy projekt.

3. Nadaj projektowi nazwę i wybierz pozycję Utwórz.

4. Wybierz pozycję Rozpocznij kompilowanie, a następnie pozycję Utwórz agenta.

5. Nadaj agentowi nazwę i wybierz pozycję Utwórz. Gdy agent jest gotowy, powinien zostać wyświetlony plac zabaw agenta.

   Zwróć uwagę na modele, których można użyć, i dostępnych regionów.

6. Na placu zabaw dla agentów rozwiń Narzędzia i wybierz Dodaj>Niestandardowe>narzędzie OpenAPI>Utwórz.

7. Nadaj narzędziu nazwę i opis. W polu schematu OpenAPI 3.0+ wklej skopiowany wcześniej schemat.

8. Wybierz pozycję Utwórz narzędzie.

9. Wybierz Zapisz.

Przetestuj agenta

1. W obszarze Instrukcje podaj proste instrukcje, takie jak "Użyj narzędzia todosApp, aby ułatwić zarządzanie zadaniami".

2. Porozmawiaj z agentem, wykorzystując następujące podpowiedzi.

   • Pokaż mi wszystkie zadania.
   • Utwórz zadanie o nazwie „Wymyśl trzy żarty o sałacie”.
   • Zmień to na "Wymyśl trzy dowcipy knock-knock."

   

Najlepsze rozwiązania dotyczące zabezpieczeń

W przypadku uwidaczniania interfejsów API za pośrednictwem interfejsu OpenAPI w usłudze Azure App Service postępuj zgodnie z następującymi najlepszymi rozwiązaniami w zakresie zabezpieczeń:

• Uwierzytelnianie i autoryzacja: ochrona punktów końcowych interfejsu OpenAPI przy użyciu uwierzytelniania firmy Microsoft Entra. Aby uzyskać instrukcje krok po kroku, zobacz Zabezpieczanie punktów końcowych interfejsu OpenAPI dla usługi agenta Foundry. Możesz również chronić punkty końcowe za pomocą usługi Azure API Management przy użyciu identyfikatora Microsoft Entra ID i upewnić się, że tylko autoryzowani użytkownicy lub agenci mogą uzyskiwać dostęp do narzędzi.
• Weryfikowanie danych wejściowych: Zawsze weryfikuj dane przychodzące, aby zapobiec nieprawidłowym lub złośliwym danym wejściowym. W przypadku aplikacji Node.js użyj bibliotek, takich jak express-validator , aby wymusić reguły sprawdzania poprawności danych. Zapoznaj się z ich dokumentacją, aby uzyskać szczegółowe informacje na temat najlepszych rozwiązań i implementacji.
• Użyj protokołu HTTPS: Przykład opiera się na usłudze Azure App Service, która domyślnie wymusza protokół HTTPS i udostępnia bezpłatne certyfikaty TLS/SSL do szyfrowania danych przesyłanych.
• Ogranicz mechanizm CORS: Ogranicz udostępnianie zasobów między źródłami (CORS) tylko do zaufanych domen. Aby uzyskać więcej informacji, zobacz Włączanie mechanizmu CORS.
• Zastosuj ograniczanie szybkości: Użyj usługi API Management lub niestandardowego oprogramowania pośredniczącego, aby zapobiec nadużyciom i atakom typu "odmowa usługi".
• Ukryj poufne punkty końcowe: Unikaj uwidaczniania wewnętrznych lub administracyjnych interfejsów API w schemacie interfejsu OpenAPI.
• Przejrzyj schemat OpenAPI: Upewnij się, że schemat interfejsu OpenAPI nie wycieka poufnych informacji (takich jak wewnętrzne adresy URL, wpisy tajne lub szczegóły implementacji).
• Zachowaj zaktualizowane zależności: Regularnie aktualizuj pakiety NuGet i monitoruj je pod kątem biuletynów zabezpieczeń.
• Monitorowanie i rejestrowanie aktywności: Włącz rejestrowanie i monitoruj dostęp do wykrywania podejrzanych działań.
• Użyj tożsamości zarządzanych: Podczas wywoływania innych usług platformy Azure użyj tożsamości zarządzanych zamiast zakodowanych na stałe poświadczeń.

Aby uzyskać więcej informacji, zobacz Zabezpieczanie aplikacji usługi App Service i Najlepsze rozwiązania dotyczące zabezpieczeń interfejsu API REST.

Następny krok

Aplikacja App Service została teraz skonfigurowana do użycia jako narzędzie przez Servis Agentów Foundry, umożliwiając interakcję z interfejsami API aplikacji za pomocą języka naturalnego w środowisku testowym agentów. W tym miejscu możesz nadal dodawać funkcje do agenta w portalu Foundry, integrować je z własnymi aplikacjami przy użyciu zestawu Microsoft Foundry SDK lub interfejsu API REST albo wdrażać je w ramach większego rozwiązania. Agentów utworzonych w rozwiązaniu Microsoft Foundry można uruchamiać w chmurze, integrować z czatbotami lub osadzać w aplikacjach internetowych i mobilnych.

Aby wykonać następny krok i dowiedzieć się, jak uruchomić agenta bezpośrednio w usłudze Azure App Service, zobacz następujący samouczek:

Więcej zasobów

• Integrowanie sztucznej inteligencji z aplikacjami usługi Azure App Service
• Co to jest usługa agenta programu Foundry?