Solace Agent Mesh CLI

Solace Agent Mesh comes with a comprehensive CLI tool that you can use to create, and run an instance of Solace Agent Mesh, which is referred to as a Solace Agent Mesh (SAM) application. The Solace Agent Mesh (SAM) CLI also allows you to add agents and gateways, manage plugins, help you debug, and much more.

Installation

The SAM CLI is installed as part of the package for Solace Agent Mesh. For more information, see Installation.

CLI Tips

• The Solace Agent Mesh CLI comes with a short alias of sam which can be used in place of solace-agent-mesh.
• You can determine the version of the SAM CLI by running solace-agent-mesh --version.
• You can get help on any command by running solace-agent-mesh [COMMAND] --help.

Commands

init - Initialize a SAM Application

sam init [OPTIONS]

When this command is run with no options, it runs in interactive mode. It first prompts you to choose between configuring your project in the terminal or through a browser-based interface.

If you choose to use the browser, the SAM CLI starts a local web configuration portal, available at http://127.0.0.1:5002

You can skip some questions by providing the appropriate options for that step during the SAM CLI-based setup.

Optionally, you can skip all the questions by providing the --skip option. This option uses the provided or default values for all the questions.

automated workflows

Use the --skip option and provide the necessary options to run the command in non-interactive mode, useful for automated workflows.

Options:

• --gui – Launch the browser-based initialization interface directly, skipping the prompt. (Recommended way to configure SAM applications)
• --skip – Runs in non-interactive mode, using default values where available.
• --llm-service-endpoint TEXT – LLM Service Endpoint URL.
• --llm-service-api-key TEXT – LLM Service API Key.
• --llm-service-planning-model-name TEXT – LLM Planning Model Name.
• --llm-service-general-model-name TEXT – LLM General Model Name.
• --namespace TEXT – Namespace for the project.
• --broker-type TEXT – Broker type: 1/solace (existing), 2/container (new local), 3/dev (dev mode). Options: 1, 2, 3, solace, container, dev_mode, dev_broker, dev.
• --broker-url TEXT – Solace broker URL endpoint.
• --broker-vpn TEXT – Solace broker VPN name.
• --broker-username TEXT – Solace broker username.
• --broker-password TEXT – Solace broker password.
• --container-engine TEXT – Container engine for local broker. Options: podman, docker.
• --dev-mode – Shortcut to select dev mode for broker (equivalent to --broker-type 3/dev).
• --agent-name TEXT – Agent name for the main orchestrator.
• --supports-streaming – Enable streaming support for the agent.
• --session-service-type TEXT – Session service type. Options: memory, vertex_rag.
• --session-service-behavior TEXT – Session service behavior. Options: PERSISTENT, RUN_BASED.
• --artifact-service-type TEXT – Artifact service type. Options: memory, filesystem, gcs.
• --artifact-service-base-path TEXT – Artifact service base path (for filesystem type).
• --artifact-service-scope TEXT – Artifact service scope. Options: namespace, app, custom.
• --artifact-handling-mode TEXT – Artifact handling mode. Options: ignore, embed, reference.
• --enable-embed-resolution – Enable embed resolution.
• --enable-artifact-content-instruction – Enable artifact content instruction.
• --enable-builtin-artifact-tools – Enable built-in artifact tools.
• --enable-builtin-data-tools – Enable built-in data tools.
• --agent-card-description TEXT – Agent card description.
• --agent-card-default-input-modes TEXT – Agent card default input modes (comma-separated).
• --agent-card-default-output-modes TEXT – Agent card default output modes (comma-separated).
• --agent-discovery-enabled – Enable agent discovery.
• --agent-card-publishing-interval INTEGER – Agent card publishing interval (seconds).
• --inter-agent-communication-allow-list TEXT – Inter-agent communication allow list (comma-separated, use * for all).
• --inter-agent-communication-deny-list TEXT – Inter-agent communication deny list (comma-separated).
• --inter-agent-communication-timeout INTEGER – Inter-agent communication timeout (seconds).
• --add-webui-gateway – Add a default Web UI gateway configuration.
• --webui-session-secret-key TEXT – Session secret key for Web UI.
• --webui-fastapi-host TEXT – Host for Web UI FastAPI server.
• --webui-fastapi-port INTEGER – Port for Web UI FastAPI server.
• --webui-enable-embed-resolution – Enable embed resolution for Web UI.
• --webui-frontend-welcome-message TEXT – Frontend welcome message for Web UI.
• --webui-frontend-bot-name TEXT – Frontend bot name for Web UI.
• --webui-frontend-collect-feedback – Enable feedback collection in Web UI.
• -h, --help – Displays the help message and exits.

add - Create a New Component

To add a new component, such as an agent or gateway, use the add command with the appropriate options.

sam add [agent|gateway] [OPTIONS] NAME

Add agent

Use agent to add an agent component.

sam add agent [OPTIONS] [NAME]

Options:

