你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

Microsoft Bot Framework 基础知识

适用于：SDK v4

机器人是用户使用文本、图形（例如卡片或图像）或语音通过聊天的方式与之进行交互的应用。 Azure AI 机器人服务是一个云平台。 它托管机器人，并使其可用于“通道”，例如 Microsoft Teams、Facebook 或 Slack。

Bot Framework Service 是 Azure AI 机器人服务的组件，用于在连接机器人的用户应用与机器人之间发送信息。 每个通道可以在发送的活动中包含其他信息。 在创建机器人之前，必须了解机器人如何使用活动对象来与其用户通信。

此图演示了用户与回显机器人通信时可能交换的两种活动类型：“对话更新”和“消息”。

当某一方参与对话时，Bot Framework Service 可以发送“对话更新”。 例如，使用 Bot Framework Emulator 开始对话时，会看到两个对话更新活动（一个活动指出用户正在参与对话，另一个活动指出机器人正在参与对话）。 若要区分这些对话更新活动，请检查活动的“已添加成员”属性包含谁。

“消息”活动承载参与方之间的对话信息。 在聊天机器人示例中，消息活动承载简单的文本，通道呈现这些文本。 消息活动也可以承载要讲述的文本、建议的操作或要显示的卡片。

提示

由每个通道实现 Bot Framework 协议，每个通道的实现方式可能略有不同。 例如，某些通道先发送对话更新活动，有些通道在发送第一个消息活动后发送对话更新活动。 一个通道可以同时在一个对话更新活动中包括机器人和用户，而另一个通道可能会发送两个对话更新活动。

在此示例中，机器人创建并发送了一个消息活动，以响应它收到的入站消息活动。 但是，机器人可通过其他方式响应收到的消息活动；机器人经常通过发送带有欢迎消息的消息活动来响应对话更新活动。 有关详细信息，请参阅如何欢迎用户。

Bot Framework SDK

Bot Framework SDK 允许生成可在 Azure AI 机器人服务上托管的机器人。 该服务定义了 REST API 和活动协议，用于定义机器人如何与通道或用户进行交互。 SDK 基于此 REST API 构建，并提供服务的抽象，以便你可以专注于对话逻辑。 虽然无需理解 REST 服务即可使用 SDK，但理解其一些功能可能会有所帮助。

机器人是具有对话界面的应用。 可以使用机器人将简单的重复性任务（例如订餐或收集个人资料信息）转移给不再需要直接人为干预的自动化系统来完成。 用户使用文本、交互卡和语音与机器人聊天。 机器人交互可以是快速的问答式交互，也可以是复杂的聊天，通过聊天以智能方式提供对服务的访问权限。

注意

对 SDK 和 REST API 提供功能的支持因通道而异。 可以使用 Bot Framework Emulator 测试机器人，但还应在要提供机器人的每个通道上测试机器人的所有功能。

交互涉及按“轮次”处理的“活动”交换。

活动

用户（或通道）与机器人之间的每个交互都表示为“活动”。 Bot Framework 活动架构定义可在用户或通道与机器人之间交换的活动。 活动可以表示人类文本或语音、应用到应用通知、对其他消息的反应等。

轮次

在聊天时，人们通常一次说一句话，并且会轮流说话。 使用机器人时，通常是由机器人对用户输入进行响应。 在 Bot Framework SDK 中，一轮通话既包含用户传给机器人的活动，又包含机器人发回用户的作为即时响应的活动。 可以将一个轮次视为机器人接收给定活动的相关处理。

例如，用户可能会要求机器人执行特定任务。 机器人可能会回答问题以获取有关该任务的详细信息，此时此轮次结束。 下一轮次，机器人从用户那里收到一条新消息，该消息可能包含机器人问题的答案，或者它可能表示主题的更改或忽略执行任务的初始请求的请求。

机器人应用程序结构

SDK 定义一个“机器人”类，用于处理机器人应用的对话推理。 机器人类：

• 识别和解释用户的输入。
• 对输入进行推理并执行相关任务。
• 生成有关机器人正在执行的操作或已执行的操作的响应。

SDK 还定义用于处理与通道的连接的“适配器”。 适配器：

• 提供处理来自用户通道之请求的方法，以及生成发送到用户通道之请求的方法。
• 包括中间件管道，其中包括机器人轮次处理程序之外的轮次处理。
• 调用机器人的轮次处理程序并捕获轮次处理程序中未处理的错误。

此外，机器人通常需要检索和存储每个轮次的状态。 状态通过“存储”、“机器人状态”和“属性访问器”类进行处理。 SDK 不提供内置存储，但为存储和存储层的一些实现提供抽象。 管理状态主题介绍了这些状态和存储功能。

