AgentApplication в пакете SDK агентов Microsoft 365

AgentApplication является центральным шаблоном агента, построенного с помощью пакета SDK агентов. AgentApplication является точкой входа для всей входящей активности, включая сообщения от пользователей, события жизненного цикла беседы, взаимодействия с адаптивной карточкой, обратные вызовы OAuth.

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

Как работает AgentApplication

У каждого агента есть жизненный цикл, который начинается, когда канал (Microsoft Teams, служба Bot или пользовательский клиент) доставляет активность на конечную точку вашего агента. AgentApplication находится в центре этого жизненного цикла:

Channel → Hosting layer → AgentApplication → Your handlers

Слои обработки в агенте, созданном с помощью пакета SDK агентов, работают следующим образом:

1. Хостинговый слой принимает HTTP-запрос и аутентифицирует его.
2. AgentApplication обрабатывает входящую активность через свой конвейер.
3. Ваши обработчики вызываются при совпадении маршрутов.

Ваш агент загружает состояние хода до запуска ваших обработчиков. После этого агент сохраняет состояние текущего хода.

Основные понятия

Действия

В пакете SDK агентов всё обрабатывается в виде действии. Действие — это структурированное сообщение, отражающее произошедшее. У действия есть тип, например: сообщение, событие, вызов, обновление разговора (conversationUpdate) и так далее. Действие содержит полезные данные, соответствующую этому типу. AgentApplication получает действия и направляет их к соответствующему обработчику.

Маршруты

Маршрут совмещает селектор с обработчиком. Селектор определяет, соответствует ли маршрут текущему действию. Обработчик выполняет вашу логику при соответствии маршрута.

Регистрируйте маршруты при настройке агента. Маршруты могут срабатывать на следующее:

• Сообщение с определенным текстом или соответствующее регулярному выражению
• Любое действие определенного типа
• События жизненного цикла беседы (участник добавлен, участник удален)
• Действия адаптивной карточки
• Настраиваемые условия

При поступлении действия система проверяет маршруты по очереди, пока не найдет соответствие. По умолчанию выполняется только один маршрут.

Состояние этапа

AgentApplication управляет _turn state — структурированным хранилищем, разделенным на области:

Тип областей	Описание
Разговор	Общая для всех пользователей в разговоре, сохраняется между этапами
Пользователь	Относится к отдельному пользователю во всех разговорах
Временная	Только для текущего этапа — не сохраняется

Система автоматически загружает состояние до запуска ваших обработчиков и сохраняет его после.

Контекст этапа

Когда обработчик выполняется, он получает контекст этапа. Контекст этапа — это снимок текущего действия, подключения адаптера и утилит для отправки ответов. Контекст этапа — это ваш интерфейс для текущего взаимодействия.

ПО промежуточного слоя

AgentApplication поддерживает конвейер ПО промежуточного слоя. ПО промежуточного слоя — это цепочка компонентов, обрабатывающих каждое взаимодействие до и после выполнения ваших обработчиков. ПО промежуточного слоя может анализировать, преобразовывать или прерывать поток действий. Распространенные применения включают логирование, проверку аутентификации и нормализацию запросов.

Создание агента

C#

Создайте подкласс AgentApplication и зарегистрируйте обработчики в конструкторе. Хостинговый фреймворк автоматически внедряет AgentApplicationOptions.

public class MyAgent : AgentApplication
{
    public MyAgent(AgentApplicationOptions options) : base(options)
    {
        OnConversationUpdate(ConversationUpdateEvents.MembersAdded, WelcomeAsync);
        OnActivity(ActivityTypes.Message, OnMessageAsync, rank: RouteRank.Last);
    }

    private async Task WelcomeAsync(ITurnContext context, ITurnState state, CancellationToken ct)
    {
        foreach (var member in context.Activity.MembersAdded)
        {
            if (member.Id != context.Activity.Recipient.Id)
            {
                await context.SendActivityAsync("Hello! How can I help you?", cancellationToken: ct);
            }
        }
    }

    private async Task OnMessageAsync(ITurnContext context, ITurnState state, CancellationToken ct)
    {
        await context.SendActivityAsync($"You said: {context.Activity.Text}", cancellationToken: ct);
    }
}

Зарегистрируйте своего агента в Program.cs:

