Skip to main content
Plugins provide a mechanism to extend Solace Agent Mesh in a modular, shareable, and reusable way. The plugin ecosystem enables you to package agents, gateways, and custom integrations as standard Python packages that can be distributed across projects and teams.

What are Plugins?

Plugins are modular Python packages that extend Agent Mesh capabilities through:
  • Agent Plugins - Specialized agents with domain-specific capabilities
  • Gateway Plugins - New interface types for external system integration
  • Custom Plugins - Specialized integrations (HR providers, monitoring tools, etc.)
Plugins integrate seamlessly with the A2A protocol and are managed through the SAM CLI.
Run sam plugin --help to see all available plugin commands.

Plugin vs Standalone Components

Here’s when to use each approach:

Standalone Component

Best for:
  • Rapid prototyping
  • Project-specific agents
  • One-off customizations
  • Quick testing
Created with:
sam add agent my-agent
sam add gateway my-gateway

Plugin

Best for:
  • Reusable components
  • Cross-project sharing
  • Production deployments
  • Team standardization
  • Open-source distribution
Created with:
sam plugin create my-plugin

Detailed Comparison

FeatureStandalone ComponentPlugin
CreationSingle command creates YAML configComplete Python project structure
StructureYAML file + optional Python toolsFull package with pyproject.toml, src/, config templates
PackagingNot packagedStandard Python wheel (.whl)
DistributionCopy files or share projectPyPI, Git, wheel files, package managers
ReusabilityWithin project onlyAcross projects, teams, organizations
InstallationNo installation neededsam plugin add or pip install
VersioningWith projectIndependent semantic versioning
DevelopmentDirect edit and runBuild/install cycle
Treat plugins as enterprise assets for any capability intended for broader use or long-term value. Standalone components are tactical tools for immediate, project-specific needs.

Official Core Plugins

Solace Agent Mesh provides official core plugins maintained by the Solace Labs team:

REST Gateway

REST API gateway for task submission and polling

Event Mesh Gateway

Connect external event meshes to the agent mesh

Slack Gateway

Slack bot integration for team collaboration

More Plugins

View all official plugins on GitHub

Creating a Plugin

Initialize Plugin

Use the SAM CLI to create a new plugin:
sam plugin create my-plugin
Follow the interactive prompts to select plugin type:
Creates a plugin that provides custom agents:
  • Pre-configured agent templates
  • Custom Python tools
  • Domain-specific capabilities

Plugin Structure

The CLI creates a standard Python project:
my-plugin/
├── src/
│   ├── __init__.py
│   ├── app.py              # Main application class (for agents/gateways)
│   ├── component.py        # Component implementation
│   └── tools/              # Custom tools (for agent plugins)
│       └── my_tool.py
├── config.yaml             # Plugin configuration template
├── pyproject.toml          # Python package metadata
├── README.md               # Documentation
└── .gitignore

Configuration Template

The config.yaml defines how the plugin is used:
# Agent Plugin Example
log:
  stdout_log_level: INFO
  log_file_level: DEBUG
  log_file: {component_name}.log

!include ../shared_config.yaml

apps:
  - name: {component_name}_app
    app_base_path: .
    app_module: my_plugin.app  # Points to your plugin module
    
    broker:
      <<: *broker_connection
    
    app_config:
      namespace: ${NAMESPACE}
      agent_name: "{component_name}"
      model: *planning_model
      
      instruction: |
        You are a specialized agent that...
      
      tools:
        - tool_type: python
          component_module: my_plugin.tools.my_tool
          function_name: my_function
          tool_name: "my_tool"
      
      # ... rest of agent configuration
Placeholders like {component_name} are replaced when users install the plugin.

Package Metadata

The pyproject.toml defines package information:
[build-system]
requires = ["setuptools>=61.0", "wheel"]
build-backend = "setuptools.build_meta"

[project]
name = "my-plugin"
version = "0.1.0"
description = "Custom agent for specialized tasks"
readme = "README.md"
requires-python = ">=3.10"
dependencies = [
    "solace-agent-mesh>=1.0.0",
    # Add plugin-specific dependencies
]

