Tutoriel : Créer une application web agentique dans Azure App Service avec microsoft Semantic Kernel or Foundry Agent Service (Spring Boot)

Ce tutoriel montre comment ajouter une fonctionnalité agentique à une application CRUD Spring Boot WebFlux basée sur les données existante. Il effectue cette opération à l’aide du service Microsoft Semantic Kernel and Foundry Agent.

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 relativement simple d’ajouter des fonctionnalités d’agent à votre application web en encapsulant ces fonctionnalités dans un plug-in (pour LangGraph) ou en tant que point de terminaison OpenAPI (pour le service De l’agent Foundry). 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 dans une application App Service.

Semantic Kernel
Service de l’agent Foundry

Capture d’écran d’une session de complétion de discussion avec un agent du noyau sémantique.

Les services Semantic Kernel et Foundry Agent vous permettent de créer des applications web intelligentes avec des fonctionnalités pilotées par l'IA. Le tableau suivant présente certaines considérations et compromis :

Considération	Noyau sémantique	Service d’agent de la fonderie
Performance	Rapide (s’exécute localement)	Plus lent (service géré, distant)
Développement	Code complet, contrôle maximal	Faible code, intégration rapide
Essai	Tests manuels/unitaires dans le code	Terrain de jeu intégré pour les tests rapides
Extensibilité	Managé par l’application	Managé par Azure, mise à l’échelle automatique
Garde-fous de sécurité	Implémentation personnalisée requise	Sécurité et modération du contenu intégrées
Identité	Implémentation personnalisée requise	ID de l'agent et authentification intégrés
Entreprise	Intégration personnalisée requise	Déploiement intégré de Microsoft 365/Teams et appels d’outils intégrés à Microsoft 365.

Dans ce tutoriel, vous allez apprendre à :

Convertissez les fonctionnalités d’application existantes en plug-in pour le noyau sémantique.
Ajoutez le plug-in à un agent de noyau sémantique et utilisez-le dans une application web.
Convertir les fonctionnalités de l'application existante en un point de terminaison OpenAPI pour le Service de l’Agent Foundry.
Appelez un agent Foundry dans une application web.
Attribuez les autorisations requises pour la connectivité d’identité managée.

Prerequisites

Un compte Azure avec un abonnement actif : créez un compte gratuitement.
Compte GitHub pour utiliser GitHub Codespaces - En savoir plus sur GitHub Codespaces.

Ouvrir l’exemple avec Codespaces

Le moyen le plus simple de commencer consiste à utiliser GitHub Codespaces, qui fournit un environnement de développement complet avec tous les outils requis préinstallés.

Accédez au dépôt GitHub à l’adresse https://github.com/Azure-Samples/app-service-agentic-semantic-kernel-java.
Sélectionnez le bouton Code , sélectionnez l’onglet Espaces de code, puis sélectionnez Créer un espace de code dans l’espace de code principal.
Attendez quelques instants pour que votre espace de code s’initialise. Une fois prêt, vous verrez un environnement de développement entièrement configuré dans votre navigateur.
Exécutez l’application localement :
```
mvn spring-boot:run
```
Lorsque vous voyez que votre application s’exécute sur le port 8080 est disponible, sélectionnez Ouvrir dans le navigateur et ajoutez quelques tâches.

L’agent de noyau sémantique est initialisé dans src/main/java/com/example/crudtaskswithagent/controller/AgentController.java, lorsque l’utilisateur entre la première invite dans une nouvelle session de navigateur.

Vous trouverez le code d’initialisation dans le SemanticKernelAgentService constructeur (dans src/main/java/com/example/crudtaskswithagent/service/SemanticKernelAgentService.java). Le code d’initialisation effectue les opérations suivantes :

