गतिविधि प्रोटोकॉल को समझना

गतिविधि प्रोटोकॉल संचार प्रोटोकॉल और मानक प्रोटोकॉल है जिसका उपयोग Microsoft में कई Microsoft SDK, सेवाओं और क्लाइंट में किया जाता है। इसमें Microsoft 365 Copilot, Microsoft Copilot Studio और Microsoft 365 Agents SDK शामिल हैं। गतिविधि प्रोटोकॉल एक के Activity आकार को परिभाषित करता है और कैसे संदेश, ईवेंट और इंटरैक्शन चैनल से, आपके कोड पर और बीच में हर जगह प्रवाहित होते हैं। एजेंट उपयोगकर्ताओं के साथ बातचीत करने और अन्य एजेंटों के साथ काम करने के लिए एक या अधिक चैनलों से जुड़ सकते हैं। गतिविधि प्रोटोकॉल Microsoft और तृतीय पक्ष क्लाइंट सहित आपके साथ काम कर रहे किसी भी क्लाइंट के बीच संचार प्रोटोकॉल को मानकीकृत करता है, इसलिए आपको उस चैनल के साथ कस्टम तर्क बनाने की आवश्यकता नहीं है जिसके साथ आप काम कर रहे हैं.

एक गतिविधि क्या है?

एक संरचित Activity JSON ऑब्जेक्ट है जो उपयोगकर्ता और आपके एजेंट के बीच किसी भी बातचीत का प्रतिनिधित्व करता है। गतिविधियाँ केवल पाठ आधारित संदेश नहीं हैं, इनमें विभिन्न प्रकार के इंटरैक्शन शामिल हो सकते हैं, जैसे कि उपयोगकर्ताओं का जुड़ना या छोड़ना जब यह क्लाइंट कई उपयोगकर्ताओं का समर्थन करते हैं, टाइपिंग संकेतक, फ़ाइल अपलोड, कार्ड क्रियाएं, और कस्टम ईवेंट जो डेवलपर्स द्वारा डिज़ाइन किए जाते हैं।

हर गतिविधि में मेटाडेटा शामिल होता है:

• इसे किसने भेजा (से)
• इसे किसे प्राप्त करना चाहिए (प्राप्तकर्ता)
• बातचीत का संदर्भ
• जिस चैनल से इसकी उत्पत्ति हुई
• बातचीत का प्रकार
• पेलोड डेटा

गतिविधि स्कीमा - प्रमुख गुण

यह विनिर्देश गतिविधि प्रोटोकॉल को परिभाषित करता है: गतिविधि प्रोटोकॉल - गतिविधि। गतिविधि प्रोटोकॉल में परिभाषित कुछ प्रमुख गुण हैं:

गुण	विवरण
Id	आमतौर पर चैनल द्वारा उत्पन्न होता है यदि वह किसी चैनल से आरंभ हुआ हो।
Type	प्रकार किसी गतिविधि के अर्थ को नियंत्रित करता है, उदाहरण के लिए संदेश प्रकार
ChannelID	यह उस ChannelID चैनल का संदर्भ देता है जिससे गतिविधि उत्पन्न हुई है. उदाहरण के लिए: msteams.
From	गतिविधि का प्रेषक (जो उपयोगकर्ता या एजेंट हो सकता है)
Recipient	गतिविधि का इच्छित प्राप्तकर्ता
Text	संदेश की पाठ सामग्री
Attachment	कार्ड, फ़ाइलों की छवियों जैसी समृद्ध सामग्री

गतिविधि डेटा तक पहुंचें

डेवलपर्स को ऑब्जेक्ट से क्रियाओं को पूरा करने के लिए गतिविधि के भीतर डेटा तक पहुंचने की आवश्यकता होती है TurnContext ।

आप Microsoft 365 एजेंट SDK के प्रत्येक भाषा संस्करण में एक TurnContext वर्ग पा सकते हैं:

• .NET: टर्नकॉन्टेक्स्ट
• पायथन: टर्नकॉन्टेक्स्ट
• जावास्क्रिप्ट: टर्नकॉन्टेक्स्ट

नोट

इस लेख में कोड स्निपेट C# का उपयोग करते हैं। जावास्क्रिप्ट और पायथन संस्करणों के लिए सिंटैक्स और एपीआई संरचना समान हैं।

TurnContext Microsoft 365 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);
});

वार्तालाप अपडेट

ConversationUpdate प्रकार आपके 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)
}

प्रार्थना करना

Invoke टाइप का 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)

गतिविधियाँ बनाएँ और भेजें

