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

Ce tutoriel montre comment ajouter une fonctionnalité agentique à une application CRUD principale basée sur les données existante ASP.NET. Cela utilise deux approches différentes : Microsoft Semantic Kernel and Foundry Agent Service.

Si votre application web dispose déjà de fonctionnalités utiles, telles que l’achat, 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 le noyau sémantique) 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.

Noyau sémantique

Service de l’agent Foundry

Capture d’écran d’une session de conversation achevée avec un agent Microsoft Foundry.

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 :

Consideration	Noyau sémantique	Service d’agent de la fonderie
Performance	Rapide (s’exécute localement)	Plus lent (service géré, distant)
Development	Code complet, contrôle maximal	Faible code, intégration rapide
Testing	Tests manuels/unitaires dans le code	Terrain de jeu intégré pour les tests rapides
Scalability	Géré par l’application	Géré par Azure, mise à l’échelle automatique

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 la fonctionnalité existante de l'application en un point de terminaison OpenAPI pour le service Agent Foundry.
• Appelez un agent Microsoft 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.

1. Accédez au dépôt GitHub à l’adresse https://github.com/Azure-Samples/app-service-agentic-semantic-kernel-ai-foundry-agent.

2. 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.

3. 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.

4. Exécutez l’application localement :

   dotnet run
   

5. Lorsque vous voyez Votre application, qui s’exécute sur le port 5280, est disponible, sélectionnez Ouvrir dans le navigateur et ajoutez quelques tâches.

Passer en revue le code de l’agent

Les deux approches utilisent le même modèle d’implémentation, où l’agent est initialisé en tant que service (dans Program.cs) dans un fournisseur et injecté dans le composant Blazor respectif.

Noyau sémantique

L’élément SemanticKernelAgentProvider est initialisé dans Services/SemanticKernelAgentProvider.cs. 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 Plugins/TaskCrudPlugin.cs). Les seules parties intéressantes du plug-in sont les attributs KernelFunction sur les définitions de méthode et les attributs Description qui aident le noyau à appeler intelligemment le plug-in.
• Crée un agent d’achèvement de conversation et le configure pour permettre au modèle IA d’appeler automatiquement des fonctions (FunctionChoiceBehavior = FunctionChoiceBehavior.Auto()).

public class SemanticKernelAgentProvider : ISemanticKernelAgentProvider
{
    public bool IsConfigured { get; }
    public ChatCompletionAgent? Agent { get; }

    public SemanticKernelAgentProvider(IConfiguration config, IServiceProvider sp)
    {
        IsConfigured = false;
        Agent = null;

        // Initialize a semantic kernel
        var deployment = config["ModelDeployment"];
        var endpoint = config["AzureOpenAIEndpoint"];
        if (string.IsNullOrWhiteSpace(deployment) || string.IsNullOrWhiteSpace(endpoint))
        {
            return;
        }
        var kernel = Kernel.CreateBuilder()
            .AddAzureOpenAIChatCompletion(
                deploymentName: deployment,
                endpoint: endpoint,
                new DefaultAzureCredential()
            ).Build();
        // Add the tasks CRUD plugin
        kernel.Plugins.AddFromType<TaskCrudPlugin>(serviceProvider: sp);

        // Create a chat completion agent
        Agent = new ChatCompletionAgent
        {
            Name = "TaskManagerAgent",
            Instructions =
                @"""
                Your 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.
                When handling requests, if you're missing any information, don't make it up but prompt the user for it instead.
                """,
            Kernel = kernel,
            Arguments = new KernelArguments(new AzureOpenAIPromptExecutionSettings()
            {
                FunctionChoiceBehavior = FunctionChoiceBehavior.Auto()
            })
        };

        IsConfigured = true;
    }
}

Service de l’agent Foundry

Le FoundryAgentProvider fournisseur est initialisé dans Services/FoundryAgentProvider.cs. Le code d’initialisation effectue les opérations suivantes :

• Crée un nouveau client d’agents.
• Permet de créer une conversation.
• Obtient l’agent nommé, spécifié par l’ID de l’agent.

public class FoundryAgentProvider : IFoundryAgentProvider
{
    public bool IsConfigured { get; }
    public PersistentAgentsClient? Client { get; }
    public string? ThreadId { get; }
    public PersistentAgent? Agent { get; }

    public FoundryAgentProvider(IConfiguration config)
    {
        IsConfigured = false;

        // Create a new client instance
        var endpoint = config["AzureAIFoundryProjectEndpoint"];
        if (string.IsNullOrWhiteSpace(endpoint))
        {
            return; // Fail gracefully
        }
        Client = new PersistentAgentsClient(endpoint, new Azure.Identity.DefaultAzureCredential());

        // Create a new thread. 
        PersistentAgentThread agentThread = Client.Threads.CreateThread();
        ThreadId = agentThread.Id;

        // Create a new angent instance
        var agentId = config["AzureAIFoundryAgentId"];
        if (string.IsNullOrWhiteSpace(agentId))
        {
            return; // Fail gracefully
        }
        Agent = Client.Administration.GetAgent(agentId);

        IsConfigured = true;
    }
}

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 (.NET) 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.

