Exercice – Créer des fonctions natives

10 minutes

Dans cet exercice, vous créez une fonction native qui ajoute une chanson à la liste « Récemment écouté » d’un utilisateur. Plus tard, vous pouvez utiliser la liste des chansons récemment écoutées pour fournir des suggestions personnalisées. C’est parti !

Préparer votre environnement de développement

Pour ces exercices, un projet de démarrage est mis à votre disposition. Effectuez les étapes suivantes pour configurer le projet de démarrage :

Important

Vous devez avoir installé Visual Studio Code et le .NET Framework 8.0 pour effectuer ces étapes. Vous devrez peut-être également installer l’extension du Kit de développement C# de Visual Studio Code.

Ouvrez Visual Studio Code.
Sous la section Démarrer de Visual Studio Code , sélectionnez le référentiel git clone.
Dans la barre d’URL, entrez https://github.com/MicrosoftLearning/MSLearn-Develop-AI-Agents-with-Azure-OpenAI-and-Semantic-Kernel-SDK.git
Dans l’Explorateur de fichiers, créez un dossier dans un emplacement facile à trouver et à mémoriser, tel qu’un dossier dans votre Bureau.
Cliquez sur le bouton Sélectionner en tant que destination du référentiel.

Vous devez être connecté à GitHub pour cloner correctement le projet.
Ouvrez le projet dans Visual Studio Code.
Dans l’Explorateur, cliquez avec le bouton droit sur le dossier M03-give-your-ai-agent-skills/M03-Project, puis cliquez sur Ouvrir dans le terminal intégré.
Développez le dossier M03-give-your-ai-agent-skills/M03-Project.

Vous devez voir un fichier « Program.cs ».
Ouvrez le fichier Program.cs, puis mettez à jour les variables suivantes avec votre point de terminaison, clé API et nom de déploiement Azure OpenAI Services.
```
string yourDeploymentName = "";
string yourEndpoint = "";
string yourKey = "";
```

Vous êtes maintenant prêt à commencer l’exercice. Bonne chance !

Créer un plug-in de bibliothèque musicale

Créez un dossier dans le répertoire « Project » et nommez-le « Plugins ».
Dans le dossier « Plugins », créez un fichier « MusicLibrary.cs »
Entrez le code suivant :
```
using System.ComponentModel;
using System.Text.Json;
using System.Text.Json.Nodes;
using Microsoft.SemanticKernel;

public class MusicLibraryPlugin
{
    [KernelFunction, 
    Description("Get a list of music recently played by the user")]
    public static string GetRecentPlays()
    {
        string dir = Directory.GetCurrentDirectory();
        string content = File.ReadAllText($"{dir}/data/recentlyplayed.txt");
        return content;
    }
}
```
Dans ce code, vous utilisez le décorateur KernelFunction pour déclarer votre fonction native. Vous utilisez également le décorateur Description pour ajouter une description de ce que fait la fonction. Pour l’instant, vous pouvez supposer que la liste des écoutes récentes de l’utilisateur est stockée dans un fichier texte appelé « recentlyplayed.txt ». Ensuite, vous pouvez ajouter du code pour ajouter une chanson à la liste.

Ajoutez le code suivant à la classe MusicLibraryPlugin :

[KernelFunction, Description("Add a song to the recently played list")]
public static string AddToRecentlyPlayed(
    [Description("The name of the artist")] string artist, 
    [Description("The title of the song")] string song, 
    [Description("The song genre")] string genre)
{
    // Read the existing content from the file
    string filePath = "data/recentlyplayed.txt";
    string jsonContent = File.ReadAllText(filePath);
    var recentlyPlayed = (JsonArray) JsonNode.Parse(jsonContent);

    var newSong = new JsonObject
    {
        ["title"] = song,
        ["artist"] = artist,
        ["genre"] = genre
    };

    recentlyPlayed.Insert(0, newSong);
    File.WriteAllText(filePath, JsonSerializer.Serialize(recentlyPlayed,
        new JsonSerializerOptions { WriteIndented = true }));

    return $"Added '{song}' to recently played";
}

Dans ce code, vous créez une fonction qui accepte l’artiste, la chanson et le genre sous forme de chaînes. En plus de la fonction Description, vous ajoutez également des descriptions des variables d’entrée. Ce code lit le contenu existant du fichier, l’analyse et ajoute la nouvelle chanson à la liste. Ensuite, la liste mise à jour est réécrite dans le fichier. Ensuite, vous allez créer le fichier « recentlyplayed.txt » avec quelques exemples de données.

Créez un dossier « data » dans le dossier « M03-Project ».

Créez un fichier « recentlyplayed.txt » dans le dossier « data », puis collez-y le contenu suivant :

[
    {
        "title": "Loanh Quanh",
        "artist": "Ly Hoa",
        "genre": "indie, folk"
    },
    {
        "title": "Kalam Eineh",
        "artist": "Yasemin",
        "genre": "pop, Egyptian pop"
    },
    {
        "title": "I Miss You",
        "artist": "Chishin",
        "genre": "hiphop, rap"
    },
    {
        "title": "4EVER",
        "artist": "Gaby",
        "genre": "alternative, indie"
    }
]

Ensuite, modifions la liste en important et en appelant votre nouveau plug-in.

Mettez à jour votre fichier « Program.cs » avec le code suivant :
```
var kernel = builder.Build();
kernel.ImportPluginFromType<MusicLibraryPlugin>();

var result = await kernel.InvokeAsync(
    "MusicLibraryPlugin", 
    "AddToRecentlyPlayed", 
    new() {
        ["artist"] = "Tiara", 
        ["song"] = "Danse", 
        ["genre"] = "French pop, electropop, pop"
    }
);

Console.WriteLine(result);
```
Dans ce code, vous importez le MusicLibraryPlugin dans le noyau en utilisant ImportPluginFromType. Appelez ensuite InvokeAsync avec le nom du plug-in que vous souhaitez utiliser et la fonction que vous souhaitez appeler. Vous passez également l’artiste, la chanson et le genre comme arguments.
Exécutez le code en entrant dotnet run dans le terminal.

Vous devez normalement voir la sortie suivante :
```
Added 'Danse' to recently played
```
Ouvrez « recentlyplayed.txt », puis vous devriez voir la nouvelle chanson ajoutée à la liste. Beau travail !

Exercice – Créer des fonctions natives

Préparer votre environnement de développement

Créer un plug-in de bibliothèque musicale

Commentaires