Build an AI Assistant Inside Microsoft Teams

A blueprint for engineering leads, enterprise architects, and product directors building intelligent, conversational AI agents within the Microsoft 365 ecosystem.

1. The Problem Premise: Context Switching & Knowledge Fragmentation

In the modern enterprise digital workspace, knowledge workers are drowning in software fragmentation.

On any given Tuesday, a software engineer, product manager, or operations analyst toggles between ten to fifteen disconnected SaaS applications just to answer a simple business question:

• Where is the latest SOC2 compliance audit report? (Search SharePoint / OneDrive)

• What is the status of the customer escalation for Client X? (Query Jira / ServiceNow)

• What were our Q3 recurring revenue figures for the EMEA region? (Log into Salesforce / Snowflake)

• How do I configure the staging environment deployment pipeline? (Search internal Wiki / Confluence)

This constant bouncing between browser tabs, desktop windows, and authentication portals creates two severe organizational crises: Cognitive Context Rot and Massive Productivity Loss.

1.1 The Cognitive Tax of Context Switching

Psychological research conducted by Dr. Gloria Mark at the University of California, Irvine, demonstrates that knowledge workers are interrupted or switch tasks every 3 to 5 minutes.

More critically, once an employee's focus is fractured by switching applications to locate information, it takes an average of 23 minutes and 15 seconds to regain deep, flow-state concentration on their primary work.

The context switching bottleneck follows a recurring cycle:

1. Focused Primary Work: Engineer or manager is working deeply in their primary tool.

2. Context Shift: Interruption occurs to search external SaaS applications.

3. Recovery Lag: An average 23-minute delay is incurred before regaining flow-state focus.

4. Productivity Rot: Cumulative fatigue and cognitive friction degrade work quality.

When an engineer leaves their IDE or a manager leaves their meeting notes to spend 20 minutes digging through SharePoint folder hierarchies or writing SQL queries, their creative momentum is destroyed. Multiply this across an enterprise of 1,000 employees, and an organization loses over 500,000 hours of productive capacity every single year, costing over $25 Million in wasted payroll.

1.2 Why Microsoft Teams is the Ultimate Conversational Interface

To solve knowledge fragmentation, you should not build yet another standalone web application or internal admin dashboard. Forcing employees to open another browser tab to ask an AI a question simply recreates the context-switching problem.

Instead, the golden rule of enterprise UI/UX is: Meet users where they already work.

With over 320 million monthly active users, Microsoft Teams has become the default operational desktop for modern enterprise communication. It is where employees start their morning, chat with colleagues, participate in video meetings, share files, and coordinate project channels.

By building a native AI Assistant inside Microsoft Teams, you insert intelligence directly into the user's primary workflow canvas:

• Zero-Friction Access: Users query the AI by simply typing @Assistant in any team channel, group chat, or 1-on-1 direct message window.

• Context Preservation: Employees ask questions, run workflows, and pull customer summaries without ever minimizing their active conversation or video call.

• Rich Interactive UIs: Rather than returning plain text strings, the assistant renders interactive Adaptive Cards complete with action buttons, status badges, dropdowns, and deep links.

2. The Architectural Blueprint for an Enterprise Teams AI Assistant

Building a simple demo bot using basic webhooks takes an afternoon. But building an enterprise-grade, secure, multi-tenant AI Assistant capable of handling thousands of concurrent users, querying internal knowledge bases safely, and obeying corporate security rules requires a robust cloud architecture.

2.1 Core Architectural Layers

End-to-end cloud architecture for a production Teams AI Assistant utilizing Azure Bot Service, Azure App Service, Azure AI Search, and Azure OpenAI.

A production enterprise Teams AI Assistant comprises four decoupled operational tiers:

1. Client Tier (Microsoft Teams): The desktop, web, or mobile Teams application that renders the user interface, captures input prompts, handles @mention events, and displays Adaptive Cards.

   
   

