Описание структуры эхо-бота

ОБЛАСТЬ ПРИМЕНЕНИЯ: ПАКЕТ SDK версии 4

Шаблоны и примеры Bot Framework написаны для ASP.NET (C#), restify (JavaScript) и aiohttp (Python). Однако функции веб-службы не являются частью пакета SDK Bot Framework, но частью веб-платформы, которую вы решили использовать.

Все приложения бота используют некоторые общие функции.

Функция	Описание
Подготовка ресурсов	Бот в качестве веб-приложения должен создать веб-службу, адаптер бота и объект бота.
Конечная точка обмена сообщениями	Веб-приложение должно реализовать конечную точку обмена сообщениями, в которой будут приниматься действия и пересылать действия адаптеру бота.
Адаптер бота	Адаптер получает действия из конечной точки обмена сообщениями, перенаправляет их в обработчик хода бота и перехватывает все ошибки или исключения, которые логика бота не перехватывает.
Объект бота	Объект бота обрабатывает мышление или логику бота для данного хода.

Вы можете создать эхо-бот из шаблонов, как описано в разделе "Создание бота" или скопировать проект эхо-бота из репозитория Microsoft/BotBuilder-Samples .

Шаблоны C# и JavaScript поддерживают встроенные подключения потоковой передачи. Однако в этой статье не рассматриваются функции потоковой передачи.

Примечание.

Чтобы создавать агенты с помощью выбранной службы ИИ, оркестрации и знаний, рекомендуется использовать пакет SDK для агентов Microsoft 365. Пакет SDK для агентов поддерживает C#, JavaScript или Python. Дополнительные сведения о пакете SDK для агентов см. в aka.ms/agents. Если вы ищете платформу агента на основе SaaS, рассмотрите microsoft Copilot Studio. Если у вас есть существующий бот, созданный с помощью пакета SDK Bot Framework, вы можете обновить бота до пакета SDK для агентов. Вы можете ознакомиться с основными изменениями и обновлениями в руководстве по миграции с Bot Framework SDK на SDK для агентов. Запросы на поддержку пакета SDK Bot Framework больше не будут обслуживаться с 31 декабря 2025 г.

Требования

• Базовые знания о ботах.
• Копия примера эхо-бота на C#, JavaScript, Java или Python.

Шаблоны для ботов

Бот — это веб-приложение, а шаблоны для него доступны для каждого из трех языков.

C#

Bot Framework включает как шаблоны VSIX, так и .NET.

Шаблоны создают веб-приложение MVC Core ASP.NET. В основах ASP.NET вы найдете похожий код в таких файлах, как Program.cs и Startup.cs. Эти файлы необходимы для всех веб-приложений и не зависят от бота.

Примечание.

Вы можете установить шаблоны из Visual Studio.

1. В меню выберите "Расширения" и "Управление расширениями".
2. В диалоговом окне "Управление расширениями" найдите и установите шаблоны SDK Bot Framework версии 4 для Visual Studio.

Сведения о развертывании ботов .NET в Azure см. в статье о подготовке и публикации бота.

Файл appsettings.json указывает сведения о конфигурации бота, такие как его идентификатор приложения и пароль, помимо прочего. При использовании определенных технологий или использовании этого бота в рабочей среде потребуется добавить в эту конфигурацию определенные ключи или URL-адрес. Однако для этого эхо-бота вам не нужно делать ничего здесь прямо сейчас; Идентификатор приложения и пароль могут оставаться неопределенными в настоящее время.

Файл EchoBot.csproj указывает зависимости и связанные версии бота. Это все настроено системой и шаблоном. Дополнительные зависимости можно установить с помощью диспетчера пакетов NuGet или dotnet add package команды.

JavaScript

Генератор Yeoman создает веб-приложение с типом restify. В разделе "Быстрый старт" в документации restify представлено приложение, похожее на сгенерированный файл index.js. Некоторые ключевые файлы, созданные шаблоном, описаны в этой статье. Код в некоторых файлах не будет скопирован, но вы увидите его при запуске бота, и вы можете обратиться к примеру эхобота Node.js.

Файл package.json указывает зависимости и связанные версии для бота. Это все настроено системой и шаблоном. Дополнительные зависимости можно установить с помощью npm install.

В файле ENV указываются сведения о конфигурации для вашего бота, в том числе и номер порта, идентификатор приложения и пароль. При использовании определенных технологий или использовании этого бота в рабочей среде потребуется добавить в эту конфигурацию определенные ключи или URL-адрес. В настоящее время для Echo Bot вам не нужно ничего делать здесь прямо сейчас; идентификатор приложения и пароль можно оставить неуказанными на этом этапе.

Чтобы использовать .env файл конфигурации, боту необходим пакет dotenv из npm. Это уже включается в качестве зависимости в файле package.json .

Ява

Генератор Yeoman создает веб-приложение на основе Spring с файлом сборки, используя Maven.

Файл Maven pom.xml указывает зависимости и связанные версии для бота. Это все настроено системой и шаблоном. Дополнительные зависимости можно установить, добавив записи в файл pom.xml.

Файл application.properties указывает сведения о конфигурации бота, такие как номер порта, идентификатор приложения и пароль. При использовании определенных технологий или использовании этого бота в рабочей среде потребуется добавить в эту конфигурацию определенные ключи или URL-адрес. В настоящее время для Echo Bot вам не нужно ничего делать здесь прямо сейчас; идентификатор приложения и пароль можно оставить неуказанными на этом этапе.

Питон

Шаблоны Cookiecutter Python создают веб-приложение aiohttp .

Файл requirements.txt указывает зависимости и связанные версии для бота. Это все настраивается шаблоном и вашей системой. Дополнительные зависимости можно установить с помощью pip install -r requirements.txt

В файле config.py указываются сведения о конфигурации для вашего бота, включая номер порта, идентификатор приложения и пароль. При использовании определенных технологий или использовании этого бота в рабочей среде потребуется добавить в эту конфигурацию определенные ключи или URL-адрес. В настоящее время для Echo Bot вам не нужно ничего делать здесь прямо сейчас; идентификатор приложения и пароль можно оставить неуказанными на этом этапе.

Подготовка ресурсов

Для работы в качестве веб-приложения боту необходимо создать веб-службу, адаптер бота и объект бота.

Для большинства ботов вы также создадите объекты уровня хранения и управления памятью для бота. Однако эхо-боту не требуется сохранять состояние между ходами. Кроме того, для некоторых ботов может потребоваться создать другие объекты, необходимые объекту или адаптеру бота.

C#

В ASP.NET вы регистрируете объекты и методы создания объектов в файле Startup.cs. Метод ConfigureServices загружает подключенные службы и их ключи (если есть) из appsettings.json, подключает состояние и т. д. Здесь адаптер и бот определены как доступные через внедрение зависимостей. Configure Затем метод завершает настройку приложения.

ConfigureServices и Configure вызываются средой выполнения при запуске приложения.

JavaScript

В restify вы настроили веб-службу и объекты, необходимые в файле index.js . Служба, адаптер и бот рассматриваются отдельно в следующих разделах.

Ява

В Spring вы настроили веб-службу и объекты, необходимые в файле application.java . В application.java есть комментарии, обозначающие различные компоненты и классы платформы, используемые приложением бота. Служба, адаптер и бот рассматриваются отдельно в следующих разделах.

Питон

В aiohttp вы настроили веб-службу и объекты, необходимые в файле app.py . Служба, адаптер и бот рассматриваются отдельно в следующих разделах.

Конечная точка обмена сообщениями

Шаблон реализует веб-службу с конечной точкой обмена сообщениями. При получении запроса служба извлекает заголовок аутентификации и полезные данные запроса и пересылает их адаптеру.

Пакеты SDK для C# и JavaScript поддерживают потоковые соединения. Хотя бот эхо не использует какие-либо функции потоковой передачи, адаптер в шаблонах C# и JavaScript предназначен для их поддержки.

Каждый входящий запрос представляет начало нового поворота.

C#

Контроллеры\BotController.cs

// This ASP Controller is created to handle a request. Dependency Injection will provide the Adapter and IBot
// implementation at runtime. Multiple different IBot implementations running at different endpoints can be
// achieved by specifying a more specific type for the bot constructor argument.
[Route("api/messages")]
[ApiController]
public class BotController : ControllerBase
{
    private readonly IBotFrameworkHttpAdapter _adapter;
    private readonly IBot _bot;

    public BotController(IBotFrameworkHttpAdapter adapter, IBot bot)
    {
        _adapter = adapter;
        _bot = bot;
    }

    [HttpPost, HttpGet]
    public async Task PostAsync()
    {
        // Delegate the processing of the HTTP POST to the adapter.
        // The adapter will invoke the bot.
        await _adapter.ProcessAsync(Request, Response, _bot);
    }
}

JavaScript

index.js

// This bot's main dialog.
const { EchoBot } = require('./bot');

// Create HTTP server
const server = restify.createServer();

// Listen for Upgrade requests for Streaming.
server.on('upgrade', async (req, socket, head) => {
    // Create an adapter scoped to this WebSocket connection to allow storing session data.
    const streamingAdapter = new CloudAdapter(botFrameworkAuthentication);
    // Set onTurnError for the CloudAdapter created for each connection.

Ява

Application.java

Предупреждение

Похоже, что образец, который вы ищете, был перемещён! Будьте уверены, что мы работаем над решением этого.

Питон

app.py

    return await ADAPTER.process(req, BOT)


APP = web.Application(middlewares=[aiohttp_error_middleware])
APP.router.add_post("/api/messages", messages)

if __name__ == "__main__":
    try:
        web.run_app(APP, host="localhost", port=CONFIG.PORT)
    except Exception as error:
        raise error

Адаптер бота

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

Адаптер позволяет добавить собственный обработчик ошибок при повороте.

C#

Startup.cs

Используемый адаптер определен в методе ConfigureServices .

// Create the Bot Framework Authentication to be used with the Bot Adapter.
services.AddSingleton<BotFrameworkAuthentication, ConfigurationBotFrameworkAuthentication>();

AdapterWithErrorHandler.cs

public class AdapterWithErrorHandler : CloudAdapter
{
    public AdapterWithErrorHandler(BotFrameworkAuthentication auth, ILogger<IBotFrameworkHttpAdapter> logger)
        : base(auth, logger)
    {
        OnTurnError = async (turnContext, exception) =>
        {
            // Log any leaked exception from the application.
            // NOTE: In production environment, you should consider logging this to
            // Azure Application Insights. Visit https://aka.ms/bottelemetry to see how
            // to add telemetry capture to your bot.
            logger.LogError(exception, $"[OnTurnError] unhandled error : {exception.Message}");

            // Send a message to the user
            await turnContext.SendActivityAsync("The bot encountered an error or bug.");
            await turnContext.SendActivityAsync("To continue to run this bot, please fix the bot source code.");

            // Send a trace activity, which will be displayed in the Bot Framework Emulator
            await turnContext.TraceActivityAsync("OnTurnError Trace", exception.Message, "https://www.botframework.com/schemas/error", "TurnError");
        };
    }
}

JavaScript

index.js

    // This check writes out errors to console log .vs. app insights.
    // NOTE: In production environment, you should consider logging this to Azure
    //       application insights. See https://aka.ms/bottelemetry for telemetry
    //       configuration instructions.
    console.error(`\n [onTurnError] unhandled error: ${ error }`);

    // Send a trace activity, which will be displayed in Bot Framework Emulator
    await context.sendTraceActivity(
        'OnTurnError Trace',
        `${ error }`,
        'https://www.botframework.com/schemas/error',
        'TurnError'
    );

    // Send a message to the user
    await context.sendActivity('The bot encountered an error or bug.');
    await context.sendActivity('To continue to run this bot, please fix the bot source code.');
};

// Set the onTurnError for the singleton CloudAdapter.
adapter.onTurnError = onTurnErrorHandler;

// Create the main dialog.
const myBot = new EchoBot();

// Listen for incoming requests.
server.post('/api/messages', async (req, res) => {

Ява

Application.java

Используемый адаптер определен в методе getBotFrameworkAdapter .

Предупреждение

Похоже, что образец, который вы ищете, был перемещён! Будьте уверены, что мы работаем над решением этого.

АдаптерWithErrorHandler определен в коде Java SDK, в пакете com.microsoft.bot.integration. Этот класс можно проверить в исходном коде пакета SDK для Java.

Питон

app.py

from botbuilder.core import (
    TurnContext,
)
from botbuilder.core.integration import aiohttp_error_middleware
from botbuilder.integration.aiohttp import CloudAdapter, ConfigurationBotFrameworkAuthentication

# Create adapter.
# See https://aka.ms/about-bot-adapter to learn more about how bots work.
ADAPTER = CloudAdapter(ConfigurationBotFrameworkAuthentication(CONFIG))


# Catch-all for errors.
    # This check writes out errors to console log .vs. app insights.
    # NOTE: In production environment, you should consider logging this to Azure
    #       application insights.
    print(f"\n [on_turn_error] unhandled error: {error}", file=sys.stderr)
    traceback.print_exc()

    # Send a message to the user
    await context.send_activity("The bot encountered an error or bug.")
    await context.send_activity(
        "To continue to run this bot, please fix the bot source code."
    )
    # Send a trace activity if we're talking to the Bot Framework Emulator
    if context.activity.channel_id == "emulator":
        # Create a trace activity that contains the error object
        trace_activity = Activity(
            label="TurnError",
            name="on_turn_error Trace",
            timestamp=datetime.utcnow(),
            type=ActivityTypes.trace,
            value=f"{error}",
            value_type="https://www.botframework.com/schemas/error",
        )
        # Send a trace activity, which will be displayed in Bot Framework Emulator
        await context.send_activity(trace_activity)


ADAPTER.on_turn_error = on_error
# Create the Bot
BOT = EchoBot()

Логика бота

Эхо-бот использует обработчик активности и реализует обработчики для типов активности, которые он распознаёт и на которые реагирует, в данном случае обновление разговора и сообщение.

• Действие обновления беседы содержит сведения о том, кто присоединился или покинул беседу. Для бесед, отличных от групп, бот и пользователь присоединяются к беседе при запуске. При групповых беседах обновление бесед создается всякий раз, когда кто-то присоединяется или покидает беседу, будь то бот или пользователь.
• Действие сообщения — это сообщение, которое пользователь отправляет боту.

Эхо-бот приветствует пользователя, когда он присоединяется к беседе, и отражает все сообщения, которые пользователь отправляет боту.

C#

Startup.cs

Используемый бот определен в методе ConfigureServices .

// Create the Bot Adapter with error handling enabled.
services.AddSingleton<IBotFrameworkHttpAdapter, AdapterWithErrorHandler>();

Bots\EchoBot.cs

public class EchoBot : ActivityHandler
{
    protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
    {
        var replyText = $"Echo: {turnContext.Activity.Text}";
        await turnContext.SendActivityAsync(MessageFactory.Text(replyText, replyText), cancellationToken);
    }

    protected override async Task OnMembersAddedAsync(IList<ChannelAccount> membersAdded, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
    {
        var welcomeText = "Hello and welcome!";
        foreach (var member in membersAdded)
        {
            if (member.Id != turnContext.Activity.Recipient.Id)
            {
                await turnContext.SendActivityAsync(MessageFactory.Text(welcomeText, welcomeText), cancellationToken);
            }
        }
    }
}

JavaScript

index.js

// This bot's main dialog.
    // Route received a request to adapter for processing
    await adapter.process(req, res, (context) => myBot.run(context));
});

bot.js

// @ts-check

const { ActivityHandler, MessageFactory } = require('botbuilder');

class EchoBot extends ActivityHandler {
    constructor() {
        super();
        // See https://aka.ms/about-bot-activity-message to learn more about the message and other activity types.
        this.onMessage(async (context, next) => {
            const replyText = `Echo: ${ context.activity.text }`;
            await context.sendActivity(MessageFactory.text(replyText, replyText));
            // By calling next() you ensure that the next BotHandler is run.
            await next();
        });

        this.onMembersAdded(async (context, next) => {
            const membersAdded = context.activity.membersAdded ?? [];
            const welcomeText = 'Hello and welcome!';
            for (let cnt = 0; cnt < membersAdded.length; ++cnt) {
                if (membersAdded[cnt].id !== context.activity.recipient.id) {
                    await context.sendActivity(MessageFactory.text(welcomeText, welcomeText));
                }
            }
            // By calling next() you ensure that the next BotHandler is run.
            await next();
        });

Ява

Application.java

Используемый бот определен в методе getBot .

Предупреждение

Похоже, что образец, который вы ищете, был перемещён! Будьте уверены, что мы работаем над решением этого.

EchoBot.cs

Предупреждение

Похоже, что образец, который вы ищете, был перемещён! Будьте уверены, что мы работаем над решением этого.

Питон

app.py

from botbuilder.core import (
    TurnContext,
)
from botbuilder.core.integration import aiohttp_error_middleware
from botbuilder.integration.aiohttp import CloudAdapter, ConfigurationBotFrameworkAuthentication

bots/bot.py

from botbuilder.core import ActivityHandler, MessageFactory, TurnContext
from botbuilder.schema import ChannelAccount


class EchoBot(ActivityHandler):
    async def on_members_added_activity(
        self, members_added: [ChannelAccount], turn_context: TurnContext
    ):
        for member in members_added:
            if member.id != turn_context.activity.recipient.id:
                await turn_context.send_activity("Hello and welcome!")

    async def on_message_activity(self, turn_context: TurnContext):
        return await turn_context.send_activity(
            MessageFactory.text(f"Echo: {turn_context.activity.text}")
        )

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

• Узнайте, как отправлять и получать текстовые сообщения
• Узнайте, как отправлять приветственные сообщения пользователям