Skip to main content

# Prerequisites

Before you begin, ensure you have the following:

- Python 3.10.16+
- pip (usually included with Python) or uv (install uv)
- Operating System: macOS, Linux, or Windows (via WSL)
- LLM API key from any major provider or your own custom endpoint

# Installation

The Solace Agent Mesh Module includes two components:

1. Agent Mesh CLI: Create, build, run, and extend Agent Mesh
2. Agent Mesh framework: A Python-based framework for customizing and extending SAM's capabilities

Installing the PyPI package provides both the Agent Mesh CLI and the framework (which is built on the Python SDK).

First, create a project directory and navigate into it:

    mkdir my-sam && cd my-sam

tip

We recommend installing the package in a virtual environment to avoid conflicts with other Python packages.

Creating a Virtual Environment
Using pip

1. Create a virtual environment:

    python3 -m venv .venv

2. Activate the environment:

   On Linux or Unix platforms:

       source .venv/bin/activate

   On Windows:

       .venv\Scripts\activate

Using uv

1. Create a virtual environment:

    uv venv .venv

2. Activate the environment:

   On Linux or Unix platforms:

       source .venv/bin/activate

   On Windows:

       .venv\Scripts\activate

3. Set the following environment variables:

   On Linux or Unix platforms:

       export SAM_PLUGIN_INSTALL_COMMAND="uv pip install {package}"

   On Windows:

       set SAM_PLUGIN_INSTALL_COMMAND="uv pip install {package}"

## Install Agent Mesh​

The following command installs Agent Mesh CLI in your environment:

Using pip

    pip install solace-agent-mesh

Using uv

    uv pip install solace-agent-mesh

Docker Alternative

Alternatively, you can use our pre-built Docker image to run Agent Mesh CLI commands without a local Python installation. This approach is useful for quick tasks or CI/CD environments. The pre-built Docker image is configured with group `solaceai` and non-root user `solaceai`.

To verify the installation using Docker, run:

    docker run --rm solace/solace-agent-mesh:latest --version

This command pulls the latest image (if not already present) and executes `solace-agent-mesh --version` inside the container. The `--rm` flag ensures the container is removed after execution.

If your host OS architecture is not `linux/amd64`, you need to add `--platform linux/amd64` when running the container.

For more complex operations like building a project, you need to mount your project directory into the container. See the Quick Start guide for examples.

Browser Requirement

The `Mermaid` agent requires a browser with headless mode support to render diagrams. Use `playwright` to install the browser dependencies. If you are using the Docker image, this is already included.

To install the browser dependencies, run:

    playwright install

## Verify Installation​

Run the following Agent Mesh CLI command to verify your installation:

    solace-agent-mesh --version

tip

For easier access to the Agent Mesh CLI, you can also use the `sam` alias:

    sam --version

To get a list of available commands, run:

    solace-agent-mesh --help

## Next Steps​

After successful installation, choose your next step based on your goals:

For Quick Exploration: If you want to try SAM's capabilities immediately without project setup, use the Docker quick start to explore SAM with minimal configuration.

For Development Work: If you're ready to build a complete project with full control over configuration, proceed directly to the project setup guide.

To Learn More: Explore the system components by reading about agents and gateways.