2. Channel & Identity Gateway (Azure Bot Service + Entra ID): Acts as the secure bridge between Microsoft Teams and your backend code. Handles channel protocol translation, OAuth2 token pass-through, and Single Sign-On (SSO) authentication.

   
   

3. Application & Orchestration Tier (Teams AI Library Backend): An asynchronous Python web server (hosted on Azure App Service or Azure Container Apps) powered by Microsoft's official Teams AI Library (microsoft-teams-apps). This tier manages message routing, dialog state, action planning, and turn contexts.

   
   

4. Cognitive & Intelligence Tier (Azure OpenAI + Vector RAG): The Generative AI engine (GPT-4o) combined with an enterprise vector database (Azure AI Search, Qdrant, or Pinecone) providing Retrieval-Augmented Generation over corporate knowledge bases.

2.2 Deep Dive into the Teams AI Library

Historically, developers built Teams bots using the raw Microsoft Bot Framework SDK (botbuilder). While powerful, the raw Bot Framework required hundreds of lines of complex boilerplate code to manage manual state storage, turn contexts, regex pattern matching, and waterfall dialogs.

Microsoft introduced the Teams AI Library (now part of the unified Teams SDK) to replace raw Bot Framework code for AI-driven applications.

Execution loop of the Teams AI Library showing prompt processing, action planning, model execution, and state persistence.

The Teams AI Library provides three core primitives that dramatically simplify development:

• Application: The central app class that wraps message routing, activity handlers, and turn contexts.

  
  

• ActionPlanner: An intelligent LLM orchestrator that analyzes incoming user prompts, automatically selects appropriate tools or actions, and constructs multi-step execution plans.

  
  

• OpenAIModel: Native wrappers for Azure OpenAI and OpenAI APIs, handling automatic prompt history management, token budgeting, and system instructions.

3. Designing Rich, Interactive Conversational UIs

Text-only chat responses are insufficient for enterprise workflows. When an employee asks your AI Assistant for a customer summary or a list of active support tickets, returning a 500-word block of plain unformatted text creates cognitive fatigue.

3.1 The Power of Adaptive Cards in Microsoft Teams

Adaptive Cards are open, declarative JSON payloads that render native UI components directly inside Microsoft Teams. They adapt seamlessly to the host environment's theme (Dark Mode, Light Mode, High Contrast) and screen size (Desktop vs Mobile).

Interactive Adaptive Card rendered inside Microsoft Teams featuring structured visual data, status badges, and action buttons.

By leveraging Adaptive Cards, your AI Assistant transforms from a simple Q&A bot into an Interactive Workspace Application:

• Action Buttons: Allow users to click buttons ("Approve Purchase", "Create Jira Ticket", "View Source Document") that fire background actions directly back to your Python backend.

  
  

• Input Forms: Render text inputs, date pickers, and choice dropdowns directly within the chat stream.

  
  

• Visual Hierarchy: Highlight critical information using colored containers, bold headers, column sets, and embedded thumbnails.

4. Step-by-Step Production Implementation Guide

Instead of dumping bloated boilerplate files, this section provides an architectural step-by-step implementation blueprint. We define the role, responsibilities, and key functions for each file in the project map, accompanied by minimal essential code snippets demonstrating the core patterns.

Project Architecture & File Map Overview

teams-ai-assistant/

├── manifest.json         # Teams App Manifest & Permissions Schema
├── config.py            # Environment Variables & Azure Configuration
├── schemas.py           # Strongly-Typed Pydantic Response Schemas
├── rag_engine.py        # Vector RAG & Azure AI Search Module
├── card_builder.py      # Adaptive Card JSON Generator
└── app.py              # Teams AI Library Web Server & Bot Handlers

Step 1: App Registration & Manifest (manifest.json)

The manifest.json file registers your application capabilities with Microsoft Teams. It configures the bot's unique ID, scopes (personal, team, groupchat), dynamic commands, valid domain endpoints, and security permissions.

Below is the snippet defining the bot registration block inside manifest.json:

