Day 14: Semantic Kernel Multi-Agent 實戰 - 多代理人的 HandoffOrchestration 編排系統 - iT 邦幫忙::一起幫忙解決難題，拯救 IT 人的一天

2025 iThome 鐵人賽

DAY 14

生成式 AI

當 .NET 遇見 AI Agents：用 Semantic Kernel × MCP 打造智慧協作應用系列第 14 篇

Day 14: Semantic Kernel Multi-Agent 實戰 - 多代理人的 HandoffOrchestration 編排系統

17th鐵人賽 ai llm ai agent

Ian

2025-09-28 23:23:05

46 瀏覽

分享至

前面的幾個範例是以單一代理人 (Single Agent) 為主，無論是單工具 (Single Tool) 還是多工具 (Multi-Tool) 的情境，都由同一個 Agent 負責處理所有任務。在真實世界的應用中，問題往往是複雜且多面向的，單一代理人可能無法有效的解決所有問題。因此接下來，我們轉入到多代理人 (Multi-Agent) 的概念，透過不同的代理人協同合作，來達成更高效的問題解決方案。

在今天文章中，看如何使用 Semantic Kernel AI Agent framework 的 HandoffOrchestration 編排系統，來管理多個代理人之間的協作與任務轉移。HandoffOrchestration 用於「依情境把對話與控制權轉交給更合適的代理（Agent）」。典型流程像是由一個分流/客服前台先接住需求，再按規則或上下文把控制權交給特定領域的專家代理 Agent。

典型應用場景包括：

客服中心：初步分流客戶問題，轉交給專門處理技術支援、帳務或產品相關問題的代理人。
企業內部支援：員工提出 IT、HR 或法遵相關問題，系統根據問題類型轉交給對應的專責代理人。
醫療諮詢：患者描述症狀後，系統將對話轉交給專門處理不同疾病領域的醫療代理人。
法律諮詢：根據客戶的法律問題，將對話轉交給專門處理合同、知識產權或勞動法的法律代理人。

接下來，以 企業內部支援 為例，展示如何使用 HandoffOrchestration 編排系統來管理多個代理人，並根據使用者的需求將對話轉交給最合適的代理人。

開始之前先確保已經安裝好 Semantic Kernel 的相關套件，並且有一個可用的 LLM 服務（例如 Azure OpenAI 或 OpenAI）。

dotnet add package Microsoft.SemanticKernel
dotnet add package Microsoft.SemanticKernel.Agents.Core
dotnet add package Microsoft.SemanticKernel.Agents.Orchestration --prerelease
dotnet add package Microsoft.SemanticKernel.Agents.Runtime.InProcess --prerelease

Step 1: 建立多個專責代理人 (ChatCompletionAgent)

首先，我們需要建立多個專責代理人 (ChatCompletionAgent)，每個代理人負責不同的領域，例如 IT 支援、人力資源 (HR) 和法遵合規 (Compliance)。這些代理人將根據使用者的需求提供專業的回答。

建立 TriageAgent，負責初步分流使用者的問題：

var triageAgent = new ChatCompletionAgent
{
    Kernel = kernel,
    Name = "TriageAgent",
    Description = "問題分流助理",
    Instructions = @"對使用者的提問進行分類的企業支援代理。任務是判斷使用者問題屬於哪一類：人資(HR)、IT、或合規(Compliance)。
    若不屬於任何類型，也可請使用者釐清問題類別。"
};

建立 HRPolicyAgent，負責處理人力資源相關的問題：

var hrAgent = new ChatCompletionAgent
{
    Kernel = kernel,
    Name = "HRPolicyAgent",
    Description = "負責回應與人資制度與公司內部 HR 規章相關的問題",
    Instructions =
    """
    你是公司的人資專員，請針對與以下主題相關的提問提供清楚、準確的解答：
    - 人事制度（如考勤、升遷、轉調等）
    - 請假規定（如病假、事假、特休等）
    - 員工福利（如保險、補助、活動等）

    如果問題不在你的職責範圍，請回覆「這部分建議您洽詢其他單位，我無法提供正確資訊」。
    """
};

建立 ITSupportAgent，負責處理 IT 支援相關的問題：