प्रतिक्रियाएँ भेजने के लिए, 'टर्नकॉन्टेक्स्ट' उपयोगकर्ता को प्रतिक्रियाएँ वापस भेजने के लिए कई तरीके प्रदान करता है।

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 अनुरोध भेजता है - प्रत्येक एडाप्टर के पास उस डेटा को प्राप्त करने का अपना तरीका होता है, उदाहरण के लिए, टीम्स, वनड्राइव, और इसी तरह। यह जानना भी महत्वपूर्ण है कि वे यूआरएल आम तौर पर अल्पकालिक होते हैं, और इसलिए यह न मानें कि वे वहां रहेंगे, यही कारण है कि यदि आपको बाद में इसका उल्लेख करने की आवश्यकता है तो अपने स्वयं के भंडारण पर जाना महत्वपूर्ण है।

उद्धरण

यह जानना महत्वपूर्ण है कि अनुलग्नक और उद्धरण एक ही ऑब्जेक्ट प्रकार नहीं हैं। उद्धरण क्लाइंट्स द्वारा, जैसे कि Microsoft Teams, अपने विशिष्ट तरीकों से नियंत्रित किए जाते हैं और एंटिटी प्रॉपर्टी का उपयोग करते हैं। इसके माध्यम से Activity जोड़ सकते हैं और एक नया activity.Entities.Add ऑब्जेक्ट जोड़ सकते हैं, जिसमें आपके क्लाइंट के अनुसार विशिष्ट Entity परिभाषा शामिल होती है। यह एक JSON ऑब्जेक्ट के रूप में क्रमबद्ध हो जाएगा, जिसे क्लाइंट फिर क्लाइंट में प्रस्तुति के आधार पर डिसीरियलाइज़ करता है। मूल रूप से, अनुलग्नक संदेश हैं, और उद्धरण अनुलग्नकों का संदर्भ दे सकते हैं और पेलोड में Entities भेजी Activity गई एक अन्य वस्तु हैं।

चैनल विशिष्ट विचार

Microsoft 365 एजेंट SDK को एक 'हब' के रूप में बनाया गया है जो डेवलपर्स को ऐसे एजेंट बनाने की अनुमति देता है जो किसी भी क्लाइंट के साथ काम कर सकते हैं, जिसमें हमारे द्वारा समर्थित क्लाइंट भी शामिल हैं और डेवलपर्स को उसी फ्रेमवर्क का उपयोग करके अपना स्वयं का चैनल एडाप्टर बनाने के लिए उपकरण प्रदान करते हैं। जब एजेंटों की बात आती है तो यह डेवलपर्स को चौड़ाई देता है, और ग्राहकों को उस हब से कनेक्ट करने के लिए एक्स्टेंसिबिलिटी प्रदान करता है, जो Microsoft Teams, Slack और अधिक जैसे एक या अधिक क्लाइंट हो सकते हैं।

विभिन्न चैनलों की अलग-अलग क्षमताएं और सीमाएं होती हैं, और आम ग्राहकों के साथ काम करते समय निम्नलिखित विचारों का सारांश है।

आप उस चैनल की जांच कर सकते हैं जिससे आपको गतिविधि प्राप्त हुई है, इसके लिए channelId में Activity गुण का निरीक्षण करें।

चैनलों में विशिष्ट डेटा शामिल होता है जो सभी चैनलों पर सामान्य Activity पेलोड के अनुरूप नहीं होता है, और इसे टर्नकॉन्टेक्स्ट से एक्सेस किया जा सकता है।Activity.ChannelData और विशेष रूप से इसे आपके कोड में उपयोग के लिए चर में कास्ट करना।

माइक्रोसॉफ्ट टीमें

• उन्नत सुविधाओं के साथ समृद्ध अनुकूली कार्ड का समर्थन करता है
• संदेश अद्यतन और विलोपन का समर्थन करता है
• Teams की सुविधाओं के लिए विशेष चैनल डेटा है जैसे कि उल्लेख, मीटिंग जानकारी, आदि।
• कार्य मॉड्यूल के लिए गतिविधियों को लागू करने का समर्थन करता है

Microsoft 365 Copilot

• मुख्य रूप से संदेश गतिविधियों पर केंद्रित
• प्रतिक्रियाओं में उद्धरणों और संदर्भों का समर्थन करता है
• स्ट्रीमिंग प्रतिक्रियाओं की आवश्यकता है
• रिच कार्ड/अनुकूली कार्ड के लिए सीमित समर्थन

वेबचैट/डायरेक्टलाइन

वेब चैट एक HTTP प्रोटोकॉल है जिसका उपयोग एजेंटों के लिए HTTPS पर बात करने के लिए किया जाता है

• सभी प्रकार की गतिविधि के लिए पूर्ण समर्थन
• कस्टम चैनल डेटा का समर्थन करता है

तृतीय पक्ष चैनल

इनमें स्लैक, फेसबुक और बहुत कुछ शामिल हैं।

• कुछ गतिविधि प्रकारों के लिए सीमित समर्थन हो सकता है
• कार्ड रेंडरिंग अलग या असमर्थित हो सकती है
• हमेशा विशिष्ट चैनल दस्तावेज़ीकरण की जाँच करें