Le code OpenAPI est défini dans Program.cs. Par exemple, l’API « get tasks » définit l’ID d’opération avec WithName(), comme requis par l’outil de spécification OpenAPI dans Microsoft Foundry, et WithDescription() aide l’agent à déterminer comment appeler l’API :

app.MapGet("/api/tasks", async (TaskService taskService) =>
{
    return Results.Ok(await taskService.GetAllTasksAsync());
})
.WithDescription("Gets all tasks.")
.WithName("GetAllTasks");

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.

1. Dans le terminal, connectez-vous à Azure à l’aide d’Azure Developer CLI :

   azd auth login
   

   Suivez les instructions pour terminer le processus d’authentification.

2. Déployez l’application Azure App Service avec le modèle AZD :

   azd up
   

3. 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 n’importe quelle région. Les ressources seront effectivement créées dans East US 2.
   Entrez un nom pour le nouveau groupe de ressources :	Tapez Entrée.

4. 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>
    

5. Sélectionnez l’élément de schéma OpenAPI pour ouvrir le schéma OpenAPI généré automatiquement au chemin d’accès par défaut /openapi/v1.json . Vous avez besoin de ce schéma ultérieurement.

6. Une fois le déploiement réussi, vous verrez une URL pour votre application déployée.

   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

1. Dans le portail Foundry, déployez un modèle de votre choix (consultez Démarrage rapide : Prise en main de Microsoft Foundry). Un projet et un agent par défaut sont créés pour vous dans le processus.

2. Dans le menu de gauche, sélectionnez Vue d’ensemble.

3. Sélectionnez Microsoft Foundry et copiez l’URL dans le point de terminaison du projet Microsoft Foundry.

4. Sélectionnez Azure OpenAI et copiez l’URL dans le point de terminaison Azure OpenAI pour plus tard.

   

5. Dans le menu de gauche, sélectionnez Agents, puis sélectionnez l’agent par défaut.

6. Dans le volet Installation , copiez l’ID de l’agent, ainsi que le nom du modèle dans Déploiement.

   

7. 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, consultez How to use Foundry Agent Service with OpenAPI Specified Tools : Prerequisites.

8. 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

1. En haut à droite du portail de recherche, sélectionnez le nom de la ressource, puis sélectionnez Groupe de ressources pour l’ouvrir dans le portail Azure.

   

2. Ajoutez un rôle pour chacune des deux ressources de l’identité de gestion de l’application App Service à l’aide du tableau suivant :

   Ressource cible	Rôle requis	Nécessaire pour
   Microsoft Foundry	Utilisateur OpenAI de Cognitive Services	Service d’achèvement de conversation dans le noyau sémantique.
   Projet Microsoft Foundry	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.

Configurer des variables de connexion dans votre exemple d’application

1. Ouvrez appsettings.json. À l’aide des valeurs que vous avez copiées précédemment à partir du portail Foundry, configurez les variables suivantes :

   Variable	Description
   AzureOpenAIEndpoint	Point de terminaison Azure OpenAI (copié à partir de la page Vue d’ensemble). Cela est nécessaire pour l’agent de noyau sémantique.
   ModelDeployment	Nom du modèle de déploiement (copié depuis le volet Configuration des agents). Cela est nécessaire pour l’agent de noyau sémantique.
   AzureAIFoundryProjectEndpoint	Point de terminaison du projet Microsoft Foundry (copié à partir de la page Vue d’ensemble). Ceci est nécessaire pour le Service de l’agent Foundry.
   AzureAIFoundryAgentId	ID de l’agent (copié à partir du volet Configuration des agents). Cela est nécessaire pour appeler un agent Microsoft Foundry existant.

   Note

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

2. 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.

3. Exécutez l’application localement :

   dotnet run
   

4. Lorsque votre application s'exécutant sur le port 5280, est disponible, sélectionnez Ouvrir dans le navigateur.

5. Sélectionnez le lien Agent De Noyau Sémantique et le lien Agent Microsoft Foundry pour essayer l’interface de conversation. Si vous obtenez une réponse, votre application se connecte correctement à la ressource Microsoft Foundry.

6. De retour dans l’espace de code GitHub, déployez les modifications apportées à votre application.

   azd up
   

7. Accédez à nouveau à l’application déployée et testez les agents de conversation.

Noyau sémantique

Service de l’agent Foundry

Capture d’écran d’une session de conversation achevée avec un agent Microsoft 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

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