Issue Type: Architecture & Design / Integration Issue Services: Azure AI Foundry, Azure Bot Service, Microsoft Entra ID

Environment Details:

• Resource Tenant (hosts Azure AI & Bot): <ResourceTenant>
  • User/Home Tenant (hosts Microsoft Teams): <HomeTenant>
  • SDK Used: azure-ai-projects (v2.0.1+)

Context & Business Goal: We needed to deploy an internal Helpdesk AI Agent built in Azure AI Foundry (<ResourceTenant>) as a one-on-one personal chat bot to our end-users via Microsoft Teams (<HomeTenant>).

The Initial Challenge: The standard out-of-the-box Foundry Teams deployment (using the auto-generated .zip manifest and User-Assigned Managed Identity) hard-fails across tenant boundaries. Users in the foreign tenant are trapped in an endless OAuth "Sign-In" loop, resulting in a 500 Internal Server Error from the /protocols/activityprotocol endpoint.

Our Implemented Solution (The "Broker Pattern"): To bypass the direct OAuth link and successfully cross the tenant boundary for these 1-on-1 chats, we designed a custom stateful middleware proxy. The architecture consists of four layers:

1. Identity & Access Management (Microsoft Entra ID)

<!-- end list -->

• We created a custom App Registration in the resource tenant and configured it as Multi-Tenant.
  • We generated a Client Secret to securely authenticate our proxy to the Bot Framework and Foundry without relying on the locked-down Managed Identity.

<!-- end list -->

2. The Traffic Gateway (Azure Bot Service)

<!-- end list -->

• We provisioned a new Azure Bot resource configured as Single-Tenant (as the classic Multi-Tenant bot creation is deprecated) and tied it directly to our custom Multi-Tenant App Registration.
  • We configured the Bot's messaging endpoint to route all Teams webhook traffic to our custom Python middleware.

<!-- end list -->

3. The Stateful Middleware (Python FastAPI Proxy)

<!-- end list -->

• We built a custom Python microservice that acts as the translator between Teams and Foundry.
  • State Mapping: It extracts the Teams conversation.id and maps it to the Azure AI conversation.id to ensure the agent retains multi-turn memory for each user's 1-on-1 session.
  • AI Integration: It uses the azure-ai-projects (v2.0+) SDK via App-Only credentials to natively push messages and fetch AI responses using the responses.create protocol.
  • Cross-Tenant Delivery: It requests a Bot Framework token from the resource tenant endpoint and uses pure REST API (httpx) to POST the reply back to the smba.trafficmanager.net service URL. We strictly mirror the Teams replyToId, recipient, and conversation payload objects to successfully bypass Teams' strict 401 Unauthorized cross-tenant injection blocks.

<!-- end list -->

4. The Client Interface (Microsoft Teams)

<!-- end list -->

• We manually decoupled the auto-generated Foundry Teams manifest.json, mapping the id, botId, and webApplicationInfo strictly to our new Multi-Tenant App Registration, scoped it to "personal", and side-loaded it into the home tenant.

Our Ask for Architectural Review: The solution is currently working perfectly in proof-of-concept, maintaining context and securely crossing the tenant boundary using this hybrid Single-Tenant Bot / Multi-Tenant App Registration approach. We are requesting a high-level engineering review of the architecture:

1. Is this "Broker Pattern" the officially recommended best practice for cross-tenant Foundry Agents, or are there native cross-tenant capabilities in Foundry that would eliminate the need for this custom middleware?
2. From an Identity and Access Management perspective, are there any security enhancements you recommend for our custom API Bot Framework routing setup?
3. Does Microsoft recommend migrating the raw REST API Bot Framework calls to the official botbuilder-core Python SDK for production workloads, or is our raw HTTP approach fully supported?

Please note: The code below is a simplified Proof-of-Concept strictly to illustrate the Teams-to-Foundry payload routing and OAuth token exchange. We are not requesting a code review of the application logic itself (e.g., we will be using external caches like Redis for state management in production, not the in-memory dictionary shown below). We are providing this solely to demonstrate the REST API calls used to cross the tenant boundary.

