# teams-sdk: the second-generation Microsoft Teams app and agent framework

> teams-sdk is Microsoft's framework for building AI agents and apps inside Microsoft Teams, with code split across TypeScript, C# and Python repositories. Version 2 replaces the v1 main branch with a new App and plugin architecture, and the repository itself is a turbo monorepo of packages and documentation rather than a single library.

**microsoft/teams-sdk** — SDK focused on building AI based applications and extensions for Microsoft Teams and other Bot Framework channels

- Repository: https://github.com/microsoft/teams-sdk
- Stars: 731 · Forks: 270
- Language: TypeScript
- License: MIT
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/microsoft-teams-sdk

## Teams SDK targets AI agents first and legacy bot applications second

The repository describes Teams SDK as a reimagining of how Teams apps and AI agents are built, with compatibility retained for existing botframework-based agents. That pairing is the project's whole pitch: it is a v2 architecture aimed at agent development, and the older Bot Framework style of application is expected to keep working rather than be rewritten from scratch.

The scope is wider than a bot library. The documentation lists AI-powered agents, Message Extensions, embedded web applications and Graph as the capability areas, and states that Teams SDK covers all of them through one framework rather than through separate SDKs per surface. That unification is the main reason to look at it if your application needs more than message handling.

The naming has also shifted. Teams AI is now officially Teams SDK, a rename the project presents as a commitment to a development framework for all kinds of Teams applications, not only AI ones. The underlying code lives in separate per-language repositories rather than here: microsoft/teams.ts, microsoft/teams.net and microsoft/teams.py. The README is explicit that language-specific bugs and issues belong in the matching language repository, so this repository is the umbrella, the documentation site and the CLI source, not the place to file a Python bug.

## This repository is a turbo monorepo of packages, plugins and docs, not a library

Look at the root package.json and the shape of the project becomes clear. It is a private workspace root that orchestrates many packages through turbo rather than a package you install from npm. The workspace globs point at a packages directory and a documentation package.

```json
  "workspaces": [
    "packages/*",
    "teams.md"
  ],
```

The scripts follow the same pattern: build, dev, lint and test are all delegated to turbo across the workspace, with a filtered variant that builds only the packages. Formatting is handled by prettier over js, ts, tsx, md and json files.

```json
    "build": "npx turbo build",
    "lint": "npx turbo lint",
    "test": "npx turbo test --concurrency=100%",
```

Two entries in the root file set the floor for anyone working on the SDK itself. The engines field requires Node 22.12.0 or newer, and the package manager is pinned to npm 10.9.2, with turbo listed as a development dependency at version 2.9.14 and TypeScript at 5.8.2. The top-level entries also show plugins/ and teams.md/ as siblings of packages/, plus a scripts/ directory holding a version stamping script that writes into version.json. Version bumps are therefore a scripted step in this monorepo, not a manual edit.

## Bootstrapping your first agent with the Teams Developer CLI

The fastest route into the framework is the Teams Developer CLI, which scaffolds a project for you. The README gives the global install first.

```bash
npm install -g @microsoft/teams.cli
```

After that, the CLI creates a new agent project. The template name in the documented command is echo, and you choose the language at the same time.

```bash
npx @microsoft/teams.cli new <typescript | csharp | python> quote-agent --template echo
```

The angle-bracket choice in that command is literal in the README, so you replace it with one of the three listed languages. Running it should produce a project named quote-agent with the echo template wired in, which gives you something that runs before you add any of your own logic.

For language-specific setup steps, the README points to per-language quickstart guides for C#, TypeScript and Python in the documentation site. Agent Accelerator Templates are offered separately as open-source starting points in the Teams Agent Accelerators repository, described as a good starting point for building your own agents on top of the SDK. The CLI is therefore one part of a larger path: templates for a scaffold, the SDK for the application logic, and the per-language quickstart for the wiring.

## The App object and its plugins carry the whole application

The shortest complete example in the README shows the shape of a v2 application. You construct an App from the teams.apps package, pass it a list of plugins, register a handler for the message activity, and start it.

