docs(DATAGO-116733): Add Teams bot tenant configuration and Agent Builder download guidance

docs/docs/documentation/developing/tutorials/teams-integration.md

@@ -7,9 +7,9 @@ sidebar_position: 70
 
 This tutorial shows you how to integrate Microsoft Teams with Agent Mesh Enterprise, allowing users to interact with the system directly from Teams workspaces and channels.
 
-:::warning[Enterprise Feature - Docker Deployment Only]
-The Microsoft Teams Gateway is an Enterprise feature included in the Docker image. It is not available when installing via PyPI or wheel files. This feature requires:
-- Agent Mesh Enterprise Docker deployment
+:::warning[Enterprise Feature - Docker Image Only]
+The Microsoft Teams Gateway is an Enterprise feature included in the Docker image. It works with both Docker and Kubernetes deployments but is not available when installing via PyPI or wheel files. This feature requires:
+- Agent Mesh Enterprise Docker image (deployed via Docker or Kubernetes)
 - Azure Active Directory tenant access
 - Azure Bot Service setup
 :::
@@ -35,6 +35,38 @@ When users send messages, the gateway streams responses back in real time, updat
 
 The gateway operates in single-tenant mode, meaning it works within your organization's Azure AD tenant. This approach provides better security and simpler management for enterprise deployments.
 
+## Bot Configuration: Multi-Tenant vs Single-Tenant
+
+Microsoft Teams bots can be configured as either **multi-tenant** or **single-tenant**. The difference is controlled by the `microsoft_app_tenant_id` field:
+
+### Single-Tenant (Recommended)
+Users from **your organization only** can access the bot.
+
+```yaml
+microsoft_app_id: ${TEAMS_BOT_ID}
+microsoft_app_password: ${TEAMS_BOT_PASSWORD}
+microsoft_app_tenant_id: ${AZURE_TENANT_ID}  # Include this line
+```
+
+### Multi-Tenant (Deprecated July 2025)
+Users from **any Azure AD organization** can access the bot.
+
+```yaml
+microsoft_app_id: ${TEAMS_BOT_ID}
+microsoft_app_password: ${TEAMS_BOT_PASSWORD}
+# Do NOT include microsoft_app_tenant_id
+```
+
+:::warning
+Multi-tenant apps are being deprecated by Microsoft after July 2025. Use single-tenant configuration for new deployments.
+:::
+
+**This guide uses single-tenant configuration throughout.**
+
+**Additional Configuration Resources:**
+- Bot Framework Portal: https://dev.botframework.com/bots
+- Teams Developer Portal: https://dev.teams.cloud.microsoft/
+
 ## Azure Setup
 
 Setting up the Teams integration requires creating several Azure resources. You configure these resources in a specific order because each one depends on information from the previous step.
@@ -231,3 +263,15 @@ Key parameters:
 - `initial_status_message`: Feedback shown when users first send a message
 - `system_purpose`: Defines the bot's role and behavior
 - `response_format`: Instructions for response formatting (e.g., markdown)
+
+## Troubleshooting
+
+### Error: "App is missing service principal in tenant"
+
+This error occurs when using single-tenant configuration (with `microsoft_app_tenant_id` set) but the app isn't properly registered in that tenant.
+
+**Solution:**
+1. Verify the `AZURE_TENANT_ID` matches your Azure AD tenant
+2. Use multi-tenant by removing `microsoft_app_tenant_id` (temporary workaround)
+3. Register service principal: `az ad sp create --id YOUR-APP-ID`
+4. Verify your configuration: https://dev.botframework.com/bots

docs/docs/documentation/enterprise/agent-builder.md

@@ -85,6 +85,42 @@ When you deploy an agent, the system records its configuration. If you later edi
 
 Downloading agents as YAML files provides portability and version control. These files support backing up agent configurations, sharing configurations between deployments, tracking configuration changes in version control systems, and deploying agents using infrastructure-as-code tools.
 
+## Downloading Agent Configurations
+
+The Download button allows you to export agent configurations as YAML files. These files are designed for the **Agent Deployer** running in Kubernetes/Helm environments.
+
+### What Downloaded YAML Files Are Designed For
+
+Agent Builder generates YAML files optimized for automated deployment through the Agent Deployer. These files:
+
+- Use S3-compatible artifact storage (expects SeaweedFS or similar in K8s)
+- Contain environment variable placeholders for credentials and settings
+- Do not reference `shared_config.yaml` (unlike agents created with `sam add agent`)
+- Are ready to deploy through the Agent Deployer without modification
+
+:::info[Agent Deployer vs Manual Deployment]
+**Agent Deployer (Recommended):** Click "Deploy" in Agent Builder to deploy agents directly to your Kubernetes cluster. The agent deployer handles all configuration automatically.
+
+**Download for Manual Use:** Download the YAML file if you need to run agents outside Kubernetes or want to review/customize the configuration.
+:::
+
+### When to Download
+
+**Use the Download button when you need to:**
+- Back up agent configurations for version control
+- Review generated configuration before deployment
+- Share agent configurations between teams or environments
+- Run agents in workshops or demos without K8s infrastructure
+
+**Use the Deploy button when:**
+- You have Kubernetes/Helm infrastructure set up
+- You want automated deployment without manual configuration
+- You want the agent deployer to manage the agent lifecycle
+
+:::warning[Configuration Required]
+Downloaded YAML files are designed for the agent deployer and require manual configuration changes to run locally. For local development, consider using `sam add agent` instead, which generates files with `shared_config` references.
+:::
+
 ## Access Control
 
 Agent Builder operations require specific RBAC capabilities. The table below shows the capabilities and what they control: