ใช้เอเจนต์ AI โดยใช้ GitHub Copilot SDK

  • 10 นาที

หน่วยนี้ครอบคลุมรูปแบบการใช้งานหลักสําหรับการสร้างเอเจนต์ AI โดยใช้ GitHub Copilot SDK รูปแบบเหล่านี้ใช้กับสถานการณ์ของตัวแทน ตัวอย่างโค้ดใช้ C# และ .NET ซึ่งเป็นแพลตฟอร์มที่ใช้ในแบบฝึกหัดโมดูล

ตั้งค่าไคลเอ็นต์ GitHub Copilot SDK

ขั้นตอนแรกคือการสร้าง CopilotClient อินสแตนซ์ที่จัดการการเชื่อมต่อกับเซิร์ฟเวอร์ Copilot CLI โดยปกติ คุณจะลงทะเบียนไคลเอ็นต์เป็นบริการซิงเกิลตันในแอปพลิเคชันของคุณ

ติดตั้งแพ็คเกจที่จําเป็น

เพิ่ม GitHub Copilot SDK และแพ็คเกจ Microsoft.Extensions.AI (ใช้สําหรับคําจํากัดความของเครื่องมือ) ลงในโปรเจ็กต์ของคุณ:

dotnet add package GitHub.Copilot.SDK
dotnet add package Microsoft.Extensions.AI

กําหนดค่าไคลเอ็นต์

สร้างด้วยCopilotClientCopilotClientOptionsที่ควบคุมพฤติกรรมการเริ่มต้นและการบันทึก:

var client = new CopilotClient(new CopilotClientOptions
{
    AutoStart = true,
    LogLevel = "info"
});

ตัวเลือกจะ AutoStart บอกให้ SDK เปิดกระบวนการเซิร์ฟเวอร์ Copilot CLI โดยอัตโนมัติเมื่อสร้างเซสชันแรก ตัวเลือกนี้ LogLevel ควบคุมรายละเอียดของเอาต์พุตการวินิจฉัย SDK

หลังจากสร้างไคลเอนต์แล้ว ให้เริ่ม:

await client.StartAsync();

รหัสนี้สร้างการเชื่อมต่อกับเซิร์ฟเวอร์ CLI และเตรียมไคลเอ็นต์สําหรับการสร้างเซสชัน

กําหนดเครื่องมือของตัวแทน

เครื่องมือช่วยให้ตัวแทนสามารถโต้ตอบกับบริการแบ็กเอนด์ของแอปพลิเคชันของคุณได้ ใน GitHub Copilot SDK สําหรับ .NET คุณกําหนดเครื่องมือโดยใช้ AIFunctionFactory.Create จาก Microsoft.Extensions.AI แพ็คเกจ

สร้างบริการเครื่องมือ

รูปแบบทั่วไปคือการสร้างคลาสบริการเฉพาะที่มีวิธีการเครื่องมือทั้งหมดที่ตัวแทนของคุณสามารถเรียกใช้ได้ แต่ละวิธีแสดงถึงการดําเนินการหนึ่งอย่างที่ตัวแทนสามารถทําได้:

public class SupportAgentTools
{
    public async Task<string> GetOrderDetailsAsync(int orderId)
    {
        // Query the database for order information
        var order = await _dbContext.Orders.FindAsync(orderId);
        return order != null
            ? $"Order {orderId}: {order.ProductName}, Status: {order.Status}"
            : "Order not found.";
    }

    public async Task<string> ProcessReturnAsync(int orderId, string reason)
    {
        // Business logic to process the return
        var order = await _dbContext.Orders.FindAsync(orderId);
        order.Status = "Return Initiated";
        await _dbContext.SaveChangesAsync();
        return $"Return initiated for order {orderId}.";
    }
}

ลงทะเบียนเครื่องมือกับ SDK

แปลงวิธีการบริการของคุณเป็นคําจํากัดความของเครื่องมือที่ SDK สามารถใช้ได้ เครื่องมือแต่ละรายการต้องการชื่อ คําอธิบาย และคําอธิบายพารามิเตอร์ เพื่อให้โมเดล AI เข้าใจว่าควรใช้งานเมื่อใดและอย่างไร:

var toolService = new SupportAgentTools(dbContext);

