### Complete Webhook Gateway Integration Example with FastAPI

Source: https://github.com/solacelabs/solace-agent-mesh-core-plugins/blob/main/sam-webhook-gateway/src/sam_webhook_gateway/webhook_llm.txt

Presents a full integration example of the webhook gateway using FastAPI. It includes the necessary imports, defines the configuration for the webhook server and endpoints, creates a `WebhookGatewayApp` instance, and indicates that the FastAPI server is automatically started by the component, with the FastAPI app instance available for further customization.

```python
from gateway.webhook.app import WebhookGatewayApp
from gateway.webhook.main import app
import uvicorn

# Complete setup and run
config = {
    "webhook_server_host": "0.0.0.0",
    "webhook_server_port": 8080,
    "webhook_endpoints": [
        {
            "path": "/hooks/process",
            "method": "POST",
            "target_agent_name": "processor_agent",
            "input_template": "Process: {{payload}}",
            "auth": {"type": "none"},
            "payload_format": "json"
        }
    ]
}

# Create app instance
app_info = {"name": "webhook_gateway", "config": config}
webhook_app = WebhookGatewayApp(app_info)

# The FastAPI server is automatically started by the component
# Access the FastAPI app instance for additional customization if needed
fastapi_instance = app
```

--------------------------------

### Forward Context Configuration Example

Source: https://github.com/solacelabs/solace-agent-mesh-core-plugins/blob/main/sam-event-mesh-gateway/README.md

Example YAML configuration for forwarding context data from incoming messages to outgoing responses. It demonstrates extracting correlation ID and original topic using SAC expressions.

```yaml
forward_context:
  correlation_id: "input.user_properties:correlation_id"
  original_topic: "input.topic:"
```

--------------------------------

### YAML - Complete Audit Metadata Configuration Example

Source: https://github.com/solacelabs/solace-agent-mesh-core-plugins/blob/main/sam-nuclia-tool/docs/nuclia_rag_tool_user_guide.md

A comprehensive YAML example demonstrating the configuration of audit metadata, including multiple template parameters for filtering and logging, and a detailed mapping of static, dynamic, and combined fields.

```yaml
template_parameters:
  # Existing parameters for filtering/rephrasing
  - name: "region"
    description: "User region"
    type: "string"
    default: ""
  
  - name: "policy_type"
    description: "Document category or policy type"
    type: "string"
    default: ""
  
  # Audit-specific parameters
  - name: "user_email"
    description: "User's email address for audit logging"
    type: "string"
    required: false
    default: ""
  
  - name: "session_id"
    description: "Session ID for audit logging"
    type: "string"
    required: false
    default: ""
  
  - name: "user_department"
    description: "User's department for audit logging"
    type: "string"
    required: false
    default: ""

audit_metadata:
  enabled: true
  fields:
    # Static fields
    environment: "production"
    agent_name: "document_agent"
    agent_version: "1.0.0"
    
    # Dynamic fields from parameters
    user_email: "{user_email}"
    user_region: "{region}"
    user_policy_type: "{policy_type}"
    user_department: "{user_department}"
    session_id: "{session_id}"
    
    # Query information
    query_text: "{query}"
    
    # Combined fields
    user_context: "{user_email} from {region}"

```

--------------------------------

### Basic Usage of Nuclia RAG Tool in Agent Instructions (Markdown)

Source: https://github.com/solacelabs/solace-agent-mesh-core-plugins/blob/main/sam-nuclia-tool/docs/nuclia_rag_tool_user_guide.md

This example demonstrates how to integrate the Nuclia RAG Tool into agent instructions. It outlines the steps for passing user queries to the tool and presenting the generated artifact content to the user.

```markdown
When the user asks a question, use the `NucliaRagTool` tool:
1. Pass the user's query to the `query` parameter
2. The tool will return a `response_artifact`
3. Present the answer using an artifact embed:
   «artifact_content:{{response_artifact.filename}}:{{response_artifact.version}}»
```

--------------------------------

### Complete Nuclia RAG Tool Configuration Example (YAML)

Source: https://github.com/solacelabs/solace-agent-mesh-core-plugins/blob/main/sam-nuclia-tool/docs/nuclia_rag_tool_user_guide.md

A comprehensive configuration for the Nuclia RAG Tool, including all required connection parameters and optional settings for performance, artifact customization, and advanced features. This example uses environment variables for sensitive information.

