azure-bot-service

name	azure-bot-service
description	Expert knowledge for Azure AI Bot Service development including troubleshooting, best practices, decision making, architecture & design patterns, limits & quotas, security, configuration, integrations & coding patterns, and deployment. Use when building bots with adaptive dialogs, Direct Line/Web Chat, Teams integration, OAuth/SSO, or proactive messages, and other Azure AI Bot Service related development tasks. Not for Azure Health Bot (use azure-health-bot), Azure Web PubSub (use azure-web-pubsub), Azure Functions (use azure-functions), Azure App Service (use azure-app-service).
compatibility	Requires network access. Uses mcp_microsoftdocs:microsoft_docs_fetch or fetch_webpage to retrieve documentation.
metadata	{"generated_at":"2026-08-02","generator":"docs2skills/1.0.0"}

Azure AI Bot Service Skill

This skill provides expert guidance for Azure AI Bot Service. Covers troubleshooting, best practices, decision making, architecture & design patterns, limits & quotas, security, configuration, integrations & coding patterns, and deployment. It combines local quick-reference content with remote documentation fetching capabilities.

How to Use This Skill

IMPORTANT for Agent: Use the Category Index below to locate relevant sections. For categories with line ranges (e.g., L35-L120), use read_file with the specified lines. For categories with file links (e.g., [security.md](security.md)), use read_file on the linked reference file

IMPORTANT for Agent: If metadata.generated_at is more than 3 months old, suggest the user pull the latest version from the repository. If mcp_microsoftdocs tools are not available, suggest the user install it: Installation Guide

This skill requires network access to fetch documentation content:

• Preferred: Use mcp_microsoftdocs:microsoft_docs_fetch with query string from=learn-agent-skill. Returns Markdown.
• Fallback: Use fetch_webpage with query string from=learn-agent-skill&accept=text/markdown. Returns Markdown.

Category Index

Category	Lines	Description
Troubleshooting	L37-L51	Debugging and troubleshooting bots: using Emulator, transcripts, Dev Tunnels, inspection middleware, fixing HTTP 500, auth, config/channel issues, and skill/consumer problems.
Best Practices	L52-L66	Guidance on designing, testing, and managing bot conversations: greetings, flow, navigation, interruptions, expirations, multimodal UX, debugging, unit testing, and Virtual Assistant best practices.
Decision Making	L67-L73	Guidance on selecting the right Microsoft bot platform, choosing Azure channels vs adapters, and picking the best Direct Line option based on integration, control, and hosting needs.
Architecture & Design Patterns	L74-L86	Designing bot architectures: dialog modularization, branching/looping flows, multi-LUIS/QnA routing, embedding bots in apps/web, human handoff, knowledge bots, and reusable skills.
Limits & Quotas	L87-L92	Handling long-running bot operations (deferred replies, proactive messages) and checking which channels support specific features, attachments, and card types.
Security	L93-L112	Securing Azure bots: auth/SSO (OAuth, Web Chat, skills), Direct Line security, network isolation/VNET, encryption, privacy, and configuring bot/connector authentication.
Configuration	L113-L157	Configuring Azure bots: adaptive dialogs/expressions, language generation and understanding, state/storage, telemetry/monitoring, Web Chat and channels, skills, and environment-specific settings.
Integrations & Coding Patterns	L158-L217	Connecting bots to channels (Teams, SMS, web, social), using Direct Line/Web Chat, handling activities/messages, media, cards, prompts, OAuth, state, skills, and channel-specific features.
Deployment	L218-L223	Guides for provisioning App Service, deploying Bot Framework bots to Azure, and setting up CI/CD pipelines for automated bot deployment.

Troubleshooting

Topic	URL
Debug bots using transcript files in Bot Framework	https://learn.microsoft.com/en-us/azure/bot-service/bot-builder-debug-transcript?view=azure-bot-service-4.0
Debug Bot Framework bots with Emulator and IDE	https://learn.microsoft.com/en-us/azure/bot-service/bot-service-debug-bot?view=azure-bot-service-4.0
Debug bot channels using Dev Tunnels	https://learn.microsoft.com/en-us/azure/bot-service/bot-service-debug-channel-devtunnel?view=azure-bot-service-4.0
Test and debug bots using Bot Framework Emulator	https://learn.microsoft.com/en-us/azure/bot-service/bot-service-debug-emulator?view=azure-bot-service-4.0
Debug bots with inspection middleware and Emulator	https://learn.microsoft.com/en-us/azure/bot-service/bot-service-debug-inspection-middleware?view=azure-bot-service-4.0
Interpret and handle Bot Framework User-Agent requests	https://learn.microsoft.com/en-us/azure/bot-service/bot-service-resources-user-agent?view=azure-bot-service-4.0
Diagnose and fix HTTP 500 errors in bots	https://learn.microsoft.com/en-us/azure/bot-service/bot-service-troubleshoot-500-errors?view=azure-bot-service-4.0
Troubleshoot Bot Framework authentication failures	https://learn.microsoft.com/en-us/azure/bot-service/bot-service-troubleshoot-authentication-problems?view=azure-bot-service-4.0
Fix configuration and channel issues in bots	https://learn.microsoft.com/en-us/azure/bot-service/bot-service-troubleshoot-bot-configuration?view=azure-bot-service-4.0

