1  ---
  2  title: Plugins
  3  sidebar_position: 270
  4  ---
  5  
  6  import NetworkAccessRequiredSomeFeatures from '@site/docs/partials/network-access-required-some-features.mdx';
  7  
  8  Plugins provide a mechanism to extend the functionality of Agent Mesh in a modular, shareable, and reusable way. The current plugin ecosystem includes agents, gateways, and specialized integrations.
  9  
 10  :::tip[In one sentence]
 11  Plugins are modular Python packages that extend Solace the capabilities of Agent Mesh through agents, gateways, and specialized integrations.
 12  :::
 13  
 14  Plugins are packaged as Python modules that can be installed using various package managers (`pip`, `uv`, `poetry`, `conda`). They integrate seamlessly with the A2A protocol and can provide:
 15  
 16  - **Agent Plugins**: Specialized agents with domain-specific capabilities
 17  - **Gateway Plugins**: New interface types for external system integration
 18  - **Custom Plugins**: Custom integrations such as HR providers.
 19  
 20  All plugin interactions (create, build, add) are managed through the Agent Mesh CLI.
 21  
 22  <NetworkAccessRequiredSomeFeatures />
 23  
 24  :::info
 25  Run `sam plugin --help` to see the list of available commands for plugins.
 26  :::
 27  
 28  ### Official Core Plugins
 29  
 30  Agent Mesh comes with a set of official core plugins that can be used to extend the functionality of the system. You can find the repository of the official core plugins [here 🔗](https://github.com/SolaceLabs/solace-agent-mesh-core-plugins).
 31  
 32  For more information about how to use the official core plugins, see [Use Plugins](#use-a-plugin).
 33  
 34  
 35  ## Create a Plugin
 36  
 37  To get started, [install the Agent Mesh CLI](../installing-and-configuring/installation.md) and run the following command:
 38  
 39  ```bash
 40  solace-agent-mesh plugin create <plugin-name>
 41  ```
 42  
 43  Follow the prompts to create a new plugin. A plugin can be one of the following types:
 44  - **Agent Plugin**: Contains custom agents that can be used in a Agent Mesh project.
 45  - **Gateway Plugin**: Contains custom gateways that can be used in a Agent Mesh project.
 46  - **Custom Plugin**: Contains custom integrations such as HR providers or other specialized functionality.
 47  
 48  The Agent Mesh CLI creates a directory with the provided name and the following structure:
 49  
 50  ```
 51  plugin-name/
 52  ├─ config.yaml
 53  ├─ src/
 54  │  ├─ __init__.py
 55  │  ├─ [...Other type specific python files]
 56  ├─ .gitignore
 57  ├─ pyproject.toml
 58  ├─ README.md
 59  ```
 60  
 61  - The `src` directory contains the python source code. 
 62  - The `config.yaml` file holds the configuration for the plugin, and how to be used in a Agent Mesh application.
 63  
 64  Once the plugin is created, you can start customizing the config.yaml or the python files.
 65  
 66  ### Build the Plugin
 67  
 68  Building the plugin creates a Python wheel package that can be installed using `pip` or other package managers.
 69  
 70  Python `build` package must be installed already since `sam plugin build` command uses `build` package, if not, run `pip install build`.
 71  
 72  To build the plugin, run the following Agent Mesh CLI command:
 73  
 74  ```bash
 75  solace-agent-mesh plugin build
 76  ```
 77  
 78  The plugin uses the standard `pyproject.toml` file to build the package. 
 79  
 80  ### Share the Plugin
 81  
 82  To share the plugin, you can upload the wheel package to a package repository or share the wheel package directly, or any other valid way to share a `pyproject` project.
 83  
 84  ## Use a Plugin
 85  
 86  To use a plugin in your project, use the `plugin add` command, which performs two steps under-the-hood:
 87  
 88  - Locates the plugin or installs the plugin package using a Python package manager (like `pip` or `uv`)
 89  - Creates a component instance based on the plugin
 90  
 91  ```bash
 92  solace-agent-mesh plugin add <COMPONENT_NAME> --plugin <PLUGIN_NAME>
 93  ``` 
 94  where:
 95  
 96  `<COMPONENT_NAME>` is the name you choose for the component instance in your project.
 97  
 98  `<PLUGIN_NAME>`, you can use:
 99  - Name of the plugin as published to a package manager like `pypi`, for example `my-plugin`
100  - Name of the plugin that has been already installed into your Python environment. 
101  - A local path to the plugin directory, for example `./my-plugin`
102  - A path to a wheel package, for example `./my-plugin/dist/my_plugin-0.1.0-py3-none-any.whl`
103  - A URL to a git repository, for example `git+https://github.com/<USERNAME>/<REPOSITORY>`
104    - If the plugin is in a subdirectory of the repository, you can specify the subdirectory using the `git+https://github.com/<USERNAME>/<REPOSITORY>#subdirectory=<PLUGIN_NAME>` syntax.
105  
106  The CLI handles both steps automatically, or you can manage the plugin installation yourself using your preferred Python package manager.
107  
108  :::tip
109  You can also customize the python package manager command used to install the plugin by setting the `SAM_PLUGIN_INSTALL_COMMAND` environment variable or passing the `--install-command` option to the `plugin add` command.
110  For example, to use `uv` as the package manager, you can run:
111  
112  ```bash
113  export SAM_PLUGIN_INSTALL_COMMAND="uv pip install {package}"
114  ```
115  
116  or
117  
118  ```bash
119  solace-agent-mesh plugin add <COMPONENT_NAME> --plugin <PLUGIN_NAME> --install-command "uv pip install {package}"
120  ```
121  :::
122  
123  
124  This command adds the plugin instance configuration to your `configs` directory.
125  
126  Depending on the plugin, you may need to update the newly added plugin configuration file. Follow the instructions provided by the plugin author for any specific configurations.
127  
128  ## Plugin Catalog Dashboard
129  
130  You can manage available plugins with the `plugin catalog` command, which launches a user-friendly interface.
131  
132  ```bash
133  solace-agent-mesh plugin catalog
134  ``` 
135  
136  ## Agent or Plugin: Which To Use?
137  
138  In simple terms, plugins of type agent are just packaged agents. However, there are distinct advantages to each approach, and choosing the right one depends on your use case.
139  
140  Here’s a detailed comparison to help you decide.
141  
142  | Feature | Standalone Agent (`sam add agent`) | Agent Plugin (`sam plugin create`) |
143  | :--- | :--- | :--- |
144  | **Creation** | A single command creates a configuration file in your project. | Creates a complete, standard Python project structure. |
145  | **Structure** | Consists of a YAML configuration file and associated Python tool files within a Agent Mesh project. | A self-contained Python package with `pyproject.toml`, a `src` directory, and configuration templates. |
146  | **Packaging** | Not packaged. It exists as a component within a larger Agent Mesh project. | Packaged into a standard Python wheel (`.whl`) file using `sam plugin build`. |
147  | **Distribution** | Shared by copying files or sharing the entire project. | Easily distributed as a wheel file, via a Git repository, or published to a package index like PyPI. |
148  | **Reusability** | Primarily for use within the project where it was created. | Designed for high reusability across different projects, teams, and communities. |
149  | **Installation** | No installation needed. The agent is configured and run as part of the main project. | Installed into the Python environment using `sam plugin add`, which handles the package installation. |
150  | **Versioning** | Versioned along with the main project. | Can be versioned independently according to Python packaging standards (e.g., `v0.1.0`, `v0.2.0`). |
151  | **Development** | Simple and direct. Edit files and run. Ideal for rapid prototyping. | Involves a build/install cycle. Better for structured, long-term development. |
152  
153  ### When To Use a Standalone Agent
154  
155  Create a standalone agent when:
156  
157  - You need to quickly test an idea or build a proof-of-concept.
158  - The agent is tightly coupled to a single project and is not intended for reuse.
159  - You want the most straightforward path to adding a simple agent without the overhead of a full package structure.
160  
161  ### When To Use an Agent Plugin
162  
163  Create an agent as a plugin when:
164  
165  - You plan to use the same agent in multiple projects.
166  - You want to share your agent with other developers, teams, or the open-source community.
167  - You are building a robust, production-ready agent that benefits from a formal package structure, dependency management, and versioning.
168  - You are building a collection of standardized agents for your organization.
169  
170  ### Recommendation
171  
172  The choice of how to build your agent depends on your goals and the requirements of your project:
173  
174  - **Standalone Agents** should be viewed as tactical tools for rapid, isolated prototyping. They serve immediate, project-specific needs but do not contribute to a scalable, long-term asset library.
175  
176  - **Agent Plugins** are the foundation for building a robust, governable, and reusable AI ecosystem. This model treats AI capabilities as enterprise assets, promoting standardization, reducing redundant development costs, and accelerating innovation across the organization. For any capability intended for broader use or long-term value, the plugin framework is the mandated path to maximize return on investment and ensure architectural integrity.
177  
178