```yaml
tools:
  - tool_type: python
    component_module: sam_nuclia_tool.nuclia_rag_tool
    class_name: NucliaRagTool
    tool_config:
      tool_name: NucliaRagTool # Optional, required if using multiple instance of the tool in the same agent
      # Connection
      base_url: "${NUCLIA_BASE_URL}"
      kb_id: "${NUCLIA_KB_ID}"
      token: "${NUCLIA_TOKEN}"
      api_key: "${NUCLIA_API_KEY}"
      
      # Performance
      top_k: 10
      
      # Artifact settings
      output_filename_base: "document_answer"
      artifact_description_query_max_length: 200
      inline_citation_links: true
      
      # Advanced features (covered in later sections)
      template_parameters: []
      prompt_rephrasing: null
      filter_expression_template: null
```

--------------------------------

### Install SAM Event Mesh Gateway Plugin

Source: https://github.com/solacelabs/solace-agent-mesh-core-plugins/blob/main/sam-event-mesh-gateway/README.md

Command to install the SAM Event Mesh Gateway plugin into a SAM project. This command creates a new component configuration file in the specified directory.

```bash
solace-agent-mesh plugin add <your-new-component-name> --plugin sam-event-mesh-gateway
```

--------------------------------

### Setup FastAPI App with Middleware and Exception Handling (Python)

Source: https://github.com/solacelabs/solace-agent-mesh-core-plugins/blob/main/sam-webhook-gateway/src/sam_webhook_gateway/webhook_llm.txt

This snippet illustrates the setup of a FastAPI application instance. It includes the integration of middleware and defines handlers for various exception types, such as HTTPExceptions, validation errors, and generic exceptions, to ensure robust error management. Dependencies are configured using `setup_dependencies`.

```Python
from gateway.webhook.main import app, setup_dependencies
from fastapi import FastAPI
from gateway.webhook.component import WebhookGatewayComponent

# FastAPI application instance
app: FastAPI

# Configures middleware and component reference
def setup_dependencies(component: WebhookGatewayComponent):
    pass

# Basic health endpoint handler
def health_check():
    pass

# Handles HTTPExceptions
def http_exception_handler(request, exc):
    pass

# Handles validation errors
def validation_exception_handler(request, exc):
    pass

# Handles unexpected exceptions
def generic_exception_handler(request, exc):
    pass

```

--------------------------------

### Response Format Example (JSON)

Source: https://github.com/solacelabs/solace-agent-mesh-core-plugins/blob/main/sam-ruleset-lookup-tool/docs/ruleset_lookup_tool_usage.md

Shows the expected JSON output format when a ruleset is retrieved. The response includes the decision logic and description for the matched ruleset.

```json
{
  "decision_logic": "Ruleset Name: Leave Policy\nDescription: Annual leave calculation rules\nLogic:\nIF employment_years >= 5:\n  RETURN 25 + (employment_years - 5) * 0.5 days (max 30)\nELSE:\n  RETURN 20 + employment_years days\n\n---\n\n..."
}

```

--------------------------------

### Basic Configuration Setup for Webhook Gateway App (Python)

Source: https://github.com/solacelabs/solace-agent-mesh-core-plugins/blob/main/sam-webhook-gateway/src/sam_webhook_gateway/webhook_llm.txt

This code demonstrates how to set up a basic `WebhookGatewayApp` instance with a sample configuration. It defines essential parameters like the application module, server host and port, CORS origins, system purpose, response format, and a list of webhook endpoints. This provides a foundational setup for processing external webhook data.

```Python
from gateway.webhook.app import WebhookGatewayApp

# Example webhook gateway configuration
webhook_config = {
    "app_module": "gateway.webhook.app",
    "webhook_server_host": "0.0.0.0",
    "webhook_server_port": 8080,
    "cors_allowed_origins": ["*"],
    "system_purpose": "Process external webhook data for AI analysis",
    "response_format": "JSON with structured results",
    "webhook_endpoints": [
        {
            "path": "/hooks/data-feed",
            "method": "POST",
            "target_agent_name": "data_processor_agent",
            "input_template": "Process this data: {{payload}}",
            "auth": {"type": "none"},
            "payload_format": "json"
        }
    ]
}

# Create the app
app_info = {"name": "my_webhook_gateway", "config": webhook_config}
webhook_app = WebhookGatewayApp(app_info)

```

--------------------------------

### Install Slack Gateway Adapter Plugin

Source: https://github.com/solacelabs/solace-agent-mesh-core-plugins/blob/main/sam-slack-gateway-adapter/README.md

