Processar mensagens

Ao utilizar o SDK do Agent 365, o seu agente pode processar eventos de atividade da plataforma, como instalação e desinstalação, e enviar várias mensagens discretas num único turno. Este artigo aborda os principais padrões para responder aos utilizadores e mantê-los informados enquanto o seu agente processa pedidos.

Processar eventos de instalação e desinstalação de agentes

Quando um utilizador instala ou desinstala o seu agente no Teams ou noutros canais alojados do Agent 365, a plataforma envia uma atividade InstallationUpdate (também referida como o evento agentInstanceCreated). O seu agente pode processar estes eventos para enviar uma mensagem de boas-vindas quando instalado e uma mensagem de despedida quando desinstalado.

Ação Descrição
add O utilizador instala o agente
remove O utilizador desinstala o agente

Ao contrário dos processadores de notificação, o processador InstallationUpdate não requer autenticação porque o evento de instalação ou desinstalação é acionado antes ou depois de o utilizador ter uma sessão ativa.

Registar o processador de instalação e desinstalação

Registe um processador de atividade para o tipo de atividade InstallationUpdate na inicialização do seu agente:

@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 é uma cadeia definida como "add" quando instala o agente ou "remove" quando o desinstala. Activity.from_property é uma instância de ChannelAccount que contém a identidade do utilizador.

Enviar várias mensagens

Os agentes do Agent 365 podem enviar várias mensagens discretas em resposta a um único pedido do utilizador. Para tal, chame SendActivityAsync (.NET), send_activity (Python) ou sendActivity (JavaScript) várias vezes num único turno.

Importante

O Teams não suporta respostas de transmissão em fluxo para identidades por meio de agentes. O SDK deteta a identidade por meio de agentes e coloca o fluxo em memória intermédia numa única mensagem. Utilize SendActivityAsync, send_activity ou sendActivity diretamente para enviar mensagens imediatas e discretas ao utilizador.

Os exemplos seguintes demonstram o padrão ao enviar uma mensagem de confirmação imediata antes da resposta do LLM:

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

O exemplo demonstra este padrão em on_message (host_agent_server.py) ao enviar uma confirmação imediata antes da resposta do LLM.

Cada chamada a sendActivity, send_activity ou SendActivityAsync cria uma mensagem distinta. Pode chamar quantas vezes for necessário para enviar atualizações de progresso, resultados parciais ou uma resposta final.

Indicadores de escrita

Os indicadores de escrita mostram uma animação de progresso ... no Teams:

  • Têm um tempo limite visual incorporado de cerca de 5 segundos e este deve ser atualizado num ciclo aproximadamente a cada quatro segundos.
  • Só são visíveis em conversas entre duas pessoas e em conversas de grupos pequenos, mas não em canais.

O agente envia indicadores de escrita num ciclo de aproximadamente quatro segundos para manter a animação ... ativa enquanto o LLM processa o pedido:

# 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