Manipular mensagens

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

Tratar eventos de instalação e desinstalação do agente

Quando um usuário instala ou desinstala seu agente no Teams ou em outros canais hospedados pelo Agent 365, a plataforma envia uma atividade InstallationUpdate (também conhecida como evento agentInstanceCreated). Seu agente pode tratar esses eventos para enviar uma mensagem de boas-vindas quando for instalado e uma mensagem de despedida quando for desinstalado.

Para descrição
add O usuário instala o agente
remove O usuário desinstala o agente

Ao contrário dos manipuladores de notificações, o handler InstallationUpdate não requer autenticação porque o evento de instalação ou desinstalação é acionado antes ou depois de o usuário ter uma sessão ativa.

Registre o manipulador de instalação e desinstalação

Registre um manipulador 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 string definida como "add" quando você instala o agente ou "remove" quando você o desinstala. Activity.from_property é uma instância de ChannelAccount que contém a identidade do usuário.

Envio de várias mensagens

Os agentes do Agent 365 podem enviar várias mensagens distintas em resposta a um único prompt do usuário. Para isso, chame SendActivityAsync (.NET), send_activity (Python) ou sendActivity (JavaScript) várias vezes em um único turno.

Importante

O Teams não suporta respostas em streaming para identidades do agente. O SDK detecta a identidade do agente e armazena em buffer o fluxo em uma única mensagem. Use SendActivityAsync, send_activity ou sendActivity diretamente para enviar mensagens imediatas e discretas ao usuário.

Os exemplos a seguir ilustram o padrão ao enviar um reconhecimento imediato 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 esse padrão em on_message (host_agent_server.py) ao enviar uma confirmação imediata antes da resposta LLM.

Cada chamada para sendActivity, send_activity ou SendActivityAsync cria uma mensagem separada. Você pode chamá-lo quantas vezes for necessário para enviar atualizações de progresso, resultados parciais ou uma resposta final.

Indicadores de digitação

Indicadores de digitação exibem uma animação de progresso ... no Teams:

  • Eles têm um tempo visual embutido de cerca de 5 segundos e precisam ser atualizados em um loop a cada quatro segundos.
  • Elas só são visíveis em conversas individuais e em pequenos grupos, não em canais.

O agente envia indicadores de digitação em um loop a cada quatro segundos para manter a animação ... ativa enquanto a LLM processa a solicitação:

# 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