Crée un noyau avec la saisie semi-automatique de conversation.
Ajoute un plug-in de noyau qui encapsule les fonctionnalités de l’application CRUD (dans src/main/java/com/example/crudtaskswithagent/plugin/TaskCrudPlugin.java). Les parties intéressantes du plug-in sont les annotations sur les DefineKernelFunction déclarations de méthode et les descriptionreturnType paramètres qui aident le noyau à appeler le plug-in intelligemment.
Crée un agent d’achèvement de conversation et le configure pour permettre au modèle IA d’appeler automatiquement des fonctions (FunctionChoiceBehavior.auto(true)).
Crée un thread d’agent qui gère automatiquement l’historique des conversations.

        // Create OpenAI client
        OpenAIAsyncClient openAIClient = new OpenAIClientBuilder()
                .endpoint(endpoint)
                .credential(new DefaultAzureCredentialBuilder().build())
                .buildAsyncClient();
        
        // Create chat completion service
        OpenAIChatCompletion chatCompletion = OpenAIChatCompletion.builder()
                .withOpenAIAsyncClient(openAIClient)
                .withModelId(deployment)
                .build();
        
        // Create kernel plugin from the task plugin
        KernelPlugin kernelPlugin = KernelPluginFactory.createFromObject(taskCrudPlugin, "TaskPlugin");
        
        // Create kernel with TaskCrudPlugin and chat completion service
        Kernel kernel = Kernel.builder()
                .withAIService(OpenAIChatCompletion.class, chatCompletion)
                .withPlugin(kernelPlugin)
                .build();
        
        // Use automatic function calling
        InvocationContext invocationContext = InvocationContext.builder()
            .withFunctionChoiceBehavior(FunctionChoiceBehavior.auto(true))
            .build();

        // Create ChatCompletionAgent
        configuredAgent = ChatCompletionAgent.builder()
                .withKernel(kernel)
                .withName("TaskAgent")
                .withInvocationContext(invocationContext)
                .withInstructions(
                    "You are an agent that manages tasks using CRUD operations. " +
                    "Use the TaskCrudPlugin functions to create, read, update, and delete tasks. " +
                    "Always call the appropriate plugin function for any task management request. " +
                    "Don't try to handle any requests that are not related to task management."
                )
                .build();
        
    } catch (Exception e) {
        logger.error("Error initializing SemanticKernelAgentService: {}", e.getMessage(), e);
    }
}

this.agent = configuredAgent;

// Initialize thread for this instance
this.thread = ChatHistoryAgentThread.builder().build();

Chaque fois que l’invite est reçue, le code du serveur utilise ChatCompletionAgent.invokeAsync() pour appeler l’agent avec l’invite utilisateur et le thread de l’agent. Le thread de l’agent effectue le suivi de l’historique des conversations.

// Use the agent to process the message with automatic function calling
return agent.invokeAsync(userMessageContent, thread)
        .<String>map(responses -> {
            
            if (responses != null && !responses.isEmpty()) {
                // Process all responses and concatenate them
                StringBuilder combinedResult = new StringBuilder();
                
                for (int i = 0; i < responses.size(); i++) {
                    var response = responses.get(i);
                    
                    // Update thread with the last response thread (as per Microsoft docs)
                    if (i == responses.size() - 1) {
                        var responseThread = response.getThread();
                        if (responseThread instanceof ChatHistoryAgentThread) {
                            this.thread = (ChatHistoryAgentThread) responseThread;
                        }
                    }
                    
                    // Get response content
                    ChatMessageContent<?> content = response.getMessage();
                    String responseContent = content != null ? content.getContent() : "";
                    
                    if (!responseContent.isEmpty()) {
                        if (combinedResult.length() > 0) {
                            combinedResult.append("\n\n"); // Separate multiple responses
                        }
                        combinedResult.append(responseContent);
                    }
                }
                
                String result = combinedResult.toString();
                if (result.isEmpty()) {
                    result = "No content returned from agent.";
                }
                return result;
            } else {
                return "I'm sorry, I couldn't process your request. Please try again.";
            }
        })
        .onErrorResume(throwable -> {
            logger.error("Error in processMessage: {}", throwable.getMessage(), throwable);
            return Mono.just("Error processing message: " + throwable.getMessage());
        });

L’agent Foundry est initialisé dans src/main/java/com/example/crudtaskswithagent/controller/AgentController.java, lorsque l’utilisateur entre la première invite dans une nouvelle session de navigateur.

