Ajouter une application App Service en tant qu’outil dans Foundry Agent Service (Spring Boot)

Dans ce tutoriel, vous allez apprendre à exposer les fonctionnalités d’une application web Spring Boot via OpenAPI, à l’ajouter en tant qu’outil au service De l’agent Foundry 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.

• Ajoutez des fonctionnalités OpenAPI à votre application web.
• Assurez-vous que le schéma OpenAPI est compatible avec le service de l'agent Foundry.
• Inscrivez votre application en tant qu’outil OpenAPI dans Foundry Agent Service.
• Testez votre agent dans le terrain de jeu des agents.

Conditions préalables

Ce tutoriel part du principe que vous utilisez l’exemple utilisé dans le tutoriel : Créer une application web Java Spring Boot avec Azure App Service sur Linux et Azure Cosmos DB.

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

Conseil / Astuce

Vous pouvez apporter toutes les modifications suivantes en indiquant à GitHub Copilot en mode Agent :

I'd like to generate OpenAPI functionality using Spring Boot OpenAPI. Please also generate the server URL and operation ID in the schema.

1. Dans l’espace de code, ouvrez pom.xml et ajoutez la dépendance suivante :

   <dependency>
       <groupId>org.springdoc</groupId>
       <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
       <version>2.6.0</version>
   </dependency>
   

2. Ouvrez src/main/java/com/microsoft/azure/appservice/examples/springbootmongodb/controller/TodoListController.java et ajoutez les importations suivantes.

   import io.swagger.v3.oas.annotations.Operation;
   import io.swagger.v3.oas.annotations.tags.Tag;
   

   La TodoListController classe implémente @RestController, donc vous devez uniquement ajouter quelques annotations pour la rendre compatible avec OpenAPI. En outre, pour rendre les API compatibles avec le service De l’agent Foundry, vous devez spécifier la operationId propriété dans l’annotation @Operation (voir Comment utiliser le service De l’agent Foundry avec les outils spécifiés OpenAPI : Prérequis).

3. Recherchez la déclaration de classe et ajoutez l’annotation @Tag comme indiqué dans l’extrait de code suivant :

   @RestController
   @Tag(name = "Todo List", description = "Todo List management APIs")
   public class TodoListController {
   

4. Recherchez la getTodoItem déclaration de méthode et ajoutez l’annotation @Operation avec description et operationId, comme indiqué dans l’extrait de code suivant :

   @Operation(description = "Returns a single todo item", operationId = "getTodoItem")
   @GetMapping(path = "/api/todolist/{index}", produces = {MediaType.APPLICATION_JSON_VALUE})
   public TodoItem getTodoItem(@PathVariable("index") String index) {
   

5. Recherchez la getAllTodoItems déclaration de méthode et ajoutez l’annotation @Operation avec description et operationId, comme indiqué dans l’extrait de code suivant :

   @Operation(description = "Returns a list of all todo items", operationId = "getAllTodoItems")
   @GetMapping(path = "/api/todolist", produces = {MediaType.APPLICATION_JSON_VALUE})
   public List<TodoItem> getAllTodoItems() {
   

6. Recherchez la addNewTodoItem déclaration de méthode et ajoutez l’annotation @Operation avec description et operationId, comme indiqué dans l’extrait de code suivant :

   @Operation(description = "Creates a new todo item", operationId = "addNewTodoItem")
   @PostMapping(path = "/api/todolist", consumes = MediaType.APPLICATION_JSON_VALUE)
   public String addNewTodoItem(@RequestBody TodoItem item) {
   

7. Recherchez la updateTodoItem déclaration de méthode et ajoutez l’annotation @Operation avec description et operationId, comme indiqué dans l’extrait de code suivant :

   @Operation(description = "Updates an existing todo item", operationId = "updateTodoItem")
   @PutMapping(path = "/api/todolist", consumes = MediaType.APPLICATION_JSON_VALUE)
   public String updateTodoItem(@RequestBody TodoItem item) {
   

8. Recherchez la deleteTodoItem déclaration de méthode et ajoutez l’annotation @Operation avec description et operationId, comme indiqué dans l’extrait de code suivant :

   @Operation(description = "Deletes a todo item by ID", operationId = "deleteTodoItem")
   @DeleteMapping("/api/todolist/{id}")
   public String deleteTodoItem(@PathVariable("id") String id) {
   

   Cette configuration minimale vous donne les paramètres suivants, comme documenté dans springdoc-openapi :

   • Interface utilisateur Swagger à l’adresse /swagger-ui.html.
   • Spécification OpenAPI à l’adresse /v3/api-docs.

9. Dans le terminal codespace, exécutez l’application avec mvn spring-boot:run.

10. Sélectionnez Ouvrir dans le navigateur.

11. Accédez à l’interface utilisateur Swagger en ajoutant /swagger-ui.html à l’URL.

12. Vérifiez que les opérations d’API fonctionnent en les essayant dans l’interface utilisateur Swagger.

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

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

Créer un agent dans Microsoft Foundry

1. Créez un agent dans le portail Foundry en suivant les étapes de : Démarrage rapide : Créer un agent.

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

2. Sélectionnez le nouvel agent et ajoutez une action avec l’outil spécifié OpenAPI 3.0 en suivant les étapes décrites dans Comment utiliser l’outil de spécification OpenAPI.

3. Dans la page Définir le schéma , collez le schéma que vous avez copié précédemment. Révisez et enregistrez l’action.

Conseil / Astuce

Dans ce tutoriel, l’outil OpenAPI est configuré pour appeler votre application anonymement sans authentification. Pour les scénarios de production, vous devez sécuriser l’outil avec l’authentification d’identité managée. Pour obtenir des instructions pas à pas, consultez Points de terminaison OpenAPI sécurisés pour le service de l'agent Foundry.

Tester l’agent

1. Si le terrain de jeu des assistants n’est pas encore ouvert dans le portail Foundry, sélectionnez l’assistant et sélectionnez Essayer dans le terrain de jeu.

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

3. 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 service de l'agent Foundry. 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 et nettoyer les données d’entrée : L’exemple de code de ce didacticiel omet la validation et l’assainissement des entrées pour plus de simplicité et de clarté. Dans les scénarios de production, implémentez toujours une validation et une assainissement appropriés pour protéger votre application. Pour Spring, consultez Spring : Validation de l’entrée de formulaire.
• 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.

Remarque

Le service de l'agent Foundry n’a pas de SDK Java actuellement. Pour voir comment utiliser l’agent que vous avez créé, consultez Tutoriel : Créer une application web agentique dans Azure App Service avec le noyau sémantique Microsoft ou le service de l’agent foundry (.NET).

Plus de ressources

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