Platform Service - Solace Agent Mesh

The Platform Service is a backend microservice that provides REST APIs for configuration management, agent deployment, and system administration in Solace Agent Mesh. It operates independently from other components and can be scaled separately.

Overview

The Platform Service is built on FastAPI and provides:

RESTful API for management operations
Database persistence for configuration data
OAuth2 authentication for secure access
RBAC authorization for fine-grained permissions
Agent discovery integration via Solace Event Mesh

The Platform Service is optional for open-source deployments but required when using Agent Mesh Enterprise features.

Architecture

Configuration

The Platform Service is configured through a YAML file:

log:
  stdout_log_level: INFO
  log_file_level: DEBUG
  log_file: platform_service.log

!include ../shared_config.yaml

apps:
  - name: platform_service_app
    app_base_path: .
    app_module: solace_agent_mesh.services.platform.app
    
    broker:
      <<: *broker_connection
    
    app_config:
      # Namespace for agent discovery
      namespace: ${NAMESPACE}
      
      # Database configuration
      database_url: ${PLATFORM_DATABASE_URL}
      
      # FastAPI server settings
      fastapi_host: ${PLATFORM_HOST, 127.0.0.1}
      fastapi_port: ${PLATFORM_PORT, 8001}
      
      # Optional: HTTPS configuration
      fastapi_https_port: ${PLATFORM_HTTPS_PORT, 8444}
      ssl_keyfile: ${SSL_KEYFILE}
      ssl_certfile: ${SSL_CERTFILE}
      ssl_keyfile_password: ${SSL_KEYFILE_PASSWORD}
      
      # CORS configuration
      cors_allowed_origins:
        - "http://localhost:8000"
        - "https://app.example.com"
      cors_allowed_origin_regex: "https?://(localhost|127\\.0\\.0\\.1):\\\\d+"
      
      # Authentication (Enterprise)
      external_auth_service_url: ${EXTERNAL_AUTH_SERVICE_URL}

Configuration Parameters

Core Settings

namespace

string

required

The A2A namespace for agent discovery and communication.

database_url

string

required

Database connection string. Supports:

PostgreSQL: postgresql://user:pass@host:5432/dbname
MySQL: mysql://user:pass@host:3306/dbname
SQLite: sqlite:///platform.db

Server Settings

fastapi_host

string

default:"127.0.0.1"

Host address for the FastAPI server. Use 0.0.0.0 to accept connections from all interfaces.

fastapi_port

integer

default:"8001"

Port for HTTP connections.

fastapi_https_port

integer

default:"8444"

Port for HTTPS connections (when SSL is enabled).

SSL Configuration

ssl_keyfile

string

Path to SSL private key file (PEM format).

ssl_certfile

string

Path to SSL certificate file (PEM format).

ssl_keyfile_password

string

Password for encrypted private key (if applicable).

CORS Settings

cors_allowed_origins

array

default:"['*']"

List of allowed origins for CORS requests:

cors_allowed_origins:
  - "http://localhost:8000"
  - "https://app.example.com"

cors_allowed_origin_regex

string

Regex pattern for dynamic origin matching:

cors_allowed_origin_regex: "https?://(localhost|127\\.0\\.0\\.1):\\\\d+"

Authentication (Enterprise)

external_auth_service_url

string

URL of the OAuth2 authentication service for token validation.

enforce_authentication

boolean

default:"true"

Whether to enforce authentication. Set to false for development only.

default_user_identity

string

default:"sam_dev_user"

Default user identity when authentication is disabled (development only).

Running the Platform Service

Initialize Configuration

The sam init --gui command automatically creates a Platform Service configuration:

sam init --gui

When prompted to enable the WebUI Gateway, select Yes. This generates configs/services/platform.yaml.

Start the Service

# Run with default configuration
sam run configs/services/platform.yaml

# Run with environment variables
export PLATFORM_DATABASE_URL="postgresql://user:pass@localhost:5432/platform"
export NAMESPACE="myorg/production"
sam run configs/services/platform.yaml

The service starts on port 8001 by default.

Verify Service Health

curl http://localhost:8001/health

Expected response:

{
  "status": "healthy",
  "timestamp": "2026-03-04T12:00:00Z"
}

API Endpoints

The Platform Service exposes the following API groups:

Health Check

GET /health

Returns service health status. No authentication required.

Agent Management (Enterprise)

GET    /api/v1/agents           # List agents
POST   /api/v1/agents           # Create agent
GET    /api/v1/agents/{id}      # Get agent details
PUT    /api/v1/agents/{id}      # Update agent
DELETE /api/v1/agents/{id}      # Delete agent

Connector Management (Enterprise)

GET    /api/v1/connectors       # List database connectors
POST   /api/v1/connectors       # Create connector
GET    /api/v1/connectors/{id}  # Get connector details
PUT    /api/v1/connectors/{id}  # Update connector
DELETE /api/v1/connectors/{id}  # Delete connector