Command to add the Slack Gateway Adapter plugin to your Solace Agent Mesh deployment. This command installs the plugin and creates a corresponding configuration file.

```bash
sam plugin add <your-new-component-name> --plugin sam-slack-gateway-adapter
```

--------------------------------

### ADK Agent Instruction Prompt Configuration (YAML)

Source: https://github.com/solacelabs/solace-agent-mesh-core-plugins/blob/main/sam-sql-database/README.md

Defines the system prompt for the ADK-compatible LLM, guiding its behavior in translating natural language to SQL. This prompt is dynamically augmented with database schema and query examples.

```yaml
instruction: |
  You are an expert SQL assistant for the connected database.
  The database schema and query examples will be provided to you.
  Your primary goal is to translate user questions into accurate SQL queries.
  If a user asks to query the database, generate the SQL and call the 'execute_sql_query' tool.
  If the 'execute_sql_query' tool returns an error, analyze the error message and the original SQL,
  then try to correct the SQL query and call the tool again.
  If the results are large and the tool indicates they were saved as an artifact, inform the user about the artifact.
  Always use the 'execute_sql_query' tool to interact with the database.
```

--------------------------------

### LLM Tool Call Example - JSON

Source: https://github.com/solacelabs/solace-agent-mesh-core-plugins/blob/main/sam-nuclia-tool/docs/nuclia_rag_tool_user_guide.md

An example JSON object representing a tool call made by an LLM, including the user's query and values for template parameters like region and department.

```json
{
  "query": "What is the document policy?",
  "region": "emea",
  "department": "your-department"
}
```

--------------------------------

### Dynamic Tool Naming Example (Text)

Source: https://github.com/solacelabs/solace-agent-mesh-core-plugins/blob/main/sam-ruleset-lookup-tool/docs/ruleset_lookup_tool_usage.md

Illustrates how the tool generates its function name based on a sanitized version of the 'name' property defined in the configuration. This ensures consistent and predictable function naming for accessing rulesets.

```text
The tool generates its function name as: `get_rulesets_{sanitized_name}`

For example:
- `name: "hr_policies"` → `get_rulesets_hr_policies`
- `name: "Compliance Rules"` → `get_rulesets_compliance_rules`

```

--------------------------------

### Incoming JSON Payload Example

Source: https://github.com/solacelabs/solace-agent-mesh-core-plugins/blob/main/sam-event-mesh-gateway/README.md

Example of an incoming JSON payload that the Solace Agent Mesh handler will process. It includes a 'caseId' and a 'documents' array, where each document object contains 'docName', 'docContent', 'docType', and 'encoding'.

```json
{
  "caseId": "C-12345",
  "documents": [
    { "docName": "claim_form.pdf", "docContent": "JVBERi...", "docType": "application/pdf", "encoding": "base64" },
    { "docName": "notes.txt", "docContent": "This is a note.", "docType": "text/plain", "encoding": "text" }
  ]
}
```

--------------------------------

### HR Policy Agent Configuration Example (YAML)

Source: https://github.com/solacelabs/solace-agent-mesh-core-plugins/blob/main/sam-ruleset-lookup-tool/docs/ruleset_lookup_tool_usage.md

An example of an agent configuration using the RulesetLookupTool for HR policies. It demonstrates how to embed the decision data directly within the agent configuration, specifying input parameters and decision tree groups for a 'Leave Policy'.

```yaml
# Agent configuration
tools:
  - tool_type: python
    component_module: sam_ruleset_lookup_tool.ruleset_lookup_tool
    component_base_path: .
    tool_config:
      decision_data: 
        name: "hr_policies"
        description: "HR policy rulesets for employee questions"
        grouping_parameter: "country"
        input_parameters:
          - name: "country"
            type: "string"
            required: true
            description: "Employee's country"
        decision_tree_groups:
          netherlands:
            decision_trees:
              - name: "Leave Policy"
                description: "Annual leave calculation rules"
                decision_logic: |
                  IF employment_years >= 5:
                    RETURN 25 + (employment_years - 5) * 0.5 days (max 30)
                  ELSE:
                    RETURN 20 + employment_years days
      include_topics_in_description: true
      include_groups_in_description: true
```

--------------------------------

### Install Solace Agent Mesh Plugins

Source: https://context7.com/solacelabs/solace-agent-mesh-core-plugins/llms.txt

Generic command to add plugins to a Solace Agent Mesh project. Examples show adding the REST gateway and MongoDB plugins.

