Обработка сообщений

С помощью пакета SDK Agent 365 агент может обрабатывать события действий платформы, такие как установка и удаление, а также отправлять несколько отдельных сообщений в рамках одного этапа разговора. В этой статье рассматриваются основные подходы к взаимодействию с пользователями и информированию их о ходе обработки запросов агентом.

Обработка событий установки и удаления агента

Когда пользователь устанавливает или удаляет ваш агент в Teams или других каналах, размещенных на платформе Agent 365, платформа отправляет действие InstallationUpdate (также называемое событием agentInstanceCreated). Ваш агент может обрабатывать эти события, отправляя приветственное сообщение при установке и прощальное сообщение при удалении.

Действие	Description
add	Пользователь устанавливает агент
remove	Пользователь удаляет агент

В отличие от обработчиков уведомлений, обработчик InstallationUpdate не требует проверки подлинности, так как событие установки или удаления агента происходит до того, как у пользователя появляется активный сеанс, или после его завершения.

Регистрация обработчика установки и удаления

Зарегистрируйте обработчик действий для типа действия InstallationUpdate в инициализации вашего агента:

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 имеет строковое значение "add" при установке агента или "remove" при его удалении. Activity.from_property — это экземпляр ChannelAccount, содержащий идентификатор пользователя.

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 — это перечисление констант типов действий, импортированных из @microsoft/agents-activity. Activity.action имеет строковое значение 'add' при установке агента или 'remove' при его удалении.

.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 — это перечисление констант типов действий. InstallationUpdateActionTypes предоставляет константы Add и Remove для сравнения значения свойства действия.

Примечание

Для .NET зарегистрируйте обработчик дважды: один раз с параметром isAgenticOnly: true для рабочего трафика Agent 365 с возможностью использования обработчиков агентной проверки подлинности, и один раз с параметром isAgenticOnly: false для локального тестирования на тестовой площадке агентов или WebChat.

Отправка нескольких сообщений

Агенты Agent 365 могут отправлять несколько отдельных сообщений в ответ на один пользовательский запрос. Для этого вызовите SendActivityAsync (.NET), send_activity (Python) или sendActivity (JavaScript) несколько раз в рамках одного этапа разговора.

Важно

Teams не поддерживает потоковую передачу ответов для агентных удостоверений. Пакет SDK обнаруживает агентное удостоверение и буферизирует поток в одно сообщение. Используйте SendActivityAsync, send_activity или sendActivity, чтобы сразу отправлять пользователю отдельные сообщения.

В следующих примерах показано, как использовать этот подход, отправляя пользователю подтверждение получения запроса до ответа языковой модели.

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)

В примере показано, как реализовать этот подход в методе on_message (host_agent_server.py): перед ответом языковой модели пользователю сразу отправляется подтверждение получения запроса.

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

В примере показано, как реализовать этот подход в обработчике действий сообщений (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);

В примере показано, как реализовать этот подход в методе OnMessageAsync (MyAgent.cs).

Каждый вызов sendActivity, send_activity или SendActivityAsync создает отдельное сообщение. Вы можете вызывать эту функцию столько раз, сколько потребуется, чтобы отправлять обновления хода выполнения, частичные результаты или окончательный ответ.

Индикаторы ввода

Индикаторы ввода отображают анимацию хода выполнения ... в Teams:

• Индикаторы отображаются примерно в течение пяти секунд, поэтому их необходимо обновлять в цикле примерно каждые четыре секунды.
• Они видны только в индивидуальных и малых групповых чатах, а не в каналах.

Агент отправляет индикаторы ввода в цикле примерно каждые четыре секунды, чтобы во время обработки запроса языковой моделью продолжала отображаться анимация ...:

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