WebApplicationBuilder builder = WebApplication.CreateBuilder(args);

builder.Services.AddHttpClient();
builder.Services.AddSingleton<IStorage, MemoryStorage>();
builder.Services.AddAgent<MyAgent>();
builder.Services.AddAgentAspNetAuthentication(builder.Configuration);

WebApplication app = builder.Build();

app.UseAuthentication();
app.UseAuthorization();
app.MapAgentApplicationEndpoints(requireAuth: !app.Environment.IsDevelopment());

app.Run();

JavaScript

Создайте AgentApplication и зарегистрируйте обработчики для экземпляра с помощью Fluent API. Чтобы запустить сервер, вызовите startServer из пакета хостинга Express.

import { AgentApplication, MemoryStorage, TurnContext, TurnState } from '@microsoft/agents-hosting'
import { startServer } from '@microsoft/agents-hosting-express'

const app = new AgentApplication<TurnState>({ storage: new MemoryStorage() })

app.onConversationUpdate('membersAdded', async (context: TurnContext) => {
    await context.sendActivity('Hello! How can I help you?')
})

app.onActivity('message', async (context: TurnContext, state: TurnState) => {
    await context.sendActivity(`You said: ${context.activity.text}`)
})

startServer(app)

Для ручной настройки Express без startServer:

import express from 'express'
import { CloudAdapter, authorizeJWT, AuthConfiguration } from '@microsoft/agents-hosting'

const authConfig: AuthConfiguration = loadAuthConfigFromEnv()
const adapter = new CloudAdapter(authConfig)
const expressApp = express()

expressApp.use(express.json())
expressApp.use(authorizeJWT(authConfig))

expressApp.post('/api/messages', async (req, res) => {
    await adapter.process(req, res, async (context) => {
        await app.run(context)
    })
})

Python

Создайте экземпляр AgentApplication с параметром типа и зарегистрируйте обработчики с помощью декораторов.

from microsoft_agents.hosting.core import AgentApplication, TurnState, TurnContext, MemoryStorage
from microsoft_agents.hosting.aiohttp import CloudAdapter, start_agent_process
from aiohttp.web import Request, Response, Application, run_app

AGENT_APP = AgentApplication[TurnState](
    storage=MemoryStorage(),
    adapter=CloudAdapter()
)

@AGENT_APP.conversation_update("membersAdded")
async def on_members_added(context: TurnContext, state: TurnState):
    await context.send_activity("Hello! How can I help you?")

@AGENT_APP.activity("message")
async def on_message(context: TurnContext, state: TurnState):
    await context.send_activity(f"You said: {context.activity.text}")

if __name__ == "__main__":
    async def messages(req: Request) -> Response:
        return await start_agent_process(req, AGENT_APP, AGENT_APP.adapter)

    app = Application()
    app.router.add_post("/api/messages", messages)
    app["agent_app"] = AGENT_APP
    app["adapter"] = AGENT_APP.adapter
    run_app(app, host="localhost", port=3978)

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

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

Сопоставьте сообщения по точному тексту (без учета регистра):

C#

OnMessage("help", async (context, state, ct) =>
{
    await context.SendActivityAsync("Here's what I can do...", cancellationToken: ct);
});

Сопоставление сообщений с помощью регулярного выражения:

OnMessage(new Regex(@"^order\s+\d+$", RegexOptions.IgnoreCase), async (context, state, ct) =>
{
    await context.SendActivityAsync("Looking up your order...", cancellationToken: ct);
});

JavaScript

app.onMessage('help', async (context: TurnContext, state: TurnState) => {
    await context.sendActivity("Here's what I can do...")
})

Сопоставление сообщений с помощью регулярного выражения:

app.onMessage(/^order\s+\d+$/i, async (context: TurnContext, state: TurnState) => {
    await context.sendActivity('Looking up your order...')
})

Python

@AGENT_APP.message("/help")
async def on_help(context: TurnContext, state: TurnState):
    await context.send_activity("Here's what I can do...")

Сопоставление сообщений с помощью регулярного выражения:

import re

@AGENT_APP.message(re.compile(r"^order\s+\d+$", re.IGNORECASE))
async def on_order(context: TurnContext, state: TurnState):
    await context.send_activity("Looking up your order...")

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