```bash
# Generic plugin installation command
solace-agent-mesh plugin add <your-component-name> --plugin <plugin-name>

# Example: Add the REST gateway plugin
solace-agent-mesh plugin add my-api-gateway --plugin sam-rest-gateway

# Example: Add the MongoDB plugin
solace-agent-mesh plugin add mongo-agent --plugin sam-mongodb
```

--------------------------------

### MongoDB Agent Query Examples

Source: https://context7.com/solacelabs/solace-agent-mesh-core-plugins/llms.txt

Illustrates natural language queries and their corresponding MongoDB aggregation pipelines generated by the MongoDB Agent. These examples demonstrate the agent's ability to translate user requests into complex database operations.

```python
# Example queries the agent can handle:

# "Show me the top 5 products by sales"
# Generates: db.products.aggregate([
#   {"#sort": {"sales": -1}},
#   {"#limit": 5}
# ])

# "Find all products out of stock in the electronics category"
# Generates: db.products.aggregate([
#   {"#match": {"category": "electronics", "stock": 0}},
#   {"#project": {"name": 1, "price": 1, "category": 1}}
# ])

# "Calculate average price by category"
# Generates: db.products.aggregate([
#   {"#group": {"_id": "$category", "avgPrice": {"$avg": "$price"}}},
#   {"#sort": {"avgPrice": -1}}
# ])

```

--------------------------------

### Install New Agent Component using SAM CLI (Bash)

Source: https://github.com/solacelabs/solace-agent-mesh-core-plugins/blob/main/sam-event-mesh-agent/README.md

This bash command installs a new agent component using the SAM CLI. It specifies the plugin name and the plugin repository. After execution, a new component configuration file will be created in the specified directory.

```bash
sam plugin add <your-new-component-name> --plugin sam-event-mesh-agent
```

--------------------------------

### SAM REST Gateway Configuration Example

Source: https://github.com/solacelabs/solace-agent-mesh-core-plugins/blob/main/sam-rest-gateway/README.md

An example YAML configuration for the Solace Agent Mesh REST Gateway application within the main SAM Host YAML file. It includes settings for namespace, gateway ID, artifact service, identity service, server host/port, and authentication.

```yaml
- name: my_rest_gateway_app
  app_module: solace_agent_mesh.gateway.rest.app
  app_base_path: src
  broker:
    # Standard A2A Control Plane broker connection details
    <<: *broker_connection
  app_config:
    # --- Base Gateway Config ---
    namespace: "my-org/dev"
    gateway_id: "rest-gw-01"
    artifact_service:
      type: "filesystem"
      base_path: "/tmp/sam_artifacts"
    identity_service:
      type: "local_file"
      file_path: "config/users.json"

    # --- REST Gateway Specific Config ---
    rest_api_server_host: "0.0.0.0"
    rest_api_server_port: 8080
    sync_mode_timeout_seconds: 60 # Timeout for the v1 synchronous API

    # --- Authentication Config ---
    enforce_authentication: true
    external_auth_service_url: "http://my-auth-server:8080"
```

--------------------------------

### Processing Raw Binary Payload into Artifact (YAML)

Source: https://github.com/solacelabs/solace-agent-mesh-core-plugins/blob/main/sam-event-mesh-gateway/README.md

This example configures an event handler to process raw binary payloads, such as images from an IoT device. It defines artifact processing to save the payload as a JPEG file and then instructs an agent to analyze it.

```yaml
# In your event_handlers list:
- name: "iot_image_handler"
  subscriptions:
    - topic: "iot/camera/+/image"
  payload_format: "binary" # Treat payload as raw bytes
  # --- Artifact Processing Block ---
  artifact_processing:
    extract_artifacts_expression: "input.payload" # The item to process is the raw payload
    artifact_definition:
      filename: "template:iot-image-{{text://input.user_properties:deviceId}}-{{text://input.user_properties:timestamp}}.jpg"
      content: "list_item:" # The content is the item itself (the raw payload)
      mime_type: "static:image/jpeg"
      content_encoding: "static:binary" # Explicitly state the content is raw bytes
  # --- Main Prompt ---
  input_expression: "template:Analyze the attached security camera image for anomalies. The device ID is {{text://input.user_properties:deviceId}}."
  target_agent_name: "ImageAnalysisAgent"
```

--------------------------------

### Webhook Endpoint Payload Format Examples (Python)

Source: https://github.com/solacelabs/solace-agent-mesh-core-plugins/blob/main/sam-webhook-gateway/src/sam_webhook_gateway/webhook_llm.txt

