Exercício: Criar funções nativas

10 minutos

Neste exercício, você vai criar uma função nativa que adiciona uma música à lista "Tocadas Recentemente" de um usuário. Posteriormente, você poderá usar a lista de músicas reproduzidas recentemente para fornecer recomendações personalizadas. Vamos começar!

Preparar seu ambiente de desenvolvimento

No caso desses exercícios, um projeto inicial está disponível para você usar. Use as seguintes etapas para configurar o projeto inicial:

Importante

Você deverá ter o Visual Studio Code e o .NET Framework 8.0 instalados para concluir essas etapas. É possível que você também precise instalar a extensão do Kit de Desenvolvimento do C# do Visual Studio Code.

Abra o Visual Studio Code.
Na seção Iniciar do Visual Studio Code, selecione Clonar repositório do Git.
Na barra de URL, insira https://github.com/MicrosoftLearning/MSLearn-Develop-AI-Agents-with-Azure-OpenAI-and-Semantic-Kernel-SDK.git
No Explorador de Arquivos, crie uma nova pasta em um local fácil de localizar e lembrar, como uma pasta em sua Área de Trabalho.
Clique no botão Selecionar como destino do repositório.

Você precisa estar conectado ao GitHub para clonar o projeto com êxito.
Abra o projeto no Visual Studio Code.
No Explorer, clique com o botão direito do mouse na pasta M03-give-your-ai-agent-skills/M03-Project e clique em Abrir no Terminal Integrado.
Expanda a pasta M03-give-your-ai-agent-skills/M03-Project.

Você deve ver um arquivo "Program.cs".
Abra o arquivo Program.cs e atualize as seguintes variáveis com o nome de implantação dos Serviços OpenAI do Azure, a chave de API e o ponto de extremidade.
```
string yourDeploymentName = "";
string yourEndpoint = "";
string yourKey = "";
```

Agora você está pronto para começar o exercício. Boa sorte!

Crie um plugin de biblioteca de músicas

Crie uma nova pasta no diretório "Projeto" com o nome "Plugins".
Na pasta "Plugins", crie um novo arquivo "MusicLibrary.cs"
Insira o seguinte código:
```
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;
    }
}
```
Nesse código, você vai usar o decorador KernelFunction para declarar sua função nativa. Você também vai usar o decorador Description para adicionar uma descrição do que a função faz. Para o momento, você pode pressupor que a lista de músicas tocadas recentemente pelo usuário é armazenada em um arquivo de texto chamado "tocadasrecentemente.txt". Em seguida, você pode adicionar código para adicionar uma música à lista.

Adicione o seguinte código à 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";
}

Nesse código, você vai criar uma função que aceita o artista, a música e o gênero como cadeias de caracteres. Além da Description da função, você também vai adicionar descrições das variáveis de entrada de dados. Esse código lê o conteúdo existente no arquivo, o analisa e adiciona a nova música à lista. Depois disso, a lista atualizada é gravada novamente no arquivo. Em seguida, você vai criar o arquivo "tocadasrecentemente.txt" com algumas amostras de dados.

Crie uma nova pasta "dados" na pasta "M03-Project".

Crie um novo arquivo "tocadasrecentemente.txt" na pasta "dados" e cole o seguinte conteúdo:

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

Em seguida, vamos modificar a lista importando e invocando seu novo plug-in.

Atualize seu arquivo "Program.cs" com o seguinte código:

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

Nesse código, você vai importar o MusicLibraryPlugin para o kernel usando ImportPluginFromType. Em seguida, você chama InvokeAsync com o nome do plug-in que deseja usar e a função que deseja chamar. Você também vai repassar o artista, a música e o gênero como argumentos.

Execute o código inserindo dotnet run no terminal.

Você deve ver o seguinte resultado:
```
Added 'Danse' to recently played
```
Abra "tocadasrecentemente.txt" e você deverá visualizar a nova música adicionada à lista. Ótimo trabalho!

Exercício: Criar funções nativas

Preparar seu ambiente de desenvolvimento

Crie um plugin de biblioteca de músicas

Comentários