How to build a production-grade AI agent inside Microsoft Teams — architecture, auth, Adaptive Cards, and the gotchas nobody warns you about
Microsoft Teams is where most enterprise workers already spend their day. An agent channel turns a Teams conversation — DM, group chat, or channel thread — into a direct interface to your AI agent. Users type natural language, the agent processes it through whatever LLM you choose, and replies appear in the same conversation thread.
The underlying technology is the Azure Bot Framework. Your agent registers as a bot in Azure, exposes an HTTPS webhook endpoint, and receives messages via Bot Framework's Activity protocol. Replies go back through the same protocol, landing in the exact conversation they came from. On top of this, Adaptive Cards give you rich interactive UI — buttons, forms, polls, images — inside the chat window.
This is not Microsoft Copilot. You control the model (Claude, GPT, Gemini, local Ollama), you control the prompts, you control the data. The tradeoff: you need to set up Azure Bot registration and maintain a publicly accessible HTTPS endpoint.
AI assistants that live in terminal windows or standalone UIs never get adopted by non-technical teams. People forget they exist. Adoption friction kills the best agent.
Your agent registers as an Azure Bot, receives Teams webhooks, processes with any LLM, and responds via the Bot Framework REST API — fully under your control.
Team members @mention the agent in channels, DM it directly, or trigger workflows through Adaptive Card buttons — without leaving Teams. Zero adoption friction.
Teams is the default workplace for most enterprises. Building your agent here means zero adoption friction — users don't download a new app, learn a new interface, or switch contexts. They message the bot like they'd message a colleague.
The alternative is Microsoft Copilot at $30/user/month, locked to Microsoft's models, with no control over prompts, data residency, or non-Microsoft integrations. A self-hosted agent on Bot Framework is free to register, model-agnostic, and fully under your control. You pay only for the LLM API tokens you consume.
Register a bot in Azure, set up a webhook, handle conversation types, implement access control, add Adaptive Cards, and handle files. Here's how each step works.
Go to Azure Portal → Bot Services → Create. Choose single-tenant. You'll get an App ID (identifies your bot), an App Password (client secret for outbound API calls), and a Tenant ID. Configure the messaging endpoint to point at your webhook URL (e.g., https://your-domain.com/api/messages).
Your endpoint needs to: validate the JWT token on every inbound request, parse the Activity payload to extract the message, sender, and conversation reference, route the message to your agent logic, and send the reply back using the Bot Framework REST API or SDK.
// Minimal Node.js example using Bot Framework SDK const { BotFrameworkAdapter } = require('botbuilder'); const adapter = new BotFrameworkAdapter({ appId: process.env.MICROSOFT_APP_ID, appPassword: process.env.MICROSOFT_APP_PASSWORD }); // POST /api/messages app.post('/api/messages', (req, res) => { adapter.processActivity(req, res, async (context) => { if (context.activity.type === 'message') { const userMessage = context.activity.text; const reply = await callYourAgent(userMessage, context); await context.sendActivity(reply); } }); });
Teams has three conversation types. Personal DMs: 1:1 with the bot, messages route directly — start here. Group Chats: Bot must be @mentioned to receive messages — filter for @mention in the activity. Channels: Bot must be @mentioned. Channels can be "Posts" or "Threads" mode — the API doesn't tell you which. Configure reply style manually or replies land in the wrong place.
Don't expose your agent to everyone by default. DMs: Use a pairing/allowlist model — unknown senders are ignored until explicitly approved. Group Chats: Allowlist by user or group, block by default. Channels: Restrict which channels the bot responds in using channel ID allowlists.
Adaptive Cards turn plain text replies into rich interactive UI. Use the Adaptive Cards Designer to build cards visually, then send them as attachments. Cards support text blocks, images, action buttons, input fields, fact sets, and polls — all defined in a JSON schema (v1.5 current).
// Sending an Adaptive Card const card = { type: "AdaptiveCard", version: "1.5", body: [ { type: "TextBlock", text: "Deployment Status", weight: "Bolder" }, { type: "FactSet", facts: [ { title: "Status", value: "Success" }, { title: "Duration", value: "2m 34s" } ]} ], actions: [ { type: "Action.OpenUrl", title: "View Logs", url: "https://..." }, { type: "Action.Submit", title: "Rollback", data: { action: "rollback", build: "1234" } } ] };
DM attachments: Work natively — files arrive as attachment URLs in the activity payload. Channel/group files: Require SharePoint integration. You need a sharePointSiteId and Sites.ReadWrite.All Graph permissions. Inbound images in channels: The webhook payload only includes an HTML stub, not the actual file bytes. You must use Graph API with additional permissions to retrieve the content.
This interactive mockup shows how a custom AI agent appears when installed as a Teams bot — DM conversations with Adaptive Cards, polls, and standard message exchange.
The bot avatar and messages flow through Azure Bot Framework webhooks to your agent's gateway. Adaptive Cards (the deployment summary and poll above) are sent as JSON payloads conforming to the Adaptive Card v1.5 schema. Card interactions (button clicks, poll votes) are received as postback events at your webhook — the gateway must stay online to collect them.
You don't need to build from scratch. Several frameworks handle the Bot Framework plumbing for you. Pick the one that fits your team's language, complexity needs, and multi-channel ambitions.
Node.js, Python, C#, Java. Full API coverage, best docs. The official SDK for Teams-first bots and enterprise compliance requirements.
Node.js. 23-channel support, plugin architecture, model-agnostic. Best for multi-channel agents that need to work across Teams, WhatsApp, Slack, and others from the same codebase.
TypeScript. Visual flow builder, built-in NLU, cloud hosting. Best for non-developer teams and rapid prototyping of Teams bots.
| Framework | Language | Strengths | Best For |
|---|---|---|---|
| Bot Framework SDK | Node.js, Python, C#, Java | First-party, full API coverage, best docs | Teams-first bots, enterprise compliance |
| OpenClaw | Node.js | 23-channel support, plugin architecture, model-agnostic | Multi-channel agents (Teams + WhatsApp + Slack) |
| Botpress | TypeScript | Visual flow builder, built-in NLU, cloud hosting | Non-developer teams, rapid prototyping |
| Custom (direct REST) | Any | Maximum control, no framework overhead | Unique integration requirements |
The Model Context Protocol (MCP) is emerging as the standard for giving agents tool access. For Teams-specific operations — scheduling meetings, managing team memberships, archiving channels — MCP servers like Composio provide pre-built toolkits that your agent can call via natural language.
Real patterns from production deployments — not theoretical possibilities.
Adaptive Cards with build status, rollback buttons, and log links posted to a #deployments channel. One-click rollback from inside Teams.
Employees DM the bot with issues. The agent classifies, routes to the right queue, and auto-creates tickets — without a separate helpdesk portal.
New hires get a personal DM bot that walks them through policy docs, benefits enrolment, and team introductions — answering questions in natural language.
Via MCP connectors, sales reps ask the bot for deal status, contact history, or pipeline numbers directly in their Teams channel — no tab-switching to Salesforce.
Automated Adaptive Card polls at 9am. Responses collected automatically. Summary posted at end-of-day. No meeting required for status updates.
Trained on internal policy documents with RAG. Employees ask compliance questions in Teams and get source-attributed answers — audit-friendly.
Key milestones in the evolution of the Teams bot platform.
Microsoft stabilises the Activity protocol and SDK for Teams bots. Adaptive Cards v1.2.
Microsoft releases Teams AI Library for LLM-powered bots. Simplified bot scaffolding.
Microsoft deprecates new multi-tenant bot registrations. Single-tenant required for new bots.
MCP servers for Teams operations (Composio, others) enable natural-language admin actions.
Rich card interactions, expanded private channel bot support rolling out across tenants.
Honest assessment. This is powerful but not trivial to set up — and it's not always the right call.
Your workforce already lives in Teams and you want AI embedded in existing workflows, not bolted on as a separate app.
You need control over model choice, prompts, data residency, and cost — not locked into Copilot's pricing or model.
You want a multi-channel agent that works across Teams, Slack, WhatsApp, and others from the same codebase.
You have (or can get) Azure AD admin consent for bot registration and someone who can maintain the gateway.
Your org blocks third-party bots in Teams or has a strict no-custom-app policy. Check with IT first.
You don't have access to Azure Portal to create a Bot registration — this is a hard requirement.
You need full message history search. RSC only covers live events; Graph API with admin consent is needed for historical access.
You want zero maintenance. This requires a running gateway on a publicly accessible HTTPS endpoint. If that sounds like a burden, Copilot might be simpler.
Bot Framework (baseline): Receive messages in DMs, group chats, and channels. Send replies to conversations.
RSC — Resource-Specific Consent (recommended): Read channel message text and send messages without broad admin scopes. Enables real-time channel listening.
Graph API (optional): Sites.ReadWrite.All for SharePoint file uploads. Chat.Read.All for restricted file sharing links. ChannelMessage.Read.All for historical message access.
All Graph permissions require admin consent from your M365 administrator.
Thread vs Post mode — Teams channels can be in "Posts" or "Threads" mode. The Bot Framework API does not tell you which mode is active. Configure reply style manually per channel, or replies appear in the wrong place.
Multi-tenant deprecation — Microsoft deprecated new multi-tenant bot registrations in July 2025. Use single-tenant. Existing multi-tenant bots still work but won't receive new feature support.
Channel images — Webhook payloads for images in channels only include an HTML stub, not actual file bytes. Graph API permissions are required to retrieve the content.
Private channels — Expanded bot support in private channels is rolling out across tenants as of early 2026 but isn't universally available yet.
RSC limitations — Resource-Specific Consent only covers real-time events. For historical message access, you need ChannelMessage.Read.All with full admin consent.
Microsoft Teams Platform Docs — Bot Framework, app manifests, deployment ↗
Bot Framework SDK (GitHub) — Source code, samples, migration guides ↗
Teams AI Library — LLM-powered bot building ↗
Adaptive Cards Designer — Visual card builder and schema reference ↗
Adaptive Cards Schema Explorer — Full v1.5 element reference ↗
Microsoft Graph API — Teams — Programmatic access to Teams data ↗
Microsoft Bot Framework SDK — First-party, Node.js/Python/C#/Java ↗
OpenClaw — Multi-channel agent framework with Teams plugin ↗
Botpress — Visual bot builder with Teams integration ↗
Microsoft Teams Platform Documentation · Bot Framework Activity Protocol · Adaptive Cards Documentation · Microsoft Graph — Teams API
Content validated March 2026. Microsoft Teams and Azure Bot Framework are trademarks of Microsoft Corporation. Independent educational explainer by Imbila.AI.
Give this URL to any AI agent — it can fetch the full explainer as structured markdown, no Cloudflare blocking.