• --gui – Launch the browser-based configuration interface for agent setup. (Recommended way to configure agents)
• --skip – Skip interactive prompts and use defaults (SAM CLI mode only).
• --namespace TEXT – A2A namespace (for example, myorg/dev).
• --supports-streaming BOOLEAN – Enable streaming support.
• --model-type TEXT – Model type for the agent. Options: planning, general, image_gen, report_gen, multimodal, gemini_pro.
• --instruction TEXT – Custom instruction for the agent.
• --session-service-type TEXT – Session service type. Options: memory, vertex_rag.
• --session-service-behavior TEXT – Session service behavior. Options: PERSISTENT, RUN_BASED.
• --artifact-service-type TEXT – Artifact service type. Options: memory, filesystem, gcs.
• --artifact-service-base-path TEXT – Base path for filesystem artifact service.
• --artifact-service-scope TEXT – Artifact service scope. Options: namespace, app, custom.
• --artifact-handling-mode TEXT – 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.
• --agent-card-description TEXT – Description for the agent card.
• --agent-card-default-input-modes-str TEXT – Comma-separated default input modes for agent card.
• --agent-card-default-output-modes-str TEXT – Comma-separated default output modes for agent card.
• --agent-card-publishing-interval INTEGER – Agent card publishing interval in seconds.
• --agent-discovery-enabled BOOLEAN – Enable agent discovery.
• --inter-agent-communication-allow-list-str TEXT – Comma-separated allow list for inter-agent communication.
• --inter-agent-communication-deny-list-str TEXT – Comma-separated deny list for inter-agent communication.
• --inter-agent-communication-timeout INTEGER – Timeout in seconds for inter-agent communication.
• -h, --help – Displays the help message and exits.

For more information, see Agents.

Add gateway

Use gateway to add a gateway component.

sam add gateway [OPTIONS] [NAME]

Options:

• --gui – Launch the browser-based configuration interface for gateway setup. (Recommended way to configure gateways)
• --skip – Skip interactive prompts and use defaults (SAM CLI mode only).
• --namespace TEXT – A2A namespace for the gateway (for example, myorg/dev).
• --gateway-id TEXT – Custom Gateway ID for the gateway.
• --artifact-service-type TEXT – Artifact service type for the gateway. Options: memory, filesystem, gcs.
• --artifact-service-base-path TEXT – Base path for filesystem artifact service (if type is 'filesystem').
• --artifact-service-scope TEXT – Artifact service scope (if not using default shared artifact service). Options: namespace, app, custom.
• --system-purpose TEXT – System purpose for the gateway (can be multi-line).
• --response-format TEXT – Response format for the gateway (can be multi-line).
• -h, --help – Displays the help message and exits.

For more information, see Gateways.

run - Run the SAM Application

To run the SAM application, use the run command.

sam run [OPTIONS] [FILES]...

Environment variables

The sam run command automatically loads environment variables from your configuration file (typically a .env file at the project root) by default.

If you want to use your system's environment variables instead, you can add the -u or --system-env option.

While running the run command, you can also skip specific files by providing the -s or --skip option.

You can provide paths to specific YAML configuration files or directories. When you provide a directory, run will recursively search for and load all .yaml and .yml files within that directory. This allows you to organize your configurations and run them together easily.

For example, to run specific files:

solace-agent-mesh run configs/agent1.yaml configs/gateway.yaml

To run all YAML files within the configs directory:

solace-agent-mesh run configs/

Options:

• -u, --system-env – Use system environment variables only; do not load .env file.
• -s, --skip TEXT – File name(s) to exclude from the run (for example, -s my_agent.yaml).
• -h, --help – Displays the help message and exits.

docs - Serve the documentation locally

Serves the project documentation on a local web server.

sam docs [OPTIONS]

This command starts a web server to host the documentation, which is useful for offline viewing or development. By default, it serves the documentation at http://localhost:8585/solace-agent-mesh/ and automatically opens your web browser to the getting started page.

If a requested page is not found, it will redirect to the main documentation page.

Options:

• -p, --port INTEGER – Port to run the web server on. (default: 8585)
• -h, --help – Displays the help message and exits.

plugin - Manage Plugins

The plugin command allows you to manage plugins for SAM application.

sam plugin [COMMAND] [OPTIONS]

For more information, see Plugins.

create - Create a Plugin

Initializes and creates a new plugin with customizable options.

sam plugin create [OPTIONS] NAME

When this command is run with no options, it runs in interactive mode and prompts you to provide the necessary information to set up the plugin for Solace Agent Mesh

You can skip some questions by providing the appropriate options for that step.

Optionally, you can skip all the questions by providing the --skip option. This option uses the provided or default values for all the questions, which is useful for automated workflows.

Options:

• --type TEXT – Plugin type. Options: agent, gateway, custom.
• --author-name TEXT – Author's name.
• --author-email TEXT – Author's email.
• --description TEXT – Plugin description.
• --version TEXT – Initial plugin version.
• --skip – Skip interactive prompts and use defaults or provided flags.
• -h, --help – Displays the help message and exits.

build - Build the Plugin

Compiles and prepares the plugin for use.

sam plugin build [PLUGIN_PATH]

Builds the SAM plugin in the specified directory (defaults to current directory).

Options:

• PLUGIN_PATH – Path to the plugin directory (defaults to current directory).
• -h, --help – Displays the help message and exits.

add - Add an Existing Plugin

Creates a new component instance from a specified plugin source.

sam plugin add [OPTIONS] COMPONENT_NAME

Options:

• --plugin TEXT – Plugin source: installed module name, local path, or Git URL. (Required)
• --install-command TEXT – Command to use to install a python package. Must follow the format command {package} args, by default pip3 install {package}. Can also be set through the environment variable SAM_PLUGIN_INSTALL_COMMAND.
• -h, --help – Displays the help message and exits.

catalog - Launch Plugin Catalog

Launch the SAM Plugin Catalog web interface.

sam plugin catalog [OPTIONS]

Options:

• --port INTEGER – Port to run the plugin catalog web server on. (default: 5003)
• --install-command TEXT – Command to use to install a python package. Must follow the format command {package} args.
• -h, --help – Displays the help message and exits.