Gateway Configuration

Overview

Gateways connect external systems (REST APIs, WebSockets, Slack, etc.) to the Solace Agent Mesh. Each gateway type has specific configuration requirements.

Gateway Types

Solace Agent Mesh supports multiple gateway types:

REST Gateway: HTTP/HTTPS REST API with SSE streaming
WebUI Gateway: Web-based user interface with real-time updates
Slack Gateway: Slack bot integration
Generic Gateway: Custom protocol adapters

Base Gateway Configuration

All gateways share common base configuration:

Top-Level Configuration

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

apps:
  - name: my_gateway_app
    app_base_path: .
    app_module: sam_rest_gateway.app  # Gateway-specific module
    broker:
      <<: *broker_connection
    
    app_config:
      # Gateway configuration below

Core Gateway Properties

namespace

string

required

The A2A topic namespace. Must match agent namespace.

namespace: ${NAMESPACE}

gateway_id

string

Unique identifier for this gateway instance. Auto-generated if omitted.

gateway_id: ${REST_GATEWAY_ID}

Artifact Service

artifact_service

object

required

Storage backend for file uploads and downloads.

artifact_service:
  type: "filesystem"
  base_path: "/tmp/samv2"
  artifact_scope: "namespace"

Scope Options:

namespace: Shared across all components in namespace
session: Isolated per user session
gateway: Isolated to this gateway

REST Gateway Configuration

REST Gateway provides HTTP/HTTPS API access with Server-Sent Events (SSE) for streaming.

REST-Specific Configuration

rest_api_server_host

string

default:"0.0.0.0"

Host address for the REST API server.

rest_api_server_host: ${REST_API_HOST, 0.0.0.0}

rest_api_server_port

integer

default:"8080"

Port for HTTP REST API.

rest_api_server_port: ${REST_API_PORT, 8080}

rest_api_https_port

integer

default:"1943"

Port for HTTPS REST API (when SSL is enabled).

rest_api_https_port: ${REST_API_HTTPS_PORT, 1943}

SSL/TLS Configuration

ssl_keyfile

string

Path to SSL private key file.

ssl_keyfile: ${SSL_KEYFILE}

ssl_certfile

string

Path to SSL certificate file.

ssl_certfile: ${SSL_CERTFILE}

ssl_keyfile_password

string

Password for encrypted SSL private key.

ssl_keyfile_password: ${SSL_KEYFILE_PASSWORD}

Authentication

enforce_authentication

boolean

default:"false"

Enable/disable authentication checks.

enforce_authentication: false

external_auth_service_url

string

URL of external OAuth2/OIDC authentication service.

