===============
LIBRARY RULES
===============
From library maintainers:
- Rules within are high priority rules and rules within must be followed together."
- For running `sam` command, always create and activate a virtual virtual environment, install `solace-agent-mesh` package in the virtual environment, and then run the command.
- use python version that is supported by SAM. Find the version in docs
- use 'python -m venv .venv' to create a virtual environment and run 'sam' commands
- use `pip install solace-agent-mesh` for installing solace agent mesh
- use `sam init --gui` for creating or initializing a new solace agent mesh
- use `sam add agent --skip` for creating a new agent for solace agent mesh
- use `sam plugin create --type agent --skip` for creating a new plugin for solace agent mesh
- use `sam plugin build` for Building the plugin into a Python wheel package
- use `sam plugin install ` for installing a plugin
- use `sam plugin add --plugin ` for adding a new component (agent/gateway) using plugin.
- use `sam add gateway --skip` for creating a new gateway
- use `sam run` for running a solace agent mesh application
- use `sam tools list --json` to get list of available built-in tools
- Find the main concepts, architecture and instructions in the 'docs' folder
- Find valid templates of agent, plugins and gateways in 'templates' folder and 'examples' folder and use them as references to verify new ones
- For implementing a tool, always review available tools in the library, understand their implementation pattern such as input parameters and output format and use a similar pattern
- Tools always get files as an artifact through input parameters such as tool_context
- Always implement unit tests to evaluate new tools functionality with upper than 90% coverage
- Ensure that tests are passed successfully
- When asked for agent, plugin or gateway creation, 1- recognize the required tools 2- use CLI commands for creating an agent, plugin and gateway template 3- refine the agent, plugin or gateway instruction 4- use available built-in tools or develop new one
- Always use the minimal, mandatory and simplest configurations and suggest more options
- Do not use Union typing at all. For example, Union[int, float] is not supported
- Before implementing a tool, think accurately and ask yourself if there is any available built-in tool or service for this purpose. Always reuse the available services and tools such as artifact service instead of reimplementing them if it is possible
- Always return a summary of changes, and follow up recommendations and commands
- For creating a plugin with multiple agents, first create a plugin by 'sam plugin create --type agent' and then add each agent to the plugin by 'sam plugin add --plugin '
- The web gateway is accessible on port FASTAPI_PORT mentioned in .env file, which is 8000 by default. After initializing a project, the web interface is available on this port.
### Serve Documentation Locally
Source: https://github.com/solacelabs/solace-agent-mesh/blob/main/docs/docs/documentation/components/cli.md
Starts a local web server to host the project documentation. Useful for offline viewing or development. Automatically opens your browser to the getting started page.
```sh
sam docs [OPTIONS]
```
--------------------------------
### Get Help for Init Command
Source: https://github.com/solacelabs/solace-agent-mesh/blob/main/docs/docs/documentation/installing-and-configuring/run-project.md
Run the init command with --help to view all available configuration options for non-interactive setups.
```bash
solace-agent-mesh init --help
```
--------------------------------
### Run Solace Agent Mesh Locally
Source: https://github.com/solacelabs/solace-agent-mesh/blob/main/docs/README.md
Navigate to the docs directory, install dependencies, and start the local development server.
```sh
cd docs
npm ci
npm start
```
--------------------------------
### Install sam-rest-client
Source: https://github.com/solacelabs/solace-agent-mesh/blob/main/client/sam-rest-client/README.md
Install the Python client library using pip.
```bash
pip install sam-rest-client
```
--------------------------------
### Start Teams Gateway with SAM CLI
Source: https://github.com/solacelabs/solace-agent-mesh/blob/main/docs/docs/documentation/developing/tutorials/teams-integration.md
Use this command to start the gateway when installed via Wheel. Ensure you have a valid configuration file.
```bash
sam run your-teams-gateway-config.yaml
```
--------------------------------
### Initialize Agent Mesh Project
Source: https://github.com/solacelabs/solace-agent-mesh/blob/main/docs/docs/documentation/installing-and-configuring/run-project.md
Run the init command to start the Agent Mesh project setup. You will be prompted to choose between terminal or web-based configuration.
```bash
solace-agent-mesh init
```
--------------------------------
### Test Installation
Source: https://github.com/solacelabs/solace-agent-mesh/blob/main/RELEASE_PROCESS.md
Verify the package installation after a release.
```bash
pip install solace-agent-mesh
```
--------------------------------
### Download Example Data with wget
Source: https://github.com/solacelabs/solace-agent-mesh/blob/main/docs/docs/documentation/developing/tutorials/sql-database.md
Downloads the example SQLite database data for the coffee company.
```sh
wget https://github.com/SolaceLabs/solace-agent-mesh-core-plugins/raw/refs/heads/main/sam-sql-database/example-data/abc_coffee_co.zip
```
--------------------------------
### Initialize Gateway Adapter
Source: https://github.com/solacelabs/solace-agent-mesh/blob/main/docs/docs/documentation/developing/create-gateways.md
Implement the `init` method to store context and start platform listeners when the gateway starts.
```python
async def init(self, context: GatewayContext) -> None:
"""
Initialize the gateway adapter.
This is where you should:
- Store the context for later use
- Start platform listeners (WebSocket, HTTP server, etc.)
- Connect to external services
"""
self.context = context
# Initialize your platform connection
await self.start_platform_listener()
```
--------------------------------
### Add MCP Gateway Plugin
Source: https://github.com/solacelabs/solace-agent-mesh/blob/main/docs/docs/documentation/developing/tutorials/mcp-gateway.md
Installs the MCP Gateway plugin and creates a gateway configuration file. Use any name for your gateway; 'my-mcp-gateway' is used as an example.
```sh
sam plugin add my-mcp-gateway --plugin sam-mcp-server-gateway-adapter
```
--------------------------------
### Install a Plugin
Source: https://github.com/solacelabs/solace-agent-mesh/blob/main/docs/docs/documentation/components/cli.md
Installs a plugin from a specified source, which can be a local path, a wheel file, a Git URL, or an official plugin name. Supports custom installation commands.
```sh
sam plugin install [OPTIONS] PLUGIN_SOURCE
```
--------------------------------
### Example Evaluation Command
Source: https://github.com/solacelabs/solace-agent-mesh/blob/main/docs/docs/documentation/developing/evaluations.md
This example shows how to run an evaluation using a specific test suite file and enabling verbose logging.
```bash
sam eval tests/evaluation/local_example.json --verbose
```
--------------------------------
### Extract Example Data
Source: https://github.com/solacelabs/solace-agent-mesh/blob/main/docs/docs/documentation/developing/tutorials/sql-database.md
Extracts the downloaded ZIP file containing the example database data.
```sh
unzip abc_coffee_co.zip
```
--------------------------------
### Run Local Evaluation with Make
Source: https://github.com/solacelabs/solace-agent-mesh/blob/main/evaluation/README.md
Automates environment setup, dependency installation, and execution of local evaluation tests. Ensure environment variables are exported before running.
```bash
make test-eval-local
```
--------------------------------
### Example: Add Proxy with Skip Option
Source: https://github.com/solacelabs/solace-agent-mesh/blob/main/docs/docs/documentation/components/cli.md
This example demonstrates adding a proxy component using the '--skip' option to use default configurations. It creates a default proxy configuration file.
```sh
sam add proxy myProxy --skip
```
--------------------------------
### Install sam-rest-gateway Plugin
Source: https://github.com/solacelabs/solace-agent-mesh/blob/main/docs/docs/documentation/developing/evaluations.md
Install the necessary plugin for local evaluation mode to enable communication with the local SAM instance.
```bash
pip install sam-rest-gateway
```
--------------------------------
### Basic Authentication Example
Source: https://github.com/solacelabs/solace-agent-mesh/blob/main/docs/docs/documentation/enterprise/openapi-tools.md
Example of OpenAPI tool configuration using basic authentication.
```yaml
tools:
- tool_type: openapi
specification_url: "https://api.example.com/openapi.json"
base_url: "https://api.example.com"
auth:
type: basic
username: ${API_USERNAME}
password: ${API_PASSWORD}
```
--------------------------------
### Example Agent Configuration for Image Creation
Source: https://github.com/solacelabs/solace-agent-mesh/blob/main/docs/docs/documentation/components/builtin-tools/image-tools.md
Example agent configuration demonstrating how to set up the create_image_from_description tool within an agent's application configuration. This includes defining the agent's name, instructions, and tool settings.
```yaml
# Agent configuration
app_config:
agent_name: "DesignAgent"
instruction: "You create visual content based on user descriptions."
tools:
- tool_type: builtin
tool_name: "create_image_from_description"
tool_config:
model: "imagen-4-ultra"
api_key: "${OPENAI_API_KEY}"
api_base: "https://api.openai.com"
```
--------------------------------
### Configure Provider-Specific Credentials (Azure Example)
Source: https://github.com/solacelabs/solace-agent-mesh/blob/main/docs/docs/documentation/enterprise/single-sign-on.md
Provide credentials for your OAuth2 provider. This example shows Azure tenant ID, client ID, and client secret. Adjust for other providers like Google or Auth0.
```bash
-e AZURE_TENANT_ID="xxxxxxxxx-xxxxxx-xxxxxxxx-xxxxxxxxxx" \
-e AZURE_CLIENT_ID="xxxxxxxxx-xxxxxx-xxxxxxxx-xxxxxxxxxx" \
-e AZURE_CLIENT_SECRET="xxxxxxxxx-xxxxxx-xxxxxxxx-xxxxxxxxxx" \
```
--------------------------------
### Prompt Template Example with Variables
Source: https://github.com/solacelabs/solace-agent-mesh/blob/main/docs/docs/documentation/components/prompts.md
This example demonstrates a prompt template with variable placeholders for dynamic content. Use `{{Variable Name}}` format for placeholders.
```plaintext
Review the {{Module Name}} module located at {{File Path}}.
Focus on:
- Security vulnerabilities
- Error handling
- {{Specific Concerns}}
```
--------------------------------
### Install Agent Mesh Enterprise with uv
Source: https://github.com/solacelabs/solace-agent-mesh/blob/main/docs/docs/documentation/enterprise/wheel-installation.md
Use this command to install the Agent Mesh Enterprise wheel file using uv.
```bash
uv pip install solace_agent_mesh_enterprise--py3-none-any.whl
```
--------------------------------
### Start Agent Mesh with Configuration
Source: https://github.com/solacelabs/solace-agent-mesh/blob/main/docs/docs/documentation/enterprise/otel-metrics/integration.md
Start the Agent Mesh process, providing both the main Agent Mesh configuration and the management server configuration file that includes observability settings.
```bash
solace-agent-mesh run configs/my_agent.yaml configs/management_server.yaml
```
--------------------------------
### API Key Authentication Example (Header)
Source: https://github.com/solacelabs/solace-agent-mesh/blob/main/docs/docs/documentation/enterprise/openapi-tools.md
Example of API key authentication where the key is sent in the X-API-Key header.
```yaml
auth:
type: apikey
in: header
name: X-API-Key
value: ${MY_API_KEY}
```
--------------------------------
### API Key Authentication Example (Query)
Source: https://github.com/solacelabs/solace-agent-mesh/blob/main/docs/docs/documentation/enterprise/openapi-tools.md
Example of API key authentication where the key is sent as a query parameter.
```yaml
auth:
type: apikey
in: query
name: apikey
value: ${MY_API_KEY}
```
--------------------------------
### Start Development Server
Source: https://github.com/solacelabs/solace-agent-mesh/blob/main/client/webui/frontend/README.md
Start the Vite development server to run the application locally. This command enables hot module replacement and other development-specific features.
```bash
npm run dev
```
--------------------------------
### Gateway Adapter Lifecycle: Initialization
Source: https://github.com/solacelabs/solace-agent-mesh/blob/main/docs/docs/documentation/developing/create-gateways.md
The `init()` method is called when the gateway starts. It's used for storing context, starting platform listeners, and connecting to external services.
```APIDOC
## init(context: GatewayContext)
### Description
Initialize the gateway adapter. This is where you should store the context, start platform listeners, and connect to external services.
### Parameters
- **context** (GatewayContext) - The context for the gateway.
### Method Signature
```python
async def init(self, context: GatewayContext) -> None:
"""
Initialize the gateway adapter.
This is where you should:
- Store the context for later use
- Start platform listeners (WebSocket, HTTP server, etc.)
- Connect to external services
"""
self.context = context
# Initialize your platform connection
await self.start_platform_listener()
```
```
--------------------------------
### Download Example Data with curl
Source: https://github.com/solacelabs/solace-agent-mesh/blob/main/docs/docs/documentation/developing/tutorials/sql-database.md
Downloads the example SQLite database data for the coffee company using curl.
```sh
curl -LO https://github.com/SolaceLabs/solace-agent-mesh-core-plugins/raw/refs/heads/main/sam-sql-database/example-data/abc_coffee_co.zip
```
--------------------------------
### Stress Test Scale Profile Examples
Source: https://github.com/solacelabs/solace-agent-mesh/blob/main/tests/stress/README.md
Examples of using the --stress-scale option to select different load profiles for stress testing.
```bash
# Examples
--stress-scale=smoke # Quick CI check
--stress-scale=medium # Standard testing
--stress-scale=large # Load testing
--stress-scale=soak # Long-running stability
```
--------------------------------
### Add an Existing Plugin
Source: https://github.com/solacelabs/solace-agent-mesh/blob/main/docs/docs/documentation/components/cli.md
Installs plugins and creates a new component instance from a specified plugin source. Supports local paths, installed module names, or Git URLs.
```sh
sam plugin add [OPTIONS] COMPONENT_NAME
```
--------------------------------
### Image Editing Prompt Examples
Source: https://github.com/solacelabs/solace-agent-mesh/blob/main/docs/docs/documentation/components/builtin-tools/image-tools.md
Examples illustrating effective prompts for the edit_image_with_gemini tool. Specificity in prompts leads to better results. Use high-resolution images for optimal quality.
```yaml
# Good
edit_prompt: "Remove the person in the red shirt on the left side, fill the space with matching background"
# Poor
edit_prompt: "Remove person"
```
--------------------------------
### Example Remote Test Suite Configuration
Source: https://github.com/solacelabs/solace-agent-mesh/blob/main/docs/docs/documentation/developing/evaluations.md
An example configuration for a remote Agent Mesh evaluation, including broker and remote instance details, test cases, and evaluation settings.
```json
{
"broker": {
"SOLACE_BROKER_URL_VAR": "SOLACE_BROKER_URL",
"SOLACE_BROKER_USERNAME_VAR": "SOLACE_BROKER_USERNAME",
"SOLACE_BROKER_PASSWORD_VAR": "SOLACE_BROKER_PASSWORD",
"SOLACE_BROKER_VPN_VAR": "SOLACE_BROKER_VPN"
},
"remote": {
"EVAL_REMOTE_URL_VAR": "EVAL_REMOTE_URL",
"EVAL_AUTH_TOKEN_VAR": "EVAL_AUTH_TOKEN",
"EVAL_NAMESPACE_VAR": "EVAL_NAMESPACE"
},
"results_dir_name": "sam-remote-eval-test",
"runs": 1,
"test_cases": [
"tests/evaluation/test_cases/filter_csv_employees_by_age_and_country.test.json",
"tests/evaluation/test_cases/hello_world.test.json"
],
"evaluation_settings": {
"tool_match": {
"enabled": true
},
"response_match": {
"enabled": true
},
"llm_evaluator": {
"enabled": true,
"env": {
"LLM_SERVICE_PLANNING_MODEL_NAME": "openai/gemini-2.5-pro",
"LLM_SERVICE_ENDPOINT_VAR": "LLM_SERVICE_ENDPOINT",
"LLM_SERVICE_API_KEY_VAR": "LLM_SERVICE_API_KEY"
}
}
}
}
```
--------------------------------
### Install Solace Agent Mesh Project
Source: https://github.com/solacelabs/solace-agent-mesh/blob/main/evaluation/README.md
Installs the Solace Agent Mesh project and its dependencies. This is a manual setup step.
```bash
pip install .
```
--------------------------------
### Create Working Directory and File
Source: https://github.com/solacelabs/solace-agent-mesh/blob/main/docs/docs/documentation/developing/tutorials/mcp-integration.md
Prepare the working directory for the filesystem MCP example by creating the directory and a sample file. This is a prerequisite for running the agent.
```sh
mkdir -p /tmp/samv2
echo "Hello MCP!" > /tmp/samv2/test.txt
```
--------------------------------
### Testcontainers Fixture Example
Source: https://github.com/solacelabs/solace-agent-mesh/blob/main/tests/integration/migrations/README.md
Example of a pytest fixture using Testcontainers to manage a PostgreSQL container. The container is automatically started before tests and stopped after.
```python
# conftest.py
@pytest.fixture(scope="session")
def postgres_container():
postgres = PostgresContainer("postgres:15-alpine")
postgres.start() # Automatic!
yield postgres
postgres.stop() # Automatic cleanup!
```
--------------------------------
### Initialize Agent Mesh Project with GUI
Source: https://github.com/solacelabs/solace-agent-mesh/blob/main/docs/docs/documentation/installing-and-configuring/run-project.md
Use the --gui flag to bypass the prompt and directly launch the web-based configuration interface for your project.
```bash
solace-agent-mesh init --gui
```
--------------------------------
### Get Agent Mesh CLI Version
Source: https://github.com/solacelabs/solace-agent-mesh/blob/main/docs/docs/documentation/components/cli.md
Run this command to determine the installed version of the Agent Mesh CLI.
```sh
solace-agent-mesh --version
```
--------------------------------
### Typical Workflow: Create, Poll, List, and Download
Source: https://github.com/solacelabs/solace-agent-mesh/blob/main/docs/docs/documentation/developing/tutorials/rest-gateway.md
This script demonstrates a typical workflow: setting tokens, creating a task, polling for completion, listing artifacts, and downloading a specific artifact.
```sh
# 1. Set your token
export SAM_TOKEN="your-token"
export SAM_HOST="http://localhost:8000"
# 2. Create a task
RESPONSE=$(curl -s -X POST "${SAM_HOST}/api/v2/tasks" \
-H "Authorization: Bearer ${SAM_TOKEN}" \
-F "agent_name=OrchestratorAgent" \
-F "prompt=Create a CSV with 5 products")
TASK_ID=$(echo $RESPONSE | jq -r '.taskId')
echo "Task ID: $TASK_ID"
# 3. Poll until complete
POLL_RESPONSE=$(curl -s -X GET "${SAM_HOST}/api/v2/tasks/${TASK_ID}" \
-H "Authorization: Bearer ${SAM_TOKEN}")
echo $POLL_RESPONSE | jq .
# 4. Get context ID from poll response, then list artifacts
CONTEXT_ID=$(echo $POLL_RESPONSE | jq -r '.contextId')
curl -s -X GET "${SAM_HOST}/api/v2/artifacts/?session_id=${CONTEXT_ID}" \
-H "Authorization: Bearer ${SAM_TOKEN}" | jq .
# 5. Download artifact
FILENAME="products.csv"
curl -s -X GET "${SAM_HOST}/api/v2/artifacts/${FILENAME}?session_id=${CONTEXT_ID}" \
-H "Authorization: Bearer ${SAM_TOKEN}" \
-o "${FILENAME}"
echo "Saved to: ${FILENAME}"
```
--------------------------------
### Initialize SAM Project with GUI
Source: https://github.com/solacelabs/solace-agent-mesh/blob/main/docs/docs/documentation/components/platform-service.md
Run this command to initialize a new SAM project with a graphical user interface. Select 'Yes' when prompted to enable the WebUI Gateway to generate the necessary configuration file for the Platform Service.
```bash
sam init --gui
```
--------------------------------
### Add REST Gateway Plugin
Source: https://github.com/solacelabs/solace-agent-mesh/blob/main/docs/docs/documentation/developing/tutorials/rest-gateway.md
Installs the sam-rest-gateway plugin and creates a new gateway configuration. Use any name for your agent; 'my-http-rest' is used as an example.
```sh
sam plugin add my-http-rest --plugin sam-rest-gateway
```
--------------------------------
### Build and Distribute Gateway Plugin
Source: https://github.com/solacelabs/solace-agent-mesh/blob/main/docs/docs/documentation/developing/create-gateways.md
Navigate to the created plugin directory and execute the build command. This prepares the plugin for distribution and use.
```bash
cd my-gateway-plugin
sam plugin build
```
--------------------------------
### Grant Broad Tool Access with Wildcards
Source: https://github.com/solacelabs/solace-agent-mesh/blob/main/docs/docs/documentation/enterprise/rbac-setup-guide.md
Use wildcard characters in role scopes to grant broad access to a category of tools. This example grants the `database_admin` role access to all tools with scopes starting with `tool:database:`.
```yaml
roles:
database_admin:
description: "Database administrator with full database tool access"
scopes:
- "tool:database:*" # Grants access to all tools with required_scopes starting with "tool:database:"
```
--------------------------------
### Run Solace Agent Mesh Docker Image
Source: https://github.com/solacelabs/solace-agent-mesh/blob/main/docs/docs/documentation/getting-started/try-agent-mesh.md
Execute this command to run the pre-configured Solace Agent Mesh Docker image. This starts the service with preset agents, making it easy to explore its capabilities immediately. Ensure Docker is installed.
```bash
docker run --rm -it -p 8000:8000 --platform linux/amd64 solace/solace-agent-mesh:latest
```
--------------------------------
### Install Agent Mesh with uv
Source: https://github.com/solacelabs/solace-agent-mesh/blob/main/docs/docs/documentation/installing-and-configuring/installation.md
Install the Solace Agent Mesh package using uv. This command installs both the CLI and the framework.
```sh
uv pip install solace-agent-mesh
```
--------------------------------
### Example Agent Instructions Configuration
Source: https://github.com/solacelabs/solace-agent-mesh/blob/main/docs/docs/documentation/developing/tutorials/bedrock-agents.md
Provide clear instructions for the agent's LLM to define its role and capabilities when responding to user queries.
```yaml
instruction: "You are a helpful assistant that can summarize text and generate creative content. Use the available tools to fulfill user requests."
```
--------------------------------
### Setup and Verify Artifacts
Source: https://github.com/solacelabs/solace-agent-mesh/blob/main/tests/sam-test-infrastructure/sam-test-infrastructure.md
Manage artifacts for testing by setting up initial artifacts and verifying their creation or modification. Artifacts can be defined with filename, content, and mime type. Use `test_artifact_service_instance` to interact with the artifact service.
```python
# Setup initial artifacts
setup_artifacts = [{
"filename": "input.txt",
"content": "Initial content",
"mime_type": "text/plain"
}]
# Include in declarative test YAML or setup programmatically
# ... run test ...
# Verify artifact was modified/created
artifacts = await test_artifact_service_instance.list_artifact_keys(
app_name="TestAgent",
user_id="user@example.com",
session_id="session_id"
)
assert "output.txt" in artifacts
```
--------------------------------
### Install Dependencies
Source: https://github.com/solacelabs/solace-agent-mesh/blob/main/client/webui/frontend/README.md
Install all project dependencies using npm ci. This command ensures that the exact versions specified in the lock file are installed, which is recommended for CI environments and consistent development.
```bash
npm ci
```
--------------------------------
### Create a Sample Document
Source: https://github.com/solacelabs/solace-agent-mesh/blob/main/docs/docs/documentation/developing/tutorials/rag-integration.md
Example of creating a simple text file to be ingested by the RAG agent. This file contains information about Agent Mesh features.
```text
Agent Mesh is a powerful framework for building AI agents.
Key features of Agent Mesh include:
- A flexible plugin architecture.
- Integration with various LLMs and vector databases.
- Scalable gateways for different communication protocols.
- An event-driven design based on Solace event broker.
```
--------------------------------
### OpenAPI Specification Example
Source: https://github.com/solacelabs/solace-agent-mesh/blob/main/docs/docs/documentation/enterprise/openapi-tools.md
Example of an OpenAPI specification showing operation IDs.
```json
{
"paths": {
"/pet/{petId}": {
"get": {
"operationId": "getPetById",
"summary": "Find pet by ID"
}
}
}
}
```
--------------------------------
### Verify Agent Mesh Installation with Docker
Source: https://github.com/solacelabs/solace-agent-mesh/blob/main/docs/docs/documentation/installing-and-configuring/installation.md
Verify the Agent Mesh installation by running the --version command within a Docker container. This is useful for environments without a local Python installation.
```sh
docker run --rm solace/solace-agent-mesh:latest --version
```
--------------------------------
### Build a Plugin into a Python Wheel Package
Source: https://github.com/solacelabs/solace-agent-mesh/blob/main/docs/docs/documentation/components/plugins.md
This command builds the plugin into a Python wheel package, which can then be installed using package managers like pip. Ensure the 'build' package is installed (`pip install build`).
```bash
solace-agent-mesh plugin build
```
--------------------------------
### Feedback Event Payload Examples
Source: https://github.com/solacelabs/solace-agent-mesh/blob/main/docs/docs/documentation/installing-and-configuring/user-feedback.md
Examples of feedback event payloads when publishing feedback events.
```APIDOC
## Publishing Feedback Events
When feedback publishing is enabled, the system publishes feedback events to the configured Solace topic. The payload structure varies based on the `include_task_info` setting.
### Event Payload Examples
**Mode: `none`**
```json
{
"feedback": {
"task_id": "task-abc123",
"session_id": "web-session-xyz",
"feedback_type": "up",
"feedback_text": "Great response!",
"user_id": "user123"
}
}
```
**Mode: `summary`**
```json
{
"feedback": {
"task_id": "task-abc123",
"session_id": "web-session-xyz",
"feedback_type": "up",
"feedback_text": "Great response!",
"user_id": "user123"
},
"task_summary": {
"id": "task-abc123",
"user_id": "user123",
"start_time": 1730217600000,
"end_time": 1730217650000,
"status": "completed",
"initial_request_text": "Help me analyze this data"
}
}
```
**Mode: `stim`**
```json
{
"feedback": {
"task_id": "task-abc123",
"session_id": "web-session-xyz",
"feedback_type": "up",
"feedback_text": "Great response!",
"user_id": "user123"
},
"task_stim_data": {
"invocation_details": {
"log_file_version": "2.0",
"task_id": "task-abc123",
"user_id": "user123",
"start_time": 1730217600000,
"end_time": 1730217650000,
"status": "completed",
"initial_request_text": "Help me analyze this data"
},
"invocation_flow": [
{
"id": "event-1",
"created_time": 1730217600000,
"topic": "namespace/agent/request",
"direction": "request",
"payload": { "message": "..." }
},
{
"id": "event-2",
"created_time": 1730217625000,
"topic": "namespace/agent/response",
"direction": "response",
"payload": { "result": "..." }
}
]
}
}
```
```
--------------------------------
### Initialize a New SAM Project
Source: https://context7.com/solacelabs/solace-agent-mesh/llms.txt
Use `sam init` to interactively scaffold a new SAM project. This command guides you through configuring the Solace broker connection, database persistence, orchestrator agent, platform services, and Web UI gateway.
```bash
sam init
```
```bash
sam --version
```
--------------------------------
### Run a SAM Application
Source: https://context7.com/solacelabs/solace-agent-mesh/llms.txt
Execute `sam run` to start the SAM runtime, launching all configured components. Use the `--suppress-warnings` flag to hide Python warnings during startup.
```bash
sam run
```
```bash
sam --suppress-warnings run
```
--------------------------------
### Example MongoDB Document Structure
Source: https://github.com/solacelabs/solace-agent-mesh/blob/main/docs/docs/documentation/developing/tutorials/mongodb-integration.md
An example document structure for a coffee shop database collection.
```json
{
"_id": "64a1b2c3d4e5f6789012345",
"order_id": "ORD-2024-001",
"customer": {
"name": "John Doe",
"email": "john.doe@example.com",
"phone": "+1-555-0123"
},
"items": [
{
"product": "Espresso",
"quantity": 2,
"price": 3.50,
"category": "Coffee"
},
{
"product": "Croissant",
"quantity": 1,
"price": 2.75,
"category": "Pastry"
}
],
"total_amount": 9.75,
"order_date": "2024-01-15T10:30:00Z",
"status": "completed",
"payment_method": "credit_card",
"location": "Downtown Store"
}
```
--------------------------------
### OAuth2/OIDC Authentication Example
Source: https://github.com/solacelabs/solace-agent-mesh/blob/main/docs/docs/documentation/enterprise/openapi-tools.md
Example of OpenAPI tool configuration using OAuth2/OIDC authentication with client credentials.
```yaml
tools:
- tool_type: openapi
specification_url: "https://api.example.com/openapi.json"
base_url: "https://api.example.com"
auth:
type: oauth2
authorization_url: "https://api.example.com/oauth/authorize"
token_url: "https://api.example.com/oauth/token"
scopes:
- "employees:read"
- "employees:write"
- "departments:read"
token_endpoint_auth_method: "client_secret_post"
client_id: ${OAUTH_CLIENT_ID}
client_secret: ${OAUTH_CLIENT_SECRET}
```
--------------------------------
### Bearer Token Authentication Example
Source: https://github.com/solacelabs/solace-agent-mesh/blob/main/docs/docs/documentation/enterprise/openapi-tools.md
Example of OpenAPI tool configuration using bearer token authentication.
```yaml
tools:
- tool_type: openapi
specification_url: "https://api.example.com/openapi.json"
base_url: "https://api.example.com"
auth:
type: bearer
token: ${API_BEARER_TOKEN}
```
--------------------------------
### View Agent CLI Help
Source: https://github.com/solacelabs/solace-agent-mesh/blob/main/docs/docs/documentation/developing/create-agents.md
Access the help documentation for the Agent Mesh CLI to see all available options for customizing agent creation.
```bash
sam add agent --help
```
--------------------------------
### Create Agent Plugin
Source: https://github.com/solacelabs/solace-agent-mesh/blob/main/docs/docs/documentation/developing/create-agents.md
Use the 'sam plugin create' command to initialize a new agent plugin. Follow the prompts to set up the directory structure and configuration files.
```bash
sam plugin create my-hello-agent --type agent
```
--------------------------------
### Configure Built-in Tools
Source: https://github.com/solacelabs/solace-agent-mesh/blob/main/docs/docs/documentation/components/builtin-tools/builtin-tools.md
Example of an app_config YAML file demonstrating how to enable a mix of tool groups and individual built-in tools using the unified configuration method. This configuration allows for flexible agent capabilities by enabling predefined tool sets or specific tools.
```yaml
# In your agent's YAML file:
app_config:
namespace: "myorg/dev"
agent_name: "DataAndWebAgent"
model: "gemini-1.5-pro"
instruction: "You are an agent that can analyze data and browse the web."
# --- Unified Tool Configuration ---
tools:
# Enable a group of tools
- tool_type: builtin-group
group_name: "data_analysis"
# Enable another group
- tool_type: builtin-group
group_name: "artifact_management"
# Enable a single, specific tool
- tool_type: builtin
tool_name: "web_request"
# ... other service configurations (session_service, artifact_service, etc.)
```
--------------------------------
### Prepare Document Directory and Move File
Source: https://github.com/solacelabs/solace-agent-mesh/blob/main/docs/docs/documentation/developing/tutorials/rag-integration.md
Commands to create the document directory if it doesn't exist and move the sample document into it for the agent to scan.
```sh
mkdir -p my_documents
mv sam_features.txt my_documents/
```
--------------------------------
### Initialize Hello World Agent
Source: https://github.com/solacelabs/solace-agent-mesh/blob/main/docs/docs/documentation/developing/create-agents.md
Implement the initialization logic for your agent. This function receives validated configuration and the host component, allowing you to set up shared resources and initial agent state.
```python
from typing import Any, Dict
from pydantic import BaseModel, Field
from solace_ai_connector.common.log import log
class HelloAgentInitConfig(BaseModel):
"""
Configuration model for the Hello Agent initialization.
"""
startup_message: str = Field(description="Message to log on startup")
log_level: str = Field(default="INFO", description="Logging level for the agent")
def initialize_hello_agent(host_component: Any, init_config: HelloAgentInitConfig):
"""
Initializes the Hello World agent.
Args:
host_component: The agent host component
init_config: Validated initialization configuration
"""
log_identifier = f"[{host_component.agent_name}:init]"
log.info(f"{log_identifier} Starting Hello Agent initialization...")
# Log the startup message from config
log.info(f"{log_identifier} {init_config.startup_message}")
# You could initialize shared resources here, such as:
# - Database connections
# - API clients
# - Caches or shared data structures
# Store any shared state in the agent
host_component.set_agent_specific_state("initialized_at", "2024-01-01T00:00:00Z")
host_component.set_agent_specific_state("greeting_count", 0)
log.info(f"{log_identifier} Hello Agent initialization completed successfully")
```
--------------------------------
### Install Dependencies
Source: https://github.com/solacelabs/solace-agent-mesh/blob/main/tests/integration/migrations/README.md
Install necessary Python packages for running migration tests, including pytest and testcontainers with PostgreSQL and MySQL support.
```bash
pip install pytest testcontainers[postgres] testcontainers[mysql] pymysql psycopg2-binary
```
--------------------------------
### Verify Python and PIP Installation
Source: https://github.com/solacelabs/solace-agent-mesh/blob/main/docs/docs/documentation/vibe_coding.md
Check if Python and PIP package manager are installed and configured correctly by running their help commands.
```bash
python --help
```
```bash
pip --help
```
--------------------------------
### Setup Artifacts for Tests
Source: https://github.com/solacelabs/solace-agent-mesh/blob/main/tests/integration/scenarios_declarative/DECLARATIVE_TEST_GUIDE.md
Define files to be created before test execution. Supports plain text and base64 encoded binary content with metadata.
```yaml
setup_artifacts:
- filename: "input.txt"
mime_type: "text/plain"
content: "Text content here"
metadata:
description: "Input file for testing"
source: "test_setup"
- filename: "binary.png"
mime_type: "image/png"
content_base64: "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII="
metadata:
description: "Binary image file"
size_bytes: 68
# For proxy tests, specify app_name explicitly
- filename: "proxy_artifact.txt"
app_name: "TargetAgentName"
content: "Content for specific agent"
```
--------------------------------
### Install Agent Mesh Enterprise with pip
Source: https://github.com/solacelabs/solace-agent-mesh/blob/main/docs/docs/documentation/enterprise/wheel-installation.md
Use this command to install the Agent Mesh Enterprise wheel file using pip.
```bash
pip install solace_agent_mesh_enterprise--py3-none-any.whl
```
--------------------------------
### Install Project with Test Dependencies
Source: https://github.com/solacelabs/solace-agent-mesh/blob/main/README.md
Install the project in editable mode, including the 'test' extra dependencies, before running Pytest directly.
```bash
pip install -e .[test]
```
--------------------------------
### Manage SAM Plugins
Source: https://context7.com/solacelabs/solace-agent-mesh/llms.txt
The `sam plugin` command suite allows for managing plugins. Use `catalog` to list available plugins, `install` to add one, `create` to scaffold a new plugin, `build` to package it, and `add` to integrate its agents into your project.
```bash
sam plugin catalog
```
```bash
sam plugin install my-plugin
```
```bash
sam plugin create my-plugin
```
```bash
sam plugin build
```
```bash
sam plugin add
```
--------------------------------
### Build Solace Agent Mesh Documentation Pages
Source: https://github.com/solacelabs/solace-agent-mesh/blob/main/docs/README.md
Navigate to the docs directory, install dependencies, and run the build script for documentation pages.
```sh
cd docs
npm ci
npm run build
```
--------------------------------
### Start Teams Gateway with Docker Compose
Source: https://github.com/solacelabs/solace-agent-mesh/blob/main/docs/docs/documentation/developing/tutorials/teams-integration.md
Use this command to start the gateway in detached mode after setting up your .env file and docker-compose.yaml.
```bash
docker compose up -d
```
--------------------------------
### Run Specific Configuration Files
Source: https://github.com/solacelabs/solace-agent-mesh/blob/main/docs/docs/documentation/components/cli.md
This example shows how to run the Agent Mesh application by specifying individual YAML configuration files.
```sh
solace-agent-mesh run configs/agent1.yaml configs/gateway.yaml
```
--------------------------------
### Install Browser Dependencies for Mermaid Agent
Source: https://github.com/solacelabs/solace-agent-mesh/blob/main/docs/docs/documentation/installing-and-configuring/installation.md
Install browser dependencies required by the Mermaid agent for rendering diagrams. This is necessary if you are not using the Docker image.
```sh
playwright install
```