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

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

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

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

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

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

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

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

@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 , содержащий личность пользователя.

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

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

Это важно

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

Следующие примеры демонстрируют эту закономерность, отправляя немедленное подтверждение перед ответом 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)

Выборка демонстрирует этот паттерн в on_message (host_agent_server.py), отправляя немедленное подтверждение перед ответом LLM.

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

Индикаторы типизации

Индикаторы ввода показывают ... анимацию прогресса в Teams:

  • У них встроенный визуальный тайм-аут около 5 секунд, который нужно обновлять по кругу примерно каждые четыре секунды.
  • Они видны только в индивидуальных и небольших групповых чатах, а не в каналах.

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

# 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