var itAgent = new ChatCompletionAgent
{
    Kernel = kernel,
    Name = "ITSupportAgent",
    Description = "提供 IT 設備、VPN、帳號權限等技術支援服務",
    Instructions =
    """
    你是公司的 IT 支援人員，請協助處理以下類型的問題：
    - IT 設備（如電腦、印表機、網路）
    - 帳號與系統存取權限（如登入問題、權限申請）
    - VPN、遠端連線與系統備份設定

    請用清楚的步驟或指引協助提問者解決問題。若問題非 IT 支援職責，請委婉引導至相關單位。
    """
};

建立 ComplianceAgent，負責處理法遵合規相關的問題：

var complianceAgent = new ChatCompletionAgent
{
    Kernel = kernel,
    Name = "ComplianceAgent",
    Description = "協助處理合規與資訊安全條例的詢問",
    Instructions =
    """
    你是法遵與資安顧問，請專注回答以下範圍的問題：
    - 公司合約條款與合規要求
    - 資訊安全政策（如存取控制、資料保護）
    - 公司治理規定與內部稽核事項

    若遇到與 HR 或 IT 技術相關的問題，請提醒使用者改由其他專責人員處理。
    """
};

Step 2: 建立相關的 plugins (Tools)

每個代理人都可以使用特定的工具 (Tools) 來輔助回答問題。這些工具可以是查詢公司政策、IT 支援文件或法遵規範的函式。

public class CompliancePlugin
{
    [KernelFunction, Description("Query specific contract compliance clause")]
    public string GetContractPolicy([Description("Clause name")] string clauseName)
    {
        return clauseName.ToLower() switch
        {
            "保密條款" => "所有員工必須簽署 NDA，嚴禁洩漏公司資料予第三方。",
            "競業禁止" => "離職後六個月內不得任職於競爭公司，除非經公司書面同意。",
            _ => "找不到指定的合約條款。"
        };
    }

    [KernelFunction, Description("Query company data security policy")]
    public string GetDataSecurityPolicy()
    {
        return "公司所有機密文件必須儲存在加密磁碟區，傳輸時使用 TLS 加密，並定期進行權限稽核。";
    }

    [KernelFunction, Description("Query company governance policy")]
    public string GetGovernancePolicy()
    {
        return "公司治理依據董事會決議與公司章程執行，設有內部稽核與合規部門監督運作。";
    }
}

public class HRPolicyPlugin
{
    [KernelFunction, Description("Get detailed leave policy information")]
    public string GetLeavePolicy([Description("Type of leave")] string leaveType)
    {
        return @"請假政策說明：\n" +
               "1. 病假：每年提供30日，未使用部分得轉為特休。\n" +
               "2. 特休：依年資計算，滿一年提供7日，滿兩年提供10日。\n" +
               "3. 事假：每年最多7日，不扣薪但需主管核准。";
    }

    [KernelFunction, Description("Query specific benefit policy")]
    public string GetBenefitPolicy([Description("Benefit name")] string benefitName)
    {
        return @"福利政策說明：\n" +
               "1. 旅遊補助：每位員工每年可申請一次旅遊補助上限 NT$5,000。\n" +
               "2. 健康檢查：公司每兩年提供一次免費員工健康檢查。\n" +
               "3. 午餐補助：每日午餐補助 NT$100，自動匯入薪資帳戶。";
    }

    [KernelFunction, Description("Query attendance policy description")]
    public string GetAttendancePolicy()
    {
        return "上班時間為上午9:00至下午6:00，彈性時間為8:00至10:00，需每日完成8小時工作。";
    }
}

public class ITSupportPlugin
{
    [KernelFunction, Description("Get VPN setup tutorial")]
    public string GetVpnSetup()
    {
        return "VPN 設定步驟：1. 下載公司專用 VPN 軟體；2. 安裝後輸入員工帳號密碼；3. 連線至內部網段 vpn.company.com。";
    }

    [KernelFunction, Description("Query system account activation process")]
    public string GetAccountPolicy([Description("System name")] string systemName)
    {
        return $"系統「{systemName}」的帳號申請請透過 IT 申請單，由主管核准後開通，預計作業時間為1-2工作天。";
    }

