Obsługa wiadomości

Korzystając z SDK Agenta 365, twój agent może obsługiwać zdarzenia aktywności platformy, takie jak instalacja i deinstalacja, oraz wysyłać wiele oddzielnych wiadomości w ciągu jednej tury. Ten artykuł omawia kluczowe wzorce odpowiadania użytkownikom i informowania ich podczas przetwarzania zgłoszeń przez Twojego agenta.

Obsługa zdarzeń instalacji i deinstalacji agenta

Gdy użytkownik instaluje lub odinstaluje Twojego agenta w Teams lub innych kanałach hostowanych przez Agenta 365, platforma wysyła aktywność InstallationUpdate (nazywaną także zdarzeniem agentInstanceCreated). Agent może obsługiwać te zdarzenia, wysyłając wiadomość powitalną po instalacji oraz pożegnalną po odinstalowaniu.

Akcja	Podpis
add	Użytkownik instaluje agenta
remove	Użytkownik odinstalowuje agenta

W przeciwieństwie do obsługi powiadomień, obsługa InstallationUpdate nie wymaga uwierzytelniania, ponieważ zdarzenie instalacji lub odinstalowania uruchamia się przed lub po aktywnej sesji użytkownika.

Zarejestruj procedurę obsługi instalacji i odinstalowania

Zarejestruj procedurę obsługi aktywności dla typu aktywności InstallationUpdate podczas inicjalizacji agenta:

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 jest ciągiem znaków ustawianym na "add" podczas instalowania agenta lub na "remove" podczas jego odinstalowywania. Activity.from_property jest instancją ChannelAccount zawierającą tożsamość użytkownika.

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 to wyliczenie stałych typu aktywności importowanych z @microsoft/agents-activity. Activity.action jest ciągiem znaków ustawianym na 'add' podczas instalowania agenta lub na 'remove' podczas jego odinstalowywania.

.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 to wyliczenie stałych typów aktywności. InstallationUpdateActionTypes dostarcza oraz AddRemove stałe do porównywania akcji aktywności.

Notatka

Dla .NET zarejestruj procedurę obsługi dwukrotnie — raz z isAgenticOnly: true dla ruchu produkcyjnego Agent 365 z opcjonalnymi procedurami obsługi uwierzytelniania agentów, oraz raz z isAgenticOnly: false dla testów lokalnych z Agents Playground lub WebChat.

Wysyłanie wielu oddzielnych wiadomości

Agenty Agent 365 mogą wysyłać wiele odrębnych wiadomości w odpowiedzi na pojedyncze polecenie użytkownika. Aby to zrobić, wywołaj SendActivityAsync (.NET), send_activity (Python) lub sendActivity (JavaScript) wielokrotnie w jednej turze.

Ważne

Teams nie obsługuje strumieniowych odpowiedzi dla tożsamości agentycznej. SDK wykrywa tożsamość agentyczną i buforuje strumień w pojedynczą wiadomość. Użyj SendActivityAsync, send_activity lub sendActivity bezpośrednio, aby wysłać natychmiastowe, oddzielne wiadomości do użytkownika.

Poniższe przykłady prezentują ten wzorzec, wysyłając natychmiastowe potwierdzenie przed odpowiedzią 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)

Przykład demonstruje ten wzorzec w on_message (host_agent_server.py), wysyłając natychmiastowe potwierdzenie przed odpowiedzią 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);

Przykład demonstruje ten wzorzec w obsłudze aktywności wiadomości (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);

Przykład demonstruje ten wzorzec w OnMessageAsync (MyAgent.cs).

Każde wywołanie sendActivity, send_activity lub SendActivityAsync tworzy osobną wiadomość. Możesz wywołać tę funkcję dowolną liczbę razy, aby wysłać aktualizacje postępów, wyniki częściowe lub odpowiedź końcową.

Wskaźniki pisania

Wskaźniki pisania pokazują ... animację postępu w Teams:

• Mają wbudowany wizualny upływający czas trwający około 5 sekund, który należy odświeżać w pętli co około cztery sekundy.
• Są widoczne tylko w czatach jeden na jeden i czatach małych grup, nie w kanałach.

Agent wysyła wskaźniki pisania w pętli co około cztery sekundy, aby animacja ... pozostała widoczna podczas przetwarzania żądania przez 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) { }
}