microsoft/BotBuilder-Samples：欢迎来到Bot Framework示例库

技术解读

以下内容由 GitRead 中文社区编辑团队基于项目 README 与官方资料整理，结合中文开发者的常见使用场景补充技术选型建议。具体以项目官方文档为准。

BotBuilder-Samples：一套「可执行的」Bot Framework 行为规范

项目背景与痛点

Bot Framework SDK 不是能拿来即用的轻量框架，而是一套完整的对话式 AI 运行时。它的抽象层次相当高：Activity 是跨渠道统一的数据事实标准，TurnContext 承载单次回合的上下文，Adapter 负责鉴权与序列化，Dialog 系统负责多轮状态机，Recognizer 负责把自然语言接入意图识别。概念一旦堆叠，新手遇到的第一个障碍不是“怎么写业务逻辑”，而是“怎么把它跑起来”。

官方 API 文档回答的是“这个类有哪些方法”，但回答不了“我要做一个 Teams 里的审批机器人，第一步该复制哪个目录”。BotBuilder-Samples 填补的正是这块空白：它按任务而非 API 组织目录，每个样例都是一个自洽、可独立运行的最小实现，并同时提供 C#、JavaScript/TypeScript、Python 三套语言版本。这一点常被低估：它实际上构成了一份可执行的跨语言行为规范。当 SDK 在某个渠道的消息序列化、卡片渲染或状态存储上出现差异时，对照三种语言下的同名目录，往往比翻阅 issue 更快定位问题。

核心技术揭秘

这个仓库不自带运行时，它的价值在于把官方运行时的分层结构原样暴露出来，供人拆解。整体数据流可以这样概括：

graph TD A[用户渠道 Teams / Web Chat / Slack] --> B[Bot Connector 服务] B --> C[Bot Adapter JWT 鉴权与 Activity 反序列化] C --> D[中间件管线 日志 / 翻译 / LUIS] D --> E{"消息意图"} E -->|"自然语言"| F[Recognizer LUIS / CLU / 正则] E -->|"结构化命令"| G[Dialog 栈 Waterfall / Component] F --> G G --> H[状态管理 Memory / Blob / Cosmos] G --> I[Skill 调用 Manifest + 令牌交换] H --> J[回复 Activity] I --> J J --> B

从工程角度看，这里有三处设计值得细读。

Adapter 模式贯穿整个框架。所有渠道差异都被收敛在 Adapter 层：入站请求先完成 JWT 校验，再把渠道特有的 JSON 规范化成 Activity；出站则反向映射。样例中对 CloudAdapter 与旧版 BotFrameworkAdapter 的取舍，本身就是一份关于托管标识和多租户隔离的实践说明。

中间件管线明显借鉴了 ASP.NET Core 的 middleware 设计：TurnContext 沿着注册顺序穿透，每层可读可写。这让日志、翻译、内容审核、限流能够以与业务逻辑无关的方式插入，也是这个仓库里最容易被直接搬进生产环境的部分。

Dialog 的组合式状态机是另一条主线。Waterfall Dialog 把“问一句、答一句”拆成可组合的步骤，Component Dialog 负责封装，DialogSet 的栈式管理让“打断—恢复”这类真实对话需求有了统一处理方案。更进一步的 Adaptive Dialogs 把流程从代码里抽离到声明式资源文件，把 LG（语言生成）和 LU（语言理解）当成可热更新的资产，这是从“写代码”向“配流程”的关键一步——也是它与 Composer 打通的技术基础。

功能亮点与差异

与社区里零散的 bot 模板相比，它的杀手锏是官方维护的版本一致性：SDK 一升级，三语言样例同步跟进，省掉了“抄了个两年前的模板，NuGet 装不上”的常见问题。其次是覆盖广度——从 Echo Bot 到 Teams SSO、消息扩展、任务模块、Skill 互调、Adaptive Cards、身份验证，几乎把企业落地的每个关键环节都给出了最短路径。再者是 Skill 体系：通过 Manifest 声明能力、用令牌交换实现租户隔离，这套模式在同类开源方案里很少见，是微软把“机器人组合”真正工程化的地方。

应用场景与落地建议

适合的场景很明确：企业内部 IT/HR/审批机器人、Teams 内的客服与知识问答、需要接入多个渠道的统一入口。语音 IVR 也有样例覆盖。

但在生产环境使用时有几处问题必须处理。状态存储：样例默认的 MemoryStorage 只用于教学，进程重启即丢，正式项目要换成 Blob 或 Cosmos，并处理好 ETag 并发冲突。密钥管理：不要沿用 appsettings.json 明文配置，改用托管标识加 Key Vault。渠道能力差异：卡片尺寸、消息大小、富文本支持在 Teams 和 Web Chat 上完全不同，不要假设样例里的渲染效果可以跨渠道成立。可观测性：把 Application Insights 和自研 trace 接进中间件，否则多轮对话的排障会非常痛苦。最后要留意版本趋势：v4 SDK 正逐步让位给面向 LLM 的 Teams AI Library 与 M365 Agents SDK，仓库中相关样例在持续补充，新项目立项前值得先确认技术路线。

综合评价

优点：覆盖面罕见地全，三语言对齐，示例可运行、可复制，对 SDK 分层的解释力远超文档；Adapter 和中间件部分可以直接借鉴。

缺点：仍是“教科书”式的组织方式，缺少部署 IaC、CI/CD 与规模化运维的示范，从样例到生产的最后一段路要自己走；文档散落在各个子目录的 README 里，检索体验一般；部分历史样例对旧 SDK 版本有路径依赖，跨版本迁移时容易踩坑。

一句话总结：它不教你写代码，它教你理解这门运行时。把它当成规范来读，比当成模板来抄更有价值。

ARCHIVE NOTICE:

We are in the process of archiving the Bot Framework SDK Samples repository on GitHub. This means that this project will no longer be updated or maintained. Customers using this tool will not be disrupted. However, the tool will no longer be supported through service tickets in the Azure portal and will not receive product updates.

To build agents with your choice of AI services, orchestration, and knowledge, consider using the Microsoft 365 Agents SDK. The Agents SDK is GA and has support for C#, JavaScript or Python. You can learn more about the Agents SDK at aka.ms/agents. If you’re looking for a SaaS-based agent platform, consider Microsoft Copilot Studio. If you have an existing bot built with the Bot Framework SDK, you can update your bot to the Agents SDK. You can review the core changes and updates at Bot Framework SDK to Agents SDK migration guidance here. Support tickets for the Bot Framework SDK will no longer be serviced as of December 31, 2025.

We plan to archive this project no later than end of December of 2025.

Click here to find out what’s new with Bot Framework

Overview

This branch contains samples for the released version of the Microsoft Bot Framework V4 SDK for .NET, JS and Python.

Getting the samples

To use the samples, clone this GitHub repository using Git.

    git clone https://github.com/Microsoft/BotBuilder-Samples.git
    cd BotBuilder-Samples

Sample lists

Samples are designed to illustrate functionality you’ll need to implement to build great bots!

!Bot Framework Samples

Bot essentials

	Sample Name	Description	.NET	JavaScript	Python
2	Echo bot	Demonstrates how to receive and send messages.	.NET Core	JavaScript, TypeScript	Python
3	Welcome user	Introduces activity types and provides a welcome message on conversation update activity.	.NET Core	JavaScript, TypeScript	Python
5	Multi turn prompts	Demonstrates how to use waterfall dialog, prompts, and component dialog to create a simple interaction that asks the user for name, age, and prints back that information.	.NET Core	JavaScript, TypeScript	Python
6	Using cards	Introduces all card types including thumbnail, audio, media etc. Builds on Welcoming user + multi-prompt bot by presenting a card with buttons in welcome message that route to appropriate dialog.	.NET Core	JavaScript, TypeScript	Python
7	Adaptive cards	Demonstrates how the multi-turn dialog can use a card to get user input for name and age.	.NET Core	JavaScript	Python
8	Suggested actions	Demonstrates how to enable your bot to present buttons that the user can tap to provide input.	.NET Core	JavaScript	Python
15	Handling attachments	Demonstrates how to listen for/handle user provided attachments.	.NET Core	JavaScript	Python
40	TIMEX resolution	Demonstrates various ways to parse and manipulate the TIMEX expressions you get from LUIS and the DateTimeRecognizer used by the DateTimePrompt.	.NET Core	JavaScript	Python
43	Complex dialogs	Demonstrates different ways for composing dialogs.	.NET Core	JavaScript	Python
45	State management	Demonstrates how to use state management and storage objects to manage and persist state.	.NET Core	JavaScript	Python

Advanced bots

	Sample Name	Description	.NET	JavaScript	Python