```typescript
import { App } from '@microsoft/teams.apps';
import { DevtoolsPlugin } from '@microsoft/teams.dev';
import * as endpoints from '@microsoft/teams.graph-endpoints';

const app = new App({
  plugins: [new DevtoolsPlugin()],
});

// Listen for incoming messages
app.on('message', async ({ userGraph, isSignedIn, send, signin }) => {
  if (!isSignedIn) {
    await signin(); // initiates Entra login flow
    return;
  }
  const me = await userGraph.call(endpoints.me.get);
  await send(`Hello, ${me.displayName} from Earth!`);
});

// Start your application
(async () => {
  await app.start();
})();
```

Several design choices are visible in that snippet. Capabilities arrive as plugins, and the DevtoolsPlugin is imported from a separate @microsoft/teams.dev package, so development tooling is additive rather than baked in. Graph calls are exposed as a generated endpoint namespace: userGraph.call(endpoints.me.get) passes a descriptor rather than a URL, and the endpoints come from the @microsoft/teams.graph-endpoints package.

The handler receives a context object with the sending capability, the sign-in trigger and the Graph client. When the user has not signed in, the handler calls signin(), which the comment identifies as the Entra login flow, and returns without replying. Authentication is therefore part of the message flow itself, not a separate middleware you configure. send() takes a plain template string, so the Graph display name lands in an f-string-style interpolation.

## The v1 to v2 branch switch is the main upgrade decision

The repository carries an explicit transition notice. The main branch now contains v2 code, which was previously developed on the v2-preview branch, and the previous main branch with v1 code has been moved to a release/v1 branch. The README states that critical bug fixes and security patches for v1 will continue on that branch.

That is a specific maintenance promise, narrower than ongoing feature work, and it defines the upgrade cost for anyone still on v1. The upgrade itself is a branch and package change rather than a code edit, but the application rewrite is not: v2 replaces the old registration and activity handling model with the App object, plugins and a context-based handler, so existing botframework-style code has to be restructured around those concepts even though the project states that compatibility with existing botframework-based agents is maintained.

The README points to a separate WHY.md document for the motivations behind v2. Architecturally, this repository also carries a .gitmodules file, an ARCHITECTURE-style split between packages/, plugins/ and teams.md/, and a SECURITY.md alongside a RELEASE.md, which suggests the SDK ships through a release process with published security guidance rather than only through source builds.

Whether to migrate is therefore a judgement about your own code rather than about the framework: staying on release/v1 is supported, but only for critical fixes, while new v2 capabilities land on main.

## The CLI releases and the repository push tell two different stories

Maintenance signals here come from two places, and they disagree in an instructive way. The last push to this repository was on 2026-10-19, so the source tree is moving. The published CLI releases are named with a cli prefix and run 3.0.2, 3.0.3 and 3.0.4, with 3.0.4 published on 2026-10-09, and both 3.0.3 and 3.0.2 published on 2026-07-08.

The practical consequence is that a team consuming the CLI from npm may be several releases behind the code in main, and the naming makes the split visible: the CLI has its own version line, separate from the SDK packages. If you scaffold with a CLI version and then read the v2 documentation on the site, you can end up with a generated project that predates the current main branch.

The repository is MIT licensed, and the LICENSE file sits at the root next to CONTRIBUTING.md, SECURITY.md and RELEASE.md. Because the SDK is distributed as npm packages under that licence, adopting it means the usual obligations of MIT apply to redistributed binaries and code, and nothing in the project states additional commercial terms for Teams apps themselves. That part is a question for Microsoft's platform terms rather than for this repository.

Nothing in the root package.json shows how releases are cut from it, so the publish process itself is documented outside the files visible here, in RELEASE.md and in the CI configuration under .azdo/ and .github/.

## Where the framework stops and the platform documentation takes over

Two limits are worth stating plainly before you invest in this. The first is that teams-sdk is a framework for building on top of Teams, not a substitute for the Teams platform itself. The sample handler still has to trigger an Entra login flow for Graph access, and the sign-in experience, the manifest and the deployment story live in the wider Teams documentation, not in this repository.

