Skip to main content

Teams Core Concepts

Running an agent on Teams involves several moving pieces — an app registration, an Azure or Teams-managed bot, a public messaging endpoint, and a sideloaded app package. Understanding these components helps you debug and deploy your agent confidently. The Teams Developer CLI automates all of them with a single teams app create command, but it's worth knowing what it sets up underneath.

Basic Flow​

Teams

  • Teams Client: User-facing agent that interacts with the user.
  • Teams Backend: Part of your app package; includes a manifest with your app’s client ID.

Azure

  • App Registration: Contains a unique client ID and secret for your app.
  • Azure Bot: Connects your app to Teams; contains a pointer to your HTTPS URL.

Local Server

  • Dev Tunnel: Public-facing HTTPS tunnel to expose your local machine.
  • Local App: Your application running locally; handles events from Teams and sends responses.

Deployed Server

  • Deployed App: Your app deployed to the cloud with a public HTTPS endpoint; also interacts with Teams.

Core Concepts​

When working with Teams, these are the key concepts. Keep in mind, this is a simplified view of the architecture.

  • Teams Client: This is the Teams application where users interact with your agent. This can be the desktop app, web app, or mobile app.
  • Teams Backend: This service handles all the Teams-related operations, including keeping a record of your manifest, and routing messages from your agent to the Azure bot service.
  • App Registration: This is the registration of your agent in Azure. This Application Registration issues a unique client ID for your application and a client secret. This is used to authenticate your agent application with the Teams backend and other Azure services (including Graph if you are using it).
  • Azure Bot Service: This is the service that handles all the bot-related operations, including routing messages from Teams to your agent and vice versa. This holds the URL to your agent application.
  • DevTunnel: This is a service that creates a public facing URL to your locally running application. Azure Bot Service requires that you have a public facing https URL to your agent application.
  • Local Agent Application: This is your agent application running on your local machine.
  • Deployed Agent Application: This is your deployed agent which probably has a public facing URL.

DevTunnel​

DevTunnel is a critical component that makes your locally running agent accessible to Teams. When you set up a DevTunnel, it:

  • Creates a secure public HTTPS endpoint that forwards to your local server
  • Manages SSL certificates automatically
  • Routes Teams messages and events to your local agent
info

DevTunnel is only one way of exposing your locally running service to the internet. Other tools like ngrok can also accomplish the same thing.

Teams App Provisioning​

Before your agent can interact with Teams, it needs to be properly registered and configured. This step handles creating or updating the App Registration and creating or registering the Azure Bot instance in Azure.

App Registration​

  • Creates an App ID (i.e. Client ID) in the Teams platform
  • Sets up a bot registration with the Bot Framework
  • Creates a client secret that your agent can use to authenticate to send and receive messages. The Teams Developer CLI writes this value to .env (or appsettings.json for C#) automatically when you run teams app create.

Azure Bot​

  • Creates an Azure Bot resource (with --azure) or a Teams-managed bot registration (default)
  • Associates the bot with your App Registration
  • Configures the messaging endpoint to point to your DevTunnel (or public URL if deployed)

Sideloading Process​

Sideloading is the process of installing your agent in Teams. You are able to pass in the manifest and icons (zipped up) to the Teams client. Sideloading an application automatically makes that application available to you. You are also able to sideload the application in a Team or a Group chat. In this case, the application will be available to all members of that Team or Group chat.

warning

Sideloading needs to be enabled in your tenant. If this is not the case, then you will need to contact your Teams administrator to enable it.

Provisioning and Deployment​

To test your app in Teams you need, at minimum, a provisioned bot. You'll likely also have other resources such as storage.

The fastest path is teams app create, which provisions a Teams-managed bot by default — no Azure subscription required. See the Quickstart: Register your app.

If you need OAuth or SSO (typically for delegated Microsoft Graph access on behalf of a user), the bot must be Azure-managed. Either start with teams app create --azure --subscription <id> --resource-group <rg>, or start Teams-managed and switch later with teams app bot migrate <appId> --subscription <id> --resource-group <rg> (both require an Azure subscription) — your CLIENT_ID, CLIENT_SECRET, and TENANT_ID stay the same. For a hand-rolled Azure setup, follow the Azure Configuration guide.

For deploying your bot's endpoint to App Service, Container Apps, or other Azure compute, see the Microsoft Learn deployment overview.