Zpracování zpráv

Použitím Agent 365 SDK může váš agent zpracovávat události aktivity platformy, jako je instalace a odinstalace, a posílat více samostatných zpráv během jedné interakce. Tento článek se zabývá klíčovými postupy, jak odpovídat uživatelům a informovat je během zpracování požadavků vaším agentem.

Zpracování událostí instalace a odinstalace agenta

Když uživatel nainstaluje nebo odinstaluje vašeho agenta v Teams nebo jiných kanálech hostovaných Agentem 365, platforma odešle aktivitu InstallationUpdate (také označovanou jako událost agentInstanceCreated). Váš agent může tyto události zpracovat a při instalaci odeslat uvítací zprávu, při odinstalaci zprávu na rozloučenou.

Akce Popis
add Uživatel nainstaluje agenta
remove Uživatel odinstaluje agenta

Na rozdíl od obslužných rutin oznámení obslužná rutina InstallationUpdate nevyžaduje ověření, protože událost instalace nebo odinstalace se spouští před zahájením nebo po ukončení aktivní relace uživatele.

Registrace obslužné rutiny instalace a odinstalace

Zaregistrujte obslužnou rutinu pro typ aktivity InstallationUpdate v inicializaci vašeho agenta:

@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 je řetězec nastavený na "add" při instalaci agenta nebo na "remove" při jeho odinstalaci. Activity.from_property je instance ChannelAccount, která obsahuje identitu uživatele.

Odesílání více zpráv

Agenti Agent 365 mohou odesílat více jednotlivých zpráv v odpovědi na jeden uživatelský prompt. K tomu zavolejte SendActivityAsync (.NET), send_activity (Python) nebo sendActivity (JavaScript) několikrát v rámci jednoho kroku.

Důležité

Teams nepodporuje streamování odpovědí pro agentické identity. SDK detekuje agentickou identitu a ukládá stream do jedné zprávy. Použijte SendActivityAsync, send_activity nebo sendActivity přímo k odeslání okamžitých, samostatných zpráv uživateli.

Následující příklady ukazují tento vzorec tím, že před odpovědí LLM je zasláno okamžité potvrzení:

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

Ukázka tento vzor demonstruje v on_message (host_agent_server.py) tím, že okamžitě pošle potvrzení před odpovědí LLM.

Každé volání sendActivity, send_activity nebo SendActivityAsync vytvoří samostatnou zprávu. Můžete ji volat tolikrát, kolikrát je potřeba, abyste zaslali aktualizace průběhu, dílčí výsledky nebo konečnou odpověď.

Indikátory psaní

Indikátory psaní ukazují animaci postupu ... v Teams:

  • Mají vestavěný vizuální časový limit přibližně 5 sekund, který je třeba pravidelně obnovovat přibližně každé čtyři sekundy.
  • Jsou viditelné pouze v chatech jeden na jednoho a malých skupinových chatech, ne v kanálech.

Agent pravidelně každé čtyři sekundy posílá indikátory psaní, aby udržel animaci ... aktivní, zatímco LLM zpracovává požadavek:

# 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
  • Last updated on