This code provides examples of webhook endpoint configurations focusing on different payload formats. It includes a JSON payload endpoint for structured data processing and a binary endpoint for file uploads, demonstrating how to specify payload formats, save payloads as artifacts, and override MIME types.

```Python
# JSON payload endpoint
json_endpoint = {
    "path": "/hooks/json-data",
    "target_agent_name": "json_processor",
    "input_template": "Analyze this JSON data: {{payload.data_field}}",
    "payload_format": "json"
}

# Binary file endpoint with artifact storage
binary_endpoint = {
    "path": "/hooks/binary-upload", 
    "target_agent_name": "binary_processor",
    "input_template": "Process binary file: {{user_data:binary_payload_artifact_uri}}",
    "payload_format": "binary",
    "save_payload_as_artifact": True,
    "artifact_filename_template": "binary_{{timestamp}}.dat",
    "artifact_mime_type_override": "application/octet-stream"
}

```

--------------------------------

### Plugin Installation

Source: https://context7.com/solacelabs/solace-agent-mesh-core-plugins/llms.txt

Commands to add plugins to your Solace Agent Mesh project.

```APIDOC
## Plugin Installation

Install any plugin into your Solace Agent Mesh project

```bash
# Generic plugin installation command
solace-agent-mesh plugin add <your-component-name> --plugin <plugin-name>

# Example: Add the REST gateway plugin
solace-agent-mesh plugin add my-api-gateway --plugin sam-rest-gateway

# Example: Add the MongoDB plugin
solace-agent-mesh plugin add mongo-agent --plugin sam-mongodb
```
```

--------------------------------

### Invoke Bedrock Agent Runtime

Source: https://github.com/solacelabs/solace-agent-mesh-core-plugins/blob/main/sam-bedrock-agent/src/sam_bedrock_agent/sam_bedrock_agent_llm.txt

Shows how to use the BedrockAgentRuntime wrapper class to simplify interactions with Amazon Bedrock Agents and Flows. This example demonstrates basic setup with AWS configuration and is a precursor to invoking agent or flow methods.

```python
from sam_bedrock_agent.bedrock_agent_runtime import BedrockAgentRuntime
import uuid

# Define your AWS configuration.
aws_config = {
    "boto3_config": {
        "region_name": "us-east-1",
    }
}

# Note: The BedrockAgentRuntime class internally uses AWSSessionManager.
# Initialization of AWSSessionManager (if not already done) will occur
# when BedrockAgentRuntime is instantiated or when its methods are called.

# Example of instantiating the wrapper (actual invocation methods would follow)
try:
    bedrock_runtime = BedrockAgentRuntime(
        boto3_config=aws_config["boto3_config"],
        endpoint_url="https://bedrock-agent-runtime.us-east-1.amazonaws.com" # Optional, ensure it matches region
    )
    print("BedrockAgentRuntime initialized successfully.")

    # Placeholder for actual invocation:
    # response = bedrock_runtime.invoke_agent(
    #     agent_id="YOUR_AGENT_ID",
    #     agent_alias_id="YOUR_AGENT_ALIAS_ID",
    #     session_id=str(uuid.uuid4()),
    #     prompt="What is the weather today?"
    # )
    # print(f"Agent response: {response}")

except Exception as e:
    print(f"An error occurred during BedrockAgentRuntime initialization or setup: {e}")

```

--------------------------------

### Example Response with Missing Filter Parameters - JSON

Source: https://github.com/solacelabs/solace-agent-mesh-core-plugins/blob/main/sam-nuclia-tool/docs/nuclia_rag_tool_user_guide.md

An example JSON response indicating that a search was performed but filtering was not applied due to missing or empty required parameters, listing the parameters that were missing.

```json
{
  "status": "success",
  "nuclia_learning_id": "abc123-def456-ghi789",
  "filter_applied": false,
  "missing_filter_parameters": ["region", "policy_type"],
  "message_to_llm": "Answer generated successfully. Note: Filtering was not applied because the following required parameters were missing or empty: region, policy_type"
}
```

--------------------------------

### FastAPI Setup for Webhook Gateway Dependencies

Source: https://github.com/solacelabs/solace-agent-mesh-core-plugins/blob/main/sam-webhook-gateway/src/sam_webhook_gateway/webhook_llm.txt

Demonstrates how to set up dependencies for the webhook gateway using FastAPI. It imports necessary components, initializes the `WebhookGatewayComponent`, sets up the dependencies, and notes that the FastAPI app is now configured with CORS, component dependencies, exception handlers, and a health check endpoint.

