Best Practices for Deploying Copilot Studio Agents in Microsoft Teams

Deploying a Copilot Studio agent to Microsoft Teams introduces unique challenges that don’t exist in web chat deployments. Sessions persist indefinitely, conversation start events don’t fire automatically, and updates can be cached. Understanding these nuances is critical for delivering a reliable user experience.

Why Teams Deployment is Different

• Sessions persist across days or weeks without automatic reset
• Conversation Start events don’t trigger on initial load
• Stale context and expired tokens can cause unexpected behavior
• Updates may not propagate immediately due to caching

Teams chats are persistent by design, which means both opportunities and challenges for bot developers.

The Session State Challenge

Unlike web chat where each session starts fresh, Teams conversations maintain state indefinitely. This persistence is powerful for continuity but creates problems:

• Stale Context: Old conversation data can confuse the AI
• Token Expiration: Connector authentication expires during long sessions
• Context Limits: Accumulated history can hit token limits
• Update Delays: Users continue running old bot logic after updates

The solution requires proactive session management and clear user guidance.

Managing Session Lifecycle

Step 1: Implement Inactivity Reset

Create a new topic and select “The user is inactive for awhile” trigger to automatically reset sessions:

Setup Process:

1. Add “The user is inactive for awhile” event trigger, adjust the duration in the property of the trigger (e.g., 15 minutes timeout)
2. Add one (or more) “Clear variables” node to wipe session variables and conversation history to prevent context overflow
3. End conversation and mark session as resolved

Configure inactivity timeout to prevent stale sessions.

This ensures that when users go idle, the bot proactively resets for a clean slate.

Clearing state on inactivity prevents the AI from hitting context length limits and avoids weird behaviors when users return later.

Step 2: Guide Users After Reset

After clearing state, send a clear message explaining what happened:

"It looks like our conversation went idle, so I've cleared the prior context for safety. Please say 'hello' to start a new conversation."

This serves two critical purposes:

1. Explains the reset - Users understand why context was lost
2. Triggers Greeting topic - Prompts the user to reinitialize properly

Why prompt for “hello”? Because in Teams, the ConversationStart event doesn’t fire automatically. The bot only responds after the user’s first message. By having users say “hello” (or any greeting), you trigger the Greeting topic and execute your initialization logic.

Treat the Greeting topic as your conversation opener for Teams deployments, not ConversationStart.

Step 3: Empower Users with Debug Commands

Include the /debug clearstate command in your help messaging:

"If something seems off, try typing /debug clearstate to refresh my state."

This special command forces a complete conversation reset:

• Clears all conversation state
• Removes cached connector information
• Re-authenticates connectors
• Loads latest agent version

When to use:

• Bot seems “stuck” with outdated information
• Connector authentication has expired
• After bot logic updates
• When behavior seems inconsistent

Transparency and Debugging

Leverage OnKnowledgeRequested for Visibility

Query rewrite is a key step in the knowledge pipeline of Copilot Studio. When a user asks a question, the system doesn’t send the raw text directly to the search indexes. Instead, it rewrites the query to optimize it for retrieval across multiple knowledge sources (lexical and semantic). This process ensures better relevance and accuracy of search results.

Enable the OnKnowledgeRequested trigger to reveal what the agent is actually searching for:

Implementation:

1. Enable OnKnowledgeRequested trigger (via YAML as this is not yet in the UI)
2. Add Message node to display search query
3. Show users: “Searching knowledge base for: {keywords}”

OnKnowledgeRequested reveals the query rewrite for transparency.

This provides read-only access to the refined search query (query rewrite) that the orchestrator generated from the user’s question.

Benefits:

• Helps debug mismatches in intent
• Shows users what’s being looked up
• Builds trust in the bot’s actions
• Assists makers during testing

Example: User asks “How do I reset my password?” and bot displays “(debug) Searching HR FAQ for ‘reset password’”.

You can see both keyword search or semantic search, notice how the second question was rewritten by the agent before search.

Use OnKnowledgeRequested during development to verify query rewrites, then decide whether to keep it visible in production.

Version Control and Updates

Surface Bot Version to Users

Always include a version identifier in your agent responses using the “Greeting” topic or a dedicated “Version” topic:

"Contoso Helpdesk Bot – Version 1.3 (Nov 2025)"

Best practices:

• Update version string with every publish
• Include in greeting message
• Reference in troubleshooting scenarios

This helps both users and makers confirm which build is running. If a user reports an issue with v1.2 when you’ve released v1.3, you know they need to refresh.

Updating version metadata also busts caches – changing the description or name forces Teams to treat it as an update.

Force Updates on Publish

When publishing to Teams, enable the “Force newest version” option:

What it does:

• Forces immediate refresh for all users
• Eliminates the need to unpublish/republish
• Users don’t need to remove and re-add the app
• New topic flows take effect immediately

Enable Force Update to ensure all users get the latest version.

Previously, makers had to ask users to manually reinstall or increment manifest versions. The Force Update feature automates this process.

Heads-up: Forcing an update will interrupt any ongoing conversation, so use this power wisely!

Teams-Specific Considerations

Handle Greeting Logic Properly

Since ConversationStart won’t auto-fire:

1. Keep greeting topic simple and straightforward
2. Provide written instructions in Teams app description
3. Include onboarding tip: “After installing or timeout, type ‘hello’ to get started”
4. Plan for users clicking bot and seeing nothing until they type

Optimize Triggers and Fallbacks

Teams users interact conversationally, so:

• Cover common greeting variants in trigger phrases
• Include farewell handling
• Provide multiple example utterances
• Make fallback behavior user-friendly

Fallback strategy:

• Use OnKnowledgeRequested to catch failed topic matches
• Inject helpful messages
• Redirect to relevant topics based on keywords
• Prompt users to rephrase if truly stuck

Manage Connector Authentication

If using connectors (Power Automate, Graph API, etc.):

Test the authentication flow:

• Verify login card appears first time
• Ensure token refresh during long conversations
• Plan for connector failures mid-conversation

Known issue: Connectors may not refresh tokens during extended sessions.

Solution: Use inactivity resets or /debug clearstate to re-trigger OAuth flow.

Communicate the “clearstate” command to support teams and power users for quick troubleshooting.

Testing in Real Conditions

Understand Persistent Sessions

Teams 1:1 chats retain context until explicitly cleared:

Advantages:

• Great for continuity
• Users can return and bot “remembers”

Challenges:

• Bugs and outdated context linger
• Changed logic doesn’t apply automatically
• Testing must account for session persistence

Deployment Testing Strategy

1. Deploy to yourself first (“Show to only me” option)
2. Test real scenarios:
   • Reopen chat after an hour
   • Publish update and verify changes
   • Test on Teams mobile and desktop
3. Verify Adaptive Cards render properly across clients
4. Test action responses in different contexts

Checklist for Robust Teams Deployment

• OnInactivity trigger configured to clear conversation history
• User messaging explains resets and guides restart
• /debug clearstate documented for users
• OnKnowledgeRequested trigger enabled for transparency during development
• Version identifier included in bot responses
• Force Update enabled on publish
• Greeting topic handles Teams initialization (and NOT conversation start)
• Trigger phrases cover conversational variants
• Fallback behavior is user-friendly
• Connector authentication tested thoroughly
• Real-world testing in Teams completed

Key Takeaways

• Manage session lifespan with inactivity triggers and clearstate options
• Make bot actions transparent through query rewrites and state messages
• Handle Teams channel nuances: manual greeting, persistent memory
• Keep bot version fresh with proper versioning and forced updates
• Empower users with self-service troubleshooting commands

Try It Yourself

1. Add an OnInactivity trigger to clear variables after 15 minutes
2. Configure a friendly message prompting users to say “hello”
3. Enable OnKnowledgeRequested to display search queries during testing
4. Include version information in your greeting message
5. Deploy with Force Update enabled and test session persistence

Questions or experiences with Teams deployment? Share your insights in the comments below or in the community forums.