Registering an agent on the Teams platform

Creating and hosting an agent runtime is not enough to make a Teams agent available to users. You must also register your agent at the beginning of the development process by creating configuration for it across three services:

  • Microsoft Entra ID: An Entra ID app registration is the agent's unique identity within the Microsoft 365 ecosystem, used for service authentication and consented access to user data.
  • Agent Communication Service (ACS): Registering the agent with ACS enables it to participate in Teams chat and receive realtime information about user activities in Teams.
  • Teams platform: An app manifest registered in Teams Developer Portal establishes an agent as a distributable, installable Teams app.

By registering an agent at the beginning of development, you can use it in Teams as it takes shape, verifying its behavior and experiencing it exactly as users will.

This article explains the service registrations needed to enable a Teams agent to interact with Teams. A deep understanding of these concepts is not needed to begin Teams agent development: you can use the quickstart to quickly create and register a new agent and refer to this guide as needed to build a more complete understanding.

Entra ID app registration: identity and authentication

Microsoft Entra ID is the identity and access management service used by Teams and Microsoft 365. An app registration in an Entra tenant owned by your organization is your agent's globally unique identity for its lifetime, and enables multiple agent capabilities:

  • Authentication to ACS: An agent's ACS registration is uniquely associated with an app registration, which is configured with the agent's runtime app credentials.
  • Authentication to organizational resources: Many agents directly access organizational data and services, such as Microsoft Graph, to power collaboration features.
  • On-behalf-of flows with single sign-on (SSO) and OAuth: Users can delegate access to agents, granting consent for them to access data and services on their behalf.
  • Obtaining consent for privileged operations in Teams: Certain agent actions in Teams require consent from administrators and users.

Every agent will have one primary Entra ID app registration, linked to its ACS registration, used to uniquely identify it. In some cases, agent implementations might use multiple app registrations to support identity scenarios across different contexts.

For more information about Entra ID app registrations, see Application and service principal objects in Microsoft Entra ID.

Agent Communication Service (ACS) registration: an agent's interface to Teams

An agent's connectivity with ACS is what makes it a Teams agent: ACS serves the API that an agent's runtime uses to interact with Teams functionality, especially chat. Before your agent can access Teams, you need to register it with the service.

Every agent's ACS registration and primary Entra ID app registration are uniquely and permanently linked. To authenticate to ACS, the agent's runtime uses a credential configured in the app registration, like a client secret or an Azure managed identity.

An ACS registration also contains a small amount of agent configuration, most importantly the agent's runtime endpoint URL. Whenever activity occurs in Teams that is visible to the agent, in any tenant where it's installed, ACS sends requests to this endpoint that the agent's runtime processes using an event-handling pattern.

ACS supports two different kinds of registration: Teams-managed and Azure-managed. See Choose an Agent Communication Service registration type for an agent for more information.

App manifest: define and distribute

An agent's app manifest is a JSON configuration file that contains everything needed by the Teams platform to distribute it and install it in Teams clients. It includes, for example:

  • The agent's name and description
  • Information about the agent's developer
  • The agent's bot ID (the unique ID shared by its ACS registration and its Entra ID app registration)
  • Platform-level configuration needed for certain agent features
  • A list of RSC permissions the agent requires in order to function

Registering an agent's app manifest in Teams Developer Portal is what establishes it as an installable Teams app that can be distributed in the Teams store or your organization's app catalog. Certain agent features require configuration in the app manifest, and as you add those features during development, you can use the web interface of Teams Developer Portal to update the app manifest.

App manifests conform to the app manifest schema, which evolves as Microsoft releases new Teams platform features.

Registering an agent with Teams developer CLI

teams app create fully registers an agent. It creates:

  1. An Entra ID app registration in your tenant, configured with a client secret
  2. A Teams-managed ACS registration linked to the Entra ID app registration
  3. A a starter app manifest, registered in the Teams Developer Portal, configured to use the Teams-managed ACS registration
  4. A local agent runtime configuration file (a .env file for a TypeScript or Python runtime, or an appsettings.json file for .NET) that your agent will use to authenticate to ACS using the client secret

Next steps

See also

  • อัปเดตล่าสุดเมื่อ