Exercício - Criar funções nativas

10 minutos

Neste exercício, você cria uma função nativa que adiciona uma música à lista "Recentemente reproduzido" de um usuário. Mais tarde, você pode usar a lista de músicas tocadas recentemente para fornecer recomendações personalizadas. Vamos começar!

Preparar o ambiente de desenvolvimento

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

Importante

Você deve ter o Visual Studio Code e o .NET Framework 8.0 instalado para concluir essas etapas. Também pode ser necessário instalar a extensão Visual Studio Code C# Dev Kit.

Abra o Visual Studio Code.
Na seção Visual Studio Code Start , selecione Clone Git Repository.
Na barra de URL, digite 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 encontrar e lembrar, como uma pasta na á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 .

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

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

Criar um plugin de biblioteca de música

Crie uma nova pasta no diretório 'Projeto' e nomeie-a 'Plugins'.
Na pasta 'Plugins', crie um novo ficheiro 'MusicLibrary.cs'

Introduza 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;
    }
}

Neste código, você usa o decorador KernelFunction para declarar sua função nativa. Você também usa o Description decorador para adicionar uma descrição do que a função faz. Por enquanto, você pode supor que a lista de reproduções recentes do usuário está armazenada em um arquivo de texto chamado 'recentlyplayed.txt'. Em seguida, você pode adicionar código para adicionar uma música à lista.

Adicione o seguinte código à sua MusicLibraryPlugin classe:

[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";
}

Neste código, você cria uma função que aceita o artista, a música e o gênero como strings. Além Description do da função, você também adiciona descrições das variáveis de entrada. Esse código lê o conteúdo existente do arquivo, analisa-o e adiciona a nova música à lista. Depois, a lista atualizada é gravada de volta no arquivo. Em seguida, você criará o arquivo 'recentlyplayed.txt' com alguns dados de exemplo.

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

Crie um novo ficheiro 'recentlyplayed.txt' na pasta 'data' e, em seguida, 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 plugin.

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

Neste código, você importa o MusicLibraryPlugin para o kernel usando ImportPluginFromType. Em seguida, você liga InvokeAsync com o nome do plugin que deseja usar e a função que deseja chamar. Você também passa o artista, a música e o gênero como argumentos.

Execute o código inserindo dotnet run no terminal.

Deverá ver o seguinte resultado:
```
Added 'Danse' to recently played
```
Abra 'recentlyplayed.txt' e você verá a nova música adicionada à lista. Bom trabalho!

Exercício - Criar funções nativas

Preparar o ambiente de desenvolvimento

Criar um plugin de biblioteca de música

Comentários