```python
from gateway.webhook.main import app, setup_dependencies
from gateway.webhook.dependencies import set_component_instance
from gateway.webhook.component import WebhookGatewayComponent

# Initialize component
component = WebhookGatewayComponent(**component_config)

# Setup FastAPI dependencies
setup_dependencies(component)

# Now the FastAPI app is ready with:
# - CORS middleware configured
# - Component dependencies available
# - Exception handlers registered
# - Health check endpoint at /health
```

--------------------------------

### Run Tests (Bash)

Source: https://github.com/solacelabs/solace-agent-mesh-core-plugins/blob/main/sam-slack-gateway-adapter/README.md

This command executes the test suite for the project using the 'hatch' build tool. Ensure 'hatch' is installed and configured for the project.

```bash
hatch test
```

--------------------------------

### Build Package (Bash)

Source: https://github.com/solacelabs/solace-agent-mesh-core-plugins/blob/main/sam-slack-gateway-adapter/README.md

This command builds the project package using the 'hatch' build tool. The resulting package can be used for distribution or deployment.

```bash
hatch build
```

--------------------------------

### Artifact Processing Configuration Example

Source: https://github.com/solacelabs/solace-agent-mesh-core-plugins/blob/main/sam-event-mesh-gateway/README.md

Example YAML configuration for the artifact processing block within an event handler. It specifies how to extract artifacts from incoming messages, including filename, content, and MIME type using SAC expressions.

```yaml
artifact_processing:
  extract_artifacts_expression: "input.payload:files"
  artifact_definition:
    filename: "list_item:filename"
    content: "list_item:content"
    mime_type: "list_item:mime_type"
    content_encoding: "list_item:encoding"
```

--------------------------------

### Initialize SQL Agent Configuration

Source: https://github.com/solacelabs/solace-agent-mesh-core-plugins/blob/main/sam-sql-database/README.md

Defines the configuration for initializing the SQL database agent. This includes specifying the database type, connection details, and schema handling. It supports PostgreSQL, MySQL, and SQLite, with options for query timeouts, data descriptions, and CSV imports. Sensitive information should be handled via environment variables.

```yaml
agent_init_function:
  module: "sam_sql_database.lifecycle" 
  name: "initialize_sql_agent"
  config:
    db_type: "${DB_TYPE}"
    db_host: "${DB_HOST}"
    db_port: ${DB_PORT}
    db_user: "${DB_USER}"
    db_password: "${DB_PASSWORD}"
    db_name: "${DB_NAME}"
    query_timeout: 30
    database_purpose: "Example: To store customer order and product information."
    data_description: "Example: Contains tables for customers, products, orders, and order_items. Timestamps are in UTC."
    auto_detect_schema: true
    database_schema_override: ""
    schema_summary_override: ""
    query_examples:
      - natural_language: "Show all customers from New York"
        sql_query: "SELECT * FROM customers WHERE city = 'New York';"
    csv_files: []
    csv_directories: []
    response_guidelines: "Please note: Data is updated daily."
```

--------------------------------

### YAML Configuration for Webhook Gateway

Source: https://github.com/solacelabs/solace-agent-mesh-core-plugins/blob/main/sam-webhook-gateway/src/sam_webhook_gateway/webhook_llm.txt

Provides an example of a YAML configuration file for setting up the webhook gateway component. It defines the component name, module, and configuration including server host, port, CORS origins, and webhook endpoints with their respective paths, methods, target agents, input templates, and authentication settings.

```yaml
# YAML configuration file example
components:
  - component_name: webhook_gateway
    component_module: gateway.webhook.app
    component_config:
      webhook_server_host: "0.0.0.0"
      webhook_server_port: 8080
      cors_allowed_origins: ["http://localhost:3000"]
      webhook_endpoints:
        - path: "/hooks/alerts"
          method: "POST"
          target_agent_name: "alert_processor"
          input_template: "Alert received: {{payload.message}}"
          auth:
            type: "token"
            token_config:
              location: "header"
              name: "Authorization"
              value: "${ALERT_TOKEN}"
```

--------------------------------

### Execute SQL Query Example

Source: https://context7.com/solacelabs/solace-agent-mesh-core-plugins/llms.txt

Demonstrates a user query and the corresponding SQL query generated and executed by the SQL Database Agent. This showcases how natural language is translated into executable SQL for database interaction.