external_auth_service_url: ${EXTERNAL_AUTH_SERVICE_URL, http://localhost:8080}

default_user_identity

string

default:"sam_dev_user"

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

default_user_identity: "sam_dev_user"

Legacy API Support

sync_mode_timeout_seconds

integer

default:"300"

Timeout for synchronous (v1) API requests.

sync_mode_timeout_seconds: 300

Complete REST Gateway Example

rest-gateway.yaml

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

!include ../shared_config.yaml

apps:
  - name: rest_gateway_app
    app_base_path: .
    app_module: sam_rest_gateway.app
    
    broker:
      <<: *broker_connection
    
    app_config:
      namespace: ${NAMESPACE}
      gateway_id: ${REST_GATEWAY_ID}
      
      # Artifact storage
      artifact_service:
        type: "filesystem"
        base_path: "/tmp/samv2"
        artifact_scope: "namespace"
      
      # REST API settings
      rest_api_server_host: ${REST_API_HOST, 0.0.0.0}
      rest_api_server_port: ${REST_API_PORT, 8080}
      rest_api_https_port: ${REST_API_HTTPS_PORT, 1943}
      
      # SSL configuration
      ssl_keyfile: ${SSL_KEYFILE}
      ssl_certfile: ${SSL_CERTFILE}
      ssl_keyfile_password: ${SSL_KEYFILE_PASSWORD}
      
      # Authentication
      enforce_authentication: false
      external_auth_service_url: ${EXTERNAL_AUTH_SERVICE_URL, http://localhost:8080}
      default_user_identity: "sam_dev_user"
      
      # Legacy API support
      sync_mode_timeout_seconds: 300

WebUI Gateway Configuration

WebUI Gateway provides a web-based interface with real-time streaming updates.

WebUI-Specific Configuration

session_secret_key

string

required

Secret key for signing web user sessions.

session_secret_key: ${SESSION_SECRET_KEY}

fastapi_host

string

default:"127.0.0.1"

Host address for the FastAPI server.

fastapi_host: ${FASTAPI_HOST, 127.0.0.1}

fastapi_port

integer

default:"8000"

Port for HTTP FastAPI server.

fastapi_port: ${FASTAPI_PORT, 8000}

fastapi_https_port

integer

default:"8443"

Port for HTTPS FastAPI server (when SSL enabled).

fastapi_https_port: ${FASTAPI_HTTPS_PORT, 8443}

CORS Configuration

cors_allowed_origins

array

default:"[\"*\"]"

List of allowed origins for CORS requests.

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

SSE Configuration

sse_max_queue_size

integer

default:"200"

Maximum size of SSE connection queues.

sse_max_queue_size: 200

resolve_artifact_uris_in_gateway

boolean

default:"true"

If true, gateway resolves artifact:// URIs before sending to client.

resolve_artifact_uris_in_gateway: true

Frontend Configuration

frontend_welcome_message

string

default:"Hi! How can I help?"

Initial welcome message displayed in chat.

frontend_welcome_message: "Welcome! Ask me anything."

frontend_bot_name

string

default:"A2A Agent"

Name displayed for the bot/agent in UI.

frontend_bot_name: "Assistant"

frontend_collect_feedback

boolean

default:"false"

Enable/disable feedback buttons in UI.

frontend_collect_feedback: true

frontend_server_url

string

default:""

Public URL for frontend API requests. Empty uses relative URLs.

frontend_server_url: "https://webui-gateway.example.com"

Session & Task Configuration

session_service

object

Session persistence configuration.

session_service:
  type: "database"
  database_url: ${DATABASE_URL}

visualization_queue_size

integer

default:"600"

Maximum size of visualization message queue.

visualization_queue_size: 600

task_logger_queue_size

integer

default:"600"

Maximum size of task logger queue.

task_logger_queue_size: 600

Complete WebUI Gateway Example

webui-gateway.yaml

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

!include ../shared_config.yaml

apps:
  - name: webui_gateway_app
    app_base_path: .
    app_module: solace_agent_mesh.gateway.http_sse.app
    
    broker:
      <<: *broker_connection
    
    app_config:
      namespace: ${NAMESPACE}
      gateway_id: ${WEBUI_GATEWAY_ID}
      
      # Session security
      session_secret_key: ${SESSION_SECRET_KEY}
      
      # Server configuration
      fastapi_host: ${FASTAPI_HOST, 127.0.0.1}
      fastapi_port: ${FASTAPI_PORT, 8000}
      fastapi_https_port: ${FASTAPI_HTTPS_PORT, 8443}
      
      # CORS
      cors_allowed_origins:
        - "http://localhost:3000"
        - "https://app.example.com"
      
      # SSE configuration
      sse_max_queue_size: 200
      resolve_artifact_uris_in_gateway: true
      
      # Frontend customization
      frontend_welcome_message: "Hello! How can I assist you today?"
      frontend_bot_name: "AI Assistant"
      frontend_collect_feedback: true
      frontend_server_url: "https://webui.example.com"
      
      # Authentication
      frontend_use_authorization: true
      external_auth_service_url: ${EXTERNAL_AUTH_SERVICE_URL}
      external_auth_callback_uri: ${EXTERNAL_AUTH_CALLBACK_URI}
      external_auth_provider: "azure"
      
      # SSL
      ssl_keyfile: ${SSL_KEYFILE}
      ssl_certfile: ${SSL_CERTFILE}
      ssl_keyfile_password: ${SSL_KEYFILE_PASSWORD}
      
      # Session persistence
      session_service:
        type: "database"
        database_url: ${DATABASE_URL}
      
      # Artifact storage
      artifact_service:
        type: "filesystem"
        base_path: "/tmp/samv2"
        artifact_scope: "namespace"

Generic Gateway Configuration

For custom protocol adapters:

apps:
  - name: custom_gateway_app
    app_base_path: .
    app_module: solace_agent_mesh.gateway.generic.app
    
    broker:
      <<: *broker_connection
    
    app_config:
      namespace: ${NAMESPACE}
      gateway_id: ${CUSTOM_GATEWAY_ID}
      
      # Custom adapter configuration
      adapter_module: "my_custom_adapter"
      adapter_config:
        protocol: "mqtt"
        broker_url: ${MQTT_BROKER_URL}
      
      artifact_service:
        type: "filesystem"
        base_path: "/tmp/samv2"
        artifact_scope: "namespace"

Environment Variables

Required environment variables:

NAMESPACE: A2A topic namespace
SOLACE_BROKER_URL: Solace broker URL
SOLACE_BROKER_USERNAME: Broker username
SOLACE_BROKER_PASSWORD: Broker password
SOLACE_BROKER_VPN: Broker VPN name

Gateway-specific:

REST_GATEWAY_ID: REST gateway identifier
REST_API_HOST: REST API host
REST_API_PORT: REST API port
SESSION_SECRET_KEY: WebUI session secret
DATABASE_URL: Database connection string
SSL certificate paths as needed

CLI Commands

Agent API

Gateway API

Workflow API

A2A Protocol

Overview

Gateway Types

Base Gateway Configuration

Top-Level Configuration

Core Gateway Properties

Artifact Service

REST Gateway Configuration

REST-Specific Configuration

SSL/TLS Configuration

Authentication

Legacy API Support

Complete REST Gateway Example

WebUI Gateway Configuration

WebUI-Specific Configuration

CORS Configuration

SSE Configuration

Frontend Configuration

Session & Task Configuration

Complete WebUI Gateway Example

Generic Gateway Configuration

Environment Variables

See Also

Build docs developers (and LLMs) love

CLI Commands

Agent API

Gateway API

Workflow API

A2A Protocol

​Overview

​Gateway Types

​Base Gateway Configuration

​Top-Level Configuration

​Core Gateway Properties

​Artifact Service

​REST Gateway Configuration

​REST-Specific Configuration

​SSL/TLS Configuration

​Authentication

​Legacy API Support

​Complete REST Gateway Example

​WebUI Gateway Configuration

​WebUI-Specific Configuration

​CORS Configuration

​SSE Configuration

​Frontend Configuration

​Session & Task Configuration

​Complete WebUI Gateway Example

​Generic Gateway Configuration

​Environment Variables

​See Also

Build docs developers (and LLMs) love

Overview

Gateway Types

Base Gateway Configuration

Top-Level Configuration

Core Gateway Properties

Artifact Service

REST Gateway Configuration

REST-Specific Configuration

SSL/TLS Configuration

Authentication

Legacy API Support

Complete REST Gateway Example

WebUI Gateway Configuration

WebUI-Specific Configuration

CORS Configuration

SSE Configuration

Frontend Configuration

Session & Task Configuration

Complete WebUI Gateway Example

Generic Gateway Configuration

Environment Variables

See Also