Skip to main content

# Migration to Platform Service (Enterprise v1.27.0+)

### ✅ This Guide Applies To:​

- 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`)
- 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

### ❌ This Guide Does NOT Apply To:​

- 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
- Users with no existing `platform.db` - If you don't have an existing `platform.db` file or have not been using enterprise features
- SAM Community Edition users - This migration only applies to SAM Enterprise

## Overview​

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:

- WebUI Gateway (port 8000): Handles chat sessions, task submissions, and real-time streaming
- Platform Service (port 8001): Handles Agent Builder, Connector management, and deployment orchestration

## What's Changing​

### Split​

| Until v1.24.x | After v1.27.0
--- | --- | ---
Architecture | WebUI Gateway | WebUI Gateway + Platform Service
Ports | Single port (8000) | WebUI (8000) + Platform (8001)
Configuration | One YAML file | Two YAML files

### Functionality Distribution​

WebUI Gateway (port 8000):

- Chat interface and sessions
- Task submission and management
- Server-Sent Events (SSE) streaming
- Artifact management
- Real-time agent interactions

Platform Service (port 8001):

- Agent Builder (UI-based agent creation)
- Connector management
- Deployment orchestration
- Background tasks (heartbeat monitoring, deployment tracking)

warning

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.

## Migration Steps​

### Step 1: Create Platform Service Configuration​

Create a new file `configs/services/platform.yaml` in your project with the contents from templates/platform.yaml:

important

`app_config.database_url` must point to the existing `platform.db` to retain agent and deployment data.

### Step 2: Update WebUI Configuration​

Update your existing `configs/gateways/webui.yaml` to include the Platform Service URL:

    apps:
      - name: a2a_webui_app
        app_module: solace_agent_mesh.gateway.http_sse.app

        # Omitted sections for brevity...

        app_config:
          namespace: ${NAMESPACE}

          # Add the following section to point to the Platform Service
          platform_service:
            url: "${PLATFORM_SERVICE_URL, http://localhost:8001}"

Delete `platform_service.database_url` from your WebUI yaml, as it is no longer needed.

### Step 3: Run Platform Service​

In addition to running the WebUI Gateway, also start the Platform Service:

Within the same process:

    sam run configs/gateways/webui.yaml configs/services/platform.yaml

Or within its own process:

    sam run configs/services/platform.yaml

## Verification​

After completing the migration, verify both services are running correctly:

1. Check WebUI Gateway:

       curl http://localhost:8000/health
       # Should return: {"status":"A2A Web UI Backend is running"}

2. Check Platform Service:

       curl http://localhost:8001/health
       # Should return: {"status":"healthy","service":"Platform Service"}

3. Verify Frontend Configuration:

       curl http://localhost:8000/api/v1/config
       # Should include frontend_platform_server_url set to the Platform Service URL"

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.