[project.optional-dependencies]
dev = [
    "pytest",
    "black",
    "ruff",
]

Building and Distributing

Build the Plugin

Create a distributable wheel package:
cd my-plugin
sam plugin build
Requires the build package: pip install build
This generates:
dist/
├── my_plugin-0.1.0-py3-none-any.whl
└── my_plugin-0.1.0.tar.gz

Distribution Methods

# Install twine
pip install twine

# Upload to PyPI
twine upload dist/*
Users install with:
sam plugin add my-component --plugin my-plugin

Using Plugins

Install and Configure

The plugin add command performs two operations:
  1. Installs the plugin package (if not already installed)
  2. Creates a component configuration from the plugin template
sam plugin add <COMPONENT_NAME> --plugin <PLUGIN_SOURCE>
Where:
  • <COMPONENT_NAME> - Name for the component instance in your project
  • <PLUGIN_SOURCE> - One of:
    • PyPI package name: my-plugin
    • Git repository: git+https://github.com/org/repo
    • Local directory: ./my-plugin
    • Wheel file: ./dist/my_plugin-0.1.0-py3-none-any.whl

Examples

sam plugin add weather-agent --plugin sam-weather-agent

Custom Package Manager

Override the installation command:
# Use uv instead of pip
export SAM_PLUGIN_INSTALL_COMMAND="uv pip install {package}"
sam plugin add my-agent --plugin my-plugin

# Or pass directly
sam plugin add my-agent --plugin my-plugin \
  --install-command "uv pip install {package}"

Plugin Catalog

Browse and manage plugins with the catalog UI:
sam plugin catalog
This launches an interactive interface showing:
  • Available plugins from configured sources
  • Installed plugins
  • Plugin descriptions and versions
  • One-click installation

Example Plugin: Weather Agent

Here’s a complete example of a weather agent plugin:
sam-weather-agent/
├── src/
│   └── sam_weather_agent/
│       ├── __init__.py
│       ├── app.py
│       └── tools/
│           └── weather_api.py
├── config.yaml
├── pyproject.toml
└── README.md
import os
import requests
from typing import Dict, Any

def get_weather(location: str) -> Dict[str, Any]:
    """
    Fetch current weather for a location.
    
    Args:
        location: City name or coordinates
    
    Returns:
        Weather data including temperature, conditions, etc.
    """
    api_key = os.getenv("WEATHER_API_KEY")
    if not api_key:
        return {"error": "WEATHER_API_KEY not set"}
    
    url = f"https://api.openweathermap.org/data/2.5/weather"
    params = {
        "q": location,
        "appid": api_key,
        "units": "metric"
    }
    
    try:
        response = requests.get(url, params=params)
        response.raise_for_status()
        data = response.json()
        
        return {
            "location": data["name"],
            "temperature": data["main"]["temp"],
            "conditions": data["weather"][0]["description"],
            "humidity": data["main"]["humidity"],
            "wind_speed": data["wind"]["speed"]
        }
    except Exception as e:
        return {"error": str(e)}
log:
  stdout_log_level: INFO
  log_file_level: DEBUG
  log_file: {component_name}.log

!include ../shared_config.yaml

apps:
  - name: {component_name}_app
    app_base_path: .
    app_module: solace_agent_mesh.agent.sac.app
    
    broker:
      <<: *broker_connection
    
    app_config:
      namespace: ${NAMESPACE}
      agent_name: "{component_name}"
      display_name: "Weather Agent"
      model: *general_model
      
      instruction: |
        You are a weather information agent. You can provide current weather
        information for any location using the get_weather tool. Always include
        temperature, conditions, and relevant details in your responses.
      
      tools:
        - tool_type: python
          component_module: sam_weather_agent.tools.weather_api
          component_base_path: .
          function_name: get_weather
          tool_name: "get_weather"
        - tool_type: builtin-group
          group_name: "artifact_management"
      
      session_service:
        type: "memory"
        default_behavior: "PERSISTENT"
      
      artifact_service:
        type: "filesystem"
        base_path: "/tmp/samv2"
        artifact_scope: namespace
      
      agent_card:
        description: "Provides current weather information for any location"
        defaultInputModes: ["text"]
        defaultOutputModes: ["text"]
        skills:
          - id: "get_weather"
            name: "Weather Lookup"
            description: "Fetches current weather data including temperature, conditions, humidity, and wind speed for any city or location"
      
      agent_card_publishing:
        interval_seconds: 10
      
      agent_discovery:
        enabled: true
      
      inter_agent_communication:
        allow_list: []
        request_timeout_seconds: 60
[build-system]
requires = ["setuptools>=61.0", "wheel"]
build-backend = "setuptools.build_meta"

[project]
name = "sam-weather-agent"
version = "1.0.0"
description = "Weather information agent for Solace Agent Mesh"
readme = "README.md"
requires-python = ">=3.10"
authors = [
    {name = "Your Name", email = "[email protected]"}
]
license = {text = "Apache-2.0"}
dependencies = [
    "solace-agent-mesh>=1.0.0",
    "requests>=2.31.0",
]

[project.urls]
Homepage = "https://github.com/yourorg/sam-weather-agent"
Documentation = "https://github.com/yourorg/sam-weather-agent#readme"
Repository = "https://github.com/yourorg/sam-weather-agent"

Using the Weather Plugin

# Install from PyPI
sam plugin add weather --plugin sam-weather-agent

# Set API key
export WEATHER_API_KEY="your-api-key"

# Run the agent
sam run configs/agents/weather.yaml

Plugin Development Best Practices

  • Use placeholders like {component_name} for customization
  • Reference shared config with !include ../shared_config.yaml
  • Provide sensible defaults
  • Document required environment variables
  • Include comprehensive README with:
    • Installation instructions
    • Configuration examples
    • Environment variable requirements
    • Usage examples
  • Document custom tools with clear docstrings
  • Provide troubleshooting guidance
  • Minimize external dependencies
  • Pin major versions for stability
  • List optional dependencies separately
  • Test with minimum required versions
  • Follow semantic versioning (MAJOR.MINOR.PATCH)
  • Update version in pyproject.toml
  • Tag releases in Git
  • Maintain a CHANGELOG
  • Include unit tests for custom tools
  • Test with different Python versions (3.10+)
  • Validate configuration templates
  • Test installation from wheel

Plugin Registry

Configure custom plugin sources:
# ~/.sam/plugin_registry.yaml
registries:
  - name: "official"
    type: "github"
    url: "https://github.com/SolaceLabs/solace-agent-mesh-core-plugins"
  
  - name: "corporate"
    type: "pypi"
    url: "https://pypi.internal.example.com/simple"
  
  - name: "local"
    type: "directory"
    path: "/shared/sam-plugins"

Troubleshooting

Check:
  • Python version is 3.10 or higher
  • Plugin package name is correct
  • Network access to package source
  • Virtual environment is activated
Try manual installation:
pip install my-plugin
sam plugin add my-component --plugin my-plugin
Check:
  • Plugin contains valid config.yaml
  • configs/ directory exists in project
  • Write permissions for config directory
Manually copy configuration:
cp $(python -c "import my_plugin; print(my_plugin.__path__[0])")/config.yaml \
   configs/agents/my_component.yaml
Check:
  • Plugin package is installed: pip show my-plugin
  • Module path in config matches actual structure
  • component_base_path is set correctly
  • Python path includes plugin location
Check:
  • Plugin dependencies don’t conflict with project
  • solace-agent-mesh version compatibility
Use dependency resolver:
pip install --upgrade pip
pip install my-plugin --dry-run

Next Steps

Core Plugins

Browse official plugin repository

Creating Agents

Learn agent development patterns

Python Tools

Build custom tool functions

Custom Gateways

Develop gateway plugins

Build docs developers (and LLMs) love