sam init

Overview

The sam init command creates a new Solace Agent Mesh project with all necessary configuration files, directory structure, and default settings.

Syntax

sam init [OPTIONS]

Description

Initializes a new Solace application project by creating:

Project directory structure
Configuration files (YAML)
Environment file (.env)
Main orchestrator configuration
Web UI gateway configuration (optional)
Platform service configuration

The command supports both interactive mode (with prompts) and non-interactive mode (using CLI flags or defaults).

Options

Initialization Mode

--skip

boolean

default:"false"

Non-interactive mode. Skip all prompts and use default values where applicable.

--gui

boolean

default:"false"

Launch the browser-based initialization interface for interactive configuration.

--dev-mode

boolean

default:"false"

Shortcut to select dev mode for broker (equivalent to --broker-type dev).

LLM Service Configuration

--llm-service-endpoint

string

LLM Service Endpoint URL.

--llm-service-api-key

string

LLM Service API Key.

--llm-service-planning-model-name

string

LLM Planning Model Name.

--llm-service-general-model-name

string

LLM General Model Name.

Project Configuration

--namespace

string

Namespace for the project (e.g., myorg/dev).

Broker Configuration

--broker-type

choice

Broker type. Options:

1, solace: Use existing Solace broker
2, container: Create new local broker in container
3, dev, dev_mode, dev_broker: Use dev mode (bypasses broker)

--broker-url

string

Solace broker URL endpoint (e.g., ws://localhost:8008).

--broker-vpn

string

Solace broker VPN name.

--broker-username

string

Solace broker username.

--broker-password

string

Solace broker password.

--container-engine

choice

Container engine for local broker. Options: docker, podman

Agent Configuration

--agent-name

string

Agent name for the main orchestrator.

--supports-streaming

boolean

Enable streaming support for the agent.

--agent-card-description

string

Agent card description.

--agent-card-default-input-modes

string

Agent card default input modes (comma-separated).

--agent-card-default-output-modes

string

Agent card default output modes (comma-separated).

--agent-discovery-enabled

boolean

Enable agent discovery.

--agent-card-publishing-interval

integer

Agent card publishing interval (seconds).

Session Service

--session-service-type

choice

Session service type. Options: memory, vertex_rag, sql

--session-service-behavior

choice

Session service behavior. Options: PERSISTENT, RUN_BASED

--orchestrator-database-url

string

Database URL for the Orchestrator.

Artifact Service

--artifact-service-type

choice

Artifact service type. Options: memory, filesystem, gcs, s3

--artifact-service-base-path

string

Artifact service base path (for filesystem type).

--artifact-service-bucket-name

string

S3 bucket name (for s3 artifact service type).

--artifact-service-endpoint-url

string

S3 endpoint URL (for s3 artifact service type, optional for AWS S3).

--artifact-service-region

string

S3 region (for s3 artifact service type).

--artifact-service-scope

choice

Artifact service scope. Options: namespace, app, custom

--artifact-handling-mode

choice

Artifact handling mode. Options: ignore, embed, reference

--enable-embed-resolution

boolean

Enable embed resolution.

--enable-artifact-content-instruction

boolean

Enable artifact content instruction.

--enable-builtin-artifact-tools

boolean

Enable built-in artifact tools.

--enable-builtin-data-tools

boolean

Enable built-in data tools.

Inter-Agent Communication

--inter-agent-communication-allow-list

string

Inter-agent communication allow list (comma-separated, use * for all).

--inter-agent-communication-deny-list

string

Inter-agent communication deny list (comma-separated).

--inter-agent-communication-timeout

integer

Inter-agent communication timeout (seconds).

Web UI Gateway

--add-webui-gateway

boolean

Add a default Web UI gateway configuration.

--webui-session-secret-key

string

Session secret key for Web UI.

--webui-fastapi-host

string

Host for Web UI FastAPI server.

--webui-fastapi-port

integer

Port for Web UI FastAPI server.

--webui-fastapi-https-port

integer

HTTPS port for Web UI FastAPI server.

--webui-ssl-keyfile

string

SSL key file path for Web UI.

--webui-ssl-certfile

string

SSL certificate file path for Web UI.

--webui-ssl-keyfile-password

string

SSL key file passphrase for Web UI.

--webui-enable-embed-resolution

boolean

Enable embed resolution for Web UI.

--webui-frontend-welcome-message

string

Frontend welcome message for Web UI.

--webui-frontend-bot-name

string

Frontend bot name for Web UI.

--webui-frontend-collect-feedback

boolean

Enable feedback collection in Web UI.

--web-ui-gateway-database-url

string

Database URL for the WebUI Gateway.

Platform Service

--platform-api-host

string

Host for Platform API server.

--platform-api-port

integer

Port for Platform API server.

Examples

Interactive Initialization

sam init

Runs the initialization wizard with prompts for all configuration options.

GUI-Based Initialization

sam init --gui

Launches a web browser interface for configuring your project.

Non-Interactive with Defaults

sam init --skip

Creates a project using all default values without prompting.

Dev Mode Initialization

sam init --dev-mode --skip

Initializes a project in development mode (bypasses broker setup).

Custom Broker Configuration

sam init \
  --broker-type solace \
  --broker-url ws://my-broker.example.com:8008 \
  --broker-vpn my-vpn \
  --broker-username admin \
  --broker-password secret \
  --skip

Custom LLM and Namespace

sam init \
  --llm-service-endpoint https://api.openai.com/v1 \
  --llm-service-api-key sk-xxx \
  --llm-service-planning-model-name gpt-4 \
  --llm-service-general-model-name gpt-3.5-turbo \
  --namespace mycompany/production \
  --skip

Output

Upon successful initialization, the command creates:

project-directory/
├── configs/
│   ├── agents/
│   │   └── orchestrator_agent.yaml
│   └── gateways/
│       └── webui_gateway_config.yaml
├── data/
├── src/
├── .env
└── docker-compose.yml (if using container broker)

Terminal Output:

Initializing Solace Application Project...
Project will be initialized in: /path/to/project

--- Step 1 of 7: Broker Setup ---
[Broker configuration output]

--- Step 2 of 7: Project Directory Setup ---
[Directory creation output]

...

Project initialization complete!
Review the generated files, especially .env and configuration YAMLs.
Next steps: Consider running 'solace-agent-mesh run' or 'sam run'.

Notes

The initialization process creates configuration files in the current directory
If --gui is used with --skip, the CLI will proceed with non-interactive mode
Dev mode (--dev-mode) bypasses the broker setup for local development
Review and update the generated .env file with your actual credentials and endpoints
All configuration files use YAML format with environment variable substitution

CLI Commands

Agent API

Gateway API

Workflow API

A2A Protocol

Overview

Syntax

Description

Options

Initialization Mode

LLM Service Configuration

Project Configuration

Broker Configuration

Agent Configuration

Session Service

Artifact Service

Inter-Agent Communication

Web UI Gateway

Platform Service

Examples

Interactive Initialization

GUI-Based Initialization

Non-Interactive with Defaults

Dev Mode Initialization

Custom Broker Configuration

Custom LLM and Namespace

Output

Notes

See Also

Build docs developers (and LLMs) love

CLI Commands

Agent API

Gateway API

Workflow API

A2A Protocol

​Overview

​Syntax

​Description

​Options

​Initialization Mode

​LLM Service Configuration

​Project Configuration

​Broker Configuration

​Agent Configuration

​Session Service

​Artifact Service

​Inter-Agent Communication

​Web UI Gateway

​Platform Service

​Examples

​Interactive Initialization

​GUI-Based Initialization

​Non-Interactive with Defaults

​Dev Mode Initialization

​Custom Broker Configuration

​Custom LLM and Namespace

​Output

​Notes

​See Also

Build docs developers (and LLMs) love

Overview

Syntax

Description

Options

Initialization Mode

LLM Service Configuration

Project Configuration

Broker Configuration

Agent Configuration

Session Service

Artifact Service

Inter-Agent Communication

Web UI Gateway

Platform Service

Examples

Interactive Initialization

GUI-Based Initialization

Non-Interactive with Defaults

Dev Mode Initialization

Custom Broker Configuration

Custom LLM and Namespace

Output

Notes

See Also