Регистрируйте обработчики для событий жизненного цикла беседы, таких как присоединение участников или их выход.

C#

OnConversationUpdate(ConversationUpdateEvents.MembersAdded, async (context, state, ct) =>
{
    foreach (var member in context.Activity.MembersAdded)
    {
        if (member.Id != context.Activity.Recipient.Id)
        {
            await context.SendActivityAsync("Welcome!", cancellationToken: ct);
        }
    }
});

OnConversationUpdate(ConversationUpdateEvents.MembersRemoved, async (context, state, ct) =>
{
    // Called when participants leave the conversation
});

JavaScript

app.onConversationUpdate('membersAdded', async (context: TurnContext) => {
    for (const member of context.activity.membersAdded ?? []) {
        if (member.id !== context.activity.recipient.id) {
            await context.sendActivity('Welcome!')
        }
    }
})

app.onConversationUpdate('membersRemoved', async (context: TurnContext) => {
    // Called when participants leave the conversation
})

Python

@AGENT_APP.conversation_update("membersAdded")
async def on_members_added(context: TurnContext, state: TurnState):
    for member in context.activity.members_added or []:
        if member.id != context.activity.recipient.id:
            await context.send_activity("Welcome!")

@AGENT_APP.conversation_update("membersRemoved")
async def on_members_removed(context: TurnContext, state: TurnState):
    pass  # Called when participants leave the conversation

Обработка действий любого типа

Сопоставление любых действий по строке типа для полного контроля маршрутизации.

C#

OnActivity(ActivityTypes.Message, async (context, state, ct) =>
{
    // Handles all message activities
});

OnActivity(ActivityTypes.Event, async (context, state, ct) =>
{
    // Handles event activities
});

Используйте константы ActivityTypes вместо строк, прописанных в коде.

JavaScript

app.onActivity('message', async (context: TurnContext, state: TurnState) => {
    // Handles all message activities
})

app.onActivity('event', async (context: TurnContext, state: TurnState) => {
    // Handles event activities
})

Python

@AGENT_APP.activity("message")
async def on_message(context: TurnContext, state: TurnState):
    pass  # Handles all message activities

@AGENT_APP.activity("event")
async def on_event(context: TurnContext, state: TurnState):
    pass  # Handles event activities

Контроль порядка оценки маршрутов

Маршруты сортируются в фиксированный порядок оценки при их регистрации, а не во время выполнения. Сортировка включает два уровня:

1. Тип маршрута: система группирует маршруты по типу и всегда сначала оценивает маршруты более высокого приоритета, чем маршруты низкого приоритета, независимо от ранга:

   Приоритет	Тип маршрута
   1 (самый высокий)	Маршруты вызовов на основе агентов
   2	Маршруты вызовов (действия адаптивных карточек, обратные вызовы OAuth и другие вызовы, чувствительные ко времени)
   3	Маршруты на основе агентов
   4 (самый низкий)	Все остальные маршруты

2. Ранг: внутри каждой группы типов маршрутов система упорядочивает маршруты по их значению ранга. Маршруты с наименьшими значениями ранга обрабатываются первыми.

Используйте константы RouteRank для назначения ранга при регистрации обработчика:

Константа	Значение	Значение
RouteRank.First	0	Оценивается перед всеми остальными маршрутами в своей группе
RouteRank.Unspecified	32767	Используется по умолчанию, если ранг не указан
RouteRank.Last	65535	Оценивается после всех остальных маршрутов своей группы

По умолчанию обработка останавливается на первом совпадающем маршруте. Используйте RouteRank.Last для универсального маршрута, который обрабатывает всё, что не охвачено более конкретными маршрутами.

C#

// Specific handlers use the default rank
OnMessage("status", HandleStatusAsync);
OnMessage("help", HandleHelpAsync);

// Catch-all — handles anything not matched above
OnActivity(ActivityTypes.Message, HandleUnknownMessageAsync, rank: RouteRank.Last);

JavaScript

// Specific handlers use the default rank
app.onMessage('status', handleStatusAsync)
app.onMessage('help', handleHelpAsync)

// Catch-all — handles anything not matched above
app.onActivity('message', handleUnknownMessageAsync, RouteRank.Last)

Python

@AGENT_APP.message("/status")
async def on_status(context: TurnContext, state: TurnState):
    await context.send_activity("Status: OK")

