Manipular mensagens

Importante

Você precisa fazer parte do programa de prévia Frontier para obter acesso antecipado ao Microsoft Agent 365. A Frontier conecta você diretamente às mais recentes inovações de IA da Microsoft. As versões preliminares da Frontier estão sujeitas aos termos de versão preliminar existentes dos contratos de cliente. Como esses recursos ainda estão em desenvolvimento, sua disponibilidade e capacidades podem mudar ao longo do tempo.

Usando o SDK do Agent 365, seu agente pode lidar com eventos de atividade de plataforma, como instalar e desinstalar, 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 o agente processa solicitações.

Manipular 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 Agente 365, a plataforma envia uma InstallationUpdate atividade (também conhecida como evento agentInstanceCreated ). Seu agente pode lidar com esses eventos para enviar uma mensagem de boas-vindas quando instalado e uma mensagem de despedida quando desinstalado.

Ação	Descrição
add	O usuário instala o agente
remove	O usuário desinstala o agente

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

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

Registre um manipulador de atividades para o InstallationUpdate tipo de atividade na inicialização do agente:

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

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 é uma enumeração de constantes de tipo de atividade importadas de @microsoft/agents-activity. Activity.action é uma string definida como 'add' quando você instala o agente ou 'remove' quando o desinstala.

.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 é uma enumeração de constantes de tipo de atividade. InstallationUpdateActionTypes fornece o Add e as constantes Remove para comparar a ação de atividade.

Observação

Para .NET, registre o manipulador duas vezes — uma vez com isAgenticOnly: true para o tráfego de produção do Agente 365 com manipuladores de autenticação agentic opcionais, e uma vez com isAgenticOnly: false para testes locais com o Agents Playground ou o WebChat.

Enviar várias mensagens

Agentes do Agente 365 podem enviar várias mensagens discretas em resposta a um único prompt de usuário. Para fazer isso, chame SendActivityAsync (.NET), send_activity (Python) ou sendActivity (JavaScript) várias vezes em um único turno.

Importante

O Teams não oferece suporte a respostas de streaming para identidades agêncicas. O SDK detecta a identidade do agente e armazena em buffer o fluxo em uma única mensagem. Use SendActivityAsync, send_activityou sendActivity diretamente para enviar mensagens imediatas e discretas para o usuário.

Os exemplos a seguir demonstram o padrão enviando uma confirmação imediata antes da resposta 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)

O exemplo demonstra esse padrão em on_message (host_agent_server.py) ao enviar uma confirmação imediata antes da resposta 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);

O exemplo demonstra esse padrão no manipulador de atividades de mensagem (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);

O exemplo demonstra esse padrão em OnMessageAsync (MyAgent.cs).

Cada chamada para sendActivity, send_activityou SendActivityAsync cria uma mensagem separada. Você pode chamá-lo quantas vezes forem necessárias 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 de espera visual embutido de cerca de 5 segundos e que deve ser renovado em um loop a cada quatro segundos.
• Eles são visíveis apenas em conversas individuais e pequenos grupos de conversa, 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:

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