```bash
# Query via SAM UI or any gateway
# User: "Show me all orders from the last 30 days with total value over $1000"

# Agent generates and executes:
# SELECT order_id, customer_name, order_date, SUM(amount) as total
# FROM orders
# WHERE order_date >= NOW() - INTERVAL '30 days'
# GROUP BY order_id, customer_name, order_date
# HAVING SUM(amount) > 1000
# ORDER BY order_date DESC;

# Result returned as formatted YAML/JSON, or saved as artifact if large

```

--------------------------------

### Poll for Task Results (cURL)

Source: https://context7.com/solacelabs/solace-agent-mesh-core-plugins/llms.txt

Example of polling for task results using cURL. This makes a GET request to a specific task ID endpoint and includes an Authorization header. The response indicates the task status and any results or artifacts.

```bash
# Poll for results
curl -X GET http://localhost:8080/api/v2/tasks/task-abc-123 \
  -H "Authorization: Bearer ${API_TOKEN}"

# Response when complete:
# {
#   "taskId": "task-abc-123",
#   "status": "completed",
#   "result": {
#     "text": "Q4 sales increased 15% year-over-year...",
#     "artifacts": [
#       {"filename": "report.pdf", "downloadUrl": "/api/v2/artifacts/abc123"}
#     ]
#   }
# }
```

--------------------------------

### Reference Shared Configuration in Application (YAML)

Source: https://github.com/solacelabs/solace-agent-mesh-core-plugins/blob/main/sam-rag/docs/configuration.md

Demonstrates how to reference shared configuration blocks (like broker connection details) within the application's configuration using YAML anchors and aliases for reusability.

```yaml
apps:
  - name: your-app-name
    app_module: solace_agent_mesh.agent.sac.app
    broker:
      <<: *broker_connection  # References the broker_connection anchor
    app_config:
      namespace: "${NAMESPACE}" # Your A2A topic namespace
      agent_name: "YourAgentName"
      display_name: "Your Agent Display Name"
      supports_streaming: true # RAG agent supports streaming responses
```

--------------------------------

### Using Forwarded Context in Output Handler (YAML)

Source: https://github.com/solacelabs/solace-agent-mesh-core-plugins/blob/main/sam-event-mesh-gateway/README.md

An example demonstrating how to use data from the original incoming message (forwarded context) within the `topic_expression` of an output handler. This allows for dynamic topic generation based on input message properties.

```yaml
topic_expression: "template:my_app/response/{{text://user_data.forward_context:correlation_id}}"
```

--------------------------------

### Full Solace Agent Mesh Gateway Configuration

Source: https://github.com/solacelabs/solace-agent-mesh-core-plugins/blob/main/sam-event-mesh-gateway/README.md

A comprehensive configuration example for a Solace Agent Mesh Gateway application. It includes settings for the application module, broker connection, artifact service, data plane connection, event handlers for processing incoming messages, and output handlers for publishing agent responses.

```yaml
- name: my_event_mesh_gateway_app
  app_module: sam_event_mesh_gateway.app
  app_base_path: plugins/sam-event-mesh-gateway/src
  broker: # A2A Control Plane Connection
    <<: *broker_connection # Using a YAML anchor for connection details
  app_config:
    namespace: "my-org/dev"
    gateway_id: "event-mesh-gw-01"
    artifact_service:
      type: "filesystem"
      base_path: "/tmp/sam_artifacts"
    
    # Data Plane Connection
    event_mesh_broker_config:
      broker_url: ${DATAPLANE_SOLACE_BROKER_URL}
      broker_vpn: ${DATAPLANE_SOLACE_BROKER_VPN}
      broker_username: ${DATAPLANE_SOLACE_BROKER_USERNAME}
      broker_password: ${DATAPLANE_SOLACE_BROKER_PASSWORD}

    # --- Event Handlers: Define how to process incoming messages ---
    event_handlers:
      - name: "process_json_order_handler"
        subscriptions:
          - topic: "acme/orders/json/>"
        input_expression: "template:Summarize this order and check for issues: {{json://input.payload}}"
        target_agent_name: "OrderProcessingAgent"
        on_success: "order_success_handler"
        on_error: "order_error_handler"
        forward_context:
          order_id: "json://input.payload:orderId"
          reply_topic: "input.user_properties:replyTo"

    # --- Output Handlers: Define how to publish agent responses ---
    output_handlers:
      - name: "order_success_handler"
        max_file_size_for_base64_bytes: 2097152 # 2MB
        topic_expression: "user_data.forward_context:reply_topic" # Use replyTo from original message
        payload_expression: "task_response:" # Send the whole simplified object as JSON

      - name: "order_error_handler"
        topic_expression: "template:acme/orders/error/{{text://user_data.forward_context:order_id}}"
        payload_expression: "task_response:a2a_task_response.error" # Send just the error details
        payload_format: "json"
```