Deployment Management (Enterprise)

GET    /api/v1/deployments      # List deployments
POST   /api/v1/deployments      # Create deployment
GET    /api/v1/deployments/{id} # Get deployment status
DELETE /api/v1/deployments/{id} # Stop deployment

Enterprise endpoints require valid OAuth2 bearer tokens and appropriate RBAC permissions.

Authentication and Authorization

The Platform Service uses a shared authentication model with the WebUI Gateway:

OAuth2 Token Validation

All authenticated requests require a bearer token:

GET /api/v1/agents HTTP/1.1
Host: localhost:8001
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

Tokens are validated against the external_auth_service_url.

RBAC Configuration

Role-based access control is configured via the SAM_AUTHORIZATION_CONFIG environment variable:

export SAM_AUTHORIZATION_CONFIG=/path/to/rbac_config.yaml

Example RBAC configuration:

roles:
  - name: admin
    permissions:
      - agents:*
      - connectors:*
      - deployments:*
  
  - name: developer
    permissions:
      - agents:read
      - agents:write
      - connectors:read
  
  - name: viewer
    permissions:
      - agents:read
      - connectors:read

user_assignments:
  [email protected]:
    roles: [admin]
  [email protected]:
    roles: [developer]
  [email protected]:
    roles: [viewer]

If SAM_AUTHORIZATION_CONFIG is not set, the Platform Service defaults to denying all access. Both the Platform Service and WebUI Gateway must use the same RBAC configuration.

For detailed authentication setup, see Platform Service Authentication.

Database Setup

PostgreSQL

# Create database
createb platform_db

# Set connection string
export PLATFORM_DATABASE_URL="postgresql://user:pass@localhost:5432/platform_db"

MySQL

# Create database
mysql -u root -p -e "CREATE DATABASE platform_db;"

# Set connection string
export PLATFORM_DATABASE_URL="mysql://user:pass@localhost:3306/platform_db"

SQLite (Development)

# Use file-based database
export PLATFORM_DATABASE_URL="sqlite:///platform.db"

The Platform Service automatically creates required tables on first startup using Alembic migrations.

Agent Discovery Integration

The Platform Service subscribes to agent discovery messages on the event mesh:

{namespace}/a2a/v1/discovery/agentcards

This enables:

Real-time agent availability tracking
Capability-based agent lookup
Health monitoring for deployed agents

Example Deployment

Production Configuration

log:
  stdout_log_level: INFO
  log_file_level: INFO
  log_file: /var/log/platform_service.log

!include /etc/sam/shared_config.yaml

apps:
  - name: platform_service_app
    app_base_path: .
    app_module: solace_agent_mesh.services.platform.app
    
    broker:
      broker_url: tcps://broker.example.com:55443
      broker_username: ${SOLACE_USERNAME}
      broker_password: ${SOLACE_PASSWORD}
      broker_vpn: production
    
    app_config:
      namespace: "myorg/production"
      
      # PostgreSQL database
      database_url: "postgresql://platform:${DB_PASSWORD}@db.example.com:5432/platform"
      
      # Public-facing HTTPS
      fastapi_host: "0.0.0.0"
      fastapi_https_port: 443
      ssl_keyfile: "/etc/ssl/private/platform.key"
      ssl_certfile: "/etc/ssl/certs/platform.crt"
      
      # CORS for web applications
      cors_allowed_origins:
        - "https://app.example.com"
        - "https://admin.example.com"
      
      # OAuth2 authentication
      external_auth_service_url: "https://auth.example.com"
      enforce_authentication: true

Development Configuration

log:
  stdout_log_level: DEBUG
  log_file_level: DEBUG
  log_file: platform_dev.log

!include shared_config.yaml

apps:
  - name: platform_service_app
    app_base_path: .
    app_module: solace_agent_mesh.services.platform.app
    
    broker:
      broker_url: ws://localhost:8008
      broker_username: default
      broker_password: default
      broker_vpn: default
    
    app_config:
      namespace: "dev/local"
      
      # SQLite for development
      database_url: "sqlite:///platform_dev.db"
      
      # Local HTTP only
      fastapi_host: "127.0.0.1"
      fastapi_port: 8001
      
      # Permissive CORS for local development
      cors_allowed_origin_regex: "https?://(localhost|127\\.0\\.0\\.1):\\\\d+"
      
      # No authentication in dev
      enforce_authentication: false
      default_user_identity: "dev_user"

Docker Deployment

Example docker-compose.yml:

version: '3.8'

