Esercizio - Creare funzioni native

10 minuti

In questo esercizio si crea una funzione nativa che aggiunge un brano all'elenco "Recentemente riprodotto" di un utente. Successivamente, si può usare l'elenco delle canzoni riprodotte di recente per fornire consigli personalizzati. È ora di iniziare.

Preparare l'ambiente di sviluppo

Per questi esercizi è disponibile un progetto iniziale da usare. Per configurare il progetto iniziale, seguire questa procedura:

Importante

Per completare questi passaggi, è necessario che sia installato Visual Studio Code e .NET Framework 8.0. Potrebbe anche essere necessario installare l'estensione Visual Studio Code C# Dev Kit.

Aprire Visual Studio Code.
Nella sezione Avvia di Visual Studio Code selezionare Clona repository Git.
Nella barra dell'URL immettere https://github.com/MicrosoftLearning/MSLearn-Develop-AI-Agents-with-Azure-OpenAI-and-Semantic-Kernel-SDK.git
In Esplora file creare una nuova cartella in un percorso facile da trovare e ricordare, ad esempio una cartella sul desktop.
Fare clic sul pulsante Seleziona come destinazione repository.

È necessario accedere a GitHub per clonare correttamente il progetto.
Aprire il progetto in Visual Studio Code.
In Esplora risorse fare clic con il pulsante destro del mouse sulla cartella M03-give-your-ai-agent-skills/M03-Project e scegliere Apri nel terminale integrato.
Espandere la cartella M03-give-your-ai-agent-skills/M03-Project.

Verrà visualizzato un file "Program.cs".
Aprire il file Program.cs e aggiornare le variabili seguenti con il nome della distribuzione dei Servizi OpenAI di Azure, la chiave API e l'endpoint.
```
string yourDeploymentName = "";
string yourEndpoint = "";
string yourKey = "";
```

A questo punto si è pronti per iniziare l'esercizio. Buona fortuna!

Creare un plug-in della libreria musicale

Creare una nuova cartella nella directory 'Project' e denominarla 'Plugins'.
Nella cartella 'Plugins' creare un nuovo file 'MusicLibrary.cs'
Immetti il codice seguente:
```
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;
    }
}
```
In questo codice si usa l'elemento Decorator KernelFunction per dichiarare la funzione nativa. Si usa l'elemento Decorator Description anche per aggiungere una descrizione delle operazioni eseguite dalla funzione. Per il momento è possibile presupporre che l'elenco di riproduzioni recenti dell'utente sia archiviato in un file di testo denominato "recentlyplayed.txt". In seguito è possibile aggiungere codice per aggiungere un brano all'elenco.

Aggiungere il codice seguente alla 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";
}

In questo codice si crea una funzione che accetta l'artista, la canzone e il genere come stringhe. Oltre a Description della funzione, è anche possibile aggiungere descrizioni delle variabili di input. Questo codice legge il contenuto esistente dal file, lo analizza e aggiunge il nuovo brano all'elenco. L'elenco aggiornato viene quindi riscritto nel file. Si creerà a questo punto il file "recentlyplayed.txt" con alcuni dati di esempio.

Creare una nuova cartella “data” nella cartella “M03-Project”.

Creare un nuovo file "recentlyplayed.txt" nella cartella "data", quindi incollare il contenuto seguente:

[
    {
        "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"
    }
]

Successivamente, modificare l'elenco importando e richiamando il nuovo plug-in.

Aggiornare il file 'Program.cs' con il codice seguente:

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

In questo codice si importa MusicLibraryPlugin nel kernel usando ImportPluginFromType. Quindi si chiama InvokeAsync con il nome del plug-in che ai vuole usare e la funzione che si vuole chiamare. Si passano anche l'artista, la canzone e il genere come argomenti.

Eseguire il codice immettendo dotnet run nel terminale.

Verrà visualizzato l'output seguente:
```
Added 'Danse' to recently played
```
Si apre 'recentlyplayed.txt' e si dovrebbe vedere la nuova canzone aggiunta all'elenco. Ottimo lavoro!

Esercizio - Creare funzioni native

Preparare l'ambiente di sviluppo

Creare un plug-in della libreria musicale

Commenti e suggerimenti