Microsoft Teams Bot Core SDK

The core SDK for building Microsoft Teams bots in .NET. It implements the Activity Protocol and provides a modern, layered framework with first-class support for ASP.NET Core dependency injection, authentication via MSAL, and extensible activity schemas.

Packages

Package	Description
Microsoft.Teams.Core	Foundational library — activity protocol, conversation client, user token client, middleware pipeline, and authentication
Microsoft.Teams.Apps	High-level Teams framework — typed activity routing, handler registration, OAuth flows, Teams API clients, and streaming
Microsoft.Teams.Apps.BotBuilder	Compatibility bridge for existing Bot Framework SDK v4 bots to run on the new Core infrastructure

Quick Start

using Microsoft.Teams.Apps;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddTeamsBotApplication();

var app = builder.Build();
var teams = app.UseTeamsBotApplication(); // maps POST /api/messages

teams.OnMessage(async (context, ct) =>
{
    await context.SendAsync($"You said: {context.Activity.Text}");
});

app.Run();

Design Principles

• Loose schema — CoreActivity contains only strictly required fields; additional fields are captured via JsonExtensionData
• Simple serialization — Standard System.Text.Json with source generation, no custom converters
• Extensible schema — ChannelData and entities support extension properties; generics allow custom types
• MSAL-based auth — Token acquisition built on Microsoft Identity Web, supporting client secrets, managed identities, and agentic (user-delegated) tokens
• ASP.NET DI — All dependencies configured via IServiceCollection, reusing the built-in HttpClient factory
• ILogger & IConfiguration — Standard .NET logging and configuration throughout

Configuration

Create a Teams Application, configure it in Azure Bot Service, and provide credentials via appsettings.json:

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "<your-tenant-id>",
    "ClientId": "<your-client-id>",
    "Scope": "https://api.botframework.com/.default",
    "ClientCredentials": [
      {
        "SourceType": "ClientSecret",
        "ClientSecret": "<your-entra-app-secret>"
      }
    ]
  }
}

Or via environment variables:

AzureAd__Instance=https://login.microsoftonline.com/
AzureAd__TenantId=<your-tenant-id>
AzureAd__ClientId=<your-client-id>
AzureAd__Scope=https://api.botframework.com/.default
AzureAd__ClientCredentials__0__SourceType=ClientSecret
AzureAd__ClientCredentials__0__ClientSecret=<your-entra-app-secret>

Testing in Localhost (Anonymous)

When no MSAL configuration is provided, all communication happens as anonymous REST calls, suitable for local development.

Install Playground

Linux:

curl -s https://raw.githubusercontent.com/OfficeDev/microsoft-365-agents-toolkit/dev/.github/scripts/install-agentsplayground-linux.sh | bash

Windows:

winget install m365agentsplayground

Run a Scenario

dotnet samples/scenarios/middleware.cs -- --urls "http://localhost:3978"

Samples

Core and hosting

Sample	Description
CoreBot	Lowest-level sample using Microsoft.Teams.Core directly
CustomHosting	Custom TeamsBotApplication subclass and hosting

Messaging and lifecycle

Sample	Description
CommonHandlersBot	Basic message and conversation lifecycle handlers
TeamsBot	Simple Teams bot sample with rich messaging and cards
ReactionsBot	Add/remove message reactions via conversation APIs
TeamsChannelBot	Channel-scoped messaging
TargetedMessages	Targeted messages and targeted message lifecycle
QuotingAndThreadingBot	Quoting and threaded replies

Cards, invokes, and tabs

Sample	Description
AdaptiveCardTaskModuleBot	Adaptive card actions and task module invoke handlers
SuggestedActionBot	Suggested actions and submit handling
MessageExtensionBot	Message extension search and actions
MeetingsBot	Meeting events and participant APIs
TabApp	Tab application with backend API

OAuth, state, and observability

Sample	Description
OAuthFlowBot	OAuth sign-in and token management
GraphBot	App-only bot using the Microsoft Graph SDK with client credentials
CachingAuthTokens	Redis-backed cache for auth/session data
StateBot	Conversation and user state backed by cache
ObservabilityBot	OpenTelemetry and AI observability

AI integrations

Sample	Description
A2ABot	Agent-to-agent handoff bot
ExtAIBot	Microsoft.Extensions.AI integration
McpServer	MCP server with Teams and Graph tools
StreamingBot	Progressive streaming responses

Compatibility and migration

Sample	Description
CompatBot	Bot Framework compatibility sample
PABot	Bot Framework compatibility with Teams auth

Test utilities

Sample	Description
TeamsApisDemo	Console demo for member paging

Project Structure

.
├── src/
│   ├── Microsoft.Teams.Core/              # Foundation: protocol, clients, middleware, auth
│   ├── Microsoft.Teams.Apps/              # Framework: routing, handlers, OAuth, API clients
│   └── Microsoft.Teams.Apps.BotBuilder/   # Compat bridge for Bot Framework SDK v4
├── samples/                               # Sample bot applications
└── test/
    ├── Microsoft.Teams.Core.UnitTests/
    ├── Microsoft.Teams.Apps.UnitTests/
    ├── Microsoft.Teams.Apps.BotBuilder.UnitTests/
    └── IntegrationTests/