var tools = new List<AIFunction>
{
    AIFunctionFactory.Create(
        async ([Description("The order ID number")] int orderId) =>
            await toolService.GetOrderDetailsAsync(orderId),
        "get_order_details",
        "Look up the status and details of a specific order."),

    AIFunctionFactory.Create(
        async ([Description("The order ID")] int orderId,
               [Description("The reason for the return")] string reason) =>
            await toolService.ProcessReturnAsync(orderId, reason),
        "process_return",
        "Process a return request for an order.")
};

การเรียกแต่ละครั้ง AIFunctionFactory.Create ต้องใช้อาร์กิวเมนต์สามแบบ:

  1. ฟังก์ชันแลมบ์ดา ที่ครอบเมธอดการบริการของคุณพร้อม [Description] แอตทริบิวต์ในแต่ละพารามิเตอร์
  2. ชื่อเครื่องมือ ที่โมเดล AI ใช้เพื่ออ้างอิงเครื่องมือ
  3. คําอธิบาย ที่ช่วยให้โมเดลเข้าใจว่าเมื่อใดควรเรียกใช้เครื่องมือ

[Description]แอตทริบิวต์บนพารามิเตอร์มีความสําคัญ ซึ่งจะบอกโมเดล AI ว่าแต่ละพารามิเตอร์หมายถึงอะไร ซึ่งช่วยให้โมเดลให้ค่าที่ถูกต้องเมื่อเรียกใช้เครื่องมือ

สร้างและกําหนดค่าเซสชัน

เซสชันแสดงถึงการสนทนาแต่ละรายการหรือบริบทของงาน คุณกําหนดค่าเซสชันด้วยแบบจําลอง พร้อมท์ระบบ เครื่องมือ และการตั้งค่าอื่นๆ

กําหนดค่าเซสชัน

ใช้เพื่อ SessionConfig ระบุวิธีการทํางานของเซสชัน:

var config = new SessionConfig
{
    Model = "gpt-4.1",
    SystemMessage = new SystemMessageConfig
    {
        Mode = SystemMessageMode.Replace,
        Content = @"You are a customer support agent for an e-commerce company.

CAPABILITIES:
- Look up order details
- Process returns

RULES:
- Only assist with order-related inquiries
- Always verify order details before taking action
- Be polite and professional"
    },
    Tools = tools,
    InfiniteSessions = new InfiniteSessionConfig
    {
        Enabled = false
    }
};

ตัวเลือกการกําหนดค่าที่สําคัญ:

  • โมเดล: ระบุโมเดล AI ที่จะใช้สําหรับเซสชันนี้
  • SystemMessage: กําหนดบทบาทและพฤติกรรมของตัวแทน กําหนด Mode ว่าข้อความแจ้งของคุณจะแทนที่ข้อความระบบเริ่มต้น (Replace) หรือผนวกข้อความ (Append)
  • เครื่องมือ: รายการคําจํากัดความของเครื่องมือที่เอเจนต์สามารถใช้ได้
  • InfiniteSessions: ควบคุมการบดอัดบริบทอัตโนมัติสําหรับการสนทนาที่ยาวนาน เมื่อเปิดใช้งาน คุณสามารถปรับ BackgroundCompactionThreshold และ BufferExhaustionThreshold เพื่อควบคุมเมื่อเกิดการบดอัด

สร้างเซสชัน

สร้างเซสชันจากไคลเอ็นต์โดยใช้การกําหนดค่าของคุณ:

var session = await client.CreateSessionAsync(config);

จัดการการตอบกลับด้วยเหตุการณ์

GitHub Copilot SDK ใช้โมเดลที่ขับเคลื่อนด้วยเหตุการณ์สําหรับการสื่อสาร หลังจากส่งข้อความ คุณจะสมัครรับกิจกรรมเพื่อรับการตอบกลับและตรวจหาเมื่อการประมวลผลเสร็จสมบูรณ์

สมัครใช้งานเหตุการณ์เซสชัน

ใช้ session.On เมธอดที่มีการจับคู่รูปแบบเพื่อจัดการกับเหตุการณ์ประเภทต่างๆ ดังนี้

var responseBuilder = new StringBuilder();
var tcs = new TaskCompletionSource<string>();