@AGENT_APP.message("/help")
async def on_help(context: TurnContext, state: TurnState):
    await context.send_activity("Here's what I can do...")

# Catch-all — handles anything not matched above (registered last)
@AGENT_APP.activity("message")
async def on_unknown(context: TurnContext, state: TurnState):
    await context.send_activity("I didn't understand that. Type /help for options.")

Перехватчики жизненного цикла этапа

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

C#

OnBeforeTurn(async (context, state, ct) =>
{
    logger.LogInformation("Turn started: {Type}", context.Activity.Type);
    return true; // Return false to abort the turn
});

OnAfterTurn(async (context, state, ct) =>
{
    logger.LogInformation("Turn completed");
    return true; // Return false to skip state saving
});

OnTurnError(async (context, state, exception, ct) =>
{
    logger.LogError(exception, "Turn error");
    await context.SendActivityAsync("Something went wrong. Please try again.", cancellationToken: ct);
});

Когда OnBeforeTurn возвращает false, выполнение этапа прерывается, и ни один маршрут не запускается. Когда OnAfterTurn возвращает false, состояние этапа не сохраняется.

JavaScript

app.beforeTurn(async (context: TurnContext, state: TurnState) => {
    console.log(`Turn started: ${context.activity.type}`)
    return true // Return false to abort the turn
})

app.afterTurn(async (context: TurnContext, state: TurnState) => {
    console.log('Turn completed')
    return true // Return false to skip state saving
})

app.onError(async (context: TurnContext, error: Error) => {
    console.error('Turn error:', error)
    await context.sendActivity('Something went wrong. Please try again.')
})

Python

@AGENT_APP.before_turn
async def on_before_turn(context: TurnContext, state: TurnState) -> bool:
    print(f"Turn started: {context.activity.type}")
    return True  # Return False to abort the turn

@AGENT_APP.after_turn
async def on_after_turn(context: TurnContext, state: TurnState) -> bool:
    print("Turn completed")
    return True  # Return False to skip state saving

@AGENT_APP.turn_error
async def on_turn_error(context: TurnContext, state: TurnState, error: Exception):
    print(f"Turn error: {error}")
    await context.send_activity("Something went wrong. Please try again.")

Использование состояния этапа

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

• Область разговора: для данных, общих для всех этапов разговора
• Область пользователя: для данных на каждого пользователя
• Временная область: для данных, которые должны существовать только на текущем этапе

C#

OnActivity(ActivityTypes.Message, async (context, state, ct) =>
{
    // Conversation scope — persisted per conversation
    var count = state.Conversation.GetValue<int>("messageCount", () => 0);
    state.Conversation.SetValue("messageCount", count + 1);

    // User scope — persisted per user
    var name = state.User.GetValue<string>("displayName");

    // Temp scope — current turn only
    state.Temp.SetValue("parsedInput", context.Activity.Text?.Trim());

    await context.SendActivityAsync($"Message #{count + 1}: {context.Activity.Text}", cancellationToken: ct);
});

JavaScript

app.onActivity('message', async (context: TurnContext, state: TurnState) => {
    // Conversation scope — persisted per conversation
    let count: number = state.getValue('conversation.messageCount') ?? 0
    state.setValue('conversation.messageCount', count + 1)

    // User scope — persisted per user
    const name: string = state.getValue('user.displayName')

    await context.sendActivity(`Message #${count + 1}: ${context.activity.text}`)
})

Python

@AGENT_APP.activity("message")
async def on_message(context: TurnContext, state: TurnState):
    # Conversation scope — persisted per conversation
    count = state.get_value("conversation.message_count") or 0
    state.set_value("conversation.message_count", count + 1)

    # User scope — persisted per user
    name = state.get_value("user.display_name")

    await context.send_activity(f"Message #{count + 1}: {context.activity.text}")

Примечание

Используйте MemoryStorage для локальной разработки и тестирования. Для развертываний в рабочей среде, особенно при работе на нескольких экземплярах, используйте поставщик постоянного хранилища, например Azure Cosmos DB или хранилище BLOB-объектов Azure. См. статью Использование поставщиков хранилища в агенте.

Следующие шаги

• Управление состоянием в пакете SDK агентов
• Использование поставщиков хранилища в агенте