1	Console echo bot	Introduces the concept of adapter and demonstrates a simple echo bot on console adapter and how to send a reply and access the incoming message.	.NET Core	JavaScript, TypeScript	Python
1	Browser echo bot	Demonstrates how to host a bot in the browser using Web Chat and a custom Web Chat Adapter.		ECMAScript 6
16	Proactive messages	Demonstrates how to send proactive messages to users.	.NET Core	JavaScript, TypeScript	Python
17	Multilingual bot	Using translate middleware to support a multi-lingual bot. Demonstrates custom middleware.	.NET Core	JavaScript	Python
19	Custom dialogs	Demonstrates complex conversation flow using the Dialogs library.	.NET Core	JavaScript	Python
23	Facebook events	Integrate and consume Facebook specific payloads, such as post-backs, quick replies and opt-in events.	.NET Core	JavaScript	Python
42	Scale out	Demonstrates how you can build your own state solution from the ground up that supports scaled out deployment with ETag based optimistic locking.	.NET Core		Python
44	Basic custom prompts	Demonstrates how to implement your own basic prompts to ask the user for information.	.NET Core	JavaScript	Python
47	Inspection middleware	Demonstrates how to use middleware to allow the Bot Framework Emulator to debug traffic into and out of the bot in addition to looking at the current state of the bot.	.NET Core	JavaScript	Python
49	Proxy echo bot	Demonstrates how to configure the bot to use it behind a corporative proxy.		JavaScript
70	Styling webchat	This sample shows how to create a web page with custom Web Chat component.		ECMAScript 6

Authentication samples

	Sample Name	Description	.NET	JavaScript	Python
18	OAuth authentication	Bot that demonstrates how to integrate OAuth providers.	.NET Core	JavaScript	Python
24	MSGraph authentication	Demonstrates bot authentication capabilities of Azure Bot Service. Demonstrates utilizing the Microsoft Graph API to retrieve data about the user.	.NET Core	JavaScript	Python
46	Teams authentication	Demonstrates how to use authentication for a bot running in Microsoft Teams.	.NET Core	JavaScript	Python
84	Certificate authentication	Demonstrates how to use Certificates to authenticate the bot	.NET Core	JavaScript
85	Subject name/issuer authentication	Demonstrates how to use the subject name/issuer authentication in a bot	.NET Core	JavaScript
86	Federated Credentials authentication	Demonstrates how to use the FIC in a bot authentication	.NET Core	JavaScript

Custom question answering samples

	Sample Name	Description	.NET	JavaScript	Python
12	Custom question answering (simple)	Demonstrates how to use Custom question answering to have simple single-turn conversations	.NET Core	JavaScript
48	Custom question answering (advanced)	Demonstrates how to integrate Multiturn and Active learning in a Custom question answering bot	.NET Core	JavaScript

Skills samples

	Sample Name	Description	.NET Core	JavaScript	Python
80	Skills - simple bot to bot	This sample shows how to connect a skill to a skill consumer.	.NET Core	JavaScript	Python
81	Skills - skill dialog	This sample shows how to connect a skill to a skill dialog consumer.	.NET Core	JavaScript	Python
82	Skills - SSO with CloudAdapter	This sample shows how to use SSO with skills and CloudAdapter.	.NET Core	JavaScript	NA

Experimental / preview samples

A collection of experimental samples exist, intended to provide samples for features currently in preview or as a way to solicit feedback on a given design, approach, or technology being considered by the Bot Framework Team.

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.

When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA. This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.

Reporting security issues

Security issues and bugs should be reported privately, via email, to the Microsoft Security Response Center (MSRC) at [email protected]. You should receive a response within 24 hours. If for some reason you do not, please follow up via email to ensure we received your original message. Further information, including the MSRC PGP key, can be found in the Security TechCenter.

BotBuilder-Samples

技术解读

BotBuilder-Samples：一套「可执行的」Bot Framework 行为规范

项目背景与痛点

核心技术揭秘

功能亮点与差异

应用场景与落地建议

综合评价

关于

简要分析

语言占比

Release

贡献者

ARCHIVE NOTICE:

Click here to find out what’s new with Bot Framework

Overview

Getting the samples

Sample lists

Bot essentials

Advanced bots

Authentication samples

Custom question answering samples

Skills samples

Experimental / preview samples

Contributing

Reporting security issues

评论

BotBuilder-Samples

技术解读

BotBuilder-Samples：一套「可执行的」Bot Framework 行为规范

项目背景与痛点

核心技术揭秘

功能亮点与差异

应用场景与落地建议

综合评价

相关仓库

关于

简要分析

语言占比

Release

贡献者

ARCHIVE NOTICE:

Click here to find out what’s new with Bot Framework

Overview

Getting the samples

Sample lists

Bot essentials

Advanced bots

Authentication samples

Custom question answering samples

Skills samples

Experimental / preview samples

Contributing

Reporting security issues

评论