Semantic Kernel | 如何建立智慧助理(Agent)

前言

之前，做 ChatBot 時，收到使用者輸入，會先判斷它的意圖，
然後判斷要完成該意圖缺多少的內容，再一一地詢問使用者。
現在，透過 Semantic Kernel(SK)，這些不足的資訊，可以透過ChatCompletionService來幫我們。
以下就來看看要如何做到呢?

Agent 在 由 Semantic Kernel 中，由plugins, planners 及 persona(角色/人設) 三個核心組件組成。
這些組件是讓 Agent 能夠從使用者或其他系統獲取資訊，規劃如何使用資訊，並使用資訊來回應使用者或執行動作。
以下我們以一個幫助使用者請假的 HR Copilot 為例。
在取得使用者資訊後，Semantic Kernel 透過 ChatCompletionService 找尋要完成任務的plugins並呼叫它，
最後再將這些plugins的結果給使用者。

實作

建立 Console 程式，並加入以下套件，

dotnet new console -n hragent -o hragent
dotnet add package Microsoft.Extensions.Logging
dotnet add package Microsoft.Extensions.Logging.Debug
dotnet add package Microsoft.SemanticKernel --prerelease
dotnet add package Microsoft.SemanticKernel.Connectors.OpenAI --prerelease
dotnet add package Microsoft.SemanticKernel.Plugins.Core --prerelease

要完成這個簡單的請假計畫包含以下幾步， 1.取得請假的起、迄日期區間 2.請假假別 3.請假原因

所以我們要建立 Plugins 來讓 Agent 有請假的能力。
這個就是 Plugins 的作用，讓 Agent 增加技能。
所以就建立 LeavePlanner 類別，
裡面有 ApplyLeaveAsync 處理請假，ParseTimeRange處理上/下午時間區間，
Function 要設定 KernelFunction ，Description 也要寫清楚，
這樣 ChatCompletionService 才可以找得到它，如下，

using Microsoft.SemanticKernel;
using System.ComponentModel;

namespace hragent.plugins.leave;
public class LeavePlanner
{

    [KernelFunction]
    [Description("執行請假，並回傳請假資訊")]
    [return: Description("執行請假結果")]
    public async Task<string> ApplyLeaveAsync(
        Kernel kernel,
        [Description("開始請假日期及時間")] string startDateTime,
        [Description("結束請假日期及時間")] string endDateTime,
        [Description("假別")] string leaveType,
        [Description("請假原因")] string reason
    )
    {
        var result = $"執行請假:從{startDateTime}~{endDateTime}, 假別:{leaveType}, 原因:{reason}";
        return await Task.FromResult<string>(result);
    }


    [KernelFunction]
    [Description("將 上午、下午 轉成時間區間")]
    [return: Description("時間區間")]
    public async Task<TimeRange> ParseTimeRange(
        Kernel kernel,
        [Description("上午、下午 ")] string morning_afternoon
    )
    {
        var result = new TimeRange(TimeSpan.FromHours(8.5), TimeSpan.FromHours(17.5));
        if (morning_afternoon == "morning")
        {
            result = new TimeRange(TimeSpan.FromHours(8.5), TimeSpan.FromHours(12));
        }
        if (morning_afternoon == "afternoon")
        {
            result = new TimeRange(TimeSpan.FromHours(13), TimeSpan.FromHours(17.5));
        }
        return await Task.FromResult<TimeRange>(result);
    }

    public record TimeRange(TimeSpan from, TimeSpan to);
}

接著將這些 Plugins 載入進來，並讓 Semantic Kernel 可以依語義自動去執行它們，
以下是 Program.cs 的程式碼，

using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Logging;
using Microsoft.SemanticKernel;
using Microsoft.SemanticKernel.ChatCompletion;
using Microsoft.SemanticKernel.Connectors.OpenAI;
using Microsoft.SemanticKernel.Plugins.Core;
var builder = Kernel.CreateBuilder();
builder.Services.AddLogging(c => c.SetMinimumLevel(LogLevel.Trace).AddDebug());
builder.Services.AddAzureOpenAIChatCompletion(
    deploymentName: "<你的aoai的deploymentName>",
    modelId: "<你的aoai的modelId(gpt-35-turbo or gpt-4)>",
    endpoint: "<你的aoai的endpoint>",
    apiKey: "<你的aoai的apikey>"
);
//載入內建的時間Plugin
builder.Plugins.AddFromType<TimePlugin>();
//找入請假Plugin
builder.Plugins.AddFromType<LeavePlanner>();
var kernel = builder.Build();
//設定它的角色(Personas)
var chatMessages = new ChatHistory("""
你是一個專業的人力資源助手，專門為用戶提供人力資源相關的建議和資訊。
如果使用者沒有提供足夠的資訊讓您完成任務，您將繼續提出問題，直到您有足夠的資訊來完成任務。
""");

var chatCompletionService = kernel.GetRequiredService<IChatCompletionService>();
// Start the conversation
while (true)
{
    // Get user input
    Console.Write("User > ");
    var userInput = Console.ReadLine()!;
    if (userInput == "exit")
    {
        break;
    }
    chatMessages.AddUserMessage(userInput);

    OpenAIPromptExecutionSettings openAIPromptExecutionSettings = new()
    {
        //設定讓 ChatCompletionService 可依語義自動去呼叫需要的 Functions
        ToolCallBehavior = ToolCallBehavior.AutoInvokeKernelFunctions
    };
    var result = chatCompletionService.GetStreamingChatMessageContentsAsync(
        chatMessages,
        executionSettings: openAIPromptExecutionSettings,
        kernel: kernel);

    // Stream the results
    string fullMessage = "";
    var first = true;
    await foreach (var content in result)
    {
        if (content.Role.HasValue && first)
        {
            Console.Write($"Assistant > ");
            first = false;
        }
        Console.Write(content.Content);
        fullMessage += content.Content;
    }
    Console.WriteLine();
    // Add the message from the agent to the chat history
    chatMessages.AddAssistantMessage(fullMessage);
}

Console.WriteLine("結束對話...");

我們的 Agent 有了請假功能，所以將程式跑起來，
輸入我明天下午要到UUU訓練中心上 Azure AZ-900 課程，所以要請公假，
ChatCompletionService會將明天呼叫TimePlugin_Today Function 解析出2024/1/5，如下，

因為有下午，所以會呼叫ParseTimeRange取得13:00~17:30時間區段，

有了時間、假別、原因，就可以呼叫ApplyLeaveAsync 來進行請假，

所以最後 Agent 就會回，已請假完成等 Summary 的資訊，如下，

另一個範例，

以往我們通常會先將使用者的要求，找出它的意圖，及相關資訊，不足地方則程式控制來詢問使用者，
例如使用者只說我要請假，那程式則將必填的欄位透過程式一個一個詢問使用者。

ChatCompletionService是透過語義的方式自動尋找可完成的Planner並搭配許多Plugins來完成使用者的要求，
如果使用者給的訊息，缺少 Function 需要的參數，則是由 Agent 自動詢問使用者取得來完成工作。
雖然這種方式很方便，但是透過 GPT 來整理相關的訊息會花費較長時間，
因為它將要將目前的ChatHistory做整理。

參考資源

What is an agent?
plugins
planners

一人計，不如百人算:集合外數人的意見，可成客觀而有系統的結論(三個臭皮匠，湊個諸葛亮)。