Getting a Microsoft Foundry agent published into Microsoft Teams is no longer a black box. After my previous post on the portal experience and outlining the AI Bot Service’s role in enabling Teams interaction, I’m diving deeper into the network architecture to bolster security controls and programmatic agent publishing.

Teams requires the agent's messaging endpoint to be accessible via the Microsoft public backbone, which introduces security and networking challenges. This post explores a hardened design pattern featuring Azure Application Gateway and API Management v2 tier, leveraging WAF and JWT validation, while avoiding publicly exposing API Management IPs.

Beyond the architecture, I'll walk through automating the entire publishing workflow using Python and Terraform — eliminating manual “push the blue button” steps. The code samples and practical guidance here will help you set up, secure, and automate your Foundry Agents to Teams integration.

Architecture Overview

┌────────────────────────────────────────────┐
│Architecture                                │
├────────────────────────────────────────────┤
│• Enterprise data sources                   │
│• Foundry platform                          │
│• AI applications                           │
└────────────────────────────────────────────┘

Key Technical Observations

• Application Gateway as a Security Boundary — Placing Azure Application Gateway with WAF capabilities in front of API Management reduces public attack surface exposure and permits host/path-based routing and granular source IP validation (e.g., only allow Microsoft Teams IP ranges).

• JWT Validation in API Management — APIM enforces authentication by validating JWT tokens issued by Bot Framework with claims verification (notably the serviceurl claim containing tenant-specific values), protecting agent endpoints from rogue callers.

• Private Endpoint Integration for Foundry Agents — By routing through APIM within an injected VNet and leveraging Private Endpoints, the Foundry Agent services remain isolated from public exposure, responding only via controlled ingress points.

• Asynchronous TCP Sessions Prevent Asymmetric Routing Concerns — Although inbound and outbound communication paths differ, separate TCP connections used by Teams and Agents avoid traditional routing asymmetry issues, simplifying firewall configurations.

• Programmatic Publishing Unlocks DevOps Automation — The discovery, activation, and publishing of agents to Teams are fully scriptable using Python and Terraform leveraging Foundry APIs, significantly improving CI/CD workflows over manual portal interactions.

• Use of Azure Machine Learning API Endpoint Internally — The final publishing call hits an Azure ML API endpoint under the hood, revealing Foundry’s architectural dependence on Azure ML for operational functionality, a critical insight for debugging and integration.

How It Works: Securing and Automating Publishing Agents to Teams

Securing Agent Endpoints Using Application Gateway and APIM

The publishing workflow starts with exposing the agent’s messaging endpoint to Microsoft Teams via a public IP. To avoid directly exposing API Management, the design places an Application Gateway in front acting as a WAF-enabled reverse proxy.

Application Gateway Configuration

• Public listener with SSL termination
• Host and path-based routing to direct /agents path to APIM
• WAF rules configured to allow only IPs from Microsoft Teams service IP ranges (official IP ranges)
• Request header validation via WAF custom rules (e.g., validating presence of x-ms-tenant-id with expected tenant ID)

APIM Policies for JWT Validation

APIM exposes an API with a PublishedAgent operation which enforces JWT validation middleware:

<policies>
  <inbound>
    <base />
    <validate-jwt header-name="Authorization" require-scheme="Bearer">
      <openid-config url="https://login.botframework.com/v1/.well-known/openidconfiguration" />
      <audiences>
        <audience>8fd8ec07-ae24-4038-8771-6d4b85a4b19a</audience>
      </audiences>
      <issuers>
        <issuer>https://api.botframework.com</issuer>
      </issuers>
      <required-claims>
        <claim name="serviceurl" match="all">
          <value>https://smba.trafficmanager.net/amer/6c80de31-d5e4-4029-93e4-5a2b3c0e1299/</value>
        </claim>
      </required-claims>
    </validate-jwt>
  </inbound>
  <backend>
    <base />
  </backend>
  <outbound>
    <base />
  </outbound>
  <on-error>
    <base />
  </on-error>
</policies>

This policy ensures only authorized bot messages originating from the expected Bot Framework tenant are accepted.

Programmatically Publishing Agents with Python and Terraform