Vous trouverez le code d’initialisation dans le FoundryAgentService constructeur (dans src/main/java/com/example/crudtaskswithagent/service/FoundryAgentService.java). Le code d’initialisation effectue les opérations suivantes :

Crée un AgentsClientBuilder avec un point de terminaison et des informations d’identification.
Crée des clients asynchrones spécialisés : ConversationsAsyncClient et ResponsesAsyncClient.
Fait référence à l’agent par nom (configuré dans le portail Foundry).
Crée une conversation pour la session.

// Configure Foundry client with endpoint and credentials
AgentsClientBuilder builder = new AgentsClientBuilder()
        .endpoint(endpoint)
        .serviceVersion(AgentsServiceVersion.V2025_11_15_PREVIEW)
        .credential(new DefaultAzureCredentialBuilder().build());

// Build specialized async clients for conversations and responses
this.conversationsClient = builder.buildConversationsAsyncClient();
this.responsesClient = builder.buildResponsesAsyncClient();

// Reference the agent by name (configured in Foundry portal)
this.agentReference = new AgentReference(agentName);

// Create a conversation for this session
this.conversationId = conversationsClient.getConversationServiceAsync()
        .create()
        .get() // Blocking call - must be on boundedElastic thread
        .id();

Note

Le constructeur effectue des opérations bloquantes (acquisition des informations d’identification et création de la conversation). Le contrôleur (dans src/main/java/com/example/crudtaskswithagent/controller/AgentController.java) crée donc le service sur un thread boundedElastic à l’aide de .subscribeOn(Schedulers.boundedElastic()).

Ce code d’initialisation ne définit aucune fonctionnalité pour l’agent, car vous générez généralement l’agent dans le portail Foundry. Dans le cadre de l’exemple de scénario, il suit également le modèle OpenAPI présenté dans Ajouter une application App Service en tant qu’outil dans Foundry Agent Service (Spring Boot) et rend ses fonctionnalités CRUD disponibles en tant que point de terminaison OpenAPI. Cela vous permet de l’ajouter à l’agent ultérieurement en tant qu’outil que vous pouvez appeler.

Les annotations OpenAPI sont définies dans la TaskController classe. Par exemple, la route "GET /api/tasks" définit operationId à l’aide de l’annotation @Operation, comme l’exige l’outil de spécification OpenAPI dans Microsoft Foundry, et summary et description aident l’agent à déterminer comment appeler l’API :

@GetMapping
@Operation(
    summary = "Get all tasks",
    description = "Retrieves all tasks from the database",
    operationId = "getAllTasks"
)
@ApiResponse(responseCode = "200", description = "List of tasks")
public Flux<TaskItem> getAllTasks() {
    return taskRepository.findAllOrderById();
}

Chaque fois que l’invite est reçue, le code du serveur utilise responsesClient.createWithAgentConversation() pour envoyer le message à l’agent Foundry et récupérer la réponse. L’ID de conversation effectue le suivi de l’historique des conversations.

// Send message to agent and get response
return responsesClient
    .createWithAgentConversation(agentReference, conversationId, paramsBuilder)
    .map(response -> {
        // Extract text from response - find the message item in output array
        return response.output().stream()
            .filter(item -> item.message().isPresent())
            .findFirst()
            .flatMap(item -> item.message())
            .map(msg -> !msg.content().isEmpty() && msg.content().get(0).isOutputText()
                ? msg.content().get(0).asOutputText().text()
                : "I received your message but couldn't generate a response.")
            .orElse("I received your message but couldn't generate a response.");
    })
    .timeout(Duration.ofSeconds(60))
    .onErrorResume(throwable -> {
        logger.error("Error processing message: {}", throwable.getMessage(), throwable);
        return Mono.just("Sorry, I encountered an error processing your request: " + throwable.getMessage());
    });

Déployer l’exemple d’application

L’exemple de référentiel contient un modèle Azure Developer CLI (AZD), qui crée une application App Service avec une identité managée et déploie votre exemple d’application.

Dans le terminal, connectez-vous à Azure à l’aide d’Azure Developer CLI :
```
azd auth login
```
Suivez les instructions pour terminer le processus d’authentification.
Déployez l’application Azure App Service avec le modèle AZD :
```
azd up
```

