Skip to main content

​
Quickstart Guide

Get Solace Agent Mesh up and running in approximately 5 minutes. This guide will walk you through installation, project initialization, and running your first agent mesh.
This quickstart uses a local development setup with in-memory queues. For production deployments, see the deployment documentation.

​
Prerequisites

Before you begin, ensure you have:
1

Python 3.10.16+

Check your Python version:
python3 --version
If you need to install or upgrade Python, visit python.org
2

pip package manager

pip comes with Python. Verify it’s installed:
pip3 --version
3

LLM API Key

Obtain an API key from any major provider:
  • OpenAI (GPT-4, GPT-4o)
  • Anthropic (Claude Sonnet, Claude Opus)
  • Google (Gemini Pro, Gemini Flash)
  • Or any OpenAI-compatible endpoint (Ollama, LiteLLM, etc.)

​
Installation Steps

​
Step 1: Create a Project Directory

Create a new directory for your Agent Mesh project: 
mkdir my-sam && cd my-sam

​
Step 2: Set Up Python Virtual Environment

Create and activate a Python virtual environment: 
python3 -m venv .venv && source .venv/bin/activate
Using a virtual environment isolates your project dependencies and prevents conflicts with other Python projects.

​
Step 3: Install Solace Agent Mesh

Check if you have a previous version installed: 
sam -v
If you have an earlier version, uninstall it first: 
pip3 uninstall solace-agent-mesh
Upgrading versions with pip3 install --upgrade solace-agent-mesh is not officially supported. Always uninstall and start from scratch when upgrading.
Install the latest version: 
pip3 install solace-agent-mesh
Verify the installation: 
sam -v
# or
solace-agent-mesh -v

​
Initialize Your Project

​
Step 4: Launch the GUI Initialization Tool

Solace Agent Mesh provides a web-based GUI for easy project setup: 
sam init --gui
The initialization UI runs on port 5002 by default. Navigate to http://localhost:5002 in your browser if it doesn’t open automatically.
The GUI will guide you through:
Choose your event broker configuration:
  • New local Solace broker container: Automatically downloads and runs a Solace container
  • Existing Solace broker: Connect to an existing broker
  • Development mode: Use in-memory queues (for quick testing only)
For this quickstart, select “Development mode” for the fastest setup.

​
Alternative: Command-Line Initialization

For automated setups or scripting, use the CLI directly: 
sam init --skip \
  --llm-service-endpoint "https://api.anthropic.com/v1" \
  --llm-service-api-key "YOUR_API_KEY" \
  --llm-service-planning-model-name "anthropic/claude-3-5-sonnet-20241022" \
  --llm-service-general-model-name "anthropic/claude-3-5-sonnet-20241022" \
  --namespace "solace_app/" \
  --broker-type "dev" \
  --add-webui-gateway
Run sam init --help to see all available configuration options.

​
What Gets Created

The initialization process creates: 
my-sam/
├── .env                          # Environment variables
├── .solace/                      # Agent Mesh configuration
│   ├── agents/
│   │   └── orchestrator.yaml     # Main orchestrator agent
│   └── gateways/
│       └── webui_gateway.yaml    # Web UI gateway
└── shared_config.yaml            # Shared configuration

​
Run Your Agent Mesh

​
Step 5: Start the Agent Mesh

Run all components (agents and gateways) in a single process: 
sam run
You should see output similar to: 
2026-03-04 - solace_agent_mesh.cli.commands.run_cmd - INFO - Loaded environment variables from: /path/to/my-sam/.env
2026-03-04 - solace_agent_mesh.cli.commands.run_cmd - INFO - Final list of configuration files to run:
  - /path/to/my-sam/.solace/agents/orchestrator.yaml
  - /path/to/my-sam/.solace/gateways/webui_gateway.yaml
2026-03-04 - INFO - Starting Solace AI Connector...
2026-03-04 - INFO - Agent Host initialized: OrchestratorAgent
2026-03-04 - INFO - Web UI Gateway started on http://localhost:8000
Use sam run --help to see additional options, including:
  • --skip or -s: Skip specific configuration files
  • --system-env or -u: Use system environment variables only

​
Advanced: Running Specific Components

You can run specific configuration files: 
# Run only the orchestrator agent
sam run .solace/agents/orchestrator.yaml

# Run orchestrator and web UI
sam run .solace/agents/orchestrator.yaml .solace/gateways/webui_gateway.yaml

# Run all configs except one
sam run -s orchestrator.yaml

​
Verify and Test

​
Step 6: Access the Web Interface

Once the agent mesh is running, open your browser to: 
http://localhost:8000
If you configured a different port during initialization, use that port instead.

​
Step 7: Test Your Agent Mesh

Try these example prompts in the web interface:

Simple Query

“Hello! What can you help me with?”Tests basic agent response and LLM connectivity.

Time Query

“What is the current time?”Tests built-in tool execution (get_current_time).

Artifact Creation

“Create a simple to-do list for planning a vacation”Tests artifact management tools.

Data Analysis

“Create a sample sales dataset and visualize it”Tests data analysis and visualization tools.

​
Understanding Your Setup

Your Agent Mesh consists of:

​
Components Running

The main orchestrator agent that:
  • Processes tasks from gateways
  • Coordinates with other agents (when you add them)
  • Has access to built-in tools:
    • Artifact management (create, list, load files)
    • Data analysis (SQL, JQ, visualizations)
    • Time utilities
    • Peer agent delegation (when other agents are available)

​
Communication Flow

​
Next Steps

Now that you have a working Agent Mesh, explore these topics:

Add Custom Agents

Create specialized agents for specific tasks:
sam add agent --gui
Learn more in the Architecture guide.

Install Plugins

Extend functionality with pre-built plugins:
sam plugin add weather-agent --plugin weather
Browse available plugins in the repository.

Add More Gateways

Connect additional interfaces (Slack, REST API, etc.):
sam add gateway --gui

Learn the Architecture

Understand how Agent Mesh works under the hood and the event-driven architecture.

​
Common CLI Commands

Here are the most useful commands for working with Agent Mesh: 
# Initialize a new project
sam init --gui

# Run the agent mesh
sam run

# Check version
sam -v

​
Troubleshooting

If port 8000 is already in use, you can:
  1. Stop the service using that port
  2. Or modify the FASTAPI_PORT in your .env file to use a different port
# In .env
FASTAPI_PORT=8001
Verify your API key is correct in the .env file:
cat .env | grep LLM_SERVICE_API_KEY
Ensure the endpoint URL matches your provider:
  • OpenAI: https://api.openai.com/v1
  • Anthropic: https://api.anthropic.com/v1
  • Google: https://generativelanguage.googleapis.com/v1beta
Ensure you’re in the correct virtual environment:
which python3
# Should show: /path/to/my-sam/.venv/bin/python3
If not, reactivate the virtual environment:
source .venv/bin/activate
Check the logs for errors. Common issues:
  • Invalid model name format (should be provider/model-name)
  • Network connectivity to LLM provider
  • Insufficient API credits or rate limiting
Enable debug logging by setting in your config:
log:
  stdout_log_level: DEBUG
  log_file_level: DEBUG

​
Additional Resources

GitHub Repository

View source code, examples, and contribute

PyPI Package

Package information and release history

Solace Platform

Learn about the Solace Event Broker

Build docs developers (and LLMs) love

Get started for freeTalk to us