--------------------------------

### Invoke Bedrock Agent with Files using sam_bedrock_agent

Source: https://github.com/solacelabs/solace-agent-mesh-core-plugins/blob/main/sam-bedrock-agent/src/sam_bedrock_agent/sam_bedrock_agent_llm.txt

This Python function, `invoke_bedrock_agent`, is designed for use within a framework, acting as a tool. It handles invoking a Bedrock Agent with optional file attachments. It enforces limits on file size and number, and supports specific file types. It requires a ToolContext and ToolConfig, which are mocked in the example for standalone demonstration.

```python
# Mock the ToolContext and its dependencies for the example
class MockToolContext:
    def __init__(self):
        self._invocation_context = MagicMock()
        self._invocation_context.app_name = "test_app"
        self._invocation_context.user_id = "test_user"
        self._invocation_context.session_id = "session_123"
        
        # Mock the artifact service to simulate file loading
        artifact_service = MagicMock()
        artifact_part = MagicMock()
        artifact_part.inline_data.data = b"This is the content of my test file."
        artifact_service.load_artifact = AsyncMock(return_value=artifact_part)
        self._invocation_context.artifact_service = artifact_service

# Define the tool configuration required by the function
tool_config = {
    "bedrock_agent_id": "YOUR_AGENT_ID",
    # ... other configurations
}

# Simplified standalone example usage (requires actual framework context for full functionality)
# result = await invoke_bedrock_agent(
#     input_text="Process this document.",
#     files=["my_document.txt"],
#     tool_context=MockToolContext(),
#     tool_config=tool_config
# )
# print(result)
```

--------------------------------

### Install SAM MongoDB Plugin

Source: https://github.com/solacelabs/solace-agent-mesh-core-plugins/blob/main/sam-mongodb/README.md

Command to install the sam-mongodb plugin for Solace Agent Mesh. This command adds the plugin and generates a new component configuration file.

```bash
sam plugin add <your-component-name> --plugin sam-mongodb
```

--------------------------------

### Install SAM Geographic Information Plugin

Source: https://github.com/solacelabs/solace-agent-mesh-core-plugins/blob/main/sam-geo-information/README.md

Command to install the SAM Geographic Information plugin. This command adds the plugin to your SAM project, creating a configuration file for it.

```bash
solace-agent-mesh plugin add <your-new-component-name> --plugin sam-geo-information
```

--------------------------------

### Install Event Mesh Tool Plugin

Source: https://github.com/solacelabs/solace-agent-mesh-core-plugins/blob/main/sam-event-mesh-tool/README.md

Command to install the Event Mesh Tool plugin for Solace Agent Mesh. This is a prerequisite for configuring and using the tool within an agent.

```bash
sam plugin install sam-event-mesh-tool
```

--------------------------------

### Accessing Webhook Gateway Component Programmatically (Python)

Source: https://github.com/solacelabs/solace-agent-mesh-core-plugins/blob/main/sam-webhook-gateway/src/sam_webhook_gateway/webhook_llm.txt

This example demonstrates how to obtain and use the `WebhookGatewayComponent` instance programmatically. After creating and configuring the `WebhookGatewayApp`, the component instance can be accessed via `webhook_app.component_instance`, allowing direct interaction with its methods and properties.

```Python
from gateway.webhook.component import WebhookGatewayComponent
from gateway.webhook.app import WebhookGatewayApp

# Placeholder for webhook_config from previous example
webhook_config = {
    "app_module": "gateway.webhook.app",
    "webhook_server_host": "0.0.0.0",
    "webhook_server_port": 8080,
    "cors_allowed_origins": ["*"],
    "system_purpose": "Process external webhook data for AI analysis",
    "response_format": "JSON with structured results",
    "webhook_endpoints": [
        {
            "path": "/hooks/data-feed",
            "method": "POST",
            "target_agent_name": "data_processor_agent",
            "input_template": "Process this data: {{payload}}",
            "auth": {"type": "none"},
            "payload_format": "json"
        }
    ]
}

# Create and configure the app
app_info = {"name": "my_webhook_gateway", "config": webhook_config}
webhook_app = WebhookGatewayApp(app_info)

# Access component methods through the app
component = webhook_app.component_instance

```