ทําความเข้าใจเกี่ยวกับโพรโทคอลกิจกรรม

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

กิจกรรมคืออะไร

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

ทุกกิจกรรมประกอบด้วยเมตาดาต้าเกี่ยวกับ:

• ใครส่งมันมา (จาก)
• ใครควรได้รับสิทธิ์ (ผู้รับ)
• บริบทการสนทนา
• ช่องที่มาจาก
• ชนิดของการโต้ตอบ
• ข้อมูลเพย์โหลด

เค้าร่างกิจกรรม - คุณสมบัติหลัก

ข้อกําหนดนี้กําหนดโพรโทคอลกิจกรรม: โพรโทคอลกิจกรรม - กิจกรรม คุณสมบัติหลักบางประการที่กําหนดไว้ในโพรโทคอลกิจกรรมคือ:

ทรัพย์สิน	คำอธิบาย
Id	โดยทั่วไปแล้ว จะสร้างขึ้นโดยช่อง ถ้ามีต้นทางจากช่อง
Type	ชนิด จะควบคุมความหมายของกิจกรรม ตัวอย่างเช่น ชนิดข้อความ
ChannelID	อ้างอิง ChannelID ถึงช่องทางต้นกำเนิดของกิจกรรม ตัวอย่างเช่น: msteams
From	ผู้ส่งของกิจกรรม (ซึ่งอาจเป็นผู้ใช้หรือตัวแทน)
Recipient	ผู้รับที่ตั้งใจของกิจกรรม
Text	เนื้อหาของข้อความ
Attachment	เนื้อหาที่สมบูรณ์ เช่น การ์ด รูปภาพของไฟล์

เข้าถึงข้อมูลกิจกรรม

นักพัฒนาจําเป็นต้องเข้าถึงข้อมูลภายในกิจกรรมเพื่อทําให้การดําเนินการจาก TurnContext วัตถุเสร็จสมบูรณ์

คุณสามารถค้นหา TurnContext คลาสในแต่ละเวอร์ชันภาษาของ SDK ของตัวแทน Microsoft 365:

• .NET: เทิร์นบริบท
• หลาม: TurnContext
• JavaScript: เทิร์นบริบท

Note

ส่วนย่อยของโค้ดในบทความนี้ใช้ C# ไวยากรณ์และโครงสร้าง API สําหรับ JavaScript และเวอร์ชัน Python จะคล้ายกัน

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

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

1. กิจกรรมที่เข้ามา: ผู้ใช้ส่งข้อความหรือดําเนินการสร้างกิจกรรม
2. รหัสของคุณได้รับกิจกรรมและตัวแทนประมวลผลโดยใช้TurnContext
3. ตัวแทนของคุณส่งกิจกรรมกลับไปหนึ่งรายการหรือมากกว่านั้น
4. การเลี้ยวสิ้นสุดลงและ TurnContext ถูกกําจัดออกไป

เข้าถึงข้อมูลจาก TurnContextเช่น:

var messageText = turnContext.Activity.Text
var channelID = turnContext.Activity.ChannelId

ส่วนย่อยของโค้ดนี้แสดงตัวอย่างของการหมุนที่สมบูรณ์:

agent.OnActivity(ActivityTypes.Message, async (turnContext, turnState, cancellationToken) =>
{
    var userMessage = turnContext.Activity.Text'
    var response = $"you said: {userMessage}";
    await turnContext.SendActivityAsync(MessageFactory.Text(response), cancellationToken);
});

TurnContextภายในคลาส ข้อมูลสําคัญที่ใช้กันทั่วไปประกอบด้วย:

• กิจกรรม: วิธีหลักในการรับข้อมูลจากกิจกรรม
• ตัวปรับต่อ: ตัวปรับต่อช่องสัญญาณที่สร้างกิจกรรม
• TurnState: สถานะสําหรับการหมุน

ชนิดกิจกรรม

ประเภทของกิจกรรมมีความสําคัญเนื่องจากเป็นตัวกําหนดสิ่งที่จําเป็นหรือที่คาดไว้ในกิจกรรมที่เหลือระหว่างไคลเอ็นต์ ผู้ใช้ และตัวแทน

ข้อความ

กิจกรรมชนิดทั่วไปคือ ชนิดActivity ซึ่งสามารถรวมข้อความ สิ่งที่แนบมา และการดําเนินการที่แนะนําเพื่อตั้งชื่อการใช้งานทั่วไปสําหรับชนิดนี้

agent.OnActivity(ActivityTypes.Message, async (turnContext, turnState, cancellationToken) =>
{
    var userMessage = turnContext.Activity.Text'
    var response = $"you said: {userMessage}";
    await turnContext.SendActivityAsync(MessageFactory.Text(response), cancellationToken);
});

อัปเดตการสนทนา