{
  "manifestVersion": "1.16",
  "id": "${TEAMS_APP_ID}",
  "name": { "short": "Enterprise AI", "full": "Enterprise AI Assistant" },
  "bots": [
    {
      "botId": "${MICROSOFT_APP_ID}",
      "scopes": ["personal", "team", "groupchat"],
      "supportsFiles": true,
      "isNotificationOnly": false
    }
  ],
  "validDomains": ["*.openai.azure.com", "*.search.windows.net", "${BOT_DOMAIN}"]
}

Step 2: Strongly-Typed Data Models (schemas.py)

This file defines type-safe data models using Pydantic. It validates document search snippets retrieved from vector search and structures the final response object generated by the LLM.

Implementation Snippet:

# schemas.py - Essential Data Models

from pydantic import BaseModel, Field
from typing import List, Optional
class SearchCitation(BaseModel):
    title: str = Field(..., description="Document title")
    content: str = Field(..., description="Text snippet")
    source_url: str = Field(..., description="Direct link to source file")
    score: float = Field(..., description="Similarity score")
class AIResponsePayload(BaseModel):
    answer_text: str = Field(..., description="Primary response text")
    citations: List[SearchCitation] = Field(default_factory=list)

Step 3: Vector RAG Search Module (rag_engine.py)

This module encapsulates all interaction with Azure AI Search and Azure OpenAI Embeddings. It converts incoming user prompts into 1,536-dimensional vectors (text-embedding-3-small) and executes a hybrid vector + keyword query against the enterprise knowledge index.

Implementation Snippet:

# rag_engine.py - Minimal Vector Retrieval Pattern

from azure.search.documents import SearchClient
from azure.search.documents.models import VectorizedQuery
from openai import AzureOpenAI
def hybrid_search(query_text: str, search_client: SearchClient, openai_client: AzureOpenAI) -> list:
    """Generates embedding vector and executes hybrid vector + keyword search."""
    embedding = openai_client.embeddings.create(
        input=query_text, model="text-embedding-3-small"
    ).data[0].embedding
    
    vector_query = VectorizedQuery(vector=embedding, k_nearest_neighbors=3, fields="content_vector")
    results = search_client.search(search_text=query_text, vector_queries=[vector_query], top=3)
    return [dict(doc) for doc in results]

Step 4: Adaptive Card UI Generator (card_builder.py)

This file takes structured response payloads from schemas.py and programmatically transforms them into v1.4 Adaptive Card JSON schemas for native rendering inside Teams.

Implementation Snippet:

# card_builder.py - Minimal Adaptive Card Generator

def build_response_card(answer_text: str, citations: list) -> dict:
    """Constructs minimal Adaptive Card JSON for Teams client."""
    citation_blocks = [
        {"type": "TextBlock", "text": f"• [{c['title']}]({c['source_url']})", "isSubtle": True, "wrap": True}
        for c in citations
    ]
    return {
        "type": "AdaptiveCard",
        "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
        "version": "1.4",
        "body": [
            {"type": "TextBlock", "text": "🤖 AI Assistant Response", "weight": "Bolder", "size": "Large"},
            {"type": "TextBlock", "text": answer_text, "wrap": True},
            {"type": "TextBlock", "text": "**Citations:**", "weight": "Bolder"},
            *citation_blocks
        ]
    }

Step 5: Teams AI App Server & Handlers (app.py)

The central web server entry point. It initializes the aiohttp web host, sets up the Bot Framework Adapter, handles incoming POST webhooks on /api/messages, fires "Typing..." status indicators, invokes the RAG pipeline, and posts Adaptive Card activities back to Teams.

Implementation Snippet:

# app.py - Teams AI App Server Pattern

