संदेशों को संभालना

Agent 365 SDK का उपयोग करके, आपका एजेंट की स्थापना और स्थापना रद्द करने जैसी प्लेटफ़ॉर्म गतिविधि घटनाओं को संभाल सकता है, और वार्तालाप के एक दौर में कई असतत संदेश भेज सकता है। यह आलेख उपयोगकर्ताओं को प्रत्युत्तर देने और उन्हें सूचित रखने के लिए, आपके एजेंट द्वारा अनुरोधों को संसाधित करते समय अपनाए जाने वाले प्रमुख पैटर्न को प्रस्तुत करता है।

एजेंट स्थापना और स्थापना रद्द की घटनाओं को संभालें

जब कोई उपयोगकर्ता आपके एजेंट को Teams या अन्य Agent 365 द्वारा होस्ट किए गए चैनलों में स्थापना या स्थापना रद्द करता है, तो प्लेटफ़ॉर्म एक InstallationUpdate गतिविधि भेजता है (जिसे agentInstanceCreated ईवेंट भी कहा जाता है)। आपका एजेंट स्थापित होने पर स्वागत संदेश और स्थापना रद्द करने पर विदाई संदेश भेजने के लिए इन घटनाओं को संभाल सकता है।

कार्यवाही	विवरण
add	उपयोगकर्ता एजेंट स्थापित करता है
remove	उपयोगकर्ता एजेंट की स्थापना रद्द करता है

सूचना हैंडलर के विपरीत, InstallationUpdate हैंडलर को प्रमाणीकरण की आवश्यकता नहीं होती है क्योंकि स्थापना या स्थापना रद्द इवेंट उपयोगकर्ता के सक्रिय सत्र से पहले या बाद में ट्रिगर होते हैं।

अपने एजेंट में स्थापना हैंडलर और स्थापना रद्द हैंडलर रजिस्टर करें

अपने एजेंट के प्रारंभन में InstallationUpdate गतिविधि प्रकार के लिए एक गतिविधि हैंडलर पंजीकृत करें:

Python

@agent_app.activity("installationUpdate")
async def on_installation_update(context: TurnContext, state: TurnState):
    action = context.activity.action
    from_prop = context.activity.from_property
    logger.info(
        "InstallationUpdate received — Action: '%s', DisplayName: '%s', UserId: '%s'",
        action or "(none)",
        getattr(from_prop, "name", "(unknown)") if from_prop else "(unknown)",
        getattr(from_prop, "id", "(unknown)") if from_prop else "(unknown)",
    )
    if action == "add":
        await context.send_activity("Thank you for hiring me! Looking forward to assisting you in your professional journey!")
    elif action == "remove":
        await context.send_activity("Thank you for your time, I enjoyed working with you.")

Activity.actionएक स्ट्रिंग है जिसे "add"पर सेट किया जाता है जब आप एजेंट को स्थापित करते हैं या"remove"पर जब आप इसकी स्थापना रद्द करते हैं। Activity.from_property एक ChannelAccount इंस्टेंस है जिसमें उपयोगकर्ता की पहचान होती है।

JavaScript

// In your agent class constructor:
this.onActivity(ActivityTypes.InstallationUpdate, async (context: TurnContext, state: TurnState) => {
    await this.handleInstallationUpdateActivity(context, state);
});

// Handler method:
async handleInstallationUpdateActivity(context: TurnContext, state: TurnState): Promise<void> {
    const from = context.activity?.from;
    console.log(`InstallationUpdate received — Action: '${context.activity.action ?? "(none)"}', DisplayName: '${from?.name ?? "(unknown)"}', UserId: '${from?.id ?? "(unknown)"}'`);

    if (context.activity.action === 'add') {
        await context.sendActivity('Thank you for hiring me! Looking forward to assisting you in your professional journey!');
    } else if (context.activity.action === 'remove') {
        await context.sendActivity('Thank you for your time, I enjoyed working with you.');
    }
}

ActivityTypes एक एनम है जिसमें @microsoft/agents-activity से आयात किए गए गतिविधि प्रकार स्थिरांक होते हैं। Activity.actionएक स्ट्रिंग है जिसे 'add'पर सेट किया जाता है जब आप एजेंट को स्थापित करते हैं या'remove'पर जब आप इसकी स्थापना रद्द करते हैं।

.NET

// In your agent class constructor:
OnActivity(ActivityTypes.InstallationUpdate, OnInstallationUpdateAsync, isAgenticOnly: true, autoSignInHandlers: agenticInstallHandlers);
OnActivity(ActivityTypes.InstallationUpdate, OnInstallationUpdateAsync, isAgenticOnly: false);

// Handler method:
protected async Task OnInstallationUpdateAsync(ITurnContext turnContext, ITurnState turnState, CancellationToken cancellationToken)
{
    _logger?.LogInformation(
        "InstallationUpdate received — Action: '{Action}', DisplayName: '{Name}', UserId: '{Id}'",
        turnContext.Activity.Action ?? "(none)",
        turnContext.Activity.From?.Name ?? "(unknown)",
        turnContext.Activity.From?.Id ?? "(unknown)");

    if (turnContext.Activity.Action == InstallationUpdateActionTypes.Add)
    {
        await turnContext.SendActivityAsync(MessageFactory.Text("Thank you for hiring me! Looking forward to assisting you in your professional journey!"), cancellationToken);
    }
    else if (turnContext.Activity.Action == InstallationUpdateActionTypes.Remove)
    {
        await turnContext.SendActivityAsync(MessageFactory.Text("Thank you for your time, I enjoyed working with you."), cancellationToken);
    }
}

ActivityTypes गतिविधि प्रकार स्थिरांक का एक enum है। InstallationUpdateActionTypes गतिविधि क्रिया की तुलना करने के लिए Add और Remove स्थिरांक प्रदान करता है।