ชนิด Activity จะแจ้งเจ้าหน้าที่ของคุณเมื่อสมาชิกเข้าร่วมหรือออกจากการสนทนา ไม่ใช่ลูกค้าทั้งหมดที่จะสนับสนุนเรื่องนี้ ไคลเอ็นต์ที่โดดเด่นคือ Microsoft Teams

ส่วนย่อยของโค้ดต่อไปนี้จะทักทายสมาชิกใหม่ในการสนทนา:

agent.OnActivity(ActivityTypes.ConversationUpdate, async (turnContext turnState, cancellationToken) =>
{
    var membersAdded = turnContext.Activity.MembersAdded
    if (membersAdded != null)
    {
        foreach (var member in membersAdded)
        {
            if (member.Id != turnContext.Activity.Reciepient.Id)
            {
                await turnContext.SendActivityAsync(MessageFactory.Text($"Welcome {member.Name}!"), cancellationToken);
            }
        }
    }
})

กิจกรรม

ชนิดของActivityเป็นเหตุการณ์แบบกําหนดเองที่อนุญาตให้ช่องหรือไคลเอ็นต์ส่งข้อมูลที่มีโครงสร้างไปยังตัวแทนของคุณ ซึ่งไม่ได้กําหนดไว้ล่วงหน้าในActivityโครงสร้างส่วนข้อมูล

คุณจะต้องสร้างตัวจัดการวิธีการ/เส้นทางสําหรับชนิดเฉพาะ Event แล้วจัดการตรรกะที่ต้องการโดยยึดตาม:

ชื่อ - ชื่อเหตุการณ์หรือตัวระบุจาก ค่า ไคลเอ็นต์ - ส่วนข้อมูลเหตุการณ์ที่โดยทั่วไปเป็นวัตถุ JSON

agent.OnActivity(ActivityTypes.Event, async (turnContext turnState, cancellationToken) =>)
{
    var eventName = turnContext.Activity.Name
    var eventValue = turnContext.Activity.Value

    // custom event (E.g. a switch on eventName)
}

เรียก

ประเภทของActivityคือประเภทเฉพาะของกิจกรรมที่ไคลเอ็นต์กําลังเรียกใช้ลงในตัวแทนเพื่อดําเนินการคําสั่งหรือการดําเนินการและไม่เพียงแค่ข้อความ ตัวอย่างของกิจกรรมประเภทเหล่านี้มีทั่วไปใน Microsoft Teams สําหรับ task/fetch และtask/submit ไม่ใช่ทุกช่องที่จะสนับสนุนกิจกรรมประเภทเหล่านี้

พิมพ์

ประเภทActivityคือการจําแนกประเภทของกิจกรรมเพื่อระบุว่ามีคนพิมพ์อยู่ในการสนทนา ซึ่งมักจะเห็นได้ทั่วไประหว่างการสนทนาของมนุษย์กับมนุษย์ในไคลเอ็นต์ Microsoft Teams กิจกรรมการพิมพ์ไม่ได้รับการสนับสนุนในทุกลูกค้า และ Microsoft 365 Copilot จะไม่สนับสนุนกิจกรรมการพิมพ์

await turnContext.SendActivityAsync(new Activity { Type = ActivityTypes.Typing }, cancellationToken); 
await Task.Delay(2000);
await turnContext.SendActivityAsync(MessageFactory.Text("Here is your answer..."), cancellationToken)

สร้างและส่งกิจกรรม

หากต้องการส่งการตอบกลับ 'TurnContext' มีหลาย วิธี ในการส่งการตอบกลับกลับไปยังผู้ใช้

agent.OnActivity(ActivityTypes.Message, async (turnContext, turnState, cancellationToken))
{
    await turnContext.SendActivityAsync("hello!", cancellationToken: CancellationToken) // uses string directly
    await turnContext.SendActivityAsync(MessageFactory.Text("Hello"), cancellationToken) // uses Message Factory
    await turnContext.SendActivitiesAsync(activities, cancellationToken) // send multiple activities in an Activity array
}

ทำงานกับสิ่งที่แนบ

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

เพื่อรับสิ่งที่แนบมา

รหัสต่อไปนี้แสดงวิธีการรับและเอกสารแนบ

agent.OnActivity(ActivityTypes.Message, async(turnContext, turnState, cancellationToken)) =>
{
    var activity = turnContext.Activity;
    if (activity.Attachments != null && activity.Attachments.Count >0)
    {
        foreach (var attachment in activity.Attachments)
        {
            // get metadata as required e.g. attachment.ContextType or attachment.ContentUrl
            // use the URL to securely download the attachment and complete your business logic
        }
    }
}

โดยทั่วไปเมื่อต้องรับเอกสารบนสิ่งที่แนบมา ไคลเอ็นต์ส่งคําขอรับรองความถูกต้อง GET เพื่อดึงข้อมูลเนื้อหาจริง - แต่ละอะแด็ปเตอร์มีวิธีของตัวเองในการรับข้อมูลตัวอย่างเช่น Teams, OneDrive และอื่น ๆ สิ่งสําคัญคือต้องทราบว่า URL เหล่านั้นมักสั้นและอย่าคิดว่าพวกเขาจะอยู่ที่นั่นซึ่งเป็นเหตุผลว่าทําไมการย้ายไปยังที่เก็บข้อมูลของคุณเองเป็นสิ่งสําคัญหากคุณต้องการอ้างอิงเรื่องนี้ในภายหลัง