The second is that the official alternative is the older path, and it is a genuine alternative rather than a dead end. An agent written against botframework-based patterns still runs, and the SDK's stated goal is compatibility with those agents. The practical difference in approach is architectural. The v1 world is a bot registration model with the SDK reached through a framework client; the v2 world is an App instance you construct in code, with capabilities attached as plugins, a single event surface for incoming messages, and typed Graph endpoint descriptors instead of hand-written URLs. v2 also adds the AI-focused capability areas and message extensions as first-class goals, while v1 stays where it is and receives only critical fixes and security patches on release/v1.

So the choice is not new framework versus nothing. It is a restructured application with a plugin model and Graph support against a supported but frozen branch.

## A first v2 app is one command and one handler

To summarise the smallest working path the documentation actually shows. Install the CLI globally with `npm install -g @microsoft/teams.cli`, then generate a project with `npx @microsoft/teams.cli new <typescript | csharp | python> quote-agent --template echo`. Open the generated code and you will find an App constructed from @microsoft/teams.apps, a DevtoolsPlugin from @microsoft/teams.dev attached to it, and a message handler registered with app.on('message'). Inside the handler, check isSignedIn, call signin() when it is false, otherwise fetch the signed-in profile through userGraph.call(endpoints.me.get) with an endpoint descriptor imported from @microsoft/teams.graph-endpoints, and reply with send(). The application ends with an awaited app.start().

The two things to verify before going further are the CLI version your project ended up with, since published CLI releases and the main branch move on separate schedules, and the language repository your questions belong to, since the Python, C# and TypeScript SDK code lives in three separate repositories. Both checks take a minute and both decide whether the next hour of work is aimed at the right code.

## Conclusion

teams-sdk fits teams building a new Teams agent or application on the v2 line, particularly when the plan involves Graph access, message extensions or embedded web experiences inside Teams. It does not fit codebases that want to stay on the v1 architecture, where support now means critical bug fixes and security patches on the release/v1 branch, nor does it fit a team that expects the SDK source itself in this repository. Before adopting it, verify the CLI version your project pins, because the published CLI releases run from 3.0.2 to 3.0.4 while the main branch holds v2 code, and confirm which of the three language repositories your issue belongs to.

## FAQ

### How do I install the Teams SDK and create a new agent project?

Install the Teams Developer CLI with `npm install -g @microsoft/teams.cli`, then run `npx @microsoft/teams.cli new <typescript | csharp | python> quote-agent --template echo`, choosing one of the three languages. The README points to per-language quickstart guides for the remaining setup.

### Is teams-sdk a single npm package or a monorepo?

This repository is a private npm workspace root that drives builds, linting and tests through turbo, with workspaces covering `packages/*` and `teams.md`. The SDK code itself lives in separate repositories: microsoft/teams.ts, microsoft/teams.net and microsoft/teams.py.

### What is the difference between teams-sdk v1 and v2?

The main branch now holds v2 code, which was developed on the v2-preview branch, while the old v1 main branch moved to release/v1 where critical bug fixes and security patches continue. v2 keeps compatibility with existing botframework-based agents and adds an App and plugin architecture with Graph, message extensions and AI agent support.

### Does teams-sdk support Graph calls and user sign-in?

Yes. The handler receives a userGraph client and an isSignedIn flag, and the README example calls `signin()` to initiate the Entra login flow when the user is not signed in. Graph calls use endpoint descriptors imported from @microsoft/teams.graph-endpoints, as in `userGraph.call(endpoints.me.get)`.

### Which license does teams-sdk use?

The project is MIT licensed, with a LICENSE file at the repository root next to CONTRIBUTING.md, SECURITY.md and RELEASE.md. No additional commercial terms for Teams applications themselves are stated in the repository.

## Sources

- [Issues](https://github.com/microsoft/teams-sdk/issues)
- [License: MIT](https://github.com/microsoft/teams-sdk/blob/main/LICENSE)
- [microsoft/teams-sdk on GitHub](https://github.com/microsoft/teams-sdk)
- [README](https://github.com/microsoft/teams-sdk/blob/main/README.md)
- [Releases](https://github.com/microsoft/teams-sdk/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/microsoft-teams-sdk