from fastapi import FastAPI, Request, Response, BackgroundTasks import httpx from azure.identity.aio import ClientSecretCredential from azure.ai.projects.aio import AIProjectClient

app = FastAPI()

--- 1. CREDENTIALS & CONFIGURATION ---

BOT_APP_ID = "<REDACTED_APP_ID>" BOT_APP_SECRET = "<REDACTED_APP_SECRET>" FOUNDRY_TENANT_ID = "<REDACTED_TENANT_ID>"

--- 2. AZURE AI FOUNDRY CONFIGURATION ---

AGENT_NAME = "<REDACTED_AGENT_NAME>"

credential = ClientSecretCredential( tenant_id=FOUNDRY_TENANT_ID, client_id=BOT_APP_ID, client_secret=BOT_APP_SECRET )

--- 3. IN-MEMORY STATE STORE (PoC ONLY) ---

session_memory = {}

async def process_and_reply(payload: dict, user_text: str): teams_conv_id = payload.get("conversation", {}).get("id") ai_response_text = ""

try:
    async with AIProjectClient(
        endpoint="<REDACTED_ENDPOINT>",
        subscription_id="<REDACTED_SUBSCRIPTON_ID>",
        resource_group_name="<REDACTED_RESOURCE_GROUP>",
        project_name="<REDACTED_PROJECT_NAME>",
        credential=credential
    ) as project_client:
        
        async with project_client.get_openai_client() as openai_client:
            
            if teams_conv_id in session_memory:
                azure_conv_id = session_memory[teams_conv_id]
                await openai_client.conversations.items.create(
                    conversation_id=azure_conv_id,
                    items=[{"type": "message", "role": "user", "content": user_text}]
                )
            else:
                conversation = await openai_client.conversations.create(
                    items=[{"type": "message", "role": "user", "content": user_text}]
                )
                azure_conv_id = conversation.id
                session_memory[teams_conv_id] = azure_conv_id
            
            response = await openai_client.responses.create(
                conversation=azure_conv_id,
                extra_body={"agent_reference": {"name": AGENT_NAME, "type": "agent_reference"}}
            )
            ai_response_text = response.output_text

except Exception as e:
    ai_response_text = "Sorry, I couldn't reach my internal knowledge base right now."

token_url = f"[https://login.microsoftonline.com/](https://login.microsoftonline.com/){FOUNDRY_TENANT_ID}/oauth2/v2.0/token"
token_data = {
    "grant_type": "client_credentials",
    "client_id": BOT_APP_ID,
    "client_secret": BOT_APP_SECRET,
    "scope": "[https://api.botframework.com/.default](https://api.botframework.com/.default)"
}

try:
    async with httpx.AsyncClient() as client:
        token_response = await client.post(token_url, data=token_data)
        token_response.raise_for_status()
        bot_token = token_response.json().get("access_token")

    service_url = payload.get("serviceUrl")
    reply_url = f"{service_url}v3/conversations/{teams_conv_id}/activities/{payload['id']}"

    reply_activity = {
        "type": "message",
        "text": ai_response_text,
        "replyToId": payload.get("id"),
        "from": payload.get("recipient"),           
        "recipient": payload.get("from"),
        "conversation": payload.get("conversation") 
    }

    headers = {
        "Authorization": f"Bearer {bot_token}",
        "Content-Type": "application/json"
    }

    async with httpx.AsyncClient(timeout=45.0) as client:
        post_response = await client.post(reply_url, json=reply_activity, headers=headers)
        post_response.raise_for_status()
        
except Exception as e:
    print(f"Failed to send message back to Teams: {str(e)}")

@app.post("/api/messages") async def handle_teams_messages(request: Request, background_tasks: BackgroundTasks): payload = await request.json() user_text = payload.get("text", "").strip()

if not user_text and payload.get("type") != "message":
    return Response(status_code=200)

background_tasks.add_task(process_and_reply, payload, user_text)
return Response(status_code=200)