Best Practices

Topic	URL
Expire and restart bot conversations safely	https://learn.microsoft.com/en-us/azure/bot-service/bot-builder-howto-expire-conversation?view=azure-bot-service-4.0
Handle user interruptions in Azure bots	https://learn.microsoft.com/en-us/azure/bot-service/bot-builder-howto-handle-user-interrupt?view=azure-bot-service-4.0
Implement welcome messages in Azure Bot Service	https://learn.microsoft.com/en-us/azure/bot-service/bot-builder-send-welcome-message?view=azure-bot-service-4.0
Apply debugging guidelines for Azure bots	https://learn.microsoft.com/en-us/azure/bot-service/bot-builder-testing-debugging?view=azure-bot-service-4.0
Apply Virtual Assistant template best practices	https://learn.microsoft.com/en-us/azure/bot-service/bot-builder-virtual-assistant-introduction?view=azure-bot-service-4.0
Design and control bot conversation flow	https://learn.microsoft.com/en-us/azure/bot-service/bot-service-design-conversation-flow?view=azure-bot-service-4.0
Design a bot’s first interaction with users	https://learn.microsoft.com/en-us/azure/bot-service/bot-service-design-first-interaction?view=azure-bot-service-4.0
Design navigation patterns for conversational bots	https://learn.microsoft.com/en-us/azure/bot-service/bot-service-design-navigation?view=azure-bot-service-4.0
Design effective conversational experiences with Bot Framework	https://learn.microsoft.com/en-us/azure/bot-service/bot-service-design-principles?view=azure-bot-service-4.0

Decision Making

Topic	URL
Choose the right Microsoft chatbot solution	https://learn.microsoft.com/en-us/azure/bot-service/bot-overview?view=azure-bot-service-4.0
Choose between Azure channels and adapters for bots	https://learn.microsoft.com/en-us/azure/bot-service/bot-service-channel-additional-channels?view=azure-bot-service-4.0
Choose the right Direct Line option for bots	https://learn.microsoft.com/en-us/azure/bot-service/bot-service-channel-directline?view=azure-bot-service-4.0

Architecture & Design Patterns

Topic	URL
Modularize bot dialogs with component dialogs	https://learn.microsoft.com/en-us/azure/bot-service/bot-builder-compositcontrol?view=azure-bot-service-4.0
Create advanced branching and looping dialogs	https://learn.microsoft.com/en-us/azure/bot-service/bot-builder-dialog-manage-complex-conversation-flow?view=azure-bot-service-4.0
Route across multiple LUIS and QnA projects	https://learn.microsoft.com/en-us/azure/bot-service/bot-builder-tutorial-orchestrator?view=azure-bot-service-4.0
Embed Azure bots inside native or web apps	https://learn.microsoft.com/en-us/azure/bot-service/bot-service-design-pattern-embed-app?view=azure-bot-service-4.0
Embed Azure bots into websites with web control	https://learn.microsoft.com/en-us/azure/bot-service/bot-service-design-pattern-embed-web-site?view=azure-bot-service-4.0
Design bot-to-human handoff patterns in Bot Framework	https://learn.microsoft.com/en-us/azure/bot-service/bot-service-design-pattern-handoff-human?view=azure-bot-service-4.0
Architect knowledge bots for information retrieval	https://learn.microsoft.com/en-us/azure/bot-service/bot-service-design-pattern-knowledge-base?view=azure-bot-service-4.0
Design and manage skill consumer (root) bots	https://learn.microsoft.com/en-us/azure/bot-service/skills-about-skill-consumers?view=azure-bot-service-4.0
Architect and reuse skills across Bot Framework bots	https://learn.microsoft.com/en-us/azure/bot-service/skills-conceptual?view=azure-bot-service-4.0

Limits & Quotas

Topic	URL
Handle long-running operations in Azure bots	https://learn.microsoft.com/en-us/azure/bot-service/bot-builder-howto-long-operations-guidance?view=azure-bot-service-4.0
Channel feature and card support reference	https://learn.microsoft.com/en-us/azure/bot-service/bot-service-channels-reference?view=azure-bot-service-4.0

Security

Topic	URL
Use federated identity credentials for bot auth	https://learn.microsoft.com/en-us/azure/bot-service/bot-builder-authentication-federated-credential?view=azure-bot-service-4.0
Configure single sign-on between root and skill bots	https://learn.microsoft.com/en-us/azure/bot-service/bot-builder-authentication-sso?view=azure-bot-service-4.0
Add OAuth-based user authentication to bots	https://learn.microsoft.com/en-us/azure/bot-service/bot-builder-authentication?view=azure-bot-service-4.0
Configure regionalization for Azure AI Bot Service	https://learn.microsoft.com/en-us/azure/bot-service/bot-builder-concept-regionalization?view=azure-bot-service-4.0
Implement single sign-on in Bot Framework bots	https://learn.microsoft.com/en-us/azure/bot-service/bot-builder-concept-sso?view=azure-bot-service-4.0
Secure Direct Line with enhanced authentication	https://learn.microsoft.com/en-us/azure/bot-service/bot-builder-security-enhanced?view=azure-bot-service-4.0
Apply security guidelines to Bot Framework bots	https://learn.microsoft.com/en-us/azure/bot-service/bot-builder-security-guidelines?view=azure-bot-service-4.0
Implement single sign-on for Web Chat bots	https://learn.microsoft.com/en-us/azure/bot-service/bot-builder-webchat-sso?view=azure-bot-service-4.0
Use Direct Line App Service extension in a VNET	https://learn.microsoft.com/en-us/azure/bot-service/bot-service-channel-directline-extension-vnet?view=azure-bot-service-4.0

Configuration

Topic	URL
Configure prebuilt adaptive dialog actions in Bot Framework	https://learn.microsoft.com/en-us/azure/bot-service/adaptive-dialog/adaptive-dialog-prebuilt-actions?view=azure-bot-service-4.0
Use prebuilt input dialogs for collecting user data	https://learn.microsoft.com/en-us/azure/bot-service/adaptive-dialog/adaptive-dialog-prebuilt-inputs?view=azure-bot-service-4.0
Reference memory scopes and paths in adaptive dialogs	https://learn.microsoft.com/en-us/azure/bot-service/adaptive-dialog/adaptive-dialog-prebuilt-memory-states?view=azure-bot-service-4.0
Configure built-in recognizers for adaptive dialogs	https://learn.microsoft.com/en-us/azure/bot-service/adaptive-dialog/adaptive-dialog-prebuilt-recognizers?view=azure-bot-service-4.0
Use prebuilt adaptive dialog triggers in Bot Framework	https://learn.microsoft.com/en-us/azure/bot-service/adaptive-dialog/adaptive-dialog-prebuilt-triggers?view=azure-bot-service-4.0
Adaptive expressions API reference for Bot Framework	https://learn.microsoft.com/en-us/azure/bot-service/adaptive-expressions/adaptive-expressions-api-reference?view=azure-bot-service-4.0
Use prebuilt adaptive expression functions in bots	https://learn.microsoft.com/en-us/azure/bot-service/adaptive-expressions/adaptive-expressions-prebuilt-functions?view=azure-bot-service-4.0
Use adaptive expressions in Bot Framework dialogs	https://learn.microsoft.com/en-us/azure/bot-service/bot-builder-concept-adaptive-expressions?view=azure-bot-service-4.0

Integrations & Coding Patterns

Topic	URL
Handle Microsoft Teams activities in bots	https://learn.microsoft.com/en-us/azure/bot-service/bot-builder-basics-teams?view=azure-bot-service-4.0
Use channelData for channel-specific bot features	https://learn.microsoft.com/en-us/azure/bot-service/bot-builder-channeldata?view=azure-bot-service-4.0
Proxy custom OAuth2 identity providers for bots	https://learn.microsoft.com/en-us/azure/bot-service/bot-builder-concept-identity-providers-proxy?view=azure-bot-service-4.0
Implement custom state storage for Azure bots	https://learn.microsoft.com/en-us/azure/bot-service/bot-builder-custom-storage?view=azure-bot-service-4.0
Implement sequential dialogs in Bot Framework	https://learn.microsoft.com/en-us/azure/bot-service/bot-builder-dialog-manage-conversation-flow?view=azure-bot-service-4.0
Send media attachments with Azure Bot Framework	https://learn.microsoft.com/en-us/azure/bot-service/bot-builder-howto-add-media-attachments?view=azure-bot-service-4.0
Use suggested action buttons in Bot Framework	https://learn.microsoft.com/en-us/azure/bot-service/bot-builder-howto-add-suggested-actions?view=azure-bot-service-4.0
Use Azure question answering in bots	https://learn.microsoft.com/en-us/azure/bot-service/bot-builder-howto-answer-questions?view=azure-bot-service-4.0
Send proactive notifications from Azure bots	https://learn.microsoft.com/en-us/azure/bot-service/bot-builder-howto-proactive-message?view=azure-bot-service-4.0

Deployment

Topic	URL
Set up continuous deployment for Azure bots	https://learn.microsoft.com/en-us/azure/bot-service/bot-service-build-continuous-deployment?view=azure-bot-service-4.0
Provision and deploy Bot Framework bots to Azure	https://learn.microsoft.com/en-us/azure/bot-service/provision-and-publish-a-bot?view=azure-bot-service-4.0
Provision Azure App Service for bot deployment via CLI	https://learn.microsoft.com/en-us/azure/bot-service/provision-app-service?view=azure-bot-service-4.0