    [KernelFunction, Description("Query backup policy")]
    public string GetBackupPolicy()
    {
        return "所有桌機與筆電會自動每日備份至雲端，保留期限為30日。如需還原請聯繫 IT 支援。";
    }
}

Step 3: 定義 HandoffOrchestration 編排系統

接下來，我們使用 HandoffOrchestration 來定義多個代理人之間的協作規則和轉移邏輯。這個系統將根據使用者的輸入，將對話從一個代理人轉移到另一個代理人，以確保問題能夠被適當處理。

起始點 (StartWith(triageAgent))
所有使用者查詢都先由 triageAgent（問題分流助理）處理
這個代理人負責判斷問題屬於哪個領域
可轉移目標 (Add(triageAgent, hrAgent, itAgent, complianceAgent))
定義分流代理人可以將問題轉移給哪些專門代理人
包含：HR代理人、IT代理人、合規代理人
轉移規則 (後續三個 Add 方法)
HR轉移：處理請假、薪資、人資政策、出勤相關問題
IT轉移：處理IT設備、帳號、VPN、密碼、裝置相關問題
合規轉移：處理合規、安全、內部公司政策相關問題

//選擇合適的聊天代理人 (用 HandoffOrchestration)
// Define the orchestration
// 代理人交接編排系統，它定義了多個AI代理人之間的協作規則和轉移邏輯。
// 負責根據使用者的輸入，將對話從一個代理人轉移到另一個代理人，以確保問題能夠被適當地處理。
HandoffOrchestration orchestration =
    new(OrchestrationHandoffs
            .StartWith(triageAgent) // 🎯 起始代理人
            .Add(triageAgent, hrAgent, itAgent, complianceAgent)  // 📋 可轉移的目標代理人清單
            .Add(triageAgent, hrAgent, "Transfer to this agent if the issue is about leave, salary, HR policy, or attendance.") // 🔄 HR轉移規則
            .Add(triageAgent, itAgent, "Transfer to this agent if the issue is about IT, account, VPN, password, or device.") // 💻 IT轉移規則
            .Add(triageAgent, complianceAgent, "Transfer to this agent if the issue is about compliance, security, or internal company policy."),  // ⚖️ 合規轉移規則
        triageAgent, hrAgent, itAgent, complianceAgent); // 🤖 參與的所有代理人

Step 4: 建立協作流程物件

InProcessRuntime 是代理人系統的執行引擎，負責管理代理人的生命週期和狀態，所有代理人都在同一個程序中執行。
runtime.StartAsync() 初始化所有代理人，啟動協作流程，準備好接受使用者的輸入並進行處理。
orchestration.InvokeAsync(userInput, runtime) 將使用者的輸入傳遞給協作流程，編排系統會先讓 triageAgent 分析問題，然後根據定義的轉移規則，將對話轉交給適當的專責代理人 (hrAgent、itAgent 或 complianceAgent) 來處理問題。

// 建立協作流程物件
InProcessRuntime runtime = new();

// 進行對話
Console.Write("User > ");
string? userInput;
while ((userInput = Console.ReadLine()) is not null)
{
    //啟動協作流程
    await runtime.StartAsync();
    if (string.IsNullOrWhiteSpace(userInput) || userInput.Equals("exit", StringComparison.OrdinalIgnoreCase))
        break;

    // 將使用者輸入傳遞給協作流程
    var result = await orchestration.InvokeAsync(userInput, runtime);
    Console.Write("AI > ");
    var response = result.GetValueAsync(TimeSpan.FromSeconds(300)); //等待代理人回應，最多等待 300 秒（5分鐘），防止程式無限等待
    Console.Write(response);
    await runtime.RunUntilIdleAsync();　// 確保所有代理人任務完成

    Console.WriteLine("\n\n");
    Console.Write("User > ");
}

執行結果

User > 公司有保密條款嗎
AI > 公司有保密條款，所有員工必須簽署 NDA（保密協議），嚴禁將公司資料洩漏給第三方。這是基本的合約與合規要求，請確實遵守相關規定。


User > 我是新人,請告訴我上理時間是幾點啊
AI > 屬於人資(HR)類問題。

本公司的上班時間是上午9:00至下午6:00，並有彈性時間8:00至10:00可供選擇，但每天需完成8小時的工作。歡迎你加入！如有其他人資相關疑問也可以再詢問我。