Add existing AI Gateway deployment profile

[Paul Yuknewicz (paulyuk)]

Summary

• Add GATEWAY_DEPLOYMENT_MODE=managed|existing, defaulting to managed, while preserving the current full-stack azd up behavior.
• Add an upstream-owned .ai-gateway-studio.json handoff contract and matching POSIX and PowerShell bootstrap scripts.
• Provision only Foundry hosted-agent resources, secure project connections, the hosted agent, routine, and Toolbox when consuming an existing AI Gateway.
• Keep existing Gateway resources ownership-safe by excluding Gateway and model Bicep resources and preventing recovery, deletion, purge, provider/model creation, runtime-key creation, Connector Namespace creation, and GitHub ToolServer updates.
• Use separate Foundry RemoteTool and CustomKeys project connections so Gateway keys are never Bicep parameters, outputs, or ordinary hosted-agent environment substitutions.
• Use the stable Toolbox consumer endpoint based on FOUNDRY_PROJECT_ENDPOINT and TOOLBOX_NAME.

Existing gateway contract

{
  "schemaVersion": 1,
  "gatewayDeploymentMode": "existing",
  "gatewayResourceId": "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.ApiManagement/service/<gateway-name>",
  "gatewayEndpoint": "https://<gateway-host>/",
  "githubMcpEndpoint": "https://<gateway-host>/default/toolservers/<toolserver>/mcp",
  "modelAliases": {
    "default": "<full-model-alias>",
    "mini": "<mini-model-alias>"
  }
}

The resource ID also accepts the Microsoft.ApiManagement/aigateways resource type. The handoff contains no secrets.

Security and ownership

• Existing mode deploys no Gateway or separate Foundry model resources.
• Lifecycle hooks exit before Gateway discovery, recovery, deletion, purge, or identity cleanup.
• Existing-mode configuration performs no Gateway PUT, PATCH, or DELETE and never overwrites the existing GitHub ToolServer.
• The only existing Gateway control-plane reads are API-key listing and listSecrets, with listValues retained for preview compatibility.
• Hosted model calls resolve ${{connections.ai-gateway-model.target}} and ${{connections.ai-gateway-model.credentials.Api-Key}} from a Foundry CustomKeys connection.
• Toolbox uses a separate RemoteTool connection with an Api-Key custom header.
• Local mode-600 .env support remains available.

Validation

• POSIX shell syntax checks
• All four Bicep builds
• Python compile and 11 unit tests
• APIM lifecycle tests, including existing-mode no-delete and no-purge coverage
• AI Gateway model registration test
• Deployment-mode tests covering both profiles, excluded Gateway/model resources, forbidden Gateway mutations, GitHub ToolServer preservation, connection placeholders, bootstrap behavior, module scopes, and PowerShell guard placement
• git diff --check

Local PowerShell execution was unavailable because the installed pwsh process aborts before script parsing with a System.Text.RegularExpressions assembly load failure. Static parity assertions cover the critical existing-mode lifecycle guard.