session.On(evt =>
{
    switch (evt)
    {
        case AssistantMessageEvent msg:
            responseBuilder.Append(msg.Data.Content);
            break;

        case SessionIdleEvent:
            tcs.SetResult(responseBuilder.ToString());
            break;

        case SessionErrorEvent err:
            tcs.SetException(
                new Exception($"Agent error: {err.Data.Message}"));
            break;
    }
});

เหตุการณ์แต่ละประเภทมีจุดประสงค์เฉพาะ:

  • AssistantMessageEvent: มีส่วนหนึ่งของข้อความตอบกลับของตัวแทน คุณรวบรวมข้อความเหล่านี้เพื่อสร้างการตอบกลับแบบเต็ม
  • SessionIdleEvent: ส่งสัญญาณว่าเอเจนต์ประมวลผลเสร็จแล้ว รวมถึงการเรียกใช้เครื่องมือทั้งหมด เหตุการณ์นี้บ่งชี้ว่าการตอบสนองเสร็จสมบูรณ์
  • SessionErrorEvent: ระบุว่ามีข้อผิดพลาดเกิดขึ้นระหว่างการประมวลผล คุณสมบัติประกอบด้วย Data.Message คําอธิบายข้อผิดพลาด

ส่งข้อความและรอการตอบกลับ

ใช้กับ SendAsync ออบเจ็ก MessageOptions ต์เพื่อส่งพรอมต์ของผู้ใช้ไปยังเอเจนต์:

await session.SendAsync(new MessageOptions
{
    Prompt = "What is the status of order 12345?"
});

// Wait for the response with a timeout
var response = await tcs.Task.WaitAsync(TimeSpan.FromSeconds(30));

TaskCompletionSourceรูปแบบที่แสดงที่นี่ช่วยให้คุณเชื่อมโยงโมเดล SDK ที่ขับเคลื่อนด้วยเหตุการณ์ด้วยโค้ดอะซิงโครนัส/รอ เมื่อ SessionIdleEvent ไฟไหม้ จะทํางานให้เสร็จสมบูรณ์ด้วยข้อความตอบกลับที่สะสมไว้

แนวทางปฏิบัติที่ดีที่สุดในการจัดการข้อผิดพลาด

การจัดการข้อผิดพลาดที่มีประสิทธิภาพเป็นสิ่งสําคัญสําหรับตัวแทนการผลิต

ข้อผิดพลาดของตัวจัดการเครื่องมือ

ห่อตัวจัดการเครื่องมือของคุณในบล็อก try-catch และส่งคืนข้อความแสดงข้อผิดพลาดที่มีความหมายแทนที่จะส่งข้อยกเว้น เมื่อเครื่องมือส่งคืนข้อความแสดงข้อผิดพลาด โมเดล AI สามารถตีความและให้การตอบสนองที่เป็นประโยชน์แก่ผู้ใช้:

AIFunctionFactory.Create(
    async ([Description("The order ID")] int orderId) =>
    {
        try
        {
            return await toolService.GetOrderDetailsAsync(orderId);
        }
        catch (Exception ex)
        {
            return $"Error retrieving order: {ex.Message}";
        }
    },
    "get_order_details",
    "Look up the status and details of a specific order.")

การจัดการข้อผิดพลาดระดับเซสชัน

ใช้ปุ่ม SessionErrorEvent เพื่อตรวจจับข้อผิดพลาดระหว่างการประมวลผลตัวแทน คุณยังสามารถกําหนดค่า OnErrorOccurred session hook ซึ่งส่งคืน ErrorHandling ค่าเพื่อควบคุมวิธีที่เอเจนต์ตอบสนองต่อข้อผิดพลาด:

  • ลองอีกครั้ง: ลองดําเนินการที่ล้มเหลวอีกครั้ง
  • ข้าม: ดําเนินการต่อโดยไม่มีผลลัพธ์ที่ล้มเหลว
  • ยกเลิก: หยุดการประมวลผลและแสดงข้อผิดพลาด

หมดเวลา

ตั้งเวลาหมดเวลาเสมอเมื่อรอการตอบกลับ ตัวอย่างก่อนหน้านี้ใช้เพื่อ WaitAsync(TimeSpan.FromSeconds(30)) ป้องกันการรออย่างไม่มีกําหนดหากตัวแทนพบปัญหาที่ไม่คาดคิด

