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.)
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
Plugin
Best for:
- Reusable components
- Cross-project sharing
- Production deployments
- Team standardization
- Open-source distribution
Detailed Comparison
| Feature | Standalone Component | Plugin |
|---|---|---|
| Creation | Single command creates YAML config | Complete Python project structure |
| Structure | YAML file + optional Python tools | Full package with pyproject.toml, src/, config templates |
| Packaging | Not packaged | Standard Python wheel (.whl) |
| Distribution | Copy files or share project | PyPI, Git, wheel files, package managers |
| Reusability | Within project only | Across projects, teams, organizations |
| Installation | No installation needed | sam plugin add or pip install |
| Versioning | With project | Independent semantic versioning |
| Development | Direct edit and run | Build/install cycle |
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:- Agent Plugin
- Gateway Plugin
- Custom Plugin
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:Configuration Template
Theconfig.yaml defines how the plugin is used:
{component_name} are replaced when users install the plugin.
Package Metadata
Thepyproject.toml defines package information:
Building and Distributing
Build the Plugin
Create a distributable wheel package:Requires the
build package: pip install buildDistribution Methods
- PyPI (Public)
- Git Repository
- Wheel File
- Local Development
Using Plugins
Install and Configure
Theplugin add command performs two operations:
- Installs the plugin package (if not already installed)
- Creates a component configuration from the plugin template
<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
- PyPI package name:
Examples
Custom Package Manager
Override the installation command:Plugin Catalog
Browse and manage plugins with the catalog UI:- 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:View Plugin Structure
View Plugin Structure
weather_api.py - Custom Tool
weather_api.py - Custom Tool
config.yaml - Plugin Configuration
config.yaml - Plugin Configuration
pyproject.toml - Package Metadata
pyproject.toml - Package Metadata
Using the Weather Plugin
Plugin Development Best Practices
Configuration Templates
Configuration Templates
- Use placeholders like
{component_name}for customization - Reference shared config with
!include ../shared_config.yaml - Provide sensible defaults
- Document required environment variables
Documentation
Documentation
- Include comprehensive README with:
- Installation instructions
- Configuration examples
- Environment variable requirements
- Usage examples
- Document custom tools with clear docstrings
- Provide troubleshooting guidance
Dependencies
Dependencies
- Minimize external dependencies
- Pin major versions for stability
- List optional dependencies separately
- Test with minimum required versions
Versioning
Versioning
- Follow semantic versioning (MAJOR.MINOR.PATCH)
- Update version in
pyproject.toml - Tag releases in Git
- Maintain a CHANGELOG
Testing
Testing
- 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:Troubleshooting
Plugin installation fails
Plugin installation fails
Check:
- Python version is 3.10 or higher
- Plugin package name is correct
- Network access to package source
- Virtual environment is activated
Configuration not created
Configuration not created
Check:
- Plugin contains valid
config.yaml configs/directory exists in project- Write permissions for config directory
Custom tools not found
Custom tools not found
Check:
- Plugin package is installed:
pip show my-plugin - Module path in config matches actual structure
component_base_pathis set correctly- Python path includes plugin location
Version conflicts
Version conflicts
Check:
- Plugin dependencies don’t conflict with project
solace-agent-meshversion compatibility
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