Skip to main content

Microsoft Teams

Use Microsoft Teams with Mastra in two ways:

  • Agent tools let an agent act in Teams, for example to read and send messages or manage channels.
  • Agent chat lets people talk to your agent through Teams mentions and conversation events.

Mastra Connect sets up both and registers the Teams bot for you, so you don't need your own Azure app registration. You can also register the bot and manage its credentials yourself.

Connect
Direct link to Connect

Before you start, complete the Connect setup to install @mastra/connect and configure your platform project.

One microsoft-teams connection provides both agent tools and agent chat. Sign in with a Microsoft work or school account. Some requested permissions need admin consent, so the first connection in a tenant needs a Microsoft Entra administrator.

Agent tools
Direct link to Agent tools

Give agents tools to read and send channel and chat messages, and manage teams, channels, chats, and members in Microsoft Teams.

Connect an account with the microsoft-teams provider ID. Run this command from the directory that contains your .env file:

mastra connect add microsoft-teams

Then pass tools() to the agent and select the provider:

src/mastra/agents/microsoft-teams-agent.ts
import { Agent } from '@mastra/core/agent'
import { tools } from '@mastra/connect'

export const microsoftTeamsAgent = new Agent({
id: 'microsoft-teams-agent',
name: 'Microsoft Teams agent',
instructions:
'You help people read and send channel and chat messages, and manage teams, channels, chats, and members in Microsoft Teams.',
model: '__GATEWAY_OPENAI_MODEL_LUNA__',
tools: tools({ providers: ['microsoft-teams'] }),
})

The agent gets 25 Microsoft Teams tools, with keys such as microsoft_teams_add_team_member. See Microsoft Teams tools for the full list, and the tools() parameters to restrict tools or require approval before a call runs.

Agent chat
Direct link to Agent chat

When you connect an agent, Mastra registers a bot for it in the Teams Developer Portal. Mastra stores the bot credential encrypted. Set MASTRA_ENCRYPTION_KEY to use a dedicated key. Without it, channels() derives a key from the platform access token and logs a warning. If you then rotate the platform access token, Mastra can't read the stored bot credentials. Disconnect and reconnect the channel to create new ones.

Your server needs a public URL for Teams webhooks and OAuth callbacks. Mastra platform supplies this URL. When you host elsewhere, set MASTRA_SERVER_URL to your public server URL. For local development, use a public HTTPS tunnel.

  1. If you haven't added the connection yet, run mastra connect add microsoft-teams and sign in.

  2. Pass channels() to the Mastra constructor. It registers the Teams channel provider and its routes:

    src/mastra/index.ts
    import { Mastra } from '@mastra/core'
    import { channels } from '@mastra/connect'
    import { assistant } from './agents/assistant'

    export const mastra = new Mastra({
    agents: { assistant },
    channels: await channels({ providers: ['microsoft-teams'] }),
    })

    To register other channels too, add their provider IDs to providers.

  3. Start your Mastra application.

  4. In Studio, connect the Teams channel to an agent. Mastra creates a single-tenant bot registration for the agent and returns a link to the Teams Developer Portal.

  5. Open the link, package the bot into a Teams app in the Developer Portal, and add the app to Teams.

Disconnecting the agent deletes the bot registration and its Entra application.

Self-managed setup
Direct link to Self-managed setup

Use the Chat SDK Teams adapter with your own Azure bot registration and credentials.

Install the adapter
Direct link to Install the adapter

Install the Teams adapter from the Chat SDK:

npm install @chat-adapter/teams

Agent configuration
Direct link to Agent configuration

Add createTeamsAdapter() to the agent's channels.adapters object:

src/mastra/agents/teams-agent.ts
import { Agent } from '@mastra/core/agent'
import { createTeamsAdapter } from '@chat-adapter/teams'

export const teamsAgent = new Agent({
id: 'teams-agent',
name: 'Teams Agent',
instructions: 'Answer questions and help with tasks in Microsoft Teams.',
model: 'openai/gpt-6.1-sol',
channels: {
adapters: {
teams: createTeamsAdapter({
appType: 'SingleTenant',
}),
},
},
})

Register the agent on the Mastra instance:

src/mastra/index.ts
import { Mastra } from '@mastra/core'
import { teamsAgent } from './agents/teams-agent'

export const mastra = new Mastra({
agents: { teamsAgent },
})

Adapter setup
Direct link to Adapter setup

Follow the Chat SDK Teams adapter docs for Teams-specific setup, including Azure bot registration, Teams CLI usage, authentication options, and required permissions.

The adapter reads Teams credentials from environment variables such as:

.env
TEAMS_APP_ID=your-azure-bot-app-id
TEAMS_APP_PASSWORD=your-azure-bot-app-password
TEAMS_APP_TENANT_ID=your-azure-tenant-id

Webhook URL
Direct link to Webhook URL

Mastra generates the Teams webhook route from the agent ID and adapter key:

/api/agents/teams-agent/channels/teams/webhook

Use your public Mastra server URL as the base URL:

https://your-app.example.com/api/agents/teams-agent/channels/teams/webhook

Use this URL anywhere the Teams adapter docs ask for the bot endpoint or webhook URL. For local development, expose the Mastra dev server with a tunnel and use the tunnel URL as the base URL.