from aiohttp import web
from botbuilder.core import BotFrameworkAdapter, BotFrameworkAdapterSettings, TurnContext
from botbuilder.schema import Activity, ActivityTypes, Attachment
from card_builder import build_response_card
from rag_engine import hybrid_search
adapter = BotFrameworkAdapter(BotFrameworkAdapterSettings(app_id="APP_ID", app_password="APP_PASSWORD"))
async def message_handler(turn_context: TurnContext):
    if turn_context.activity.type == ActivityTypes.message:

        # 1. Send immediate typing indicator to Teams
        await turn_context.send_activity(Activity(type=ActivityTypes.typing))
        

        # 2. Execute RAG Search & LLM Completion
        user_query = turn_context.activity.text or ""
        docs = hybrid_search(user_query, search_client, openai_client)
        
        # 3. Build & Send Adaptive Card Activity
        card_json = build_response_card("Extracted answer content...", docs)
        attachment = Attachment(content_type="application/vnd.microsoft.card.adaptive", content=card_json)
        await turn_context.send_activity(Activity(type=ActivityTypes.message, attachments=[attachment]))

# Server Webhook Listener
async def messages_api(request: web.Request) -> web.Response:
    body = await request.json()
    activity = Activity().deserialize(body)
    await adapter.process_activity(activity, request.headers.get("Authorization", ""), message_handler)
    return web.Response(status=201)
app = web.Application()
app.router.add_post("/api/messages", messages_api)

Step 6: Local Debugging & Azure Deployment

:

Local testing and debugging workflow using VS Code, Microsoft 365 Agents Toolkit, and secure local tunneling.

Azure resource topology for hosting production Teams AI Assistants.

Check out these other blogs from us which you might like

• Discover how to design and implement an enterprise-grade architecture for a natural language analytics assistant within Power BI.

  
  

• Get a complete overview of utilizing Mistral's open-weight language models to power robust and efficient Retrieval-Augmented Generation (RAG) applications.

  
  

• Learn exactly when deploying local LLMs via Ollama makes sense for your RAG architecture and when alternative cloud solutions might be better suited.

  
  

• Understand the strengths, multimodal features, and limitations of using Google's Gemini for RAG systems to make informed architectural decisions before you start building.

  
  

• Explore this comprehensive production guide on safely building and deploying a secure, enterprise-ready AI email assistant using Azure OpenAI for 2026.

  
  

• Dive into this complete enterprise guide for automating complex invoice extraction and achieving end-to-end accounting accuracy utilizing Azure Document Intelligence.

5. Enterprise Security, Identity, and Governance

Deploying an AI Assistant into a corporate Microsoft Teams tenant requires strict adherence to security and data privacy standards.

5.1 Single Sign-On (SSO) & User-Level Security Trimming

When an employee asks a question inside Microsoft Teams, the AI Assistant must never return information the user is not authorized to see in the underlying source system.

Security-trimmed retrieval operates through an identity-bound pipeline:

1. User Token Acquisition: Teams client authenticates user via Entra ID SSO.

   
   

2. Bot Activity Delegation: Bot receives validated user Bearer token containing user Object ID and group claims.

   
   

3. Security-Filtered RAG Search: Vector search filters out unauthorized documents before context generation.

   
   

4. Contextual Generation: OpenAI synthesizes answer strictly from authorized document snippets.

   
   

5. Microsoft Entra ID SSO: Configure native Single Sign-On using Microsoft Entra ID (formerly Azure Active Directory). The bot receives a validated user Bearer token containing the user's oid (Object ID) and Security Group memberships.

   
   

6. Security-Trimmed Vector RAG: When querying Azure AI Search, pass the ser's security group IDs as an explicit filter expression: filter=search.in(allowed_groups, 'Group-UUID-1, Group-UUID-2'). Documents the user does not have permission to read in SharePoint are filtered out before the context is sent to the LLM.

   
   

5.2 Zero-Trust VNet Isolation & Private Endpoints

For strict regulatory compliance (SOC2, HIPAA, ISO 27001), you can completely isolate your Azure App Service, Azure Bot Service, and Azure OpenAI instance inside your Azure Virtual Network (VNet).

• Private Endpoints: Bind Azure OpenAI and Azure AI Search to Private Endpoints. Public internet access is disabled entirely (publicNetworkAccess: "Disabled").

  
  

