Microsoft Teams SDK

The Teams Developer CLI is a command-line tool designed for managing Microsoft Teams apps. It allows developers to automate the lifecycle of Teams apps, manage bot registrations, and handle authentication credentials directly from the terminal.

Key Capabilities:

• App Lifecycle Management: Create, retrieve, update, and manage Teams apps, including operations on manifests and packages.
• Bot Registration: Register bots with Microsoft Teams or Azure, migrate bots between platforms, and configure messaging endpoints.
• Authentication Management: Generate client secrets for Azure Active Directory (AAD) applications and manage bot credentials.
• AI Agent Integration: Provides structured JSON help output, making the CLI easy to consume via AI coding agents and automated workflows.

The Teams SDK provides several tools to accelerate the development and testing of agents:

• Teams Developer CLI: Used for scaffolding and managing projects.
• Microsoft 365 Agents Playground: Allows for local testing of agents without the need to sideload them into Microsoft Teams.
• Local Tunnels: Tools to expose your local development server publicly, which is required for Teams, message extensions, and other webhooks to communicate with your local environment.
• Agent Skills: Contextual information provided to AI coding assistants to assist in Teams development.
• llms.txt: Documentation files specifically optimized for consumption by AI coding assistants.

The @microsoft/teams.client package is designed to streamline common interaction patterns for Tab apps that need to communicate with remote services. It builds on TeamsJS and MSAL to simplify the following tasks:

• Remote Service Authentication: Uses MSAL-based authentication and token acquisition.
• Graph API Integration: Provides a pre-configured and type-safe Microsoft Graph client.
• Agent Function Calling: Handles authentication and automatically includes app context when calling server-side functions implemented via Teams SDK agents.
• Scope Consent Management: Offers simple APIs to check for user consent and request it when necessary.

To ensure secure user consent and allow remote services to authenticate the user, these interactions should leverage Nested App Authentication (NAA).

The Python Teams Echo Bot template is organized into the following key files:

• src/main.py: Contains the main application logic for the Teams bot.
• pyproject.toml: Defines the project metadata and required dependencies.

This template utilizes the microsoft-teams library.

The 2.1 preview currently supports the following development scenarios:

• Messages: Handling, regex routing, updates, deletes, and reactions.
• Adaptive Cards: Action submissions with typed value access.
• Task modules: Fetching and submitting dialogs.
• Message extensions: Search queries.
• OAuth and SSO: Per-flow sign-in with automatic SSO.
• Conversation events: Members added/removed, and install/uninstall events.
• Streaming: Progressive message updates with rate limiting.
• Proactive messaging: Sending messages and replies outside of a turn.
• Agentic identity: Acting on behalf of users using their permissions.
• Targeted messages: Messages visible only to a specific user.

The Teams SDK supports building a wide variety of Microsoft Teams experiences across TypeScript, C#, and Python. Supported capabilities include:

• AI-powered agents
• Message extensions
• Embedded web apps
• Adaptive Cards
• Dialogs
• Microsoft Graph integrations

Language-Specific Guides

• TypeScript guide
• C# guide
• Python guide

This template provides a Microsoft Teams bot application that includes a personal tab built with Vite. The project structure is divided into two main parts:

• src/index.ts: Contains the main bot application logic.
• src/Tab/: Contains the React application for the personal tab, which is bundled using Vite.

In Teams SDK 2.1, Turn middleware is the mechanism used to run logic on every activity received by your application before that activity reaches your specific activity handlers. It is designed for cross-cutting concerns such as logging, metrics collection, and request enrichment.

The execution flow follows this sequence:

1. Teams sends an Activity.
2. The App Server (ASP.NET Core) receives it.
3. Turn Middleware executes (in registration order).
4. Dedicated Activity Handlers execute.

If you need logic to apply to the entire application lifecycle for every interaction, use Turn middleware.

For decisions requiring explicit outcomes (e.g., 'Approve' or 'Reject'), use an approval flow mirroring the 'ask' pattern:

1. request_approval: Sends an Adaptive Card with explicit buttons and returns an approvalId.
2. wait_for_approval: Blocks until the user makes a decision.

Responses are captured via a card-action handler (e.g., approval_response) which wakes up the waiting caller.

Integrating an agent with Microsoft Teams involves four primary pillars:

• DevTunnel: Used for local development to create secure public endpoints, allowing Teams to communicate with your local machine.
• App Provisioning: The process of registering and configuring your agent within the Teams platform.
• Environment Setup: Managing the specific configuration files required for Teams-compatible environments.
• App Packaging: The final step of bundling your agent into a format suitable for Teams deployment.

Depending on your environment, you may follow the standard SDK flow or a manual Azure Configuration path if you are working with existing Entra apps, locked-down environments, or custom tenant policies.

In Slack Bolt, you handle different event subtypes (e.g., event.subtype == 'file_share'). In the Teams SDK, you use Activity handlers based on the ActivityTypes enum.

While the syntax differs, the logic is similar. You can use specific handlers like app.activity(ActivityTypes.Message) or use the tailored app.message API for standard text messages.

The SDK produces a structured span hierarchy for every incoming activity. Auto-instrumented libraries like ASP.NET Core and HttpClient add their own spans as children.

Span Hierarchy Example:

HTTP server span                       (auto — ASP.NET Core)
└─ turn                                (Microsoft.Teams.Core)
   ├─ middleware [n times]             (Microsoft.Teams.Core)
   ├─ handler                          (Microsoft.Teams.Apps)
   └─ conversation_client              (Microsoft.Teams.Core)
      ├─ auth.outbound                 (Microsoft.Teams.Core)
      │  └─ HTTP client span           (auto — token endpoint)
      └─ HTTP client span              (auto — Bot Service API)

Key Attributes: The turn span is enriched with the following metadata:

• activity.type
• activity.id
• conversation.id
• channel.id