update links and add some guides (#392)

* update links

* update examples

---------

Co-authored-by: vtomar <vtomar@microsoft.com>

Author: Vijendra123

samples/microsoft/infrastructure-setup/01-connections/apim-and-modelgateway-integration-guide.md

@@ -19,6 +19,19 @@
 
 The **Bring Your Own AI Gateway** feature in Foundry enables organizations to connect and use AI models hosted behind their enterprise gateways directly within the Foundry platform. This capability allows you to maintain control over your model endpoints while leveraging the power of Foundry's agent capabilities.
 
+### 🎯 Connection Type Selection
+
+**Choose the right connection type for your gateway:**
+
+| Gateway Type | Connection Type | When to Use | Setup Guide |
+|--------------|-----------------|-------------|-------------|
+| **🏢 Azure API Management** | APIM Connection | If you are using Azure API Management service directly as your gateway | [APIM Setup](./apim/) |
+| **🌐 Other Gateways** | ModelGateway Connection | If you are using any other gateway (self-hosted, third-party, or custom solutions) | [ModelGateway Setup](./model-gateway/) |
+
+> **💡 Quick Decision**: 
+> - **Azure API Management service** → Use **APIM Connection**
+> - **Everything else** (Kong, MuleSoft, custom gateways, etc.) → Use **ModelGateway Connection**
+
 ### 💡 Key Benefits
 
 | Benefit | Description |
@@ -278,8 +291,8 @@ Unified connections for various AI model providers through self-hosted or third-
 ### Step 2️⃣: Create Your Gateway Connection
 
 📚 **Detailed Instructions**:
-- **APIM Connections**: [APIM Connection Setup Guide](./apim/README.md) - Complete walkthrough for Azure API Management
-- **ModelGateway Connections**: [ModelGateway Setup Guide](./model-gateway/README.md) - Step-by-step for self-hosted/third-party gateways
+- **APIM Connections**: [APIM Setup Guide](./apim/apim-setup-guide-for-agents.md) - Complete walkthrough for Azure API Management
+- **ModelGateway Connections**: [ModelGateway Setup Guide](./model-gateway/modelgateway-setup-guide-for-agents.md) - Step-by-step for self-hosted/third-party gateways
 
 1. **📋 Choose the appropriate template**:
    ```bash
@@ -327,16 +340,22 @@ Unified connections for various AI model providers through self-hosted or third-
 
 ## 📚 Resources & Links
 
-### 🔧 Setup Guides
+### 🏢 APIM Connections
 
 | Resource | Description | Link |
 |----------|-------------|------|
-| **🏢 Azure API Management Setup Guide** | Complete guide for importing AI Foundry and Azure OpenAI resources, adding list/get deployment endpoints, and verification | [APIM Setup Guide](./apim-setup-guide.md) |
+| **🏢 Azure API Management Setup Guide** | Complete guide for importing AI Foundry and Azure OpenAI resources, adding list/get deployment endpoints, and verification | [APIM Setup Guide](./apim/apim-setup-guide-for-agents.md) |
+| **🔗 APIM Connection Configuration** | Detailed JSON schema, examples, and configuration options for APIM connections | [APIM Connection Objects](./apim/APIM-Connection-Objects.md) |
+| **📋 How to Create APIM Connections** | Step-by-step instructions for creating Azure API Management gateway connections | [APIM Connection Setup README](./apim/README.md) |
+| **🔒 Private Network APIM Setup** | Bicep template for secure private network APIM gateway setup with Agents BYO VNet | [Private APIM Setup](https://github.com/azure-ai-foundry/foundry-samples/tree/main/samples/microsoft/infrastructure-setup/16-private-network-standard-agent-apim-setup-preview) |
 | **📖 Azure API Management GenAI Gateway** | Official Microsoft documentation on Azure API Management GenAI gateway capabilities and features | [GenAI Gateway Capabilities](https://learn.microsoft.com/en-in/azure/api-management/genai-gateway-capabilities) |
 | **🔗 Azure AI Foundry API in APIM** | Official Microsoft documentation on integrating Azure AI Foundry APIs with Azure API Management | [Azure AI Foundry API](https://learn.microsoft.com/en-in/azure/api-management/azure-ai-foundry-api) |
 | **🔗 Azure OpenAI API from Specification** | Official Microsoft documentation on importing Azure OpenAI APIs into Azure API Management from specification | [Azure OpenAI API Import](https://learn.microsoft.com/en-in/azure/api-management/azure-openai-api-from-specification) |
-| **🔒 Private Network APIM Setup** | Bicep template for secure private network APIM gateway setup with Agents BYO VNet | [Private APIM Setup](https://github.com/azure-ai-foundry/foundry-samples/tree/main/samples/microsoft/infrastructure-setup/16-private-network-standard-agent-apim-setup-preview) |
-| **�🔗 APIM Connection Configuration** | Detailed JSON schema, examples, and configuration options for APIM connections | [APIM Connection Objects](./apim/APIM-Connection-Objects.md) |
+
+### 🌉 ModelGateway Connections
+
+| Resource | Description | Link |
+|----------|-------------|------|
+| **🌉 ModelGateway Setup Guide** | Complete guide for configuring self-hosted and third-party gateways for Foundry Agents integration | [ModelGateway Setup Guide](./model-gateway/modelgateway-setup-guide-for-agents.md) |
 | **🔗 ModelGateway Connection Configuration** | Detailed JSON schema, examples, and configuration options for ModelGateway connections | [ModelGateway Connection Objects](./model-gateway/ModelGateway-Connection-Objects.md) |
-| **📋 How to Create APIM Connections** | Step-by-step instructions for creating Azure API Management gateway connections | [APIM Connection Setup README](./apim/README.md) |
 | **📋 How to Create ModelGateway Connections** | Step-by-step instructions for creating ModelGateway connections for self-hosted/third-party gateways | [ModelGateway Setup README](./model-gateway/README.md) |

samples/microsoft/infrastructure-setup/01-connections/apim/APIM-Connection-Objects.md

@@ -141,29 +141,23 @@ We support exactly **2 deployment API formats** for model discovery through APIM
 {
   "value": [
     {
-      "id": "/subscriptions/.../deployments/gpt-4-deployment",
-      "name": "gpt-4-deployment",
-      "type": "Microsoft.CognitiveServices/accounts/deployments",
+      "name": "gpt-4o-deployment",
       "properties": {
         "model": {
           "format": "OpenAI",
-          "name": "gpt-4",
-          "version": "0613"
-        },
-        "provisioningState": "Succeeded"
+          "name": "gpt-4o",
+          "version": "2024-11-20"
+        }
       }
     },
     {
-      "id": "/subscriptions/.../deployments/gpt-35-turbo-deployment",
-      "name": "gpt-35-turbo-deployment", 
-      "type": "Microsoft.CognitiveServices/accounts/deployments",
+      "name": "gpt-5-deployment", 
       "properties": {
         "model": {
           "format": "OpenAI",
-          "name": "gpt-35-turbo",
-          "version": "0613"
-        },
-        "provisioningState": "Succeeded"
+          "name": "gpt-5",
+          "version": ""
+        }
       }
     }
   ]
@@ -173,16 +167,13 @@ We support exactly **2 deployment API formats** for model discovery through APIM
 *Get Deployment by Name Response (`getModelEndpoint`):`*
 ```json
 {
-  "id": "/subscriptions/.../deployments/gpt-4-deployment",
-  "name": "gpt-4-deployment",
-  "type": "Microsoft.CognitiveServices/accounts/deployments",
+  "name": "gpt-4o-deployment",
   "properties": {
     "model": {
       "format": "OpenAI",
-      "name": "gpt-4",
-      "version": "0613"
-    },
-    "provisioningState": "Succeeded"
+      "name": "gpt-4o",
+      "version": "2024-11-20"
+    }
   }
 }
 ```
@@ -191,7 +182,6 @@ We support exactly **2 deployment API formats** for model discovery through APIM
 - Follows Azure ARM resource structure
 - Separate deployment `name` and model details in `properties.model`
 - Includes model `name`, `version`, and `format`
-- Provides deployment provisioning state
 
 **2. OpenAI Format Responses (`deploymentProvider: "OpenAI"`):**
 
@@ -200,13 +190,13 @@ We support exactly **2 deployment API formats** for model discovery through APIM
 {
   "data": [
     {
-      "id": "gpt-4",
+      "id": "gpt-4o",
       "object": "model",
       "created": 1687882411,
       "owned_by": "openai"
     },
     {
-      "id": "gpt-3.5-turbo",
+      "id": "gpt-5",
       "object": "model", 
       "created": 1677610602,
       "owned_by": "openai"
@@ -218,7 +208,7 @@ We support exactly **2 deployment API formats** for model discovery through APIM
 *Get Model by Name Response (`getModelEndpoint`):`*
 ```json
 {
-  "id": "gpt-4",
+  "id": "gpt-4o",
   "object": "model",
   "created": 1687882411,
   "owned_by": "openai"
@@ -237,12 +227,22 @@ Static discovery uses a predefined `models` array in metadata. Models are define
 {
   "models": [
     {
-      "name": "deployment-name",
+      "name": "gpt-4o-deployment",
+      "properties": {
+        "model": {
+          "name": "gpt-4o",
+          "version": "2024-11-20",
+          "format": "OpenAI"
+        }
+      }
+    },
+    {
+      "name": "gpt-5-deployment",
       "properties": {
         "model": {
-          "name": "model-name",
-          "version": "model-version",
-          "format": "provider-format"
+          "name": "gpt-5",
+          "version": "",
+          "format": "OpenAI"
         }
       }
     }
@@ -420,21 +420,21 @@ Predefined static list of models without dynamic discovery.
     "metadata": {
       "models": [
         {
-          "name": "gpt-4-deployment",
+          "name": "gpt-4o-deployment",
           "properties": {
             "model": {
-              "name": "gpt-4",
-              "version": "0613",
+              "name": "gpt-4o",
+              "version": "2024-11-20",
               "format": "OpenAI"
             }
           }
         },
         {
-          "name": "gpt-35-turbo-deployment",
+          "name": "gpt-5-deployment",
           "properties": {
             "model": {
-              "name": "gpt-35-turbo",
-              "version": "0613",
+              "name": "gpt-5",
+              "version": "",
               "format": "OpenAI"
             }
           }

samples/microsoft/infrastructure-setup/01-connections/apim/apim-setup-guide-for-agents.md

@@ -232,4 +232,11 @@ Determine if your chat completions URL includes the deployment name in the path:
 - `"true"`: `/deployments/gpt-4/chat/completions`
 - `"false"`: `/chat/completions?deployment=gpt-4`
 
-> **📝 Note**: These values will be used when creating your APIM connection in Foundry using the Bicep templates.
+> **📝 Note**: These values will be used when creating your APIM connection in Foundry using the Bicep templates.
+
+---
+
+## 📚 Additional Resources
+
+- **🔗 [APIM Connection Objects Documentation](APIM-Connection-Objects.md)** - Read up on more configurations available for APIM connections
+- **📖 [APIM README](README.md)** - Next steps for deploying your APIM connections