อ้าง อิง

สิ่งสําคัญคือต้องทราบว่า สิ่งที่แนบมา และ การอ้างอิง ไม่ใช่ชนิดวัตถุเดียวกัน ข้อมูลอ้างอิงคือการจัดการโดยไคลเอ็นต์ เช่น Microsoft Teams ด้วยวิธีของตนเอง และใช้ คุณสมบัติ เอนทิตี ของ Activity และ สามารถเพิ่มและ activity.Entities.Add เพิ่มวัตถุใหม่ Entity ที่มีข้อกําหนดเฉพาะ Citation ตามไคลเอ็นต์ของคุณ ซึ่งจะได้รับการซีเรียลไลซ์เป็นออบเจ็กต์ JSON ที่ไคลเอ็นต์จากนั้นจะดีซีเรียลโดยยึดตามวิธีการแสดงผลในไคลเอ็นต์ โดยพื้นฐานแล้ว สิ่งที่แนบมาเป็นข้อความ และการอ้างอิงสามารถอ้างอิงสิ่งที่แนบมา และเป็นวัตถุอีกชนิดหนึ่งที่ส่งใน Entities ของข้อมูล Activity

ข้อควรพิจารณาเฉพาะของช่อง

SDK ตัวแทนของ Microsoft 365 ถูกสร้างขึ้นเป็น 'ฮับ' ที่ช่วยให้นักพัฒนาสามารถสร้างตัวแทนที่สามารถทํางานกับลูกค้า ใด ๆ รวมทั้งไคลเอ็นต์ที่เราสนับสนุนและให้เครื่องมือสําหรับนักพัฒนาเพื่อสร้างอะแด็ปเตอร์แชนเนลของพวกเขาเองโดยใช้เฟรมเวิร์กเดียวกัน ซึ่งทําให้นักพัฒนามีความแพร่หลายเมื่อกล่าวถึงตัวแทน และเพิ่มความสามารถในการเพิ่มให้กับไคลเอ็นต์เพื่อเชื่อมต่อกับฮับนั้น ซึ่งอาจเป็นไคลเอ็นต์อย่างน้อยหนึ่งราย เช่น Microsoft Teams, Slack และอื่นๆ

ช่องทางที่แตกต่างกันมีความสามารถและข้อจํากัดที่แตกต่างกัน และต่อไปนี้เป็นข้อมูลสรุปข้อควรพิจารณาเมื่อทํางานกับลูกค้าทั่วไป

คุณสามารถตรวจสอบช่องที่ได้รับกิจกรรมโดยการตรวจสอบคุณสมบัติ channelId ใน Activity ได้

ช่องมีข้อมูลเฉพาะที่ไม่สอดคล้องกับส่วนข้อมูลทั่วไป Activity ในทุกช่อง และสามารถเข้าถึงได้จาก TurnContextActivity.ChannelData และแคสต์ไปยังตัวแปรโดยเฉพาะสําหรับการใช้งานในโค้ดของคุณ

ทีมไมโครซอฟท์

• รองรับ อะแดปทีฟการ์ด ที่สมบูรณ์ด้วยคุณลักษณะขั้นสูง
• รองรับการอัปเดตข้อความและการลบ
• มีข้อมูลช่องเฉพาะสําหรับคุณลักษณะของ Teams (กล่าวถึง ข้อมูลการประชุม และอื่นๆ)
• รองรับการเรียกใช้งานสําหรับโมดูลงาน

Microsoft 365 Copilot

• เน้นไปที่กิจกรรมข้อความเป็นหลัก
• สนับสนุนอ้างอิงและการอ้างอิงในการตอบกลับ
• จําเป็นต้องมีการตอบสนองการสตรีม
• การสนับสนุนที่จำกัดสำหรับการ์ดแบบรวย/การ์ดปรับเปลี่ยนได้

WebChat/DirectLine

Web Chat เป็นโพรโทคอล HTTP ที่ใช้สําหรับตัวแทนในการพูดคุยผ่าน HTTPS

• การสนับสนุนเต็มรูปแบบสําหรับประเภทกิจกรรมทั้งหมด
• รองรับข้อมูลช่องแบบกําหนดเอง

ช่องของบุคคลที่สาม

ซึ่งรวมถึง Slack, Facebook และอื่นๆ อีกมากมาย

• อาจมีการจํากัดการสนับสนุนสําหรับกิจกรรมบางประเภท
• การแสดงการ์ดอาจแตกต่างกันหรือไม่สนับสนุน
• ตรวจสอบเอกสารแชนเนลเฉพาะเสมอ