• Managed Identities: Use Azure System-Assigned Managed Identities (DefaultAzureCredential) for all inter-service authentication (App Service $\rightarrow$ Azure Key Vault / Azure AI Search), completely removing secret API keys from your environment configurations.

6. FAQs

Below are answers to some edge cases encountered when deploying AI Assistants in Microsoft Teams.

Q1: How do you bypass Microsoft Teams' strict 10-second HTTP response timeout when your RAG pipeline or LLM reasoning takes longer to complete?

Answer: Microsoft Teams enforces a strict 10-second timeout on incoming bot HTTP webhooks. If your server does not return an HTTP 200/201 ACK within 10 seconds, Teams marks the activity as failed and drops the response.

To solve this in production:

1. Immediate HTTP Acknowledgment: When your messages_handler receives an activity, validate the authorization header and immediately return an HTTP 201 Created status to Teams within 50 milliseconds.

   
   

2. Asynchronous Background Processing: Offload the actual RAG search, LLM completion, and card rendering to an asynchronous Python background task (asyncio.create_task(process_user_turn(turn_context))).

   
   

3. Send Typing Indicator Activity: Fire an initial ActivityTypes.typing activity to Teams immediately. This maintains the "Assistant is typing..." visual indicator in the user's Teams window while your background task executes. Once complete, call turn_context.send_activity with the final Adaptive Card payload.

Q2: How do you persist conversation state and user memory across bot server restarts and horizontal scaling instances?

Answer: Default in-memory bot state storage (MemoryStorage) is destroyed whenever your Azure App Service restarts or scales horizontally across multiple container instances.

To enforce state persistence across enterprise clusters:

• Use Azure Cosmos DB Storage or Azure Table Storage as your bot state provider.

  
  

• Initialize the Bot Framework adapter with CosmosDbPartitionedStorage (or BlobsStorage).

  
  

• Store conversation state keyed by turn_context.activity.conversation.id and user memory keyed by turn_context.activity.from.id. This ensures that even if User A's Turn 1 lands on App Instance 1 and Turn 2 lands on App Instance 2, the exact conversation history and state variables are re-hydrated from Cosmos DB seamlessly.

Q3: How do you implement Proactive Messaging to send unsolicited Teams alerts when a background AI job completes?

Answer: Proactive messaging allows your bot to send messages to a user or channel without the user initiating a turn first (e.g., notifying an engineer when a long-running CI/CD build fails or a contract review completes).

To send proactive messages in production:

1. Save Conversation References: Whenever a user interacts with your bot, save their ConversationReference object (containing service_url, conversation_id, user_id, tenant_id) into a Cosmos DB table.

   
   

2. Execute Proactive Callback: When a background event triggers, fetch the stored ConversationReference from Cosmos DB.

   
   

3. Invoke Adapter Continuation:

   
   

   Call adapter.continue_conversation(conversation_reference, proactive_callback_function, bot_app_id). Inside the callback function, use turn_context.send_activity to deliver the Adaptive Card or message directly to the target user's Teams window.

Q4: How do you enforce Microsoft Entra ID (Azure AD) Single Sign-On (SSO) and pass-through user permissions to vector search?

Answer: Allowing an AI bot to return sensitive corporate data to unauthenticated users is a major security vulnerability.

To enforce native SSO:

1. Configure Azure Bot Service OAuth Connection linked to an Azure AD App Registration configured with access_as_user permissions.

   
   

2. In your bot code, invoke turn_context.adapter.get_user_token(turn_context, connection_name) during the message turn. If no token is returned, send an OAuthCard prompting the user to sign in with one click inside Teams.

   
   

3. Once the validated JWT Bearer token is acquired, extract the user's oid (Object ID) and group claims. Pass these claims to your vector database (Azure AI Search) as filter parameters ($filter=search.in(group_ids, 'Group-1, Group-2')). This guarantees that vector RAG search returns only documents the authenticated user has explicit permission to read in SharePoint.

Q5: How do you handle bot deployment errors where the Teams client displays "Sending..." indefinitely or fails to load Adaptive Cards?

