Appearance
Microsoft Teams agents
A Teams agent wakes when someone @mentions it in a channel or group chat, messages it in a personal chat, or posts in a channel it watches. It answers in the same reply chain. teamsChannel() takes the same engagement options as slackChannel(), so an agent that already runs in Slack can run in Teams with the same shape of config.
The agent answers as an Azure Bot that you register and own. Teams sends each message to the bot's messaging endpoint, and the channel checks the Bot Framework token on every request before it starts a turn.
Set up with the CLI
The agent-sdk channels teams commands do every step except the clicks in the Azure portal and in Teams:
bash
agent-sdk channels teams setup
printf %s "$CLIENT_SECRET" | agent-sdk channels teams init --dir ./helm \
--app-id <microsoft-app-id> --tenant-id <app-tenant-id>
agent-sdk channels teams package --dir ./helm
agent-sdk dev ./helm
agent-sdk channels teams doctor --dir ./helm --endpoint <printed URL>setupprints the Azure portal steps in Register the Azure Bot.initwritesbot/channels/teams.tsand puts the app id, the client secret, and the tenant id in.env.local. It reads the secret from a hidden prompt or stdin, never from an argument.packagewriteshelm-teams-app.zip. Upload it in Teams, as Install the bot in Teams describes.devopens a tunnel and prints the messaging endpoint. Set it on the Azure Bot.doctorchecks the env names, the token, the Azure Bot, and the endpoint, and names the part that fails.
The CLI reference lists every flag. The rest of this guide explains what the commands write and how the channel behaves.
Answer a mention or personal chat
ts
// bot/channels/teams.ts
import { teamsChannel } from "@grok/agent-sdk/channels/teams";
export default teamsChannel();By default the agent answers @mentions in channels and group chats, and every message in a personal chat. While a turn runs, Teams shows the typing indicator, and the reply arrives as one message in the reply chain. In a channel, each reply chain is its own conversation. A personal chat and a group chat have no reply chains, so each one is a single conversation.
The channel reads three variables:
| Variable | Value |
|---|---|
TEAMS_APP_ID | The Azure Bot's Microsoft App ID |
TEAMS_APP_PASSWORD | A client secret of that app registration |
TEAMS_TENANT_ID | Required. The home tenant of your single-tenant Azure Bot |
The Azure Bot is a single-tenant bot in your own tenant, because Azure does not create new multi-tenant bots after July 31, 2025. The channel mints its Bot Connector token in that tenant and ignores activities from any other tenant. To run several agents in one agent-sdk dev, give each its own bot and an envPrefix. channels teams init --prefix HELPDESK writes it for you. The prefix starts with a letter.
ts
export default teamsChannel({ envPrefix: "HELPDESK" });
// HELPDESK_TEAMS_APP_ID, HELPDESK_TEAMS_APP_PASSWORD, HELPDESK_TEAMS_TENANT_IDThe channel file owns these names. When the file exists, init writes the names it reads, and doctor and package read them from the loaded channel.
Register the Azure Bot
- In the Azure portal, create an Azure Bot resource. Set Type of App to Single Tenant and Creation type to Create new Microsoft App ID.
- Open the bot's Configuration page. Copy Microsoft App ID and App Tenant ID.
inittakes them as--app-idand--tenant-id. - From Configuration, open Manage Password, add a client secret, and copy its value. Azure shows the value once.
initreads it from the hidden prompt or stdin. - Under Channels, add Microsoft Teams.
- Set Messaging endpoint to the URL in Messaging endpoint, or for a hosted deploy, the URL in Deploy.
Install the bot in Teams
Teams installs a bot from an app package: a zip of manifest.json and two icons. agent-sdk channels teams package builds it from the channel. The bots entry names the Azure Bot by its app ID and the places people can talk to it:
json
{
"id": "<TEAMS_APP_ID>",
"bots": [
{
"botId": "<TEAMS_APP_ID>",
"scopes": ["personal", "team", "groupChat"],
"isNotificationOnly": false
}
]
}A full manifest also needs manifestVersion, version, developer, name, description, icons, and accentColor; see the app manifest schema. Upload the package in Teams under Apps > Manage your apps > Upload an app, or have a Teams admin publish it to your organization in the Teams admin center. Then add the app to a team, a group chat, or a personal chat.
Wake on a channel post
Teams sends a channel post without a mention only to an app that holds the resource-specific consent permission ChannelMessage.Read.Group. package adds it when the channel sets engagement.channelPosts, and a team owner grants it when they add the app to the team:
json
{
"webApplicationInfo": { "id": "<TEAMS_APP_ID>" },
"authorization": {
"permissions": {
"resourceSpecific": [{ "name": "ChannelMessage.Read.Group", "type": "Application" }]
}
}
}Then name the channels to watch. Copy a channel's ID from its Get link to channel URL: it's the 19:…@thread.tacv2 part.
ts
export default teamsChannel({
engagement: {
channelPosts: {
allow: ["19:4b7c2f9e1d6a4e8f9a3b5c7d1e2f3a4b@thread.tacv2"],
posts: "all",
},
},
});Watched posts go to onChannelPost when you set it, the same way mentions go to onAppMention and personal chats to onDirectMessage. Return null from a hook to skip a message. posts is "top-level" (the default), "replies", or "all". Use allow: ["*"] to watch every channel the app is in, and replies: "joined" to also answer replies in any reply chain the agent already answered. Bot posts stay out unless you set includeBotPosts: true; the agent's own posts never start a turn.
To let another bot wake the agent with an @mention, list it in engagement.botMentions.allowFrom as 28:<its app ID>. Each thread allows 5 bot wakes an hour and 20 in total by default (maxPerThreadPerHour, maxPerThreadTotal).
Stream the reply
ts
export default teamsChannel({ reply: { mode: "stream" } });In stream mode the agent posts one message as soon as it starts working. That message names the tool the agent is running until text arrives, then fills in as the reply grows, and it ends as the final answer. Teams limits how often a bot can edit a message, so the channel edits at most once every 1.5 seconds; set updateIntervalMs to change that.
Approve tool calls in Teams
ts
export default teamsChannel({ toolApprovals: true });When a server tool with needsApproval is about to run, the agent posts an Adaptive Card in the thread with the tool's arguments, secrets redacted, and Approve and Deny buttons. Anyone who could continue the conversation can decide; set policy: { respondTo: "author" } to limit that, and follow-ups, to the person who started it. After the click, the card shows the decision and who made it.
For your own cards, handle other Action.Submit clicks in onCardAction, which receives the submitted data and can start a turn in the card's thread.
Refuse guests and other tenants
By default the channel answers only members and owners of the bot's tenant. It asks Teams for the sender's role and tenant. It refuses a guest, an anonymous meeting user, or a person from another organization. This applies when they message the agent and when they click a card. Approve and Deny are card clicks. A sender with no role is refused. A sender Teams does not list is refused too.
The agent posts one short reply to a refused sender. It posts at most once per conversation and sender per hour. The default text is "I can only help members of this organization. Ask the agent owner to allow guests."
Set policy.refusalMessage to change the default text. Set policy.refusalMessage to false to stay silent. Silence applies to a refused sender and to a sender the lookup could not verify.
A failed lookup gets the reply "I couldn't verify your access, try again shortly." The agent does not reply to a card click from a refused sender. The agent ignores a card click from a bot, including a bot that engagement.botMentions allows. The agent does not reply to an activity from another tenant.
To let guests and external members in, set blockExternals to false.
ts
export default teamsChannel({ policy: { blockExternals: false } });ts
export default teamsChannel({
policy: {
refusalMessage: "Ask your team owner to add you to this organization.",
},
});Welcome message
When someone installs the app in a conversation, the agent posts one greeting there. Teams reports the install as an installationUpdate activity whose action is add. The greeting does not start a model turn. The agent posts it once per conversation.
The default text is "Hi! Mention me in a channel, or message me here, to get started."
Set welcome to change the greeting. Set welcome to false to turn it off.
ts
export default teamsChannel({
welcome: "Hi. Mention me when you want help with a laptop.",
});Messaging endpoint
Under agent-sdk dev or self-hosted agent-sdk serve, the Azure Bot's messaging endpoint is the server's public origin plus the channel's path:
text
https://<origin>/<slug>/v1/channels/<channel><slug> is the agent's slug and <channel> is the channel file's name, so bot/channels/teams.ts in the helm agent answers at https://<origin>/helm/v1/channels/teams. The URL has no trailing slash. With teamsChannel({ path: "/messages" }), the channel appends that path: https://<origin>/helm/v1/channels/teams/messages. A hosted deploy has a different URL; see Deploy.
Test locally
Teams reaches the bot only at a public HTTPS URL. agent-sdk dev opens a cloudflared tunnel and prints the messaging endpoint on the tunnel's origin:
bash
agent-sdk dev ./helmCopy the printed URL into the Azure Bot's Messaging endpoint, then mention the bot in Teams. --tunnel devtunnel keeps one URL across restarts. Next to a plain agent-sdk serve, agent-sdk channels teams forward opens the same tunnel. agent-sdk dev --mode single serves one agent without a slug, so its endpoint is https://<origin>/v1/channels/teams. Without --mode single, the endpoint includes the agent's slug: https://<origin>/helm/v1/channels/teams.
To run your own tunnel instead, serve with plain agent-sdk serve, which opens no tunnel, and point cloudflared at its port:
bash
agent-sdk serve --dir ./helm --mode single --port 3978
cloudflared tunnel --url http://localhost:3978Add --protocol http2 to cloudflared if your network blocks QUIC. Set the Azure Bot's Messaging endpoint to the printed <public-url> plus /v1/channels/teams, or <public-url>/helm/v1/channels/teams without --mode single. The built-in tunnel forwards only POST requests to the Teams messaging paths. A tunnel you run yourself exposes every route on the port.
Requests through a tunnel always get the Bot Framework token check, so only Teams can start turns there. A tunnel adds proxy headers or forwards its public hostname, and the dev exception for unsigned activities refuses both. To replay a saved activity without Teams, POST it to the same path on http://127.0.0.1:<port> from the same machine; agent-sdk dev admits unsigned activities from loopback only.
Deploy
Hosted, the agent needs its three secrets:
ts
// bot/agent.ts
import { defineAgent } from "@grok/agent-sdk";
export default defineAgent({
hosting: {
secretNames: ["TEAMS_APP_ID", "TEAMS_APP_PASSWORD", "TEAMS_TENANT_ID"],
},
});Hosting adds the Microsoft hosts that a Teams channel calls (login.microsoftonline.com, login.botframework.com, and smba.trafficmanager.net), so you do not list them in egressDomains. Your team's network settings still apply to them. If your team restricts egress, its allowlist must include all three hosts, or the agent's replies fail.
An envPrefix changes the secret names. With teamsChannel({ envPrefix: "ECHO" }), list ECHO_TEAMS_APP_ID, ECHO_TEAMS_APP_PASSWORD, and ECHO_TEAMS_TENANT_ID in secretNames, and set those names with agent-sdk secret set.
bash
agent-sdk deploy --dir . --slug helpdesk
agent-sdk secret set helpdesk TEAMS_APP_ID
agent-sdk secret set helpdesk TEAMS_APP_PASSWORD
agent-sdk secret set helpdesk TEAMS_TENANT_IDagent-sdk deploy prints the hosted messaging endpoint on a public: line of the form https://api.cursor.com/v1/agent-sdk/<applicationId>/channels/teams (with /<slug> before /channels/ in a multi-agent deploy). Set the Azure Bot's Messaging endpoint to that URL, not to the slug URL from local testing. With a custom path, add it after the printed URL.
On CLI 0.7.1 and older, agent-sdk channels teams doctor fails its endpoint path check on /v1/agent-sdk/... URLs; deploy and running bots are unaffected, and 0.7.2 accepts the new URL.
On hosting, Cursor checks the Bot Framework token and the tenant before the agent starts. Activities that the channel cannot act on, such as a reaction or an unmentioned post outside channelPosts, stop there and use no compute. Each personal or group chat is one session, and each channel reply chain is one session. Tool approvals work on hosting: an Approve or Deny click reaches the turn that waits for it, and a call that nobody approves in 10 minutes is denied.
Hosting runs Teams channels only in the commercial Microsoft cloud, and only for teams that have Teams channels turned on. The deploy fails otherwise.
How Teams differs from Slack
| Slack | Teams | |
|---|---|---|
| App | Your Slack app's bot and app tokens | Your Azure Bot's app ID, client secret, and tenant |
| Local transport | Socket Mode, no public URL | agent-sdk dev opens a tunnel to the messaging endpoint |
| Watch channel posts | message.channels subscription | ChannelMessage.Read.Group consent at install |
| Threads | Every message can start a thread | Reply chains in channels; personal and group chats are one conversation each |
| Bot-to-bot wakes | maxDepth from message metadata, plus per-thread caps | Per-thread caps only |
| Progress | Status chip, streaming API, tool and reasoning cards | Typing indicator, or one edited message in stream mode |
| Approvals | Block Kit buttons | Adaptive Card buttons |
| Hosted sessions | One per thread | One per chat, or one per channel reply chain |
| Not available in Teams | Reactions, file uploads and downloads, suggested prompts, eval commands, edit debounce |