Lorsque vous y êtes invité, fournissez les réponses suivantes :

Question	Answer
Entrez un nouveau nom d’environnement :	Tapez un nom unique.
Sélectionnez un abonnement Azure à utiliser :	Sélectionnez l’abonnement.
Choisissez un groupe de ressources à utiliser :	Sélectionnez Créer un groupe de ressources.
Sélectionnez un emplacement dans lequel créer le groupe de ressources :	Sélectionnez Suède Centre.
Entrez un nom pour le nouveau groupe de ressources :	Tapez Entrée.

Dans la sortie AZD, retrouvez l’URL de votre application et accédez-y dans le navigateur. L’URL ressemble à ceci dans la sortie AZD :
```
 Deploying services (azd deploy)

   (✓) Done: Deploying service web
   - Endpoint: <URL>
 
```
Ouvrez le schéma OpenAPI généré automatiquement au niveau du chemin d’accès https://....azurewebsites.net/api/schema . Vous avez besoin de ce schéma ultérieurement.

Vous disposez maintenant d’une application App Service avec une identité managée affectée par le système.

Créer et configurer la ressource Microsoft Foundry

Semantic Kernel
Service de l’agent Foundry

Dans le portail Foundry, vérifiez que le bouton radio New Foundry supérieur est activé, et créez un projet.
Déployez un modèle de votre choix (consultez Démarrage rapide Microsoft Foundry : Créer des ressources).
Depuis le haut du model playground, copiez le nom du modèle.
Le moyen le plus simple d’obtenir le point de terminaison Azure OpenAI est toujours à partir du portail Classic. Sélectionnez le bouton radio New Foundry, puis Azure OpenAI, et copiez l’URL dans le point d'accès Azure OpenAI pour plus tard.

Dans le portail Foundry, vérifiez que le bouton radio "New Foundry" en haut est activé et créez un projet.
Dans la page d’accueil, copiez le point de terminaison Project pour plus tard.
Sélectionnez Démarrer la création>Créer un agent et suivez l’invite.
Dans le nouvel espace de l'agent, créez un outil OpenAPI pour appeler votre application web en sélectionnant Outils>Ajouter>Personnalisé>Outil OpenAPI>Créer. Dans le volet Installation , ajoutez une action avec l’outil de spécification OpenAPI. Utilisez le schéma OpenAPI que vous obtenez à partir de l’application web déployée et de l’authentification anonyme . Pour obtenir des instructions détaillées, consultez Comment utiliser l’outil de spécification OpenAPI.

Votre code d’application est déjà configuré pour inclure le url et le operationId du serveur, ce qui est nécessaire pour l’agent. Pour plus d’informations, voir Se connecter à la spécification OpenAPI.
Veillez à sélectionner Enregistrer.
Sélectionnez Essayer dans le terrain de jeu et tester votre agent Foundry avec des invites telles que « Afficher toutes les tâches » et « Veuillez ajouter une tâche ».

Si vous obtenez une réponse valide, l’agent effectue des appels d’outil au point de terminaison OpenAPI sur votre application web déployée.

Attribuer des autorisations requises

Semantic Kernel
Service de l’agent Foundry

Dans le menu supérieur du nouveau portail Foundry, sélectionnez Utiliser, puis sélectionnez Administrateur. Dans la ligne de votre projet Foundry, vous devez voir deux liens. La colonne Name est la ressource de projet Foundry, et celle de la colonne de ressource Parent est la ressource Foundry.
Sélectionnez la ressource Foundry dans la ressource parente , puis sélectionnez Gérer cette ressource dans le portail Azure. À partir du portail Azure, vous pouvez attribuer un accès en fonction du rôle pour la ressource à l’application web déployée.
Ajoutez le rôle suivant pour l’identité managée de l’application App Service :

Ressource cible Rôle requis Nécessaire pour

Fonderie Utilisateur OpenAI de Cognitive Services Service d’achèvement de conversation dans Microsoft Agent Framework.

Pour obtenir des instructions, consultez Attribuer des rôles Azure à l’aide du portail Azure.