नोट

.NET के लिए, हैंडलर को दो बार पंजीकृत करें — एक बार isAgenticOnly: true (प्रोडक्शन Agent 365 ट्रैफ़िक के लिए, वैकल्पिक agentic auth हैंडलर के साथ), और एक बार isAgenticOnly: false (स्थानीय परीक्षण के लिए Agents Playground या WebChat के साथ)।

एकाधिक संदेश भेजें

Agent 365 एजेंट एक एकल उपयोगकर्ता प्रॉम्प्ट के प्रत्युत्तर में कई अलग-अलग संदेश भेज सकते हैं। ऐसा करने के लिए, एक ही टर्न में SendActivityAsync (.NET), send_activity (Python), या sendActivity (JavaScript) को एकाधिक कॉल करें।

महत्त्वपूर्ण

Teams एजेंटिक पहचान के लिए स्ट्रीमिंग प्रत्युत्तर का समर्थन नहीं करता है। SDK एजेंटिक पहचान का पता लगाता है और स्ट्रीम को एक ही संदेश में बफ़र करता है। SendActivityAsync, send_activity, या sendActivity का सीधे उपयोग करें ताकि उपयोगकर्ता को तुरंत, अलग-अलग संदेश भेजे जा सकें।

निम्नलिखित उदाहरण इस पैटर्न को प्रदर्शित करते हैं, जिसमें LLM प्रत्युत्तर से पहले तत्काल पावती भेजी जाती है:

Python

@agent_app.activity("message")
async def on_message(context: TurnContext, state: TurnState):
    # Message 1: immediate ack — reaches the user right away
    await context.send_activity("Got it — working on it…")

    # ... LLM processing ...

    # Message 2: the LLM response
    await context.send_activity(response)

नमूना इस पैटर्न को on_message (host_agent_server.py) में प्रदर्शित करता है, जिसमें LLM प्रत्युत्तर से पहले तुरंत पुष्टि भेजी जाती है।

JavaScript

// Message 1: immediate ack — reaches the user right away
await context.sendActivity('Got it — working on it…');

// ... LLM processing ...

// Message 2: the LLM response
await context.sendActivity(modelResponse);

नमूना संदेश गतिविधि हैंडलर (agent.ts) में इस पैटर्न को प्रदर्शित करता है।

.NET

// Message 1: immediate ack — reaches the user right away
await turnContext.SendActivityAsync(MessageFactory.Text("Got it — working on it…"), cancellationToken);

// ... LLM processing ...

// Message 2: the LLM response (via StreamingResponse, buffered into one message for Teams agentic)
await turnContext.StreamingResponse.EndStreamAsync(cancellationToken);

नमूना इस पैटर्न को OnMessageAsync (MyAgent.cs)में प्रदर्शित करता है।

sendActivity, send_activity या SendActivityAsync में से प्रत्येक को कॉल करने पर एक अलग संदेश बनता है। आप प्रगति अपडेट, आंशिक परिणाम, या अंतिम उत्तर भेजने के लिए इसे आवश्यकतानुसार जितनी बार चाहें कॉल कर सकते हैं।

टाइपिंग इंडिकेटर

टाइपिंग संकेतक Teams में ... प्रगति एनीमेशन दिखाते हैं:

• इनमें लगभग 5 सेकंड का अंतर्निहित विज़ुअल टाइमआउट होता है, जिसे हर चार सेकंड में एक लूप में रीफ्रेश करना आवश्यक है।
• वे केवल एक-पर-एक चैट और छोटे समूह चैट में दिखाई देते हैं; चैनलों में नहीं।

एजेंट हर चार सेकंड में टाइपिंग संकेतक भेजता है ताकि LLM के अनुरोध को संसाधित करते समय ... एनीमेशन सक्रिय रहे।

Python

# Message 1: immediate ack — reaches the user right away
await context.send_activity("Got it — working on it…")

# Send typing indicator immediately (awaited so it arrives before the LLM call starts).
await context.send_activity(Activity(type="typing"))

# Background loop refreshes the "..." animation every ~4s (it times out after ~5s).
async def _typing_loop():
    try:
        while True:
            await asyncio.sleep(4)
            await context.send_activity(Activity(type="typing"))
    except asyncio.CancelledError:
        pass  # Expected on cancel.

typing_task = asyncio.create_task(_typing_loop())
try:
    response = await agent.process_user_message(...)
    await context.send_activity(response)
finally:
    typing_task.cancel()
    try:
        await typing_task
    except asyncio.CancelledError:
        pass

JavaScript

let typingInterval: ReturnType<typeof setInterval> | undefined;
const startTypingLoop = () => {
    typingInterval = setInterval(async () => {
        await context.sendActivity(Activity.fromObject({ type: ActivityTypes.Typing }));
    }, 4000);
};
const stopTypingLoop = () => { clearInterval(typingInterval); };

startTypingLoop();
try {
    // ... LLM processing ...
} finally {
    stopTypingLoop();
}

.NET

// Typing indicator loop — refreshes every ~4s for long-running operations.
using var typingCts = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken);
var typingTask = Task.Run(async () =>
{
    try
    {
        while (!typingCts.IsCancellationRequested)
        {
            await Task.Delay(TimeSpan.FromSeconds(4), typingCts.Token);
            await turnContext.SendActivityAsync(Activity.CreateTypingActivity(), typingCts.Token);
        }
    }
    catch (OperationCanceledException) { /* expected on cancel */ }
}, typingCts.Token);

try { /* ... do work ... */ }
finally
{
    typingCts.Cancel();
    try { await typingTask; } catch (OperationCanceledException) { }
}