services:
  platform-service:
    image: solace-agent-mesh:latest
    command: sam run configs/services/platform.yaml
    ports:
      - "8001:8001"
    environment:
      - NAMESPACE=myorg/production
      - PLATFORM_DATABASE_URL=postgresql://platform:${DB_PASSWORD}@postgres:5432/platform
      - SOLACE_BROKER_URL=tcps://broker.example.com:55443
      - SOLACE_BROKER_USERNAME=${SOLACE_USERNAME}
      - SOLACE_BROKER_PASSWORD=${SOLACE_PASSWORD}
      - SOLACE_BROKER_VPN=production
      - EXTERNAL_AUTH_SERVICE_URL=https://auth.example.com
    volumes:
      - ./configs:/app/configs
      - ./ssl:/etc/ssl/private
    depends_on:
      - postgres
  
  postgres:
    image: postgres:15
    environment:
      - POSTGRES_DB=platform
      - POSTGRES_USER=platform
      - POSTGRES_PASSWORD=${DB_PASSWORD}
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  postgres_data:

Troubleshooting

Service won't start

Check:

Database is accessible and connection string is correct
Port 8001 is not already in use
Broker connection parameters are valid
All required environment variables are set

View logs:

tail -f platform_service.log

Authentication failures

Check:

external_auth_service_url is correct and reachable
OAuth2 tokens are valid and not expired
SAM_AUTHORIZATION_CONFIG environment variable is set
RBAC configuration is loaded correctly

Test authentication:

curl -H "Authorization: Bearer ${TOKEN}" http://localhost:8001/api/v1/agents

CORS errors in browser

Check:

Origin is included in cors_allowed_origins
Origin matches cors_allowed_origin_regex (if using regex)
Protocol (http/https) matches configuration

For development, use permissive regex:

cors_allowed_origin_regex: "https?://(localhost|127\\.0\\.0\\.1):\\\\d+"

Database migration errors

Check:

Database user has CREATE TABLE permissions
Database exists and is accessible
No conflicting schema versions

Manual migration:

# From the agent mesh installation directory
alembic -c src/solace_agent_mesh/services/platform/alembic.ini upgrade head

Performance Tuning

Database Connection Pooling

For PostgreSQL/MySQL, configure connection pooling:

# In database_url, add pool parameters
postgresql://user:pass@host:5432/db?pool_size=20&max_overflow=10

Worker Processes

For high-traffic deployments, run with multiple workers:

gunicorn -w 4 -k uvicorn.workers.UvicornWorker \
  --bind 0.0.0.0:8001 \
  solace_agent_mesh.services.platform.api.main:app

Caching

Enable Redis caching for agent discovery data:

app_config:
  cache_service:
    type: redis
    url: redis://localhost:6379/0
    ttl_seconds: 300

Security Best Practices

Production Deployment

Always use HTTPS with valid certificates
Enable authentication (enforce_authentication: true)
Use PostgreSQL or MySQL (not SQLite)
Restrict cors_allowed_origins to known domains
Use strong database passwords
Keep OAuth2 tokens short-lived

Network Security

Run behind a reverse proxy (nginx, Traefik)
Use firewall rules to restrict database access
Enable TLS for broker connections (tcps://)
Consider API rate limiting

RBAC Configuration

Follow principle of least privilege
Regularly audit user permissions
Use specific permissions (avoid wildcards)
Separate admin and developer roles

Next Steps

WebUI Gateway

Configure the web interface

Authentication

Set up OAuth2 and RBAC

Agent Builder

Use the visual agent builder

Deployment

Deploy to Kubernetes

Getting Started

Installation & Configuration

Core Concepts

Components

Built-in Tools

Developer Guides

Deployment

Enterprise Features

​Overview

​Architecture

​Configuration

​Configuration Parameters

​Core Settings

​Server Settings

​SSL Configuration

​CORS Settings

​Authentication (Enterprise)

​Running the Platform Service

​Initialize Configuration

​Start the Service

​Verify Service Health

​API Endpoints

​Health Check

​Agent Management (Enterprise)

​Connector Management (Enterprise)

​Deployment Management (Enterprise)

​Authentication and Authorization

​OAuth2 Token Validation

​RBAC Configuration

​Database Setup

​PostgreSQL

​MySQL

​SQLite (Development)

​Agent Discovery Integration

​Example Deployment

​Docker Deployment

​Troubleshooting

​Performance Tuning

​Database Connection Pooling

​Worker Processes

​Caching

​Security Best Practices

​Next Steps

WebUI Gateway

Authentication

Agent Builder

Deployment

Build docs developers (and LLMs) love

Overview

Architecture

Configuration

Configuration Parameters

Core Settings

Server Settings

SSL Configuration

CORS Settings

Authentication (Enterprise)

Running the Platform Service

Initialize Configuration

Start the Service

Verify Service Health

API Endpoints

Health Check

Agent Management (Enterprise)

Connector Management (Enterprise)

Deployment Management (Enterprise)

Authentication and Authorization

OAuth2 Token Validation

RBAC Configuration

Database Setup

PostgreSQL

MySQL

SQLite (Development)

Agent Discovery Integration

Example Deployment

Docker Deployment

Troubleshooting

Performance Tuning

Database Connection Pooling

Worker Processes

Caching

Security Best Practices

Next Steps