To avoid manual clicks in the Foundry Portal, automation scripts leverage Foundry REST APIs. Here's a condensed flow:

1. Create Bot Service Resource — Terraform templates automate bot creation linked to the Foundry agent.

2. Fetch Required Identity Information:

   • Obtain EntraID tenant ID:
     bash az account show --query tenantId -o tsv
   • Use Azure SDK to get an access token scoped to Foundry:
     ```python
     from azure.identity import DefaultAzureCredential

   credential = DefaultAzureCredential()
   scopes = ["https://ai.azure.com"]
   token = credential.get_token(*scopes)
   ```

3. Query the Foundry Agent to retrieve associated principal IDs for identity binding:
   ```python
   import requests

   def get_foundry_agent(account, project, agent, token):
   url = f"https://{account}.services.ai.azure.com/api/projects/{project}/agents/{agent}?api-version=v1"
   headers = {"Authorization": f"Bearer {token}"}
   response = requests.get(url, headers=headers)
   return response.json() if response.status_code == 200 else None
   ```

4. Enable Agent Activity Protocol by patching the agent configuration with supported protocols and authorization schemes:
   python body = { "agent_endpoint": { "protocols": ["responses", "activity"], "authorization_schemes": [ {"type": "Entra", "isolation_key_source": {"kind": "Entra"}}, {"type": "BotServiceRbac"} ] } } # PATCH request to Foundry agent API with above body

5. Publish the Agent to Teams invoking the Foundry API:
   python def publish_agent_teams(...): # payload includes subscription, agent GUID, bot ID, descriptions, URLs # POST request to Azure ML-based publish endpoint

This automation mirrors all portal functionality and integrates smoothly into CI/CD pipelines.

Quick Tips & Tricks

1. Leverage Application Gateway WAF IP Restrictions — Configure WAF rules to only allow traffic from Microsoft Teams official IP ranges, preventing unauthorized access early.

2. Validate Tenant ID in Request Headers — Use WAF or APIM policy rules to verify the x-ms-tenant-id header matches your Azure AD tenant, adding a layer beyond IP allowlisting.

3. Use APIM JWT Validate-Claims to Secure APIs — Customize JWT validation policies to assert specific claims, such as the Bot Framework’s serviceurl, ensuring requests originate from legitimate bot services.

4. Automate with Azure SDK and Terraform — Script resource creation and configuration with Azure SDK for Python and Terraform templates for repeatability and infrastructure-as-code best practices.

5. Use Private Endpoints for Isolated Backend Connectivity — Always route Foundry Agent services through private endpoints inside VNets to prevent public exposure.

6. Understand Foundry’s Azure ML Dependency — The Teams publish API routes through an Azure Machine Learning endpoint; this knowledge is useful when troubleshooting API errors or latency.

Conclusion

Microsoft Foundry’s seamless integration with Teams offers powerful opportunities to deploy AI agents inside familiar collaboration tools. However, exposing these agents securely requires thoughtful network design — leveraging Application Gateway with WAF capabilities combined with API Management’s robust JWT validation provides a hardened security posture without sacrificing flexibility.

Furthermore, automating the entire publishing pipeline through code unlocks faster, repeatable deployments, eliminates manual errors, and fits well within modern DevOps practices. The discovery of Foundry’s architectural layering on Azure Machine Learning hints at underlying scalability and capability expansion possibilities.

As Microsoft continues evolving Foundry and Teams ecosystem, adopting secure, automated publishing workflows will become a foundational best practice for enterprises seeking to harness AI-powered agents securely and efficiently.

References

1. Microsoft Foundry – Publishing Agents To Teams Deep Dive – Part 2 | Journey Of The Geek
2. Microsoft Teams URLs and IP Address Ranges — Official Microsoft documentation on Teams network requirements.
3. Microsoft Bot Framework OpenID Configuration — Used for JWT validation in APIM.
4. Terraform Bot Service Module — Example Terraform templates for automating Bot Service resource.
5. Publish Agent Programmatic Sample (Jupyter Notebook) — Python code example automating publishing.
6. Graeme’s Blog on Foundry Agents and Custom Engine Agents — Additional context on proxy architectures for Foundry agents.