1  ---
  2  title: "Migration to Platform Service (Enterprise v1.27.0+)"
  3  sidebar_position: 20
  4  ---
  5  
  6  ### ✅ This Guide Applies To:
  7  
  8  - **Users running SAM manually with YAML files** - Typically after generating your SAM application with `sam init`, you run SAM directly using configuration files (e.g., `sam run configs/gateways/webui.yaml`)
  9  - **Users using Enterprise features and have an existing `platform.db`** - You are using features like Agent Builder, Connectors, or other enterprise capabilities that have created a `platform.db` file
 10  
 11  ### ❌ This Guide Does NOT Apply To:
 12  
 13  - **Users using Docker images** - If you're using Solace's pre-packaged Docker images via the Docker quickstart or Kubernetes deployments with Helm charts, this migration is handled automatically
 14  - **Users with no existing `platform.db`** - If you don't have an existing `platform.db` file or have not been using enterprise features
 15  - **SAM Community Edition users** - This migration only applies to SAM Enterprise
 16  
 17  ## Overview
 18  
 19  Previously, backend enterprise functionality was served from the WebUI Gateway. With version 1.27.0+, the architecture splits the WebUI Gateway into two separate services:
 20  
 21  - **WebUI Gateway** (port 8000): Handles chat sessions, task submissions, and real-time streaming
 22  - **Platform Service** (port 8001): Handles Agent Builder, Connector management, and deployment orchestration
 23  
 24  ## What's Changing
 25  
 26  ### Split
 27  
 28  |  | Until v1.24.x      | After v1.27.0                  |
 29  |--------|--------------------|--------------------------------|
 30  | **Architecture** | WebUI Gateway      | WebUI Gateway + Platform Service |
 31  | **Ports** | Single port (8000) | WebUI (8000) + Platform (8001) |
 32  | **Configuration** | One YAML file      | Two YAML files                 |
 33  
 34  ### Functionality Distribution
 35  
 36  **WebUI Gateway (port 8000)**:
 37  - Chat interface and sessions
 38  - Task submission and management
 39  - Server-Sent Events (SSE) streaming
 40  - Artifact management
 41  - Real-time agent interactions
 42  
 43  **Platform Service (port 8001)**:
 44  - Agent Builder (UI-based agent creation)
 45  - Connector management
 46  - Deployment orchestration
 47  - Background tasks (heartbeat monitoring, deployment tracking)
 48  
 49  :::warning
 50  If you upgrade to v1.27.0+ without completing this migration, users will lose access to the Agent Builder, Connector management, and dynamic agent deployment capabilities. Chat functionality will continue to work, but enterprise features will be unavailable.
 51  :::
 52  
 53  ## Migration Steps
 54  
 55  ### Step 1: Create Platform Service Configuration
 56  
 57  Create a new file `configs/services/platform.yaml` in your project with the contents from [templates/platform.yaml](https://raw.githubusercontent.com/SolaceLabs/solace-agent-mesh/main/templates/platform.yaml):
 58  
 59  :::important
 60  `app_config.database_url` must point to the existing `platform.db` to retain agent and deployment data.
 61  :::
 62  
 63  ### Step 2: Update WebUI Configuration
 64  
 65  Update your existing `configs/gateways/webui.yaml` to include the Platform Service URL:
 66  
 67  ```yaml
 68  apps:
 69    - name: a2a_webui_app
 70      app_module: solace_agent_mesh.gateway.http_sse.app
 71       
 72      # Omitted sections for brevity...
 73  
 74      app_config:
 75        namespace: ${NAMESPACE}
 76  
 77        # Add the following section to point to the Platform Service
 78        platform_service:
 79          url: "${PLATFORM_SERVICE_URL, http://localhost:8001}"
 80  ```
 81  
 82  Delete `platform_service.database_url` from your WebUI yaml, as it is no longer needed.
 83  
 84  ### Step 3: Run Platform Service
 85  
 86  In addition to running the WebUI Gateway, also start the Platform Service:
 87  
 88  Within the same process:
 89  ```bash
 90  sam run configs/gateways/webui.yaml configs/services/platform.yaml
 91  ```
 92  
 93  Or within its own process:
 94  ```bash
 95  sam run configs/services/platform.yaml
 96  ```
 97  
 98  ## Verification
 99  
100  After completing the migration, verify both services are running correctly:
101  
102  1. **Check WebUI Gateway**:
103     ```bash
104     curl http://localhost:8000/health
105     # Should return: {"status":"A2A Web UI Backend is running"}
106     ```
107  
108  2. **Check Platform Service**:
109     ```bash
110     curl http://localhost:8001/health
111     # Should return: {"status":"healthy","service":"Platform Service"}
112     ```
113  
114  3. **Verify Frontend Configuration**:
115     ```bash
116     curl http://localhost:8000/api/v1/config
117     # Should include frontend_platform_server_url set to the Platform Service URL"
118     ```
119  
120  4. **Test Agent Builder** - Access the web UI and navigate to Agent Builder. You should be able to create and manage agents through the UI.