SDK 不需要使用特定的应用程序层来发送和接收 Web 请求。 Bot Framework 有适用于 ASP.NET (C#)、restify (JavaScript) 和 aiohttp (Python) 的模板和示例。 但是，可以选择为应用使用不同的应用程序层。

使用 SDK 创建机器人时，提供代码来接收 HTTP 流量并将其转发到适配器。 Bot Framework 提供了一些模板和示例，可用于开发自己的机器人。

注意

Bot Framework JavaScript、C# 和 Python SDK 将继续受支持，但 Java SDK 即将停用，最终长期支持将于 2023 年 11 月结束。

使用 Java SDK 构建的现有机器人将继续正常运行。

对于新的机器人生成，请考虑使用 Microsoft Copilot Studio 并阅读选择 正确的 copilot 解决方案。

有关详细信息，请参阅机器人构建的未来。

机器人逻辑

机器人对象包含轮次的对话推理或逻辑，并公开“轮次处理程序”，该方法可以接受来自机器人适配器的传入活动。

SDK 提供了一些不同的范例来管理机器人逻辑。

• “活动处理程序”提供事件驱动的模型，其中传入的活动类型和子类型是事件。 对于与用户进行有限的简短交互的机器人，请考虑使用活动处理程序。
  • 使用活动处理程序并为机器人将识别和响应的每个活动类型或子类型实现处理程序。
  • 使用 Teams 活动处理程序创建可连接到 Teams 通道的机器人。 （Teams 通道要求机器人处理某些特定于通道的行为。）
• 对话库提供了基于状态的模型来管理与用户的长时间对话。
  • 对主要顺序对话使用活动处理程序和“组件对话”。 有关详细信息，请参阅关于组件和瀑布对话。
• 实现自己的机器人类，并提供自己的逻辑来处理每个轮次。 有关示例，请参阅如何创建自己的提示来收集用户输入。

机器人适配器

适配器具有用于启动轮次的“进程活动”方法。

• 它采用请求正文（请求有效负载，转换为活动）和请求标头作为参数。
• 它检查身份验证标头是否有效。
• 它为轮次创建“上下文”对象。 上下文对象包含有关活动的信息。
• 它通过其“中间件”管道发送上下文对象。
• 然后，它将上下文对象发送至机器人对象的轮次处理程序。

适配器还会：

• 设置响应活动的格式并发送。 这些响应通常是给用户的消息，但也可能包括用户通道直接使用的信息。
• 显示 Bot Connector REST API 提供的其他方法，例如“更新消息”和“删除消息”。
• 捕获轮次未能捕获的错误或异常。

轮次上下文

轮次上下文对象提供有关活动的信息，例如发送方和接收方、通道，以及处理该活动所需的其他数据。 使用该对象还能在机器人的不同层中处理轮次期间添加信息。

轮次上下文是 SDK 中最重要的抽象之一。 轮次上下文不仅将入站活动传递到所有中间件组件将和应用程序逻辑，而且还提供所需的机制让中间件组件和机器人逻辑发送出站活动。

中间件

中间件非常类似于其他任何消息传送中间件，由一组线性组件构成，其中每个组件按顺序执行，并有机会对活动运行。 中间件管道的最后一个阶段是回调已由应用程序注册到适配器 process activity 方法的机器人类中的轮次处理程序。 中间件实现 适配器调用的“轮次”方法。

轮次处理程序采用轮次上下文作为参数。通常，在轮次处理程序函数内部运行的应用程序逻辑将处理入站活动的内容，在响应中生成一个或多个活动，并使用轮次上下文中的 send activity 函数发送这些出站活动。 调用轮次上下文中的 send activity 会导致针对出站活动调用中间件组件。 中间件组件在机器人的轮次处理程序函数之前和之后执行。 执行在本质上是嵌套的，因此，有时称作“洋葱式的”。

中间件主题更深入地介绍了中间件。

机器人状态和存储

与其他 Web 应用一样，机器人本质上是无状态的。 机器人中的状态遵循与新式 Web 应用程序相同的模式，Bot Framework SDK 提供存储层和状态管理抽象用于简化状态管理。

管理状态主题介绍了这些状态和存储功能。

消息传送端点和预配

通常，应用程序需要一个接收消息的 REST 端点。 它还需要根据你决定使用的平台为机器人预配资源。

按照创建机器人快速入门的说明创建和测试简单的回显机器人。

HTTP 详细信息

活动通过 HTTP POST 请求从 Bot Framework Service 抵达机器人。 机器人使用 200 HTTP 状态代码响应入站 POST 请求。 从机器人发送到通道的活动通过单独的 HTTP POST 发送到 Bot Framework Service。 而此请求也会通过 200 HTTP 状态代码得到确认。

协议不会指定这些 POST 请求及其确认的发送顺序。 但是，为了适应常见的 HTTP 服务框架，这些请求通常会嵌套，这意味着，出站 HTTP 请求将在入站 HTTP 请求的范围内从机器人发出。 前面的关系图演示了此模式。 由于两个不同的 HTTP 连接相继出现，安全模型必须能够应对这种情况。

注意

在大多数通道上机器人有 15 秒的时间确认状态为 200 的呼叫。 如果机器人在 15 秒内未响应，则会发生 HTTP GatewayTimeout 错误 (504)。

活动处理堆栈

让我们深入查看前面的序列图，并重点关注消息活动的抵达。

通道将用户的消息发送到 Azure AI 机器人服务，服务会将消息转发到机器人的消息端点。 机器人的响应会发送到轮次范围内的用户。

在上述示例中，机器人使用包含相同文本消息的另一个消息活动回复了原始消息活动。 处理工作从 HTTP POST 请求（包含以 JSON 有效负载形式传递的活动信息）抵达 Web 服务器时开始。 通常，ASP.NET 项目用于 C# 机器人，而 Express 或 restify 等常用框架用于 JavaScript Node.js 机器人。

适配器（SDK 的集成组件）是 SDK 运行时的核心。 活动以 JSON 形式承载在 HTTP POST 正文中。 将反序列化此 JSON 以创建 activity 对象，然后通过调用其 process activity 方法将此对象传递给适配器。 收到活动时，适配器会创建轮次上下文并调用中间件。

如前所述，轮次上下文提供一个机制来让机器人发送出站活动（主要是为了响应入站活动）。 轮次上下文提供 send、update 和 delete activity 响应方法。 每个响应方法都在异步进程中运行。

重要

线程处理主机器人轮次完成后处理上下文对象释放。 确保 await 任何活动调用，以便主线程等待生成的活动，再完成处理并释放轮次上下文。 否则，如果某个响应（包括其处理程序）在已占用大量时间的情况下尝试对上下文对象执行操作，则会出现“上下文已释放”错误。

机器人模板

你需要为应用选择应用程序层用途；但是，Bot Framework 具有适用于 ASP.NET (C#)、restify (JavaScript) 和 aiohttp (Python) 的模板和示例。 文档是假设你使用这些平台之一，但 SDK 不需要你如此。 有关如何访问和安装模板的说明，请参阅创建机器人快速入门。

机器人是一个 Web 应用程序，我们为 SDK 每种语言版本都提供了对应的模板。 所有模板都提供默认端点实现和适配器。 各模板包括：

• 资源预配
• 特定于语言的 HTTP 端点实现，用于将传入活动路由到适配器。
• 适配器对象
• 机器人对象

不同模板类型之间的主要区别在于机器人对象。 模板是：

• 空机器人
  • 包括一个活动处理程序，该处理程序通过在对话的第一轮发送“hello world”消息来欢迎用户进行对话。
• 回显机器人
  • 使用活动处理程序欢迎用户并回传用户输入。
• 核心机器人
  • 将 SDK 的许多功能汇集在一起，并演示了机器人的最佳做法。
  • 使用活动处理程序欢迎用户。
  • 使用组件对话和子对话来管理对话。
  • 对话使用语言理解 (LUIS) 和 QnA Maker 功能。

注意

Azure QnA Maker 将于 2025 年 3 月 31 日停用。 从2022年10月1日开始，您将无法创建新的 QnA Maker 资源或知识库。 问答功能的较新版本现已作为 Azure AI 语言的一部分提供。

自定义问答是 Azure 语言认知服务的一项功能，是 QnA Maker 服务的更新版本。 有关 Bot Framework SDK 中的问答支持的详细信息，请参阅自然语言理解。

注意

语言理解 (LUIS) 将于 2025 年 10 月 1 日停用。 从 2023 年 4 月 1 日开始，将无法创建新的 LUIS 资源。 语言理解的较新版本现已作为 Azure AI 语言的一部分提供。

对话语言理解（CLU）是 Azure AI 语言的一项功能，是 LUIS 的更新版本。 有关 Bot Framework SDK 中的语言理解支持的详细信息，请参阅自然语言理解。

其他信息

管理机器人资源

你需要管理机器人的资源，例如其应用 ID 和密码，以及任何连接的服务的信息。 部署机器人时，需要安全访问此信息。 为了避免过于复杂，大多数 Bot Framework SDK 文章不介绍如何管理此信息。

• 有关常规安全信息，请参阅 Bot Framework 安全准则。
• 若要管理 Azure 中的密钥和机密，请参阅关于 Azure Key Vault。

渠道适配器

SDK 还允许你使用通道适配器，其中适配器本身还会执行 Bot Connector Service 正常为通道执行的任务。

SDK 提供一些语言的通道适配器。 Botkit 和社区存储库提供了更多通道适配器。 有关详细信息，请参阅 Bot Framework SDK 存储库的通道和适配器表。

Bot Connector REST API

Bot Framework SDK 在 Bot Connector REST API 的基础上包装和生成。 若要了解支持 SDK 的基础 HTTP 请求，请参阅 Connector 身份验证和相关文章。 机器人发送和接收的活动符合 Bot Framework 活动架构。

后续步骤

• 若要了解机器人中的状态的作用，请参阅管理状态。
• 若要了解有关开发 Microsoft Teams 机器人的重要概念，请参阅 Microsoft Teams 机器人的工作原理