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

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

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

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

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

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

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

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

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

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

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

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

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

उद्धरण

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

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

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

विभिन्न चैनलों की अलग-अलग क्षमताएं और सीमाएं होती हैं।

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

चैनलों में विशिष्ट डेटा शामिल होता है जो सभी चैनलों पर सामान्य Activity पेलोड के अनुरूप नहीं होता है। आप इस डेटा को अपने कोड में उपयोग के लिए चर में कास्ट करके संपत्ति से एक्सेस TurnContext.[Activity.ChannelData](/dotnet/api/microsoft.agents.core.models.activity.channeldata) कर सकते हैं।

निम्नलिखित अनुभाग आम ग्राहकों के साथ काम करते समय विचारों को संक्षेप में प्रस्तुत करते हैं।

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

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

Microsoft 365 Copilot

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

Web Chat/DirectLine

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

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

गैर-Microsoft चैनल

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

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

अगले कदम

• AgentApplication के बारे में जानें