Answer: This common issue is almost always caused by one of three configuration mismatches:

• App ID / Password Mismatch:

  
  

  Ensure MICROSOFT_APP_ID and MICROSOFT_APP_PASSWORD in your App Service environment variables match the exact App Registration ID and secret in your Azure Bot Service channel.

  
  

• Missing Valid Domains in Manifest:

  
  

  If your Adaptive Card contains Action.OpenUrl links or embedded images, those domain URLs (e.g., .search.windows.net, .openai.azure.com) must be listed in the validDomains array inside your manifest.json.

  
  

• Invalid Adaptive Card JSON Version:

  
  

  Ensure the $schema and version declared in your Adaptive Card JSON match supported Teams versions (use "version": "1.4" for universal compatibility across desktop and mobile Teams clients).

7. Financial ROI & Productivity Benchmark

Let's evaluate the operational economics of building and deploying a custom Teams AI Assistant across an enterprise of 1,000 knowledge workers.

Baseline Productivity Metrics (1,000 Employees):

• Average Time Wasted Searching for Information: 45 minutes / employee / day.

• Hourly Knowledge Worker Cost: $50.00 / hour.

• The total daily wasted search payroll across the enterprise is $37,500, based on 1,000 employees each wasting 0.75 hours per day at an average rate of $50 per hour.

• Monthly Wasted Search Payroll: $825,000 / month.

Post-Deployment Efficiency Gains:

• Time Reduction in Search with Teams AI Assistant: 70% reduction in search time (saving 31.5 minutes / day per worker).

• Monthly Hours Saved: 11,500 hours / month.

• Monthly Payroll Value Reclaimed: $577,500 / month.

System Operational Cost Model (50,000 User Queries / Month):

Azure OpenAI (GPT-4o + Embeddings): ~$350.00 / month

Azure App Service (B2 Linux Instance): ~$75.00 / month

Azure AI Search (Standard Tier): ~$250.00 / month

Azure Bot Service (Standard Channel): ~$0.00 (Teams channel free)

Total Operational Infrastructure Cost: ~$675.00 / month

Performance Dimension	Manual Search	Custom Teams AI Assistant	Net Enterprise Advantage
Avg Search Latency	20 - 30 Minutes	3 - 5 Seconds	99.7% faster
Monthly Operational Cost	$825,000 (Wasted Payroll)	$675 (Infrastructure)	$824,325 saved / month
Context Switching Events / Day	40+ switching events	0 (In-Context inside Teams)	Eliminates focus rot
Information Accuracy Rate	65% (Outdated local files)	96% (Real-Time Vector RAG)	Higher decision quality
Payback Period	—	—	Less than 3 Business Days

8. Partnering with Codersarts AI for Enterprise Deployment

While the Teams AI Library simplifies bot development, building a production-grade, secure enterprise Teams Assistant requires experienced software engineering craft:

• Engineering complex Entra ID SSO authentication & user-level security trimming.

• Building custom Adaptive Card UIs with interactive action handlers.

• Designing fault-tolerant asynchronous event queues for long-running AI tasks.

• Configuring private VNet Endpoints, Managed Identities, and Azure CI/CD pipelines.

That is precisely why enterprise teams partner with Codersarts AI

Why Enterprises Choose Codersarts AI

At Codersarts AI, we specialize in building bespoke, production-grade AI Assistants, custom Teams/Slack agents, and enterprise RAG engines.

• Senior Engineering Execution: We provide senior AI/ML developers, Microsoft 365 cloud architects, and full-stack engineers.

  
  

• 35% to 55% Cost Advantage: We deliver high-velocity enterprise engineering at a fraction of typical US consulting agency rates.

  
  

• Turnkey Production Delivery: From initial architecture design to full Teams tenant deployment, we deliver production software ready for scale.

  
  

"Stop forcing your employees to jump through SaaS hoops. Bring enterprise intelligence directly into Microsoft Teams."

Contact us today to book a dedicated technical architecture consultation with our engineering leads.