Ressource cible	Rôle requis	Nécessaire pour
Fonderie	Utilisateur OpenAI de Cognitive Services	Service d’achèvement de conversation dans Microsoft Agent Framework.

Dans le menu supérieur du nouveau portail Foundry, sélectionnez Utiliser, puis sélectionnez Administrateur. Dans la ligne de votre projet Foundry, vous devez voir deux liens. La colonne Name est la ressource de projet Foundry, et celle de la colonne de ressource Parent est la ressource Foundry.
Sélectionnez la ressource de projet Foundry dans la colonne Nom , puis sélectionnez Gérer cette ressource dans le portail Azure. À partir du portail Azure, vous pouvez attribuer un accès en fonction du rôle pour la ressource à l’application web déployée.
Ajoutez le rôle suivant pour l’identité managée de l’application App Service :

Ressource cible Rôle requis Nécessaire pour

Projet de fonderie Utilisateur Azure AI Lecture et appel de l’agent Foundry.

Pour obtenir des instructions, consultez Attribuer des rôles Azure à l’aide du portail Azure.

Ressource cible	Rôle requis	Nécessaire pour
Projet de fonderie	Utilisateur Azure AI	Lecture et appel de l’agent Foundry.

Configurer des variables de connexion dans votre exemple d’application

Ouvrez src/main/resources/application.properties. À l’aide des valeurs que vous avez copiées précédemment à partir du portail Foundry, configurez les variables suivantes :

Semantic Kernel
Service de l’agent Foundry

Variable	Description
`azure.openai.endpoint`	Point de terminaison Azure OpenAI (copié à partir du portail Foundry classique).
`azure.openai.deployment`	Nom du modèle dans le déploiement (copié depuis le model playground dans le nouveau portail Foundry).

Note

Pour simplifier le didacticiel, vous allez utiliser ces variables dans .env au lieu de les remplacer par les paramètres d’application dans App Service.

Variable	Description
`azure.foundry.endpoint`	Point de terminaison du projet Microsoft Foundry à partir du nouveau portail Foundry.
`azure.foundry.agent.name`	Nom de l’agent (depuis l’agent playground dans le portail Foundry).

Note

Pour simplifier le didacticiel, vous allez utiliser ces variables dans src/main/resources/application.properties au lieu de les remplacer par des paramètres d’application dans App Service.

Connectez-vous à Azure avec Azure CLI :
```
az login
```
Cela permet à la bibliothèque cliente Azure Identity dans l’exemple de code de recevoir un jeton d’authentification pour l’utilisateur connecté. N’oubliez pas que vous avez ajouté le rôle requis pour cet utilisateur précédemment.
Exécutez l’application localement :
```
mvn spring-boot:run
```
Lorsque vous voyez Votre application s’exécuter sur le port 8080 est disponible, sélectionnez Ouvrir dans le navigateur.
Essayez l’interface de conversation. Si vous obtenez une réponse, votre application se connecte correctement à la ressource Microsoft Foundry.
De retour dans l’espace de code GitHub, déployez les modifications apportées à votre application.
```
azd up
```
Accédez à nouveau à l’application déployée et testez les agents de conversation.
- Semantic Kernel
- Service de l’agent Foundry

Nettoyer les ressources

Lorsque vous avez terminé avec l’application, vous pouvez supprimer les ressources App Service pour éviter d’entraîner d’autres coûts :

azd down --purge

Étant donné que le modèle AZD n’inclut pas les ressources Microsoft Foundry, vous devez les supprimer manuellement si vous le souhaitez.

Plus de ressources

Commentaires

Cette page a-t-elle été utile ?

Last updated on 2025-12-16

Partager via

Tutoriel : Créer une application web agentique dans Azure App Service avec microsoft Semantic Kernel or Foundry Agent Service (Spring Boot)

Prerequisites

Ouvrir l’exemple avec Codespaces

Passer en revue le code de l’agent

Déployer l’exemple d’application

Créer et configurer la ressource Microsoft Foundry

Attribuer des autorisations requises

Configurer des variables de connexion dans votre exemple d’application

Nettoyer les ressources

Plus de ressources

Commentaires

Ressources supplémentaires