Viestien käsitteleminen

Agent 365 SDK:n avulla agentti voi käsitellä ympäristön toimintatapahtumia, kuten asennustapahtumia ja asennuksen poistotapahtumia, sekä lähettää useita erillisiä viestejä yhden vuoron aikana. Tämä artikkeli esittelee keskeiset mallit, joiden avulla vastataan käyttäjille ja pidetään käyttäjät ajan tasalla agentin käsitellessä pyyntöjä.

Agentin asennustapahtumien ja asennuksen poistotapahtumien käsitteleminen

Kun käyttäjä asentaa agentin tai poistaa agentin asennuksen Teamsissa tai muissa Agent 365:n isännöimissä kanavissa, ympäristö lähettää InstallationUpdate-aktiviteetin (kutsutaan myös agentInstanceCreated-tapahtumaksi). Agentti voi käsitellä nämä tapahtumat lähettämällä tervetuloviestin asennuksen yhteydessä ja jäähyväisviestin poiston yhteydessä.

Toimi	Description
add	Käyttäjä asentaa agentin
remove	Käyttäjä poistaa agentin asennuksen

Toisin kuin ilmoitusten käsittelijät, InstallationUpdate-käsittelijä ei vaadi todennusta, koska asennustapahtuma ja asennuksen poistotapahtuma käynnistyy ennen kuin käyttäjällä on aktiivinen istunto tai sen jälkeen.

Asennuksen ja asennuksen poiston käsittelijän rekisteröiminen

Rekisteröi aktiviteettien käsittelijä InstallationUpdate-aktiviteettityypille agentin alustuksessa:

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 on merkkijono, jonka arvoksi on määritetty "add", kun agentti asennetaan, ja "remove", kun agentin asennus poistetaan. Activity.from_property on ChannelAccount-esiintymä, joka sisältää käyttäjätiedot.

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 on luettelointi, joka sisältää aktiivisuustyypin vakioita, jotka on tuotu kohteesta @microsoft/agents-activity. Activity.action on merkkijono, jonka arvoksi on määritetty 'add', kun agentti asennetaan, ja 'remove', kun agentin asennus poistetaan.

.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 on aktiviteettityypin vakioiden luettelointi. InstallationUpdateActionTypes tuo Add- ja Remove-vakion aktiviteetin toiminnon vertailua varten.

Muistiinpano

Rekisteröi käsittelijä kaksi kertaa .NET:lle. Kerran kohteelle isAgenticOnly: true tuotantoa varten Agent 365:n liikenteelle vaihtoehtoisten agenttien todennuksen käsittelijöiden kanssa ja kerran kohteelle isAgenticOnly: false paikallista testausta varten agenttien testausalustan tai verkkokeskustelun kanssa.

Useiden viestien lähettäminen

Agent 365 -agentit voivat lähettää useita erillisiä viestejä vastauksena yhteen käyttäjäkehotteeseen. Tätä varten kutsutaan kohdetta SendActivityAsync (.NET), send_activity (Python) tai sendActivity (JavaScript) useita kertoja yhden vuoron aikana.

Tärkeää

Teams ei tue suoratoistovastauksia agentin käyttäjätietoja varten. SDK tunnistaa agentin käyttäjätiedot ja puskuroi viestivirran yhdeksi viestiksi. Käytä kohdetta SendActivityAsync, send_activity tai sendActivity suoraan lähettääksesi välittömiä, erillisiä viestejä käyttäjälle.

Seuraavat esimerkit havainnollistavat toimintatapaa, jossa käyttäjälle lähetetään välitön kuittaus ennen LLM-vastausta:

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)

Esimerkki osoittaa tämän mallin kohteessa on_message (host_agent_server.py) lähettämällä välittömän kuittauksen ennen LLM:n vastausta.

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);

Esimerkki havainnollistaa tämän mallin viestiaktiviteetin käsittelijässä (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);

Esimerkki havainnollistaa tämän mallin kohteessa OnMessageAsync (MyAgent.cs).

Jokainen kutsu kohteeseen sendActivity, send_activity tai SendActivityAsync luo erillisen viestin. Voit kutsua sitä niin monta kertaa kuin edistymispäivitysten, osittaisten tulosten ja lopullisen vastauksen lähettäminen vaatii.

Kirjoitusilmaisimet

Kirjoitusilmaisimet näyttävät edistymisanimaation ... Teamsissa:

• Niissä on valmis visuaalinen aikakatkaisu (noin 5 sekuntia), joka täytyy päivittää silmukassa noin neljän sekunnin välein.
• Kirjoitusilmaisimet ovat näkyvissä vain kahdenkeskisissä keskusteluissa ja pienryhmäkeskusteluissa, eivät kanavissa.

Agentti lähettää kirjoitusilmaisimia silmukassa noin neljän sekunnin välein pitääkseen animaation ... käynnissä samalla kun LLM käsittelee pyyntöä:

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) { }
}