การออกแบบพร้อมท์ของระบบ

พรอมต์ของระบบเป็นหนึ่งในการตัดสินใจกําหนดค่าที่สําคัญที่สุด มันกําหนดว่าใครคือตัวแทน สามารถทําอะไรได้บ้าง และควรประพฤติตนอย่างไร พรอมต์ระบบที่มีโครงสร้างดีโดยทั่วไปจะประกอบด้วย:

  • คําจํากัดความบทบาท: สิ่งที่ตัวแทนแสดง (ตัวอย่างเช่น "คุณเป็นตัวแทนฝ่ายสนับสนุนลูกค้าของ ContosoShop")
  • ความสามารถ: มีเครื่องมืออะไรบ้างและทําอะไรได้บ้าง
  • คําแนะนําเวิร์กโฟลว์: วิธีที่ตัวแทนควรเข้าหางาน (ตัวอย่างเช่น "ตรวจสอบรายละเอียดใบสั่งก่อนดําเนินการส่งคืนเสมอ")
  • กฎและข้อจํากัด: ขอบเขตที่ตัวแทนต้องปฏิบัติตาม (ตัวอย่างเช่น "พูดคุยเฉพาะหัวข้อที่เกี่ยวข้องกับคําสั่งซื้อ" หรือ "ส่งต่อคําขอคืนเงินมากกว่า $100")

ให้พรอมต์ของระบบโฟกัสและเฉพาะเจาะจง คําแนะนําที่คลุมเครือนําไปสู่พฤติกรรมที่คาดเดาไม่ได้ ในขณะที่กฎที่เข้มงวดเกินไปอาจทําให้ตัวแทนไม่เป็นประโยชน์

สตรีมการตอบกลับด้วยเหตุการณ์เดลต้า

สําหรับแอปพลิเคชันแบบโต้ตอบ เช่น UI การแชท คุณสามารถสตรีมโทเค็นการตอบกลับของตัวแทนด้วยโทเค็นแทนการรอข้อความที่สมบูรณ์ ใช้เพื่อ AssistantMessageDeltaEvent จับโทเค็นบางส่วนแต่ละรายการเมื่อมาถึง:

session.On(evt =>
{
    switch (evt)
    {
        case AssistantMessageDeltaEvent delta:
            // Render each token as it arrives
            Console.Write(delta.Data.DeltaContent);
            break;

        case SessionIdleEvent:
            Console.WriteLine();
            tcs.SetResult("Done");
            break;

        case SessionErrorEvent err:
            tcs.SetException(
                new Exception($"Agent error: {err.Data.Message}"));
            break;
    }
});

คุณสมบัติประกอบด้วย DeltaContent ส่วนย่อยของข้อความที่เพิ่มขึ้น การสตรีมมอบประสบการณ์การตอบสนองที่มากขึ้น เนื่องจากผู้ใช้เห็นการตอบสนองตามรูปแบบ แทนที่จะรอให้โมเดลสร้างข้อความทั้งหมด

Summary

GitHub Copilot SDK มีเฟรมเวิร์กที่มีประสิทธิภาพสําหรับการใช้ตัวแทน AI ที่สามารถให้เหตุผล ใช้เครื่องมือ และรักษาบริบทได้ การกําหนดค่าเซสชันด้วยข้อความแจ้งของระบบที่ชัดเจน และการจัดการการตอบกลับด้วยเหตุการณ์ คุณสามารถสร้างตัวแทนที่ซับซ้อนซึ่งมอบคุณค่าทางธุรกิจที่แท้จริงได้ การจัดการข้อผิดพลาดที่มีประสิทธิภาพและการออกแบบที่รวดเร็วอย่างรอบคอบเป็นสิ่งสําคัญในการทําให้มั่นใจว่าตัวแทนของคุณทํางานได้อย่างน่าเชื่อถือและมีประสิทธิภาพในสถานการณ์การผลิต ในหน่วยถัดไป คุณจะเห็นวิธีใช้รูปแบบการใช้งานเหล่านี้เพื่อสร้างตัวแทนการสนับสนุนลูกค้าตัวอย่างโดยใช้ GitHub Copilot SDK