solace-agent-mesh 1.6.3__py3-none-any.whl → 1.7.1__py3-none-any.whl

solace_agent_mesh/assets/docs/search-doc-1761744323675.json

@@ -1 +0,0 @@
-{"searchDocs":[{"title":"Agents","type":0,"sectionRef":"#","url":"/solace-agent-mesh/docs/documentation/components/agents","content":"","keywords":"","version":"Next"},{"title":"Key Functions​","type":1,"pageTitle":"Agents","url":"/solace-agent-mesh/docs/documentation/components/agents#key-functions","content":" ADK Integration: Agents are built using the Google Agent Development Kit, providing advanced AI capabilities including tool usage, memory management, and artifact handling. AI-Enabled: Agents come packaged with access to large language models (LLMs) and can utilize various tools. Dynamic Discovery: New agents can self-register/deregister and be discovered dynamically through broadcast messages without requiring changes to the running system. Tool Ecosystem: Agents have access to built-in tools for artifact management, data analysis, web scraping, and peer-to-peer delegation. Session Management: Agents support conversation continuity through ADK's session management capabilities. Independence: Agents are modularized and can be updated or replaced independently of other components.  ","version":"Next","tagName":"h2"},{"title":"Agent Design​","type":1,"pageTitle":"Agents","url":"/solace-agent-mesh/docs/documentation/components/agents#agent-design","content":" Agents in Agent Mesh are built around the Solace AI Connector (SAC) component with ADK. Agent Mesh agents are complete self-contained units that can carry out specific tasks or provide domain-specific knowledge or capabilities. Each agent is defined by a YAML configuration file.  Each agent integrates with:  ADK Runtime: For AI model access, tool execution, and session managementA2A Protocol: For standardized agent-to-agent communicationTool Registry: Access to built-in and custom toolsArtifact Service: For file handling and management  For example, an agent configured with SQL database tools can execute queries, perform data analysis, and generate visualizations through the integrated tool ecosystem, all while maintaining conversation context through its session management.  ","version":"Next","tagName":"h2"},{"title":"The Agent Lifecycle​","type":1,"pageTitle":"Agents","url":"/solace-agent-mesh/docs/documentation/components/agents#the-agent-lifecycle","content":" Agents in Agent Mesh follow the A2A protocol lifecycle and interact with the agent registry:  Discovery: Agents start broadcasting discovery messages on startup to announce their availability and capabilities to the agent mesh. Active: The agent listens for A2A protocol messages on its designated topics and processes incoming tasks through the ADK runtime. Execution: The agent works on a task. They can also delegate tasks to other agents through the peer-to-peer A2A communication protocol. Cleanup: When shutting down, agents perform session cleanup and deregister from the agent mesh.  ","version":"Next","tagName":"h3"},{"title":"Potential Agent Examples​","type":1,"pageTitle":"Agents","url":"/solace-agent-mesh/docs/documentation/components/agents#potential-agent-examples","content":" RAG (Retrieval Augmented Generation) Agent: An agent that can retrieve information based on a natural language query using an embedding model and vector database, and then generate a response using a language model. External API Bridge: An agent that acts as a bridge to external APIs, retrieving information from third-party services such as weather APIs or product information databases. Internal System Lookup: An agent that performs lookups in internal systems, such as a ticket management system or a customer relationship management (CRM) database. Natural Language Processing Agent: An agent that can perform tasks like sentiment analysis, named entity recognition, or language translation.  ","version":"Next","tagName":"h3"},{"title":"Tool Ecosystem​","type":1,"pageTitle":"Agents","url":"/solace-agent-mesh/docs/documentation/components/agents#tool-ecosystem","content":" Agents perform tasks by using tools. A tool is a specific capability, like querying a database, calling an external API, or generating an image. The Agent Mesh framework provides a flexible and powerful tool ecosystem, allowing you to equip your agents with the right capabilities for any job.  There are three primary ways to add tools to an agent:  ","version":"Next","tagName":"h2"},{"title":"1. Built-in Tools​","type":1,"pageTitle":"Agents","url":"/solace-agent-mesh/docs/documentation/components/agents#1-built-in-tools","content":" Agent Mesh includes a rich library of pre-packaged tools for common tasks like data analysis, file management, and web requests. These are the easiest to use and can be enabled with just a few lines of configuration.  Use Case: For standard, out-of-the-box functionality.Learn More: See the Built-in Tools Reference for a complete list and configuration details.  ","version":"Next","tagName":"h3"},{"title":"2. Custom Python Tools​","type":1,"pageTitle":"Agents","url":"/solace-agent-mesh/docs/documentation/components/agents#2-custom-python-tools","content":" For unique business logic or specialized tasks, you can create your own tools using Python. This is the most powerful and flexible method, supporting everything from simple functions to advanced, class-based tool factories that can generate multiple tools programmatically.  Use Case: For implementing custom logic, integrating with proprietary systems, or creating dynamically configured tools.Learn More: See the Creating Python Tools guide for a complete walkthrough.  ","version":"Next","tagName":"h3"},{"title":"3. MCP (Model Context Protocol) Tools​","type":1,"pageTitle":"Agents","url":"/solace-agent-mesh/docs/documentation/components/agents#3-mcp-model-context-protocol-tools","content":" For integrating with external, standalone tool servers that conform to the Model Context Protocol, you can configure an MCP tool. This allows agents to communicate with tools running in separate processes or on different machines.  Use Case: For integrating with existing MCP-compliant tool servers or language-agnostic tool development.Learn More: See the MCP Integration Tutorial.  ","version":"Next","tagName":"h3"},{"title":"Agent Card​","type":1,"pageTitle":"Agents","url":"/solace-agent-mesh/docs/documentation/components/agents#agent-card","content":" The Agent Card is a public-facing profile that describes an agent's identity, capabilities, and how to interact with it. It functions like a digital business card, allowing other agents and clients within Agent Mesh to discover what an agent can do. This information is published by the agent and is crucial for dynamic discovery and interoperability.  The Agent Card is defined in the agent's YAML configuration file under the agent_card section.  ","version":"Next","tagName":"h2"},{"title":"Key Fields​","type":1,"pageTitle":"Agents","url":"/solace-agent-mesh/docs/documentation/components/agents#key-fields","content":" You can configure the following fields in the agent card:  description: A summary of the agent's purpose and capabilities.defaultInputModes: A list of supported MIME types for input (e.g., ["text/plain", "application/json", "file"]).defaultOutputModes: A list of supported MIME types for output.skills: A list of specific skills the agent possesses. Each skill corresponds to a capability, often backed by a tool.  ","version":"Next","tagName":"h3"},{"title":"Skills​","type":1,"pageTitle":"Agents","url":"/solace-agent-mesh/docs/documentation/components/agents#skills","content":" A skill describes a specific function the agent can perform. It provides granular detail about the agent's abilities.  Key attributes of a skill include:  id: A unique identifier for the skill, which should match the tool_name if the skill is directly mapped to a tool.name: A human-readable name for the skill.description: A clear explanation of what the skill does, which helps the LLM (and other agents) decide when to use it.  ","version":"Next","tagName":"h3"},{"title":"Example Configuration​","type":1,"pageTitle":"Agents","url":"/solace-agent-mesh/docs/documentation/components/agents#example-configuration","content":" Here is an example of an agent_card configuration for a "Mermaid Diagram Generator" agent:  # ... inside app_config ... agent_card: description: "An agent that generates PNG images from Mermaid diagram syntax." defaultInputModes: ["text"] # Expects Mermaid syntax as text defaultOutputModes: ["text", "file"] # Confirms with text, outputs file artifact skills: - id: "mermaid_diagram_generator" name: "Mermaid Diagram Generator" description: "Generates a PNG image from Mermaid diagram syntax. Input: mermaid_syntax (string), output_filename (string, optional)."   This card clearly communicates that the agent can take text (the Mermaid syntax) and produce a file (the PNG image), and it details the specific "mermaid_diagram_generator" skill it offers. For more details on creating agents and configuring their cards, see Creating Custom Agents.  ","version":"Next","tagName":"h3"},{"title":"User-Defined Agents​","type":1,"pageTitle":"Agents","url":"/solace-agent-mesh/docs/documentation/components/agents#user-defined-agents","content":" Using the Agent Mesh CLI, you can create your own agents. Agents are configured through YAML files that specify:  Agent name and instructionsLLM model configurationAvailable tools and capabilitiesArtifact and session management settingsDiscovery settings  The following Agent Mesh CLI command creates an agent configuration:  sam add agent my-agent [--gui]   For more information, see Creating Custom Agents.  ","version":"Next","tagName":"h2"},{"title":"Remote A2A Agents​","type":1,"pageTitle":"Agents","url":"/solace-agent-mesh/docs/documentation/components/agents#remote-a2a-agents","content":" In addition to agents that run natively within Agent Mesh, you can integrate external agents that communicate using the A2A protocol over HTTPS. These remote agents run on separate infrastructure but can still participate in collaborative workflows with mesh agents.  Remote A2A agents are useful when you need to:  Integrate third-party agents from vendors or partnersConnect agents running in different cloud environments or on-premises systemsMaintain service isolation while enabling collaborationGradually migrate existing A2A agents to the mesh  To integrate external agents, you use a proxy component that acts as a protocol bridge between A2A over HTTPS and A2A over Solace event mesh. The proxy handles authentication, artifact flow, and discovery, making remote agents appear as native mesh agents to other components.  For detailed information on configuring and deploying proxies for remote agents, see Proxies.  ","version":"Next","tagName":"h2"},{"title":"Agent Plugins​","type":1,"pageTitle":"Agents","url":"/solace-agent-mesh/docs/documentation/components/agents#agent-plugins","content":" You can also use agents built by the community or Solace directly in your app with little to no configuration.  For more information, see Use a Plugin. ","version":"Next","tagName":"h2"},{"title":"Configuring Built-in Tools","type":0,"sectionRef":"#","url":"/solace-agent-mesh/docs/documentation/components/builtin-tools/","content":"","keywords":"","version":"Next"},{"title":"Overview​","type":1,"pageTitle":"Configuring Built-in Tools","url":"/solace-agent-mesh/docs/documentation/components/builtin-tools/#overview","content":" Built-in tools are pre-packaged functionalities that can be granted to agents without requiring custom Python code. These tools address common operations such as file management, data analysis, web requests, and multi-modal generation.  The Agent Mesh framework manages these tools through a central tool_registry, which is responsible for loading the tools, generating instructional prompts for the Large Language Model (LLM), and handling their execution in a consistent manner.  ","version":"Next","tagName":"h2"},{"title":"Configuration Methods​","type":1,"pageTitle":"Configuring Built-in Tools","url":"/solace-agent-mesh/docs/documentation/components/builtin-tools/#configuration-methods","content":" Tool configuration is managed within the tools list in an agent's app_config block in the corresponding YAML configuration file.  ","version":"Next","tagName":"h2"},{"title":"Method 1: Enabling Tool Groups (Recommended)​","type":1,"pageTitle":"Configuring Built-in Tools","url":"/solace-agent-mesh/docs/documentation/components/builtin-tools/#method-1-enabling-tool-groups-recommended","content":" For efficient configuration, built-in tools are organized into logical groups. An entire group of related tools can be enabled with a single entry. This is the recommended approach for standard functionalities.  tool_type: builtin-groupgroup_name: The unique identifier for the tool category.  Example:  # In your agent's app_config: tools: - tool_type: builtin-group group_name: "artifact_management" - tool_type: builtin-group group_name: "data_analysis"   ","version":"Next","tagName":"h3"},{"title":"Method 2: Enabling Individual Tools​","type":1,"pageTitle":"Configuring Built-in Tools","url":"/solace-agent-mesh/docs/documentation/components/builtin-tools/#method-2-enabling-individual-tools","content":" For more granular control over an agent's capabilities, specific tools can be enabled individually.  tool_type: builtintool_name: The unique, registered name of the tool.  Example:  # In your agent's app_config: tools: - tool_type: builtin tool_name: "web_request" - tool_type: builtin tool_name: "time_delay"   Note The Agent Mesh framework automatically handles duplicate tool registrations. If a tool group is enabled and a tool from that group is also listed individually, the tool is only loaded once.  ","version":"Next","tagName":"h3"},{"title":"Available Tool Groups and Tools​","type":1,"pageTitle":"Configuring Built-in Tools","url":"/solace-agent-mesh/docs/documentation/components/builtin-tools/#available-tool-groups-and-tools","content":" The following sections detail the available tool groups and the individual tools they contain.  ","version":"Next","tagName":"h2"},{"title":"Artifact Management​","type":1,"pageTitle":"Configuring Built-in Tools","url":"/solace-agent-mesh/docs/documentation/components/builtin-tools/#artifact-management","content":" Group Name: artifact_management  Description: Tools for creating, loading, and managing file artifacts.  Individual Tools:  create_artifactappend_to_artifactlist_artifactsload_artifactsignal_artifact_for_returnapply_embed_and_create_artifactextract_content_from_artifact  info For a more in-depth guide on using artifact management tools, refer to the Artifact Management documentation.  ","version":"Next","tagName":"h3"},{"title":"Data Analysis​","type":1,"pageTitle":"Configuring Built-in Tools","url":"/solace-agent-mesh/docs/documentation/components/builtin-tools/#data-analysis","content":" Group Name: data_analysis  Description: Tools for querying, transforming, and visualizing data.  Individual Tools:  query_data_with_sqlcreate_sqlite_dbtransform_data_with_jqcreate_chart_from_plotly_config  info For a more in-depth guide on using Data Analysis tools, refer to the Data Analysis Tools documentation.  ","version":"Next","tagName":"h3"},{"title":"Web​","type":1,"pageTitle":"Configuring Built-in Tools","url":"/solace-agent-mesh/docs/documentation/components/builtin-tools/#web","content":" Group Name: web  Description: Tools for interacting with web resources.  Individual Tools:  web_request  ","version":"Next","tagName":"h3"},{"title":"Audio​","type":1,"pageTitle":"Configuring Built-in Tools","url":"/solace-agent-mesh/docs/documentation/components/builtin-tools/#audio","content":" Group Name: audio  Description: Tools for generating and transcribing audio content.  Individual Tools:  text_to_speechmulti_speaker_text_to_speechtranscribe_audio  ","version":"Next","tagName":"h3"},{"title":"Image​","type":1,"pageTitle":"Configuring Built-in Tools","url":"/solace-agent-mesh/docs/documentation/components/builtin-tools/#image","content":" Group Name: image  Description: Tools for generating and analyzing images.  Individual Tools:  create_image_from_descriptiondescribe_imageedit_image_with_geminidescribe_audio  ","version":"Next","tagName":"h3"},{"title":"General​","type":1,"pageTitle":"Configuring Built-in Tools","url":"/solace-agent-mesh/docs/documentation/components/builtin-tools/#general","content":" Group Name: general  Description: General-purpose utility tools.  Individual Tools:  convert_file_to_markdownmermaid_diagram_generator  ","version":"Next","tagName":"h3"},{"title":"Complete Configuration Example​","type":1,"pageTitle":"Configuring Built-in Tools","url":"/solace-agent-mesh/docs/documentation/components/builtin-tools/#complete-configuration-example","content":" Below is a comprehensive example of a well-formed app_config that uses the unified method to enable a mix of tool groups and individual tools.  # 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" # Enable a custom Python tool - tool_type: python component_module: "my_company.tools.custom_calculators" function_name: "calculate_roi" # ... other service configurations (session_service, artifact_service, etc.)  ","version":"Next","tagName":"h2"},{"title":"Components","type":0,"sectionRef":"#","url":"/solace-agent-mesh/docs/documentation/components/","content":"","keywords":"","version":"Next"},{"title":"Agents​","type":1,"pageTitle":"Components","url":"/solace-agent-mesh/docs/documentation/components/#agents","content":" Agents are the intelligent processing units that perform tasks within the mesh. Each agent combines the Google Agent Development Kit (ADK) with specialized instructions, LLM configurations, and toolsets to create focused AI capabilities. Agents can work independently or collaborate with other agents to solve complex problems. You can configure agents with different personalities, expertise areas, and access permissions to match your specific use cases. For comprehensive agent configuration and development guidance, see Agents.  ","version":"Next","tagName":"h2"},{"title":"Gateways​","type":1,"pageTitle":"Components","url":"/solace-agent-mesh/docs/documentation/components/#gateways","content":" Gateways serve as the entry and exit points for your agent mesh, translating between external protocols and the internal A2A communication standard. Whether you need REST APIs, webhooks, WebSocket connections, or integrations with platforms like Slack, gateways handle the protocol conversion and session management. They also manage authentication and authorization, ensuring that user permissions are properly enforced throughout the system. For gateway development and configuration details, see Gateways.  ","version":"Next","tagName":"h2"},{"title":"Orchestrator​","type":1,"pageTitle":"Components","url":"/solace-agent-mesh/docs/documentation/components/#orchestrator","content":" The orchestrator is a specialized agent that manages complex workflows by breaking down requests into smaller tasks and coordinating their execution across multiple agents. It understands dependencies between tasks, manages parallel execution, and aggregates results to provide comprehensive responses. The orchestrator is particularly valuable for scenarios that require multiple specialized agents to work together toward a common goal. For orchestrator configuration and workflow design patterns, see Orchestrator.  ","version":"Next","tagName":"h2"},{"title":"Plugins​","type":1,"pageTitle":"Components","url":"/solace-agent-mesh/docs/documentation/components/#plugins","content":" Plugins extend the capabilities of Agent Mesh by providing custom tools, integrations, and functionality. You can develop plugins to connect with proprietary systems, add domain-specific tools, or integrate with external services that aren't covered by the built-in toolset. The plugin system provides a standardized way to package and distribute custom functionality across your organization. For plugin development guidelines and examples, see Plugins.  ","version":"Next","tagName":"h2"},{"title":"Built-in Tools​","type":1,"pageTitle":"Components","url":"/solace-agent-mesh/docs/documentation/components/#built-in-tools","content":" Agent Mesh includes a comprehensive set of built-in tools that provide essential capabilities for most AI agent scenarios. These tools handle common tasks like artifact management, data analysis, web interactions, and inter-agent communication. The built-in tools are designed to work seamlessly with the A2A protocol and provide consistent behavior across all agents in your mesh. For detailed documentation of available tools and their usage, see Built-in Tools.  ","version":"Next","tagName":"h2"},{"title":"Command Line Interface​","type":1,"pageTitle":"Components","url":"/solace-agent-mesh/docs/documentation/components/#command-line-interface","content":" The CLI provides the primary interface for managing your Agent Mesh deployment. You can use it to start agents, configure gateways, monitor system health, and perform administrative tasks. The CLI simplifies complex operations and provides helpful feedback during development and deployment. For complete CLI documentation and command reference, see CLI. ","version":"Next","tagName":"h2"},{"title":"Artifact Management Tools","type":0,"sectionRef":"#","url":"/solace-agent-mesh/docs/documentation/components/builtin-tools/artifact-management","content":"","keywords":"","version":"Next"},{"title":"The Metadata-Aware Workflow​","type":1,"pageTitle":"Artifact Management Tools","url":"/solace-agent-mesh/docs/documentation/components/builtin-tools/artifact-management#the-metadata-aware-workflow","content":" Rather than automatically bundling all created artifacts in the final response, the agent follows a structured workflow:  Create & Describe: The agent invokes the create_artifact tool to persist a file. Rich metadata, such as descriptions, sources, and inferred schemas, is stored alongside the artifact.Inject & Inform: This metadata is automatically injected into the conversation history, providing the agent with immediate context regarding the new file.List & Discover: The agent can call list_artifacts at any point to retrieve a summary of all available artifacts and their associated metadata.Load & Analyze: The agent can use load_artifact to read the content of a text-based artifact or inspect the detailed metadata of any artifact (for example, to ascertain the schema of a CSV file).Return on Request: To transmit an artifact to the user or a calling application, the agent must explicitly invoke signal_artifact_for_return. Artifacts are not returned automatically.  ","version":"Next","tagName":"h2"},{"title":"Configuration​","type":1,"pageTitle":"Artifact Management Tools","url":"/solace-agent-mesh/docs/documentation/components/builtin-tools/artifact-management#configuration","content":" The file management tools are encapsulated within the artifact_management tool group.  ","version":"Next","tagName":"h2"},{"title":"Enabling the Tools​","type":1,"pageTitle":"Artifact Management Tools","url":"/solace-agent-mesh/docs/documentation/components/builtin-tools/artifact-management#enabling-the-tools","content":" Enable the tool group within the agent's app_config.yml:  # In your agent's app_config: tools: - tool_type: builtin-group group_name: "artifact_management"   ","version":"Next","tagName":"h3"},{"title":"Configuring Artifact Return Behavior​","type":1,"pageTitle":"Artifact Management Tools","url":"/solace-agent-mesh/docs/documentation/components/builtin-tools/artifact-management#configuring-artifact-return-behavior","content":" The artifact_handling_mode setting in your app_config dictates the behavior when signal_artifact_for_return is called:  ignore (Default): The request is logged, but no artifact is transmitted.embed: The artifact content is base64-encoded and embedded within the TaskArtifactUpdateEvent payload. This is suitable for smaller files.reference: A URI pointing to the artifact is sent in the event payload. This approach requires a separate service to host the file at the specified URI.  # In your agent's app_config: artifact_handling_mode: "reference"   ","version":"Next","tagName":"h3"},{"title":"Tool Reference​","type":1,"pageTitle":"Artifact Management Tools","url":"/solace-agent-mesh/docs/documentation/components/builtin-tools/artifact-management#tool-reference","content":" ","version":"Next","tagName":"h2"},{"title":"create_artifact​","type":1,"pageTitle":"Artifact Management Tools","url":"/solace-agent-mesh/docs/documentation/components/builtin-tools/artifact-management#create_artifact","content":" Creates a new file artifact and its corresponding metadata.  Parameters: filename (str): The designated name for the artifact (for example, "report.pdf").content (str): The file content. For binary file types (for example, images, PDFs), this content must be base64-encoded.mime_type (str): The standard MIME type of the content (for example, "text/plain", "image/png").metadata (dict, optional): A dictionary containing custom metadata (for example, {"description": "Monthly sales data"}). Returns: A dictionary confirming the successful persistence of the artifact.Key Feature: Upon successful execution of this tool, a summary of the artifact's metadata is automatically injected into the conversation history, informing the agent of the new file's context.    ","version":"Next","tagName":"h3"},{"title":"list_artifacts​","type":1,"pageTitle":"Artifact Management Tools","url":"/solace-agent-mesh/docs/documentation/components/builtin-tools/artifact-management#list_artifacts","content":" Lists all available artifacts within the current session.  Parameters: None.Returns: A list of file objects, each containing the filename, available versions, and a metadata_summary for the latest version.    ","version":"Next","tagName":"h3"},{"title":"load_artifact​","type":1,"pageTitle":"Artifact Management Tools","url":"/solace-agent-mesh/docs/documentation/components/builtin-tools/artifact-management#load_artifact","content":" Loads the content or detailed metadata of a specific version of an artifact.  Parameters: filename (str): The name of the artifact to be loaded.version (int): The specific version number of the artifact to load.load_metadata_only (bool, optional): If True, the tool returns the complete, detailed metadata dictionary instead of the artifact's content. This is useful for inspecting schemas or other metadata fields. Returns: If load_metadata_only=False: The artifact's content (for text-based files) or a basic information dictionary (for binary files).If load_metadata_only=True: The complete metadata dictionary for the specified artifact version.    ","version":"Next","tagName":"h3"},{"title":"signal_artifact_for_return​","type":1,"pageTitle":"Artifact Management Tools","url":"/solace-agent-mesh/docs/documentation/components/builtin-tools/artifact-management#signal_artifact_for_return","content":" Instructs the system to transmit a specific artifact version to the caller.  Parameters: filename (str): The name of the artifact to be returned.version (int): The specific version number of the artifact to return. Returns: A dictionary confirming that the request has been received.Note: This tool functions as a signal. The actual transmission of the artifact is handled by the system in accordance with the configured artifact_handling_mode.  ","version":"Next","tagName":"h3"},{"title":"Key Concepts​","type":1,"pageTitle":"Artifact Management Tools","url":"/solace-agent-mesh/docs/documentation/components/builtin-tools/artifact-management#key-concepts","content":" Explicit Control: Agents possess full, explicit control over the entire artifact lifecycle.Metadata-Driven Context: The automatic injection and summarization of metadata are fundamental to providing agents with situational awareness.Signaled Return: Artifacts are transmitted to the user only upon an explicit request from the agent via the signal_artifact_for_return tool.Synergy with Embeds: These tools can be used in conjunction with Dynamic Embeds, such as «artifact_meta:report.csv», for more efficient file handling. ","version":"Next","tagName":"h2"},{"title":"Data Analysis Tools","type":0,"sectionRef":"#","url":"/solace-agent-mesh/docs/documentation/components/builtin-tools/data-analysis-tools","content":"","keywords":"","version":"Next"},{"title":"Setup and Configuration​","type":1,"pageTitle":"Data Analysis Tools","url":"/solace-agent-mesh/docs/documentation/components/builtin-tools/data-analysis-tools#setup-and-configuration","content":" Enable the data analysis tool group in the agent's app_config.yml file.  # In your agent's app_config: tools: - tool_type: builtin-group group_name: "data_analysis" # Optional: Configure tool behavior data_tools_config: sqlite_memory_threshold_mb: 100 max_result_preview_rows: 50 max_result_preview_bytes: 4096   ","version":"Next","tagName":"h2"},{"title":"Available Tools​","type":1,"pageTitle":"Data Analysis Tools","url":"/solace-agent-mesh/docs/documentation/components/builtin-tools/data-analysis-tools#available-tools","content":" ","version":"Next","tagName":"h2"},{"title":"query_data_with_sql​","type":1,"pageTitle":"Data Analysis Tools","url":"/solace-agent-mesh/docs/documentation/components/builtin-tools/data-analysis-tools#query_data_with_sql","content":" Enterprise Only This feature is available in the Enterprise Edition only.  Executes a SQL query against data stored in a CSV or SQLite artifact.  Parameters: input_filename (str): The filename of the input artifact (for example, 'data.csv', 'mydatabase.sqlite'). Supports versioning (for example, 'data.csv:2').sql_query (str): The SQL query string to execute.output_format (str, optional): The desired format for the output artifact ('csv' or 'json'). Defaults to 'csv'. Behavior: For CSV Input: The tool loads the CSV data into a temporary in-memory SQLite database table named data and executes the query against it.For SQLite Input: The tool connects directly to the specified SQLite database artifact in read-only mode. Returns: A dictionary containing the execution status, a preview of the query result, and the output_filename where the full result set is stored.    ","version":"Next","tagName":"h3"},{"title":"create_sqlite_db​","type":1,"pageTitle":"Data Analysis Tools","url":"/solace-agent-mesh/docs/documentation/components/builtin-tools/data-analysis-tools#create_sqlite_db","content":" Enterprise Only This feature is available in the Enterprise Edition only.  Converts a CSV or JSON artifact into a persistent SQLite database artifact. This is the recommended approach for executing multiple queries on the same dataset, as it avoids repeated parsing of the source file.  Parameters: input_filename (str): The filename of the input CSV or JSON artifact.output_db_filename (str): The desired filename for the output SQLite database artifact (for example, 'queryable_dataset.sqlite').table_name (str, optional): The name of the table to be created within the SQLite database. Defaults to 'data'. Returns: A dictionary confirming the successful creation of the database artifact and providing its output_filename.    ","version":"Next","tagName":"h3"},{"title":"transform_data_with_jq​","type":1,"pageTitle":"Data Analysis Tools","url":"/solace-agent-mesh/docs/documentation/components/builtin-tools/data-analysis-tools#transform_data_with_jq","content":" Enterprise Only This feature is available in the Enterprise Edition only.  Applies a JQ expression to transform data from a JSON, YAML, or CSV artifact.  Parameters: input_filename (str): The filename of the input artifact.jq_expression (str): The JQ filter or transformation expression string (for example, '.users[] | {name, id}'). Returns: A dictionary containing the execution status, a preview of the transformed data, and the output_filename where the full JSON result is stored.    ","version":"Next","tagName":"h3"},{"title":"create_chart_from_plotly_config​","type":1,"pageTitle":"Data Analysis Tools","url":"/solace-agent-mesh/docs/documentation/components/builtin-tools/data-analysis-tools#create_chart_from_plotly_config","content":" Generates a static chart image (for example, PNG, JPG, SVG) from a Plotly configuration provided as a string.  Parameters: config_content (str): A JSON or YAML formatted string representing the Plotly figure dictionary.config_format (str): Specifies whether config_content is 'json' or 'yaml'.output_filename (str): The desired filename for the output image artifact (for example, 'sales_chart.png').output_format (str, optional): The desired image format ('png', 'jpeg', 'svg', etc.). Defaults to 'png'. Returns: A dictionary confirming the chart's creation and providing its output_filename.  ","version":"Next","tagName":"h3"},{"title":"Example Workflow: Querying a Large CSV​","type":1,"pageTitle":"Data Analysis Tools","url":"/solace-agent-mesh/docs/documentation/components/builtin-tools/data-analysis-tools#example-workflow-querying-a-large-csv","content":" The following workflow demonstrates an efficient method for analyzing a large CSV file:  User Request: "I need to run several queries on large_data.csv."Agent Strategy: The agent determines that converting the CSV to a SQLite database is more performant for subsequent queries.Agent Call 1: The agent calls create_sqlite_db to convert large_data.csv into a new artifact, queryable_data.sqlite.Agent Response: "The data has been prepared for querying. What is your first question?"User Request: "Find all records where the category is 'Sales'."Agent Call 2: The agent calls query_data_with_sql, targeting the queryable_data.sqlite artifact.Agent Response: The agent provides the results of the query.User Request: "Now, find the average amount for the 'Marketing' category."Agent Call 3: The agent calls query_data_with_sql again on the same queryable_data.sqlite artifact, avoiding the overhead of reprocessing the original CSV file.  ","version":"Next","tagName":"h2"},{"title":"Technical Considerations​","type":1,"pageTitle":"Data Analysis Tools","url":"/solace-agent-mesh/docs/documentation/components/builtin-tools/data-analysis-tools#technical-considerations","content":" ","version":"Next","tagName":"h2"},{"title":"Result Handling​","type":1,"pageTitle":"Data Analysis Tools","url":"/solace-agent-mesh/docs/documentation/components/builtin-tools/data-analysis-tools#result-handling","content":" Previews: For query_data_with_sql and transform_data_with_jq, the tools return a truncated preview of the result directly to the LLM for immediate context.Full Results: The complete, untruncated result sets are always saved as new artifacts. The LLM is provided with the filename and version of these artifacts.Accessing Full Results: To utilize the full results, the agent can employ file management tools (load_artifact) or Dynamic Embeds («artifact_content:...»).  ","version":"Next","tagName":"h3"},{"title":"Security​","type":1,"pageTitle":"Data Analysis Tools","url":"/solace-agent-mesh/docs/documentation/components/builtin-tools/data-analysis-tools#security","content":" SQL Execution: Queries against existing SQLite artifacts are performed in read-only mode to prevent data modification. Queries against temporary databases generated from CSVs are isolated.JQ Execution: JQ expressions are executed within a sandboxed Python library, not via shell execution.Resource Usage: Complex queries or transformations can be resource-intensive. Monitor performance and resource consumption accordingly. ","version":"Next","tagName":"h3"},{"title":"Agent Mesh CLI","type":0,"sectionRef":"#","url":"/solace-agent-mesh/docs/documentation/components/cli","content":"","keywords":"","version":"Next"},{"title":"Installation​","type":1,"pageTitle":"Agent Mesh CLI","url":"/solace-agent-mesh/docs/documentation/components/cli#installation","content":" The Agent Mesh CLI is installed as part of the Agent Mesh package. For more information, see Installation.  CLI Tips The Agent Mesh CLI comes with a short alias of sam which can be used in place of solace-agent-mesh.You can determine the version of the Agent Mesh CLI by running solace-agent-mesh --version.You can get help on any command by running solace-agent-mesh [COMMAND] --help.  ","version":"Next","tagName":"h2"},{"title":"Commands​","type":1,"pageTitle":"Agent Mesh CLI","url":"/solace-agent-mesh/docs/documentation/components/cli#commands","content":" ","version":"Next","tagName":"h2"},{"title":"init - Initialize an Agent Mesh Application​","type":1,"pageTitle":"Agent Mesh CLI","url":"/solace-agent-mesh/docs/documentation/components/cli#init---initialize-an-agent-mesh-application","content":" sam init [OPTIONS]   When this command is run with no options, it runs in interactive mode. It first prompts you to choose between configuring your project in the terminal or through a browser-based interface.  If you choose to use the browser, the Agent Mesh CLI starts a local web configuration portal, available at http://127.0.0.1:5002  You can skip some questions by providing the appropriate options for that step during the Agent Mesh CLI-based setup.  Optionally, you can skip all the questions by providing the --skip option. This option uses the provided or default values for all the questions.  automated workflows Use the --skip option and provide the necessary options to run the command in non-interactive mode, useful for automated workflows.  Options:​  --gui – Launch the browser-based initialization interface directly, skipping the prompt. (Recommended way to configure Agent Mesh applications)--skip – Runs in non-interactive mode, using default values where available.--llm-service-endpoint TEXT – LLM Service Endpoint URL.--llm-service-api-key TEXT – LLM Service API Key.--llm-service-planning-model-name TEXT – LLM Planning Model Name.--llm-service-general-model-name TEXT – LLM General Model Name.--namespace TEXT – Namespace for the project.--broker-type TEXT – Broker type: 1/solace (existing), 2/container (new local), 3/dev (dev mode). Options: 1, 2, 3, solace, container, dev_mode, dev_broker, dev.--broker-url TEXT – Solace broker URL endpoint.--broker-vpn TEXT – Solace broker VPN name.--broker-username TEXT – Solace broker username.--broker-password TEXT – Solace broker password.--container-engine TEXT – Container engine for local broker. Options: podman, docker.--dev-mode – Shortcut to select dev mode for broker (equivalent to --broker-type 3/dev).--agent-name TEXT – Agent name for the main orchestrator.--supports-streaming – Enable streaming support for the agent.--session-service-type TEXT – Session service type. Options: memory, vertex_rag.--session-service-behavior TEXT – Session service behavior. Options: PERSISTENT, RUN_BASED.--artifact-service-type TEXT – Artifact service type. Options: memory, filesystem, gcs.--artifact-service-base-path TEXT – Artifact service base path (for filesystem type).--artifact-service-scope TEXT – Artifact service scope. Options: namespace, app, custom.--artifact-handling-mode TEXT – Artifact handling mode. Options: ignore, embed, reference.--enable-embed-resolution – Enable embed resolution.--enable-artifact-content-instruction – Enable artifact content instruction.--enable-builtin-artifact-tools – Enable built-in artifact tools.--enable-builtin-data-tools – Enable built-in data tools.--agent-card-description TEXT – Agent card description.--agent-card-default-input-modes TEXT – Agent card default input modes (comma-separated).--agent-card-default-output-modes TEXT – Agent card default output modes (comma-separated).--agent-discovery-enabled – Enable agent discovery.--agent-card-publishing-interval INTEGER – Agent card publishing interval (seconds).--inter-agent-communication-allow-list TEXT – Inter-agent communication allow list (comma-separated, use * for all).--inter-agent-communication-deny-list TEXT – Inter-agent communication deny list (comma-separated).--inter-agent-communication-timeout INTEGER – Inter-agent communication timeout (seconds).--add-webui-gateway – Add a default Web UI gateway configuration.--webui-session-secret-key TEXT – Session secret key for Web UI.--webui-fastapi-host TEXT – Host for Web UI FastAPI server.--webui-fastapi-port INTEGER – Port for Web UI FastAPI server.--webui-enable-embed-resolution – Enable embed resolution for Web UI.--webui-frontend-welcome-message TEXT – Frontend welcome message for Web UI.--webui-frontend-bot-name TEXT – Frontend bot name for Web UI.--webui-frontend-collect-feedback – Enable feedback collection in Web UI.-h, --help – Displays the help message and exits.  ","version":"Next","tagName":"h3"},{"title":"add - Create a New Component​","type":1,"pageTitle":"Agent Mesh CLI","url":"/solace-agent-mesh/docs/documentation/components/cli#add---create-a-new-component","content":" To add a new component, such as an agent or gateway, use the add command with the appropriate options.  sam add [agent|gateway] [OPTIONS] NAME   Add agent​  Use agent to add an agent component.  sam add agent [OPTIONS] [NAME]   Options:​  --gui – Launch the browser-based configuration interface for agent setup. (Recommended way to configure agents)--skip – Skip interactive prompts and use defaults (Agent Mesh CLI mode only).--namespace TEXT – namespace (for example, myorg/dev).--supports-streaming BOOLEAN – Enable streaming support.--model-type TEXT – Model type for the agent. Options: planning, general, image_gen, report_gen, multimodal, gemini_pro.--instruction TEXT – Custom instruction for the agent.--session-service-type TEXT – Session service type. Options: memory, vertex_rag.--session-service-behavior TEXT – Session service behavior. Options: PERSISTENT, RUN_BASED.--artifact-service-type TEXT – Artifact service type. Options: memory, filesystem, gcs.--artifact-service-base-path TEXT – Base path for filesystem artifact service.--artifact-service-scope TEXT – Artifact service scope. Options: namespace, app, custom.--artifact-handling-mode TEXT – Artifact handling mode. Options: ignore, embed, reference.--enable-embed-resolution BOOLEAN – Enable embed resolution.--enable-artifact-content-instruction BOOLEAN – Enable artifact content instruction.--enable-builtin-artifact-tools BOOLEAN – Enable built-in artifact tools.--enable-builtin-data-tools BOOLEAN – Enable built-in data tools.--agent-card-description TEXT – Description for the agent card.--agent-card-default-input-modes-str TEXT – Comma-separated default input modes for agent card.--agent-card-default-output-modes-str TEXT – Comma-separated default output modes for agent card.--agent-card-publishing-interval INTEGER – Agent card publishing interval in seconds.--agent-discovery-enabled BOOLEAN – Enable agent discovery.--inter-agent-communication-allow-list-str TEXT – Comma-separated allow list for inter-agent communication.--inter-agent-communication-deny-list-str TEXT – Comma-separated deny list for inter-agent communication.--inter-agent-communication-timeout INTEGER – Timeout in seconds for inter-agent communication.-h, --help – Displays the help message and exits.  For more information, see Agents.  Add gateway​  Use gateway to add a gateway component.  sam add gateway [OPTIONS] [NAME]   Options:​  --gui – Launch the browser-based configuration interface for gateway setup. (Recommended way to configure gateways)--skip – Skip interactive prompts and use defaults (Agent Mesh CLI mode only).--namespace TEXT – namespace for the gateway (for example, myorg/dev).--gateway-id TEXT – Custom Gateway ID for the gateway.--artifact-service-type TEXT – Artifact service type for the gateway. Options: memory, filesystem, gcs.--artifact-service-base-path TEXT – Base path for filesystem artifact service (if type is 'filesystem').--artifact-service-scope TEXT – Artifact service scope (if not using default shared artifact service). Options: namespace, app, custom.--system-purpose TEXT – System purpose for the gateway (can be multi-line).--response-format TEXT – Response format for the gateway (can be multi-line).-h, --help – Displays the help message and exits.  For more information, see Gateways.  ","version":"Next","tagName":"h3"},{"title":"run - Run the Agent Mesh Application​","type":1,"pageTitle":"Agent Mesh CLI","url":"/solace-agent-mesh/docs/documentation/components/cli#run---run-the-agent-mesh-application","content":" To run the Agent Mesh application, use the run command.  sam run [OPTIONS] [FILES]...   Environment variables The sam run command automatically loads environment variables from your configuration file (typically a .env file at the project root) by default. If you want to use your system's environment variables instead, you can add the -u or --system-env option.  While running the run command, you can also skip specific files by providing the -s or --skip option.  You can provide paths to specific YAML configuration files or directories. When you provide a directory, run will recursively search for and load all .yaml and .yml files within that directory. This allows you to organize your configurations and run them together easily.  For example, to run specific files:  solace-agent-mesh run configs/agent1.yaml configs/gateway.yaml   To run all YAML files within the configs directory:  solace-agent-mesh run configs/   Options:​  -u, --system-env – Use system environment variables only; do not load .env file.-s, --skip TEXT – File name(s) to exclude from the run (for example, -s my_agent.yaml).-h, --help – Displays the help message and exits.  ","version":"Next","tagName":"h3"},{"title":"docs - Serve the documentation locally​","type":1,"pageTitle":"Agent Mesh CLI","url":"/solace-agent-mesh/docs/documentation/components/cli#docs---serve-the-documentation-locally","content":" Serves the project documentation on a local web server.  sam docs [OPTIONS]   This command starts a web server to host the documentation, which is useful for offline viewing or development. By default, it serves the documentation at http://localhost:8585/solace-agent-mesh/ and automatically opens your web browser to the getting started page.  If a requested page is not found, it will redirect to the main documentation page.  Options:​  -p, --port INTEGER – Port to run the web server on. (default: 8585)-h, --help – Displays the help message and exits.  ","version":"Next","tagName":"h3"},{"title":"plugin - Manage Plugins​","type":1,"pageTitle":"Agent Mesh CLI","url":"/solace-agent-mesh/docs/documentation/components/cli#plugin---manage-plugins","content":" The plugin command allows you to manage plugins for Agent Mesh application.  sam plugin [COMMAND] [OPTIONS]   For more information, see Plugins.  create - Create a Plugin​  Initializes and creates a new plugin with customizable options.  sam plugin create [OPTIONS] NAME   When this command is run with no options, it runs in interactive mode and prompts you to provide the necessary information to set up the plugin for Agent Mesh.  You can skip some questions by providing the appropriate options for that step.  Optionally, you can skip all the questions by providing the --skip option. This option uses the provided or default values for all the questions, which is useful for automated workflows.  Options:​  --type TEXT – Plugin type. Options: agent, gateway, custom.--author-name TEXT – Author's name.--author-email TEXT – Author's email.--description TEXT – Plugin description.--version TEXT – Initial plugin version.--skip – Skip interactive prompts and use defaults or provided flags.-h, --help – Displays the help message and exits.  build - Build the Plugin​  Compiles and prepares the plugin for use.  sam plugin build [PLUGIN_PATH]   Builds the Agent Mesh plugin in the specified directory (defaults to current directory).  Options:​  PLUGIN_PATH – Path to the plugin directory (defaults to current directory).-h, --help – Displays the help message and exits.  add - Add an Existing Plugin​  Installs the plugins and creates a new component instance from a specified plugin source.  sam plugin add [OPTIONS] COMPONENT_NAME   Options:​  --plugin TEXT – Plugin source: installed module name, local path, or Git URL. (Required)--install-command TEXT – Command to use to install a python package. Must follow the format command {package} args, by default pip3 install {package}. Can also be set through the environment variable SAM_PLUGIN_INSTALL_COMMAND.-h, --help – Displays the help message and exits.  installs - Installs a Plugin​  Installs a plugin from a specified plugin source.  sam plugin install [OPTIONS] PLUGIN_SOURCE   PLUGIN_SOURCE can be:  A local path to a directory (e.g., '/path/to/plugin')A local path to a wheel file (e.g., '/path/to/plugin.whl')A Git URL (e.g., 'https://github.com/user/repo.git')The name of the plugin from https://github.com/SolaceLabs/solace-agent-mesh-core-plugins  Options:​  --install-command TEXT – Command to use to install a python package. Must follow the format command {package} args, by default pip3 install {package}. Can also be set through the environment variable SAM_PLUGIN_INSTALL_COMMAND.-h, --help – Displays the help message and exits.  catalog - Launch Plugin Catalog​  Launch the Agent Mesh Plugin Catalog web interface.  sam plugin catalog [OPTIONS]   Options:​  --port INTEGER – Port to run the plugin catalog web server on. (default: 5003)--install-command TEXT – Command to use to install a python package. Must follow the format command {package} args.-h, --help – Displays the help message and exits. ","version":"Next","tagName":"h3"},{"title":"Dynamic Embeds","type":0,"sectionRef":"#","url":"/solace-agent-mesh/docs/documentation/components/builtin-tools/embeds","content":"","keywords":"","version":"Next"},{"title":"Dynamic Embeds​","type":1,"pageTitle":"Dynamic Embeds","url":"/solace-agent-mesh/docs/documentation/components/builtin-tools/embeds#dynamic-embeds","content":" Dynamic embeds provide a mechanism for agents to insert context-dependent information into their text responses or tool parameters using a specialized «...» syntax. This feature allows for the dynamic retrieval and formatting of data without requiring explicit tool calls for simple data retrieval or calculations.  ","version":"Next","tagName":"h2"},{"title":"Overview​","type":1,"pageTitle":"Dynamic Embeds","url":"/solace-agent-mesh/docs/documentation/components/builtin-tools/embeds#overview","content":" Dynamic embeds allow an agent to defer the inclusion of data until it is needed, resolving the value just before the final response is sent to the user.  Standard Approach: "The current time is [call get_time tool]."With Dynamic Embeds: "The current time is «datetime:%H:%M»."  The system resolves the embed directive, a dynamic placeholder for data that gets computed at runtime, replacing it with the evaluated result (for example, "The current time is 10:45.").  ","version":"Next","tagName":"h3"},{"title":"Syntax​","type":1,"pageTitle":"Dynamic Embeds","url":"/solace-agent-mesh/docs/documentation/components/builtin-tools/embeds#syntax","content":" There are two primary syntaxes for embed directives.  Simple Syntax​  This syntax is used for most general-purpose embeds.  «type:expression | format_spec»   type: A keyword indicating the type of information to embed (for example, state, math, datetime).expression: The specific data to retrieve or the expression to evaluate.format_spec: (Optional) A specifier for formatting the output value (for example, a number precision .2f or a strftime string %Y-%m-%d).  Chain Syntax​  This syntax is used exclusively for the artifact_content embed type to apply a sequence of transformations.  «artifact_content:spec >>> modifier1 >>> modifier2 >>> format:output_format»   artifact_spec: The artifact identifier (filename[:version]).>>>: The chain delimiter, separating transformation steps.modifier: A transformation to apply to the data (for example, jsonpath, grep, slice_lines).format: A required final step that specifies the output format (for example, text, json, datauri).  ","version":"Next","tagName":"h3"},{"title":"Available Embed Types​","type":1,"pageTitle":"Dynamic Embeds","url":"/solace-agent-mesh/docs/documentation/components/builtin-tools/embeds#available-embed-types","content":" General Purpose Embeds​  These are typically resolved by the agent host during execution.  Type\tDescription\tExamplestate\tAccesses a session state variable.\t«state:user_name» math\tEvaluates a mathematical expression.\t«math:100 * 0.05 | .2f» (Result: 5.00) datetime\tInserts the current date and/or time.\t«datetime:%Y-%m-%d» (Result: 2023-10-27) uuid\tInserts a random Version 4 UUID.\t«uuid:» status_update\tSignals a temporary status update to the UI.\t«status_update:Searching knowledge base...»  Artifact-Related Embeds​  artifact_meta​  Retrieves a JSON string containing the full metadata of a specified artifact.  Syntax: «artifact_meta:filename[:version]»Example: «artifact_meta:report.csv»  artifact_content​  Embeds the content of an artifact, with support for a chain of transformations. This is the most advanced embed type.  Modifiers (Data Transformations)Modifiers are applied sequentially to transform the data.  Modifier\tDescriptionjsonpath:<expr>\tApplies a JSONPath query to JSON data. select_cols:<c1,c2>\tSelects specific columns from CSV data. filter_rows_eq:<col>:<val>\tFilters CSV rows where a column's value equals the specified value. slice_rows:<start>:<end>\tSelects a slice of rows from CSV data. slice_lines:<start>:<end>\tSelects a slice of lines from text data. grep:<pattern>\tFilters lines matching a regular expression in text data. head:<N> / tail:<N>\tReturns the first or last N lines of text data. select_fields:<f1,f2>\tSelects specific fields from a list of dictionaries. apply_to_template:<file>\tRenders data using a Mustache template artifact. See the Templates Guide.  Formatters (Final Output)This is the required final step in an artifact_content chain, defining the output format.  Formatter\tDescriptiontext\tPlain text, decoded as UTF-8. json / json_pretty\tA compact or indented JSON string. csv\tA CSV formatted string. datauri\tA Base64-encoded data URI, typically for images (data:image/png;base64,...).  artifact_content Examples:  To embed an image for display in a UI:«artifact_content:logo.png >>> format:datauri»To extract and format specific data from a JSON file:«artifact_content:results.json >>> jsonpath:$.data[*].name >>> format:json»To get the last 10 lines of a log file:«artifact_content:debug.log >>> tail:10 >>> format:text»To filter a CSV file and render it using an HTML template:«artifact_content:users.csv >>> filter_rows_eq:Status:Active >>> apply_to_template:active_users.html >>> format:text»  ","version":"Next","tagName":"h3"},{"title":"Technical Details​","type":1,"pageTitle":"Dynamic Embeds","url":"/solace-agent-mesh/docs/documentation/components/builtin-tools/embeds#technical-details","content":" Resolution Stages​  Embeds are resolved in two distinct stages, depending on where the required data is available:  Early Stage (Agent Host): Resolved by the agent runtime itself. This stage handles simple, context-local embeds like state, math, and datetime.Late Stage (Gateway): Resolved by the Gateway component before the final message is sent to the client. This is necessary for artifact_content embeds, which may involve large files or transformations that are too resource-intensive for the agent host.  Configuration​  Enabling/Disabling: Embed resolution is enabled by default. It can be disabled in the app_config of the agent host or gateway by setting enable_embed_resolution: false.Resource Limits: The gateway enforces configurable limits to prevent abuse, including gateway_artifact_content_limit_bytes (default: 32KB) and gateway_recursive_embed_depth (default: 3).  ","version":"Next","tagName":"h3"},{"title":"Error Handling​","type":1,"pageTitle":"Dynamic Embeds","url":"/solace-agent-mesh/docs/documentation/components/builtin-tools/embeds#error-handling","content":" If an embed directive fails during parsing or evaluation, it is replaced with a descriptive error message in the final output.  Parsing Error: [Error: Invalid modifier format: 'badmodifier']Evaluation Error: [Error: State variable 'user_id' not found]Limit Exceeded: [Error: Artifact 'large_file.zip' exceeds size limit]  ","version":"Next","tagName":"h3"},{"title":"Templates​","type":1,"pageTitle":"Dynamic Embeds","url":"/solace-agent-mesh/docs/documentation/components/builtin-tools/embeds#templates","content":" ","version":"Next","tagName":"h2"},{"title":"Using Templates for Formatted Output​","type":1,"pageTitle":"Dynamic Embeds","url":"/solace-agent-mesh/docs/documentation/components/builtin-tools/embeds#using-templates-for-formatted-output","content":" The apply_to_template modifier, used within an «artifact_content:...» embed directive, enables an agent to render structured data using a Mustache template. This mechanism allows for the separation of data and presentation, enabling the agent to control the output format (for example, HTML, Markdown) without generating the formatting markup itself.  ","version":"Next","tagName":"h3"},{"title":"The Templating Workflow​","type":1,"pageTitle":"Dynamic Embeds","url":"/solace-agent-mesh/docs/documentation/components/builtin-tools/embeds#the-templating-workflow","content":" The process involves three distinct steps:  Template Creation: Author a Mustache template file that defines the desired output structure.Artifact Storage: Persist the template file as an artifact in the agent's artifact storage using the create_artifact tool.Template Rendering: Utilize an «artifact_content:...» embed chain to process a data artifact and then apply the stored template to the result.    Step 1: Create a Mustache Template​  Mustache is a logic-less template syntax. Templates are created as text files (for example, user_table.html.mustache) containing placeholders for data injection.  Key Mustache Syntax:  {{variable}}: A variable placeholder. It is replaced with the corresponding value from the data context.{{#section}}...{{/section}}: A section tag. The enclosed block is rendered for each item in a list or if the section variable is a non-empty object or truthy value.{{^section}}...{{/section}}: An inverted section tag. The enclosed block is rendered only if the section variable is false, null, or an empty list.{{! comment }}: A comment tag. The content is ignored during rendering.  Example: user_table.html.mustacheThis template generates an HTML table from a list of user objects.  <h2>User List</h2> {{#items}} <table> <thead> <tr> <th>Name</th> <th>Status</th> </tr> </thead> <tbody> {{#.}} <tr> <td>{{name}}</td> <td>{{status}}</td> </tr> {{/.}} </tbody> </table> {{/items}} {{^items}} <p>No users found.</p> {{/items}}     Step 2: Store the Template as an Artifact​  The template must be stored as an artifact to be accessible by the Gateway during the late-stage embed resolution process. This is accomplished using the create_artifact tool.  Example Agent Interaction:  User: "Please create an HTML template to display a list of users."Agent: "Acknowledged. I will create the template artifact user_table.html.mustache."(The agent then invokes the create_artifact tool with the specified filename and the HTML content from Step 1.)    Step 3: Render the Template with an Embed​  With the data and template artifacts stored, the agent can construct an artifact_content embed chain to perform the rendering.  Syntax: ... >>> apply_to_template:template_filename[:version] >>> ...Data Context: The data provided to the template engine is the output of the preceding modifier in the chain. If the data is a list, it is automatically wrapped in a dictionary of the form {'items': your_list}. The template should use {{#items}} to iterate over this list.If the data is a dictionary, it is used directly as the rendering context. Output Format: It is mandatory to terminate the chain with a format: step (for example, format:text) to specify the MIME type of the final rendered output.  Complete Example: The following embed chain processes a JSON file and renders its content using the HTML template created in Step 1.  «artifact_content:user_data.json >>> jsonpath:$.users[*] >>> select_fields:name,status >>> apply_to_template:user_table.html.mustache >>> format:text»   Execution Flow:  artifact_content:user_data.json: Loads the raw data from the user_data.json artifact.jsonpath:$.users[*]: Applies a JSONPath expression to extract the list of user objects.select_fields:name,status: Filters each object in the list to retain only the name and status fields.apply_to_template:user_table.html.mustache: Renders the resulting list of users using the specified Mustache template.  ","version":"Next","tagName":"h3"},{"title":"Error Handling​","type":1,"pageTitle":"Dynamic Embeds","url":"/solace-agent-mesh/docs/documentation/components/builtin-tools/embeds#error-handling-1","content":" Template Not Found: If the specified template artifact does not exist, the embed resolves to [Error: Template artifact '...' not found].Rendering Error: If the data structure is incompatible with the template's expectations, the embed resolves to [Error: Error rendering template '...']. ","version":"Next","tagName":"h3"},{"title":"Orchestrator Agent","type":0,"sectionRef":"#","url":"/solace-agent-mesh/docs/documentation/components/orchestrator","content":"","keywords":"","version":"Next"},{"title":"Key Functions​","type":1,"pageTitle":"Orchestrator Agent","url":"/solace-agent-mesh/docs/documentation/components/orchestrator#key-functions","content":" The orchestrator agent provides the following key functions:  Request Analysis and Action Planning: Receives high-level goals or requestsAnalyzes them in the context of available actions registered by agents in the systemUses state-of-the-art generative AI techniques to plan a sequence of actions to fulfill the request Task Creation and Distribution: Creates tasks based on the action planDistributes tasks to appropriate agentsEnables efficient parallel processing and optimal resource utilization Workflow Management: Tracks outstanding tasksAggregates responses from various agentsEnsures all parts of a complex request are processed and combined coherently Response Formatting: Formats aggregated responses suitable for the gatewayEnsures the final output meets the requirements of the specific use case or interface ","version":"Next","tagName":"h2"},{"title":"Using Text-to-Speech (TTS) Tools","type":0,"sectionRef":"#","url":"/solace-agent-mesh/docs/documentation/components/builtin-tools/audio-tools","content":"","keywords":"","version":"Next"},{"title":"Overview​","type":1,"pageTitle":"Using Text-to-Speech (TTS) Tools","url":"/solace-agent-mesh/docs/documentation/components/builtin-tools/audio-tools#overview","content":" The audio tool group provides two primary TTS tools for generating high-quality audio artifacts:  text_to_speech: Converts a string of text to speech using a single voice, featuring intelligent tone selection.multi_speaker_text_to_speech: Converts a conversational script, delineated by speaker, into a multi-speaker audio file.  ","version":"Next","tagName":"h2"},{"title":"Setup and Configuration​","type":1,"pageTitle":"Using Text-to-Speech (TTS) Tools","url":"/solace-agent-mesh/docs/documentation/components/builtin-tools/audio-tools#setup-and-configuration","content":" ","version":"Next","tagName":"h2"},{"title":"Prerequisites​","type":1,"pageTitle":"Using Text-to-Speech (TTS) Tools","url":"/solace-agent-mesh/docs/documentation/components/builtin-tools/audio-tools#prerequisites","content":" API Key: A valid Google Gemini API key with access to the TTS model is required.Dependencies: The pydub library is necessary for audio processing and format conversion. It can be installed via pip install pydub.  ","version":"Next","tagName":"h3"},{"title":"Basic Configuration​","type":1,"pageTitle":"Using Text-to-Speech (TTS) Tools","url":"/solace-agent-mesh/docs/documentation/components/builtin-tools/audio-tools#basic-configuration","content":" Environment Variable: The Gemini API key must be set as an environment variable. export GEMINI_API_KEY="your_gemini_api_key_here" Enablement: The audio tool group must be enabled in the agent's app_config.yml. tools: - tool_type: builtin-group group_name: "audio"   ","version":"Next","tagName":"h3"},{"title":"Advanced Configuration​","type":1,"pageTitle":"Using Text-to-Speech (TTS) Tools","url":"/solace-agent-mesh/docs/documentation/components/builtin-tools/audio-tools#advanced-configuration","content":" You can exercise more granular control over the TTS tools by providing a tool_config block for each tool in your app_config.yml.  ","version":"Next","tagName":"h2"},{"title":"text_to_speech Configuration​","type":1,"pageTitle":"Using Text-to-Speech (TTS) Tools","url":"/solace-agent-mesh/docs/documentation/components/builtin-tools/audio-tools#text_to_speech-configuration","content":" This example shows how to set a default voice and define the mapping between tones and specific voice models.  - tool_type: builtin tool_name: "text_to_speech" tool_config: gemini_api_key: ${GEMINI_API_KEY} model: "gemini-2.5-flash-preview-tts" voice_name: "Kore" # Default voice if no tone is matched language: "en-US" # Default language output_format: "mp3" # Voice selection by tone mapping voice_tone_mapping: bright: ["Zephyr", "Autonoe"] upbeat: ["Puck", "Laomedeia"] informative: ["Charon", "Rasalgethi"] firm: ["Kore", "Orus", "Alnilam"] friendly: ["Achird"] casual: ["Zubenelgenubi"] warm: ["Sulafar"]   ","version":"Next","tagName":"h3"},{"title":"multi_speaker_text_to_speech Configuration​","type":1,"pageTitle":"Using Text-to-Speech (TTS) Tools","url":"/solace-agent-mesh/docs/documentation/components/builtin-tools/audio-tools#multi_speaker_text_to_speech-configuration","content":" This example defines default voice configurations for up to five speakers.  - tool_type: builtin tool_name: "multi_speaker_text_to_speech" tool_config: gemini_api_key: ${GEMINI_API_KEY} model: "gemini-2.5-flash-preview-tts" language: "en-US" output_format: "mp3" # Default speaker voice configurations default_speakers: - { name: "Speaker1", voice: "Kore", tone: "firm" } - { name: "Speaker2", voice: "Puck", tone: "upbeat" } - { name: "Speaker3", voice: "Charon", tone: "informative" } - { name: "Speaker4", voice: "Achird", tone: "friendly" } - { name: "Speaker5", voice: "Sulafar", tone: "warm" } # The voice_tone_mapping can also be included here   ","version":"Next","tagName":"h3"},{"title":"Features​","type":1,"pageTitle":"Using Text-to-Speech (TTS) Tools","url":"/solace-agent-mesh/docs/documentation/components/builtin-tools/audio-tools#features","content":" ","version":"Next","tagName":"h2"},{"title":"Intelligent Tone Selection​","type":1,"pageTitle":"Using Text-to-Speech (TTS) Tools","url":"/solace-agent-mesh/docs/documentation/components/builtin-tools/audio-tools#intelligent-tone-selection","content":" The system supports tone-based voice selection, allowing for dynamic voice choice based on desired emotional or stylistic output, rather than explicit voice names.  Available Tones:bright, upbeat, informative, firm, excitable, youthful, breezy, easy-going, breathy, clear, smooth, gravelly, soft, even, mature, forward, friendly, casual, gentle, lively, knowledgeable, warm  Tone Aliases:  professional → firmcheerful → upbeatcalm → softconversational → casual  ","version":"Next","tagName":"h3"},{"title":"Multi-Language Support​","type":1,"pageTitle":"Using Text-to-Speech (TTS) Tools","url":"/solace-agent-mesh/docs/documentation/components/builtin-tools/audio-tools#multi-language-support","content":" The tools support over 25 languages, specified via BCP-47 language codes (for example, en-US, fr-FR, es-US, ja-JP).  ","version":"Next","tagName":"h3"},{"title":"Usage Examples​","type":1,"pageTitle":"Using Text-to-Speech (TTS) Tools","url":"/solace-agent-mesh/docs/documentation/components/builtin-tools/audio-tools#usage-examples","content":" ","version":"Next","tagName":"h2"},{"title":"Single-Voice Text-to-Speech (text_to_speech)​","type":1,"pageTitle":"Using Text-to-Speech (TTS) Tools","url":"/solace-agent-mesh/docs/documentation/components/builtin-tools/audio-tools#single-voice-text-to-speech-text_to_speech","content":" Basic Usage  Convert the following text to speech: "Welcome to the technical briefing on artificial intelligence."   With Tone Selection  Convert this text to speech with a professional tone: "Thank you for joining today's technical review."   ","version":"Next","tagName":"h3"},{"title":"Multi-Speaker Text-to-Speech (multi_speaker_text_to_speech)​","type":1,"pageTitle":"Using Text-to-Speech (TTS) Tools","url":"/solace-agent-mesh/docs/documentation/components/builtin-tools/audio-tools#multi-speaker-text-to-speech-multi_speaker_text_to_speech","content":" Basic Conversation  Convert this conversation to speech: Speaker1: Welcome to the podcast. Speaker2: Thank you for having me.   With Custom Speaker Tones  Convert this conversation using specific tones for each speaker: - Speaker1 should sound professional - Speaker2 should sound friendly Conversation: Speaker1: Good morning, this is the daily security briefing. Speaker2: Hi everyone, let's review the agenda for today's session.   ","version":"Next","tagName":"h3"},{"title":"Tool Reference​","type":1,"pageTitle":"Using Text-to-Speech (TTS) Tools","url":"/solace-agent-mesh/docs/documentation/components/builtin-tools/audio-tools#tool-reference","content":" ","version":"Next","tagName":"h2"},{"title":"text_to_speech​","type":1,"pageTitle":"Using Text-to-Speech (TTS) Tools","url":"/solace-agent-mesh/docs/documentation/components/builtin-tools/audio-tools#text_to_speech","content":" Parameter\tType\tDescriptiontext\tstring\tThe text to be synthesized. output_filename\tstring\t(Optional) A custom MP3 filename. voice_name\tstring\t(Optional) A specific voice name to use. tone\tstring\t(Optional) The desired voice tone. language\tstring\t(Optional) The BCP-47 language code.  ","version":"Next","tagName":"h3"},{"title":"multi_speaker_text_to_speech​","type":1,"pageTitle":"Using Text-to-Speech (TTS) Tools","url":"/solace-agent-mesh/docs/documentation/components/builtin-tools/audio-tools#multi_speaker_text_to_speech","content":" Parameter\tType\tDescriptionconversation_text\tstring\tA string of text with speaker labels (for example, S1: ...). output_filename\tstring\t(Optional) A custom MP3 filename. speaker_configs\tarray\t(Optional) An array to configure tones for specific speakers. language\tstring\t(Optional) The BCP-47 language code.  ","version":"Next","tagName":"h3"},{"title":"Output and Metadata​","type":1,"pageTitle":"Using Text-to-Speech (TTS) Tools","url":"/solace-agent-mesh/docs/documentation/components/builtin-tools/audio-tools#output-and-metadata","content":" Both tools generate an MP3 audio artifact that includes a rich set of metadata:  The source text (or a truncated version for long inputs)The voice(s) and language used for synthesisThe generation timestamp and the specific tool invokedThe requested tone and any speaker-specific configurations  ","version":"Next","tagName":"h2"},{"title":"Troubleshooting​","type":1,"pageTitle":"Using Text-to-Speech (TTS) Tools","url":"/solace-agent-mesh/docs/documentation/components/builtin-tools/audio-tools#troubleshooting","content":" Error: GEMINI_API_KEY is required: This indicates that the GEMINI_API_KEY environment variable has not been set correctly.Warning: Unknown tone 'xyz': The specified tone is not recognized. Refer to the list of supported tones. The system will fall back to a default voice.Error: Failed to convert WAV to MP3: This typically indicates that pydub is not installed or that the underlying system is missing necessary audio codecs (for example, ffmpeg). ","version":"Next","tagName":"h2"},{"title":"Gateways","type":0,"sectionRef":"#","url":"/solace-agent-mesh/docs/documentation/components/gateways","content":"","keywords":"","version":"Next"},{"title":"Key Functions​","type":1,"pageTitle":"Gateways","url":"/solace-agent-mesh/docs/documentation/components/gateways#key-functions","content":" Entry Points: Gateways act as the entry points from the outside world and translate external requests into A2A protocol messages and route them through the Solace event mesh to appropriate agents. Authentication & Authorization: Common authentication and user enrichment flow across all gateway types, with pluggable identity providers. Configurable System Purpose: Each gateway has a configurable system purpose that sets the context for all stimuli entering Agent Mesh through that gateway. This design allows for tailored processing based on the specific use case or domain. Customizable Output Formatting: Gateways have a configurable output description that controls how stimuli responses are formatted when sent back to the outside world. This configurable output description ensures that the output meets the requirements of the receiving system or user interface. Multiple Interface Types: Gateways can have different interfaces to accommodate various communication protocols and systems. Some examples include REST APIs, event meshes, Slack integrations, browser-based interfaces, and so on.  ","version":"Next","tagName":"h2"},{"title":"How Gateways Work​","type":1,"pageTitle":"Gateways","url":"/solace-agent-mesh/docs/documentation/components/gateways#how-gateways-work","content":" The following diagram illustrates the complete flow of information through a gateway in Agent Mesh:    ","version":"Next","tagName":"h2"},{"title":"Available Gateways​","type":1,"pageTitle":"Gateways","url":"/solace-agent-mesh/docs/documentation/components/gateways#available-gateways","content":" Agent Mesh comes with several built-in gateway types:  ","version":"Next","tagName":"h2"},{"title":"Core Gateways​","type":1,"pageTitle":"Gateways","url":"/solace-agent-mesh/docs/documentation/components/gateways#core-gateways","content":" HTTP SSE Gateway Real-time web interface with streaming responsesServer-sent events for live updatesAgent discovery APIFile upload and download handling REST Gateway Task submission with immediate task ID returnPolling-based result retrievalAuthentication integration Webhook Gateway Handles incoming webhook requestsTransforms webhook payloads to A2A messages  ","version":"Next","tagName":"h3"},{"title":"Plugin Gateways​","type":1,"pageTitle":"Gateways","url":"/solace-agent-mesh/docs/documentation/components/gateways#plugin-gateways","content":" Additional gateway types are available through the plugin ecosystem:  Event Mesh Gateway: External event mesh connectivity with message transformationSlack Gateway: Slack bot integration for team collaborationCustom Gateways: Create your own gateway implementations  For more information about plugins and how to configure them, see Plugins.  One of the official core plugin gateway interfaces is the Solace Event Mesh Gateway, which enables communication with the PubSub+ event broker directly as an input interface.  note Each gateway type has its own configuration options and specific features. See the individual gateway documentation pages for detailed information on setup and usage.  ","version":"Next","tagName":"h3"},{"title":"Create a Gateway​","type":1,"pageTitle":"Gateways","url":"/solace-agent-mesh/docs/documentation/components/gateways#create-a-gateway","content":" To create a gateway, you can either use one of the pre-existing plugins or create yours from scratch.  ","version":"Next","tagName":"h2"},{"title":"Gateway from Scratch​","type":1,"pageTitle":"Gateways","url":"/solace-agent-mesh/docs/documentation/components/gateways#gateway-from-scratch","content":" To create a gateway from scratch, you need to use the CLI add gateway command without any interfaces. This command creates a python gateway template file which you can then customize to your needs.  sam add gateway my-interface   To learn more about creating your own gateway, see Create Custom Gateways.  Share and Reuse If you would like to share your custom gateway with the community or re-use it within other projects, you can create a plugin for it. For more information, see Create Plugins. ","version":"Next","tagName":"h3"},{"title":"Deploying Agent Mesh","type":0,"sectionRef":"#","url":"/solace-agent-mesh/docs/documentation/deploying/","content":"","keywords":"","version":"Next"},{"title":"Selecting Your Deployment Strategy​","type":1,"pageTitle":"Deploying Agent Mesh","url":"/solace-agent-mesh/docs/documentation/deploying/#selecting-your-deployment-strategy","content":" Production deployments require different considerations than development environments, particularly around scalability, reliability, and security. You can choose containerized deployments using Docker for single-node setups, Kubernetes orchestration for scalable architectures, or hybrid approaches that separate components for independent scaling. Each strategy offers distinct advantages depending on your operational requirements. For comprehensive guidance on evaluating and implementing these approaches, see Choosing Deployment Options.  ","version":"Next","tagName":"h2"},{"title":"Observing Your Agent Mesh​","type":1,"pageTitle":"Deploying Agent Mesh","url":"/solace-agent-mesh/docs/documentation/deploying/#observing-your-agent-mesh","content":" Effective monitoring provides the visibility you need to understand system behavior and maintain optimal operation. The platform offers multiple observability layers that create a complete picture of your system's health. You can visualize request workflows through interactive diagrams, monitor real-time agent status, track message flows at the event broker level, and analyze detailed stimulus logs for forensic analysis. For detailed information on implementing these monitoring tools, see Monitoring Your Agent Mesh.  ","version":"Next","tagName":"h2"},{"title":"Troubleshooting and Debugging Issues​","type":1,"pageTitle":"Deploying Agent Mesh","url":"/solace-agent-mesh/docs/documentation/deploying/#troubleshooting-and-debugging-issues","content":" When issues arise in distributed systems, systematic debugging approaches help you quickly identify root causes. The debugging process leverages observability tools in focused ways to isolate problems and understand their causes. You can isolate specific components to reduce complexity, examine stimulus traces for detailed analysis, monitor real-time event broker activity, use interactive debugging tools for code investigation, and invoke agents directly for controlled testing. For step-by-step guidance on applying these strategies, see Diagnosing and Resolving Problems.  ","version":"Next","tagName":"h2"},{"title":"Production Readiness Considerations​","type":1,"pageTitle":"Deploying Agent Mesh","url":"/solace-agent-mesh/docs/documentation/deploying/#production-readiness-considerations","content":" Successful production deployments require attention to security, performance, and operational practices beyond basic functionality. Consider implementing robust secret management, establishing TLS encryption for all communication channels, configuring appropriate resource limits and scaling policies, setting up automated backup procedures, and creating runbooks for common scenarios. These practices ensure your agent mesh operates reliably and securely while providing the foundation for ongoing maintenance and optimization. ","version":"Next","tagName":"h2"},{"title":"Diagnosing and Resolving Problems","type":0,"sectionRef":"#","url":"/solace-agent-mesh/docs/documentation/deploying/debugging","content":"","keywords":"","version":"Next"},{"title":"Isolating Components​","type":1,"pageTitle":"Diagnosing and Resolving Problems","url":"/solace-agent-mesh/docs/documentation/deploying/debugging#isolating-components","content":" When facing complex issues in a multi-agent system, isolation becomes your most powerful debugging technique. By running only the components directly related to your problem, you eliminate variables and focus your investigation on the most likely sources of trouble.  Component isolation works because it reduces system complexity to manageable levels. Instead of trying to understand interactions across dozens of agents, you can focus on a small subset and verify their behavior in controlled conditions.  The Agent Mesh CLI provides precise control over which components run in your debugging session. You can specify exactly which configuration files to load, creating a minimal environment that includes only the agents you need to investigate.  For example, if you're debugging an issue with a specific tool integration, you might run only the orchestrator and the problematic tool agent:  sam run configs/agents/my_tool_1.yaml configs/agents/my_tool_2.yaml   This command creates a focused debugging environment that includes only the agents defined in my_tool_1.yaml and my_tool_2.yaml. By eliminating unrelated components, you reduce log noise and make it easier to trace the specific interactions that might be causing problems.  This isolation approach is particularly effective when you suspect issues with agent-to-agent communication, configuration problems, or logic errors within specific agents.  ","version":"Next","tagName":"h2"},{"title":"Examining STIM Files​","type":1,"pageTitle":"Diagnosing and Resolving Problems","url":"/solace-agent-mesh/docs/documentation/deploying/debugging#examining-stim-files","content":" STIM files serve as your detailed forensic evidence when debugging complex issues. These comprehensive traces capture every aspect of how requests flow through your system, making them invaluable for understanding problems that span multiple agents or involve timing-sensitive interactions.  STIM files provide the most complete picture available of stimulus lifecycles. Unlike real-time monitoring tools that show current activity, STIM files preserve historical data that you can analyze repeatedly and share with team members for collaborative debugging.  Each .stim file contains a complete record of all Solace event broker events related to a single stimulus, from the initial user request through every agent interaction to the final response delivery. This comprehensive coverage makes STIM files particularly useful for debugging issues that involve:  Multi-agent workflows where the problem might occur at any stepTiming-related issues where sequence and duration matterIntermittent problems that are difficult to reproduce in real-timePerformance bottlenecks that require detailed timing analysis  When examining STIM files, look for patterns in agent response times, unexpected message routing, or missing interactions that should have occurred based on your system design.  ","version":"Next","tagName":"h2"},{"title":"Monitoring Event Broker Activity​","type":1,"pageTitle":"Diagnosing and Resolving Problems","url":"/solace-agent-mesh/docs/documentation/deploying/debugging#monitoring-event-broker-activity","content":" Real-time Solace event broker monitoring provides immediate insights into your system's communication patterns and helps identify issues as they occur. This approach complements STIM file analysis by giving you live visibility into message flows and event interactions.  Broker-level monitoring is particularly valuable because it shows the actual communication happening between components, regardless of how agents are configured or what they report about their own status. This ground-truth perspective helps identify discrepancies between expected and actual behavior.  For comprehensive guidance on Solace event broker monitoring techniques and tools, see Monitoring Event Broker Activity.  ","version":"Next","tagName":"h2"},{"title":"Using Debug Mode​","type":1,"pageTitle":"Diagnosing and Resolving Problems","url":"/solace-agent-mesh/docs/documentation/deploying/debugging#using-debug-mode","content":" Interactive debugging provides the deepest level of investigation capability by allowing you to pause execution and examine system state in real-time. Because Agent Mesh is built on Python, you can leverage standard Python debugging tools and IDE features to step through code execution and inspect variables.  This approach is most effective when you've already isolated the problem to specific components and need to understand exactly what's happening within agent logic or framework code.  ","version":"Next","tagName":"h2"},{"title":"Setting Up VSCode Debugging​","type":1,"pageTitle":"Diagnosing and Resolving Problems","url":"/solace-agent-mesh/docs/documentation/deploying/debugging#setting-up-vscode-debugging","content":" VSCode provides an excellent debugging environment for Agent Mesh development. The integrated debugger allows you to set breakpoints, step through code execution, and inspect variables in real-time, making it easier to understand complex agent interactions and identify logic errors.  Configure debugging by creating or updating your .vscode/launch.json file:  { "version": "0.2.0", "configurations": [ { "name": "sam-debug", "type": "debugpy", "request": "launch", "module": "solace_agent_mesh.cli.main", "console": "integratedTerminal", "envFile": "${workspaceFolder}/.env", "args": [ "run", "configs/agents/main_orchestrator.yaml", "configs/gateways/webui.yaml" // Add any other components you want to run here ], "justMyCode": false } ] }   The "justMyCode": false setting is particularly important because it allows you to step into Agent Mesh framework code, not just your custom agent logic. This capability is valuable when debugging issues that might involve framework behavior or when you need to understand how your agents interact with the underlying platform.  To start a debugging session:  Open the RUN AND DEBUG panel in the left sidebarSelect sam-debug from the configuration dropdownClick the Play button to launch your system in debug mode  Once running, you can set breakpoints in your agent code, framework files, or any Python modules your system uses. When execution hits a breakpoint, you can inspect variable states, evaluate expressions, and step through code line by line to understand exactly what's happening.  ","version":"Next","tagName":"h3"},{"title":"Invoking Agents Directly​","type":1,"pageTitle":"Diagnosing and Resolving Problems","url":"/solace-agent-mesh/docs/documentation/deploying/debugging#invoking-agents-directly","content":" Direct agent invocation provides a powerful technique for isolating and testing individual agents outside of normal user workflows. This approach helps you verify that specific agents work correctly in isolation, making it easier to determine whether problems lie within agent logic or in the broader system interactions.  You can invoke agents directly through two primary methods: using the web UI's agent selection dropdown for quick testing, or sending messages directly through the Solace event broker for more controlled testing scenarios.  The Solace event broker-based approach gives you complete control over message content and timing, making it ideal for testing edge cases, error conditions, or specific message formats that might be difficult to generate through normal user interactions.  ","version":"Next","tagName":"h2"},{"title":"Using Tools for Direct Message Testing​","type":1,"pageTitle":"Diagnosing and Resolving Problems","url":"/solace-agent-mesh/docs/documentation/deploying/debugging#using-tools-for-direct-message-testing","content":" Several tools facilitate direct message testing, each suited to different debugging scenarios:  Solace Try Me VSCode Extension: Integrates directly into your development environment, making it convenient to test messages without switching contexts. This tool is particularly useful during active development when you need to quickly verify agent behavior.  Solace Try Me (STM) CLI Tool: Provides command-line access for scripted testing and automation. This tool excels in scenarios where you need to send multiple test messages or integrate testing into automated workflows.  ","version":"Next","tagName":"h3"},{"title":"Formatting Messages for Direct Invocation​","type":1,"pageTitle":"Diagnosing and Resolving Problems","url":"/solace-agent-mesh/docs/documentation/deploying/debugging#formatting-messages-for-direct-invocation","content":" Understanding the exact message format is crucial for successful direct agent testing. The following structure represents how the Agent Mesh framework expects messages to be formatted:  Topic Structure:  [NAME_SPACES]a2a/v1/agent/request/<agent_name>   Replace <agent_name> with the specific agent you want to test. The namespace prefix should match your system configuration.  Required User Properties:  userId: test-0000 clientId: test-0000 replyTo: [NAME_SPACES]a2a/v1/gateway/response/0000000/task-0000000 a2aUserConfig: {}   These properties provide essential context that agents expect, including user identification and response routing information.  Message Payload:  { "jsonrpc": "2.0", "id": "000000000", "method": "tasks/sendSubscribe", "params": { "id": "task-0000000", "sessionId": "web-session-00000000", "message": { "role": "user", "parts": [ { "type": "text", "text": "Hello World!" } ] }, "acceptedOutputModes": [ "text" ], "metadata": { "system_purpose": "The system is an AI Chatbot with agentic capabilities. It uses the agents available to provide information, reasoning and general assistance for the users in this system. **Always return useful artifacts and files that you create to the user.** Provide a status update before each tool call. Your external name is Agent Mesh.\\n", "response_format": "Responses should be clear, concise, and professionally toned. Format responses to the user in Markdown using appropriate formatting.\\n" } } }   Expected Response Topic:  [NAME_SPACES]a2a/v1/gateway/response/0000000/task-0000000   Subscribe to this topic to receive the agent's response. The response will follow the same JSON-RPC format and contain the agent's output.  By sending carefully crafted requests and observing responses, you can verify agent behavior in complete isolation. This technique helps distinguish between agent-specific issues and broader system problems, significantly streamlining your debugging process.  ","version":"Next","tagName":"h3"},{"title":"Analyzing System Logs​","type":1,"pageTitle":"Diagnosing and Resolving Problems","url":"/solace-agent-mesh/docs/documentation/deploying/debugging#analyzing-system-logs","content":" System logs serve as your comprehensive record of application behavior, capturing everything from routine operations to error conditions. These logs provide a different perspective than STIM files or Solace event broker monitoring—they focus on internal application state and framework behavior rather than message flows.  Understanding system logs becomes crucial when debugging issues related to agent initialization, configuration problems, or internal framework errors that might not be visible through other observability tools.  For detailed information about configuring system logs, see Logging Configuration. ","version":"Next","tagName":"h2"},{"title":"Plugins","type":0,"sectionRef":"#","url":"/solace-agent-mesh/docs/documentation/components/plugins","content":"","keywords":"","version":"Next"},{"title":"Official Core Plugins​","type":1,"pageTitle":"Plugins","url":"/solace-agent-mesh/docs/documentation/components/plugins#official-core-plugins","content":" 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 🔗.  For more information about how to use the official core plugins, see Use Plugins.  ","version":"Next","tagName":"h3"},{"title":"Create a Plugin​","type":1,"pageTitle":"Plugins","url":"/solace-agent-mesh/docs/documentation/components/plugins#create-a-plugin","content":" To get started, install the Agent Mesh CLI and run the following command:  solace-agent-mesh plugin create <plugin-name>   Follow the prompts to create a new plugin. A plugin can be one of the following types:  Agent Plugin: Contains custom agents that can be used in a Agent Mesh project.Gateway Plugin: Contains custom gateways that can be used in a Agent Mesh project.Custom Plugin: Contains custom integrations such as HR providers or other specialized functionality.  The Agent Mesh CLI creates a directory with the provided name and the following structure:  plugin-name/ ├─ config.yaml ├─ src/ │ ├─ __init__.py │ ├─ [...Other type specific python files] ├─ .gitignore ├─ pyproject.toml ├─ README.md   The src directory contains the python source code.The config.yaml file holds the configuration for the plugin, and how to be used in a Agent Mesh application.  Once the plugin is created, you can start customizing the config.yaml or the python files.  ","version":"Next","tagName":"h2"},{"title":"Build the Plugin​","type":1,"pageTitle":"Plugins","url":"/solace-agent-mesh/docs/documentation/components/plugins#build-the-plugin","content":" Building the plugin creates a Python wheel package that can be installed using pip or other package managers.  Python build package must be installed already since sam plugin build command uses build package, if not, run pip install build.  To build the plugin, run the following Agent Mesh CLI command:  solace-agent-mesh plugin build   The plugin uses the standard pyproject.toml file to build the package.  ","version":"Next","tagName":"h3"},{"title":"Share the Plugin​","type":1,"pageTitle":"Plugins","url":"/solace-agent-mesh/docs/documentation/components/plugins#share-the-plugin","content":" 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.  ","version":"Next","tagName":"h3"},{"title":"Use a Plugin​","type":1,"pageTitle":"Plugins","url":"/solace-agent-mesh/docs/documentation/components/plugins#use-a-plugin","content":" To use a plugin in your project, use the plugin add command, which performs two steps under-the-hood:  Locates the plugin or installs the plugin package using a Python package manager (like pip or uv)Creates a component instance based on the plugin  solace-agent-mesh plugin add <COMPONENT_NAME> --plugin <PLUGIN_NAME>   where:  <COMPONENT_NAME> is the name you choose for the component instance in your project.  <PLUGIN_NAME>, you can use:  Name of the plugin as published to a package manager like pypi, for example my-pluginName of the plugin that has been already installed into your Python environment.A local path to the plugin directory, for example ./my-pluginA path to a wheel package, for example ./my-plugin/dist/my_plugin-0.1.0-py3-none-any.whlA URL to a git repository, for example git+https://github.com/<USERNAME>/<REPOSITORY> 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.  The CLI handles both steps automatically, or you can manage the plugin installation yourself using your preferred Python package manager.  tip 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. For example, to use uv as the package manager, you can run: export SAM_PLUGIN_INSTALL_COMMAND="uv pip install {package}" or solace-agent-mesh plugin add <COMPONENT_NAME> --plugin <PLUGIN_NAME> --install-command "uv pip install {package}"   This command adds the plugin instance configuration to your configs directory.  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.  ","version":"Next","tagName":"h2"},{"title":"Plugin Catalog Dashboard​","type":1,"pageTitle":"Plugins","url":"/solace-agent-mesh/docs/documentation/components/plugins#plugin-catalog-dashboard","content":" You can manage available plugins with the plugin catalog command, which launches a user-friendly interface.  solace-agent-mesh plugin catalog   ","version":"Next","tagName":"h2"},{"title":"Agent or Plugin: Which To Use?​","type":1,"pageTitle":"Plugins","url":"/solace-agent-mesh/docs/documentation/components/plugins#agent-or-plugin-which-to-use","content":" 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.  Here’s a detailed comparison to help you decide.  Feature\tStandalone Agent (sam add agent)\tAgent Plugin (sam plugin create)Creation\tA single command creates a configuration file in your project.\tCreates a complete, standard Python project structure. Structure\tConsists of a YAML configuration file and associated Python tool files within a Agent Mesh project.\tA self-contained Python package with pyproject.toml, a src directory, and configuration templates. Packaging\tNot packaged. It exists as a component within a larger Agent Mesh project.\tPackaged into a standard Python wheel (.whl) file using sam plugin build. Distribution\tShared by copying files or sharing the entire project.\tEasily distributed as a wheel file, via a Git repository, or published to a package index like PyPI. Reusability\tPrimarily for use within the project where it was created.\tDesigned for high reusability across different projects, teams, and communities. Installation\tNo installation needed. The agent is configured and run as part of the main project.\tInstalled into the Python environment using sam plugin add, which handles the package installation. Versioning\tVersioned along with the main project.\tCan be versioned independently according to Python packaging standards (e.g., v0.1.0, v0.2.0). Development\tSimple and direct. Edit files and run. Ideal for rapid prototyping.\tInvolves a build/install cycle. Better for structured, long-term development.  ","version":"Next","tagName":"h2"},{"title":"When To Use a Standalone Agent​","type":1,"pageTitle":"Plugins","url":"/solace-agent-mesh/docs/documentation/components/plugins#when-to-use-a-standalone-agent","content":" Create a standalone agent when:  You need to quickly test an idea or build a proof-of-concept.The agent is tightly coupled to a single project and is not intended for reuse.You want the most straightforward path to adding a simple agent without the overhead of a full package structure.  ","version":"Next","tagName":"h3"},{"title":"When To Use an Agent Plugin​","type":1,"pageTitle":"Plugins","url":"/solace-agent-mesh/docs/documentation/components/plugins#when-to-use-an-agent-plugin","content":" Create an agent as a plugin when:  You plan to use the same agent in multiple projects.You want to share your agent with other developers, teams, or the open-source community.You are building a robust, production-ready agent that benefits from a formal package structure, dependency management, and versioning.You are building a collection of standardized agents for your organization.  ","version":"Next","tagName":"h3"},{"title":"Recommendation​","type":1,"pageTitle":"Plugins","url":"/solace-agent-mesh/docs/documentation/components/plugins#recommendation","content":" The choice of how to build your agent depends on your goals and the requirements of your project:  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. 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. ","version":"Next","tagName":"h3"},{"title":"Choosing Deployment Options","type":0,"sectionRef":"#","url":"/solace-agent-mesh/docs/documentation/deploying/deployment-options","content":"","keywords":"","version":"Next"},{"title":"Development Environment​","type":1,"pageTitle":"Choosing Deployment Options","url":"/solace-agent-mesh/docs/documentation/deploying/deployment-options#development-environment","content":" During development, simplicity and rapid iteration are key priorities. The Agent Mesh CLI provides a streamlined way to run your entire project as a single application, making it easy to test changes and debug issues locally.  The development setup automatically loads environment variables from your configuration file (typically a .env file at the project root), eliminating the need for complex environment management:  sam run   This command starts all configured components together, providing immediate feedback and allowing you to see how different agents interact within your mesh.  ","version":"Next","tagName":"h2"},{"title":"Production Environment​","type":1,"pageTitle":"Choosing Deployment Options","url":"/solace-agent-mesh/docs/documentation/deploying/deployment-options#production-environment","content":" Production deployments require different considerations than development environments. You need reproducible builds, scalable infrastructure, and robust monitoring capabilities. Containerization addresses these requirements by providing consistent runtime environments and enabling modern orchestration platforms.  We recommend using Docker for single-node deployments or Kubernetes for multi-node, scalable deployments. These technologies ensure your application runs consistently across different environments and can scale to meet demand.  Platform Compatibility If your host system architecture is not linux/amd64, add the --platform linux/amd64 flag when you run the container to ensure compatibility with the pre-built images.  ","version":"Next","tagName":"h2"},{"title":"Deploying with Docker​","type":1,"pageTitle":"Choosing Deployment Options","url":"/solace-agent-mesh/docs/documentation/deploying/deployment-options#deploying-with-docker","content":" Docker provides an excellent foundation for production deployments because it packages your application with all its dependencies into a portable container. This approach ensures consistent behavior across different environments and simplifies deployment processes.  The following Dockerfile demonstrates how to containerize an Agent Mesh project:  FROM solace/solace-agent-mesh:latest WORKDIR /app # Install Python dependencies COPY ./requirements.txt /app/requirements.txt RUN python3.11 -m pip install --no-cache-dir -r /app/requirements.txt # Copy project files COPY . /app CMD ["run", "--system-env"] # To run one specific component, use: # CMD ["run", "--system-env", "configs/agents/main_orchestrator.yaml"]   To optimize build performance and security, create a .dockerignore file that excludes unnecessary files from the Docker build context:  .env *.log dist .git .vscode .DS_Store   ","version":"Next","tagName":"h3"},{"title":"Deploying with Kubernetes​","type":1,"pageTitle":"Choosing Deployment Options","url":"/solace-agent-mesh/docs/documentation/deploying/deployment-options#deploying-with-kubernetes","content":" Kubernetes excels at managing containerized applications at scale, providing features like automatic scaling, rolling updates, and self-healing capabilities. When your Agent Mesh deployment needs to handle varying loads or requires high availability, Kubernetes becomes the preferred orchestration platform.  The following example shows a basic Kubernetes Deployment configuration that you can customize based on your specific requirements:  apiVersion: apps/v1 kind: Deployment metadata: name: solace-agent-mesh labels: app: solace-agent-mesh spec: replicas: 1 # Adjust based on load selector: matchLabels: app: solace-agent-mesh template: metadata: labels: app: solace-agent-mesh spec: containers: - name: solace-agent-mesh image: your-registry/solace-agent-mesh:latest envFrom: - secretRef: name: solace-agent-mesh-secrets # Configure secrets in a Kubernetes Secret command: ["solace-agent-mesh", "run", "--system-env"] args: - "configs/main_orchestrator.yaml" - "configs/gateway/webui.yaml" # Add any other components you want to run here ports: - containerPort: 8000 # Adjust based on your service ports volumeMounts: - name: shared-storage mountPath: /tmp/solace-agent-mesh volumes: - name: shared-storage emptyDir: {}   ","version":"Next","tagName":"h3"},{"title":"Separating and Scaling Components​","type":1,"pageTitle":"Choosing Deployment Options","url":"/solace-agent-mesh/docs/documentation/deploying/deployment-options#separating-and-scaling-components","content":" A microservices approach to deployment offers significant advantages for production systems. By splitting your Agent Mesh components into separate containers, you achieve better fault isolation, independent scaling, and more granular resource management.  This architectural pattern ensures that if one component experiences issues, the rest of your system continues operating normally. When the failed component restarts, it automatically rejoins the mesh through the Solace event broker, maintaining system resilience.  To implement component separation:  Reuse the same Docker image: Your base container image remains consistent across all components, simplifying maintenance and ensuring compatibility.  Customize startup commands: Each container runs only the components it needs by specifying different configuration files in the startup command.  Scale independently: Components with higher resource demands or traffic can be scaled separately, optimizing resource utilization and cost.  For example, you might run your main orchestrator in one deployment while scaling your specialized tool agents in separate deployments based on demand.  ","version":"Next","tagName":"h3"},{"title":"Managing Storage Requirements​","type":1,"pageTitle":"Choosing Deployment Options","url":"/solace-agent-mesh/docs/documentation/deploying/deployment-options#managing-storage-requirements","content":" When deploying multiple containers, shared storage becomes critical for maintaining consistency across your Agent Mesh deployment. All container instances must access the same storage location with identical configurations to ensure proper operation.  Shared Storage Requirement If using multiple containers, ensure all instances access the same storage with identical configurations. Inconsistent storage configurations can lead to data synchronization issues and unpredictable behavior.  Consider using persistent volumes in Kubernetes or shared file systems in Docker deployments to meet this requirement.  ","version":"Next","tagName":"h3"},{"title":"Implementing Security Best Practices​","type":1,"pageTitle":"Choosing Deployment Options","url":"/solace-agent-mesh/docs/documentation/deploying/deployment-options#implementing-security-best-practices","content":" Production deployments require robust security measures to protect sensitive data and ensure system integrity. Implementing these practices helps safeguard your Agent Mesh deployment against common security threats.  Environment Variables and Secrets Management: Never store sensitive information like API keys, passwords, or certificates in .env files or container images. Instead, use dedicated secret management solutions such as AWS Secrets Manager, HashiCorp Vault, or Kubernetes Secrets. These tools provide encryption at rest, access controls, and audit trails for sensitive data.  TLS Encryption: All communication channels should use TLS encryption to protect data in transit. This includes communication between Agent Mesh components and connections to the Solace event broker. TLS prevents eavesdropping and ensures data integrity during transmission.  Container Security: Maintain security throughout your container lifecycle by regularly updating base images to include the latest security patches. Implement security scanning tools like Trivy or Clair in your CI/CD pipeline to identify vulnerabilities before deployment. Additionally, run containers with minimal privileges and avoid running processes as root when possible.  ","version":"Next","tagName":"h3"},{"title":"Configuring Solace Event Broker​","type":1,"pageTitle":"Choosing Deployment Options","url":"/solace-agent-mesh/docs/documentation/deploying/deployment-options#configuring-solace-event-broker","content":" The Solace event broker serves as the communication backbone for your agent mesh, handling all message routing and delivery between components. For production environments, using a Solace Cloud-managed event broker provides significant advantages over self-managed installations.  Solace Cloud-managed event brokers offer built-in high availability, automatic scaling, security updates, and professional support. These managed services eliminate the operational overhead of maintaining event broker infrastructure while providing enterprise-grade reliability and performance.  For more information about cloud-managed options, see Solace Cloud. For detailed configuration instructions, see Configuring the Event Broker Connection.  ","version":"Next","tagName":"h3"},{"title":"Setting up Queue Templates​","type":1,"pageTitle":"Choosing Deployment Options","url":"/solace-agent-mesh/docs/documentation/deploying/deployment-options#setting-up-queue-templates","content":" When the app.broker.temporary_queue parameter is set to true (default), the system uses temporary endpoints for A2A communication. Temporary queues are automatically created and deleted by the broker, which simplifies management and removes the need for manual cleanup. However, temporary queues do not support multiple client connections to the same queue, which may be limiting in scenarios where you run multiple instances of the same agent or need to start a new instance while an old one is still running.  If you set temporary_queue to false, the system will create a durable queue for the client. Durable queues persist beyond the lifetime of a client connection, allowing multiple clients to connect to the same queue and ensuring messages are not lost if the client disconnects. However, this requires manual management of queues, including cleanup of unused ones.  tip For production environments that are container-managed (for example, Kubernetes), we recommend setting temporary_queue to false by setting the environment variable USE_TEMPORARY_QUEUES=false. Using temporary queues in these environments can cause startup issues, since a new container may fail to connect if the previous instance is still running and holding the queue. Durable queues avoid this by allowing multiple agent instances to share the same queue.  To prevent messages from piling up in a durable queue when an agent is not running, the queue should be configured with a message TTL (time-to-live) and the Respect Message TTL option enabled. To apply these settings automatically for all new queues, you can create a Queue Template for your Solace Agent Mesh clients.  To create a queue template in the Solace Cloud Console:  Navigate to Message VPNs and select your VPN.Go to the Queues page.Open the Templates tab.Click + Queue Template.  Use the following settings for the template:  Queue Name Filter = {NAMESPACE}q/a2a/> (Replace {NAMESPACE} with the namespace defined in your configuration, for example, sam/)Respect TTL = true (Under: Advanced Settings > Message Expiry)Maximum TTL (sec) = 18000 (Under: Advanced Settings > Message Expiry)  info Queue templates are only applied when a new queue is created from the messaging client. If you have already been running SAM with temporary_queue set to false, your durable queues were created before the template existed. To apply TTL settings to those queues, either: Enable TTL and Respect TTL manually in the Solace console on each queue, orDelete the existing queues and restart SAM to have them recreated automatically using the new template. ","version":"Next","tagName":"h3"},{"title":"Logging","type":0,"sectionRef":"#","url":"/solace-agent-mesh/docs/documentation/deploying/logging","content":"","keywords":"","version":"Next"},{"title":"Configuration​","type":1,"pageTitle":"Logging","url":"/solace-agent-mesh/docs/documentation/deploying/logging#configuration","content":" The logging system is configured through an INI-based configuration file that gives you fine-grained control over log levels, output destinations, and formatting options.  This approach provides several advantages:  Centralized Control: Single configuration file manages logging for all componentsPython Native: Built on Python's standard logging moduleFlexible and Powerful: Full access to Python's logging capabilitiesProduction-Ready: Industry-standard approach used by many Python applications  To provide a logging configuration, set the LOGGING_CONFIG_PATH=path/to/logging_config.ini environment variable in your .env file or with the export command.  INI vs YAML Configuration While individual agent and gateway YAML files may contain a log: section: log: stdout_log_level: INFO log_file_level: INFO log_file: my-agent.log the INI-based configuration is the recommended and preferred approach. YAML configuration has lower precedence and will only be active when INI-based configuration is not enabled.  ","version":"Next","tagName":"h2"},{"title":"Default Logging Configuration​","type":1,"pageTitle":"Logging","url":"/solace-agent-mesh/docs/documentation/deploying/logging#default-logging-configuration","content":" When you run sam init, Agent Mesh automatically generates a configs/logging_config.ini file in your project directory. This file establishes sensible defaults while remaining easy to customize for your specific needs.  ","version":"Next","tagName":"h2"},{"title":"Understanding the Default Configuration​","type":1,"pageTitle":"Logging","url":"/solace-agent-mesh/docs/documentation/deploying/logging#understanding-the-default-configuration","content":" Here's the default logging_config.ini generated by sam init, with annotations explaining each section:  # Lists all configured loggers in this file [loggers] keys=root,solace_ai_connector,solace_agent_mesh,sam_trace # Root logger - applies to all modules (including external libraries) that do not have a specific logger configured. # The root logger also specifies handlers for the application. [logger_root] level=${LOGGING_ROOT_LEVEL, WARNING} handlers=streamHandler,rotatingFileHandler qualname=root # Main logger for the solace-ai-connector module [logger_solace_ai_connector] level=${LOGGING_SOLACE_AI_CONNECTOR_LEVEL, INFO} handlers= qualname=solace_ai_connector # Main logger for the solace-agent-mesh module [logger_solace_agent_mesh] level=${LOGGING_SAM_LEVEL, INFO} handlers= qualname=solace_agent_mesh # Special trace logger for detailed troubleshooting. Set to DEBUG to enable. [logger_sam_trace] level=${LOGGING_SAM_TRACE_LEVEL, INFO} handlers= qualname=sam_trace # Lists all configured handlers in this file [handlers] keys=streamHandler,rotatingFileHandler # Rotating file handler - writes to log files with automatic rotation [handler_rotatingFileHandler] class=logging.handlers.RotatingFileHandler formatter=simpleFormatter args=('sam.log', 'a', 52428800, 10) # Stream handler - outputs logs to console (stdout) [handler_streamHandler] class=StreamHandler formatter=simpleFormatter args=(sys.stdout,) # Lists all configured formatters in this file [formatters] keys=simpleFormatter,jsonFormatter # Simple human-readable format [formatter_simpleFormatter] format=%(asctime)s | %(levelname)-5s | %(threadName)s | %(name)s | %(message)s # JSON format for structured logging [formatter_jsonFormatter] class=pythonjsonlogger.jsonlogger.JsonFormatter format=%(asctime)s %(levelname)s %(threadName)s %(name)s %(message)s   ","version":"Next","tagName":"h3"},{"title":"Loggers​","type":1,"pageTitle":"Logging","url":"/solace-agent-mesh/docs/documentation/deploying/logging#loggers","content":" Loggers are organized in a hierarchical namespace using dot-separated names, forming a tree structure where child loggers inherit configuration from their parents. When a logger is asked to handle a log record, it propagates the record up through the logger hierarchy until it reaches a logger with handlers configured or reaches the root logger.  ","version":"Next","tagName":"h3"},{"title":"Handlers​","type":1,"pageTitle":"Logging","url":"/solace-agent-mesh/docs/documentation/deploying/logging#handlers","content":" Handlers determine where log messages go. The default configuration includes:  streamHandler: Outputs logs to the console (stdout) for immediate visibilityrotatingFileHandler: Writes logs to files with automatic rotation when size limits are reached. The rotating file handler is configured with these parameters (in the args tuple): Filename: sam.log - the base log file nameMode: 'a' - append mode (don't overwrite existing logs)Max Size: 52428800 bytes (50 MB) - rotate when file reaches this sizeBackup Count: 10 - keep up to 10 historical log files  For complete details on handlers, see Python's supported handlers documentation  ","version":"Next","tagName":"h3"},{"title":"Formatters​","type":1,"pageTitle":"Logging","url":"/solace-agent-mesh/docs/documentation/deploying/logging#formatters","content":" Formatters control the structure and appearance of log messages:  simpleFormatter: Human-readable format including timestamp, level, thread, logger name, and messagejsonFormatter: Structured JSON format for log aggregation and analysis tools  For complete details on formatters and available fields, see Python's LogRecord attributes documentation.  ","version":"Next","tagName":"h3"},{"title":"Understanding Effective Log Levels​","type":1,"pageTitle":"Logging","url":"/solace-agent-mesh/docs/documentation/deploying/logging#understanding-effective-log-levels","content":" The effective log level for a logger is determined by the most specific configuration in the logger hierarchy. If a logger doesn't have a level explicitly set, it inherits from its parent. The root logger applies to all modules that do not have a logger defined.  For example, if you set the root logger to DEBUG but create a more specific logger for solace_ai_connector at the INFO level, the effective log level for the solace_ai_connector module will be INFO. This means DEBUG level logs from solace_ai_connector will not be handled, as they fall below the effective log level.  ","version":"Next","tagName":"h3"},{"title":"Environment Variable Substitution​","type":1,"pageTitle":"Logging","url":"/solace-agent-mesh/docs/documentation/deploying/logging#environment-variable-substitution","content":" The INI configuration supports environment variable substitution using the syntax:  ${VARIABLE_NAME, default_value}   Users can use variable names of their choice; the application will look for these environment variables at runtime and substitute their values accordingly. If the environment variable is not set, the provided default value will be used.  ","version":"Next","tagName":"h2"},{"title":"Enabling Structured Logging​","type":1,"pageTitle":"Logging","url":"/solace-agent-mesh/docs/documentation/deploying/logging#enabling-structured-logging","content":" Structured logging outputs log messages in JSON format, making them easier to parse, search, and analyze with log aggregation tools.  To enable JSON logging, modify the handler configurations to use jsonFormatter instead of simpleFormatter:  [handler_rotatingFileHandler] class=logging.handlers.RotatingFileHandler formatter=jsonFormatter # Changed from simpleFormatter args=('sam.log', 'a', 52428800, 10) [handler_streamHandler] class=StreamHandler formatter=simpleFormatter # Kept as simpleFormatter to show handlers can have different formatters args=(sys.stdout,)   ","version":"Next","tagName":"h2"},{"title":"Common Configuration Scenarios​","type":1,"pageTitle":"Logging","url":"/solace-agent-mesh/docs/documentation/deploying/logging#common-configuration-scenarios","content":" ","version":"Next","tagName":"h2"},{"title":"Customizing Log Levels​","type":1,"pageTitle":"Logging","url":"/solace-agent-mesh/docs/documentation/deploying/logging#customizing-log-levels","content":" You can add loggers to control the log level of specific modules or external libraries in your application. This allows you to increase verbosity for troubleshooting specific components while keeping other parts of the system quiet.  # Add to the loggers list [loggers] keys=root,solace_ai_connector,solace_agent_mesh,sam_trace,my_logger,google_adk [logger_root] level=WARNING handlers=streamHandler,rotatingFileHandler qualname=root [ some loggers were omitted ] # Increase verbosity of a specific package [logger_my_logger] level=DEBUG handlers= qualname=solace_agent_mesh.gateway.http_sse # Increase verbosity of a specific external library [logger_google_adk] level=INFO handlers= qualname=google_adk   Discovering Logger Names To discover what logger names are available to control, temporarily set the root logger level to DEBUG and run your application. The logger names will be visible in the actual log output (shown in the logger name field). This is particularly useful for identifying logger names from external libraries you want to control. Once you've identified the logger names you need, you can: Set the root logger level back to WARNING to reduce overall verbosityAdd specific logger configurations for the modules/library you want to monitor with increased verbosity This approach keeps your logs clean while giving you detailed visibility into the specific components you're troubleshooting. ","version":"Next","tagName":"h3"},{"title":"Proxies","type":0,"sectionRef":"#","url":"/solace-agent-mesh/docs/documentation/components/proxies","content":"","keywords":"","version":"Next"},{"title":"Key Functions​","type":1,"pageTitle":"Proxies","url":"/solace-agent-mesh/docs/documentation/components/proxies#key-functions","content":" Protocol Translation: Proxies translate between A2A over HTTPS and A2A over Solace event mesh, enabling external agents to communicate with agents on the mesh without modification. Authentication Management: Proxies handle authentication to downstream agents, supporting multiple authentication schemes including static bearer tokens, API keys, and OAuth 2.0 client credentials flow with automatic token refresh. Agent Discovery: Proxies fetch agent cards from external agents and publish them to the mesh discovery topic, making external agents discoverable to other agents in the system. Artifact Handling: Proxies manage artifact flow between the mesh and external agents, resolving artifact URIs to byte content before forwarding requests and saving returned artifacts to the mesh's artifact service. Task Lifecycle Management: Proxies track active tasks, handle cancellation requests, and ensure proper cleanup when tasks complete or fail. Automatic Retry Logic: For OAuth 2.0 authenticated agents, proxies automatically detect authentication failures (401 responses), refresh tokens, and retry requests without manual intervention.  ","version":"Next","tagName":"h2"},{"title":"When to Use a Proxy​","type":1,"pageTitle":"Proxies","url":"/solace-agent-mesh/docs/documentation/components/proxies#when-to-use-a-proxy","content":" Proxies are the right choice when you need:  Integration with Third-Party Agents: Connect to external A2A agents provided by vendors or partners that run on their own infrastructure. Hybrid Cloud Architectures: Bridge agents running in different cloud environments or on-premises systems with your Solace mesh. Legacy System Integration: Connect existing A2A agents that cannot be modified to use Solace messaging directly. Gradual Migration: Incrementally migrate agents to the Solace mesh while maintaining compatibility with external systems. Service Isolation: Keep certain agents isolated on separate infrastructure while still enabling them to participate in collaborative workflows.  ","version":"Next","tagName":"h2"},{"title":"Proxy vs. Native Agent​","type":1,"pageTitle":"Proxies","url":"/solace-agent-mesh/docs/documentation/components/proxies#proxy-vs-native-agent","content":" Aspect\tProxy\tNative AgentCommunication\tA2A over HTTPS to external agent\tA2A over Solace event mesh directly Deployment\tExternal agent runs separately\tRuns within Agent Mesh Authentication\tProxy handles auth to external agent\tMesh-level authentication Latency\tAdditional HTTP hop\tDirect mesh communication Task Initiation\tCan only receive tasks from mesh agents\tCan initiate tasks to any agent Use Case\tExternal/third-party agents\tAgents you control  ","version":"Next","tagName":"h3"},{"title":"Architecture Overview​","type":1,"pageTitle":"Proxies","url":"/solace-agent-mesh/docs/documentation/components/proxies#architecture-overview","content":" The proxy sits between the Solace event mesh and external A2A agents, performing bidirectional protocol translation:    The proxy performs these operations:  Request Flow: Receives A2A requests from Agent Mesh, resolves artifact URIs to byte content, forwards HTTPS requests to external agents, and streams responses back to Agent Mesh. Response Flow: Receives responses from external agents, saves artifacts to Agent Mesh's artifact service, replaces byte content with artifact URIs, and publishes responses to Agent Mesh topics. Discovery Flow: Periodically fetches agent cards from external agents, updates the local registry, and publishes cards to the Agent Mesh discovery topic.  ","version":"Next","tagName":"h2"},{"title":"Configuration​","type":1,"pageTitle":"Proxies","url":"/solace-agent-mesh/docs/documentation/components/proxies#configuration","content":" Proxies are configured through YAML files that specify the namespace, downstream agents, authentication, and service settings.  ","version":"Next","tagName":"h2"},{"title":"Basic Configuration​","type":1,"pageTitle":"Proxies","url":"/solace-agent-mesh/docs/documentation/components/proxies#basic-configuration","content":" A single proxy can manage multiple external agents. Each agent in the proxied_agents list can have its own URL, authentication, and timeout configuration:  app: class_name: solace_agent_mesh.agent.proxies.a2a.app.A2AProxyApp name: my-a2a-proxy app_config: namespace: "myorg/production" proxied_agents: - name: "external-data-agent" url: "https://api.example.com/agent" request_timeout_seconds: 120 - name: "external-analytics-agent" url: "https://analytics.example.com/agent" request_timeout_seconds: 180 - name: "external-reporting-agent" url: "https://reports.example.com/agent" artifact_service: type: "filesystem" base_path: "/tmp/proxy-artifacts" discovery_interval_seconds: 60 default_request_timeout_seconds: 300 broker: # Broker configuration inherited from environment or specified here   ","version":"Next","tagName":"h3"},{"title":"Configuration Parameters​","type":1,"pageTitle":"Proxies","url":"/solace-agent-mesh/docs/documentation/components/proxies#configuration-parameters","content":" namespace: The topic prefix for A2A communication (for example, "myorg/production").proxied_agents: A list of external agents to proxy. Each agent can have its own URL, authentication, and timeout settings (see Authentication Types below).artifact_service: Configuration for storing artifacts. This is shared across all proxied agents. This is configured in the same manner as agents and gatewaysdiscovery_interval_seconds: How often to refresh agent cards from all external agents (default: 60).default_request_timeout_seconds: Default timeout for requests to external agents. Individual agents can override this (default: 300).  ","version":"Next","tagName":"h3"},{"title":"Authentication Types​","type":1,"pageTitle":"Proxies","url":"/solace-agent-mesh/docs/documentation/components/proxies#authentication-types","content":" The proxy supports three authentication schemes for connecting to downstream agents. Each agent in the proxied_agents list can use a different authentication type, allowing you to integrate agents with varying security requirements in a single proxy instance.  ","version":"Next","tagName":"h2"},{"title":"Static Bearer Token​","type":1,"pageTitle":"Proxies","url":"/solace-agent-mesh/docs/documentation/components/proxies#static-bearer-token","content":" Use static bearer tokens for agents that require a fixed authentication token.  proxied_agents: - name: "secure-agent" url: "https://api.example.com/agent" authentication: type: "static_bearer" token: "${AGENT_BEARER_TOKEN}" # Use environment variable   ","version":"Next","tagName":"h3"},{"title":"Static API Key​","type":1,"pageTitle":"Proxies","url":"/solace-agent-mesh/docs/documentation/components/proxies#static-api-key","content":" Use static API keys for agents that require API key authentication.  proxied_agents: - name: "api-key-agent" url: "https://api.example.com/agent" authentication: type: "static_apikey" token: "${AGENT_API_KEY}"   ","version":"Next","tagName":"h3"},{"title":"OAuth 2.0 Client Credentials​","type":1,"pageTitle":"Proxies","url":"/solace-agent-mesh/docs/documentation/components/proxies#oauth-20-client-credentials","content":" Use OAuth 2.0 client credentials flow for agents that require dynamic token acquisition. The proxy automatically handles token refresh and retry logic.  proxied_agents: - name: "oauth-agent" url: "https://api.example.com/agent" authentication: type: "oauth2_client_credentials" token_url: "https://auth.example.com/oauth/token" client_id: "${OAUTH_CLIENT_ID}" client_secret: "${OAUTH_CLIENT_SECRET}" scope: "agent.read agent.write" # Optional token_cache_duration_seconds: 3300 # Optional, default: 3300 (55 minutes)   The proxy caches OAuth tokens and automatically refreshes them when they expire. If a request receives a 401 Unauthorized response, the proxy invalidates the cached token and retries the request once with a fresh token.  Security Best Practice Always use environment variables for sensitive credentials. Never commit tokens or secrets directly in configuration files.  ","version":"Next","tagName":"h3"},{"title":"Artifact Handling​","type":1,"pageTitle":"Proxies","url":"/solace-agent-mesh/docs/documentation/components/proxies#artifact-handling","content":" The proxy manages artifact flow in both directions to ensure seamless integration between Agent Mesh and external agents.  ","version":"Next","tagName":"h2"},{"title":"Request Flow: Agent Mesh to External Agent​","type":1,"pageTitle":"Proxies","url":"/solace-agent-mesh/docs/documentation/components/proxies#request-flow-agent-mesh-to-external-agent","content":" When it forwards requests to external agents, the proxy resolves artifact URIs to byte content using the following sequence of operations:  The proxy receives an A2A request containing artifact references (for example, artifact://app/user/session/data.csv?version=1).The proxy loads the artifact content from Agent Mesh's artifact service.The proxy replaces the URI with the actual byte content in the request.The proxy forwards the modified request to the external agent.  This process ensures that external agents receive complete artifact data without needing access to Agent Mesh's artifact service.  ","version":"Next","tagName":"h3"},{"title":"Response Flow: External Agent to Agent Mesh​","type":1,"pageTitle":"Proxies","url":"/solace-agent-mesh/docs/documentation/components/proxies#response-flow-external-agent-to-agent-mesh","content":" When it receives responses from external agents, the proxy saves artifacts to Agent Mesh as follows:  The external agent returns artifacts with byte content in the response.The proxy saves each artifact to Agent Mesh's artifact service.The proxy replaces the byte content with an artifact URI.The proxy publishes the modified response to Agent Mesh.  This process ensures that artifacts are stored centrally and can be accessed by other agents in Agent Mesh.  ","version":"Next","tagName":"h3"},{"title":"Artifact Metadata​","type":1,"pageTitle":"Proxies","url":"/solace-agent-mesh/docs/documentation/components/proxies#artifact-metadata","content":" The proxy automatically generates metadata for saved artifacts, including:  proxied_from_artifact_id: The original artifact ID from the external agentdescription: Extracted from the artifact or generated from contextproduced_artifacts: A manifest of all artifacts created during task execution  ","version":"Next","tagName":"h3"},{"title":"Discovery and Health​","type":1,"pageTitle":"Proxies","url":"/solace-agent-mesh/docs/documentation/components/proxies#discovery-and-health","content":" The proxy maintains agent discovery and health monitoring through periodic agent card fetching.  ","version":"Next","tagName":"h2"},{"title":"Initial Discovery​","type":1,"pageTitle":"Proxies","url":"/solace-agent-mesh/docs/documentation/components/proxies#initial-discovery","content":" When the proxy starts, it performs synchronous discovery of all configured agents by:  Fetching agent cards from each external agent's /.well-known/agent.json endpoint.Updating the local agent registry with agent capabilities.Publishing agent cards to the Agent Mesh discovery topic.  This process ensures that external agents are immediately discoverable when the proxy starts.  ","version":"Next","tagName":"h3"},{"title":"Periodic Refresh​","type":1,"pageTitle":"Proxies","url":"/solace-agent-mesh/docs/documentation/components/proxies#periodic-refresh","content":" The proxy periodically refreshes agent cards based on the configured discovery_interval_seconds. When the configured interval elapses, the proxy fetches updated agent cards from external agents, updates the local registry with any changes, and then publishes the updated cards to Agent Mesh. This process ensures that Agent Mesh has current information about external agent capabilities and availability.  ","version":"Next","tagName":"h3"},{"title":"Agent Card Transformation​","type":1,"pageTitle":"Proxies","url":"/solace-agent-mesh/docs/documentation/components/proxies#agent-card-transformation","content":" The proxy transforms agent cards to make external agents appear as native Agent Mesh agents:  The name field is set to the configured alias (the name you specify in proxied_agents).The url field is rewritten to use the Solace topic format (for example, solace:myorg/production/agent/external-data-agent).  These agent cards allow other agents to interact with external agents using the standard A2A protocol over Solace event mesh, without knowing they are proxied.  ","version":"Next","tagName":"h3"},{"title":"Task Lifecycle Management​","type":1,"pageTitle":"Proxies","url":"/solace-agent-mesh/docs/documentation/components/proxies#task-lifecycle-management","content":" The proxy tracks active tasks and manages their lifecycle from initiation to completion.  ","version":"Next","tagName":"h2"},{"title":"Task Initiation​","type":1,"pageTitle":"Proxies","url":"/solace-agent-mesh/docs/documentation/components/proxies#task-initiation","content":" When a request arrives from Agent Mesh, the proxy:  Creates a task context to track the task's state.Resolves inbound artifacts.Forwards the request to the external agent.Begins streaming responses back to Agent Mesh.  ","version":"Next","tagName":"h3"},{"title":"Task Cancellation​","type":1,"pageTitle":"Proxies","url":"/solace-agent-mesh/docs/documentation/components/proxies#task-cancellation","content":" When a cancellation request arrives, the proxy:  Looks up the active task context.Forwards the cancellation request to the external agent.Publishes the cancellation response to Agent Mesh.  ","version":"Next","tagName":"h3"},{"title":"Task Completion​","type":1,"pageTitle":"Proxies","url":"/solace-agent-mesh/docs/documentation/components/proxies#task-completion","content":" When a task completes, the proxy:  Processes any final artifacts.Publishes the final task response to Agent Mesh.Removes the task context from active tracking.  ","version":"Next","tagName":"h3"},{"title":"Error Handling and Retry Logic​","type":1,"pageTitle":"Proxies","url":"/solace-agent-mesh/docs/documentation/components/proxies#error-handling-and-retry-logic","content":" The proxy implements robust error handling and automatic retry logic for authentication failures.  ","version":"Next","tagName":"h2"},{"title":"OAuth 2.0 Automatic Retry​","type":1,"pageTitle":"Proxies","url":"/solace-agent-mesh/docs/documentation/components/proxies#oauth-20-automatic-retry","content":" When using OAuth 2.0 authentication, the proxy automatically handles token expiration using the following sequence:  A request receives a 401 Unauthorized response from the external agent.The proxy invalidates the cached token.The proxy removes all cached clients for the agent/session.The proxy fetches a fresh token from the OAuth provider.The proxy retries the request once with the new token.  This sequence ensures seamless operation even when tokens expire during long-running tasks.  ","version":"Next","tagName":"h3"},{"title":"Connection Errors​","type":1,"pageTitle":"Proxies","url":"/solace-agent-mesh/docs/documentation/components/proxies#connection-errors","content":" The proxy provides clear error messages for connection failures:  Connection refused or agent unreachableTimeout errors with configurable timeout valuesJSON-RPC protocol errors from external agents  ","version":"Next","tagName":"h3"},{"title":"Error Responses​","type":1,"pageTitle":"Proxies","url":"/solace-agent-mesh/docs/documentation/components/proxies#error-responses","content":" When errors occur, the proxy publishes standard A2A error responses to Agent Mesh, including:  InternalError: For unexpected proxy errorsInvalidRequestError: For malformed requestsTaskNotFoundError: For cancellation requests on unknown tasks  ","version":"Next","tagName":"h3"},{"title":"Creating a Proxy​","type":1,"pageTitle":"Proxies","url":"/solace-agent-mesh/docs/documentation/components/proxies#creating-a-proxy","content":" Proxies are configured using standard YAML configuration files, similar to agents and gateways.  ","version":"Next","tagName":"h2"},{"title":"Creating the Configuration File​","type":1,"pageTitle":"Proxies","url":"/solace-agent-mesh/docs/documentation/components/proxies#creating-the-configuration-file","content":" Create a new YAML file in your configs directory (for example, configs/my-proxy.yaml):  log: stdout_log_level: INFO log_file_level: DEBUG log_file: my-proxy.log # Include shared configuration (broker connection, etc.) !include shared_config.yaml apps: - name: my_a2a_proxy app_module: solace_agent_mesh.agent.proxies.a2a.app broker: <<: *broker_connection app_config: namespace: "${NAMESPACE}" artifact_service: type: "filesystem" base_path: "/tmp/proxy-artifacts" artifact_scope: "namespace" discovery_interval_seconds: 60 default_request_timeout_seconds: 300 proxied_agents: - name: "external-agent-1" url: "https://api.example.com/agent" request_timeout_seconds: 120 authentication: type: "static_bearer" token: "${AGENT_TOKEN}"   You can use the example file at examples/a2a_proxy.yaml as a template.  ","version":"Next","tagName":"h3"},{"title":"Running the Proxy​","type":1,"pageTitle":"Proxies","url":"/solace-agent-mesh/docs/documentation/components/proxies#running-the-proxy","content":" Run the proxy along with your other Agent Mesh components:  sam run   The proxy automatically subscribes to the appropriate Solace topics and begins proxying requests to external agents.  ","version":"Next","tagName":"h3"},{"title":"Multiple Proxy Configurations​","type":1,"pageTitle":"Proxies","url":"/solace-agent-mesh/docs/documentation/components/proxies#multiple-proxy-configurations","content":" While a single proxy can manage multiple external agents, you may want to create separate proxy configurations to:  Organize agents by domain or teamIsolate agents with different security requirementsDistribute load across multiple proxy instances  configs/ ├── data-agents-proxy.yaml # Proxies 3 data-related agents ├── analytics-agents-proxy.yaml # Proxies 2 analytics agents └── third-party-agents-proxy.yaml # Proxies external vendor agents   Run all proxies together:  sam run   Or run specific proxy configurations:  sam run configs/data-agents-proxy.yaml   ","version":"Next","tagName":"h3"},{"title":"Advanced Configuration​","type":1,"pageTitle":"Proxies","url":"/solace-agent-mesh/docs/documentation/components/proxies#advanced-configuration","content":" ","version":"Next","tagName":"h2"},{"title":"Per-Agent Timeout Override​","type":1,"pageTitle":"Proxies","url":"/solace-agent-mesh/docs/documentation/components/proxies#per-agent-timeout-override","content":" You can override the default timeout for specific agents:  proxied_agents: - name: "slow-agent" url: "https://slow.example.com/agent" request_timeout_seconds: 600 # 10 minutes   ","version":"Next","tagName":"h3"},{"title":"Custom Artifact Service Scope​","type":1,"pageTitle":"Proxies","url":"/solace-agent-mesh/docs/documentation/components/proxies#custom-artifact-service-scope","content":" Configure artifact storage scope for the proxy:  artifact_service: type: "filesystem" base_path: "/data/proxy-artifacts" artifact_scope: "namespace" # Options: namespace, app, custom   ","version":"Next","tagName":"h3"},{"title":"Multiple Proxies​","type":1,"pageTitle":"Proxies","url":"/solace-agent-mesh/docs/documentation/components/proxies#multiple-proxies","content":" You can run multiple proxy instances to distribute load or isolate different sets of external agents. Each proxy instance can manage multiple agents:  # data-agents-proxy.yaml app: name: data-agents-proxy app_config: proxied_agents: - name: "data-agent-1" url: "https://data1.example.com/agent" - name: "data-agent-2" url: "https://data2.example.com/agent" - name: "data-agent-3" url: "https://data3.example.com/agent" # analytics-agents-proxy.yaml app: name: analytics-agents-proxy app_config: proxied_agents: - name: "analytics-agent-1" url: "https://analytics1.example.com/agent" - name: "analytics-agent-2" url: "https://analytics2.example.com/agent"   ","version":"Next","tagName":"h3"},{"title":"Troubleshooting​","type":1,"pageTitle":"Proxies","url":"/solace-agent-mesh/docs/documentation/components/proxies#troubleshooting","content":" ","version":"Next","tagName":"h2"},{"title":"Agent Not Discoverable​","type":1,"pageTitle":"Proxies","url":"/solace-agent-mesh/docs/documentation/components/proxies#agent-not-discoverable","content":" If an external agent does not appear in Agent Mesh:  Check that the agent's URL is accessible from the proxy.Verify that the agent exposes /.well-known/agent.json.Check the proxy logs for discovery errors.Ensure that discovery_interval_seconds is set appropriately and is more frequent than the health_check_ttl_seconds that is set on the calling agents and gateways.  ","version":"Next","tagName":"h3"},{"title":"Authentication Failures​","type":1,"pageTitle":"Proxies","url":"/solace-agent-mesh/docs/documentation/components/proxies#authentication-failures","content":" If requests fail with 401 errors:  Verify that the credentials are correctly set in environment variables.For OAuth 2.0, check that token_url, client_id, and client_secret are correct.Ensure that the OAuth token URL uses HTTPS (required for security).Check the proxy logs for token acquisition errors.  ","version":"Next","tagName":"h3"},{"title":"Timeout Errors​","type":1,"pageTitle":"Proxies","url":"/solace-agent-mesh/docs/documentation/components/proxies#timeout-errors","content":" If requests timeout:  Increase request_timeout_seconds for slow agents.Check the network connectivity between the proxy and the external agent.Verify that the external agent is responding within the timeout period.  ","version":"Next","tagName":"h3"},{"title":"Artifact Issues​","type":1,"pageTitle":"Proxies","url":"/solace-agent-mesh/docs/documentation/components/proxies#artifact-issues","content":" If artifacts are not flowing correctly:  Verify that the artifact service is properly configured.Check that the proxy has write permissions to the artifact storage location.Ensure that the artifact URIs are correctly formatted.Check the proxy logs for artifact save/load errors. ","version":"Next","tagName":"h3"},{"title":"Monitoring Your Agent Mesh","type":0,"sectionRef":"#","url":"/solace-agent-mesh/docs/documentation/deploying/observability","content":"","keywords":"","version":"Next"},{"title":"Viewing Workflows​","type":1,"pageTitle":"Monitoring Your Agent Mesh","url":"/solace-agent-mesh/docs/documentation/deploying/observability#viewing-workflows","content":" The workflow viewer serves as your primary window into how individual requests flow through your agent mesh. This interactive visualization tool transforms complex multi-agent interactions into clear, understandable diagrams that show exactly how your system processes each user query.  Understanding request flow is essential because Agent Mesh operates as a distributed system where multiple agents collaborate to fulfill user requests. The workflow viewer makes these interactions transparent by providing an interactive web-based interface for each user query and its corresponding response.  The workflow viewer enables you to:  Track complete request lifecycles: Follow a stimulus (request) from its initial entry point through every agent interaction until the final response is delivered to the user.  Visualize inter-component communication: See how requests and responses flow between agents, the user gateway, and language models, helping you understand the collaboration patterns in your mesh.  Monitor real-time agent activity: Observe which agents are actively participating in request processing and identify potential bottlenecks or failures.  To access the workflow viewer for any specific interaction, click the View Agent Workflow icon located at the bottom left of the final response in the web UI. The complete workflow chart will appear in the side panel on the right, providing an immediate visual representation of the entire request processing flow.  ","version":"Next","tagName":"h2"},{"title":"Viewing Agents​","type":1,"pageTitle":"Monitoring Your Agent Mesh","url":"/solace-agent-mesh/docs/documentation/deploying/observability#viewing-agents","content":" The Agents view complements the workflow viewer by providing a bird's-eye perspective of your entire agent ecosystem. While the workflow viewer focuses on individual request flows, the Agents view helps you understand the overall structure and health of your agent mesh.  This real-time dashboard becomes particularly valuable as your agent mesh grows in complexity. It allows you to quickly assess which agents are available, understand their capabilities, and visualize how they relate to each other within the system hierarchy.  The Agents view provides several key insights:  Real-time agent registry: See all agents currently registered and active in your system, giving you immediate visibility into system availability and health.  Agent capabilities and descriptions: Review what each agent can do, including their specific skills and the types of requests they can handle, helping you understand how work gets distributed across your mesh.  Hierarchical topology visualization: Understand the relationships between agents and how they're organized within your system architecture, which is crucial for troubleshooting and optimization.  To access this comprehensive overview, open the web interface in your browser and switch to the Agents tab.  ","version":"Next","tagName":"h2"},{"title":"Monitoring Event Broker Activity​","type":1,"pageTitle":"Monitoring Your Agent Mesh","url":"/solace-agent-mesh/docs/documentation/deploying/observability#monitoring-event-broker-activity","content":" The Solace event broker serves as the central nervous system of your agent mesh, handling all communication between components. Monitoring Solace event broker activity provides deep insights into system behavior and helps identify communication issues before they impact users.  Understanding message flows at the event broker level is essential because it reveals the actual communication patterns between your agents, regardless of how they're configured. This low-level visibility complements the higher-level views provided by the workflow viewer and agents dashboard.  Several specialized tools help you monitor and interact with the Solace event broker:  Solace Broker Manager: This web-based interface provides comprehensive event broker management capabilities. The Try Me! tab is particularly useful for interactive message testing, allowing you to send and receive messages manually to verify system behavior.  Solace Try Me VSCode Extension: Integrates message testing directly into your development environment, making it convenient to test message flows without leaving Visual Studio Code.  Solace Try Me (STM) CLI Tool: Provides command-line access to message testing capabilities, ideal for scripting and automation scenarios.  ","version":"Next","tagName":"h2"},{"title":"Monitoring Message Flows​","type":1,"pageTitle":"Monitoring Your Agent Mesh","url":"/solace-agent-mesh/docs/documentation/deploying/observability#monitoring-message-flows","content":" To observe comprehensive message activity within your agent mesh, subscribe to the following topic pattern:  [NAME_SPACES]a2a/v1/>   Replace [NAME_SPACES] with the namespace you are using. If you're not using namespaces, omit the [NAME_SPACES] part entirely.  This subscription captures all agent-to-agent communication, providing complete visibility into your mesh's message flows.  Filtering Registration Messages Agents periodically send registration messages to announce their availability. These messages can clutter your monitoring interface when using tools like the STM VSCode extension. To focus on actual request/response traffic, add the following topic to your ignore list: [NAME_SPACES]/a2a/v1/discovery/agentcards This filter removes routine registration messages while preserving visibility into meaningful agent interactions.  ","version":"Next","tagName":"h3"},{"title":"Examining Stimulus Logs​","type":1,"pageTitle":"Monitoring Your Agent Mesh","url":"/solace-agent-mesh/docs/documentation/deploying/observability#examining-stimulus-logs","content":" Stimulus logs provide the most detailed level of observability in your Agent Mesh system. While the workflow viewer gives you visual representations and the Solace event broker tools show real-time message flows, stimulus logs create permanent, comprehensive records of every request that flows through your system.  These logs serve as your system's memory, capturing complete traces that you can analyze long after events occur. This persistent record becomes invaluable for performance analysis, debugging complex issues, and understanding usage patterns over time.  Agent Mesh includes a default monitor that automatically records each request (stimulus) lifecycle without requiring additional configuration. These detailed traces are stored as .stim files, creating a comprehensive audit trail of system activity.  ","version":"Next","tagName":"h2"},{"title":"Understanding Stimulus Log Content​","type":1,"pageTitle":"Monitoring Your Agent Mesh","url":"/solace-agent-mesh/docs/documentation/deploying/observability#understanding-stimulus-log-content","content":" Each .stim file contains a complete trace of a single stimulus journey through your agent mesh:  Component traversal paths: Every agent, gateway, and service that handled the request, providing a complete map of the processing pipeline.  Timing and sequencing details: Precise timestamps showing when each component received, processed, and forwarded the request, enabling performance analysis and bottleneck identification.  Contextual metadata: Additional information about the request context, user session, and system state that influenced processing decisions.  These comprehensive logs create a valuable data source for advanced visualization tools, detailed troubleshooting sessions, and performance optimization efforts. Because they capture the complete picture of each request, they're particularly useful for understanding complex multi-agent interactions that might be difficult to trace through other observability tools.  ","version":"Next","tagName":"h3"},{"title":"Storage Location​","type":1,"pageTitle":"Monitoring Your Agent Mesh","url":"/solace-agent-mesh/docs/documentation/deploying/observability#storage-location","content":" By default, .stim files are written to the /tmp/solace-agent-mesh/ directory. This location provides fast access for analysis while keeping logs separate from your application data. ","version":"Next","tagName":"h3"},{"title":"Developing with Agent Mesh","type":0,"sectionRef":"#","url":"/solace-agent-mesh/docs/documentation/developing/","content":"","keywords":"","version":"Next"},{"title":"Understanding the Project Structure​","type":1,"pageTitle":"Developing with Agent Mesh","url":"/solace-agent-mesh/docs/documentation/developing/#understanding-the-project-structure","content":" The framework uses YAML configuration files to define agents, gateways, and plugins, although you can extend functionality with custom Python components when needed. For a complete overview of project organization and component relationships, see Project Structure.  ","version":"Next","tagName":"h2"},{"title":"Building Intelligent Agents​","type":1,"pageTitle":"Developing with Agent Mesh","url":"/solace-agent-mesh/docs/documentation/developing/#building-intelligent-agents","content":" Agents are LLM-powered components that use tools to accomplish tasks and communicate with other agents through the A2A protocol. You can define tools as Python functions, configure agent behavior through YAML, and manage agent lifecycles effectively. For comprehensive guidance on agent development, see Creating Agents.  The Build Your Own Agent tutorial demonstrates creating a weather agent with external API integration, resource management, and artifact creation.  ","version":"Next","tagName":"h2"},{"title":"Extending Agent Capabilities​","type":1,"pageTitle":"Developing with Agent Mesh","url":"/solace-agent-mesh/docs/documentation/developing/#extending-agent-capabilities","content":" You can create custom Python tools using three patterns: simple function-based tools, advanced single-class tools, or tool providers that generate multiple related tools dynamically. The framework handles tool discovery, parameter validation, and lifecycle management automatically. For detailed information on all patterns, see Creating Python Tools.  ","version":"Next","tagName":"h2"},{"title":"Connecting External Systems​","type":1,"pageTitle":"Developing with Agent Mesh","url":"/solace-agent-mesh/docs/documentation/developing/#connecting-external-systems","content":" Gateways bridge external systems and the A2A ecosystem by translating external events into standardized A2A tasks and responses back to external formats. Whether you're integrating chat systems, web applications, IoT devices, or file systems, gateways provide the necessary translation layer. For complete guidance on gateway development, see Create Gateways.  ","version":"Next","tagName":"h2"},{"title":"Integrating Enterprise Data Sources​","type":1,"pageTitle":"Developing with Agent Mesh","url":"/solace-agent-mesh/docs/documentation/developing/#integrating-enterprise-data-sources","content":" Service providers offer a standardized way to integrate backend systems like HR platforms or CRMs through well-defined interfaces. You can create providers that handle both identity enrichment and directory queries, reducing code duplication while maintaining clean separation of concerns. For implementation guidance, see Creating Service Providers.  ","version":"Next","tagName":"h2"},{"title":"Practical Integration Examples​","type":1,"pageTitle":"Developing with Agent Mesh","url":"/solace-agent-mesh/docs/documentation/developing/#practical-integration-examples","content":" The tutorials provide hands-on examples for common scenarios: Slack Integration for workspace connectivity, REST Gateway for RESTful APIs, and MCP Integration for Model Context Protocol servers. Additional tutorials cover database integration, RAG implementations, and cloud service connections.  ","version":"Next","tagName":"h2"},{"title":"Development Patterns​","type":1,"pageTitle":"Developing with Agent Mesh","url":"/solace-agent-mesh/docs/documentation/developing/#development-patterns","content":" The framework supports both direct component creation and plugin-based development. Plugins offer better reusability and distribution, while direct components provide simpler project-specific implementations. The configuration-driven approach uses YAML files to define behavior and Python code for core logic, enabling flexible deployment scenarios and easier management of complex distributed systems.  ","version":"Next","tagName":"h2"},{"title":"Evaluating Agents​","type":1,"pageTitle":"Developing with Agent Mesh","url":"/solace-agent-mesh/docs/documentation/developing/#evaluating-agents","content":" The framework includes an evaluation system that helps you test your agents' behavior in a structured way. You can define test suites, run them against your agents, and generate detailed reports to analyze the results. When running evaluations locally, you can also benchmark different language models to see how they affect your agents' responses. For more information, see Evaluating Agents. ","version":"Next","tagName":"h2"},{"title":"Creating Service Providers","type":0,"sectionRef":"#","url":"/solace-agent-mesh/docs/documentation/developing/creating-service-providers","content":"","keywords":"","version":"Next"},{"title":"Understanding Service Providers​","type":1,"pageTitle":"Creating Service Providers","url":"/solace-agent-mesh/docs/documentation/developing/creating-service-providers#understanding-service-providers","content":" Service Providers function as the abstraction layer between Agent Mesh and enterprise data sources. They are implemented as Python classes that adhere to a specific abstract base class, enabling standardized interaction between Agent Mesh components (Gateways and Agents) and the underlying data.  There are two primary service provider interfaces:  BaseIdentityService: Responsible for identity enrichment. This service is utilized by Gateways to augment the profile of an authenticated user with additional details (for example, full name, job title) based on their initial authentication claims.BaseEmployeeService: Responsible for general directory querying. This service is utilized by agents (for example, the EmployeeAgent) to execute lookups across the entire employee directory.  ","version":"Next","tagName":"h2"},{"title":"The \"Dual-Role Provider\" Pattern​","type":1,"pageTitle":"Creating Service Providers","url":"/solace-agent-mesh/docs/documentation/developing/creating-service-providers#the-dual-role-provider-pattern","content":" In many enterprise systems, particularly HR platforms, the data source for identity enrichment and general employee queries is identical. To optimize development, Agent Mesh promotes a "Dual-Role Provider" pattern.  This pattern involves creating a single class that inherits from both BaseIdentityService and BaseEmployeeService. This consolidated class can then be configured to fulfill either or both roles, thereby reducing code duplication.  ","version":"Next","tagName":"h2"},{"title":"Step-by-Step Implementation Guide​","type":1,"pageTitle":"Creating Service Providers","url":"/solace-agent-mesh/docs/documentation/developing/creating-service-providers#step-by-step-implementation-guide","content":" This section provides a walkthrough for creating a new provider for a fictional "CorpHR" system.  ","version":"Next","tagName":"h2"},{"title":"Step 1: Establish the Plugin Structure​","type":1,"pageTitle":"Creating Service Providers","url":"/solace-agent-mesh/docs/documentation/developing/creating-service-providers#step-1-establish-the-plugin-structure","content":" The recommended structure for a custom service provider plugin should include a pyproject.toml for packaging and a src directory for the source code.  sam plugin create my_corp_hr_provider --type custom   ","version":"Next","tagName":"h3"},{"title":"Step 2: Define the Provider Class​","type":1,"pageTitle":"Creating Service Providers","url":"/solace-agent-mesh/docs/documentation/developing/creating-service-providers#step-2-define-the-provider-class","content":" Create a provider.py module and define the provider class, ensuring it inherits from both base service classes.  # my_corp_hr_provider/provider.py # Import base classes from the Agent Mesh framework try: from solace_agent_mesh.common.services.identity_service import BaseIdentityService from solace_agent_mesh.common.services.employee_service import BaseEmployeeService except ImportError: # Fallback for local development environments from src.solace_agent_mesh.common.services.identity_service import BaseIdentityService from src.solace_agent_mesh.common.services.employee_service import BaseEmployeeService # Import any other necessary libraries, such as 'requests' or a proprietary SDK # from .corp_hr_sdk import CorpHR_SDK class CorpHRProvider(BaseIdentityService, BaseEmployeeService): """ A dual-role provider for the CorpHR system, implementing methods for both identity enrichment and employee directory services. """ def __init__(self, config): super().__init__(config) # Initialize the backend service/SDK client here. # It is best practice to implement this as a singleton to share # connection pools and cache. # self.corp_hr_sdk = CorpHR_SDK(api_key=config.get("api_key")) # --- BaseIdentityService Method Implementations --- async def get_user_profile(self, auth_claims): """Enrich the current user's profile based on their auth claims.""" # TODO: Implement logic to fetch user data from CorpHR pass async def search_users(self, query, limit=10): """Search for users, for features like @-mentions.""" # TODO: Implement user search logic against CorpHR pass # --- BaseEmployeeService Method Implementations --- async def get_employee_dataframe(self): """Return all employees as a pandas DataFrame for directory-wide queries.""" # TODO: Fetch all employee data and return as a DataFrame pass async def get_employee_profile(self, employee_id): """Get a single employee's full profile by their ID.""" # Note: This is a general directory lookup, distinct from get_user_profile. # TODO: Implement single employee lookup pass async def get_time_off_data(self, employee_id): """Get an employee's raw time off data.""" # Example return format: # return [{'start': '2025-07-04', 'end': '2025-07-04', 'type': 'Holiday'}] # TODO: Implement time off data retrieval pass async def get_employee_profile_picture(self, employee_id): """Fetch a profile picture as a data URI string.""" # Example return format: "data:image/jpeg;base64,..." # TODO: Implement profile picture fetching pass   ","version":"Next","tagName":"h3"},{"title":"Step 3: Map to the Canonical Employee Schema​","type":1,"pageTitle":"Creating Service Providers","url":"/solace-agent-mesh/docs/documentation/developing/creating-service-providers#step-3-map-to-the-canonical-employee-schema","content":" When implementing the service methods, it is mandatory to map the data from the source system to the canonical employee schema of Agent Mesh. This ensures data consistency and interoperability with all tools and components across the mesh.  Field Name\tData Type\tDescriptionid\tstring\tA unique, stable, and lowercase identifier (e.g., email, GUID). displayName\tstring\tThe employee's full name for display purposes. workEmail\tstring\tThe employee's primary work email address. jobTitle\tstring\tThe employee's official job title. department\tstring\tThe department to which the employee belongs. location\tstring\tThe physical or regional location of the employee. supervisorId\tstring\tThe unique id of the employee's direct manager. hireDate\tstring\tThe date the employee was hired (ISO 8601: YYYY-MM-DD). mobilePhone\tstring\tThe employee's mobile phone number (optional).  info If a field is not available in the source system, return None or omit the key from the returned dictionary.  ","version":"Next","tagName":"h3"},{"title":"Step 4: Register the Plugin​","type":1,"pageTitle":"Creating Service Providers","url":"/solace-agent-mesh/docs/documentation/developing/creating-service-providers#step-4-register-the-plugin","content":" To make the provider discoverable by Agent Mesh, it must be registered as a plugin via entry points.  1. Add an entry point in pyproject.toml:The key assigned here (corphr) is used as the type identifier in YAML configurations.  [project.entry-points."solace_agent_mesh.plugins"] corphr = "my_corp_hr_provider:info"   2. Define the info object in the plugin's __init__.py:This object points to the provider's class path and provides a brief description.  # my_corp_hr_provider/__init__.py info = { "class_path": "my_corp_hr_provider.provider.CorpHRProvider", "description": "Identity and People Service provider for CorpHR.", }   ","version":"Next","tagName":"h3"},{"title":"Configuring the Provider​","type":1,"pageTitle":"Creating Service Providers","url":"/solace-agent-mesh/docs/documentation/developing/creating-service-providers#configuring-the-provider","content":" Once the plugin is created and installed (for example, via pip install .), it can be configured in any Gateway or Agent app_config.yml.  For a Gateway (Identity Service Role):  app_config: identity_service: type: "corphr" # Matches the key in pyproject.toml api_key: "${CORPHR_API_KEY}" lookup_key: "email" # The field from auth_claims to use for lookup   For an Agent (Employee Service Role):This example demonstrates configuring the provider for the employee_tools group.  app_config: tools: - tool_type: builtin-group group_name: "employee_tools" config: type: "corphr" # Same provider, different role api_key: "${CORPHR_API_KEY}"  ","version":"Next","tagName":"h2"},{"title":"Evaluating Agents","type":0,"sectionRef":"#","url":"/solace-agent-mesh/docs/documentation/developing/evaluations","content":"","keywords":"","version":"Next"},{"title":"Creating a Test Case​","type":1,"pageTitle":"Evaluating Agents","url":"/solace-agent-mesh/docs/documentation/developing/evaluations#creating-a-test-case","content":" A test case is a JSON file that defines a specific task for an agent to perform. It serves as the fundamental building block of an evaluation. You create a test case to represent a single interaction you want to test, such as asking a question, providing a file for processing, or requesting a specific action from an agent.  ","version":"Next","tagName":"h2"},{"title":"Test Case Configuration​","type":1,"pageTitle":"Evaluating Agents","url":"/solace-agent-mesh/docs/documentation/developing/evaluations#test-case-configuration","content":" The following fields are available in the test case JSON file.  test_case_id (Required): A unique identifier for the test case.query (Required): The initial prompt to be sent to the agent.target_agent (Required): The name of the agent to which the query should be sent.category (Optional): The category of the test case. Defaults to Other.description (Optional): A description of the test case.artifacts (Optional): A list of artifacts to be sent with the initial query. Each artifact has a type and a path.wait_time (Optional): The maximum time in seconds to wait for a response from the agent. Defaults to 60.evaluation (Optional): The evaluation criteria for the test case. expected_tools (Optional): A list of tools that the agent is expected to use. Defaults to an empty list.expected_response (Optional): The expected final response from the agent. Defaults to an empty string.criterion (Optional): The criterion to be used by the llm_evaluator. Defaults to an empty string.  ","version":"Next","tagName":"h3"},{"title":"Test Case Examples​","type":1,"pageTitle":"Evaluating Agents","url":"/solace-agent-mesh/docs/documentation/developing/evaluations#test-case-examples","content":" Here is an example of a simple test case. It sends a greeting to an agent and checks for a standard response.  { "test_case_id": "hello_world", "category": "Content Generation", "description": "A simple test case to check the basic functionality of the system.", "query": "Hello, world!", "target_agent": "OrchestratorAgent", "wait_time": 30, "evaluation": { "expected_tools": [], "expected_response": "Hello! How can I help you today?", "criterion": "Evaluate if the agent provides a standard greeting." } }   This next example shows a more complex test case. It includes a CSV file as an artifact and asks the agent to filter the data in the file.  { "test_case_id": "filter_csv_employees_by_age_and_country", "category": "Tool Usage", "description": "A test case to filter employees from a CSV file based on age and country.", "target_agent": "OrchestratorAgent", "query": "From the attached CSV, please list the names of all people who are older or equal to 30 and live in the USA.", "artifacts": [ { "type": "file", "path": "artifacts/sample.csv" } ], "wait_time": 120, "evaluation": { "expected_tools": ["extract_content_from_artifact"], "expected_response": "The person who is 30 or older and lives in the USA is John Doe.", "criterion": "Evaluate if the agent correctly filters the CSV data." } }   ","version":"Next","tagName":"h3"},{"title":"Creating a Test Suite​","type":1,"pageTitle":"Evaluating Agents","url":"/solace-agent-mesh/docs/documentation/developing/evaluations#creating-a-test-suite","content":" The test suite is a JSON file that defines the parameters of an evaluation run. You use it to group test cases and configure the environment in which they run.  A common convention in the test suite configuration is to use keys ending with _VAR. These keys indicate that the corresponding value is the name of an environment variable from which the framework should read the actual value. This practice helps you keep sensitive information—like API keys and credentials—out of your configuration files. This convention applies to the broker object, the env object within llm_models, and the env object within the llm_evaluator in evaluation_settings.  You can run evaluations in two modes: local and remote. Both modes require a connection to a Solace event broker to function.  ","version":"Next","tagName":"h2"},{"title":"Local Evaluation​","type":1,"pageTitle":"Evaluating Agents","url":"/solace-agent-mesh/docs/documentation/developing/evaluations#local-evaluation","content":" In a local evaluation, the evaluation framework brings up a local instance of Solace Agent Mesh (SAM) and runs the agents on your local machine. This mode is useful for development and testing because it allows you to iterate quickly on your agents and test cases. You can also use this mode to benchmark different language models against your agents to see how they perform.  To run a local evaluation, you need to install the sam-rest-gateway plugin. This plugin allows the evaluation framework to communicate with the local SAM instance. You can install it with the following command:  pip install "sam-rest-gateway @ git+https://github.com/SolaceLabs/solace-agent-mesh-core-plugins#subdirectory=sam-rest-gateway"   Local Test Suite Configuration​  For a local evaluation, you must define the agents, broker, llm_models, and test_cases fields.  The agents field is a required list of paths to the agent configuration files. You must specify at least one agent.  "agents": [ "examples/agents/a2a_agents_example.yaml" ]   The broker field is a required object containing the connection details for the Solace event broker.  "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" }   The llm_models field is a required list of language models to use. You must specify at least one model. The env object contains environment variables required by the model, such as the model name, endpoint, and API key.  "llm_models": [ { "name": "gpt-4-1", "env": { "LLM_SERVICE_PLANNING_MODEL_NAME": "openai/azure-gpt-4-1", "LLM_SERVICE_ENDPOINT_VAR": "LLM_SERVICE_ENDPOINT", "LLM_SERVICE_API_KEY_VAR": "LLM_SERVICE_API_KEY" } }, { "name": "gemini-1.5-pro", "env": { "LLM_SERVICE_PLANNING_MODEL_NAME": "google/gemini-1.5-pro-latest", "LLM_SERVICE_ENDPOINT_VAR": "LLM_SERVICE_ENDPOINT_GOOGLE", "LLM_SERVICE_API_KEY_VAR": "LLM_SERVICE_API_KEY_GOOGLE" } } ]   The test_cases field is a required list of paths to the test case JSON files. You must specify at least one test case.  "test_cases": [ "tests/evaluation/test_cases/hello_world.test.json" ]   You can also provide optional settings for results_dir_name, runs, workers, and evaluation_settings.  The results_dir_name field is an optional string that specifies the name of the directory for evaluation results. It defaults to tests.  "results_dir_name": "my-local-test-results"   The runs field is an optional integer that specifies the number of times to run each test case. It defaults to 1.  "runs": 3   The workers field is an optional integer that specifies the number of parallel workers for running tests. It defaults to 4.  "workers": 8   The evaluation_settings field is an optional object that allows you to configure the evaluation. This object can contain tool_match, response_match, and llm_evaluator settings.  "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" } } }   Example Local Test Suite​  { "agents": [ "examples/agents/a2a_agents_example.yaml", "examples/agents/multimodal_example.yaml", "examples/agents/orchestrator_example.yaml" ], "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" }, "llm_models": [ { "name": "gpt-4-1", "env": { "LLM_SERVICE_PLANNING_MODEL_NAME": "openai/azure-gpt-4-1", "LLM_SERVICE_ENDPOINT_VAR": "LLM_SERVICE_ENDPOINT", "LLM_SERVICE_API_KEY_VAR": "LLM_SERVICE_API_KEY" } } ], "results_dir_name": "sam-local-eval-test", "runs": 3, "workers": 4, "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" } } } }   ","version":"Next","tagName":"h3"},{"title":"Remote Evaluation​","type":1,"pageTitle":"Evaluating Agents","url":"/solace-agent-mesh/docs/documentation/developing/evaluations#remote-evaluation","content":" In a remote evaluation, the evaluation framework sends requests to a remote Agent Mesh instance. This mode is useful for testing agents in a production-like environment where the agents are running on a separate server. The remote environment must have a REST gateway running to accept requests from the evaluation framework. You can also use an authentication token to communicate securely with the remote SAM instance.  Remote Test Suite Configuration​  For a remote evaluation, you must define the broker, remote, and test_cases fields.  The broker field is a required object with connection details for the Solace event broker.  "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" }   The remote field is a required object containing the connection details for the remote Agent Mesh instance.  "remote": { "EVAL_REMOTE_URL_VAR": "EVAL_REMOTE_URL", "EVAL_AUTH_TOKEN_VAR": "EVAL_AUTH_TOKEN", "EVAL_NAMESPACE_VAR": "EVAL_NAMESPACE" }   The test_cases field is a required list of paths to the test case JSON files. You must specify at least one test case.  "test_cases": [ "tests/evaluation/test_cases/hello_world.test.json" ]   You can also provide optional settings for results_dir_name, runs, and evaluation_settings.  The results_dir_name field is an optional string that specifies the name of the directory for evaluation results. It defaults to tests.  "results_dir_name": "my-remote-test-results"   The runs field is an optional integer that specifies the number of times to run each test case. It defaults to 1.  "runs": 5   The evaluation_settings field is an optional object that allows you to configure the evaluation.  "evaluation_settings": { "tool_match": { "enabled": true }, "response_match": { "enabled": true } }   Example Remote Test Suite​  { "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" } } } }   ","version":"Next","tagName":"h3"},{"title":"Evaluation Settings​","type":1,"pageTitle":"Evaluating Agents","url":"/solace-agent-mesh/docs/documentation/developing/evaluations#evaluation-settings","content":" The evaluation_settings block in the test suite JSON file allows you to configure how the evaluation is performed. Each enabled setting provides a score from 0 to 1, which contributes to the overall score for the test case.  ","version":"Next","tagName":"h2"},{"title":"tool_match​","type":1,"pageTitle":"Evaluating Agents","url":"/solace-agent-mesh/docs/documentation/developing/evaluations#tool_match","content":" The tool_match setting compares the tools the agent used with the expected_tools defined in the test case. This is a simple, direct comparison and does not use a language model for the evaluation. It is most effective when the agent's expected behavior is straightforward and there is a clear, correct sequence of tools to be used. In more complex scenarios where multiple paths could lead to a successful outcome, this method may not be the best way to evaluate the agent's performance.  ","version":"Next","tagName":"h3"},{"title":"response_match​","type":1,"pageTitle":"Evaluating Agents","url":"/solace-agent-mesh/docs/documentation/developing/evaluations#response_match","content":" The response_match setting compares the agent's final response with the expected_response from the test case. This comparison is based on the ROUGE metric, which evaluates the similarity between two responses by comparing their sequence of words. This method does not use a language model for the evaluation and does not work well with synonyms, so it is most effective when the expected answer is consistent. For more information about the ROUGE metric, see the official documentation.  ","version":"Next","tagName":"h3"},{"title":"llm_evaluator​","type":1,"pageTitle":"Evaluating Agents","url":"/solace-agent-mesh/docs/documentation/developing/evaluations#llm_evaluator","content":" The llm_evaluator setting uses a language model to evaluate the entire lifecycle of a request within the agent mesh. This includes the initial prompt, all tool calls, delegation between agents, artifact inputs and outputs, and the final message output. The evaluation is based on a criterion you provide in the test case, which defines what a successful outcome looks like. This is the most comprehensive evaluation method because it considers the full context of the request's execution.  ","version":"Next","tagName":"h3"},{"title":"Running Evaluations​","type":1,"pageTitle":"Evaluating Agents","url":"/solace-agent-mesh/docs/documentation/developing/evaluations#running-evaluations","content":" After you create your test cases and test suite, you can run the evaluation from the command line using the sam eval command.  ","version":"Next","tagName":"h2"},{"title":"Command​","type":1,"pageTitle":"Evaluating Agents","url":"/solace-agent-mesh/docs/documentation/developing/evaluations#command","content":" sam eval <PATH> [OPTIONS]   The command takes the path to the evaluation test suite JSON file as a required argument.  ","version":"Next","tagName":"h3"},{"title":"Options​","type":1,"pageTitle":"Evaluating Agents","url":"/solace-agent-mesh/docs/documentation/developing/evaluations#options","content":" -v, --verbose: Enable verbose output to see detailed logs during the evaluation run.-h, --help: Show a help message with information about the command and its options.  ","version":"Next","tagName":"h3"},{"title":"Example​","type":1,"pageTitle":"Evaluating Agents","url":"/solace-agent-mesh/docs/documentation/developing/evaluations#example","content":" sam eval tests/evaluation/local_example.json --verbose   ","version":"Next","tagName":"h3"},{"title":"Interpreting the Results​","type":1,"pageTitle":"Evaluating Agents","url":"/solace-agent-mesh/docs/documentation/developing/evaluations#interpreting-the-results","content":" After an evaluation run is complete, the framework stores the results in a directory. The path to this directory is results/ followed by the results_dir_name you specified in the test suite.  ","version":"Next","tagName":"h2"},{"title":"Results Directory​","type":1,"pageTitle":"Evaluating Agents","url":"/solace-agent-mesh/docs/documentation/developing/evaluations#results-directory","content":" The results directory has the following structure:  <results_dir_name>/ ├── report.html ├── stats.json └── <model_name>/ ├── full_messages.json ├── results.json └── <test_case_id>/ └── run_1/ ├── messages.json ├── summary.json └── test_case_info.json └── run_2/ ├── ...   report.html: An HTML report that provides a comprehensive overview of the evaluation results. It includes a summary of the test runs, a breakdown of the results for each test case, and detailed logs for each test run. This report is the primary tool for analyzing the results of an evaluation.stats.json: A JSON file containing detailed statistics about the evaluation run, including scores for each evaluation metric.<model_name>/: A directory for each language model tested (or a single remote directory for remote evaluations). full_messages.json: A log of all messages exchanged during the evaluation for that model.results.json: The raw evaluation results for each test case.<test_case_id>/: A directory for each test case, containing a run_n subdirectory for each run of the test case. These directories contain detailed logs and artifacts for each run.  ","version":"Next","tagName":"h3"},{"title":"HTML Report​","type":1,"pageTitle":"Evaluating Agents","url":"/solace-agent-mesh/docs/documentation/developing/evaluations#html-report","content":" The report.html file provides a comprehensive overview of the evaluation results. It includes a summary of the test runs, a breakdown of the results for each test case, and detailed logs for each test run. This report is the primary tool for analyzing the results of an evaluation. You can open this file in a web browser to view the report. ","version":"Next","tagName":"h3"},{"title":"Creating Agents","type":0,"sectionRef":"#","url":"/solace-agent-mesh/docs/documentation/developing/create-agents","content":"","keywords":"","version":"Next"},{"title":"Understanding the Architecture​","type":1,"pageTitle":"Creating Agents","url":"/solace-agent-mesh/docs/documentation/developing/create-agents#understanding-the-architecture","content":" Before diving into implementation, you need to understand how the different components of an Agent Mesh agent work together. This architectural overview will help you see the big picture before you start building.    When a user sends a request to your agent, the LLM orchestrator analyzes the request and decides which tool to use. The framework wraps your tool functions and provides them with context and configuration. Your tool executes its logic and returns results to the LLM, which then formulates a response to the user.  ","version":"Next","tagName":"h2"},{"title":"Core Concepts​","type":1,"pageTitle":"Creating Agents","url":"/solace-agent-mesh/docs/documentation/developing/create-agents#core-concepts","content":" Understanding these fundamental concepts will help you build effective agents.  ","version":"Next","tagName":"h2"},{"title":"Tools: The Building Blocks​","type":1,"pageTitle":"Creating Agents","url":"/solace-agent-mesh/docs/documentation/developing/create-agents#tools-the-building-blocks","content":" Tools are the fundamental building blocks of Agent Mesh agents. Each tool is implemented as a Python function that performs a specific task. The LLM orchestrating your agent decides which tools to use based on the user's request and the tool descriptions you provide.  Tools can process text and data, interact with external APIs, create and manipulate files, communicate with other agents, and access databases and services. You write tools as standard Python functions, and the framework handles the integration with the LLM.  tip Agent Mesh provides a set of built-in tools plus support for model context protocol (MCP) servers, which can be configured in the tools list of your agent configuration.  ","version":"Next","tagName":"h3"},{"title":"Configuration File: The Blueprint​","type":1,"pageTitle":"Creating Agents","url":"/solace-agent-mesh/docs/documentation/developing/create-agents#configuration-file-the-blueprint","content":" The config.yaml (for plugin template) or agent-name.yaml (for agent instances) file is the blueprint of your agent. This YAML file defines your agent's identity (name, description, and capabilities), model configuration (which LLM to use), tools list (which tools the agent can access and how they're configured), lifecycle functions (setup and cleanup procedures), framework services (session management, artifact storage, and so on), and agent card (metadata describing the agent capabilities, skills and its visibility in the system).  The configuration file connects all the pieces together. It tells the framework where to find your tool functions, how to configure them, and what instructions to give the LLM about your agent's purpose.  ","version":"Next","tagName":"h3"},{"title":"Tool Configuration: Customizing Behavior​","type":1,"pageTitle":"Creating Agents","url":"/solace-agent-mesh/docs/documentation/developing/create-agents#tool-configuration-customizing-behavior","content":" Within the tools list in your YAML config, each tool can have its own tool_config section. This allows you to configure the same tool function for different purposes, pass specific parameters to tool instances, and customize tool behavior per agent.  This design pattern enables code reuse. You can write a single generic tool function and configure it multiple times with different parameters to serve different purposes within the same agent.  info For tools of type "python", you can also use the tool_name and tool_description to overwrite the function name and description in the tool docstring. This is useful when using a generic tool function for multiple purposes, allowing you to provide a more descriptive name and description for each instance.  ","version":"Next","tagName":"h3"},{"title":"ToolContext: Accessing Framework Services​","type":1,"pageTitle":"Creating Agents","url":"/solace-agent-mesh/docs/documentation/developing/create-agents#toolcontext-accessing-framework-services","content":" The ToolContext object (passed as one of the arguments to your tool function) provides your tools with access to Agent Mesh core services. Through this context object, your tools can access structured logging for debugging and monitoring, the artifact service for file storage and retrieval, session information about the current user and session context, and agent state for sharing data between tool calls.  The framework automatically provides this context to your tool functions. You don't need to create or manage it yourself.  ","version":"Next","tagName":"h3"},{"title":"Lifecycle Functions: Managing Resources​","type":1,"pageTitle":"Creating Agents","url":"/solace-agent-mesh/docs/documentation/developing/create-agents#lifecycle-functions-managing-resources","content":" Lifecycle functions allow you to manage resources that should persist for the agent's lifetime. The agent_init_function runs when the agent starts (for example, to establish database connections), and the agent_cleanup_function runs when the agent shuts down (for example, to close connections gracefully).  These functions are optional but recommended for managing resources effectively. They ensure that your agent properly initializes any required resources and cleans them up when shutting down.  note Lifecycle functions are optional but recommended for managing resources effectively.  ","version":"Next","tagName":"h3"},{"title":"Creating Your First Agent: Step-by-Step​","type":1,"pageTitle":"Creating Agents","url":"/solace-agent-mesh/docs/documentation/developing/create-agents#creating-your-first-agent-step-by-step","content":" Now that you understand the core concepts, you can create a simple agent that demonstrates how these pieces work together. You will build a "Hello World" agent that can greet users and say goodbye.  ","version":"Next","tagName":"h2"},{"title":"Step 1: Initialize Your Agent Plugin​","type":1,"pageTitle":"Creating Agents","url":"/solace-agent-mesh/docs/documentation/developing/create-agents#step-1-initialize-your-agent-plugin","content":" You can create an agent either by using the sam add agent command or by creating a new plugin of type agent with sam plugin create my-hello-agent --type agent.  tip For information and recommendations about these options, see Agent or Plugin: Which To use?.  In this tutorial, you create a new agent by creating a new plugin of type agent. For an example of custom agents, see Build Your Own Agent guide.  Although the directory structure for plugins is slightly different than the one for agents, both require a YAML configuration file, and a python module with the tools and lifecycle functions you want.  To create a new agent plugin, run the following command:  sam plugin create my-hello-agent --type agent   Follow the prompts to set up your agent. The prompts create a new directory structure for your agent:  my-hello-agent/ ├── src/ │ └── my_hello_agent/ │ ├── __init__.py │ ├── tools.py │ └── lifecycle.py # This file won't be automatically created ├── config.yaml ├── pyproject.toml └── README.md     The config.yaml file will contain your agent configuration, tools.py will contain your tool functions, and lifecycle.py (which you'll create manually) will contain your lifecycle functions. The pyproject.toml file manages your plugin's dependencies and metadata.  ","version":"Next","tagName":"h3"},{"title":"Step 2: Create Your Tool Functions​","type":1,"pageTitle":"Creating Agents","url":"/solace-agent-mesh/docs/documentation/developing/create-agents#step-2-create-your-tool-functions","content":" Tools are where your agent's actual capabilities live. You will create two simple tools: one to greet users and one to say goodbye.  Create your tool functions in the src/my_hello_agent/tools.py file. For a complete guide on creating python tools, see our Creating Python Tools documentation.  # src/my_hello_agent/tools.py """ Tools for the Hello World agent. """ from typing import Any, Dict, Optional from google.adk.tools import ToolContext from solace_ai_connector.common.log import log async def hello_tool( name: str, tool_context: Optional[ToolContext] = None, tool_config: Optional[Dict[str, Any]] = None ) -> Dict[str, Any]: """ Greets a user with a personalized message. Args: name: The name of the person to greet Returns: A dictionary with the greeting message """ log_identifier = "[HelloTool]" log.info(f"{log_identifier} Greeting user: {name}") # Get configuration from tool_config greeting_prefix = "Hello" if tool_config: greeting_prefix = tool_config.get("greeting_prefix", "Hello") # Create the greeting message greeting_message = f"{greeting_prefix}, {name}! Welcome to Agent Mesh!" log.info(f"{log_identifier} Generated greeting: {greeting_message}") return { "status": "success", "message": greeting_message, "greeted_name": name } async def farewell_tool( name: str, tool_context: Optional[ToolContext] = None, tool_config: Optional[Dict[str, Any]] = None ) -> Dict[str, Any]: """ Says goodbye to a user. Args: name: The name of the person to say goodbye to Returns: A dictionary with the farewell message """ log_identifier = "[FarewellTool]" log.info(f"{log_identifier} Saying goodbye to user: {name}") # Get configuration from tool_config farewell_prefix = "Goodbye" if tool_config: farewell_prefix = tool_config.get("farewell_prefix", "Goodbye") # Create the farewell message farewell_message = f"{farewell_prefix}, {name}! Thanks for using Agent Mesh!" log.info(f"{log_identifier} Generated farewell: {farewell_message}") return { "status": "success", "message": farewell_message, "farewell_name": name }   Let's examine what makes these tool functions work. All tool functions must be asynchronous (defined with async def) because the framework uses asynchronous execution. The framework automatically provides two special parameters: tool_context gives you access to framework services like logging and artifact storage, and tool_config contains any custom configuration you define in your YAML file.  The function signature includes regular parameters (like name) that the LLM will provide when calling the tool. The docstring is important because the LLM uses it to understand what the tool does and when to use it. You should always write clear, descriptive docstrings.  The tool retrieves its configuration from the tool_config dictionary. This allows you to customize the tool's behavior without changing the code. In this example, you can configure different greeting prefixes for different use cases.  The tool returns a dictionary with at least a status field. This structured format makes it easy for the LLM to understand the result. You can include any additional data that might be useful for the LLM or for debugging.  The logging statements help you track what your tool is doing. The framework provides a logger that you should use for consistent logging across your agent.  ","version":"Next","tagName":"h3"},{"title":"Step 3: Configure Your Agent​","type":1,"pageTitle":"Creating Agents","url":"/solace-agent-mesh/docs/documentation/developing/create-agents#step-3-configure-your-agent","content":" Now you need to tell the framework about your agent and its tools. Create the main configuration file for your agent in config.yaml:  # File: config.yaml (at root of project directory) # ... (additional services and configurations) apps: - name: my-hello-agent app_module: solace_agent_mesh.agent.sac.app broker: # Can be found in configs/shared_config.yaml after running sam init <<: *broker_connection # Agent-specific configuration app_config: # Basic agent identity namespace: ${NAMESPACE} supports_streaming: true agent_name: "HelloAgent" display_name: "Hello World Agent" # LLM model configuration model: *general_model # Agent instructions (system prompt) instruction: | You are a friendly Hello World agent. Your purpose is to greet users and demonstrate the capabilities of Agent Mesh. You can: 1. Greet users with personalized messages using the hello_tool 2. Say goodbye to users using the farewell_tool Always be polite and helpful. When greeting someone, ask for their name if they haven't provided it. # Lifecycle functions agent_init_function: module: "my_hello_agent.lifecycle" # This should point to your lifecycle python module name: "initialize_hello_agent" base_path: . config: startup_message: "Hello Agent is starting up!" log_level: "INFO" agent_cleanup_function: module: "my_hello_agent.lifecycle" base_path: . name: "cleanup_hello_agent" # Tools configuration tools: # Hello tool with custom greeting - tool_type: python component_module: "my_hello_agent.tools" component_base_path: . function_name: "hello_tool" tool_name: "greet_user" # Renaming the tool, must use this name in the agent card tool_config: greeting_prefix: "Hello there" # Farewell tool with custom farewell - tool_type: python component_module: "my_hello_agent.tools" component_base_path: . function_name: "farewell_tool" tool_name: "say_goodbye" tool_config: farewell_prefix: "See you later" # Built-in artifact tools for file operations - tool_type: builtin-group group_name: "artifact_management" # Agent card (describes the agent's capabilities) agent_card: description: "A friendly Hello World agent that demonstrates Agent Mesh capabilities" defaultInputModes: ["text"] defaultOutputModes: ["text"] skills: - id: "greet_user" name: "Greet User" description: "Greets users with personalized messages" - id: "say_goodbye" name: "Say Goodbye" description: "Says goodbye to users" - id: "file_operations" name: "File Operations" description: "Create, read, and manage files and artifacts" # Session and artifact services session_service: *default_session_service artifact_service: *default_artifact_service # ... (additional services and configurations)   This configuration file connects all the pieces of your agent. Let's examine each section to understand its purpose.  The namespace uniquely identifies your agent in the mesh. This allows multiple agents to coexist and communicate. The agent_name and display_name provide human-readable identifiers for your agent.  The model section specifies which LLM to use. The *general_model reference points to a model configuration defined elsewhere in your configuration files (typically in shared_config.yaml). This allows you to centrally manage model configurations across multiple agents.  The instruction field contains the system prompt that defines your agent's personality and behavior. This text tells the LLM what role it should play and what capabilities it has. You should write clear, specific instructions that help the LLM understand its role.  The tools section lists all the tools your agent can use. Each tool entry specifies the tool_type (python for custom functions, builtin-group for built-in tools), the component_module that contains the function, the function_name to call, and optionally a tool_name to rename the tool for the LLM. The tool_config section passes custom configuration to each tool instance. This is where you provide the greeting_prefix and farewell_prefix values that your tool functions read.  Notice that you can configure the same function multiple times with different names and configurations. The hello_tool function is configured as greet_user with one greeting prefix, but you could add another configuration with a different prefix for formal greetings.  The agent_card section describes your agent's capabilities to other parts of the system. The skills list should match the tools you've configured. Each skill has an id that corresponds to a tool name, making it discoverable by other agents and the user interface.  The session_service and artifact_service references connect your agent to framework services for managing user sessions and storing files. These services are typically defined in your shared configuration.  ","version":"Next","tagName":"h3"},{"title":"Step 4: Create Lifecycle Functions​","type":1,"pageTitle":"Creating Agents","url":"/solace-agent-mesh/docs/documentation/developing/create-agents#step-4-create-lifecycle-functions","content":" Lifecycle functions manage resources that should persist for your agent's lifetime. Although these functions are optional, they demonstrate how to properly initialize and clean up resources.  The lifecycle file is not automatically created, so you need to create it manually:  touch src/my_hello_agent/lifecycle.py   Now add your lifecycle functions:  # src/my_hello_agent/lifecycle.py """ Lifecycle functions for the Hello World agent. """ 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") def cleanup_hello_agent(host_component: Any): """ Cleans up resources when the Hello World agent shuts down. Args: host_component: The agent host component """ log_identifier = f"[{host_component.agent_name}:cleanup]" log.info(f"{log_identifier} Starting Hello Agent cleanup...") # Retrieve any shared state greeting_count = host_component.get_agent_specific_state("greeting_count", 0) log.info(f"{log_identifier} Agent processed {greeting_count} greetings during its lifetime") # Clean up resources here, such as: # - Closing database connections # - Shutting down background tasks # - Saving final state log.info(f"{log_identifier} Hello Agent cleanup completed")   The lifecycle functions follow a specific pattern. The initialize_hello_agent function receives two parameters: host_component provides access to the agent instance and its methods, and init_config contains the validated configuration from your YAML file's agent_init_function.config section.  Using a Pydantic model for init_config provides automatic validation. The framework validates your configuration against this model when the agent starts, catching configuration errors early. This is better than manually checking configuration values in your code.  The host_component object provides methods for managing agent state. The set_agent_specific_state method stores data that persists across tool calls within the same agent instance. This is useful for tracking statistics, caching data, or maintaining connections. The state is specific to this agent instance and is not shared with other agents.  The cleanup_hello_agent function runs when the agent shuts down. This is your opportunity to gracefully close connections, save final state, or perform any other cleanup tasks. The function receives only the host_component parameter because cleanup typically doesn't need additional configuration.  In this example, you retrieve the greeting count from the agent state and log it. In a real application, you might close database connections, flush caches to disk, or notify other services that the agent is shutting down.  ","version":"Next","tagName":"h3"},{"title":"Running Your Agent​","type":1,"pageTitle":"Creating Agents","url":"/solace-agent-mesh/docs/documentation/developing/create-agents#running-your-agent","content":" Now that you have created all the necessary components, you can run your agent. The process involves building your plugin and adding it to your Agent Mesh project.  ","version":"Next","tagName":"h2"},{"title":"Building and Installing the Plugin​","type":1,"pageTitle":"Creating Agents","url":"/solace-agent-mesh/docs/documentation/developing/create-agents#building-and-installing-the-plugin","content":" To properly instantiate your plugin agent, first build the plugin. The following command will produce a python wheel file under dist directory:  sam plugin build   This command packages your agent code, configuration, and dependencies into a distributable wheel file. The wheel file is a standard Python package format that can be installed into any Python environment.  Check into your Agent Mesh project directory, and add the plugin wheel with a given name:  sam plugin add my-first-weather-agent --plugin PATH/TO/weather-agent/dist/weather-agent.whl   note Using the sam plugin add command installs your plugin as a python dependency into your python environment. This also means changing the source code without reinstalling the plugin will not reflect the changes.  The sam plugin add command does several things. It installs your plugin package into your Python environment, making your tool functions and lifecycle functions importable. It also creates a configuration file in your project's configs/agents/ directory that references your plugin. This configuration file is what the framework loads when you run your agent.  Now, you can run the complete Agent Mesh application along with your newly added agent:  sam run   Alternatively, only run the newly added agent using sam run configs/agents/my-first-weather-agent.yaml  ","version":"Next","tagName":"h3"},{"title":"Quick Debug Mode​","type":1,"pageTitle":"Creating Agents","url":"/solace-agent-mesh/docs/documentation/developing/create-agents#quick-debug-mode","content":" Quick Debug For debugging or isolated development testing, you can run your agent from the src directory directly using the Agent Mesh CLI. cd src sam run ../config.yaml Changing to the src directory allows the module path to be set correctly so that Agent Mesh can find your functions without your having to install them in your python environment as a plugin package.  This quick debug mode is useful during development because you can make changes to your code and immediately test them without rebuilding and reinstalling the plugin. However, you should always test with the full plugin installation process before deploying to production.  ","version":"Next","tagName":"h3"},{"title":"Advanced Concepts​","type":1,"pageTitle":"Creating Agents","url":"/solace-agent-mesh/docs/documentation/developing/create-agents#advanced-concepts","content":" Once you understand the basics, you can explore more advanced patterns for building sophisticated agents.  ","version":"Next","tagName":"h2"},{"title":"Working with Artifacts​","type":1,"pageTitle":"Creating Agents","url":"/solace-agent-mesh/docs/documentation/developing/create-agents#working-with-artifacts","content":" The artifact service allows your tools to create, store, and retrieve files. You can enhance your hello tool to save greetings to a file using the artifact service:   from datetime import datetime from solace_agent_mesh.agent.utils.artifact_helpers import save_artifact_with_metadata async def hello_tool_with_artifact( name: str, save_to_file: bool = False, tool_context: Optional[ToolContext] = None, tool_config: Optional[Dict[str, Any]] = None ) -> Dict[str, Any]: """ Greets a user and optionally saves the greeting to a file. """ log_identifier = "[HelloToolWithArtifact]" # Generate greeting (same as before) greeting_prefix = tool_config.get("greeting_prefix", "Hello") if tool_config else "Hello" greeting_message = f"{greeting_prefix}, {name}! Welcome to Agent Mesh!" result = { "status": "success", "message": greeting_message, "greeted_name": name } # Save to artifact if requested if save_to_file and tool_context: try: # Prepare content timestamp = datetime.now(timezone.utc) filename = f"greeting_{name}_{timestamp}.txt" content = f"Greeting: {greeting_message}\\nTimestamp: {timestamp}\\n" # Save artifact artifact_service = tool_context._invocation_context.artifact_service await save_artifact_with_metadata( artifact_service=artifact_service, app_name=tool_context._invocation_context.app_name, user_id=tool_context._invocation_context.user_id, session_id=tool_context._invocation_context.session.id, filename=filename, content_bytes=content.encode('utf-8'), mime_type="application/json", metadata_dict={ "description": "Greeting message", "source": "Greeting Agent", }, timestamp=timestamp ) result["artifact_saved"] = filename log.info(f"{log_identifier} Saved greeting to artifact: {filename}") except Exception as e: log.error(f"{log_identifier} Failed to save artifact: {e}") result["artifact_error"] = str(e) return result   This enhanced tool demonstrates several important concepts. The save_to_file parameter allows the LLM to decide whether to save the greeting based on the user's request. This gives your agent flexibility in how it uses the tool.  The tool_context object provides access to the artifact service through its _invocation_context property. The invocation context contains information about the current execution environment, including the user ID, session ID, and app name. These identifiers are necessary for properly organizing and retrieving artifacts.  The save_artifact_with_metadata helper function handles the details of saving files to the artifact service. You provide the content as bytes, specify a MIME type, and include metadata that describes the artifact. The metadata makes it easier to search for and manage artifacts later.  Error handling is important when working with external services. The try-except block ensures that if artifact saving fails, your tool can still return a successful greeting. The error is logged and included in the result, allowing the LLM to inform the user about the issue.  ","version":"Next","tagName":"h3"},{"title":"Using Multiple Tool Configurations​","type":1,"pageTitle":"Creating Agents","url":"/solace-agent-mesh/docs/documentation/developing/create-agents#using-multiple-tool-configurations","content":" You can configure the same tool function multiple times with different settings. This pattern is useful when you want to provide the LLM with multiple variations of the same capability:  tools: # Formal greeting - tool_type: python component_module: "my_hello_agent.tools" function_name: "hello_tool" tool_name: "formal_greeting" tool_config: greeting_prefix: "Good day" # Casual greeting - tool_type: python component_module: "my_hello_agent.tools" function_name: "hello_tool" tool_name: "casual_greeting" tool_config: greeting_prefix: "Hey there" # Enthusiastic greeting - tool_type: python component_module: "my_hello_agent.tools" function_name: "hello_tool" tool_name: "enthusiastic_greeting" tool_config: greeting_prefix: "Hello and welcome"   This configuration creates three different tools from the same function. The LLM sees these as distinct capabilities and can choose the appropriate greeting style based on the context of the conversation. For example, it might use the formal greeting for business contexts and the casual greeting for friendly conversations.  Each tool configuration should have a unique tool_name and should be listed in your agent card's skills section. This makes each variation discoverable and allows you to provide specific descriptions for each greeting style.  ","version":"Next","tagName":"h3"},{"title":"Quick Start: Using the CLI​","type":1,"pageTitle":"Creating Agents","url":"/solace-agent-mesh/docs/documentation/developing/create-agents#quick-start-using-the-cli","content":" If you want to get started quickly without manually creating all the files, you can use the Agent Mesh CLI to generate the basic structure:  sam add agent my-first-agent   This command launches an interactive setup (or use --gui for browser-based configuration) that generates the necessary files and configuration, and sets up the basic agent structure.  Note that creating an agent as a plugin is preferred over creating an agent directly because plugins are more portable and easier to share.  ","version":"Next","tagName":"h2"},{"title":"CLI Options​","type":1,"pageTitle":"Creating Agents","url":"/solace-agent-mesh/docs/documentation/developing/create-agents#cli-options","content":" You can customize the agent creation with provided CLI options. For a complete list of options, run:  sam add agent --help   The CLI tool is useful for quickly scaffolding new agents, but understanding the manual process helps you customize and troubleshoot your agents more effectively.  ","version":"Next","tagName":"h3"},{"title":"Best Practices​","type":1,"pageTitle":"Creating Agents","url":"/solace-agent-mesh/docs/documentation/developing/create-agents#best-practices","content":" Following these best practices will help you create robust, maintainable agents.  ","version":"Next","tagName":"h2"},{"title":"Tool Design​","type":1,"pageTitle":"Creating Agents","url":"/solace-agent-mesh/docs/documentation/developing/create-agents#tool-design","content":" Each tool should do one thing well. This single responsibility principle makes your tools easier to test, debug, and reuse. Instead of creating one large tool that handles multiple tasks, create several focused tools that each handle a specific task.  Write detailed docstrings for your tools. The LLM uses these docstrings to understand what each tool does and when to use it. Include descriptions of all parameters, return values, and any important behavior or limitations.  Always return structured error responses. When something goes wrong, your tool should return a dictionary with a status field indicating failure and a message explaining what went wrong. This allows the LLM to understand the error and potentially retry with different parameters or inform the user about the issue.  Use consistent logging for debugging and monitoring. Log important events, parameter values, and results. This makes it much easier to troubleshoot issues when your agent is running in production.  ","version":"Next","tagName":"h3"},{"title":"Configuration​","type":1,"pageTitle":"Creating Agents","url":"/solace-agent-mesh/docs/documentation/developing/create-agents#configuration","content":" Use environment variables for sensitive data like API keys, database passwords, and other credentials. Never hardcode sensitive information in your configuration files or source code.  Use Pydantic models for configuration validation. This catches configuration errors early and provides clear error messages when something is wrong. It also serves as documentation for what configuration options are available.  Comment your configuration files thoroughly. YAML files can become complex, and clear comments help other developers (and your future self) understand what each section does and why it's configured that way.  ","version":"Next","tagName":"h3"},{"title":"Testing​","type":1,"pageTitle":"Creating Agents","url":"/solace-agent-mesh/docs/documentation/developing/create-agents#testing","content":" Write unit tests for your tool functions independently. Test them with various inputs, including edge cases and error conditions. Mock the tool_context and tool_config parameters to isolate your tool logic from the framework.  Write integration tests that test your agent with real Agent Mesh infrastructure. These tests verify that your configuration is correct and that your tools work properly when called by the LLM.  Mock external dependencies for reliable testing. If your tools call external APIs or databases, create mock versions for testing. This makes your tests faster and more reliable because they don't depend on external services being available. ","version":"Next","tagName":"h3"},{"title":"Creating Python Tools","type":0,"sectionRef":"#","url":"/solace-agent-mesh/docs/documentation/developing/creating-python-tools","content":"","keywords":"","version":"Next"},{"title":"Tool Creation Patterns​","type":1,"pageTitle":"Creating Python Tools","url":"/solace-agent-mesh/docs/documentation/developing/creating-python-tools#tool-creation-patterns","content":" There are three primary patterns for creating Python tools, ranging from simple to advanced. You can choose the best pattern for your needs, and even mix and match them within the same project.  Pattern\tBest For\tKey FeatureFunction-Based\tSimple, self-contained tools with static inputs.\tQuick and easy; uses function signature. Single DynamicTool Class\tTools that require complex logic or a programmatically defined interface.\tFull control over the tool's definition. DynamicToolProvider Class\tGenerating multiple related tools from a single, configurable source.\tMaximum scalability and code reuse.  All three patterns are configured in your agent's YAML file under the tools list with tool_type: python.    ","version":"Next","tagName":"h2"},{"title":"Pattern 1: Simple Function-Based Tools​","type":1,"pageTitle":"Creating Python Tools","url":"/solace-agent-mesh/docs/documentation/developing/creating-python-tools#pattern-1-simple-function-based-tools","content":" This is the most straightforward way to create a custom tool. You define a standard Python async function, and Agent Mesh automatically introspects its signature and docstring to create the tool definition for the LLM.  ","version":"Next","tagName":"h2"},{"title":"Step 1: Write the Tool Function​","type":1,"pageTitle":"Creating Python Tools","url":"/solace-agent-mesh/docs/documentation/developing/creating-python-tools#step-1-write-the-tool-function","content":" Create a Python file (e.g., src/my_agent/tools.py) and define your tool.  # src/my_agent/tools.py from typing import Any, Dict, Optional from google.adk.tools import ToolContext async def greet_user( name: str, tool_context: Optional[ToolContext] = None, tool_config: Optional[Dict[str, Any]] = None ) -> Dict[str, Any]: """ Greets a user with a personalized message. Args: name: The name of the person to greet. Returns: A dictionary with the greeting message. """ greeting_prefix = "Hello" if tool_config: greeting_prefix = tool_config.get("greeting_prefix", "Hello") greeting_message = f"{greeting_prefix}, {name}! Welcome to Agent Mesh!" return { "status": "success", "message": greeting_message }   Key Requirements:  The function must be async def.The function's docstring is used as the tool's description for the LLM.Type hints (str, int, bool) are used to generate the parameter schema.The function should accept tool_context and tool_config as optional keyword arguments to receive framework context and YAML configuration.  ","version":"Next","tagName":"h3"},{"title":"Step 2: Configure the Tool​","type":1,"pageTitle":"Creating Python Tools","url":"/solace-agent-mesh/docs/documentation/developing/creating-python-tools#step-2-configure-the-tool","content":" In your agent's YAML configuration, add a tool_type: python block and point it to your function.  # In your agent's app_config: tools: - tool_type: python component_module: "my_agent.tools" function_name: "greet_user" tool_config: greeting_prefix: "Greetings"   component_module: The Python module path to your tools file.function_name: The exact name of the function to load.tool_config: An optional dictionary passed to your tool at runtime.    ","version":"Next","tagName":"h3"},{"title":"Pattern 2: Advanced Single-Class Tools​","type":1,"pageTitle":"Creating Python Tools","url":"/solace-agent-mesh/docs/documentation/developing/creating-python-tools#pattern-2-advanced-single-class-tools","content":" For tools that require more complex logic—such as defining their interface programmatically based on configuration—you can use a class that inherits from DynamicTool.  ","version":"Next","tagName":"h2"},{"title":"Step 1: Create the DynamicTool Class​","type":1,"pageTitle":"Creating Python Tools","url":"/solace-agent-mesh/docs/documentation/developing/creating-python-tools#step-1-create-the-dynamictool-class","content":" Instead of a function, define a class that implements the DynamicTool abstract base class.  # src/my_agent/tools.py from typing import Optional, Dict, Any from google.genai import types as adk_types from solace_agent_mesh.agent.tools.dynamic_tool import DynamicTool class WeatherTool(DynamicTool): """A dynamic tool that fetches current weather information.""" @property def tool_name(self) -> str: return "get_current_weather" @property def tool_description(self) -> str: return "Get the current weather for a specified location." @property def parameters_schema(self) -> adk_types.Schema: # Programmatically define the tool's parameters return adk_types.Schema( type=adk_types.Type.OBJECT, properties={ "location": adk_types.Schema(type=adk_types.Type.STRING, description="The city and state/country."), "units": adk_types.Schema(type=adk_types.Type.STRING, enum=["celsius", "fahrenheit"], nullable=True), }, required=["location"], ) async def _run_async_impl(self, args: Dict[str, Any], **kwargs) -> Dict[str, Any]: location = args["location"] # Access config via self.tool_config api_key = self.tool_config.get("api_key") if not api_key: return {"status": "error", "message": "API key not configured"} # ... implementation to call weather API ... return {"status": "success", "weather": "Sunny"}   ","version":"Next","tagName":"h3"},{"title":"Step 2: Configure the Tool​","type":1,"pageTitle":"Creating Python Tools","url":"/solace-agent-mesh/docs/documentation/developing/creating-python-tools#step-2-configure-the-tool-1","content":" The YAML configuration is very similar. You can either specify the class_name or let Agent Mesh auto-discover it if it's the only DynamicTool in the module.  # In your agent's app_config: tools: - tool_type: python component_module: "my_agent.tools" # class_name: WeatherTool # Optional if it's the only one tool_config: api_key: ${WEATHER_API_KEY}     ","version":"Next","tagName":"h3"},{"title":"Pattern 3: The Tool Provider Factory​","type":1,"pageTitle":"Creating Python Tools","url":"/solace-agent-mesh/docs/documentation/developing/creating-python-tools#pattern-3-the-tool-provider-factory","content":" This is the most powerful pattern, designed for generating multiple, related tools from a single module and configuration block. It's perfect for creating toolsets based on external schemas, database tables, or other dynamic sources.  ","version":"Next","tagName":"h2"},{"title":"Step 1: Create the Provider and Tools​","type":1,"pageTitle":"Creating Python Tools","url":"/solace-agent-mesh/docs/documentation/developing/creating-python-tools#step-1-create-the-provider-and-tools","content":" In your tools module, you define your DynamicTool classes as before, but you also create a provider class that inherits from DynamicToolProvider. This provider acts as a factory.  You can also use the @register_tool decorator on simple functions to have them automatically included by the provider.  # src/my_agent/database_tools.py from typing import Optional, Dict, Any, List from google.genai import types as adk_types from solace_agent_mesh.agent.tools.dynamic_tool import DynamicTool, DynamicToolProvider # --- Tool Implementations --- class DatabaseQueryTool(DynamicTool): # ... (implementation as in previous examples) ... pass class DatabaseSchemaTool(DynamicTool): # ... (implementation as in previous examples) ... pass # --- Tool Provider Implementation --- class DatabaseToolProvider(DynamicToolProvider): """A factory that creates all database-related tools.""" # Use a decorator for a simple, function-based tool def create_tools(self, tool_config: Optional[dict] = None) -> List[DynamicTool]: """ Generates a list of all database tools, passing the shared configuration to each one. """ # 1. Create tools from any decorated functions in this module tools = self._create_tools_from_decorators(tool_config) # 2. Programmatically create and add more complex tools if tool_config and tool_config.get("connection_string"): tools.append(DatabaseQueryTool(tool_config=tool_config)) tools.append(DatabaseSchemaTool(tool_config=tool_config)) return tools # NOTE that you must use the decorator outside of any class with the provider's class name. @DatabaseToolProvider.register_tool async def get_database_server_version(tool_config: dict, **kwargs) -> dict: """Returns the version of the connected PostgreSQL server.""" # ... implementation ... return {"version": "PostgreSQL 15.3"}   ","version":"Next","tagName":"h3"},{"title":"Step 2: Configure the Provider​","type":1,"pageTitle":"Creating Python Tools","url":"/solace-agent-mesh/docs/documentation/developing/creating-python-tools#step-2-configure-the-provider","content":" You only need a single YAML block. Agent Mesh will automatically detect the DynamicToolProvider and use it to load all the tools it generates.  # In your agent's app_config: tools: # This single block loads get_database_server_version, # execute_database_query, and get_database_schema. - tool_type: python component_module: "my_agent.database_tools" tool_config: connection_string: ${DB_CONNECTION_STRING} max_rows: 1000   This approach is incredibly scalable, as one configuration entry can bootstrap an entire suite of dynamically generated tools.    ","version":"Next","tagName":"h3"},{"title":"Managing Tool Lifecycles with init and cleanup​","type":1,"pageTitle":"Creating Python Tools","url":"/solace-agent-mesh/docs/documentation/developing/creating-python-tools#managing-tool-lifecycles-with-init-and-cleanup","content":" For tools that need to manage resources—such as database connections, API clients, or temporary files—Agent Mesh provides optional init and cleanup lifecycle hooks. These allow you to run code when the agent starts up and shuts down, ensuring that resources are acquired and released gracefully.  There are two ways to define these hooks:  YAML-based (init_function, cleanup_function): A flexible method that works for any Python tool, including simple function-based ones.Class-based (init, cleanup methods): The idiomatic and recommended way for DynamicTool and DynamicToolProvider classes.  ","version":"Next","tagName":"h2"},{"title":"YAML-Based Lifecycle Hooks​","type":1,"pageTitle":"Creating Python Tools","url":"/solace-agent-mesh/docs/documentation/developing/creating-python-tools#yaml-based-lifecycle-hooks","content":" You can add init_function and cleanup_function to any Python tool's configuration in your agent's YAML. The lifecycle functions must be defined in the same module as the tool itself.  Step 1: Define the Tool and Hook Functions​  In your tool's Python file (e.g., src/my_agent/db_tools.py), define the tool function and its corresponding init and cleanup functions. These functions must be async and will receive the agent component instance and the tool's configuration model object as arguments.  # src/my_agent/db_tools.py from solace_agent_mesh.agent.sac.component import SamAgentComponent from solace_agent_mesh.agent.tools.tool_config_types import AnyToolConfig from google.adk.tools import ToolContext from typing import Dict, Any # --- Lifecycle Hooks --- async def initialize_db_connection(component: SamAgentComponent, tool_config_model: AnyToolConfig): """Initializes a database connection and stores it for the agent to use.""" print("INFO: Initializing database connection...") # In a real scenario, you would create a client instance db_client = {"connection_string": tool_config_model.tool_config.get("connection_string")} # Store the client in a shared state accessible by the component component.set_agent_specific_state("db_client", db_client) print("INFO: Database client initialized.") async def close_db_connection(component: SamAgentComponent, tool_config_model: AnyToolConfig): """Retrieves and closes the database connection.""" print("INFO: Closing database connection...") db_client = component.get_agent_specific_state("db_client") if db_client: # In a real scenario, you would call db_client.close() print("INFO: Database connection closed.") # --- Tool Function --- async def query_database(query: str, tool_context: ToolContext, **kwargs) -> Dict[str, Any]: """Queries the database using the initialized connection.""" host_component = tool_context._invocation_context.agent.host_component db_client = host_component.get_agent_specific_state("db_client") if not db_client: return {"error": "Database connection not initialized."} # ... use db_client to run query ... return {"result": "some data"}   Step 2: Configure the Hooks in YAML​  In your YAML configuration, reference the lifecycle functions by name. The framework will automatically look for them in the component_module.  # In your agent's app_config: tools: - tool_type: python component_module: "my_agent.db_tools" function_name: "query_database" tool_config: connection_string: "postgresql://user:pass@host/db" # Initialize the tool on startup init_function: "initialize_db_connection" # Clean up the tool on shutdown cleanup_function: "close_db_connection"   ","version":"Next","tagName":"h3"},{"title":"Class-Based Lifecycle Methods (for DynamicTool)​","type":1,"pageTitle":"Creating Python Tools","url":"/solace-agent-mesh/docs/documentation/developing/creating-python-tools#class-based-lifecycle-methods-for-dynamictool","content":" For tools built with DynamicTool or DynamicToolProvider, the recommended approach is to override the init and cleanup methods directly within the class. This co-locates the entire tool's logic and improves encapsulation.  Example: Adding Lifecycle Methods to a DynamicTool  Here, we extend a DynamicTool to manage its own API client.  # src/my_agent/api_tool.py from solace_agent_mesh.agent.sac.component import SamAgentComponent from solace_agent_mesh.agent.tools.dynamic_tool import DynamicTool from solace_agent_mesh.agent.tools.tool_config_types import AnyToolConfig # Assume WeatherApiClient is a custom class for an external service from my_agent.api_client import WeatherApiClient class WeatherTool(DynamicTool): """A dynamic tool that fetches weather and manages its own API client.""" async def init(self, component: "SamAgentComponent", tool_config: "AnyToolConfig") -> None: """Initializes the API client when the agent starts.""" print("INFO: Initializing Weather API client...") # self.tool_config is the validated Pydantic model or dict from YAML api_key = self.tool_config.get("api_key") self.api_client = WeatherApiClient(api_key=api_key) print("INFO: Weather API client initialized.") async def cleanup(self, component: "SamAgentComponent", tool_config: "AnyToolConfig") -> None: """Closes the API client connection when the agent shuts down.""" print("INFO: Closing Weather API client...") if hasattr(self, "api_client"): await self.api_client.close() print("INFO: Weather API client closed.") # ... other required properties like tool_name, tool_description, etc. ... async def _run_async_impl(self, args: dict, **kwargs) -> dict: """Uses the initialized client to perform its task.""" location = args.get("location") if not hasattr(self, "api_client"): return {"error": "API client not initialized. Check lifecycle hooks."} weather_data = await self.api_client.get_weather(location) return {"weather": weather_data}   The YAML configuration remains simple, as the lifecycle logic is now part of the tool's code.  # In your agent's app_config: tools: - tool_type: python component_module: "my_agent.api_tool" class_name: "WeatherTool" tool_config: api_key: ${WEATHER_API_KEY}   ","version":"Next","tagName":"h3"},{"title":"Execution Order and Guarantees​","type":1,"pageTitle":"Creating Python Tools","url":"/solace-agent-mesh/docs/documentation/developing/creating-python-tools#execution-order-and-guarantees","content":" It's important to understand the order in which lifecycle hooks are executed, especially if you mix both YAML-based and class-based methods for a single tool.  Initialization (init): All init hooks are awaited during agent startup. A failure in any init hook will prevent the agent from starting. The YAML-based init_function is executed first.The class-based init() method is executed second. Cleanup (cleanup): All registered cleanup hooks are executed during agent shutdown. They run in LIFO (Last-In, First-Out) order relative to initialization. The class-based cleanup() method is executed first.The YAML-based cleanup_function is executed second.  This LIFO order for cleanup is intuitive: the resource that was initialized last is the first one to be torn down.    ","version":"Next","tagName":"h3"},{"title":"Adding Validated Configuration to Dynamic Tools​","type":1,"pageTitle":"Creating Python Tools","url":"/solace-agent-mesh/docs/documentation/developing/creating-python-tools#adding-validated-configuration-to-dynamic-tools","content":" For any class-based tool (DynamicTool or DynamicToolProvider) that requires configuration, this is the recommended pattern. By linking a Pydantic model to your tool class, you can add automatic validation and type safety to your tool_config. This provides several key benefits:  Automatic Validation: The agent will fail to start if the YAML configuration doesn't match your model, providing clear error messages.Type Safety: Inside your tool, self.tool_config is a fully typed Pydantic object, not a dictionary, enabling autocompletion and preventing common errors.Self-Documentation: The Pydantic model itself serves as clear, machine-readable documentation for your tool's required configuration.  ","version":"Next","tagName":"h2"},{"title":"Example 1: Using a Pydantic Model with a Single DynamicTool​","type":1,"pageTitle":"Creating Python Tools","url":"/solace-agent-mesh/docs/documentation/developing/creating-python-tools#example-1-using-a-pydantic-model-with-a-single-dynamictool","content":" This example shows how to add a validated configuration to a standalone DynamicTool class.  Step 1: Define the Model and Tool Class​  In your tools file, define a pydantic.BaseModel for your configuration. Then, in your DynamicTool class, link to it using the config_model class attribute.  # src/my_agent/weather_tools.py from typing import Dict, Any from pydantic import BaseModel, Field from google.genai import types as adk_types from solace_agent_mesh.agent.tools.dynamic_tool import DynamicTool # 1. Define the configuration model class WeatherConfig(BaseModel): api_key: str = Field(..., description="The API key for the weather service.") default_unit: str = Field(default="celsius", description="The default temperature unit.") # 2. Create a tool and link the config model class GetCurrentWeatherTool(DynamicTool): config_model = WeatherConfig def __init__(self, tool_config: WeatherConfig): super().__init__(tool_config) # self.tool_config is now a validated WeatherConfig instance # You can safely access attributes with type safety self.api_key = self.tool_config.api_key self.unit = self.tool_config.default_unit @property def tool_name(self) -> str: return "get_current_weather" @property def tool_description(self) -> str: return f"Get the current weather. The default unit is {self.unit}." @property def parameters_schema(self) -> adk_types.Schema: return adk_types.Schema( type=adk_types.Type.OBJECT, properties={ "location": adk_types.Schema(type=adk_types.Type.STRING, description="The city and state/country."), }, required=["location"], ) async def _run_async_impl(self, args: Dict[str, Any], **kwargs) -> Dict[str, Any]: # ... implementation using self.api_key ... return {"weather": f"Sunny in {args['location']}"}   Step 2: Configure the Tool in YAML​  The YAML configuration remains simple. The framework handles the validation against your Pydantic model automatically.  # In your agent's app_config: tools: - tool_type: python component_module: "my_agent.weather_tools" # The framework will auto-discover the GetCurrentWeatherTool class tool_config: api_key: ${WEATHER_API_KEY} default_unit: "fahrenheit" # Optional, overrides the model's default   If you were to forget api_key in the YAML, the agent would fail to start and print a clear error message indicating that the api_key field is required, making debugging configuration issues much easier.  ","version":"Next","tagName":"h3"},{"title":"Example 2: Using a Pydantic Model with a DynamicToolProvider​","type":1,"pageTitle":"Creating Python Tools","url":"/solace-agent-mesh/docs/documentation/developing/creating-python-tools#example-2-using-a-pydantic-model-with-a-dynamictoolprovider","content":" The same pattern applies to tool providers, allowing you to pass a validated, type-safe configuration object to your tool factory.  Step 1: Define the Model and Provider Class​  # src/my_agent/weather_tools_provider.py from typing import List from pydantic import BaseModel, Field from solace_agent_mesh.agent.tools.dynamic_tool import DynamicTool, DynamicToolProvider # ... assume GetCurrentWeatherTool is defined in this file or imported ... # 1. Define the configuration model class WeatherProviderConfig(BaseModel): api_key: str = Field(..., description="The API key for the weather service.") default_unit: str = Field(default="celsius", description="The default temperature unit.") # 2. Create a provider and link the config model class WeatherToolProvider(DynamicToolProvider): config_model = WeatherProviderConfig def create_tools(self, tool_config: WeatherProviderConfig) -> List[DynamicTool]: # The framework passes a validated WeatherProviderConfig instance here return [ GetCurrentWeatherTool(tool_config=tool_config) # You could create other tools here that also use the config ]   Step 2: Configure the Provider in YAML​  # In your agent's app_config: tools: - tool_type: python component_module: "my_agent.weather_tools_provider" # The framework will auto-discover the WeatherToolProvider tool_config: api_key: ${WEATHER_API_KEY} default_unit: "fahrenheit" # Optional, overrides the model's default  ","version":"Next","tagName":"h3"},{"title":"Project Structure","type":0,"sectionRef":"#","url":"/solace-agent-mesh/docs/documentation/developing/structure","content":"","keywords":"","version":"Next"},{"title":"Shared Configuration​","type":1,"pageTitle":"Project Structure","url":"/solace-agent-mesh/docs/documentation/developing/structure#shared-configuration","content":" The shared_config.yaml file is the foundation of your project configuration. It contains common elements that are reused across all agents and gateways using YAML anchors:  Broker Connection: Solace event broker settings for A2A communicationModel Definitions: LLM model configurations (planning, general, multimodal, etc.)Services: Artifact service, session service, and data tools configuration  This shared configuration approach eliminates duplication and ensures consistency across your entire project. Each agent and gateway configuration file references these shared elements using YAML anchor syntax (*reference_name).  Further values can be added to the shared configuration file as needed, and they are available to all agents and gateways that include it.  ","version":"Next","tagName":"h3"},{"title":"YAML Configuration Files​","type":1,"pageTitle":"Project Structure","url":"/solace-agent-mesh/docs/documentation/developing/structure#yaml-configuration-files","content":" Each configuration file defines one (recommended) or more applications that can be run independently. The framework supports:  Agent Applications: A2A-enabled agents that use Google ADK runtime and Agent Mesh frameworkGateway Applications: Protocol translators that bridge external interfaces to adopted A2A protocolPlugin Applications: Specialized components that extend framework capabilities  ","version":"Next","tagName":"h2"},{"title":"Configuration Management​","type":1,"pageTitle":"Project Structure","url":"/solace-agent-mesh/docs/documentation/developing/structure#configuration-management","content":" Environment Variables: Configuration values use environment variables for flexibility across environmentsShared Configuration: Common settings are defined once in shared_config.yaml and referenced using YAML anchors (& and *)Automatic Generation: The sam add agent, sam add gateway, and sam plugin add commands automatically generate appropriate configuration filesStandalone Execution: Each configuration file can be run independently using sam run <config-file>  ","version":"Next","tagName":"h2"},{"title":"Python Components​","type":1,"pageTitle":"Project Structure","url":"/solace-agent-mesh/docs/documentation/developing/structure#python-components","content":" Although most functionality is configured through YAML, custom Python components can be added to the src/ directory when needed. The framework provides base classes for extending functionality such as custom agent tools, gateway protocol handlers, and service providers. ","version":"Next","tagName":"h2"},{"title":"Amazon Bedrock Agents Integration","type":0,"sectionRef":"#","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/bedrock-agents","content":"","keywords":"","version":"Next"},{"title":"What are Amazon Bedrock Agents and Flows?​","type":1,"pageTitle":"Amazon Bedrock Agents Integration","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/bedrock-agents#what-are-amazon-bedrock-agents-and-flows","content":" Amazon Bedrock Agents are AI assistants that can be customized to perform specific tasks using foundation models (FMs). They can connect to enterprise systems and data sources, allowing them to take actions on behalf of users.  Amazon Bedrock Flows are visual workflows that orchestrate multiple foundation models to solve complex problems. They allow you to chain together different AI capabilities without writing code.  By integrating these services with Agent Mesh, you can:  Use the extensible Agent Mesh framework to combine Bedrock agents and flows with other agents.Create conversational interfaces that leverage Bedrock agents and flows.Connect your Agent Mesh agents to enterprise data sources through Bedrock.Maintain a consistent experience across different agent providers by centralizing them in Agent Mesh.  Learn about Bedrock Agents and Flows Check the official documentation for Amazon Bedrock Agents and Amazon Bedrock Flows to learn more about these features.  ","version":"Next","tagName":"h2"},{"title":"Setting Up the Environment​","type":1,"pageTitle":"Amazon Bedrock Agents Integration","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/bedrock-agents#setting-up-the-environment","content":" ","version":"Next","tagName":"h2"},{"title":"Create Bedrock Agents and Flows​","type":1,"pageTitle":"Amazon Bedrock Agents Integration","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/bedrock-agents#create-bedrock-agents-and-flows","content":" Follow these steps to create your Bedrock resources:  Log in to your AWS console Navigate to the Amazon Bedrock service Create Bedrock Agents Go to the Agents tab in the Bedrock consoleClick "Create agent"Follow the wizard to configure your agent: Select a foundation modelDefine the agent's instructionsConfigure knowledge bases (optional)Set up action groups (if needed) Once created, create an alias for your agent by selecting it and clicking "Create alias"Copy the Agent ID and Alias ID from the agent details page - you'll need these for the Agent Mesh configuration Create Bedrock Flows Go to the Flows tab in the Bedrock consoleClick "Create flow"Use the visual editor to design your flowConnect nodes to create your workflowTest and publish your flowCreate an alias for your flowCopy the Flow ID and Alias ID - you'll need these for the Agent Mesh configuration Set up IAM permissions Ensure your IAM user or role has the following permissions: bedrock:InvokeAgentbedrock:InvokeFlowAny other permissions required by your specific Bedrock configuration  ","version":"Next","tagName":"h3"},{"title":"Create an Agent Mesh Project​","type":1,"pageTitle":"Amazon Bedrock Agents Integration","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/bedrock-agents#create-an-agent-mesh-project","content":" You must install Agent Mesh and Solace Mesh Agent CLI, and then you'll want to create a new Agent Mesh project.  ","version":"Next","tagName":"h3"},{"title":"Integrating Bedrock with Agent Mesh​","type":1,"pageTitle":"Amazon Bedrock Agents Integration","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/bedrock-agents#integrating-bedrock-with-agent-mesh","content":" ","version":"Next","tagName":"h2"},{"title":"Adding the Bedrock Agent Plugin​","type":1,"pageTitle":"Amazon Bedrock Agents Integration","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/bedrock-agents#adding-the-bedrock-agent-plugin","content":" The sam-bedrock-agent plugin from the solace-agent-mesh-core-plugins repository creates a bridge between Agent Mesh and Amazon Bedrock services. This plugin allows your Agent Mesh agents to invoke Bedrock Agents and Flows as tools.  Add the plugin to your Agent Mesh project:  sam plugin add aws-agent --plugin sam-bedrock-agent   Replace aws-agent with a descriptive name for your agent, such as bedrock-summarizer or bedrock-customer-service.  This command:  Installs the sam-bedrock-agent pluginCreates a new agent configuration file in configs/agents/aws-agent.yaml  Locate the configuration file:  The command creates an aws-agent.yaml file in the configs/agents/ directory of your Agent Mesh project.  Naming Convention Choose a descriptive name that reflects the purpose of your Bedrock integration. This name is used to reference the agent in your Agent Mesh project.  ","version":"Next","tagName":"h3"},{"title":"Configuring the Bedrock Agent​","type":1,"pageTitle":"Amazon Bedrock Agents Integration","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/bedrock-agents#configuring-the-bedrock-agent","content":" The configuration file you created needs to be edited to connect to your specific Amazon Bedrock resources. This section explains each part of the configuration and how to customize it.  ","version":"Next","tagName":"h2"},{"title":"Understanding the Configuration Structure​","type":1,"pageTitle":"Amazon Bedrock Agents Integration","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/bedrock-agents#understanding-the-configuration-structure","content":" Open the aws-agent.yaml file in your editor. The core of the agent's configuration consists of:  amazon_bedrock_runtime_config: AWS connection settingstools: List of Bedrock agents and flows to expose as toolsagent_card: Agent capabilities and skills definition  ","version":"Next","tagName":"h3"},{"title":"Example Configuration​","type":1,"pageTitle":"Amazon Bedrock Agents Integration","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/bedrock-agents#example-configuration","content":" Here's an annotated example based on the actual plugin structure:  log: stdout_log_level: INFO log_file_level: DEBUG log_file: aws-agent.log !include ../shared_config.yaml apps: - name: aws-agent-app app_base_path: . app_module: solace_agent_mesh.agent.sac.app broker: <<: *broker_connection app_config: namespace: ${NAMESPACE} supports_streaming: true agent_name: "AwsAgent" display_name: "AwsAgent Component" model: *general_model instruction: | You're AwsAgent responsible for handling user queries by interacting with Amazon Bedrock agents or flows. # AWS Connection Configuration amazon_bedrock_runtime_config: &amazon_bedrock_runtime_config endpoint_url: # Optional: Custom AWS endpoint URL boto3_config: region_name: "us-east-1" # AWS region where your Bedrock resources are located aws_access_key_id: # Your AWS access key (or use profiles/env vars) aws_secret_access_key: # Your AWS secret key tools: # Bedrock Agent Tool - tool_type: python component_module: sam_bedrock_agent.bedrock_agent component_base_path: . function_name: invoke_bedrock_agent tool_name: "text_transformer" # Customizable, Name exposed to the LLM tool_description: "Transforms text using the Text Transformer agent which summarizes the given text and extracts key points." # Customizable, Optional description tool_config: amazon_bedrock_runtime_config: *amazon_bedrock_runtime_config bedrock_agent_id: "XXXXXXXXXX" # Your actual Bedrock agent ID bedrock_agent_alias_id: "XXXXXXXXXX" # Your actual Bedrock agent alias ID allow_files: true # Whether to allow file uploads (5 files, 10MB total max) # Bedrock Flow Tool - tool_type: python component_module: sam_bedrock_agent.bedrock_flow component_base_path: . function_name: invoke_bedrock_flow tool_name: "poem_writer" # Name exposed to the LLM tool_config: amazon_bedrock_runtime_config: *amazon_bedrock_runtime_config bedrock_flow_id: "XXXXXXXXXX" # Your actual Bedrock flow ID bedrock_flow_alias_id: "XXXXXXXXXX" # Your actual Bedrock flow alias ID # Agent capabilities agent_card: description: "Agent that integrates with Amazon Bedrock agents and flows for various AI tasks." defaultInputModes: ["text"] defaultOutputModes: ["text"] skills: - id: "text_transformer" name: "Text Transformer" description: "Transforms text using the Text Transformer agent." - id: "poem_writer" name: "Poem Writer" description: "Generates poems based on user input." # A2A Protocol settings agent_card_publishing: { interval_seconds: 10 } agent_discovery: { enabled: true } inter_agent_communication: allow_list: ["*"] request_timeout_seconds: 30   ","version":"Next","tagName":"h3"},{"title":"Customizing Your Configuration​","type":1,"pageTitle":"Amazon Bedrock Agents Integration","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/bedrock-agents#customizing-your-configuration","content":" Follow these steps to customize your configuration:  Configure AWS Connection: Set the region_name to the AWS region where your Bedrock resources are locatedChoose one of these authentication methods: Set aws_access_key_id and aws_secret_access_key directly in the config.Use AWS profiles by removing these fields and configuring your AWS CLI profile.Use environment variables (see Environment Variables section below).  Check the boto3 documentation for more details.  Configure Bedrock Agent Tools: For each Bedrock agent you want to expose, add a tool entry: Set a descriptive tool_name (for example, text_summarizer, content_generator).Provide a clear tool_description of what the agent does.Replace bedrock_agent_id with your actual Bedrock agent ID.Replace bedrock_agent_alias_id with your actual Bedrock agent alias ID.Set allow_files to true if your agent can process file uploads. Configure Bedrock Flow Tools: For each Bedrock flow you want to expose, add a tool entry: Set a descriptive tool_name for the flow.Provide a clear tool_description of what the flow does (optional).Replace bedrock_flow_id with your actual Bedrock flow ID.Replace bedrock_flow_alias_id with your actual Bedrock flow alias ID. Update Agent Card Skills: Update the agent_card.description to reflect the purpose of your Bedrock agent (This is what other agents see).For each tool you add, create a corresponding skill entry in the agent_card.skills section.Use the same id as the tool_name.Provide a user-friendly name and description. Update Agent Instructions: Modify the instruction field to provide clear guidance on how the agent should respond to user queries.This instruction is used by the Agent's LLM to understand its role and capabilities.  info You must provide at least one Bedrock agent or flow tool. You can mix and match agents and flows in the same configuration.  ","version":"Next","tagName":"h3"},{"title":"Environment Variables​","type":1,"pageTitle":"Amazon Bedrock Agents Integration","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/bedrock-agents#environment-variables","content":" The Bedrock agent integration requires standard Solace connection variables and can use AWS environment variables for authentication.  Required Solace Variables:​  SOLACE_BROKER_URL: URL of your Solace brokerSOLACE_BROKER_USERNAME: Username for Solace broker authenticationSOLACE_BROKER_PASSWORD: Password for Solace broker authenticationSOLACE_BROKER_VPN: Solace message VPN nameSOLACE_AGENT_MESH_NAMESPACE: Namespace for your Agent Mesh project  Optional AWS Variables:​  If you prefer to use environment variables for AWS authentication instead of configuration in the YAML file:  AWS_ACCESS_KEY_ID: Your AWS access keyAWS_SECRET_ACCESS_KEY: Your AWS secret keyAWS_SESSION_TOKEN: If using temporary credentialsAWS_REGION or AWS_DEFAULT_REGION: AWS region for Bedrock services  AWS Credentials Precedence AWS credentials are loaded in this order: Explicit credentials in the YAML configurationEnvironment variablesAWS configuration files (~/.aws/credentials)EC2/ECS instance profiles (if running on AWS)  ","version":"Next","tagName":"h3"},{"title":"Running and Testing Your Integration​","type":1,"pageTitle":"Amazon Bedrock Agents Integration","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/bedrock-agents#running-and-testing-your-integration","content":" ","version":"Next","tagName":"h2"},{"title":"Starting Your Agent Mesh Project​","type":1,"pageTitle":"Amazon Bedrock Agents Integration","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/bedrock-agents#starting-your-agent-mesh-project","content":" After configuring your Bedrock agent integration, run your Agent Mesh project:  sam run configs/agents/aws-agent.yaml   This command starts the Bedrock agent with your specific configuration.  ","version":"Next","tagName":"h3"},{"title":"Testing the Integration​","type":1,"pageTitle":"Amazon Bedrock Agents Integration","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/bedrock-agents#testing-the-integration","content":" You can test your Bedrock agent integration through any gateway in your Agent Mesh project:  Using the Web UI Gateway​  Ensure you have a Web UI gateway running (typically at http://localhost:8000)Start a conversation with your agentAsk a question that would trigger your Bedrock agent or flow  Example: If you configured a Bedrock agent for text transformation:  Transform this text: "The quick brown fox jumps over the lazy dog. The lazy dog did not chase the fox. The fox was brown and quick, while the dog was lazy and slow. Despite their differences, they both enjoyed the sunny day in the meadow."   Example: If you configured a Bedrock flow for poem writing:  Write a poem about a sunset over the ocean.   Testing with File Uploads​  If you have enabled file uploads for your Bedrock agent (allow_files: true), you can test file processing:  In the Web UI, use the file upload button to attach a supported fileInclude a prompt that references the file, such as "Analyze this document" or "Summarize the content of this file"The file is sent to the Bedrock agent along with your prompt  Example with file upload:  Please analyze the attached document and provide key insights.   Supported File Types Bedrock agents support these file types for uploads: PDF documents (.pdf)Text files (.txt)Word documents (.doc, .docx)CSV files (.csv)Excel spreadsheets (.xls, .xlsx) There's a limit of 5 files with a total size of 10MB per request.  ","version":"Next","tagName":"h3"},{"title":"Troubleshooting​","type":1,"pageTitle":"Amazon Bedrock Agents Integration","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/bedrock-agents#troubleshooting","content":" ","version":"Next","tagName":"h2"},{"title":"Common Issues and Solutions​","type":1,"pageTitle":"Amazon Bedrock Agents Integration","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/bedrock-agents#common-issues-and-solutions","content":" Authentication Errors​  Issue: "Unable to locate credentials" or "Access denied" errorsSolution:  Verify your AWS credentials are correctly configuredCheck that your IAM user/role has the necessary permissionsTry using AWS CLI to test your credentials: aws bedrock list-foundation-models  Configuration Errors​  Issue: "Invalid agent ID" or "Invalid flow ID" errorsSolution:  Double-check your Bedrock agent and flow IDs in the configurationEnsure you've created aliases for your agents and flowsVerify the region in your configuration matches where your Bedrock resources are located  Connection Issues​  Issue: Agent Mesh can't connect to Bedrock servicesSolution:  Check your network connectivityVerify that Bedrock services are available in your configured regionCheck for any VPC or firewall restrictions  File Upload Issues​  Issue: Files aren't being processed by the Bedrock agentSolution:  Verify allow_files is set to true in your configurationCheck that your file type is supportedEnsure the file size is under the 10MB limitCheck the model context length ","version":"Next","tagName":"h3"},{"title":"Event Mesh Gateway","type":0,"sectionRef":"#","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/event-mesh-gateway","content":"","keywords":"","version":"Next"},{"title":"Benefits of Integrating with an Event Mesh​","type":1,"pageTitle":"Event Mesh Gateway","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/event-mesh-gateway#benefits-of-integrating-with-an-event-mesh","content":" Seamless Communication: Agent Mesh can subscribe to and publish events across the entire event meshEvent-Driven Automation: Intelligent event processing based on patterns and AI-driven insightsScalability: Agent Mesh can dynamically participate in large-scale event-driven systems  The Event Mesh Gateway connects Agent Mesh to your existing event mesh infrastructure. Through its asynchronous interfaces, applications within your event mesh can seamlessly access and utilize Agent Mesh capabilities.  This tutorial shows you how to build an Event Mesh Gateway that automatically generates and adds concise summaries to Jira bug reports, making them easier to understand at a glance.  ","version":"Next","tagName":"h2"},{"title":"Prerequisites​","type":1,"pageTitle":"Event Mesh Gateway","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/event-mesh-gateway#prerequisites","content":" This tutorial assumes you have an existing Jira application integrated with your event mesh that:  Publishes a "jira_created" event to topic jira/issue/created/<jira_id> when a new Jira issue is createdListens for "jira_update" events on topic jira/issue/update to update existing issues  Create an Event Mesh Gateway that:  Monitors for new Jira issuesAutomatically generates a concise summaryCreates an event to update the original Jira issue with this summary  This creates a streamlined workflow where bug reports are automatically enhanced with clear, AI-generated summaries.  ","version":"Next","tagName":"h2"},{"title":"Setting Up the Environment​","type":1,"pageTitle":"Event Mesh Gateway","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/event-mesh-gateway#setting-up-the-environment","content":" First, you need to install Agent Mesh and the Agent Mesh CLI, and then create a new Agent Mesh project.  For this tutorial, you need to create or use an existing Solace Event Broker or event mesh created using Solace event brokers.  ","version":"Next","tagName":"h2"},{"title":"Adding the Event Mesh Gateway Plugin​","type":1,"pageTitle":"Event Mesh Gateway","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/event-mesh-gateway#adding-the-event-mesh-gateway-plugin","content":" Once you have your project set up, add the Event Mesh Gateway plugin:  sam plugin add jira-event-mesh --plugin sam-event-mesh-gateway   You can use any name for your agent, in this tutorial we use jira-event-mesh.  This command:  Installs the sam-event-mesh-gateway pluginCreates a new gateway configuration named jira-event-mesh in your configs/gateways/ directory  Configuring the Event Mesh Gateway​  After adding the plugin, you can see a new configuration file in configs/gateways/jira-event-mesh.yaml. This file contains the gateway configuration that needs to be customized for your Jira integration use case.  Environment Variables​  First, set up the required environment variables for the data plane connection:  # Data plane Solace broker connection (can be same or different from control plane) export JIRA_EVENT_MESH_SOLACE_BROKER_URL="ws://localhost:8008" export JIRA_EVENT_MESH_SOLACE_BROKER_VPN="default" export JIRA_EVENT_MESH_SOLACE_BROKER_USERNAME="default" export JIRA_EVENT_MESH_SOLACE_BROKER_PASSWORD="default"   ","version":"Next","tagName":"h2"},{"title":"Gateway Configuration​","type":1,"pageTitle":"Event Mesh Gateway","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/event-mesh-gateway#gateway-configuration","content":" The main configuration includes several key sections:  Event Handlers​  Configure the event handler to listen for new Jira issues and generate summaries:  event_handlers: - name: "jira_issue_handler" subscriptions: - topic: "jira/issue/created/>" qos: 1 input_expression: "template:Create a concise summary for the newly created Jira issue: Title: {{text://input.payload:title}}, Body: {{text://input.payload:body}}, ID: {{text://input.payload:id}}. Return a JSON object with fields 'id', 'type' (value should be 'summary'), and 'summary'." payload_encoding: "utf-8" payload_format: "json" target_agent_name: "OrchestratorAgent" on_success: "jira_summary_handler" on_error: "error_response_handler" forward_context: jira_id: "input.payload:id" correlation_id: "input.user_properties:correlation_id"   Output Handlers​  Configure output handlers to publish the summary back to the event mesh:  output_handlers: - name: "jira_summary_handler" topic_expression: "static:jira/issue/update" payload_expression: "task_response:text" payload_encoding: "utf-8" payload_format: "json" - name: "error_response_handler" topic_expression: "template:jira/issue/error/{{text://user_data.forward_context:jira_id}}" payload_expression: "task_response:a2a_task_response.error" payload_encoding: "utf-8" payload_format: "json"   ","version":"Next","tagName":"h3"},{"title":"Complete Configuration Example​","type":1,"pageTitle":"Event Mesh Gateway","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/event-mesh-gateway#complete-configuration-example","content":" Here is a complete configuration file based on the plugin template:  log: stdout_log_level: INFO log_file_level: DEBUG log_file: jira-event-mesh.log !include ../shared_config.yaml apps: - name: jira-event-mesh-app app_module: sam_event_mesh_gateway.app broker: <<: *broker_connection app_config: namespace: ${NAMESPACE} gateway_id: "jira-event-mesh-gw-01" artifact_service: *default_artifact_service default_user_identity: "anonymous_event_mesh_user" # If no identity from event # Data plane connection event_mesh_broker_config: broker_url: ${JIRA_EVENT_MESH_SOLACE_BROKER_URL} broker_vpn: ${JIRA_EVENT_MESH_SOLACE_BROKER_VPN} broker_username: ${JIRA_EVENT_MESH_SOLACE_BROKER_USERNAME} broker_password: ${JIRA_EVENT_MESH_SOLACE_BROKER_PASSWORD} event_handlers: - name: "jira_issue_handler" subscriptions: - topic: "jira/issue/created/>" qos: 1 input_expression: "template:Create a concise summary for the newly created Jira issue: Title: {{text://input.payload:title}}, Body: {{text://input.payload:body}}, ID: {{text://input.payload:id}}. Return a JSON object with fields 'id', 'type' (value should be 'summary'), and 'summary'." payload_encoding: "utf-8" payload_format: "json" target_agent_name: "OrchestratorAgent" on_success: "jira_summary_handler" on_error: "error_response_handler" forward_context: jira_id: "input.payload:id" output_handlers: - name: "jira_summary_handler" topic_expression: "static:jira/issue/update" payload_expression: "task_response:text" payload_encoding: "utf-8" payload_format: "json" - name: "error_response_handler" topic_expression: "template:jira/issue/error/{{text://user_data.forward_context:jira_id}}" payload_expression: "task_response:a2a_task_response.error" payload_encoding: "utf-8" payload_format: "json"   ","version":"Next","tagName":"h3"},{"title":"Running the Event Mesh Gateway​","type":1,"pageTitle":"Event Mesh Gateway","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/event-mesh-gateway#running-the-event-mesh-gateway","content":" Now you can run the Event Mesh Gateway:  sam run configs/gateways/jira-event-mesh.yaml   The gateway:  Connects to both the A2A control plane and the data plane event meshSubscribes to the configured topics on the data planeStarts processing incoming events and routing them to agents  ","version":"Next","tagName":"h2"},{"title":"Testing the Event Mesh Gateway​","type":1,"pageTitle":"Event Mesh Gateway","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/event-mesh-gateway#testing-the-event-mesh-gateway","content":" Now that the system is running, let's test the Event Mesh Gateway.  ","version":"Next","tagName":"h2"},{"title":"Using The Solace Broker Manager​","type":1,"pageTitle":"Event Mesh Gateway","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/event-mesh-gateway#using-the-solace-broker-manager","content":" Open the Try Me! tab of the Solace Broker Manager Connect both the Publisher and Subscriber panels by clicking their respective Connect buttons In the Subscriber panel: Enter jira/issue/update in the Topic Subscriber fieldClick Subscribe In the Publisher panel: Use the topic jira/issue/created/JIRA-143321In the Message Content field, enter:  { "id": "JIRA-143321", "title": "Exception when reading customer record", "body": "I got a DatabaseReadException when trying to get the data for customer ABC. The error indicated that the customer didn't exist, while they are our biggest customer!" }   Click Publish  After a few seconds, you can see a new message in the Subscriber messages with the topic jira/issue/update and a body similar to:  { "id": "JIRA-143321", "type": "summary", "summary": "Database read error: Unable to retrieve record for key customer ABC despite confirmed existence" }   ","version":"Next","tagName":"h3"},{"title":"Advanced Features​","type":1,"pageTitle":"Event Mesh Gateway","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/event-mesh-gateway#advanced-features","content":" The Event Mesh Gateway supports several advanced features:  ","version":"Next","tagName":"h2"},{"title":"Artifact Processing​","type":1,"pageTitle":"Event Mesh Gateway","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/event-mesh-gateway#artifact-processing","content":" You can configure the gateway to automatically create artifacts from incoming message payloads before sending them to agents. This is useful for processing files, images, or other binary data embedded in events.  ","version":"Next","tagName":"h3"},{"title":"Dynamic Agent Routing​","type":1,"pageTitle":"Event Mesh Gateway","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/event-mesh-gateway#dynamic-agent-routing","content":" Instead of using a static target_agent_name, you can use target_agent_name_expression to dynamically determine which agent should process each event based on the message content.  ","version":"Next","tagName":"h3"},{"title":"Context Forwarding​","type":1,"pageTitle":"Event Mesh Gateway","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/event-mesh-gateway#context-forwarding","content":" The forward_context configuration allows you to extract data from incoming messages and make it available when generating outgoing responses, enabling request-reply patterns and correlation tracking.  ","version":"Next","tagName":"h3"},{"title":"Error Handling​","type":1,"pageTitle":"Event Mesh Gateway","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/event-mesh-gateway#error-handling","content":" Configure separate output handlers for success and error scenarios to ensure proper error reporting and system monitoring. ","version":"Next","tagName":"h3"},{"title":"MongoDB Integration","type":0,"sectionRef":"#","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/mongodb-integration","content":"","keywords":"","version":"Next"},{"title":"Prerequisites​","type":1,"pageTitle":"MongoDB Integration","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/mongodb-integration#prerequisites","content":" Before starting this tutorial, ensure that you have installed and configured Agent Mesh:  Installed Agent Mesh and the Agent Mesh CLICreated a new Agent Mesh projectAccess to a MongoDB database (local or remote)  ","version":"Next","tagName":"h2"},{"title":"Adding the MongoDB Plugin​","type":1,"pageTitle":"MongoDB Integration","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/mongodb-integration#adding-the-mongodb-plugin","content":" Add the MongoDB plugin to your Agent Mesh project:  sam plugin add coffee-shop-mongo --plugin sam-mongodb   You can use any name for your agent, in this tutorial we use coffee-shop-mongo.  This command:  Installs the sam-mongodb pluginCreates a new agent configuration file at configs/agents/coffee-shop-mongo.yaml  Setting Up Your MongoDB Database​  This tutorial assumes you have a MongoDB database with a collection containing coffee shop data. You can use any MongoDB database, but here is an example structure for a coffee shop:  Example Document Structure​  { "_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" }   ","version":"Next","tagName":"h2"},{"title":"Configuring the Agent​","type":1,"pageTitle":"MongoDB Integration","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/mongodb-integration#configuring-the-agent","content":" Open the configs/agents/coffee-shop-mongo.yaml file and modify the agent_init_function.config section to connect to your MongoDB database.  Here is what you need to modify in the configuration file:  # Find the agent_init_function section and update the config: agent_init_function: module: "sam_mongodb.lifecycle" name: "initialize_mongo_agent" config: db_host: "${COFFEE_SHOP_MONGO_MONGO_HOST}" db_port: ${COFFEE_SHOP_MONGO_MONGO_PORT} db_user: "${COFFEE_SHOP_MONGO_MONGO_USER}" db_password: "${COFFEE_SHOP_MONGO_MONGO_PASSWORD}" db_name: "${COFFEE_SHOP_MONGO_MONGO_DB}" database_collection: "${COFFEE_SHOP_MONGO_MONGO_COLLECTION}" database_purpose: "${COFFEE_SHOP_MONGO_DB_PURPOSE}" data_description: "${COFFEE_SHOP_MONGO_DB_DESCRIPTION}" auto_detect_schema: true max_inline_results: 10   Setting the Environment Variables​  The MongoDB agent requires several environment variables. Create or update your .env file with the following variables:  # MongoDB Connection Settings COFFEE_SHOP_MONGO_MONGO_HOST=localhost COFFEE_SHOP_MONGO_MONGO_PORT=27017 COFFEE_SHOP_MONGO_MONGO_USER=your_username COFFEE_SHOP_MONGO_MONGO_PASSWORD=your_password COFFEE_SHOP_MONGO_MONGO_DB=coffee_shop COFFEE_SHOP_MONGO_MONGO_COLLECTION=orders # Database Description COFFEE_SHOP_MONGO_DB_PURPOSE="Coffee shop order management database" COFFEE_SHOP_MONGO_DB_DESCRIPTION="Contains customer orders, product information, sales data, and transaction history for a coffee shop business." # Optional Settings AUTO_DETECT_SCHEMA=true MAX_INLINE_RESULTS=10   MongoDB Connection Options​  Local MongoDB: Use localhost as the host and default port 27017MongoDB Atlas: Use your Atlas connection string formatAuthentication: Provide username and password if your MongoDB requires authenticationNo Authentication: Leave username and password empty for local development databases  ","version":"Next","tagName":"h2"},{"title":"Running the Agent​","type":1,"pageTitle":"MongoDB Integration","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/mongodb-integration#running-the-agent","content":" Now you can start your MongoDB agent:  sam run configs/agents/coffee-shop-mongo.yaml   The agent:  Connects to the A2A control planeInitializes the MongoDB connectionDetects the database schema automaticallyRegisters its capabilities with the agent discovery system  ","version":"Next","tagName":"h2"},{"title":"Interacting with the Database​","type":1,"pageTitle":"MongoDB Integration","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/mongodb-integration#interacting-with-the-database","content":" After your MongoDB agent is running, you can interact with the database through any gateway in your Agent Mesh project (such as the Web UI gateway at http://localhost:8000).  You can ask natural language questions about your MongoDB database, such as:  "How many orders were placed today?""What are the most popular coffee products?""Show me all orders from customers in New York""What's the average order value this month?""Find all incomplete orders""Group orders by payment method and show totals"  Try creating reports by asking questions such as:  "Create a sales report for the last 7 days""Generate a summary of customer preferences""Show me the top 10 customers by total spending"  The MongoDB agent converts your natural language questions into MongoDB aggregation pipelines, executes them against the database, and returns the results. For large result sets, the agent automatically saves the results as artifacts that you can download.  ","version":"Next","tagName":"h2"},{"title":"Advanced Configuration​","type":1,"pageTitle":"MongoDB Integration","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/mongodb-integration#advanced-configuration","content":" The MongoDB plugin supports many advanced configuration options. Here is a complete example based on the plugin structure:  log: stdout_log_level: INFO log_file_level: DEBUG log_file: coffee-shop-mongo.log !include ../shared_config.yaml apps: - name: coffee-shop-mongo-app app_module: solace_agent_mesh.agent.sac.app broker: <<: *broker_connection app_config: namespace: ${NAMESPACE} agent_name: "CoffeeShopMongo" display_name: "Coffee Shop MongoDB Agent" supports_streaming: false model: *general_model instruction: | You are an expert MongoDB assistant for the coffee shop database. Your primary goal is to translate user questions into accurate MongoDB aggregation pipelines. When asked to query the database, generate the pipeline and call the query tool. If the tool returns an error, analyze the error message and the original pipeline, then try to correct the pipeline and call the tool again. Always provide clear explanations of the results you find. # Agent initialization with database setup agent_init_function: module: "sam_mongodb.lifecycle" name: "initialize_mongo_agent" config: db_host: "${COFFEE_SHOP_MONGO_MONGO_HOST}" db_port: ${COFFEE_SHOP_MONGO_MONGO_PORT} db_user: "${COFFEE_SHOP_MONGO_MONGO_USER}" db_password: "${COFFEE_SHOP_MONGO_MONGO_PASSWORD}" db_name: "${COFFEE_SHOP_MONGO_MONGO_DB}" database_collection: "${COFFEE_SHOP_MONGO_MONGO_COLLECTION}" database_purpose: "${COFFEE_SHOP_MONGO_DB_PURPOSE}" data_description: "${COFFEE_SHOP_MONGO_DB_DESCRIPTION}" auto_detect_schema: true max_inline_results: 10 agent_cleanup_function: module: "sam_mongodb.lifecycle" name: "cleanup_mongo_agent_resources" # MongoDB query tool tools: - tool_type: builtin-group group_name: "artifact_management" - tool_type: builtin-group group_name: "data_analysis" - tool_type: python component_module: "sam_mongodb.search_query" function_name: "mongo_query" tool_config: collection: "${COFFEE_SHOP_MONGO_MONGO_COLLECTION}" session_service: *default_session_service artifact_service: *default_artifact_service # Artifact handling artifact_handling_mode: "reference" enable_embed_resolution: true enable_artifact_content_instruction: true # Agent capabilities - This is what other agents see during discovery agent_card: description: "Coffee Shop MongoDB Agent - Access to comprehensive coffee shop order data including customer information, product details, sales transactions, and order history. Can answer questions about sales analytics, customer behavior, product performance, and business metrics." defaultInputModes: ["text"] defaultOutputModes: ["text", "file"] skills: - id: "mongo_query" name: "Coffee Shop MongoDB Query" description: "Queries coffee shop MongoDB database containing customer orders, product catalog, payment transactions, and order history using aggregation pipelines." # A2A Protocol settings agent_card_publishing: { interval_seconds: 30 } agent_discovery: { enabled: true } inter_agent_communication: allow_list: ["*"] request_timeout_seconds: 60   ","version":"Next","tagName":"h2"},{"title":"Customizing the Agent Card​","type":1,"pageTitle":"MongoDB Integration","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/mongodb-integration#customizing-the-agent-card","content":" The agent_card section is crucial as it defines how other agents in your Agent Mesh ecosystem discover and understand this MongoDB agent's capabilities. When other agents use agent discovery, they can see this information to decide whether to delegate tasks to your database agent.  ","version":"Next","tagName":"h2"},{"title":"Key Agent Card Elements​","type":1,"pageTitle":"MongoDB Integration","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/mongodb-integration#key-agent-card-elements","content":" Description: Clearly describe what data the agent has access to and what types of questions it can answerSkills: List specific capabilities with concrete examples that show the scope of data availableData Context: Mention the business domain, data types, and scope of information available  ","version":"Next","tagName":"h3"},{"title":"Example of a Well-Configured Agent Card​","type":1,"pageTitle":"MongoDB Integration","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/mongodb-integration#example-of-a-well-configured-agent-card","content":" agent_card: description: "Coffee Shop MongoDB Agent - Access to comprehensive coffee shop order data including customer information, product details, sales transactions, and order history. Can answer questions about sales analytics, customer behavior, product performance, and business metrics." defaultInputModes: ["text"] defaultOutputModes: ["text", "file"] skills: - id: "mongo_query" name: "Coffee Shop MongoDB Query" description: "Queries coffee shop MongoDB database containing customer orders, product catalog, payment transactions, and order history using aggregation pipelines."   This detailed information helps other agents understand:  What business domain this agent covers (coffee shop operations)What types of data are available (orders, customers, products, payments)What kinds of questions can be answered (analytics, behavior, performance, metrics)Specific examples of queries that work well with MongoDB aggregation pipelines  When configuring your own MongoDB agent, customize the description and examples to match your specific data structure and use cases.  ","version":"Next","tagName":"h3"},{"title":"MongoDB Query Features​","type":1,"pageTitle":"MongoDB Integration","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/mongodb-integration#mongodb-query-features","content":" The MongoDB agent supports various types of queries through natural language:  ","version":"Next","tagName":"h2"},{"title":"Aggregation Queries​","type":1,"pageTitle":"MongoDB Integration","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/mongodb-integration#aggregation-queries","content":" "Show me the top 5 products by sales volume""Calculate the average order value by customer segment""Group orders by month and show revenue trends"  ","version":"Next","tagName":"h3"},{"title":"Filtering and Search​","type":1,"pageTitle":"MongoDB Integration","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/mongodb-integration#filtering-and-search","content":" "Find all orders placed in the last 24 hours""Show me orders with a total amount greater than $50""Find customers who ordered espresso drinks"  ","version":"Next","tagName":"h3"},{"title":"Complex Analytics​","type":1,"pageTitle":"MongoDB Integration","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/mongodb-integration#complex-analytics","content":" "What's the conversion rate from browsing to purchase?""Show me the busiest hours of the day""Calculate customer lifetime value"  ","version":"Next","tagName":"h3"},{"title":"Output Formats​","type":1,"pageTitle":"MongoDB Integration","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/mongodb-integration#output-formats","content":" The agent supports multiple output formats:  JSON: Default format, good for structured dataYAML: Human-readable formatCSV: Suitable for spreadsheet importMarkdown: Formatted for documentation  You can specify the format in your query: "Show me today's sales in CSV format"  ","version":"Next","tagName":"h3"},{"title":"Troubleshooting​","type":1,"pageTitle":"MongoDB Integration","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/mongodb-integration#troubleshooting","content":" ","version":"Next","tagName":"h2"},{"title":"Common Issues and Solutions​","type":1,"pageTitle":"MongoDB Integration","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/mongodb-integration#common-issues-and-solutions","content":" Connection Errors​  Issue: "Unable to connect to MongoDB" errorsSolution:  Verify your MongoDB server is runningCheck connection parameters (host, port, credentials)Ensure network connectivity and firewall settingsTest connection using MongoDB client tools  Authentication Errors​  Issue: "Authentication failed" errorsSolution:  Verify username and password are correctCheck that the user has appropriate database permissionsEnsure the authentication database is correct  Query Errors​  Issue: "Invalid aggregation pipeline" errorsSolution:  The agent automatically retries with corrected pipelinesCheck that your natural language query is clear and specificVerify that referenced fields exist in your collection  Schema Detection Issues​  Issue: Agent does not understand your data structureSolution:  Ensure auto_detect_schema is set to trueProvide detailed data_description in your configurationCheck that your collection has representative sample documents ","version":"Next","tagName":"h3"},{"title":"MCP Integration","type":0,"sectionRef":"#","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/mcp-integration","content":"","keywords":"","version":"Next"},{"title":"Setting Up the Environment​","type":1,"pageTitle":"MCP Integration","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/mcp-integration#setting-up-the-environment","content":" You must install Agent Mesh and the CLI, and then create a new Agent Mesh project.  For this tutorial using the filesystem MCP server, you also need Node.js and NPM installed.  ","version":"Next","tagName":"h2"},{"title":"Adding MCP Tools to an Agent​","type":1,"pageTitle":"MCP Integration","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/mcp-integration#adding-mcp-tools-to-an-agent","content":" MCP integration is accomplished by adding MCP tools directly to your agent configuration. There are three main connection types supported:  ","version":"Next","tagName":"h2"},{"title":"1. Stdio Connection (Local MCP Servers)​","type":1,"pageTitle":"MCP Integration","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/mcp-integration#1-stdio-connection-local-mcp-servers","content":" This is the most common method for connecting to MCP servers that run as local processes:  tools: - tool_type: mcp connection_params: type: stdio command: "npx" args: - "-y" - "@modelcontextprotocol/server-filesystem" - "/tmp/samv2"   ","version":"Next","tagName":"h3"},{"title":"2. SSE Connection (Remote MCP Servers)​","type":1,"pageTitle":"MCP Integration","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/mcp-integration#2-sse-connection-remote-mcp-servers","content":" For connecting to remote MCP servers using Server-Sent Events:  tools: - tool_type: mcp connection_params: type: sse url: "https://mcp.example.com/v1/sse" headers: Authorization: "Bearer ${MCP_AUTH_TOKEN}"   ","version":"Next","tagName":"h3"},{"title":"3. StreamableHTTP Connection (Remote MCP Servers)​","type":1,"pageTitle":"MCP Integration","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/mcp-integration#3-streamablehttp-connection-remote-mcp-servers","content":" For connecting to remote MCP servers using Server-Sent Events:  tools: - tool_type: mcp connection_params: type: streamable-http url: "https://mcp.example.com:<port>/mcp/message" headers: Authorization: "Bearer ${MCP_AUTH_TOKEN}"   ","version":"Next","tagName":"h3"},{"title":"4. Docker Connection (Containerized MCP Servers)​","type":1,"pageTitle":"MCP Integration","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/mcp-integration#4-docker-connection-containerized-mcp-servers","content":" For running MCP servers in Docker containers:  tools: - tool_type: mcp connection_params: type: stdio command: "docker" args: - "run" - "-i" - "--rm" - "-e" - "API_KEY" - "mcp-server-image:latest" environment_variables: API_KEY: ${MY_API_KEY}   ","version":"Next","tagName":"h3"},{"title":"Complete Example: Filesystem MCP Agent​","type":1,"pageTitle":"MCP Integration","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/mcp-integration#complete-example-filesystem-mcp-agent","content":" Here is a complete example of an agent that uses the filesystem MCP server:  # configs/agents/filesystem_agent.yaml log: stdout_log_level: INFO log_file_level: DEBUG log_file: filesystem_agent.log !include ../shared_config.yaml apps: - name: filesystem_mcp_agent_app app_base_path: . app_module: solace_agent_mesh.agent.sac.app broker: <<: *broker_connection app_config: namespace: ${NAMESPACE} supports_streaming: true agent_name: "FileSystemAgent" display_name: "File System" model: *general_model instruction: | You can interact with the local filesystem using MCP tools. Use the available tools to read, write, and manage files as requested. tools: - tool_type: mcp connection_params: type: stdio command: "npx" args: - "-y" - "@modelcontextprotocol/server-filesystem" - "/tmp/samv2" - tool_type: builtin-group group_name: "artifact_management" session_service: *default_session_service artifact_service: *default_artifact_service # Agent discovery and communication agent_card: description: "An agent that interacts with the local filesystem via MCP." defaultInputModes: ["text"] defaultOutputModes: ["text", "file"] skills: [] agent_card_publishing: { interval_seconds: 10 } agent_discovery: { enabled: true } inter_agent_communication: allow_list: ["*"] request_timeout_seconds: 30   ","version":"Next","tagName":"h2"},{"title":"Configuration Options​","type":1,"pageTitle":"MCP Integration","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/mcp-integration#configuration-options","content":" ","version":"Next","tagName":"h2"},{"title":"Tool-Specific Configuration​","type":1,"pageTitle":"MCP Integration","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/mcp-integration#tool-specific-configuration","content":" You can limit which tools from an MCP server are available by specifying a specific tool name:  tools: - tool_type: mcp tool_name: "read_file" # Only expose the read_file tool connection_params: type: stdio command: "npx" args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp/samv2"]   ","version":"Next","tagName":"h3"},{"title":"Environment Variables​","type":1,"pageTitle":"MCP Integration","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/mcp-integration#environment-variables","content":" Pass environment variables to MCP servers using the environment_variables block:  tools: - tool_type: mcp connection_params: type: stdio command: "my-mcp-server" environment_variables: API_KEY: ${MY_API_KEY} DEBUG_MODE: "true" CONFIG_PATH: "/etc/myconfig"   ","version":"Next","tagName":"h3"},{"title":"Running Your MCP-Enabled Agent​","type":1,"pageTitle":"MCP Integration","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/mcp-integration#running-your-mcp-enabled-agent","content":" Create the working directory (for filesystem example): mkdir -p /tmp/samv2 echo "Hello MCP!" > /tmp/samv2/test.txt Set required environment variables: export NAMESPACE="myorg/dev" export SOLACE_BROKER_URL="ws://localhost:8008" # ... other Solace broker settings Run the agent: sam run configs/agents/filesystem_agent.yaml   ","version":"Next","tagName":"h2"},{"title":"How MCP Integration Works​","type":1,"pageTitle":"MCP Integration","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/mcp-integration#how-mcp-integration-works","content":" When your agent starts:  Connection: The framework establishes a connection to the MCP server using the specified connection parametersDiscovery: It queries the MCP server for available tools, resources, and promptsRegistration: Available capabilities are registered as agent tools.Communication: The agent can use these tools through the standard A2A protocol, with the framework handling MCP protocol translation  ","version":"Next","tagName":"h2"},{"title":"Testing Your MCP Integration​","type":1,"pageTitle":"MCP Integration","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/mcp-integration#testing-your-mcp-integration","content":" Once your MCP-enabled agent is running, you can test it through any gateway in your project (such as the Web UI gateway):  Access your gateway (for example, Web UI at http://localhost:8000)Send a request to test the MCP functionality: "List the files in the directory""Create a simple text file with some content""Read the contents of test.txt"  The agent uses the MCP tools to interact with the filesystem and provide responses through the A2A protocol. ","version":"Next","tagName":"h2"},{"title":"REST Gateway","type":0,"sectionRef":"#","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/rest-gateway","content":"","keywords":"","version":"Next"},{"title":"Key Features​","type":1,"pageTitle":"REST Gateway","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/rest-gateway#key-features","content":" Dual API Versions: Supports both a modern asynchronous API (v2) and a deprecated synchronous API (v1) for backward compatibility.Asynchronous by Default: The v2 API uses a "202 Accepted + Poll" pattern, ideal for long-running agent tasks.Delegated Authentication: Integrates with an external authentication service via bearer tokens for secure access.File Handling: Supports file uploads for tasks and provides download URLs for generated artifacts.Dynamic Configuration: All gateway behaviors, including server settings and authentication, are configured via the main Agent Mesh Host YAML file.  ","version":"Next","tagName":"h2"},{"title":"Setting Up the Environment​","type":1,"pageTitle":"REST Gateway","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/rest-gateway#setting-up-the-environment","content":" First, you need to install Agent Mesh and the Agent Mesh CLI, and then create a new Agent Mesh project.  ","version":"Next","tagName":"h2"},{"title":"Adding the REST Gateway Plugin​","type":1,"pageTitle":"REST Gateway","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/rest-gateway#adding-the-rest-gateway-plugin","content":" Once you have your project set up, add the REST Gateway plugin:  sam plugin add my-http-rest --plugin sam-rest-gateway   You can use any name for your agent, in this tutorial we use my-http-rest.  This command:  Installs the sam-rest-gateway pluginCreates a new gateway configuration named my-http-rest in your configs/gateways/ directory  ","version":"Next","tagName":"h2"},{"title":"Configuring the REST Gateway​","type":1,"pageTitle":"REST Gateway","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/rest-gateway#configuring-the-rest-gateway","content":" For further configuration, you can edit the configs/gateways/my-http-rest.yaml file. This file contains the gateway configuration that can be customized for your use case.  Using a local Solace Broker container The Solace broker container uses port 8080. You need to edit the rest_api_server_port field and external_auth_service_url field in the configs/gateways/my-http-rest.yaml file to a free port other than 8080 (for example: 8081). You can edit the YAML file directly or add environment variables REST_API_PORT=8081 and EXTERNAL_AUTH_SERVICE_URL=http://localhost:8081. Make sure you change the REST API gateway to your new port in the following request examples.  ","version":"Next","tagName":"h3"},{"title":"Running the REST Gateway​","type":1,"pageTitle":"REST Gateway","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/rest-gateway#running-the-rest-gateway","content":" To run the REST Gateway, use the following command:  sam run configs/gateways/my-http-rest.yaml   ","version":"Next","tagName":"h2"},{"title":"Sending a Request via REST API​","type":1,"pageTitle":"REST Gateway","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/rest-gateway#sending-a-request-via-rest-api","content":" You can also interact with Agent Mesh via the REST API.  The REST API gateway runs on http://localhost:8080 by default. You can use either the legacy v1 API or the modern async v2 API.  ","version":"Next","tagName":"h2"},{"title":"Modern API (v2) - Asynchronous​","type":1,"pageTitle":"REST Gateway","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/rest-gateway#modern-api-v2---asynchronous","content":" # Submit task curl --location 'http://localhost:8080/api/v2/tasks' \\ --header 'Authorization: Bearer token' \\ --form 'agent_name="OrchestratorAgent"' \\ --form 'prompt="Hi\\!"' # Poll for result using returned task ID curl --location 'http://localhost:8080/api/v2/tasks/{taskId}' \\ --header 'Authorization: Bearer token'   warning It might take a while for the system to respond. See the observability page for more information about monitoring the system while it processes the request.  Sample output:  From api/v2/tasks  { "taskId":"task-6a0e682f4f6c4927a5997e4fd06eea83" }   From api/v2/tasks/{taskId}  { "id": "task-6a0e682f4f6c4927a5997e4fd06eea83", "sessionId": "rest-session-4df0c24fcecc45fcb69692db9876bc5c", "status": { "state": "completed", "message": { "role": "agent", "parts": [{ "type": "text", "text": "Outdoor Activities in London: Spring Edition. Today's Perfect Activities (13°C, Light Cloud): - Royal Parks Exploration : Hyde Park and Kensington Gardens..." }] }, "timestamp": "2025-07-03T16:54:15.273085" }, "artifacts": [], "metadata": { "agent_name": "OrchestratorAgent" } }   ","version":"Next","tagName":"h3"},{"title":"Legacy API (v1) - Synchronous​","type":1,"pageTitle":"REST Gateway","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/rest-gateway#legacy-api-v1---synchronous","content":" curl --location 'http://localhost:8080/api/v1/invoke' \\ --header 'Authorization: Bearer None' \\ --form 'prompt="Suggest some good outdoor activities in London given the season and current weather conditions."' \\ --form 'agent_name="OrchestratorAgent"' \\ --form 'stream="false"'   Sample output:  { "id": "task-9f7d5f465f5a4f1ca799e8e5ecb35a43", "sessionId": "rest-session-36b36eeb69b04da7b67708f90e5512dc", "status": { "state": "completed", "message": { "role": "agent", "parts": [ { "type": "text", "text": "Outdoor Activities in London: Spring Edition. Today's Perfect Activities (13°C, Light Cloud): - Royal Parks Exploration : Hyde Park and Kensington Gardens..." } ] }, "timestamp": "2025-07-03T16:59:37.486480" }, "artifacts": [], "metadata": { "agent_name": "OrchestratorAgent" } }  ","version":"Next","tagName":"h3"},{"title":"Slack Integration","type":0,"sectionRef":"#","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/slack-integration","content":"","keywords":"","version":"Next"},{"title":"Setting Up the Environment​","type":1,"pageTitle":"Slack Integration","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/slack-integration#setting-up-the-environment","content":" First, you need to install Agent Mesh and the CLI, and then create a new Agent Mesh project or create a new gateway plugin.  ","version":"Next","tagName":"h2"},{"title":"Creating the Slack App​","type":1,"pageTitle":"Slack Integration","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/slack-integration#creating-the-slack-app","content":" Next, create a Slack Application in your workspace.  Go to the Slack Application website.Select Your Apps and click Create New App.Choose From a manifest and apply the following configuration. You can customize the name and description, but keep the rest of the configuration and settings unchanged.  display_information: name: solace-agent-mesh-bot description: An app to integrate with Agent Mesh features: app_home: home_tab_enabled: false messages_tab_enabled: true messages_tab_read_only_enabled: false bot_user: display_name: Agent Mesh always_online: false oauth_config: scopes: bot: - app_mentions:read - bookmarks:read - channels:history - channels:join - channels:manage - channels:read - chat:write - chat:write.customize - chat:write.public - files:read - files:write - groups:history - groups:read - groups:write - im:history - im:read - im:write - links:read - links:write - mpim:history - mpim:read - mpim:write - pins:read - pins:write - reactions:read - reactions:write - reminders:read - reminders:write - team:read - usergroups:read - usergroups:write - users.profile:read - users:read.email - users:read - users:write - conversations.connect:read - conversations.connect:write - incoming-webhook settings: event_subscriptions: bot_events: - app_mention - message.groups - message.im interactivity: is_enabled: true org_deploy_enabled: false socket_mode_enabled: true token_rotation_enabled: false   Then select Create to create your new App.  ","version":"Next","tagName":"h2"},{"title":"App-Level Tokens​","type":1,"pageTitle":"Slack Integration","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/slack-integration#app-level-tokens","content":" In your created App, select Basic Information under Settings. Scroll down to App-Level Tokens and click Generate Token and Scopes.  Provide your token a name, add all available scopes, and then click Generate.  Make note of the resulting application token (beginning with xapp-) - you need it in a future step.  ","version":"Next","tagName":"h3"},{"title":"Installing the App in Your Slack Workspace​","type":1,"pageTitle":"Slack Integration","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/slack-integration#installing-the-app-in-your-slack-workspace","content":" Next, select Install App under Settings and follow the installation flow to install the App in your workspace.  After installation, the bot token (beginning with xoxb-) is visible. Make note of this token.  ","version":"Next","tagName":"h3"},{"title":"Installing the Slack Gateway​","type":1,"pageTitle":"Slack Integration","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/slack-integration#installing-the-slack-gateway","content":" After configuring your Slack App, the next step is to add the Slack gateway to Agent Mesh.  Add the gateway plugin using the Agent Mesh CLI: sam plugin add slack-bot --plugin sam-slack You can change slack-bot to any name you prefer for your gateway. Configure the required environment variables: The Slack interface requires two authentication tokens. Add these to your .env file in the project root directory using the tokens generated during Slack App setup: SLACK_BOT_TOKEN=xoxb-xxxxxxxxxx SLACK_APP_TOKEN=xapp-xxxxxxxxxx   tip You can further customize the Slack gateway by updating the configs/gateways/slack-bot.yaml file. This file contains the configuration for the Slack gateway, including the initial status message, the gateway system purpose, and response format.  ","version":"Next","tagName":"h2"},{"title":"Running the Slack Gateway​","type":1,"pageTitle":"Slack Integration","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/slack-integration#running-the-slack-gateway","content":" Launch the Slack gateway with:  sam run configs/gateways/slack-bot.yaml   For detailed information about available Agent Mesh CLI commands, see Agent Mesh CLI.  ","version":"Next","tagName":"h2"},{"title":"Testing the Installation​","type":1,"pageTitle":"Slack Integration","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/slack-integration#testing-the-installation","content":" To test your installation:  Open your Slack workspace in the desktop app or browser.Find and click on the Agent Mesh app under the Apps section.Send a test message by typing hello and click Enter.You should see: A "Chatbot is thinking..." status messageA response from the chatbot within a few seconds ","version":"Next","tagName":"h2"},{"title":"RAG Integration","type":0,"sectionRef":"#","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/rag-integration","content":"","keywords":"","version":"Next"},{"title":"What is Agent Mesh RAG?​","type":1,"pageTitle":"RAG Integration","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/rag-integration#what-is-agent-mesh-rag","content":" The Agent Mesh RAG plugin enhances your agents with the ability to perform retrieval-augmented generation. This means the agent can:  Scan documents from various sources (local filesystem, Google Drive, etc.).Preprocess and split the text into manageable chunks.Embed these chunks into vectors and store them in a vector database.Retrieve relevant chunks of text based on a user's query.Generate an answer using a large language model (LLM) augmented with the retrieved information.  This allows you to build agents that can answer questions about your own private data.  ","version":"Next","tagName":"h2"},{"title":"Prerequisites​","type":1,"pageTitle":"RAG Integration","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/rag-integration#prerequisites","content":" Before you begin, ensure you have:  Installed Agent Mesh and the Agent Mesh CLI.Created a new Agent Mesh project.Access to a vector database (for example, Qdrant, Chroma, and Pinecone).Access to an LLM for generation and an embedding model.A directory with some documents for the agent to ingest.  ","version":"Next","tagName":"h2"},{"title":"Adding the RAG Plugin​","type":1,"pageTitle":"RAG Integration","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/rag-integration#adding-the-rag-plugin","content":" To add the RAG plugin to your Agent Mesh project, run the following command:  sam plugin add my-rag-agent --plugin sam-rag   Replace my-rag-agent with your preferred agent name. This command:  Installs the sam-rag plugin.Creates a new agent configuration file at configs/agents/my-rag-agent.yaml.  ","version":"Next","tagName":"h2"},{"title":"Configuring the RAG Agent​","type":1,"pageTitle":"RAG Integration","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/rag-integration#configuring-the-rag-agent","content":" The RAG agent requires a detailed configuration. Open configs/agents/my-rag-agent.yaml to configure the following sections:  ","version":"Next","tagName":"h2"},{"title":"Shared Configuration​","type":1,"pageTitle":"RAG Integration","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/rag-integration#shared-configuration","content":" Like other agents, the RAG agent needs a connection to the Solace broker and a configured LLM. This is typically done in a shared_config.yaml file.  # configs/shared_config.yaml shared_config: - broker_connection: &broker_connection dev_mode: ${SOLACE_DEV_MODE, false} broker_url: ${SOLACE_BROKER_URL, ws://localhost:8008} broker_username: ${SOLACE_BROKER_USERNAME, default} broker_password: ${SOLACE_BROKER_PASSWORD, default} broker_vpn: ${SOLACE_BROKER_VPN, default} temporary_queue: ${USE_TEMPORARY_QUEUES, true} - models: general: &general_model model: ${LLM_SERVICE_GENERAL_MODEL_NAME} api_base: ${LLM_SERVICE_ENDPOINT} api_key: ${LLM_SERVICE_API_KEY}   ","version":"Next","tagName":"h3"},{"title":"RAG Pipeline Configuration​","type":1,"pageTitle":"RAG Integration","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/rag-integration#rag-pipeline-configuration","content":" The RAG pipeline has several stages, each with its own configuration block within the app_config section of your my-rag-agent.yaml file.  1. Scanner Configuration​  The scanner discovers documents to be ingested. You can configure it to scan a local filesystem or cloud sources.  Local Filesystem Example:  scanner: batch: true use_memory_storage: true source: type: filesystem directories: - "/path/to/your/documents" # Important: Replace with your actual document directory path filters: file_formats: - ".txt" - ".pdf" - ".md"   Multi-Cloud Source Example:You can also configure multiple sources, including Google Drive, OneDrive, and S3.  scanner: batch: true use_memory_storage: true sources: - type: filesystem directories: ["${LOCAL_DOCUMENTS_PATH}"] - type: google_drive credentials_path: "${GOOGLE_DRIVE_CREDENTIALS_PATH}" folders: - folder_id: "${GOOGLE_DRIVE_FOLDER_ID_1}" name: "Documents" recursive: true   2. Preprocessor Configuration​  The preprocessor cleans the text extracted from documents.  preprocessor: default_preprocessor: type: enhanced params: lowercase: true normalize_whitespace: true remove_urls: true preprocessors: pdf: type: document params: lowercase: true normalize_whitespace: true remove_non_ascii: true remove_urls: true   3. Splitter Configuration​  The splitter breaks down large documents into smaller chunks. Different splitters are available for different file types.  splitter: default_splitter: type: recursive_character params: chunk_size: 2048 chunk_overlap: 400 splitters: markdown: type: markdown params: chunk_size: 2048 chunk_overlap: 400 pdf: type: token params: chunk_size: 500 chunk_overlap: 100   4. Embedding Configuration​  This section defines the model used to create vector embeddings from the text chunks.  embedding: embedder_type: "openai" embedder_params: model: "${OPENAI_EMBEDDING_MODEL}" api_key: "${OPENAI_API_KEY}" api_base: "${OPENAI_API_ENDPOINT}" normalize_embeddings: true   5. Vector Database Configuration​  Configure the connection to your vector database where the embeddings are stored.  Qdrant Example:  vector_db: db_type: "qdrant" db_params: url: "${QDRANT_URL}" api_key: "${QDRANT_API_KEY}" collection_name: "${QDRANT_COLLECTION}" embedding_dimension: ${QDRANT_EMBEDDING_DIMENSION}   Chroma Example:  vector_db: db_type: "chroma" db_params: host: "${CHROMA_HOST}" port: "${CHROMA_PORT}" collection_name: "${CHROMA_COLLECTION}"   6. LLM Configuration​  Configure the LLM that is used to generate answers based on the retrieved context.  llm: load_balancer: - model_name: "gpt-4o" litellm_params: model: "openai/${OPENAI_MODEL_NAME}" api_key: "${OPENAI_API_KEY}" api_base: "${OPENAI_API_ENDPOINT}"   7. Retrieval Configuration​  This defines how many document chunks are retrieved to answer a query.  retrieval: top_k: 7   ","version":"Next","tagName":"h3"},{"title":"Environment Variables​","type":1,"pageTitle":"RAG Integration","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/rag-integration#environment-variables","content":" The RAG agent relies heavily on environment variables. Here are some of the most important ones you'll need to set in your .env file:  # Solace Connection SOLACE_BROKER_URL=ws://localhost:8008 SOLACE_BROKER_VPN=default SOLACE_BROKER_USERNAME=default SOLACE_BROKER_PASSWORD=default NAMESPACE=my-org/dev # LLM and Embedding Models OPENAI_API_KEY="your-openai-api-key" OPENAI_API_ENDPOINT="your-openai-api-endpoint" OPENAI_MODEL_NAME="model name. E.g., gpt-4o" OPENAI_EMBEDDING_MODEL="embedding model name. E.g., text-embedding-3-small" # Vector Database (Qdrant example) QDRANT_URL="Qdrant url" QDRANT_API_KEY="API key" QDRANT_COLLECTION="my-rag-collection" QDRANT_EMBEDDING_DIMENSION=1536 # Depends on your embedding model # Scanner LOCAL_DOCUMENTS_PATH="./my_documents" # Relative path to your documents folder   Create a directory named my_documents in your project root and place some text or markdown files inside it.  ","version":"Next","tagName":"h3"},{"title":"Running the RAG Agent​","type":1,"pageTitle":"RAG Integration","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/rag-integration#running-the-rag-agent","content":" Once you have configured your agent and set the environment variables, you can run it:  sam run configs/agents/my-rag-agent.yaml   When the agent starts, it begins scanning the documents in the configured source, processing and ingesting them into your vector database. This process may take some time, depending on the number and size of your documents.  ","version":"Next","tagName":"h2"},{"title":"Testing the RAG Agent​","type":1,"pageTitle":"RAG Integration","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/rag-integration#testing-the-rag-agent","content":" Once your agent is running, you can test its retrieval capabilities and ingest new documents.  ","version":"Next","tagName":"h2"},{"title":"Ingesting Documents​","type":1,"pageTitle":"RAG Integration","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/rag-integration#ingesting-documents","content":" There are two primary ways to ingest documents into your RAG agent's knowledge base:  Option 1: Automatic Scanning (Batch Ingestion)​  This method uses the configured scanner component. The agent automatically ingests documents from the directories specified in your configuration upon startup.  Step 1: Create a Document  First, create a simple text file named sam_features.txt and add some content to it. For example:  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.   Step 2: Place the Document in the Scanned Directory  In the "Environment Variables" section, we configured LOCAL_DOCUMENTS_PATH to point to a directory (e.g., ./my_documents).  Create this directory in your project's root folder if you haven't already, and move your sam_features.txt file into it.  mkdir -p my_documents mv sam_features.txt my_documents/   Step 3: Run the Agent to Trigger Ingestion  If your agent is already running, you'll need to restart it to trigger the batch scan. If it's not running, start it now:  sam run configs/agents/my-rag-agent.yaml   You will see logs indicating that the file is being processed. Once the agent is running and the initial scan is complete, the document is successfully ingested and ready for retrieval.  Option 2: Manual Upload via Gateway​  You can also ingest documents dynamically by uploading them directly through a gateway, like the Web UI. This is useful for adding single documents without restarting the agent. The RAG agent exposes a tool for this purpose.  Step 1: Start the RAG Agent and Web UI  Ensure both your RAG agent and the Web UI gateway are running.  Step 2: Upload a Document in the Web UI  Open the Web UI (usually at http://localhost:8000, or check your gateway configuration for the correct URL) and start a chat with your RAG agent.Use the file attachment button to select a document from your local machine.Send a prompt along with the file, instructing the agent to ingest it. For example: "Please ingest the attached document into your knowledge base."  The RAG agent uses its built-in ingest_document tool to process the file you uploaded. The file goes through the same preprocessing, splitting, and embedding pipeline as the documents from the automatic scan.  Step 3: Confirm Ingestion  After the agent confirms that the document has been ingested, you can immediately ask questions about its content.  ","version":"Next","tagName":"h3"},{"title":"Querying the Knowledge Base​","type":1,"pageTitle":"RAG Integration","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/rag-integration#querying-the-knowledge-base","content":" You can interact with your RAG agent through any gateway, such as the Web UI gateway.  Make sure you have a Web UI gateway running (or add one to your project).Open the Web UI (usually at http://localhost:8000).Start a conversation with my-rag-agent.Ask a question related to the content of the documents you provided during the initial scan.  For example, if you have a document about product features, you could ask:  "What are the key features of Product X?"  The agent searches its knowledge base, finds the relevant information, and generates an answer based on the content of your documents.  ","version":"Next","tagName":"h3"},{"title":"Troubleshooting​","type":1,"pageTitle":"RAG Integration","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/rag-integration#troubleshooting","content":" Connection Errors: Double-check all your URLs, API keys, and credentials for your LLM and vector database.Ingestion Issues: Check the agent logs for errors during the scanning, preprocessing, or embedding stages. Ensure the file formats are supported and the paths are correct.No Answers: If the agent can't answer, it might be because the information is not in the documents, or the top_k retrieval setting is too low. ","version":"Next","tagName":"h2"},{"title":"Agent Mesh Enterprise","type":0,"sectionRef":"#","url":"/solace-agent-mesh/docs/documentation/enterprise/","content":"","keywords":"","version":"Next"},{"title":"Enterprise Features​","type":1,"pageTitle":"Agent Mesh Enterprise","url":"/solace-agent-mesh/docs/documentation/enterprise/#enterprise-features","content":" The Enterprise version delivers several key capabilities that distinguish it from the Community edition.  Authentication and authorization integrate with your existing identity systems through SSO, eliminating the need for separate credentials while maintaining security standards. You can configure role-based access control to implement granular authorization policies that determine which agents and resources each user can access through the Agent Mesh Gateways.  Data management features help you optimize costs and improve accuracy. Smart filtering capabilities reduce unnecessary compute expenses while precise data governance helps prevent hallucinations by controlling what information reaches your language models.  Observability tools provide complete visibility into your agent ecosystem. The built-in workflow viewer tracks LLM interactions and agent communications in real time, giving you the insights needed to monitor performance, diagnose issues, and understand system behavior.  ","version":"Next","tagName":"h2"},{"title":"Getting Started with Enterprise​","type":1,"pageTitle":"Agent Mesh Enterprise","url":"/solace-agent-mesh/docs/documentation/enterprise/#getting-started-with-enterprise","content":" Setting up Agent Mesh Enterprise involves three main areas: installation, security configuration, and authentication setup.  ","version":"Next","tagName":"h2"},{"title":"Installation​","type":1,"pageTitle":"Agent Mesh Enterprise","url":"/solace-agent-mesh/docs/documentation/enterprise/#installation","content":" The Docker-based installation process downloads the enterprise image from the Solace Product Portal, loads it into your container environment, and launches it with the appropriate configuration for your deployment scenario. You can run Enterprise in development mode with an embedded broker for testing, or connect it to an external Solace broker for production deployments. For complete installation instructions, see Installing Agent Mesh Enterprise.  ","version":"Next","tagName":"h3"},{"title":"Access Control​","type":1,"pageTitle":"Agent Mesh Enterprise","url":"/solace-agent-mesh/docs/documentation/enterprise/#access-control","content":" Role-based access control lets you define who can access which agents and features in your deployment. You create roles that represent job functions, assign permissions to those roles through scopes, and then assign roles to users. This three-tier model implements the principle of least privilege while simplifying administration. For guidance on planning and implementing RBAC, see Setting Up RBAC.  ","version":"Next","tagName":"h3"},{"title":"Single Sign-On​","type":1,"pageTitle":"Agent Mesh Enterprise","url":"/solace-agent-mesh/docs/documentation/enterprise/#single-sign-on","content":" SSO integration connects Agent Mesh Enterprise with your organization's identity provider, whether you use Azure, Google, Auth0, Okta, Keycloak, or another OAuth2-compliant system. The configuration process involves creating YAML files that define the authentication service and provider settings, then launching the container with the appropriate environment variables. For step-by-step configuration instructions, see Enabling SSO.  ","version":"Next","tagName":"h3"},{"title":"What's Next​","type":1,"pageTitle":"Agent Mesh Enterprise","url":"/solace-agent-mesh/docs/documentation/enterprise/#whats-next","content":" After you complete the initial setup, you can begin developing agents and gateways using the same patterns and tools available in the Community edition. The Enterprise features operate transparently—your agents and tools work the same way, but with the added security, governance, and observability that production environments demand. ","version":"Next","tagName":"h2"},{"title":"SQL Database Integration","type":0,"sectionRef":"#","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/sql-database","content":"","keywords":"","version":"Next"},{"title":"Prerequisites​","type":1,"pageTitle":"SQL Database Integration","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/sql-database#prerequisites","content":" Before starting this tutorial, ensure that you have installed and configured Agent Mesh:  Installed Agent Mesh and the Agent Mesh CLICreated a new Agent Mesh projectAccess to a SQL database (local or remote)  ","version":"Next","tagName":"h2"},{"title":"Adding the SQL Database Plugin​","type":1,"pageTitle":"SQL Database Integration","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/sql-database#adding-the-sql-database-plugin","content":" Add the SQL Database plugin to your Agent Mesh project:  sam plugin add abc-coffee-info --plugin sam-sql-database   You can use any name for your agent, in this tutorial we use abc-coffee-info.  This command:  Installs the sam-sql-database pluginCreates a new agent configuration file at configs/agents/abc-coffee-info.yaml  ","version":"Next","tagName":"h2"},{"title":"Downloading Example Data​","type":1,"pageTitle":"SQL Database Integration","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/sql-database#downloading-example-data","content":" For this tutorial, you can use a sample SQLite database for a fictional coffee company called ABC Coffee Co.  First, download the example data.  You can either visit this link to download with your browser:  https://github.com/SolaceLabs/solace-agent-mesh-core-plugins/raw/refs/heads/main/sam-sql-database/example-data/abc_coffee_co.zip  Or you can use the command line to download the ZIP file:  Using wget​  wget https://github.com/SolaceLabs/solace-agent-mesh-core-plugins/raw/refs/heads/main/sam-sql-database/example-data/abc_coffee_co.zip   Using curl​  curl -LO https://github.com/SolaceLabs/solace-agent-mesh-core-plugins/raw/refs/heads/main/sam-sql-database/example-data/abc_coffee_co.zip   After downloading the ZIP file, extract it to a directory of your choice. You can use the following command to extract the ZIP file:  unzip abc_coffee_co.zip   ","version":"Next","tagName":"h2"},{"title":"Configuring the Agent​","type":1,"pageTitle":"SQL Database Integration","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/sql-database#configuring-the-agent","content":" Now, update the agent configuration to use the SQLite database and import the CSV files. Open the configs/agents/abc-coffee-info.yaml file and modify the agent_init_function.config section to specify the CSV directory.  Here is what you need to modify in the configuration file:  # Find the agent_init_function section and update the config: agent_init_function: module: "sam_sql_database.lifecycle" name: "initialize_sql_agent" config: db_type: "${ABC_COFFEE_INFO_DB_TYPE}" db_name: "${ABC_COFFEE_INFO_DB_NAME}" database_purpose: "${ABC_COFFEE_INFO_DB_PURPOSE}" data_description: "${ABC_COFFEE_INFO_DB_DESCRIPTION}" # Add the CSV directory path csv_directories: - /path/to/your/unzipped/data   Ensure you replace /path/to/your/unzipped/data with the path where you extracted the example data. For example, if you put the ZIP file in the root directory of your Agent Mesh project, you can use abc_coffee_co.  ","version":"Next","tagName":"h2"},{"title":"Setting the Environment Variables​","type":1,"pageTitle":"SQL Database Integration","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/sql-database#setting-the-environment-variables","content":" The SQL Database agent requires that you configure several environment variables. You must create or update your .env file with the following variables for this tutorial:  ABC_COFFEE_INFO_DB_TYPE=sqlite ABC_COFFEE_INFO_DB_NAME=abc_coffee.db ABC_COFFEE_INFO_DB_PURPOSE="ABC Coffee Co. sales and operations database" ABC_COFFEE_INFO_DB_DESCRIPTION="Contains information about ABC Coffee Co. products, sales, customers, employees, and store locations." # You can leave other environment variables as unset or empty   SQLite stores the database in a local file and doesn't require a username or password for access. If you're using a database such as MySQL or PostgreSQL, you'll need to provide the appropriate environment variables for them.  ","version":"Next","tagName":"h2"},{"title":"Running the Agent​","type":1,"pageTitle":"SQL Database Integration","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/sql-database#running-the-agent","content":" Now, you can start your SQL database agent:  sam run configs/agents/abc-coffee-info.yaml   The agent:  Connects to the A2A control planeInitializes the SQLite database and imports CSV data from the specified directoryDetects the database schema automaticallyRegisters its capabilities with the agent discovery system  ","version":"Next","tagName":"h2"},{"title":"Interacting with the Database​","type":1,"pageTitle":"SQL Database Integration","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/sql-database#interacting-with-the-database","content":" After your SQL database agent is running, you can interact with the ABC Coffee database through any gateway in your Agent Mesh project (such as the Web UI gateway at http://localhost:8000).  You can ask natural language questions about the ABC Coffee Co. database, such as:  "How many customers does ABC Coffee have?""What are the top-selling products?""Show me the sales by region""List all orders from the last 30 days""What products are currently low in inventory?"  Try creating reports by asking questions such as:  "Create a report of our sales in 2024""Generate a summary of customer demographics"  The SQL Database agent converts your natural language questions into SQL queries, executes them against the database, and returns the results. For large result sets, the agent automatically saves the results as artifacts that you can download.  ","version":"Next","tagName":"h2"},{"title":"Advanced Configuration​","type":1,"pageTitle":"SQL Database Integration","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/sql-database#advanced-configuration","content":" The SQL Database plugin supports many advanced configuration options. Here is a complete example based on the plugin structure:  log: stdout_log_level: INFO log_file_level: DEBUG log_file: abc-coffee-info.log !include ../shared_config.yaml apps: - name: abc-coffee-info-app app_module: solace_agent_mesh.agent.sac.app broker: <<: *broker_connection app_config: namespace: ${NAMESPACE} agent_name: "AbcCoffeeInfo" display_name: "ABC Coffee Database Agent" supports_streaming: false model: *general_model instruction: | You are an expert SQL assistant for the ABC Coffee Co. database. The database schema and query examples are 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. # Agent initialization with database setup agent_init_function: module: "sam_sql_database.lifecycle" name: "initialize_sql_agent" config: db_type: "${ABC_COFFEE_INFO_DB_TYPE}" db_name: "${ABC_COFFEE_INFO_DB_NAME}" database_purpose: "${ABC_COFFEE_INFO_DB_PURPOSE}" data_description: "${ABC_COFFEE_INFO_DB_DESCRIPTION}" auto_detect_schema: true csv_directories: - "abc_coffee_co" # Path to your extracted data query_examples: - natural_language: "Show all customers from New York" sql_query: "SELECT * FROM customers WHERE city = 'New York';" - natural_language: "What are the top 5 best-selling products?" sql_query: "SELECT product_name, SUM(quantity) as total_sold FROM order_items JOIN products ON order_items.product_id = products.id GROUP BY product_name ORDER BY total_sold DESC LIMIT 5;" agent_cleanup_function: module: "sam_sql_database.lifecycle" name: "cleanup_sql_agent_resources" # SQL query tool tools: - tool_type: python component_module: "sam_sql_database.tools" function_name: "execute_sql_query" session_service: *default_session_service artifact_service: *default_artifact_service # Agent capabilities - This is what other agents see during discovery agent_card: description: "ABC Coffee Co. Database Agent - Access to comprehensive coffee shop data including customers, orders, products, inventory, and sales history. Can answer questions about business metrics, customer analytics, product performance, and operational data." defaultInputModes: ["text"] defaultOutputModes: ["text", "file"] skills: - id: "sql_query" name: "Coffee Shop Database Query" description: "Queries ABC Coffee Co. database containing customer orders, product catalog, inventory levels, sales history, and employee data." # A2A Protocol settings agent_card_publishing: { interval_seconds: 30 } agent_discovery: { enabled: true } inter_agent_communication: allow_list: ["*"] request_timeout_seconds: 60   ","version":"Next","tagName":"h2"},{"title":"Customizing the Agent Card​","type":1,"pageTitle":"SQL Database Integration","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/sql-database#customizing-the-agent-card","content":" The agent_card section is crucial as it defines how other agents in your Agent Mesh ecosystem discover and understand this database agent's capabilities. When other agents use agent discovery, they can see this information to decide whether to delegate tasks to your database agent.  ","version":"Next","tagName":"h2"},{"title":"Key Agent Card Elements​","type":1,"pageTitle":"SQL Database Integration","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/sql-database#key-agent-card-elements","content":" Description: Clearly describe what data the agent has access to and what types of questions it can answerSkills: List specific capabilities with concrete examples that show the scope of data availableData Context: Mention the business domain, data types, and scope of information available  ","version":"Next","tagName":"h3"},{"title":"Example of a Well-Configured Agent Card​","type":1,"pageTitle":"SQL Database Integration","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/sql-database#example-of-a-well-configured-agent-card","content":" agent_card: description: "ABC Coffee Co. Database Agent - Access to comprehensive coffee shop data including customers, orders, products, inventory, and sales history. Can answer questions about business metrics, customer analytics, product performance, and operational data." defaultInputModes: ["text"] defaultOutputModes: ["text", "file"] skills: - id: "sql_query" name: "Coffee Shop Database Query" description: "Queries ABC Coffee Co. database containing customer orders, product catalog, inventory levels, sales history, and employee data."   This detailed information helps other agents understand:  What business domain this agent covers (coffee shop operations)What types of data are available (customers, orders, products, inventory, sales)What kinds of questions can be answered (metrics, analytics, performance data)Specific examples of queries that work well  When configuring your own database agent, customize the description and examples to match your specific data and use cases. ","version":"Next","tagName":"h3"},{"title":"Create Gateways","type":0,"sectionRef":"#","url":"/solace-agent-mesh/docs/documentation/developing/create-gateways","content":"","keywords":"","version":"Next"},{"title":"What Are Gateways?​","type":1,"pageTitle":"Create Gateways","url":"/solace-agent-mesh/docs/documentation/developing/create-gateways#what-are-gateways","content":" A gateway acts as a translator and coordinator that:  Receives events, messages, or data from external systemsAuthenticates and authorizes external interactionsTranslates external data into standardized A2A Task formatSubmits tasks to target A2A agents for processingReceives responses and status updates from agentsTranslates A2A responses back to external system formatSends results back to the originating external system  ","version":"Next","tagName":"h2"},{"title":"Quick Start: Creating Your First Gateway​","type":1,"pageTitle":"Create Gateways","url":"/solace-agent-mesh/docs/documentation/developing/create-gateways#quick-start-creating-your-first-gateway","content":" You can create a gateway directly using the Agent Mesh CLI sam add gateway:  sam add gateway my-custom-gateway   This command:  Launches an interactive setup (or use --gui for browser-based configuration)Generates the necessary files and configurationSets up the basic gateway structure  ","version":"Next","tagName":"h2"},{"title":"CLI Options​","type":1,"pageTitle":"Create Gateways","url":"/solace-agent-mesh/docs/documentation/developing/create-gateways#cli-options","content":" You can customize the gateway creation with these options:  sam add gateway my-gateway \\ --namespace "myorg/dev" \\ --gateway-id "my-custom-gw-id" \\ --artifact-service-type "filesystem" \\ --artifact-service-base-path "var/data/my-gateway-artifacts" \\ --system-purpose "This gateway processes external data feeds" \\ --response-format "Agents should respond with structured JSON"   For a complete list of options, run:  sam add gateway --help   ","version":"Next","tagName":"h3"},{"title":"Gateway Architecture​","type":1,"pageTitle":"Create Gateways","url":"/solace-agent-mesh/docs/documentation/developing/create-gateways#gateway-architecture","content":" Every Agent Mesh gateway consists of two main components:  ","version":"Next","tagName":"h2"},{"title":"Gateway App​","type":1,"pageTitle":"Create Gateways","url":"/solace-agent-mesh/docs/documentation/developing/create-gateways#gateway-app","content":" Gateway App (app.py):  Defines configuration schemaManages gateway-level settingsLinks to the gateway component  ","version":"Next","tagName":"h3"},{"title":"Gateway Component​","type":1,"pageTitle":"Create Gateways","url":"/solace-agent-mesh/docs/documentation/developing/create-gateways#gateway-component","content":" Gateway Component (component.py):  Contains the core business logicHandles external system integrationImplements required abstract methods  ","version":"Next","tagName":"h3"},{"title":"Step-by-Step Tutorial​","type":1,"pageTitle":"Create Gateways","url":"/solace-agent-mesh/docs/documentation/developing/create-gateways#step-by-step-tutorial","content":" Let's create a practical example, Directory Monitor Gateway, a gateway that monitors a directory for new files and sends them to agents for processing.  You can create a gateway using either sam add gateway <your_gateway_name> command directly or sam plugin create <your_gateway_plugin_name> --type gateway command as gateway plugin.  Gateway as plugin Gateways can also be implemented as plugins. This allows you to easily package your gateway logic and reuse it across different projects. To create a plugin of type gateway, use the sam plugin create <your_gateway_plugin_name> --type gateway command. For a complete list of options, run: sam plugin create --help To create a gateway instance based on a plugin, use the sam plugin add <your_gateway_name> --plugin <your_gateway_plugin> command. For a complete list of options, run: sam plugin add --help Although the specific directory structure may differ from standalone gateways, the core concepts remain the same. The core files remain the same: app.py, component.py, and the YAML configuration file.  ","version":"Next","tagName":"h2"},{"title":"Step 1: Generate the Gateway Structure​","type":1,"pageTitle":"Create Gateways","url":"/solace-agent-mesh/docs/documentation/developing/create-gateways#step-1-generate-the-gateway-structure","content":" This tutorial shows you how to create a new gateway with the sam add gateway command.  sam add gateway dir-monitor   This creates:  configs/gateways/dir_monitor_config.yaml - Configuration filesrc/dir_monitor/app.py - Gateway app classsrc/dir_monitor/component.py - Gateway component class  ","version":"Next","tagName":"h3"},{"title":"Step 2: Define Configuration Schema​","type":1,"pageTitle":"Create Gateways","url":"/solace-agent-mesh/docs/documentation/developing/create-gateways#step-2-define-configuration-schema","content":" Define Configuration Schema (app.py)  # src/dir_monitor/app.py from typing import Any, Dict, List, Type from solace_ai_connector.common.log import log from solace_agent_mesh.gateway.base.app import BaseGatewayApp from solace_agent_mesh.gateway.base.component import BaseGatewayComponent from .component import DirMonitorGatewayComponent # Module info required by SAC info = { "class_name": "DirMonitorGatewayApp", "description": "Custom App class for the A2A DirMonitor Gateway.", } class DirMonitorGatewayApp(BaseGatewayApp): """ Directory Monitor Gateway App Extends BaseGatewayApp with directory monitoring specific configuration. """ # Define gateway-specific configuration parameters SPECIFIC_APP_SCHEMA_PARAMS: List[Dict[str, Any]] = [ { "name": "directory_path", "required": True, "type": "string", "description": "The directory path to monitor for changes.", }, { "name": "target_agent_name", "required": False, "type": "string", "default": "OrchestratorAgent", "description": "The A2A agent to send tasks to.", }, { "name": "default_user_identity", "required": False, "type": "string", "default": "dir_monitor_user", "description": "Default user identity for A2A tasks.", }, { "name": "error_directory_path", "required": True, "type": "string", "description": "Directory to move files if processing fails.", }, ] def __init__(self, app_info: Dict[str, Any], **kwargs): log_prefix = app_info.get("name", "DirMonitorGatewayApp") log.info("[%s] Initializing Directory Monitor Gateway App...", log_prefix) super().__init__(app_info=app_info, **kwargs) log.info("[%s] Directory Monitor Gateway App initialized.", self.name) def _get_gateway_component_class(self) -> Type[BaseGatewayComponent]: """Returns the gateway component class for this app.""" return DirMonitorGatewayComponent   ","version":"Next","tagName":"h3"},{"title":"Step 3: Implement Core Logic​","type":1,"pageTitle":"Create Gateways","url":"/solace-agent-mesh/docs/documentation/developing/create-gateways#step-3-implement-core-logic","content":" Implement Core Logic (component.py)  # src/dir_monitor/component.py import asyncio import os import shutil import mimetypes import threading from typing import Any, Dict, List, Optional, Tuple, Union from datetime import datetime, timezone from solace_ai_connector.common.log import log # Import watchdog for file system monitoring try: from watchdog.observers import Observer from watchdog.events import FileSystemEventHandler WATCHDOG_AVAILABLE = True except ImportError: WATCHDOG_AVAILABLE = False Observer = None FileSystemEventHandler = None from solace_agent_mesh.gateway.base.component import BaseGatewayComponent from solace_agent_mesh.common.types import ( Part as A2APart, TextPart, FilePart, Task, TaskStatusUpdateEvent, TaskArtifactUpdateEvent, JSONRPCError, FileContent, ) from solace_agent_mesh.agent.utils.artifact_helpers import save_artifact_with_metadata # Component info info = { "class_name": "DirMonitorGatewayComponent", "description": "Monitors directories for new files and processes them via A2A agents.", } class DirMonitorGatewayComponent(BaseGatewayComponent): """ Directory Monitor Gateway Component Watches a directory and creates A2A tasks for new files. """ def __init__(self, **kwargs: Any): super().__init__(**kwargs) log.info("%s Initializing Directory Monitor Gateway Component...", self.log_identifier) # Check if watchdog is available if not WATCHDOG_AVAILABLE: log.error("%s Watchdog library not found. Install with: pip install watchdog", self.log_identifier) raise ImportError("Watchdog library required for directory monitoring") # Load configuration try: self.directory_path = self.get_config("directory_path") self.target_agent_name = self.get_config("target_agent_name", "OrchestratorAgent") self.default_user_identity_id = self.get_config("default_user_identity", "dir_monitor_user") self.error_directory_path = self.get_config("error_directory_path") # Validate directories if not os.path.isdir(self.directory_path): raise ValueError(f"Monitor directory not found: {self.directory_path}") os.makedirs(self.error_directory_path, exist_ok=True) log.info("%s Monitoring: %s, Error dir: %s", self.log_identifier, self.directory_path, self.error_directory_path) except Exception as e: log.error("%s Configuration error: %s", self.log_identifier, e) raise # Initialize monitoring components self.observer: Optional[Observer] = None self.watchdog_thread: Optional[threading.Thread] = None log.info("%s Directory Monitor Gateway Component initialized.", self.log_identifier) class DirWatchEventHandler(FileSystemEventHandler): """Handles file system events from Watchdog.""" def __init__(self, component_ref: 'DirMonitorGatewayComponent'): super().__init__() self.component_ref = component_ref self.log_identifier = f"{component_ref.log_identifier}[FileHandler]" def on_created(self, event): if event.is_directory: return file_path = event.src_path log.info("%s New file detected: %s", self.log_identifier, file_path) # Bridge to async loop if self.component_ref.async_loop and self.component_ref.async_loop.is_running(): asyncio.run_coroutine_threadsafe( self.component_ref._process_new_file(file_path), self.component_ref.async_loop ) else: log.error("%s Async loop not available for file: %s", self.log_identifier, file_path) def generate_uuid(self) -> str: """Generate a unique identifier.""" import uuid return str(uuid.uuid4()) def _start_listener(self) -> None: """Start the directory monitoring listener.""" log_id_prefix = f"{self.log_identifier}[StartListener]" log.info("%s Starting directory monitor for: %s", log_id_prefix, self.directory_path) if not WATCHDOG_AVAILABLE: log.error("%s Watchdog not available", log_id_prefix) self.stop_signal.set() return # Set up file system observer self.observer = Observer() event_handler = self.DirWatchEventHandler(self) self.observer.schedule(event_handler, self.directory_path, recursive=False) # Start observer in separate thread self.watchdog_thread = threading.Thread( target=self._run_observer, name=f"{self.name}_WatchdogThread", daemon=True ) self.watchdog_thread.start() log.info("%s Directory monitor started", log_id_prefix) def _run_observer(self): """Run the watchdog observer.""" if not self.observer: return log_id_prefix = f"{self.log_identifier}[Observer]" try: log.info("%s Starting file system observer...", log_id_prefix) self.observer.start() # Wait for stop signal while not self.stop_signal.is_set() and self.observer.is_alive(): self.stop_signal.wait(timeout=1) log.info("%s Observer loop exiting", log_id_prefix) except Exception as e: log.exception("%s Observer error: %s", log_id_prefix, e) self.stop_signal.set() finally: if self.observer.is_alive(): self.observer.stop() self.observer.join() log.info("%s Observer stopped", log_id_prefix) def _stop_listener(self) -> None: """Stop the directory monitoring listener.""" log_id_prefix = f"{self.log_identifier}[StopListener]" log.info("%s Stopping directory monitor...", log_id_prefix) if self.observer and self.observer.is_alive(): log.info("%s Stopping observer...", log_id_prefix) self.observer.stop() if self.watchdog_thread and self.watchdog_thread.is_alive(): log.info("%s Joining observer thread...", log_id_prefix) self.watchdog_thread.join(timeout=5) if self.watchdog_thread.is_alive(): log.warning("%s Observer thread did not join cleanly", log_id_prefix) log.info("%s Directory monitor stopped", log_id_prefix) async def _process_new_file(self, file_path: str): """Process a newly detected file.""" log_id_prefix = f"{self.log_identifier}[ProcessFile:{os.path.basename(file_path)}]" log.info("%s Processing new file: %s", log_id_prefix, file_path) error_context = { "file_path": file_path, "a2a_session_id": f"dir_monitor-error-{self.generate_uuid()}" } try: # Step 1: Authenticate and enrich user user_identity_profile = await self.authenticate_and_enrich_user(file_path) if not user_identity_profile: log.error("%s Authentication failed for file: %s", log_id_prefix, file_path) error_obj = JSONRPCError(code=-32001, message="Authentication failed") await self._send_error_to_external(error_context, error_obj) return # Step 2: Translate external input to A2A format target_agent_name, a2a_parts, external_request_context = await self._translate_external_input( file_path, user_identity_profile ) if not target_agent_name or not a2a_parts: log.error("%s Failed to translate file to A2A task: %s", log_id_prefix, file_path) error_obj = JSONRPCError(code=-32002, message="Failed to translate file to A2A task") final_error_context = {**error_context, **external_request_context} await self._send_error_to_external(final_error_context, error_obj) return # Step 3: Submit A2A task log.info("%s Submitting A2A task for file: %s to agent: %s", log_id_prefix, file_path, target_agent_name) await self.submit_a2a_task( target_agent_name=target_agent_name, a2a_parts=a2a_parts, external_request_context=external_request_context, user_identity=user_identity_profile ) log.info("%s A2A task submitted for file: %s", log_id_prefix, file_path) except FileNotFoundError: log.error("%s File not found during processing: %s", log_id_prefix, file_path) except Exception as e: log.exception("%s Unexpected error processing file %s: %s", log_id_prefix, file_path, e) error_obj = JSONRPCError(code=-32000, message=f"Unexpected error: {e}") await self._send_error_to_external(error_context, error_obj) async def _extract_initial_claims(self, external_event_data: Any) -> Optional[Dict[str, Any]]: """Extract user identity claims from file event.""" file_path = str(external_event_data) log_id_prefix = f"{self.log_identifier}[ExtractClaims:{os.path.basename(file_path)}]" claims = { "id": self.default_user_identity_id, "source": "dir_monitor", "file_path": file_path } log.debug("%s Extracted claims for file %s: %s", log_id_prefix, file_path, claims) return claims async def _translate_external_input( self, external_event_data: Any, authenticated_user_identity: Dict[str, Any] ) -> Tuple[Optional[str], List[A2APart], Dict[str, Any]]: """Translate file event to A2A task format.""" file_path = str(external_event_data) log_id_prefix = f"{self.log_identifier}[TranslateInput:{os.path.basename(file_path)}]" user_id_for_a2a = authenticated_user_identity.get("id", self.default_user_identity_id) a2a_session_id = f"dir_monitor-session-{self.generate_uuid()}" # Prepare external request context external_request_context: Dict[str, Any] = { "file_path": file_path, "user_id_for_a2a": user_id_for_a2a, "app_name_for_artifacts": self.gateway_id, "user_id_for_artifacts": user_id_for_a2a, "a2a_session_id": a2a_session_id, } a2a_parts: List[A2APart] = [] try: # Check if file exists if not os.path.exists(file_path): log.error("%s File does not exist: %s", log_id_prefix, file_path) raise FileNotFoundError(f"File not found: {file_path}") # Read file content with open(file_path, "rb") as f: content_bytes = f.read() # Determine MIME type mime_type, _ = mimetypes.guess_type(file_path) if mime_type is None: mime_type = "application/octet-stream" # Save file as artifact if not self.shared_artifact_service: log.error("%s Artifact service not available for file: %s", log_id_prefix, os.path.basename(file_path)) return None, [], external_request_context artifact_metadata = { "source": "dir_monitor_gateway", "original_filename": os.path.basename(file_path), "detected_mime_type": mime_type, "processing_timestamp_utc": datetime.now(timezone.utc).isoformat(), } log.debug("%s Saving artifact for file: %s", log_id_prefix, file_path) save_result = await save_artifact_with_metadata( artifact_service=self.shared_artifact_service, app_name=self.gateway_id, user_id=str(user_id_for_a2a), session_id=a2a_session_id, filename=os.path.basename(file_path), content_bytes=content_bytes, mime_type=mime_type, metadata_dict=artifact_metadata, timestamp=datetime.now(timezone.utc), ) if save_result["status"] not in ["success", "partial_success"]: log.error("%s Failed to save file as artifact: %s", log_id_prefix, save_result.get("message")) return None, [], external_request_context # Create artifact URI data_version = save_result.get("data_version", 0) artifact_uri = f"artifact://{self.gateway_id}/{str(user_id_for_a2a)}/{a2a_session_id}/{os.path.basename(file_path)}?version={data_version}" log.info("%s Saved file as artifact: %s", log_id_prefix, artifact_uri) # Create A2A parts file_content_obj = FileContent( name=os.path.basename(file_path), uri=artifact_uri, mimeType=mime_type ) a2a_parts.append(FilePart(file=file_content_obj)) a2a_parts.append(TextPart( text=f"Please analyze and summarize the content of: {os.path.basename(file_path)}" )) log.info("%s Successfully translated file %s into A2A parts", log_id_prefix, file_path) return self.target_agent_name, a2a_parts, external_request_context except Exception as e: log.exception("%s Error translating file %s: %s", log_id_prefix, file_path, e) return None, [], external_request_context async def _send_final_response_to_external( self, external_request_context: Dict[str, Any], task_data: Task ) -> None: """Handle final response from A2A agent.""" log_id_prefix = f"{self.log_identifier}[SendFinalResponse]" file_path = external_request_context.get("file_path", "Unknown file") task_id = task_data.id # Extract summary from response summary_text = "Summary not available." if task_data.status and task_data.status.message and task_data.status.message.parts: for part in task_data.status.message.parts: if isinstance(part, TextPart): summary_text = part.text break log.info("%s Task %s completed for file '%s'. Status: %s", log_id_prefix, task_id, os.path.basename(file_path), task_data.status.state if task_data.status else "Unknown") log.info("%s Summary: %s", log_id_prefix, summary_text[:200] + "..." if len(summary_text) > 200 else summary_text) async def _send_error_to_external( self, external_request_context: Dict[str, Any], error_data: JSONRPCError ) -> None: """Handle errors by moving files to error directory.""" log_id_prefix = f"{self.log_identifier}[SendError]" file_path = external_request_context.get("file_path") log.error("%s A2A Error for file '%s'. Code: %s, Message: %s", log_id_prefix, os.path.basename(file_path) if file_path else "Unknown file", error_data.code, error_data.message) # Move problematic file to error directory if file_path and os.path.exists(file_path): try: os.makedirs(self.error_directory_path, exist_ok=True) base_name = os.path.basename(file_path) error_file_path = os.path.join(self.error_directory_path, base_name) # Handle filename conflicts counter = 0 while os.path.exists(error_file_path): counter += 1 name, ext = os.path.splitext(base_name) error_file_path = os.path.join(self.error_directory_path, f"{name}_error_{counter}{ext}") shutil.move(file_path, error_file_path) log.info("%s Moved problematic file %s to %s", log_id_prefix, file_path, error_file_path) except Exception as e: log.exception("%s Failed to move file %s to error directory: %s", log_id_prefix, file_path, e) async def _send_update_to_external( self, external_request_context: Dict[str, Any], event_data: Union[TaskStatusUpdateEvent, TaskArtifactUpdateEvent], is_final_chunk_of_update: bool, ) -> None: """Handle intermediate updates (optional for this gateway).""" log_id_prefix = f"{self.log_identifier}[SendUpdate]" task_id = event_data.id file_path = external_request_context.get("file_path", "Unknown file") log.debug("%s Received update for task %s (file %s). Updates not processed by this gateway.", log_id_prefix, task_id, os.path.basename(file_path)) def cleanup(self): """Clean up resources.""" log.info("%s Cleaning up Directory Monitor Gateway Component...", self.log_identifier) super().cleanup() log.info("%s Directory Monitor Gateway Component cleanup finished.", self.log_identifier)   ","version":"Next","tagName":"h3"},{"title":"Step 4: Configure the Gateway​","type":1,"pageTitle":"Create Gateways","url":"/solace-agent-mesh/docs/documentation/developing/create-gateways#step-4-configure-the-gateway","content":" Configure the Gateway (dir_monitor_config.yaml)  # configs/gateways/dir_monitor_config.yaml log: stdout_log_level: INFO log_file_level: DEBUG log_file: "dir_monitor_gateway.log" !include ../shared_config.yaml apps: - name: dir_monitor_gateway_app app_base_path: . app_module: src.dir_monitor.app broker: <<: *broker_connection app_config: namespace: ${NAMESPACE} gateway_id: dir-monitor-gateway # Artifact service configuration artifact_service: *default_artifact_service # System purpose for A2A context system_purpose: > This system monitors directories for new files and processes them automatically. Analyze and summarize file contents. Always provide useful insights about the files. Your external name is Directory Monitor Agent. response_format: > Responses should be clear, concise, and professionally formatted. Provide structured analysis of file contents in Markdown format. # Gateway-specific configuration directory_path: /path/to/monitor/directory error_directory_path: /path/to/error/directory target_agent_name: "OrchestratorAgent" default_user_identity: "dir_monitor_system"   ","version":"Next","tagName":"h3"},{"title":"Step 5: Install Dependencies​","type":1,"pageTitle":"Create Gateways","url":"/solace-agent-mesh/docs/documentation/developing/create-gateways#step-5-install-dependencies","content":" Add required dependencies to your project:  pip install watchdog   ","version":"Next","tagName":"h3"},{"title":"Step 6: Run Your Gateway​","type":1,"pageTitle":"Create Gateways","url":"/solace-agent-mesh/docs/documentation/developing/create-gateways#step-6-run-your-gateway","content":" sam run configs/gateways/dir_monitor_config.yaml   ","version":"Next","tagName":"h3"},{"title":"Advanced Gateway Patterns​","type":1,"pageTitle":"Create Gateways","url":"/solace-agent-mesh/docs/documentation/developing/create-gateways#advanced-gateway-patterns","content":" ","version":"Next","tagName":"h2"},{"title":"Authentication and Authorization​","type":1,"pageTitle":"Create Gateways","url":"/solace-agent-mesh/docs/documentation/developing/create-gateways#authentication-and-authorization","content":" Gateways can implement sophisticated authentication:  async def _extract_initial_claims(self, external_event_data: Any) -> Optional[Dict[str, Any]]: """Extract user claims with API key validation.""" request = external_event_data.get("request") # Validate API key api_key = request.headers.get("X-API-Key") if not api_key or not self._validate_api_key(api_key): return None # Extract user information user_id = request.headers.get("X-User-ID", "anonymous") return { "id": user_id, "source": "api_gateway", "api_key_hash": hashlib.sha256(api_key.encode()).hexdigest()[:8], "roles": self._get_user_roles(user_id) }   ","version":"Next","tagName":"h3"},{"title":"File Handling with Artifacts​","type":1,"pageTitle":"Create Gateways","url":"/solace-agent-mesh/docs/documentation/developing/create-gateways#file-handling-with-artifacts","content":" For gateways that handle files:  async def _save_file_as_artifact(self, file_content: bytes, filename: str, mime_type: str, session_id: str) -> Optional[str]: """Save file content as artifact and return URI.""" if not self.shared_artifact_service: return None try: save_result = await save_artifact_with_metadata( artifact_service=self.shared_artifact_service, app_name=self.gateway_id, user_id="system", session_id=session_id, filename=filename, content_bytes=file_content, mime_type=mime_type, metadata_dict={ "source": "my_gateway", "upload_timestamp": datetime.now(timezone.utc).isoformat() }, timestamp=datetime.now(timezone.utc) ) if save_result["status"] in ["success", "partial_success"]: version = save_result.get("data_version", 0) return f"artifact://{self.gateway_id}/system/{session_id}/{filename}?version={version}" except Exception as e: log.error("Failed to save artifact: %s", e) return None   ","version":"Next","tagName":"h3"},{"title":"Streaming Responses​","type":1,"pageTitle":"Create Gateways","url":"/solace-agent-mesh/docs/documentation/developing/create-gateways#streaming-responses","content":" Handle streaming responses from agents:  async def _send_update_to_external( self, external_request_context: Dict[str, Any], event_data: Union[TaskStatusUpdateEvent, TaskArtifactUpdateEvent], is_final_chunk_of_update: bool ) -> None: """Send streaming updates to external system.""" if isinstance(event_data, TaskStatusUpdateEvent): if event_data.status and event_data.status.message: for part in event_data.status.message.parts: if isinstance(part, TextPart): # Send partial text to external system await self._send_partial_response( external_request_context, part.text, is_final=is_final_chunk_of_update )   ","version":"Next","tagName":"h3"},{"title":"Error Handling and Retry Logic​","type":1,"pageTitle":"Create Gateways","url":"/solace-agent-mesh/docs/documentation/developing/create-gateways#error-handling-and-retry-logic","content":" Implement robust error handling:  async def _process_with_retry(self, data: Any, max_retries: int = 3): """Process data with retry logic.""" for attempt in range(max_retries): try: return await self._process_data(data) except TemporaryError as e: if attempt < max_retries - 1: wait_time = 2 ** attempt # Exponential backoff log.warning("Attempt %d failed, retrying in %ds: %s", attempt + 1, wait_time, e) await asyncio.sleep(wait_time) else: raise except PermanentError: # Don't retry permanent errors raise   ","version":"Next","tagName":"h3"},{"title":"Best Practices​","type":1,"pageTitle":"Create Gateways","url":"/solace-agent-mesh/docs/documentation/developing/create-gateways#best-practices","content":" ","version":"Next","tagName":"h2"},{"title":"1. Configuration Management​","type":1,"pageTitle":"Create Gateways","url":"/solace-agent-mesh/docs/documentation/developing/create-gateways#1-configuration-management","content":" Use environment variables for sensitive dataProvide sensible defaultsValidate configuration at startup  ","version":"Next","tagName":"h3"},{"title":"2. Error Handling​","type":1,"pageTitle":"Create Gateways","url":"/solace-agent-mesh/docs/documentation/developing/create-gateways#2-error-handling","content":" Implement comprehensive error handlingUse appropriate HTTP status codesLog errors with sufficient contextProvide meaningful error messages  ","version":"Next","tagName":"h3"},{"title":"3. Security​","type":1,"pageTitle":"Create Gateways","url":"/solace-agent-mesh/docs/documentation/developing/create-gateways#3-security","content":" Validate all external inputsUse secure authentication methodsImplement rate limiting where appropriateStore secrets securely (use environment variables)Follow principle of least privilege  ","version":"Next","tagName":"h3"},{"title":"4. Performance​","type":1,"pageTitle":"Create Gateways","url":"/solace-agent-mesh/docs/documentation/developing/create-gateways#4-performance","content":" Use async/await for I/O operationsImplement connection pooling for external APIsMonitor resource usageHandle backpressure appropriately  ","version":"Next","tagName":"h3"},{"title":"5. Monitoring and Logging​","type":1,"pageTitle":"Create Gateways","url":"/solace-agent-mesh/docs/documentation/developing/create-gateways#5-monitoring-and-logging","content":" Use structured loggingInclude correlation IDsMonitor key metrics (latency, error rates, throughput)Set up health checks  ","version":"Next","tagName":"h3"},{"title":"Common Gateway Patterns​","type":1,"pageTitle":"Create Gateways","url":"/solace-agent-mesh/docs/documentation/developing/create-gateways#common-gateway-patterns","content":" ","version":"Next","tagName":"h2"},{"title":"HTTP/REST API Gateway​","type":1,"pageTitle":"Create Gateways","url":"/solace-agent-mesh/docs/documentation/developing/create-gateways#httprest-api-gateway","content":" For HTTP-based integrations:  from fastapi import FastAPI, HTTPException, Depends from fastapi.security import HTTPBearer class HTTPAPIGatewayComponent(BaseGatewayComponent): def __init__(self, **kwargs): super().__init__(**kwargs) self.app = FastAPI() self.security = HTTPBearer() self._setup_routes() def _setup_routes(self): @self.app.post("/webhook/{endpoint_id}") async def webhook_handler(endpoint_id: str, request: Request, token: str = Depends(self.security)): # Authenticate request user_identity = await self.authenticate_and_enrich_user({ "token": token, "endpoint_id": endpoint_id, "request": request }) if not user_identity: raise HTTPException(status_code=401, detail="Unauthorized") # Process webhook body = await request.json() target_agent, parts, context = await self._translate_external_input( body, user_identity ) task_id = await self.submit_a2a_task( target_agent_name=target_agent, a2a_parts=parts, external_request_context=context, user_identity=user_identity ) return {"task_id": task_id, "status": "accepted"}   ","version":"Next","tagName":"h3"},{"title":"WebSocket Gateway​","type":1,"pageTitle":"Create Gateways","url":"/solace-agent-mesh/docs/documentation/developing/create-gateways#websocket-gateway","content":" For real-time bidirectional communication:  import websockets import json class WebSocketGatewayComponent(BaseGatewayComponent): def __init__(self, **kwargs): super().__init__(**kwargs) self.connections = {} async def _start_listener(self): """Start WebSocket server.""" self.server = await websockets.serve( self.handle_websocket, self.get_config("websocket_host", "localhost"), self.get_config("websocket_port", 8765) ) log.info("%s WebSocket server started", self.log_identifier) async def handle_websocket(self, websocket, path): """Handle WebSocket connections.""" connection_id = self.generate_uuid() self.connections[connection_id] = websocket try: async for message in websocket: data = json.loads(message) await self.process_websocket_message(connection_id, data) except websockets.exceptions.ConnectionClosed: log.info("%s WebSocket connection closed: %s", self.log_identifier, connection_id) finally: self.connections.pop(connection_id, None) async def process_websocket_message(self, connection_id: str, data: dict): """Process incoming WebSocket message.""" user_identity = await self.authenticate_and_enrich_user({ "connection_id": connection_id, "data": data }) if user_identity: target_agent, parts, context = await self._translate_external_input( data, user_identity ) context["connection_id"] = connection_id await self.submit_a2a_task( target_agent_name=target_agent, a2a_parts=parts, external_request_context=context, user_identity=user_identity ) async def _send_final_response_to_external(self, context: Dict[str, Any], task_data: Task): """Send response back via WebSocket.""" connection_id = context.get("connection_id") websocket = self.connections.get(connection_id) if websocket: response = { "task_id": task_data.id, "status": task_data.status.state.value if task_data.status else "unknown", "result": self._extract_text_from_task(task_data) } await websocket.send(json.dumps(response))   ","version":"Next","tagName":"h3"},{"title":"Message Queue Gateway​","type":1,"pageTitle":"Create Gateways","url":"/solace-agent-mesh/docs/documentation/developing/create-gateways#message-queue-gateway","content":" For integration with message queues:  import asyncio import aio_pika class MessageQueueGatewayComponent(BaseGatewayComponent): def __init__(self, **kwargs): super().__init__(**kwargs) self.connection = None self.channel = None async def _start_listener(self): """Connect to message queue and start consuming.""" connection_url = self.get_config("rabbitmq_url") queue_name = self.get_config("input_queue_name") self.connection = await aio_pika.connect_robust(connection_url) self.channel = await self.connection.channel() queue = await self.channel.declare_queue(queue_name, durable=True) await queue.consume(self.process_message) log.info("%s Started consuming from queue: %s", self.log_identifier, queue_name) async def process_message(self, message: aio_pika.IncomingMessage): """Process incoming queue message.""" async with message.process(): try: data = json.loads(message.body.decode()) user_identity = await self.authenticate_and_enrich_user(data) if not user_identity: log.warning("%s Authentication failed for message", self.log_identifier) return target_agent, parts, context = await self._translate_external_input( data, user_identity ) context["message_id"] = message.message_id context["reply_to"] = message.reply_to await self.submit_a2a_task( target_agent_name=target_agent, a2a_parts=parts, external_request_context=context, user_identity=user_identity ) except Exception as e: log.exception("%s Error processing message: %s", self.log_identifier, e) async def _send_final_response_to_external(self, context: Dict[str, Any], task_data: Task): """Send response back to reply queue.""" reply_to = context.get("reply_to") if reply_to and self.channel: response = { "task_id": task_data.id, "status": task_data.status.state.value if task_data.status else "unknown", "result": self._extract_text_from_task(task_data) } await self.channel.default_exchange.publish( aio_pika.Message(json.dumps(response).encode()), routing_key=reply_to )   ","version":"Next","tagName":"h3"},{"title":"Packaging as a Plugin​","type":1,"pageTitle":"Create Gateways","url":"/solace-agent-mesh/docs/documentation/developing/create-gateways#packaging-as-a-plugin","content":" For distribution and reusability, package your gateway as a plugin:  ","version":"Next","tagName":"h2"},{"title":"1. Create Plugin Structure​","type":1,"pageTitle":"Create Gateways","url":"/solace-agent-mesh/docs/documentation/developing/create-gateways#1-create-plugin-structure","content":" The following structure is created when running the sam plugin create my-gateway-plugin --type gateway command:  my-gateway-plugin/ ├── pyproject.toml ├── README.md ├── src/ │ └── sam_my_gateway/ │ ├── __init__.py │ ├── app.py │ ├── component.py ├── config.yaml └── examples/ └── my_gateway_example.yaml   ","version":"Next","tagName":"h3"},{"title":"2. Configure pyproject.toml​","type":1,"pageTitle":"Create Gateways","url":"/solace-agent-mesh/docs/documentation/developing/create-gateways#2-configure-pyprojecttoml","content":" Update the pyproject.toml file to include your gateway dependencies:  ... dependencies = [ "watchdog>=3.0.0", # Add your specific dependencies ] ...   ","version":"Next","tagName":"h3"},{"title":"3. Build and Install​","type":1,"pageTitle":"Create Gateways","url":"/solace-agent-mesh/docs/documentation/developing/create-gateways#3-build-and-install","content":" # Build the plugin sam plugin build # Install plugin from local wheel file sam plugin add my-gateway --plugin dist/sam_my_gateway-0.1.0-py3-none-any.whl   ","version":"Next","tagName":"h3"},{"title":"Troubleshooting​","type":1,"pageTitle":"Create Gateways","url":"/solace-agent-mesh/docs/documentation/developing/create-gateways#troubleshooting","content":" ","version":"Next","tagName":"h2"},{"title":"Common Issues​","type":1,"pageTitle":"Create Gateways","url":"/solace-agent-mesh/docs/documentation/developing/create-gateways#common-issues","content":" Gateway Fails to Start​  Check configuration schema validationVerify all required parameters are providedEnsure external dependencies are installed  Tasks Not Reaching Agents​  Verify namespace configuration matches agentsCheck Solace broker connectivityConfirm agent names are correct  Authentication Failures​  Validate user identity extraction logicCheck authorization service configurationVerify claims format matches expectations  File/Artifact Issues​  Ensure artifact service is properly configuredCheck file permissions and pathsVerify artifact URI construction  ","version":"Next","tagName":"h3"},{"title":"Debugging Tips​","type":1,"pageTitle":"Create Gateways","url":"/solace-agent-mesh/docs/documentation/developing/create-gateways#debugging-tips","content":" Enable Debug Logging: log: stdout_log_level: DEBUG log_file_level: DEBUG Use Test Agents: Create simple echo agents for testing gateway integration Monitor Solace Topics: Use Solace monitoring tools to trace message flow Add Correlation IDs: Include unique identifiers in logs for request tracing ","version":"Next","tagName":"h3"},{"title":"Installing Agent Mesh Enterprise","type":0,"sectionRef":"#","url":"/solace-agent-mesh/docs/documentation/enterprise/installation","content":"","keywords":"","version":"Next"},{"title":"Prerequisites​","type":1,"pageTitle":"Installing Agent Mesh Enterprise","url":"/solace-agent-mesh/docs/documentation/enterprise/installation#prerequisites","content":" Before you begin, ensure you have the following:  Docker installed on your systemAccess to the Solace Product PortalAn LLM service API key and endpointFor production deployments, Solace broker credentials  ","version":"Next","tagName":"h2"},{"title":"Understanding the Installation Process​","type":1,"pageTitle":"Installing Agent Mesh Enterprise","url":"/solace-agent-mesh/docs/documentation/enterprise/installation#understanding-the-installation-process","content":" The installation process consists of three main steps. First, you download and load the Docker image into your local Docker environment. This makes the Agent Mesh Enterprise software available on your system. Second, you identify the exact image name and tag that Docker assigned during the load process. You need this information to reference the correct image when starting your container. Finally, you run the container with the appropriate configuration for your use case—either development mode with an embedded broker or production mode connected to an external Solace broker.  ","version":"Next","tagName":"h2"},{"title":"Step 1: Download and Load the Enterprise Image​","type":1,"pageTitle":"Installing Agent Mesh Enterprise","url":"/solace-agent-mesh/docs/documentation/enterprise/installation#step-1-download-and-load-the-enterprise-image","content":" You need to obtain the Agent Mesh Enterprise Docker image from the Solace Product Portal and load it into your Docker environment.  Download the latest enterprise docker image tarball from the Solace Product Portal.  After downloading the tarball, load the image into Docker. This command extracts the image from the compressed archive and makes it available in your local Docker image repository.  docker load -i solace-agent-mesh-enterprise-<tag>.tar.gz   Ensure you replace <tag> with the appropriate version number from your downloaded file.  ","version":"Next","tagName":"h2"},{"title":"Step 2: Identify the Image Name​","type":1,"pageTitle":"Installing Agent Mesh Enterprise","url":"/solace-agent-mesh/docs/documentation/enterprise/installation#step-2-identify-the-image-name","content":" After loading the image, you need to identify its full name and tag. Docker assigns a repository name and tag to the image during the load process, and you will use this information when running the container.  Run the following command to list all Docker images on your system:  docker images   The output displays all available images with their repository names, tags, image IDs, creation dates, and sizes. Look for the Agent Mesh Enterprise image in the list.  Example output:  REPOSITORY TAG IMAGE ID CREATED SIZE 868978040651.dkr.ecr.us-east-1.amazonaws.com/solace-agent-mesh-enterprise 1.0.37-c8890c7f31 2589d25d0917 9 days ago 5.25 GB   Take note of the complete repository name and tag. You will need this full identifier when starting the container. In the example above, the complete image name is 868978040651.dkr.ecr.us-east-1.amazonaws.com/solace-agent-mesh-enterprise:1.0.37-c8890c7f31.  The numeric hashes at the beginning and end of the repository name (such as 868978040651 and c8890c7f31) vary between versions and builds. Your image will have different hash values.  ","version":"Next","tagName":"h2"},{"title":"Step 3: Run the Container​","type":1,"pageTitle":"Installing Agent Mesh Enterprise","url":"/solace-agent-mesh/docs/documentation/enterprise/installation#step-3-run-the-container","content":" You can run Agent Mesh Enterprise in two different modes depending on your needs. Development mode uses an embedded Solace broker for quick testing and experimentation, while production mode connects to an external Solace broker for enterprise deployments.  tip You may need to include --platform linux/amd64 depending on the host machine you're using.  ","version":"Next","tagName":"h2"},{"title":"Running in Development Mode​","type":1,"pageTitle":"Installing Agent Mesh Enterprise","url":"/solace-agent-mesh/docs/documentation/enterprise/installation#running-in-development-mode","content":" Development mode simplifies getting started by using an embedded Solace broker. This configuration requires fewer parameters and allows you to test Agent Mesh Enterprise without setting up external infrastructure. Use this mode for local development, testing, and evaluation.  The following command starts a container in development mode. The -itd flags run the container in interactive mode with a pseudo-TTY, detached in the background. The -p 8001:8000 flag maps port 8000 inside the container to port 8001 on your host machine, making the web UI accessible at http://localhost:8001.  docker run -itd -p 8001:8000 \\ -e LLM_SERVICE_API_KEY="<YOUR_LLM_TOKEN>" \\ -e LLM_SERVICE_ENDPOINT="<YOUR_LLM_SERVICE_ENDPOINT>" \\ -e LLM_SERVICE_PLANNING_MODEL_NAME="<YOUR_MODEL_NAME>" \\ -e LLM_SERVICE_GENERAL_MODEL_NAME="<YOUR_MODEL_NAME>" \\ -e NAMESPACE="<YOUR_NAMESPACE>" \\ -e SOLACE_DEV_MODE="true" \\ --name sam-ent-dev \\ solace-agent-mesh-enterprise:<tag>   Replace the placeholder values with your actual configuration:  <YOUR_LLM_TOKEN>: Your API key for the LLM service<YOUR_LLM_SERVICE_ENDPOINT>: The URL endpoint for your LLM service<YOUR_MODEL_NAME>: The name of the LLM model you want to use (you can specify the same model for both planning and general tasks, or use different models)<YOUR_NAMESPACE>: A unique identifier for your deployment (such as "sam-dev")<tag>: The image tag you identified in Step 2  The SOLACE_DEV_MODE="true" environment variable tells the container to use the embedded broker instead of connecting to an external one.  Example docker run -itd -p 8001:8000 \\ -e LLM_SERVICE_API_KEY="<YOUR_LLM_TOKEN>" \\ -e LLM_SERVICE_ENDPOINT="https://lite-llm.mymaas.net/" \\ -e LLM_SERVICE_PLANNING_MODEL_NAME="openai/vertex-claude-4-sonnet" \\ -e LLM_SERVICE_GENERAL_MODEL_NAME="openai/vertex-claude-4-sonnet" \\ -e NAMESPACE="sam-dev" \\ -e SOLACE_DEV_MODE="true" \\ --name sam-ent-dev \\ 868978040651.dkr.ecr.us-east-1.amazonaws.com/solace-agent-mesh-enterprise:1.0.37-c8890c7f31   ","version":"Next","tagName":"h3"},{"title":"Running in Production Mode​","type":1,"pageTitle":"Installing Agent Mesh Enterprise","url":"/solace-agent-mesh/docs/documentation/enterprise/installation#running-in-production-mode","content":" Production mode connects to an external Solace broker, which provides enterprise-grade messaging capabilities including high availability, disaster recovery, and scalability. Use this mode when deploying Agent Mesh Enterprise in production environments.  The production configuration requires additional environment variables to specify the Solace broker connection details. These credentials allow the container to connect to your Solace Cloud service or on-premises broker.  docker run -itd -p 8001:8000 \\ -e LLM_SERVICE_API_KEY="<YOUR_LLM_TOKEN>" \\ -e LLM_SERVICE_ENDPOINT="<YOUR_LLM_SERVICE_ENDPOINT>" \\ -e LLM_SERVICE_PLANNING_MODEL_NAME="<YOUR_MODEL_NAME>" \\ -e LLM_SERVICE_GENERAL_MODEL_NAME="<YOUR_MODEL_NAME>" \\ -e NAMESPACE="<YOUR_NAMESPACE>" \\ -e SOLACE_DEV_MODE="false" \\ -e SOLACE_BROKER_URL="<YOUR_BROKER_URL>" \\ -e SOLACE_BROKER_VPN="<YOUR_BROKER_VPN>" \\ -e SOLACE_BROKER_USERNAME="<YOUR_BROKER_USERNAME>" \\ -e SOLACE_BROKER_PASSWORD="<YOUR_BROKER_PASSWORD>" \\ --name sam-ent-prod \\ solace-agent-mesh-enterprise:<tag>   Replace the placeholder values with your actual configuration. In addition to the LLM service parameters described in the development mode section, you need to provide:  <YOUR_BROKER_URL>: The secured SMF URI for your Solace broker<YOUR_BROKER_VPN>: The Message VPN name for your Solace service<YOUR_BROKER_USERNAME>: The username for broker authentication<YOUR_BROKER_PASSWORD>: The password for broker authentication  The SOLACE_DEV_MODE="false" environment variable tells the container to connect to the external broker specified by the other SOLACE_BROKER parameters instead of using the embedded broker.  How to find your credentials Go to Solace Cloud. Cluster manager > Your Service > Connect Switch dropdown to View by Language Open the connect with Python dropdown Click Solace Python with smf as the protocol. Copy: Username for SOLACE_BROKER_USERNAME,Password for SOLACE_BROKER_PASSWORD,Message VPN for SOLACE_BROKER_VPNSecured SMF URI for SOLACE_BROKER_URL  ","version":"Next","tagName":"h3"},{"title":"Accessing the Web UI​","type":1,"pageTitle":"Installing Agent Mesh Enterprise","url":"/solace-agent-mesh/docs/documentation/enterprise/installation#accessing-the-web-ui","content":" After starting the container in either development or production mode, you can access the Agent Mesh Enterprise web interface through your browser. The UI provides a graphical interface for managing agents, monitoring activity, and configuring your deployment.  Navigate to http://localhost:8001 in your web browser. The port number corresponds to the host port you specified in the -p 8001:8000 flag when running the container.  ","version":"Next","tagName":"h2"},{"title":"Troubleshooting and Debugging​","type":1,"pageTitle":"Installing Agent Mesh Enterprise","url":"/solace-agent-mesh/docs/documentation/enterprise/installation#troubleshooting-and-debugging","content":" If you encounter issues or need to investigate the behavior of your Agent Mesh Enterprise deployment, you can examine the log files generated by the container. These logs provide detailed information about system operations, errors, and debugging information.  To view logs, check the .log files in your container. For information about changing debug levels and advanced debugging techniques, see Diagnosing and Resolving Problems. ","version":"Next","tagName":"h2"},{"title":"Setting Up RBAC","type":0,"sectionRef":"#","url":"/solace-agent-mesh/docs/documentation/enterprise/rbac-setup-guide","content":"","keywords":"","version":"Next"},{"title":"Table of Contents​","type":1,"pageTitle":"Setting Up RBAC","url":"/solace-agent-mesh/docs/documentation/enterprise/rbac-setup-guide#table-of-contents","content":" Understanding RBAC in Agent Mesh EnterprisePlanning Your RBAC ConfigurationSetting Up RBAC in DockerUnderstanding Configuration FilesAdvanced Configuration OptionsBest PracticesTroubleshooting  ","version":"Next","tagName":"h2"},{"title":"Understanding RBAC in Agent Mesh Enterprise​","type":1,"pageTitle":"Setting Up RBAC","url":"/solace-agent-mesh/docs/documentation/enterprise/rbac-setup-guide#understanding-rbac-in-agent-mesh-enterprise","content":" Before you configure RBAC, you need to understand how the system works. Agent Mesh Enterprise uses a three-tier authorization model that separates identity, roles, and permissions.  ","version":"Next","tagName":"h2"},{"title":"The Three Components​","type":1,"pageTitle":"Setting Up RBAC","url":"/solace-agent-mesh/docs/documentation/enterprise/rbac-setup-guide#the-three-components","content":" RBAC in Agent Mesh Enterprise consists of three interconnected components:  Users represent identities in your system. Each user has a unique identifier, typically an email address. When a user attempts to access a feature or resource, Agent Mesh Enterprise checks their assigned roles to determine what they can do.  Roles are collections of permissions that you assign to users. Instead of granting permissions directly to individual users, you create roles that represent job functions or responsibilities. For example, you might create a "data_analyst" role for users who need to work with data tools and artifacts. This approach simplifies administration because you can modify a role's permissions once and affect all users assigned to that role.  Scopes are the actual permissions that grant access to specific features or resources. Each scope follows a pattern that identifies what it controls. For example, the scope tool:data:read grants permission to read data tools, while artifact:create allows creating artifacts. Scopes use wildcards to grant broader permissions. For example, the scope tool:data:* grants all permissions for data tools.  ","version":"Next","tagName":"h3"},{"title":"How Authorization Works​","type":1,"pageTitle":"Setting Up RBAC","url":"/solace-agent-mesh/docs/documentation/enterprise/rbac-setup-guide#how-authorization-works","content":" When a user attempts an action in Agent Mesh Enterprise, the system follows this authorization flow:  The system identifies the user based on their authentication credentialsIt retrieves all roles assigned to that userFor each role, it collects all associated scopes (permissions)It checks if any of the user's scopes match the permission required for the requested actionIf a matching scope exists, the system allows the action; otherwise, it denies access  This model implements the principle of least privilege: users receive only the permissions they need to perform their job functions.  ","version":"Next","tagName":"h3"},{"title":"Planning Your RBAC Configuration​","type":1,"pageTitle":"Setting Up RBAC","url":"/solace-agent-mesh/docs/documentation/enterprise/rbac-setup-guide#planning-your-rbac-configuration","content":" Before you create configuration files, you should plan your RBAC structure. This planning phase helps you design a system that meets your organization's needs while remaining maintainable.  ","version":"Next","tagName":"h2"},{"title":"Identifying User Types​","type":1,"pageTitle":"Setting Up RBAC","url":"/solace-agent-mesh/docs/documentation/enterprise/rbac-setup-guide#identifying-user-types","content":" Start by identifying the different types of users in your organization. Consider their job functions and what they need to accomplish with Agent Mesh Enterprise. Common user types include:  Administrators need full access to all features and resources. They manage the system, configure settings, and troubleshoot issues. You typically assign these users a role with wildcard permissions.  Operators perform day-to-day tasks such as running tools, creating artifacts, and monitoring system activity. They need broad access to operational features but not administrative capabilities.  Analysts work with data and reports. They need access to data tools, artifact creation, and monitoring capabilities, but they do not need access to system configuration or advanced tools.  Viewers need read-only access to monitor system activity and view artifacts. They cannot create, modify, or delete resources.  ","version":"Next","tagName":"h3"},{"title":"Designing Roles​","type":1,"pageTitle":"Setting Up RBAC","url":"/solace-agent-mesh/docs/documentation/enterprise/rbac-setup-guide#designing-roles","content":" Once you identify user types, design roles that match their needs. Each role should represent a specific job function and include only the scopes necessary for that function.  Consider creating a role hierarchy where some roles inherit permissions from others. For example, an "operator" role might inherit all permissions from a "viewer" role and add additional capabilities. This approach reduces duplication and makes your configuration easier to maintain.  ","version":"Next","tagName":"h3"},{"title":"Mapping Scopes to Features​","type":1,"pageTitle":"Setting Up RBAC","url":"/solace-agent-mesh/docs/documentation/enterprise/rbac-setup-guide#mapping-scopes-to-features","content":" Understanding available scopes helps you design effective roles. Agent Mesh Enterprise uses a hierarchical scope naming convention:  Tool scopes control access to tools and follow the pattern tool:<category>:<action>. For example, tool:basic:read grants permission to read basic tools, while tool:data:* grants all permissions for data tools.  Artifact scopes control access to artifacts (files and data created by the system) and use the pattern artifact:<action>. Common artifact scopes include artifact:read, artifact:create, and artifact:delete.  Monitoring scopes control access to system monitoring features and follow the pattern monitor/namespace/<namespace>:a2a_messages:subscribe. These scopes allow users to observe message traffic in specific namespaces.  The wildcard scope * grants all permissions and should only be used for administrator roles.  ","version":"Next","tagName":"h3"},{"title":"Setting Up RBAC in Docker​","type":1,"pageTitle":"Setting Up RBAC","url":"/solace-agent-mesh/docs/documentation/enterprise/rbac-setup-guide#setting-up-rbac-in-docker","content":" Now that you understand RBAC concepts and have planned your configuration, you can set up RBAC in your Docker environment. This process involves creating configuration files, setting up the Docker container, and verifying that everything works correctly.  ","version":"Next","tagName":"h2"},{"title":"Prerequisites​","type":1,"pageTitle":"Setting Up RBAC","url":"/solace-agent-mesh/docs/documentation/enterprise/rbac-setup-guide#prerequisites","content":" Before you begin, ensure you have:  Docker installed and running on your systemThe Agent Mesh Enterprise Docker image (solace-agent-mesh-enterprise)A text editor for creating configuration filesBasic familiarity with YAML file format  ","version":"Next","tagName":"h3"},{"title":"Creating the Configuration Directory Structure​","type":1,"pageTitle":"Setting Up RBAC","url":"/solace-agent-mesh/docs/documentation/enterprise/rbac-setup-guide#creating-the-configuration-directory-structure","content":" You need to create a directory structure on your host system to store RBAC configuration files. The Docker container will mount this directory to access your configurations.  Create the directory structure as follows:  mkdir -p sam-enterprise/config/auth   This command creates a sam-enterprise directory with a nested config/auth subdirectory. The auth subdirectory will contain your RBAC configuration files.  ","version":"Next","tagName":"h3"},{"title":"Defining Roles and Permissions​","type":1,"pageTitle":"Setting Up RBAC","url":"/solace-agent-mesh/docs/documentation/enterprise/rbac-setup-guide#defining-roles-and-permissions","content":" Create a file named role-to-scope-definitions.yaml in the sam-enterprise/config/auth directory. This file defines all roles in your system and the scopes (permissions) associated with each role.  Here is an example configuration that defines three roles:  # role-to-scope-definitions.yaml roles: enterprise_admin: description: "Full access for enterprise administrators" scopes: - "*" # Wildcard grants all permissions data_analyst: description: "Data analysis and visualization specialist" scopes: - "tool:data:*" # All data tools - "artifact:read" - "artifact:create" - "monitor/namespace/*:a2a_messages:subscribe" # Can monitor any namespace standard_user: description: "Standard user with basic access" scopes: - "artifact:read" - "tool:basic:read" - "tool:basic:search"   This configuration creates three distinct roles:  The enterprise_admin role receives the wildcard scope *, which grants all permissions in the system. You should assign this role only to trusted administrators who need complete control over Agent Mesh Enterprise.  The data_analyst role receives permissions tailored for data analysis work. The scope tool:data:* grants all permissions for data-related tools (read, write, execute). The artifact:read and artifact:create scopes allow analysts to view existing artifacts and create new ones. The monitoring scope monitor/namespace/*:a2a_messages:subscribe enables analysts to observe message traffic across all namespaces, which helps them understand data flows.  The standard_user role provides minimal permissions for basic operations. Users with this role can read artifacts and perform basic tool operations but cannot create new artifacts or access advanced features.  ","version":"Next","tagName":"h3"},{"title":"Assigning Users to Roles​","type":1,"pageTitle":"Setting Up RBAC","url":"/solace-agent-mesh/docs/documentation/enterprise/rbac-setup-guide#assigning-users-to-roles","content":" Create a file named user-to-role-assignments.yaml in the sam-enterprise/config/auth directory. This file maps user identities to roles.  Here is an example configuration:  # user-to-role-assignments.yaml users: admin@example.com: roles: ["enterprise_admin"] description: "Enterprise Administrator Account" data.analyst@example.com: roles: ["data_analyst"] description: "Senior Data Analyst" user1@example.com: roles: ["standard_user"] description: "Standard Enterprise User"   Each entry in this file maps a user identity (typically an email address) to one or more roles. The user identity must match exactly what your authentication system provides because Agent Mesh Enterprise performs case-sensitive matching.  You can assign multiple roles to a single user by listing them in the roles array. When a user has multiple roles, they receive the combined permissions from all assigned roles. For example, if you assign both data_analyst and standard_user roles to a user, they receive all scopes from both roles.  The description field is optional but recommended. It helps you document the purpose of each user account, which is valuable when reviewing or auditing your RBAC configuration.  ","version":"Next","tagName":"h3"},{"title":"Creating the Enterprise Configuration​","type":1,"pageTitle":"Setting Up RBAC","url":"/solace-agent-mesh/docs/documentation/enterprise/rbac-setup-guide#creating-the-enterprise-configuration","content":" Create a file named enterprise_config.yaml in the sam-enterprise/config directory (not in the auth subdirectory). This file tells Agent Mesh Enterprise where to find your RBAC configuration files and how to use them.  # enterprise_config.yaml authorization_service: type: "default_rbac" role_to_scope_definitions_path: "config/auth/role-to-scope-definitions.yaml" user_to_role_assignments_path: "config/auth/user-to-role-assignments.yaml" namespace: "enterprise_prod" gateway_id: "enterprise_gateway"   The authorization_service section configures the RBAC system. The type field specifies default_rbac, which tells Agent Mesh Enterprise to use the file-based RBAC system. The two path fields point to your RBAC configuration files—these paths are relative to the container's working directory, not your host system.  The namespace and gateway_id fields configure the Agent Mesh Enterprise instance. The namespace isolates this instance from others, while the gateway ID identifies the web interface gateway.  ","version":"Next","tagName":"h3"},{"title":"Running the Docker Container​","type":1,"pageTitle":"Setting Up RBAC","url":"/solace-agent-mesh/docs/documentation/enterprise/rbac-setup-guide#running-the-docker-container","content":" Now you can start the Docker container with your RBAC configuration. Navigate to your sam-enterprise directory and run:  cd sam-enterprise docker run -d \\ --name sam-enterprise \\ -p 8001:8000 \\ -v "$(pwd):/app" \\ -e SAM_AUTHORIZATION_CONFIG="/app/config/auth/enterprise_config.yaml" \\ -e NAMESPACE=enterprise_prod \\ -e WEBUI_GATEWAY_ID=enterprise_gateway \\ -e ... list here all other necessary env vars ... solace-agent-mesh-enterprise:<tagname>   ","version":"Next","tagName":"h3"},{"title":"Verifying Your Configuration​","type":1,"pageTitle":"Setting Up RBAC","url":"/solace-agent-mesh/docs/documentation/enterprise/rbac-setup-guide#verifying-your-configuration","content":" After starting the container, you should verify that RBAC is working correctly. Follow these steps:  Open your web browser and navigate to http://localhost:8001Log in using one of the user identities defined in your user-to-role-assignments.yaml fileAttempt to access features that the user should have permission to useAttempt to access features that the user should not have permission to use  If RBAC is configured correctly, the user can access permitted features and receives authorization errors when attempting to access restricted features.  You can also check the container logs to verify that Agent Mesh Enterprise loaded your configuration files:  docker logs sam-enterprise   Look for log messages that indicate successful configuration loading. You should see messages similar to:  INFO:solace_ai_connector:[ConfigurableRbacAuthSvc] Successfully loaded role-to-scope definitions from: /app/config/auth/role-to-scope-definitions.yaml DEBUG:solace_ai_connector:[ConfigurableRbacAuthSvc] Role 'enterprise_admin' loaded with 1 direct scopes, 1 resolved scopes. DEBUG:solace_ai_connector:[ConfigurableRbacAuthSvc] Role 'data_analyst' loaded with 4 direct scopes, 4 resolved scopes. DEBUG:solace_ai_connector:[ConfigurableRbacAuthSvc] Role 'standard_user' loaded with 3 direct scopes, 3 resolved scopes.   These messages confirm that Agent Mesh Enterprise found and parsed your configuration files correctly.  ","version":"Next","tagName":"h3"},{"title":"Understanding Configuration Files​","type":1,"pageTitle":"Setting Up RBAC","url":"/solace-agent-mesh/docs/documentation/enterprise/rbac-setup-guide#understanding-configuration-files","content":" Now that you have a working RBAC configuration, you should understand the full structure and capabilities of each configuration file. This knowledge helps you customize the configuration to meet your specific needs.  ","version":"Next","tagName":"h2"},{"title":"Role-to-Scope Definitions Structure​","type":1,"pageTitle":"Setting Up RBAC","url":"/solace-agent-mesh/docs/documentation/enterprise/rbac-setup-guide#role-to-scope-definitions-structure","content":" The role-to-scope-definitions.yaml file supports several features beyond the basic examples shown earlier. Here is the complete structure:  roles: role_name: description: "Role description" scopes: - "scope1" - "scope2" inherits: # Optional - inherit scopes from other roles - "parent_role1" - "parent_role2"   The inherits field allows you to create role hierarchies. When a role inherits from another role, it receives all scopes from the parent role in addition to its own scopes. This feature reduces duplication and makes your configuration easier to maintain.  For example, you might create a base "viewer" role with read-only permissions, then create an "operator" role that inherits from "viewer" and adds write permissions:  roles: viewer: description: "Read-only access" scopes: - "tool:basic:read" - "artifact:read" operator: description: "Operational access" inherits: - "viewer" scopes: - "tool:basic:*" - "artifact:create"   In this example, the "operator" role receives all scopes from "viewer" (tool:basic:read and artifact:read) plus its own scopes (tool:basic:* and artifact:create). Note that tool:basic:* includes tool:basic:read, so there is some overlap. Agent Mesh Enterprise handles this correctly by deduplicating scopes.  ","version":"Next","tagName":"h3"},{"title":"User-to-Role Assignments Structure​","type":1,"pageTitle":"Setting Up RBAC","url":"/solace-agent-mesh/docs/documentation/enterprise/rbac-setup-guide#user-to-role-assignments-structure","content":" The user-to-role-assignments.yaml file supports both global user identities and gateway-specific identities. Here is the complete structure:  users: user_identity: roles: ["role1", "role2"] description: "User description" # Optional: Gateway-specific user identities gateway_specific_identities: gateway_id:user_identity: roles: ["role1", "role2"] description: "User with specific roles on this gateway"   The users section defines global user identities that apply across all gateways. Most configurations only need this section.  The gateway_specific_identities section allows you to assign different roles to the same user identity on different gateways. This feature is useful in multi-gateway deployments where you want to grant different permissions based on which gateway a user accesses. The key format is gateway_id:user_identity, where gateway_id matches the gateway ID in your enterprise configuration.  ","version":"Next","tagName":"h3"},{"title":"Enterprise Configuration Structure​","type":1,"pageTitle":"Setting Up RBAC","url":"/solace-agent-mesh/docs/documentation/enterprise/rbac-setup-guide#enterprise-configuration-structure","content":" The enterprise configuration file supports multiple authorization service types. Here is the complete structure for the file-based RBAC system:  authorization_service: type: "default_rbac" role_to_scope_definitions_path: "path/to/role-to-scope-definitions.yaml" user_to_role_assignments_path: "path/to/user-to-role-assignments.yaml"   ","version":"Next","tagName":"h3"},{"title":"Advanced Configuration Options​","type":1,"pageTitle":"Setting Up RBAC","url":"/solace-agent-mesh/docs/documentation/enterprise/rbac-setup-guide#advanced-configuration-options","content":" After you have a basic RBAC configuration working, you might want to explore advanced options that provide additional flexibility and integration capabilities.  ","version":"Next","tagName":"h2"},{"title":"Production-Ready Role Configuration​","type":1,"pageTitle":"Setting Up RBAC","url":"/solace-agent-mesh/docs/documentation/enterprise/rbac-setup-guide#production-ready-role-configuration","content":" A production environment typically needs more sophisticated role definitions than the basic examples . Here is a comprehensive configuration that demonstrates best practices:  # role-to-scope-definitions.yaml roles: admin: description: "Administrator with full access" scopes: - "*" operator: description: "System operator" scopes: - "tool:basic:*" - "tool:advanced:read" - "artifact:read" - "artifact:create" - "monitor/namespace/*:a2a_messages:subscribe" viewer: description: "Read-only access" scopes: - "tool:basic:read" - "artifact:read" - "monitor/namespace/*:a2a_messages:subscribe"   # user-to-role-assignments.yaml users: admin@company.com: roles: ["admin"] description: "System Administrator" operator@company.com: roles: ["operator"] description: "System Operator" viewer@company.com: roles: ["viewer"] description: "Read-only User"   This configuration creates a clear hierarchy of access levels. The admin role has unrestricted access, the operator role can perform most operational tasks, and the viewer role provides read-only access for monitoring and auditing purposes.  ","version":"Next","tagName":"h3"},{"title":"Integrating with Microsoft Graph​","type":1,"pageTitle":"Setting Up RBAC","url":"/solace-agent-mesh/docs/documentation/enterprise/rbac-setup-guide#integrating-with-microsoft-graph","content":" For enterprise environments that use Microsoft Entra ID (formerly Azure AD) for user management, you can integrate Agent Mesh Enterprise with Microsoft Graph. This integration allows you to manage user role assignments through Microsoft Graph instead of maintaining a separate YAML file.  To configure Microsoft Graph integration, modify your enterprise_config.yaml:  # enterprise_config.yaml authorization_service: type: "default_rbac" role_to_scope_definitions_path: "config/auth/role-to-scope-definitions.yaml" user_to_role_provider: "ms_graph" ms_graph_config: ms_graph_tenant_id: ${MS_GRAPH_TENANT_ID} ms_graph_client_id: ${MS_GRAPH_CLIENT_ID} ms_graph_client_secret: ${MS_GRAPH_CLIENT_SECRET}   This configuration tells Agent Mesh Enterprise to retrieve user role assignments from Microsoft Graph instead of reading them from a YAML file. The ${...} syntax indicates that these values come from environment variables, which keeps sensitive credentials out of your configuration files.  When you use Microsoft Graph integration, you still define roles in the role-to-scope-definitions.yaml file, but you manage user-to-role assignments through Microsoft Graph groups or attributes.  Run the Docker container with the Microsoft Graph credentials:  docker run -d \\ --name sam-enterprise \\ -p 8000:8001 \\ -v "$(pwd):/app" \\ -e MS_GRAPH_TENANT_ID=your-tenant-id \\ -e MS_GRAPH_CLIENT_ID=your-client-id \\ -e MS_GRAPH_CLIENT_SECRET=your-client-secret \\ -e NAMESPACE=enterprise_prod \\ -e WEBUI_GATEWAY_ID=enterprise_gateway \\ solace-agent-mesh-enterprise:<tag>   The Microsoft Graph integration requires that you configure an application registration in Microsoft Entra ID with appropriate permissions to read user and group information. The tenant ID identifies your Microsoft Entra ID tenant, the client ID identifies your application registration, and the client secret authenticates your application.  ","version":"Next","tagName":"h3"},{"title":"Best Practices​","type":1,"pageTitle":"Setting Up RBAC","url":"/solace-agent-mesh/docs/documentation/enterprise/rbac-setup-guide#best-practices","content":" Following best practices helps you create a secure, maintainable RBAC configuration that scales with your organization's needs.  ","version":"Next","tagName":"h2"},{"title":"Security Recommendations​","type":1,"pageTitle":"Setting Up RBAC","url":"/solace-agent-mesh/docs/documentation/enterprise/rbac-setup-guide#security-recommendations","content":" You should implement these security practices to protect your Agent Mesh Enterprise deployment:  Apply the principle of least privilege by assigning users only the minimum permissions necessary for their tasks. Start with restrictive permissions and add more as needed, rather than starting with broad permissions and removing them later. This approach reduces the risk of unauthorized access.  Conduct regular audits of your role assignments and permissions. Review who has access to what features and verify that access levels remain appropriate as job responsibilities change. Remove access for users who no longer need it.  Protect your RBAC configuration files with appropriate file permissions on your host system. These files control access to your entire Agent Mesh Enterprise deployment, so you should restrict read and write access to authorized administrators only.  Store sensitive information like Microsoft Graph credentials as environment variables rather than hardcoding them in configuration files. Environment variables provide better security because they do not appear in version control systems or configuration backups.  Never use development configurations in production environments. Development configurations often include test accounts with elevated permissions or relaxed security settings that are inappropriate for production use.  ","version":"Next","tagName":"h3"},{"title":"Role Design Principles​","type":1,"pageTitle":"Setting Up RBAC","url":"/solace-agent-mesh/docs/documentation/enterprise/rbac-setup-guide#role-design-principles","content":" Well-designed roles make your RBAC configuration easier to understand and maintain:  Create roles that align with job functions in your organization. Each role should represent a specific type of work that users perform. This alignment makes it easier to determine which role to assign to new users.  Use role inheritance to build a logical hierarchy. If one role needs all the permissions of another role plus additional permissions, use inheritance rather than duplicating scopes. This approach reduces configuration size and makes updates easier.  Use clear, descriptive names for roles that indicate their purpose. Names like "data_analyst" or "system_operator" are more meaningful than generic names like "role1" or "user_type_a".  Document the purpose and scope of each role in the description field. This documentation helps other administrators understand your RBAC configuration and makes it easier to maintain over time.  Minimize wildcard usage in scope definitions. While wildcards like * or tool:*:* are convenient, they grant broad permissions that might include features you did not intend to allow. Use specific scopes whenever possible, and reserve wildcards for administrator roles.  ","version":"Next","tagName":"h3"},{"title":"Docker-Specific Recommendations​","type":1,"pageTitle":"Setting Up RBAC","url":"/solace-agent-mesh/docs/documentation/enterprise/rbac-setup-guide#docker-specific-recommendations","content":" When you run Agent Mesh Enterprise in Docker, follow these recommendations:  Use Docker volumes for persistent configuration storage. The volume mount approach shown in this guide ensures that your configuration persists even if you remove and recreate the container.  Create separate configuration files for different environments (development, staging, production). This separation prevents accidental use of inappropriate configurations and makes it easier to maintain environment-specific settings.  Implement health checks to verify that RBAC is functioning correctly. You can add a health check to your Docker run command that periodically tests whether the container is responding correctly.  Regularly backup your RBAC configuration files. Store backups in a secure location separate from your Docker host. If you lose your configuration files, you lose control over who can access your Agent Mesh Enterprise deployment.  Follow Docker security best practices such as running containers as non-root users and using read-only filesystems where possible. These practices reduce the impact of potential security vulnerabilities.  ","version":"Next","tagName":"h3"},{"title":"Troubleshooting​","type":1,"pageTitle":"Setting Up RBAC","url":"/solace-agent-mesh/docs/documentation/enterprise/rbac-setup-guide#troubleshooting","content":" When you encounter issues with your RBAC configuration, systematic troubleshooting helps you identify and resolve problems quickly.  ","version":"Next","tagName":"h2"},{"title":"Authorization Denied for Valid User​","type":1,"pageTitle":"Setting Up RBAC","url":"/solace-agent-mesh/docs/documentation/enterprise/rbac-setup-guide#authorization-denied-for-valid-user","content":" If a user cannot access features they should have permission to use, you might see authorization denied messages in the logs or user interface.  To resolve this issue, first verify that the user identity matches exactly what appears in your user-to-role-assignments.yaml file. Agent Mesh Enterprise performs case-sensitive matching, so user@example.com and User@example.com are different identities.  Next, check that the role assigned to the user has the necessary scopes. Review the role-to-scope-definitions.yaml file and verify that the role includes scopes for the features the user is trying to access.  Ensure that your configuration files are correctly mounted in the Docker container. You can verify the mount by running:  docker exec -it sam-enterprise ls -la /app/config/auth   This command lists the files in the mounted directory. You should see your role-to-scope-definitions.yaml and user-to-role-assignments.yaml files.  Check the container logs for authorization service errors:  docker logs sam-enterprise   Look for messages with the [ConfigurableRbacAuthSvc] prefix. These messages indicate whether Agent Mesh Enterprise successfully loaded your configuration files and how it resolved roles and scopes. You should see messages like:  INFO:solace_ai_connector:[ConfigurableRbacAuthSvc] Successfully loaded role-to-scope definitions from: /app/config/auth/role-to-scope-definitions.yaml DEBUG:solace_ai_connector:[ConfigurableRbacAuthSvc] Role 'enterprise_admin' loaded with 1 direct scopes, 1 resolved scopes. DEBUG:solace_ai_connector:[ConfigurableRbacAuthSvc] Role 'data_analyst' loaded with 4 direct scopes, 4 resolved scopes. DEBUG:solace_ai_connector:[ConfigurableRbacAuthSvc] Role 'standard_user' loaded with 1 direct scopes, 1 resolved scopes.   ","version":"Next","tagName":"h3"},{"title":"Configuration Files Not Found​","type":1,"pageTitle":"Setting Up RBAC","url":"/solace-agent-mesh/docs/documentation/enterprise/rbac-setup-guide#configuration-files-not-found","content":" If you see error messages about missing configuration files or the system uses default authorization behavior, the container cannot find your configuration files.  Check that the volume mount in your Docker run command is correct. The mount should map your host directory to /app in the container. Verify that you are using the correct path on your host system.  Ensure that file permissions allow the container user to read the files. On Linux systems, you might need to adjust file permissions:  chmod 644 sam-enterprise/config/auth/*.yaml   Check for typos in file names or paths. The file names are case-sensitive, and even small typos prevent Agent Mesh Enterprise from finding your configuration files.  ","version":"Next","tagName":"h3"},{"title":"Microsoft Graph Integration Not Working​","type":1,"pageTitle":"Setting Up RBAC","url":"/solace-agent-mesh/docs/documentation/enterprise/rbac-setup-guide#microsoft-graph-integration-not-working","content":" If users cannot authenticate when you use Microsoft Graph integration, or you see error messages related to Microsoft Graph in the logs, several issues might be causing the problem.  Verify that your Microsoft Graph credentials are correct. Double-check the tenant ID, client ID, and client secret against your Microsoft Entra ID application registration.  Check that environment variables are properly set in your Docker run command. You can verify environment variables inside the container:  docker exec -it sam-enterprise env | grep MS_GRAPH   Ensure that your Microsoft Graph application has the necessary permissions. The application needs permissions to read user and group information from Microsoft Entra ID.  Check network connectivity from the container to Microsoft Graph endpoints. The container must be able to reach graph.microsoft.com over HTTPS. Firewall rules or network policies might block this connectivity.  ","version":"Next","tagName":"h3"},{"title":"Debugging Authorization Issues​","type":1,"pageTitle":"Setting Up RBAC","url":"/solace-agent-mesh/docs/documentation/enterprise/rbac-setup-guide#debugging-authorization-issues","content":" When you need to investigate authorization problems in detail, follow these debugging steps:  Enable debug logging by adding a log level setting to your enterprise_config.yaml:  # Add to your enterprise_config.yaml log_level: "DEBUG"   Debug logging provides detailed information about authorization decisions, including which scopes the system checked and why it allowed or denied access.  Check the container logs for detailed information:  docker logs sam-enterprise   Look for log messages with the [EnterpriseConfigResolverImpl] or [ConfigurableRbacAuthSvc] prefixes. These messages show how Agent Mesh Enterprise loaded and processed your configuration.  Temporarily assign the user to an administrator role to verify whether the issue is permission-related. If the user can access features when assigned to an admin role, the problem is with the scopes assigned to their original role.  Inspect the mounted configuration files inside the container to verify that they contain the expected content:  docker exec -it sam-enterprise cat /app/config/auth/role-to-scope-definitions.yaml docker exec -it sam-enterprise cat /app/config/auth/user-to-role-assignments.yaml   This verification ensures that the files inside the container match your host files and that the volume mount is working correctly.  ","version":"Next","tagName":"h3"},{"title":"Getting Help​","type":1,"pageTitle":"Setting Up RBAC","url":"/solace-agent-mesh/docs/documentation/enterprise/rbac-setup-guide#getting-help","content":" If you continue to experience issues after following these troubleshooting steps, you can get additional help:  Check the Agent Mesh Enterprise documentation for updates or additional information about RBAC configuration.  Review the container logs for specific error messages. Error messages often include details about what went wrong and how to fix it.  Contact Solace support with details of your configuration and the issues you are experiencing. Include relevant log excerpts and describe the steps you have already taken to troubleshoot the problem.  ","version":"Next","tagName":"h3"},{"title":"Conclusion​","type":1,"pageTitle":"Setting Up RBAC","url":"/solace-agent-mesh/docs/documentation/enterprise/rbac-setup-guide#conclusion","content":" Setting up Role-Based Access Control in your Agent Mesh Enterprise Docker installation provides enhanced security and granular access control. This guide has walked you through understanding RBAC concepts, planning your configuration, creating configuration files, and troubleshooting common issues.  You now have the knowledge to configure RBAC to meet your organization's specific requirements while maintaining a secure and manageable environment. Remember to regularly review and update your RBAC configuration as your organization's needs evolve, and always follow security best practices when managing access control. ","version":"Next","tagName":"h2"},{"title":"Build Your Own Agent","type":0,"sectionRef":"#","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/custom-agent","content":"","keywords":"","version":"Next"},{"title":"Overview​","type":1,"pageTitle":"Build Your Own Agent","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/custom-agent#overview","content":" Our weather agent will demonstrate:  External API integration (OpenWeatherMap)Professional service layer architectureMultiple sophisticated toolsProper lifecycle managementError handling and validationArtifact creation and management  ","version":"Next","tagName":"h2"},{"title":"Prerequisites​","type":1,"pageTitle":"Build Your Own Agent","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/custom-agent#prerequisites","content":" Before starting this tutorial, make sure you have:  Read the Create Agent tutorialAn OpenWeatherMap API key (free at openweathermap.org)Basic understanding of Python async/awaitFamiliarity with HTTP APIs  ","version":"Next","tagName":"h2"},{"title":"Planning the Weather Agent​","type":1,"pageTitle":"Build Your Own Agent","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/custom-agent#planning-the-weather-agent","content":" Our weather agent will have the following capabilities:  Get Current Weather: Fetch current weather conditions for a specified locationGet Weather Forecast: Retrieve a multi-day weather forecastSave Weather Reports: Store weather data as artifacts  The agent will demonstrate:  External API integrationError handling and validationConfiguration managementArtifact creationResource lifecycle management  ","version":"Next","tagName":"h2"},{"title":"Step 1: Project Structure​","type":1,"pageTitle":"Build Your Own Agent","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/custom-agent#step-1-project-structure","content":" Run the following command to create a new custom agent:  sam add agent --gui   tip You can create an agent either by using the sam add agent command or by creating a new plugin of type agent, sam plugin create my-hello-agent --type agent. For information and recommendations about these options, see Agent or Plugin: Which To use?. For an example of plugin agents, see the Create Agents guide.  Follow the steps on the GUI to create a new agent named "Weather Agent". We can update the tools/skills section directly in the configuration file later.  Important Notice This tutorial is intentionally comprehensive to demonstrate the full flexibility and advanced features available in Agent Mesh agents. For most straightforward use cases, you only need a simple Python function and a corresponding reference in your YAML configuration file. Simple Weather Agent Example After going through the add agent wizard from sam add agent --gui, create the following file under src/weather_agent/tools.py directory: # src/weather_agent/tools.py import httpx from typing import Any, Dict, Optional from google.adk.tools import ToolContext from solace_ai_connector.common.log import log async def get_current_weather( location: str, units: str = "metric", tool_context: Optional[ToolContext] = None, tool_config: Optional[Dict[str, Any]] = None ) -> Dict[str, Any]: """ Get current weather conditions for a specified location. Args: location: City name, state, and country (for example, "New York, NY, US") units: Temperature units - "metric" (Celsius), "imperial" (Fahrenheit), or "kelvin" """ log.info("[GetCurrentWeather] Getting current weather for: %s", location) base_url = "https://api.openweathermap.org/data/2.5" api_key = tool_config.get("api_key") if tool_config else None url = f"{base_url}/weather" params = { "q": location, "appid": api_key, "units": units } try: # Fetch weather data async with httpx.AsyncClient() as client: response = await client.get(url, params=params) response.raise_for_status() weather_data = response.json() result = { "status": "success", "location": location, "units": units, "data": weather_data } return result except Exception as e: log.error(f"[GetCurrentWeather] Error getting weather: {e}") return { "status": "error", "message": f"Weather service error: {str(e)}" } async def get_weather_forecast( location: str, days: int = 5, units: str = "metric", tool_context: Optional[ToolContext] = None, tool_config: Optional[Dict[str, Any]] = None ) -> Dict[str, Any]: """ Get weather forecast for a specified location. Args: location: City name, state, and country days: Number of days for forecast (1-5) units: Temperature units """ log.info("[GetWeatherForecast] Getting %d-day forecast for: %s", days, location) base_url = "https://api.openweathermap.org/data/2.5" api_key = tool_config.get("api_key") if tool_config else None url = f"{base_url}/forecast" params = { "q": location, "appid": api_key, "units": units, "cnt": min(days * 8, 40) } try: # Fetch forecast data async with httpx.AsyncClient() as client: response = await client.get(url, params=params) response.raise_for_status() forecast_data = response.json() result = { "status": "success", "location": forecast_data["location"], "days": days, "units": units, "data": forecast_data } return result except Exception as e: log.error(f"[GetWeatherForecast] Error getting forecast: {e}") return { "status": "error", "message": f"Weather service error: {str(e)}" } And update the weather agent config file's tool section under configs/agent/weather-agent.yaml as follows: # Tools configuration tools: # Current weather tool - tool_type: python component_module: "src.weather_agent.tools" component_base_path: . function_name: "get_current_weather" tool_description: "Get current weather conditions for a specified location" tool_config: api_key: ${OPENWEATHER_API_KEY} # Weather forecast tool - tool_type: python component_module: "src.weather_agent.tools" function_name: "get_weather_forecast" component_base_path: . tool_description: "Get weather forecast for up to 5 days for a specified location" tool_config: api_key: ${OPENWEATHER_API_KEY} For better discoverability, update the agent card section in the same YAML file as follows: # Agent card agent_card: description: "Professional weather agent providing current conditions, forecasts, and weather comparisons" defaultInputModes: ["text"] defaultOutputModes: ["text"] skills: - id: "get_current_weather" name: "Get Current Weather" description: "Retrieve current weather conditions for any location worldwide" - id: "get_weather_forecast" name: "Get Weather Forecast" description: "Provide detailed weather forecasts up to 5 days ahead" To run the agent, you can continue following documentation from Step 6 of this tutorial. Other concepts mentioned in this page such as lifecycle, services, artifacts are just to showcase more advanced patterns.  Create the directory structure for the weather agent:  sam-project/ ├── src/ │ └── weather_agent/ │ ├── __init__.py │ ├── tools.py │ ├── lifecycle.py │ └── services/ │ ├── __init__.py │ └── weather_service.py ├── configs │ └── shared_config.yaml │ └── agents/ │ └── weather_agent.yaml ...   tip In Agent Mesh, you can create an agent either by using the sam add agent command or by creating a new plugin of type agent, sam plugin create your-agent --type agent. This tutorial uses the sam add agent command to create a new agent named "Weather Agent", for an example of creating a custom agent plugin, see the Create Agents tutorial.  ","version":"Next","tagName":"h2"},{"title":"Step 2: Weather Service Implementation​","type":1,"pageTitle":"Build Your Own Agent","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/custom-agent#step-2-weather-service-implementation","content":" First, create a service class to handle weather API interactions:  src/weather_agent/services/weather_service.py:  """ Weather service for interacting with external weather APIs. """ import aiohttp from typing import Dict, Any, Optional, List from datetime import datetime, timezone from solace_ai_connector.common.log import log class WeatherService: """Service for fetching weather data from external APIs.""" def __init__(self, api_key: str, base_url: str = "https://api.openweathermap.org/data/2.5"): self.api_key = api_key self.base_url = base_url self.session: Optional[aiohttp.ClientSession] = None self.log_identifier = "[WeatherService]" async def _get_session(self) -> aiohttp.ClientSession: """Get or create an HTTP session.""" if self.session is None or self.session.closed: self.session = aiohttp.ClientSession() return self.session async def close(self): """Close the HTTP session.""" if self.session and not self.session.closed: await self.session.close() log.info(f"{self.log_identifier} HTTP session closed") async def get_current_weather(self, location: str, units: str = "metric") -> Dict[str, Any]: """ Get current weather for a location. Args: location: City name, state code, and country code (for example, "London,UK") units: Temperature units (metric, imperial, kelvin) Returns: Dictionary containing current weather data """ log.info(f"{self.log_identifier} Fetching current weather for: {location}") session = await self._get_session() url = f"{self.base_url}/weather" params = { "q": location, "appid": self.api_key, "units": units } try: async with session.get(url, params=params) as response: if response.status == 200: data = await response.json() log.info(f"{self.log_identifier} Successfully fetched weather for {location}") return self._format_current_weather(data) elif response.status == 404: raise ValueError(f"Location '{location}' not found") else: error_data = await response.json() raise Exception(f"Weather API error: {error_data.get('message', 'Unknown error')}") except aiohttp.ClientError as e: log.error(f"{self.log_identifier} Network error fetching weather: {e}") raise Exception(f"Network error: {str(e)}") async def get_weather_forecast(self, location: str, days: int = 5, units: str = "metric") -> Dict[str, Any]: """ Get weather forecast for a location. Args: location: City name, state code, and country code days: Number of days for forecast (1-5) units: Temperature units Returns: Dictionary containing forecast data """ log.info(f"{self.log_identifier} Fetching {days}-day forecast for: {location}") session = await self._get_session() url = f"{self.base_url}/forecast" params = { "q": location, "appid": self.api_key, "units": units, "cnt": min(days * 8, 40) # API returns 3-hour intervals, max 40 entries } try: async with session.get(url, params=params) as response: if response.status == 200: data = await response.json() log.info(f"{self.log_identifier} Successfully fetched forecast for {location}") return self._format_forecast_data(data, days) elif response.status == 404: raise ValueError(f"Location '{location}' not found") else: error_data = await response.json() raise Exception(f"Weather API error: {error_data.get('message', 'Unknown error')}") except aiohttp.ClientError as e: log.error(f"{self.log_identifier} Network error fetching forecast: {e}") raise Exception(f"Network error: {str(e)}") def _format_current_weather(self, data: Dict) -> Dict[str, Any]: """Format current weather data for consistent output.""" return { "location": f"{data['name']}, {data['sys']['country']}", "temperature": data['main']['temp'], "feels_like": data['main']['feels_like'], "humidity": data['main']['humidity'], "pressure": data['main']['pressure'], "description": data['weather'][0]['description'].title(), "wind_speed": data.get('wind', {}).get('speed', 0), "wind_direction": data.get('wind', {}).get('deg', 0), "visibility": data.get('visibility', 0) / 1000, # Convert to km "timestamp": datetime.fromtimestamp(data['dt']).isoformat(), "sunrise": datetime.fromtimestamp(data['sys']['sunrise']).isoformat(), "sunset": datetime.fromtimestamp(data['sys']['sunset']).isoformat() } def _format_forecast_data(self, data: Dict, days: int) -> Dict[str, Any]: """Format forecast data for consistent output.""" forecasts = [] current_date = None daily_data = [] for item in data['list'][:days * 8]: forecast_date = datetime.fromtimestamp(item['dt']).date() if current_date != forecast_date: if daily_data: forecasts.append(self._aggregate_daily_forecast(daily_data)) current_date = forecast_date daily_data = [] daily_data.append(item) # Add the last day's data if daily_data: forecasts.append(self._aggregate_daily_forecast(daily_data)) return { "location": f"{data['city']['name']}, {data['city']['country']}", "forecasts": forecasts[:days] } def _aggregate_daily_forecast(self, daily_data: List[Dict]) -> Dict[str, Any]: """Aggregate 3-hour forecasts into daily summary.""" if not daily_data: return {} # Get temperatures for min/max calculation temps = [item['main']['temp'] for item in daily_data] # Use the forecast closest to noon for general conditions noon_forecast = min(daily_data, key=lambda x: abs( datetime.fromtimestamp(x['dt']).hour - 12 )) return { "date": datetime.fromtimestamp(daily_data[0]['dt']).date().isoformat(), "temperature_min": min(temps), "temperature_max": max(temps), "description": noon_forecast['weather'][0]['description'].title(), "humidity": noon_forecast['main']['humidity'], "wind_speed": noon_forecast.get('wind', {}).get('speed', 0), "precipitation_probability": noon_forecast.get('pop', 0) * 100 }   ","version":"Next","tagName":"h2"},{"title":"Step 3: Weather Tools Implementation​","type":1,"pageTitle":"Build Your Own Agent","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/custom-agent#step-3-weather-tools-implementation","content":" Now create the tool functions:  src/weather_agent/tools.py:  """ Weather agent tools for fetching and processing weather data. """ import json from typing import Any, Dict, Optional from datetime import datetime, timezone from google.adk.tools import ToolContext from solace_ai_connector.common.log import log from solace_agent_mesh.agent.utils.artifact_helpers import save_artifact_with_metadata async def get_current_weather( location: str, units: str = "metric", save_to_file: bool = False, tool_context: Optional[ToolContext] = None, tool_config: Optional[Dict[str, Any]] = None ) -> Dict[str, Any]: """ Get current weather conditions for a specified location. Args: location: City name, state, and country (for example, "New York, NY, US") units: Temperature units - "metric" (Celsius), "imperial" (Fahrenheit), or "kelvin" save_to_file: Whether to save the weather report as an artifact Returns: Dictionary containing current weather information """ log_identifier = "[GetCurrentWeather]" log.info(f"{log_identifier} Getting current weather for: {location}") if not tool_context: return { "status": "error", "message": "Tool context is required for weather operations" } try: # Get weather service from agent state host_component = getattr(tool_context._invocation_context, "agent", None) if host_component: host_component = getattr(host_component, "host_component", None) if not host_component: return { "status": "error", "message": "Could not access agent host component" } weather_service = host_component.get_agent_specific_state("weather_service") if not weather_service: return { "status": "error", "message": "Weather service not initialized" } # Fetch weather data weather_data = await weather_service.get_current_weather(location, units) # Create human-readable summary summary = _create_weather_summary(weather_data) result = { "status": "success", "location": weather_data["location"], "summary": summary, "data": weather_data } # Save to artifact if requested if save_to_file: artifact_result = await _save_weather_artifact( weather_data, f"current_weather_{location}", tool_context ) result["artifact"] = artifact_result log.info(f"{log_identifier} Successfully retrieved weather for {location}") return result except ValueError as e: log.warning(f"{log_identifier} Invalid location: {e}") return { "status": "error", "message": f"Location error: {str(e)}" } except Exception as e: log.error(f"{log_identifier} Error getting weather: {e}") return { "status": "error", "message": f"Weather service error: {str(e)}" } async def get_weather_forecast( location: str, days: int = 5, units: str = "metric", save_to_file: bool = False, tool_context: Optional[ToolContext] = None, tool_config: Optional[Dict[str, Any]] = None ) -> Dict[str, Any]: """ Get weather forecast for a specified location. Args: location: City name, state, and country days: Number of days for forecast (1-5) units: Temperature units save_to_file: Whether to save the forecast as an artifact Returns: Dictionary containing weather forecast information """ log_identifier = "[GetWeatherForecast]" log.info(f"{log_identifier} Getting {days}-day forecast for: {location}") if not tool_context: return { "status": "error", "message": "Tool context is required for weather operations" } # Validate days parameter if not 1 <= days <= 5: return { "status": "error", "message": "Days must be between 1 and 5" } try: # Get weather service from agent state host_component = getattr(tool_context._invocation_context, "agent", None) if host_component: host_component = getattr(host_component, "host_component", None) if not host_component: return { "status": "error", "message": "Could not access agent host component" } weather_service = host_component.get_agent_specific_state("weather_service") if not weather_service: return { "status": "error", "message": "Weather service not initialized" } # Fetch forecast data forecast_data = await weather_service.get_weather_forecast(location, days, units) # Create human-readable summary summary = _create_forecast_summary(forecast_data) result = { "status": "success", "location": forecast_data["location"], "summary": summary, "data": forecast_data } # Save to artifact if requested if save_to_file: artifact_result = await _save_weather_artifact( forecast_data, f"forecast_{location}_{days}day", tool_context ) result["artifact"] = artifact_result log.info(f"{log_identifier} Successfully retrieved forecast for {location}") return result except ValueError as e: log.warning(f"{log_identifier} Invalid location: {e}") return { "status": "error", "message": f"Location error: {str(e)}" } except Exception as e: log.error(f"{log_identifier} Error getting forecast: {e}") return { "status": "error", "message": f"Weather service error: {str(e)}" } def _create_weather_summary(weather_data: Dict[str, Any]) -> str: """Create a human-readable weather summary.""" temp_unit = "°C" # Assuming metric units for summary summary = f"Current weather in {weather_data['location']}:\\n" summary += f"• Temperature: {weather_data['temperature']}{temp_unit} (feels like {weather_data['feels_like']}{temp_unit})\\n" summary += f"• Conditions: {weather_data['description']}\\n" summary += f"• Humidity: {weather_data['humidity']}%\\n" summary += f"• Wind: {weather_data['wind_speed']} m/s\\n" summary += f"• Visibility: {weather_data['visibility']} km" return summary def _create_forecast_summary(forecast_data: Dict[str, Any]) -> str: """Create a human-readable forecast summary.""" summary = f"Weather forecast for {forecast_data['location']}:\\n\\n" for forecast in forecast_data['forecasts']: date = datetime.fromisoformat(forecast['date']).strftime('%A, %B %d') summary += f"• {date}: {forecast['description']}\\n" summary += f" High: {forecast['temperature_max']:.1f}°C, Low: {forecast['temperature_min']:.1f}°C\\n" if forecast['precipitation_probability'] > 0: summary += f" Precipitation: {forecast['precipitation_probability']:.0f}% chance\\n" summary += "\\n" return summary.strip() async def _save_weather_artifact( weather_data: Dict[str, Any], filename_base: str, tool_context: ToolContext ) -> Dict[str, Any]: """Save weather data as an artifact.""" try: # Prepare content content = json.dumps(weather_data, indent=2, default=str) timestamp = datetime.now(timezone.utc) filename = f"{filename_base}_{timestamp.strftime('%Y%m%d_%H%M%S')}.json" # Save artifact artifact_service = tool_context._invocation_context.artifact_service result = await save_artifact_with_metadata( artifact_service=artifact_service, app_name=tool_context._invocation_context.app_name, user_id=tool_context._invocation_context.user_id, session_id=tool_context._invocation_context.session.id, filename=filename, content_bytes=content.encode('utf-8'), mime_type="application/json", metadata_dict={ "description": "Weather data report", "source": "Weather Agent" }, timestamp=timestamp ) return { "filename": filename, "status": result.get("status", "success") } except Exception as e: log.error(f"[WeatherArtifact] Error saving artifact: {e}") return { "status": "error", "message": f"Failed to save artifact: {str(e)}" }   ","version":"Next","tagName":"h2"},{"title":"Step 4: Lifecycle Functions​","type":1,"pageTitle":"Build Your Own Agent","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/custom-agent#step-4-lifecycle-functions","content":" Create the lifecycle management:  src/weather_agent/lifecycle.py:  """ Lifecycle functions for the Weather Agent. """ from typing import Any import asyncio from pydantic import BaseModel, Field, SecretStr from solace_ai_connector.common.log import log from .services.weather_service import WeatherService class WeatherAgentInitConfig(BaseModel): """ Configuration model for Weather Agent initialization. """ api_key: SecretStr = Field(description="OpenWeatherMap API key") base_url: str = Field( default="https://api.openweathermap.org/data/2.5", description="Weather API base URL" ) startup_message: str = Field( default="Weather Agent is ready to provide weather information!", description="Message to log on startup" ) def initialize_weather_agent(host_component: Any, init_config: WeatherAgentInitConfig): """ Initialize the Weather Agent with weather service. 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 Weather Agent initialization...") try: # Initialize weather service weather_service = WeatherService( api_key=init_config.api_key.get_secret_value(), base_url=init_config.base_url ) # Store service in agent state host_component.set_agent_specific_state("weather_service", weather_service) # Log startup message log.info(f"{log_identifier} {init_config.startup_message}") # Store initialization metadata host_component.set_agent_specific_state("initialized_at", "2024-01-01T00:00:00Z") host_component.set_agent_specific_state("weather_requests_count", 0) log.info(f"{log_identifier} Weather Agent initialization completed successfully") except Exception as e: log.error(f"{log_identifier} Failed to initialize Weather Agent: {e}") raise def cleanup_weather_agent(host_component: Any): """ Clean up Weather Agent resources. Args: host_component: The agent host component """ log_identifier = f"[{host_component.agent_name}:cleanup]" log.info(f"{log_identifier} Starting Weather Agent cleanup...") async def cleanup_async(host_component: Any): try: # Get and close weather service weather_service = host_component.get_agent_specific_state("weather_service") if weather_service: await weather_service.close() log.info(f"{log_identifier} Weather service closed successfully") # Log final statistics request_count = host_component.get_agent_specific_state("weather_requests_count", 0) log.info(f"{log_identifier} Agent processed {request_count} weather requests during its lifetime") log.info(f"{log_identifier} Weather Agent cleanup completed") except Exception as e: log.error(f"{log_identifier} Error during cleanup: {e}") # run cleanup in the event loop loop = asyncio.get_event_loop() loop.run_until_complete(cleanup_async(host_component)) log.info(f"{log_identifier} Weather Agent cleanup completed successfully")   ","version":"Next","tagName":"h2"},{"title":"Step 5: Agent Configuration​","type":1,"pageTitle":"Build Your Own Agent","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/custom-agent#step-5-agent-configuration","content":" Create the comprehensive YAML configuration:  # Weather Agent Configuration log: stdout_log_level: INFO log_file_level: DEBUG log_file: weather-agent.log !include ../shared_config.yaml apps: - name: weather-agent # Broker configuration app_module: solace_agent_mesh.agent.sac.app broker: <<: *broker_connection app_config: namespace: "${NAMESPACE}" agent_name: "WeatherAgent" display_name: "Weather Information Agent" supports_streaming: true # LLM model configuration model: *general_model # Agent instructions instruction: | You are a professional weather agent that provides accurate, up-to-date weather information. Your capabilities include: 1. Getting current weather conditions for any location worldwide 2. Providing detailed weather forecasts up to 5 days 3. Saving weather reports as files for future reference Guidelines: - Always specify the location clearly when providing weather information - Include relevant details like temperature, conditions, humidity, and wind - Offer to save weather reports when providing detailed information - Be helpful in suggesting appropriate clothing or activities based on weather - If a location is ambiguous, ask for clarification (city, state/province, country) When users ask about weather, use the appropriate tools to fetch real-time data. Present information in a clear, organized manner that's easy to understand. # Lifecycle functions agent_init_function: module: "src.weather_agent.lifecycle" name: "initialize_weather_agent" base_path: . config: api_key: ${OPENWEATHER_API_KEY} base_url: "https://api.openweathermap.org/data/2.5" startup_message: "Weather Agent is ready to provide weather information!" agent_cleanup_function: module: "src.weather_agent.lifecycle" base_path: . name: "cleanup_weather_agent" # Tools configuration tools: # Current weather tool - tool_type: python component_module: "src.weather_agent.tools" component_base_path: . function_name: "get_current_weather" tool_description: "Get current weather conditions for a specified location" # Weather forecast tool - tool_type: python component_module: "src.weather_agent.tools" component_base_path: . function_name: "get_weather_forecast" tool_description: "Get weather forecast for up to 5 days for a specified location" # Built-in artifact tools for file operations - tool_type: builtin-group group_name: "artifact_management" session_service: *default_session_service artifact_service: *default_artifact_service artifact_handling_mode: "reference" enable_embed_resolution: true enable_artifact_content_instruction: true # Agent card agent_card: description: "Professional weather agent providing current conditions, forecasts, and weather comparisons" defaultInputModes: ["text"] defaultOutputModes: ["text", "file"] skills: - id: "get_current_weather" name: "Get Current Weather" description: "Retrieve current weather conditions for any location worldwide" - id: "get_weather_forecast" name: "Get Weather Forecast" description: "Provide detailed weather forecasts up to 5 days ahead" agent_card_publishing: interval_seconds: 30 agent_discovery: enabled: false inter_agent_communication: allow_list: [] request_timeout_seconds: 30   For more details on agent cards, see the Agent Card Concepts documentation.  ","version":"Next","tagName":"h2"},{"title":"Step 6: Environment Setup​","type":1,"pageTitle":"Build Your Own Agent","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/custom-agent#step-6-environment-setup","content":" Before running your weather agent, you'll need to:  Get an OpenWeatherMap API key: Sign up at OpenWeatherMapGet your free API key Set environment variables: export OPENWEATHER_API_KEY="your_api_key_here" # Other environment variables as needed   ","version":"Next","tagName":"h2"},{"title":"Step 7: Running the Agent​","type":1,"pageTitle":"Build Your Own Agent","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/custom-agent#step-7-running-the-agent","content":" To start the agent, it is preferred to build the plugin and then install it with your agent name. But for debugging or isolated development testing, you can run your agent from the src directory directly using the Agent Mesh CLI.  Start your weather agent for development purposes run:  sam run   To solely run the agent, use sam run configs/agents/weather_agent.yaml  ","version":"Next","tagName":"h2"},{"title":"Step 8: Testing the Weather Agent​","type":1,"pageTitle":"Build Your Own Agent","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/custom-agent#step-8-testing-the-weather-agent","content":" You can test your weather agent with these example requests:  Current Weather:  "What's the current weather in New York City?"  Weather Forecast:  "Can you give me a 5-day forecast for London, UK and save it to a file?"  Weather with File Save:  "Get the current weather for Tokyo, Japan and save the report"  ","version":"Next","tagName":"h2"},{"title":"Key Features Demonstrated​","type":1,"pageTitle":"Build Your Own Agent","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/custom-agent#key-features-demonstrated","content":" ","version":"Next","tagName":"h2"},{"title":"1. External API Integration​","type":1,"pageTitle":"Build Your Own Agent","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/custom-agent#1-external-api-integration","content":" Proper HTTP session managementError handling for network issuesAPI response transformation  ","version":"Next","tagName":"h3"},{"title":"2. Resource Management​","type":1,"pageTitle":"Build Your Own Agent","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/custom-agent#2-resource-management","content":" Lifecycle functions for initialization and cleanupShared service instances across tool callsProper resource disposal  ","version":"Next","tagName":"h3"},{"title":"3. Configuration Management​","type":1,"pageTitle":"Build Your Own Agent","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/custom-agent#3-configuration-management","content":" Pydantic models for type-safe configurationEnvironment variable integrationFlexible tool configuration  ","version":"Next","tagName":"h3"},{"title":"4. Error Handling​","type":1,"pageTitle":"Build Your Own Agent","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/custom-agent#4-error-handling","content":" Comprehensive exception handlingUser-friendly error messagesLogging for debugging  ","version":"Next","tagName":"h3"},{"title":"5. Artifact Management​","type":1,"pageTitle":"Build Your Own Agent","url":"/solace-agent-mesh/docs/documentation/developing/tutorials/custom-agent#5-artifact-management","content":" Saving structured data as filesMetadata enrichmentFile format handling ","version":"Next","tagName":"h3"},{"title":"Get Started with Agent Mesh","type":0,"sectionRef":"#","url":"/solace-agent-mesh/docs/documentation/getting-started/","content":"","keywords":"","version":"Next"},{"title":"Understanding Agent Mesh​","type":1,"pageTitle":"Get Started with Agent Mesh","url":"/solace-agent-mesh/docs/documentation/getting-started/#understanding-agent-mesh","content":" Before diving into implementation, it's helpful to understand what makes Agent Mesh unique. The framework combines the power of Google's Agent Development Kit with Solace's event-driven messaging platform, creating a robust foundation for multi-agent AI systems. To learn about the core concepts and architectural principles that drive the framework's design, see What is Agent Mesh?  The system's event-driven architecture enables true scalability and reliability, allowing agents to communicate asynchronously while maintaining loose coupling between components. For detailed insights into how these components work together to create a cohesive AI ecosystem, see Architecture Overview  To see how all the pieces fit together, you can explore the key building blocks that make up every Agent Mesh deployment. For more information, see Components Overview  ","version":"Next","tagName":"h2"},{"title":"Getting Started Quickly​","type":1,"pageTitle":"Get Started with Agent Mesh","url":"/solace-agent-mesh/docs/documentation/getting-started/#getting-started-quickly","content":" The fastest way to experience Agent Mesh is through our pre-configured Docker setup that gets you up and running with a working system in minutes. This approach lets you explore the framework's capabilities immediately without any installation or complex configuration. To get started right away, see Try Agent Mesh  Once you've explored the basic functionality and want to set up your own development environment, you'll need to install the CLI and framework tools. The installation process supports multiple approaches including pip, uv, and Docker, making it easy to integrate with your existing workflow. For complete setup instructions, see Installation  For those ready to build their own projects from scratch, comprehensive guidance is available for creating and configuring custom deployments with full control over your agent mesh. This approach provides the flexibility needed for serious development work and production environments. To learn about project creation and configuration, see Creating and Running an Agent Mesh Project  ","version":"Next","tagName":"h2"},{"title":"Building with Agent Mesh​","type":1,"pageTitle":"Get Started with Agent Mesh","url":"/solace-agent-mesh/docs/documentation/getting-started/#building-with-agent-mesh","content":" Creating effective AI systems requires understanding how to design and implement the right components for your use case. The framework provides several key building blocks that you can combine and customize to meet your specific needs.  Specialized AI components can perform specific tasks, access particular data sources, or integrate with external systems, with each agent bringing its own capabilities while participating in the larger collaborative ecosystem. To learn how to build these components, see Creating Agents  Interfaces that connect your agent mesh to the outside world enable integration through REST APIs, web interfaces, chat platforms, or custom integrations. For guidance on building these connection points, see Creating Gateways  Custom tools extend functionality beyond the built-in capabilities, allowing agents to interact with databases, APIs, file systems, or any other resources your applications require. To understand how to add these extensions, see Creating Python Tools  ","version":"Next","tagName":"h2"},{"title":"Core Components​","type":1,"pageTitle":"Get Started with Agent Mesh","url":"/solace-agent-mesh/docs/documentation/getting-started/#core-components","content":" Agent Mesh is built around several fundamental components that work together to create intelligent, collaborative systems. Understanding these components helps you design effective solutions and troubleshoot issues when they arise.  The intelligent workers of your system are powered by AI models and equipped with specialized tools, capable of analyzing data, generating content, making decisions, and delegating tasks to other agents when needed. For more information, see Agents  Bridges between your agent mesh and external systems translate requests from users, applications, or other systems into the standardized communication protocol that agents understand. To learn about these interface components, see Gateways  The conductor of your agent symphony breaks down complex requests into manageable tasks and coordinates the work of multiple agents to achieve sophisticated outcomes. For details about this coordination system, see Orchestrator  A powerful extension mechanism lets you add new capabilities to your system without modifying core components, making it easy to integrate with existing tools and services. To understand how to extend your system, see Plugins  Comprehensive command-line tools manage your projects from initial setup through deployment and ongoing maintenance. For information about these development tools, see CLI  ","version":"Next","tagName":"h2"},{"title":"Advanced Capabilities​","type":1,"pageTitle":"Get Started with Agent Mesh","url":"/solace-agent-mesh/docs/documentation/getting-started/#advanced-capabilities","content":" As your AI systems grow in complexity and scale, Agent Mesh provides advanced features to support enterprise deployments and sophisticated use cases.  Various approaches for running Agent Mesh in production range from single-machine setups to distributed enterprise deployments across multiple environments. To explore your deployment options, see Deployment Options  Real-time monitoring capabilities help you track performance metrics and debug issues when they occur, with the framework's event-driven architecture providing natural visibility into all system interactions. For guidance on system monitoring, see Observability  Organizations with specific security and governance requirements can leverage advanced capabilities including role-based access control, single sign-on integration, and enterprise-grade security features. To learn about these advanced features, see Enterprise Features  ","version":"Next","tagName":"h2"},{"title":"Learning Through Examples​","type":1,"pageTitle":"Get Started with Agent Mesh","url":"/solace-agent-mesh/docs/documentation/getting-started/#learning-through-examples","content":" Practical tutorials help you understand how to apply Agent Mesh to real-world scenarios. These hands-on guides walk you through building complete solutions that demonstrate the framework's capabilities.  Creating agents that can query databases and provide intelligent responses based on your organization's data demonstrates how to integrate with existing data sources. For a complete walkthrough, see SQL Database Integration  Building a gateway that lets users interact with your agent mesh directly through Slack brings AI capabilities into existing workflows and communication platforms. To learn how to set this up, see Slack Integration  Creating a specialized agent from scratch, including tool integration and configuration, shows you the complete development process for custom components. For step-by-step guidance, see Custom Agent Tutorial  Incorporating Model Context Protocol servers into your agent mesh extends capabilities through standardized integrations with external tools and services. To understand this integration approach, see MCP Integration  ","version":"Next","tagName":"h2"},{"title":"Additional Resources​","type":1,"pageTitle":"Get Started with Agent Mesh","url":"/solace-agent-mesh/docs/documentation/getting-started/#additional-resources","content":" Beyond the core documentation, several resources can help you get the most out of Agent Mesh. The latest source code, example configurations, and community discussions are available in the GitHub repository  Pre-built functionality for common use cases provides tested integrations that you can incorporate into your own projects. You can find these extensions in the official plugins repository  Participating in the project's development is possible through reporting issues, suggesting improvements, or contributing code. To learn how you can get involved, see the Contributing Guide ","version":"Next","tagName":"h2"},{"title":"Architecture Overview","type":0,"sectionRef":"#","url":"/solace-agent-mesh/docs/documentation/getting-started/architecture","content":"","keywords":"","version":"Next"},{"title":"Architectural Principles​","type":1,"pageTitle":"Architecture Overview","url":"/solace-agent-mesh/docs/documentation/getting-started/architecture#architectural-principles","content":" The design of Agent Mesh is founded on several key architectural principles:  Event-Driven Architecture (EDA): All interactions between major components are asynchronous and mediated by the Solace event broker. This eliminates direct dependencies, allowing components to be developed, deployed, and scaled independently.Component Decoupling: Gateways, Agent Hosts, and other services communicate through standardized A2A protocol messages over the event mesh. They do not require knowledge of each other's network location, implementation language, or internal logic.Scalability and Resilience: The architecture supports horizontal scaling of Agent Hosts and Gateways. The Solace event broker provides fault tolerance and guaranteed message delivery, ensuring system resilience even if individual components fail or are restarted.  ","version":"Next","tagName":"h2"},{"title":"System Components​","type":1,"pageTitle":"Architecture Overview","url":"/solace-agent-mesh/docs/documentation/getting-started/architecture#system-components","content":" The architecture comprises several distinct types of components that interact through the Solace Event Broker. External systems connect through gateways, which translate requests into the A2A protocol, while agent hosts run individual agents that can communicate with each other and access backend services like LLMs and databases. For detailed information about each component, see Components. The architecture diagram below illustrates how these components work together.    ","version":"Next","tagName":"h2"},{"title":"Solace Event Broker​","type":1,"pageTitle":"Architecture Overview","url":"/solace-agent-mesh/docs/documentation/getting-started/architecture#solace-event-broker","content":" The Solace Event Broker serves as the central messaging fabric that enables all communication within the agent mesh. It routes A2A protocol messages between components using a hierarchical topic structure, supporting patterns like request/reply, streaming updates, and publish/subscribe for agent discovery. For more information about the event broker, see (solace.com)[https://solace.com/products/event-broker/]  ","version":"Next","tagName":"h3"},{"title":"Gateways​","type":1,"pageTitle":"Architecture Overview","url":"/solace-agent-mesh/docs/documentation/getting-started/architecture#gateways","content":" Gateways are SAC applications that act as bridges between external systems and the agent mesh. They handle protocol translation, converting external protocols (such as HTTP, WebSockets, or Slack RTM) into the standardized A2A protocol and vice versa. Gateways also manage authentication and authorization, authenticate incoming requests, and use a pluggable AuthorizationService to retrieve user permission scopes. Additionally, they manage external user sessions and map them to A2A task lifecycles, while handling asynchronous responses and status updates from agents.  The Gateway Development Kit (GDK) provides BaseGatewayApp and BaseGatewayComponent classes that abstract common gateway logic, including A2A protocol handling, agent discovery, and late-stage embed resolution. For more information about gateways, see Gateways.  ","version":"Next","tagName":"h3"},{"title":"Agent Hosts and Agents​","type":1,"pageTitle":"Architecture Overview","url":"/solace-agent-mesh/docs/documentation/getting-started/architecture#agent-hosts-and-agents","content":" An Agent Host is a SAC application (SamAgentApp) that hosts a single ADK-based agent. It manages the lifecycle of the ADK Runner and LlmAgent, handles A2A protocol translation between incoming requests and ADK Task objects, enforces permission scopes by filtering available tools, and initializes ADK services like the ArtifactService and MemoryService.  An agent is the logical entity within an Agent Host that performs tasks. Each agent is defined by its configuration, which includes instructions that define its persona and capabilities, LLM configuration specifying which large language model to use, and a toolset containing built-in tools, custom Python functions, or MCP Toolsets. For more information about agents, see Agents.  ","version":"Next","tagName":"h3"},{"title":"Key Architectural Flows​","type":1,"pageTitle":"Architecture Overview","url":"/solace-agent-mesh/docs/documentation/getting-started/architecture#key-architectural-flows","content":" The following flows illustrate how data moves through the system and demonstrate the relationships between components in the event-driven architecture.  ","version":"Next","tagName":"h2"},{"title":"User Task Processing Flow​","type":1,"pageTitle":"Architecture Overview","url":"/solace-agent-mesh/docs/documentation/getting-started/architecture#user-task-processing-flow","content":" When you submit a request through any gateway, the system processes it through several stages:  An external client sends a request to a gatewayThe gateway authenticates the request, retrieves your permission scopes via its AuthorizationService, and translates the request into an A2A task message, including the scopes in the Solace message's user propertiesThe gateway publishes the message to the target agent's request topic on the Solace BrokerThe corresponding Agent Host receives the message, with the SamAgentComponent extracting the scopes and initiating an ADK taskThe ADK LlmAgent processes the task, with a before_model_callback filtering the available tools based on your scopes before invoking the LLMAs the agent executes, the SamAgentComponent translates ADK events into A2A status and artifact update messages, publishing them to the originating gateway's status topicThe gateway receives these streaming updates, performs any necessary late-stage processing (such as resolving artifact_content embeds), and forwards them to youUpon completion, the Agent Host sends a final A2A response message to the gateway, which delivers it to you  ","version":"Next","tagName":"h3"},{"title":"Agent-to-Agent Delegation Flow​","type":1,"pageTitle":"Architecture Overview","url":"/solace-agent-mesh/docs/documentation/getting-started/architecture#agent-to-agent-delegation-flow","content":" Agents can delegate subtasks to other agents while maintaining security context:  Agent A, while processing a task, determines that a subtask should be delegated to Agent BAgent A uses its PeerAgentTool to construct a new A2A task request for Agent B, propagating the original user's permission scopes to maintain the security contextThe request is published to Agent B's request topicAgent B's Host receives and processes the subtask, enforcing the propagated scopes on its own toolsetAgent B sends status updates and a final response to topics designated by Agent AAgent A receives the results and incorporates them into its ongoing task  ","version":"Next","tagName":"h3"},{"title":"Agent Discovery Flow​","type":1,"pageTitle":"Architecture Overview","url":"/solace-agent-mesh/docs/documentation/getting-started/architecture#agent-discovery-flow","content":" The system automatically discovers available agents through a publish-subscribe mechanism:  On startup and periodically, each Agent Host publishes an AgentCard (a JSON document describing its agent's capabilities) to a well-known discovery topicGateways and other Agent Hosts subscribe to this topicUpon receiving an AgentCard, components update their local AgentRegistry, making them aware of available agents for user selection (at gateways) or peer delegation (at agents)  ","version":"Next","tagName":"h3"},{"title":"A2A Protocol and Topic Structure​","type":1,"pageTitle":"Architecture Overview","url":"/solace-agent-mesh/docs/documentation/getting-started/architecture#a2a-protocol-and-topic-structure","content":" The A2A protocol is based on JSON-RPC 2.0 and defines the message formats for all interactions between components. Communication is routed via a hierarchical topic structure on the Solace event broker, which allows for precise, point-to-point routing in a decoupled, asynchronous environment.  Purpose\tTopic PatternAgent Discovery\t{namespace}/a2a/v1/discovery/agentcards Task Requests\t{namespace}/a2a/v1/agent/request/{target_agent_name} Status Updates\t{namespace}/a2a/v1/gateway/status/{gateway_id}/{task_id} Final Responses\t{namespace}/a2a/v1/gateway/response/{gateway_id}/{task_id} Peer Delegation Status\t{namespace}/a2a/v1/agent/status/{delegating_agent_name}/{sub_task_id} Peer Delegation Response\t{namespace}/a2a/v1/agent/response/{delegating_agent_name}/{sub_task_id}  For more information about the CLI tools that help you work with these components, see CLI. To learn about extending the system with custom functionality, see Plugins. ","version":"Next","tagName":"h2"},{"title":"Enabling SSO","type":0,"sectionRef":"#","url":"/solace-agent-mesh/docs/documentation/enterprise/single-sign-on","content":"","keywords":"","version":"Next"},{"title":"Overview​","type":1,"pageTitle":"Enabling SSO","url":"/solace-agent-mesh/docs/documentation/enterprise/single-sign-on#overview","content":" Single Sign-On (SSO) enables users to authenticate with Agent Mesh Enterprise using their existing organizational credentials through OAuth2 providers such as Azure, Google, Auth0, Okta, or Keycloak. This integration eliminates the need for separate login credentials and leverages your organization's existing identity management infrastructure.  This guide walks you through configuring and enabling SSO for Agent Mesh Enterprise running in Docker. You will create configuration files, set up your OAuth2 provider, and launch the container with the appropriate environment variables.  ","version":"Next","tagName":"h2"},{"title":"Prerequisites​","type":1,"pageTitle":"Enabling SSO","url":"/solace-agent-mesh/docs/documentation/enterprise/single-sign-on#prerequisites","content":" Before you begin, ensure you have:  A running instance of your chosen OAuth2 provider (Azure, Google, Auth0, Okta, Keycloak, or another OIDC-compliant provider)Client credentials (client ID and client secret) from your OAuth2 providerA Named Docker Volume for storing configuration filesAccess to the Agent Mesh Enterprise Docker image  ","version":"Next","tagName":"h2"},{"title":"Understanding the SSO Architecture​","type":1,"pageTitle":"Enabling SSO","url":"/solace-agent-mesh/docs/documentation/enterprise/single-sign-on#understanding-the-sso-architecture","content":" Agent Mesh Enterprise uses a two-component architecture for SSO:  The main UI server (default port 8000) handles user interactions and serves the web interfaceThe OAuth2 authentication service (default port 9000) manages the authentication flow with your identity provider  When a user attempts to access the UI, they are redirected to your OAuth2 provider for authentication. After successful authentication, the provider redirects back to the application with an authorization code, which is then exchanged for access tokens. This separation of concerns keeps authentication logic isolated from the main application.  ","version":"Next","tagName":"h2"},{"title":"Step 1: Create Configuration Files​","type":1,"pageTitle":"Enabling SSO","url":"/solace-agent-mesh/docs/documentation/enterprise/single-sign-on#step-1-create-configuration-files","content":" You need to create two YAML configuration files in your Named Docker Volume. These files define how the OAuth2 service operates and which identity provider it connects to.  ","version":"Next","tagName":"h2"},{"title":"Create oauth2_server.yaml​","type":1,"pageTitle":"Enabling SSO","url":"/solace-agent-mesh/docs/documentation/enterprise/single-sign-on#create-oauth2_serveryaml","content":" The oauth2_server.yaml file configures the OAuth2 authentication service as a component within Agent Mesh Enterprise. This file tells the system to start the OAuth2 service and specifies where to find its detailed configuration.  Create a file named oauth2_server.yaml in the root directory of your Named Docker Volume with the following content:  --- # Example gateway configuration with OAuth2 service integration # This shows how to configure a gateway to use the OAuth2 authentication service log: stdout_log_level: INFO log_file_level: DEBUG log_file: oauth_server.log !include ../shared_config.yaml shared_config: # OAuth2 service configuration - oauth2_config: &oauth2_config enabled: true config_file: "configs/sso_vol/oauth2_config.yaml" host: ${OAUTH2_HOST, localhost} port: ${OAUTH2_PORT, 9000} ssl_cert: "" # Optional: path to SSL certificate ssl_key: "" # Optional: path to SSL private key flows: # Initialize OAuth2 service - name: oauth2_service components: - component_name: oauth2_auth_service component_module: solace_agent_mesh_enterprise.components.oauth2_component component_config: <<: *oauth2_config   This configuration accomplishes several things:  It sets up logging for the OAuth2 service, directing detailed debug information to oauth_server.logIt references the shared_config.yaml file, which contains common configuration used across multiple componentsIt defines the OAuth2 service configuration, including where to find the provider-specific settings (oauth2_config.yaml)It specifies the host and port where the OAuth2 service will listen for requestsIt creates a flow that initializes the OAuth2 authentication service component  The ${OAUTH2_HOST, localhost} syntax means the service will use the OAUTH2_HOST environment variable if provided, otherwise it defaults to localhost. This pattern allows you to override configuration values at runtime without modifying the file.  ","version":"Next","tagName":"h3"},{"title":"Create oauth2_config.yaml​","type":1,"pageTitle":"Enabling SSO","url":"/solace-agent-mesh/docs/documentation/enterprise/single-sign-on#create-oauth2_configyaml","content":" The oauth2_config.yaml file contains provider-specific configuration for your chosen OAuth2 identity provider. This is where you specify which provider to use and provide the necessary credentials and endpoints.  Create a file named oauth2_config.yaml in the same directory with the following content:  --- # OAuth2 Service Configuration # This file configures the OAuth2 authentication service that supports multiple providers # All providers now use the unified OIDC approach with automatic endpoint discovery # Enable or disable the OAuth2 service enabled: ${OAUTH2_ENABLED:false} # Development mode - enables insecure transport and relaxed token scope for local development # Set OAUTH2_DEV_MODE=true for local development (NEVER use in production!) development_mode: ${OAUTH2_DEV_MODE:false} # OAuth2 providers configuration # All providers now use the unified OIDCProvider with automatic endpoint discovery providers: # Google OAuth2 provider # google: # # OIDC issuer URL - endpoints will be discovered automatically # issuer: "https://accounts.google.com" # client_id: ${GOOGLE_CLIENT_ID} # client_secret: ${GOOGLE_CLIENT_SECRET} # redirect_uri: ${GOOGLE_REDIRECT_URI:http://localhost:8080/callback} # scope: "openid email profile" # Azure/Microsoft OAuth2 provider azure: # Azure OIDC issuer URL includes tenant ID issuer: https://login.microsoftonline.com/${AZURE_TENANT_ID}/v2.0 client_id: ${AZURE_CLIENT_ID} client_secret: ${AZURE_CLIENT_SECRET} redirect_uri: ${AZURE_REDIRECT_URI:http://localhost:8080/callback} scope: "openid email profile offline_access" # Auth0 OAuth2 provider # auth0: # # Auth0 issuer URL # issuer: ${AUTH0_ISSUER:https://your-domain.auth0.com/} # client_id: ${AUTH0_CLIENT_ID} # client_secret: ${AUTH0_CLIENT_SECRET} # redirect_uri: ${AUTH0_REDIRECT_URI:http://localhost:8080/callback} # scope: "openid email profile" # # Optional: Auth0 audience for API access # audience: ${AUTH0_AUDIENCE:} # # Okta OAuth2 provider (example) # okta: # issuer: ${OKTA_ISSUER:https://your-okta-domain.okta.com/oauth2/default} # client_id: ${OKTA_CLIENT_ID} # client_secret: ${OKTA_CLIENT_SECRET} # redirect_uri: ${OKTA_REDIRECT_URI:http://localhost:8080/callback} # scope: "openid email profile" # # Keycloak OAuth2 provider (example) # keycloak: # issuer: ${KEYCLOAK_ISSUER:https://your-keycloak.com/auth/realms/your-realm} # client_id: ${KEYCLOAK_CLIENT_ID} # client_secret: ${KEYCLOAK_CLIENT_SECRET} # redirect_uri: ${KEYCLOAK_REDIRECT_URI:http://localhost:8080/callback} # scope: "openid email profile" # # Generic OIDC provider (for any standard OIDC-compliant provider) # custom_oidc: # # Just provide the issuer URL and the service will discover all endpoints # issuer: ${CUSTOM_OIDC_ISSUER:https://your-provider.com} # client_id: ${CUSTOM_OIDC_CLIENT_ID} # client_secret: ${CUSTOM_OIDC_CLIENT_SECRET} # redirect_uri: ${CUSTOM_OIDC_REDIRECT_URI:http://localhost:8080/callback} # scope: "openid email profile" # Logging configuration logging: level: ${OAUTH2_LOG_LEVEL:INFO} # Session configuration session: # Session timeout in seconds (default: 1 hour) timeout: ${OAUTH2_SESSION_TIMEOUT:3600} # Security configuration security: # CORS settings cors: enabled: ${OAUTH2_CORS_ENABLED:true} origins: ${OAUTH2_CORS_ORIGINS:*} # Rate limiting rate_limit: enabled: ${OAUTH2_RATE_LIMIT_ENABLED:true} requests_per_minute: ${OAUTH2_RATE_LIMIT_RPM:60}   This configuration file provides several important features:  The enabled setting controls whether the OAuth2 service is active. You can enable it by setting the OAUTH2_ENABLED environment variable to true.  The development_mode setting is crucial for local testing. When enabled, it allows HTTP connections (instead of requiring HTTPS) and relaxes token validation. You must disable this in production environments to maintain security.  The providers section defines multiple OAuth2 providers. By default, Azure is uncommented and active. To use a different provider, comment out the Azure section and uncomment your chosen provider. Each provider requires:  An issuer URL that points to the OAuth2 provider's discovery endpointA client_id and client_secret obtained from your provider's application registrationA redirect_uri where the provider sends users after authenticationA scope that defines what user information the application can access  The system uses OpenID Connect (OIDC) discovery, which means it automatically finds the authorization, token, and userinfo endpoints from the issuer URL. This simplifies configuration because you only need to provide the base issuer URL rather than individual endpoint URLs.  The session configuration determines how long authenticated sessions remain valid. The default of 3600 seconds (1 hour) balances security with user convenience.  The security section configures Cross-Origin Resource Sharing (CORS) and rate limiting. CORS allows the web UI to communicate with the OAuth2 service from different origins, while rate limiting prevents abuse by restricting the number of authentication requests per minute.  ","version":"Next","tagName":"h3"},{"title":"Update Your WebUI Gateway​","type":1,"pageTitle":"Enabling SSO","url":"/solace-agent-mesh/docs/documentation/enterprise/single-sign-on#update-your-webui-gateway","content":" Update your WebUI Gateway to configure login as follows:  # Auth-related (placeholders, functionality depends on backend implementation) frontend_auth_login_url: ${FRONTEND_AUTH_LOGIN_URL} frontend_use_authorization: ${FRONTEND_USE_AUTHORIZATION} frontend_redirect_url: ${FRONTEND_REDIRECT_URL, ""} external_auth_callback_uri: ${EXTERNAL_AUTH_CALLBACK} external_auth_service_url: ${EXTERNAL_AUTH_SERVICE_URL} external_auth_provider: ${EXTERNAL_AUTH_PROVIDER}   Your final WebUI Gateway yaml configuration should look like this:  WebUI Gateway SSO Enabled webUI.yaml log: stdout_log_level: INFO log_file_level: INFO log_file: webui_app.log !include ../shared_config.yaml apps: - name: a2a_webui_app app_base_path: . app_module: solace_agent_mesh.gateway.http_sse.app broker: <<: *broker_connection app_config: namespace: ${NAMESPACE} session_secret_key: "${SESSION_SECRET_KEY}" artifact_service: *default_artifact_service session_service: type: "sql" database_url: ${WEB_UI_GATEWAY_DATABASE_URL, sqlite:///webui_gateway.db} default_behavior: "PERSISTENT" gateway_id: ${WEBUI_GATEWAY_ID} fastapi_host: ${FASTAPI_HOST} fastapi_port: ${FASTAPI_PORT} cors_allowed_origins: - "http://localhost:3000" - "http://127.0.0.1:3000" enable_embed_resolution: ${ENABLE_EMBED_RESOLUTION} # Enable late-stage resolution gateway_artifact_content_limit_bytes: ${GATEWAY_ARTIFACT_LIMIT_BYTES, 10000000} # Max size for late-stage embeds sse_max_queue_size: ${SSE_MAX_QUEUE_SIZE, 200} # Max size of SSE connection queues system_purpose: > The system is an AI Chatbot with agentic capabilities. It will use the agents available to provide information, reasoning and general assistance for the users in this system. **Always return useful artifacts and files that you create to the user.** Provide a status update before each tool call. Your external name is Agent Mesh. response_format: > Responses should be clear, concise, and professionally toned. Format responses to the user in Markdown using appropriate formatting. # --- Frontend Config Passthrough --- frontend_welcome_message: ${FRONTEND_WELCOME_MESSAGE} frontend_bot_name: ${FRONTEND_BOT_NAME} frontend_collect_feedback: ${FRONTEND_COLLECT_FEEDBACK} # Auth-related (placeholders, functionality depends on backend implementation) frontend_auth_login_url: ${FRONTEND_AUTH_LOGIN_URL} frontend_use_authorization: ${FRONTEND_USE_AUTHORIZATION} frontend_redirect_url: ${FRONTEND_REDIRECT_URL, ""} external_auth_callback_uri: ${EXTERNAL_AUTH_CALLBACK} external_auth_service_url: ${EXTERNAL_AUTH_SERVICE_URL} external_auth_provider: ${EXTERNAL_AUTH_PROVIDER}   ","version":"Next","tagName":"h3"},{"title":"Step 2: Configure Your OAuth2 Provider​","type":1,"pageTitle":"Enabling SSO","url":"/solace-agent-mesh/docs/documentation/enterprise/single-sign-on#step-2-configure-your-oauth2-provider","content":" Before running the Docker container, you need to register an application with your chosen OAuth2 provider and obtain the necessary credentials.  ","version":"Next","tagName":"h2"},{"title":"For Azure (Microsoft Entra ID)​","type":1,"pageTitle":"Enabling SSO","url":"/solace-agent-mesh/docs/documentation/enterprise/single-sign-on#for-azure-microsoft-entra-id","content":" Navigate to the Azure Portal and go to Microsoft Entra ID (formerly Azure Active Directory)Select "App registrations" and create a new registrationNote the Application (client) ID and Directory (tenant) IDCreate a client secret under "Certificates & secrets"Add a redirect URI pointing to your callback endpoint (for example, http://localhost:8000/api/v1/auth/callback)Grant the necessary API permissions (typically Microsoft Graph with User.Read)  ","version":"Next","tagName":"h3"},{"title":"For Google​","type":1,"pageTitle":"Enabling SSO","url":"/solace-agent-mesh/docs/documentation/enterprise/single-sign-on#for-google","content":" Go to the Google Cloud Console and create a new project or select an existing oneEnable the Google+ APICreate OAuth2 credentials under "APIs & Services" > "Credentials"Configure the authorized redirect URIsNote the client ID and client secret  ","version":"Next","tagName":"h3"},{"title":"For Other Providers​","type":1,"pageTitle":"Enabling SSO","url":"/solace-agent-mesh/docs/documentation/enterprise/single-sign-on#for-other-providers","content":" Consult your provider's documentation for application registration procedures. You will need to obtain a client ID, client secret, and configure the redirect URI to point to your Agent Mesh Enterprise callback endpoint.  ","version":"Next","tagName":"h3"},{"title":"Step 3: Launch the Docker Container​","type":1,"pageTitle":"Enabling SSO","url":"/solace-agent-mesh/docs/documentation/enterprise/single-sign-on#step-3-launch-the-docker-container","content":" With your configuration files in place and provider credentials obtained, you can now launch the Agent Mesh Enterprise container with SSO enabled.  The following example demonstrates a production deployment using Azure as the OAuth2 provider:  tip You may need to include --platform linux/amd64 depending on the host machine you're using.  docker run -itd -p 8000:8000 -p 9000:9000 \\ -e LLM_SERVICE_API_KEY="<YOUR_LLM_TOKEN>" \\ -e LLM_SERVICE_ENDPOINT="<YOUR_LLM_SERVICE_ENDPOINT>" \\ -e LLM_SERVICE_PLANNING_MODEL_NAME="<YOUR_MODEL_NAME>" \\ -e LLM_SERVICE_GENERAL_MODEL_NAME="<YOUR_MODEL_NAME>" \\ -e NAMESPACE="<YOUR_NAMESPACE>" \\ -e SOLACE_DEV_MODE="false" \\ -e SOLACE_BROKER_URL="<YOUR_BROKER_URL>" \\ -e SOLACE_BROKER_VPN="<YOUR_BROKER_VPN>" \\ -e SOLACE_BROKER_USERNAME="<YOUR_BROKER_USERNAME>" \\ -e SOLACE_BROKER_PASSWORD="<YOUR_BROKER_PASSWORD>" \\ -e FASTAPI_HOST="0.0.0.0" \\ -e FASTAPI_PORT="8000" \\ -e AZURE_TENANT_ID="xxxxxxxxx-xxxxxx-xxxxxxxx-xxxxxxxxxx" \\ -e AZURE_CLIENT_ID="xxxxxxxxx-xxxxxx-xxxxxxxx-xxxxxxxxxx" \\ -e AZURE_CLIENT_SECRET="xxxxxxxxx-xxxxxx-xxxxxxxx-xxxxxxxxxx" \\ -e OAUTH2_ENABLED="true" \\ -e OAUTH2_LOG_LEVEL="DEBUG" \\ -e OAUTH2_DEV_MODE="true" \\ -e OAUTH2_HOST="0.0.0.0" \\ -e OAUTH2_PORT="9000" \\ -e FRONTEND_USE_AUTHORIZATION="true" \\ -e FRONTEND_REDIRECT_URL="http://localhost:8000" \\ -e FRONTEND_AUTH_LOGIN_URL="http://localhost:8000/api/v1/auth/login" \\ -e EXTERNAL_AUTH_SERVICE_URL="http://localhost:9000" \\ -e EXTERNAL_AUTH_PROVIDER="azure" \\ -e EXTERNAL_AUTH_CALLBACK="http://localhost:8000/api/v1/auth/callback" \\ -v <YOUR_NAMED_DOCKER_VOLUME>:/app/config/sso_vol/ \\ --name sam-ent-prod-sso \\ solace-agent-mesh-enterprise:<tag> run config/sso_vol/oauth2_server.yaml config/webui_backend.yaml config/a2a_orchestrator.yaml config/a2a_agents.yaml   This command starts the container in detached mode with interactive terminal support. The -p flags expose both the main UI port (8000) and the OAuth2 service port (9000) to the host machine. The volume mount makes your configuration files available inside the container at the expected location.  After the container starts successfully, you can access the Agent Mesh Enterprise UI at http://localhost:8000. When you navigate to this URL, the system will redirect you to your OAuth2 provider's login page for authentication.  ","version":"Next","tagName":"h2"},{"title":"Understanding the Environment Variables​","type":1,"pageTitle":"Enabling SSO","url":"/solace-agent-mesh/docs/documentation/enterprise/single-sign-on#understanding-the-environment-variables","content":" The Docker run command includes numerous environment variables that control different aspects of the SSO configuration. Understanding these variables helps you customize the deployment for your specific environment.  ","version":"Next","tagName":"h2"},{"title":"Core Application Settings​","type":1,"pageTitle":"Enabling SSO","url":"/solace-agent-mesh/docs/documentation/enterprise/single-sign-on#core-application-settings","content":" These variables configure the main Agent Mesh Enterprise application:  -e FASTAPI_HOST="0.0.0.0" \\ -e FASTAPI_PORT="8000" \\   The FASTAPI_HOST setting determines which network interfaces the main UI server binds to. Using "0.0.0.0" allows external access to the container, which is necessary for production deployments. The FASTAPI_PORT specifies which port the UI listens on inside the container.  ","version":"Next","tagName":"h3"},{"title":"Frontend Authentication Settings​","type":1,"pageTitle":"Enabling SSO","url":"/solace-agent-mesh/docs/documentation/enterprise/single-sign-on#frontend-authentication-settings","content":" These variables control how the web UI handles authentication:  -e FRONTEND_USE_AUTHORIZATION="true" \\   Setting FRONTEND_USE_AUTHORIZATION to "true" enables SSO processing on the frontend. When enabled, the UI will redirect unauthenticated users to the login flow instead of allowing direct access.  -e FRONTEND_REDIRECT_URL="http://localhost:8000" \\   The FRONTEND_REDIRECT_URL specifies the main URL of your UI. In production, this would be your public-facing domain (for example, https://www.example.com). The system uses this URL to construct proper redirect chains during authentication.  -e FRONTEND_AUTH_LOGIN_URL="http://localhost:8000/api/v1/auth/login" \\   The FRONTEND_AUTH_LOGIN_URL tells the frontend where to send users who need to authenticate. This endpoint initiates the OAuth2 flow by redirecting to your identity provider.  ","version":"Next","tagName":"h3"},{"title":"OAuth2 Service Settings​","type":1,"pageTitle":"Enabling SSO","url":"/solace-agent-mesh/docs/documentation/enterprise/single-sign-on#oauth2-service-settings","content":" These variables configure the OAuth2 authentication service itself:  -e OAUTH2_ENABLED="true" \\ -e OAUTH2_LOG_LEVEL="DEBUG" \\   The OAUTH2_ENABLED variable activates the OAuth2 service. Setting OAUTH2_LOG_LEVEL to "DEBUG" provides detailed logging information, which is helpful during initial setup and troubleshooting. You can change this to "INFO" or "WARNING" in production to reduce log verbosity.  -e OAUTH2_HOST="0.0.0.0" \\ -e OAUTH2_PORT="9000" \\   These variables specify where the OAuth2 authentication service listens for requests. Using "0.0.0.0" as the host allows external access to the container, which is necessary because the OAuth2 provider needs to reach the callback endpoint. The port must match the port mapping in your Docker run command.  -e OAUTH2_DEV_MODE="true" \\   The OAUTH2_DEV_MODE setting controls whether the OAuth2 service operates in development mode. When set to "true", the service sets these internal environment variables:  OAUTHLIB_RELAX_TOKEN_SCOPE="1" OAUTHLIB_INSECURE_TRANSPORT="1"   These settings allow HTTP connections (instead of requiring HTTPS) and relax token scope validation. This is convenient for local development and testing, but you must set OAUTH2_DEV_MODE to "false" in production environments to maintain security. Production deployments should always use HTTPS with valid SSL certificates.  ","version":"Next","tagName":"h3"},{"title":"Provider-Specific Credentials​","type":1,"pageTitle":"Enabling SSO","url":"/solace-agent-mesh/docs/documentation/enterprise/single-sign-on#provider-specific-credentials","content":" These variables provide the credentials obtained from your OAuth2 provider. The example shows Azure configuration:  -e AZURE_TENANT_ID="xxxxxxxxx-xxxxxx-xxxxxxxx-xxxxxxxxxx" \\ -e AZURE_CLIENT_ID="xxxxxxxxx-xxxxxx-xxxxxxxx-xxxxxxxxxx" \\ -e AZURE_CLIENT_SECRET="xxxxxxxxx-xxxxxx-xxxxxxxx-xxxxxxxxxx" \\   The required variables depend on which provider you configured in oauth2_config.yaml. For Google, you would use GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET. For Auth0, you would use AUTH0_CLIENT_ID, AUTH0_CLIENT_SECRET, and AUTH0_ISSUER. Refer to the oauth2_config.yaml file to identify the exact variable names for your chosen provider.  ","version":"Next","tagName":"h3"},{"title":"External Authentication Configuration​","type":1,"pageTitle":"Enabling SSO","url":"/solace-agent-mesh/docs/documentation/enterprise/single-sign-on#external-authentication-configuration","content":" These variables connect the main UI to the OAuth2 service:  -e EXTERNAL_AUTH_SERVICE_URL="http://localhost:9000" \\ -e EXTERNAL_AUTH_PROVIDER="azure" \\   The EXTERNAL_AUTH_SERVICE_URL specifies the public URL where the OAuth2 service can be reached. This must be accessible from outside the Docker container because your OAuth2 provider will redirect users to this service. The EXTERNAL_AUTH_PROVIDER must match one of the provider names defined in your oauth2_config.yaml file (in this example, "azure").  -e EXTERNAL_AUTH_CALLBACK="http://localhost:8000/api/v1/auth/callback" \\   The EXTERNAL_AUTH_CALLBACK is the URL where your OAuth2 provider redirects users after successful authentication. This URL must be registered with your OAuth2 provider as an authorized redirect URI. In production, this would be your public domain followed by the callback path (for example, https://www.example.com/api/v1/auth/callback).  ","version":"Next","tagName":"h3"},{"title":"Port Mapping and Volume Mount​","type":1,"pageTitle":"Enabling SSO","url":"/solace-agent-mesh/docs/documentation/enterprise/single-sign-on#port-mapping-and-volume-mount","content":" Two additional configuration elements are essential for SSO to function:  -p 8000:8000 -p 9000:9000 \\   Both the main UI port (8000) and the OAuth2 service port (9000) must be mapped to the host machine. This allows external access to both services, which is necessary for the authentication flow to complete successfully.  -v <YOUR_NAMED_DOCKER_VOLUME>:/app/config/sso_vol/ \\   The volume mount makes your OAuth2 configuration files available inside the container at the expected location. Replace <YOUR_NAMED_DOCKER_VOLUME> with the path to your Named Docker Volume containing the oauth2_server.yaml and oauth2_config.yaml files.  ","version":"Next","tagName":"h3"},{"title":"Verifying Your SSO Configuration​","type":1,"pageTitle":"Enabling SSO","url":"/solace-agent-mesh/docs/documentation/enterprise/single-sign-on#verifying-your-sso-configuration","content":" After starting the container, you can verify that SSO is working correctly:  Navigate to http://localhost:8000 in your web browserYou should be automatically redirected to your OAuth2 provider's login pageAfter entering your credentials, you should be redirected back to the Agent Mesh Enterprise UICheck the container logs for any authentication errors: docker logs sam-ent-prod-sso  If you encounter issues, check that:  Your OAuth2 provider credentials are correctThe redirect URI in your provider's configuration matches the EXTERNAL_AUTH_CALLBACK valueBoth ports (8000 and 9000) are accessible from your networkThe configuration files are properly mounted in the container  ","version":"Next","tagName":"h2"},{"title":"Security Considerations for Production​","type":1,"pageTitle":"Enabling SSO","url":"/solace-agent-mesh/docs/documentation/enterprise/single-sign-on#security-considerations-for-production","content":" When deploying SSO in a production environment, follow these security best practices:  Set OAUTH2_DEV_MODE to "false" to disable insecure transport and enforce proper token validation. This ensures that all OAuth2 communication uses HTTPS with valid SSL certificates.  Use HTTPS for all URLs (FRONTEND_REDIRECT_URL, FRONTEND_AUTH_LOGIN_URL, EXTERNAL_AUTH_SERVICE_URL, and EXTERNAL_AUTH_CALLBACK). Configure SSL certificates using the ssl_cert and ssl_key parameters in oauth2_server.yaml.  Restrict CORS origins by setting OAUTH2_CORS_ORIGINS to your specific domain instead of using the wildcard "*". This prevents unauthorized websites from making requests to your authentication service.  Regularly rotate your OAuth2 client secrets and update the corresponding environment variables. Store sensitive credentials securely using Docker secrets or a secrets management service rather than passing them directly in the command line.  Configure appropriate session timeouts based on your security requirements. Shorter timeouts increase security but may inconvenience users who need to reauthenticate more frequently.  Monitor authentication logs for suspicious activity and failed login attempts. The OAuth2 service logs all authentication events, which you can review for security auditing. ","version":"Next","tagName":"h2"},{"title":"What is Agent Mesh?","type":0,"sectionRef":"#","url":"/solace-agent-mesh/docs/documentation/getting-started/introduction","content":"","keywords":"","version":"Next"},{"title":"Real-World Applications​","type":1,"pageTitle":"What is Agent Mesh?","url":"/solace-agent-mesh/docs/documentation/getting-started/introduction#real-world-applications","content":" Agent Mesh is already solving real problems across industries:  Intelligent Enterprise Automation: Customer service systems that route inquiries to specialized agents and data processing pipelines that transform, analyze, and enrich information from multiple sources. AI Task Specialization: Image analysis workflows with visual processing and text generation specialists, and document processing systems that extract, summarize, and translate content through coordinated agents. Human-AI Collaboration: Complex task execution that keeps humans in the loop for approvals, clarifications, or expert guidance via web or chat interfaces. Data-Driven Intelligence: Agents that query databases, transform results, and generate visualizations based on natural language requests or system events.  ","version":"Next","tagName":"h2"},{"title":"For Developers​","type":1,"pageTitle":"What is Agent Mesh?","url":"/solace-agent-mesh/docs/documentation/getting-started/introduction#for-developers","content":" Agent Mesh is an agentic framework that provides several key technical advantages:  Complete Observability: Because all communication flows through the event broker, you can monitor and debug the entire system in real-timeFlexible Integration: Built-in support for common enterprise systems and AI frameworksPlugin Architecture: Easily extend the system with custom agents and gatewaysDeveloper Tools: Comprehensive CLI and debugging utilities  ","version":"Next","tagName":"h2"},{"title":"Getting Started​","type":1,"pageTitle":"What is Agent Mesh?","url":"/solace-agent-mesh/docs/documentation/getting-started/introduction#getting-started","content":" Whether you're building a proof-of-concept or planning a production deployment, Agent Mesh provides the foundation you need. For more information, see:  Getting Started: For an overview of Agent Mesh and what you can find in this documentation.Installation: For installing and setting up Agent Mesh.Quick Start: For creating a project, building, and running Agent Mesh.Component Overview: Understanding the parts of Agent Mesh. ","version":"Next","tagName":"h2"},{"title":"Try Agent Mesh","type":0,"sectionRef":"#","url":"/solace-agent-mesh/docs/documentation/getting-started/try-agent-mesh","content":"","keywords":"","version":"Next"},{"title":"Prerequisites​","type":1,"pageTitle":"Try Agent Mesh","url":"/solace-agent-mesh/docs/documentation/getting-started/try-agent-mesh#prerequisites","content":" Before you begin, ensure you have:  Docker (or Podman) installed on your systemAn AI provider and API key from any major provider. For best results, use a state-of-the-art AI model like Anthropic Claude Sonnet 4, Google Gemini 2.5 Pro, or OpenAI GPT-4  Ready for Development? If you're ready to set up a full development environment with complete project control, skip this quick trial and go directly to the installation guide followed by the project setup guide.  ","version":"Next","tagName":"h2"},{"title":"Run the Docker Image​","type":1,"pageTitle":"Try Agent Mesh","url":"/solace-agent-mesh/docs/documentation/getting-started/try-agent-mesh#run-the-docker-image","content":" The simplest way to try Agent Mesh is to run the pre-configured agents that come with the Docker image. This approach gets you up and running immediately without any project setup.  docker run --rm -it -p 8000:8000 --platform linux/amd64 --env-file <your-env-file-path> solace/solace-agent-mesh:latest   You can provide the required environment variables using an environment file as shown above, or pass them directly as command-line arguments using the -e flag, as shown in the section that follows. The preset configuration includes several ready-to-use agents that demonstrate the capabilities of Agent Mesh. You can find a complete list of all available preset agents in the Agent Mesh GitHub repository.  If your host system architecture is not linux/amd64, you must add the --platform linux/amd64 flag when you run the container.  ","version":"Next","tagName":"h2"},{"title":"Using Custom Agents (Optional)​","type":1,"pageTitle":"Try Agent Mesh","url":"/solace-agent-mesh/docs/documentation/getting-started/try-agent-mesh#using-custom-agents-optional","content":" Although the preset agents are sufficient for exploring the capabilities of Agent Mesh, you can optionally run your own custom agents if you already have them configured. However, for any serious development work, we recommend following the complete project setup guide instead of this Docker shortcut.  If you do want to test a custom agent quickly, you can mount your agent configuration into the container using the following command:  docker run --rm -it --platform linux/amd64 -p 8000:8000 -v $(pwd):/app \\ -e LLM_SERVICE_ENDPOINT=<your-llm-endpoint> \\ -e LLM_SERVICE_API_KEY=<your-llm-api-key> \\ -e LLM_SERVICE_PLANNING_MODEL_NAME=<your-llm-planning-model-name> \\ -e LLM_SERVICE_GENERAL_MODEL_NAME=<your-llm-general-model-name> \\ solace/solace-agent-mesh:latest run /preset/agents/basic /app/my-agent   Replace /app/my-agent with the path to your agent YAML configuration file. Note that you still need either a shared_config.yaml file or hard-coded settings in your agent configuration. The /preset/agents/basic path runs only the required agents, while /preset/agents loads all available agents. This example includes only the minimum required environment variables.  ","version":"Next","tagName":"h3"},{"title":"Explore the Web Interface​","type":1,"pageTitle":"Try Agent Mesh","url":"/solace-agent-mesh/docs/documentation/getting-started/try-agent-mesh#explore-the-web-interface","content":" After the Docker container starts successfully, you can interact with Agent Mesh through the web interface. Navigate to http://localhost:8000 in your web browser and try commands like "Suggest some good outdoor activities in London given the season and current weather conditions."  The web interface provides an intuitive way to interact with your agents and explore the capabilities of Agent Mesh without any additional setup.  ","version":"Next","tagName":"h2"},{"title":"Next Steps​","type":1,"pageTitle":"Try Agent Mesh","url":"/solace-agent-mesh/docs/documentation/getting-started/try-agent-mesh#next-steps","content":" Once you've explored the basic functionality, you can learn more about agents and how they work, explore gateways and different interface options, or try using plugins to extend functionality.  For serious development work, set up a complete project by following the installation guide and then the project setup guide, which provides full control over your configuration and is suitable for development, testing, and production environments. ","version":"Next","tagName":"h2"},{"title":"Installing and Configuring Agent Mesh","type":0,"sectionRef":"#","url":"/solace-agent-mesh/docs/documentation/installing-and-configuring/","content":"","keywords":"","version":"Next"},{"title":"Setting Up Your Environment​","type":1,"pageTitle":"Installing and Configuring Agent Mesh","url":"/solace-agent-mesh/docs/documentation/installing-and-configuring/#setting-up-your-environment","content":" Before you can build and deploy agent meshes, you need to install the Agent Mesh framework and CLI tools on your system. The installation process includes setting up Python dependencies, configuring virtual environments, and verifying that all components work correctly. You can choose between local installation using pip or uv, or use the pre-built Docker image for containerized deployments. For complete installation instructions and system requirements, see Installing Agent Mesh.  ","version":"Next","tagName":"h2"},{"title":"Creating Your First Project​","type":1,"pageTitle":"Installing and Configuring Agent Mesh","url":"/solace-agent-mesh/docs/documentation/installing-and-configuring/#creating-your-first-project","content":" Once you have Agent Mesh installed, you'll create and run your first project to establish a working agent mesh system. This process involves initializing a new project directory, configuring basic settings through either a web interface or command-line prompts, and starting your agent mesh with the built-in orchestrator and web gateway. The project creation process also handles essential setup tasks like environment variable configuration and component initialization. For step-by-step guidance on project creation and execution, see Creating and Running an Agent Mesh Project.  ","version":"Next","tagName":"h2"},{"title":"Managing System Configuration​","type":1,"pageTitle":"Installing and Configuring Agent Mesh","url":"/solace-agent-mesh/docs/documentation/installing-and-configuring/#managing-system-configuration","content":" Effective configuration management ensures consistent behavior across all components in your agent mesh deployment. The shared configuration system allows you to define common settings such as broker connections, service definitions, and environment-specific parameters in centralized files that multiple agents and gateways can reference. You'll learn how to structure configuration files, use YAML anchors for reusable settings, and manage multiple configuration environments for development, testing, and production scenarios. For comprehensive configuration guidance and best practices, see Configuring Agent Mesh.  ","version":"Next","tagName":"h2"},{"title":"Connecting Language Models​","type":1,"pageTitle":"Installing and Configuring Agent Mesh","url":"/solace-agent-mesh/docs/documentation/installing-and-configuring/#connecting-language-models","content":" Language models provide the intelligence that powers your agents' reasoning, decision-making, and natural language capabilities. The system supports numerous LLM providers through a unified configuration interface, allowing you to connect with OpenAI, Anthropic, Google, Amazon, and many other services. You'll configure model-specific settings, manage API credentials securely through environment variables, and optimize model behavior for different use cases such as planning, general tasks, and specialized functions like image generation or audio transcription. For detailed provider configurations and security settings, see Configuration Settings for LLMs. ","version":"Next","tagName":"h2"},{"title":"Prerequisites","type":0,"sectionRef":"#","url":"/solace-agent-mesh/docs/documentation/installing-and-configuring/installation","content":"","keywords":"","version":"Next"},{"title":"Install Agent Mesh​","type":1,"pageTitle":"Prerequisites","url":"/solace-agent-mesh/docs/documentation/installing-and-configuring/installation#install-agent-mesh","content":" The following command installs Agent Mesh CLI in your environment:  Using pip pip install solace-agent-mesh   Using uv uv pip install solace-agent-mesh   Docker Alternative Alternatively, you can use our pre-built Docker image to run Agent Mesh CLI commands without a local Python installation. This approach is useful for quick tasks or CI/CD environments. The pre-built Docker image is configured with group solaceai and non-root user solaceai. To verify the installation using Docker, run: docker run --rm solace/solace-agent-mesh:latest --version This command pulls the latest image (if not already present) and executes solace-agent-mesh --version inside the container. The --rm flag ensures the container is removed after execution. If your host OS architecture is not linux/amd64, you need to add --platform linux/amd64 when running the container. For more complex operations like building a project, you need to mount your project directory into the container. See the Quick Start guide for examples.  Browser Requirement The Mermaid agent requires a browser with headless mode support to render diagrams. Use playwright to install the browser dependencies. If you are using the Docker image, this is already included. To install the browser dependencies, run: playwright install   ","version":"Next","tagName":"h2"},{"title":"Verify Installation​","type":1,"pageTitle":"Prerequisites","url":"/solace-agent-mesh/docs/documentation/installing-and-configuring/installation#verify-installation","content":" Run the following Agent Mesh CLI command to verify your installation:  solace-agent-mesh --version   tip For easier access to the Agent Mesh CLI, you can also use the sam alias: sam --version   To get a list of available commands, run:  solace-agent-mesh --help   ","version":"Next","tagName":"h2"},{"title":"Next Steps​","type":1,"pageTitle":"Prerequisites","url":"/solace-agent-mesh/docs/documentation/installing-and-configuring/installation#next-steps","content":" After successful installation, choose your next step based on your goals:  For Quick Exploration: If you want to try SAM's capabilities immediately without project setup, use the Docker quick start to explore SAM with minimal configuration.  For Development Work: If you're ready to build a complete project with full control over configuration, proceed directly to the project setup guide.  To Learn More: Explore the system components by reading about agents and gateways. ","version":"Next","tagName":"h2"},{"title":"Configuring Agent Mesh","type":0,"sectionRef":"#","url":"/solace-agent-mesh/docs/documentation/installing-and-configuring/configurations","content":"","keywords":"","version":"Next"},{"title":"Understanding Shared Configuration​","type":1,"pageTitle":"Configuring Agent Mesh","url":"/solace-agent-mesh/docs/documentation/installing-and-configuring/configurations#understanding-shared-configuration","content":" All agents and gateways require access to a shared_config object. You can provide configuration in the following ways:  hard-coding configuration values directly within your agent or gateway YAML files. This method works for simple setups or quick prototyping, but it becomes unwieldy as your deployment grows.using the !include directive to reference a centralized configuration file. This approach promotes consistency and simplifies maintenance across your entire project.  When a plugin is installed, it may come with hard-coded default values. It is a best practice to remove this section and use !include to point to the centralized shared_config file. This ensures that all components are using the same base configuration.  ","version":"Next","tagName":"h2"},{"title":"Managing Multiple Shared Configuration Files​","type":1,"pageTitle":"Configuring Agent Mesh","url":"/solace-agent-mesh/docs/documentation/installing-and-configuring/configurations#managing-multiple-shared-configuration-files","content":" You can use multiple shared configuration files to manage different environments or setups (e.g., for different cloud providers), as follows:  The filename must always begin with shared_config, followed by any descriptive suffix that helps identify the configuration's purpose. Examples include shared_config_aws.yaml for Amazon Web Services deployments or shared_config_production.yaml for production environments. This naming convention ensures the system can locate and process these files correctly. You can organize configuration files into subdirectories to further improve project structure. For instance, you might place files in configs/agents/shared_config.yaml or environments/dev/shared_config_dev.yaml. When you use subdirectories, you must update the !include path in your agent or gateway configurations to reflect the correct file location.  The configuration file uses YAML anchors (&anchor_name) to create reusable configuration blocks, which can then be referenced in agent configuration files.  ","version":"Next","tagName":"h3"},{"title":"Configuration Structure​","type":1,"pageTitle":"Configuring Agent Mesh","url":"/solace-agent-mesh/docs/documentation/installing-and-configuring/configurations#configuration-structure","content":" The following example shows the structure of the shared_config.yaml configuration file:  shared_config: - broker_connection: &broker_connection dev_mode: ${SOLACE_DEV_MODE, false} broker_url: ${SOLACE_BROKER_URL, ws://localhost:8008} broker_username: ${SOLACE_BROKER_USERNAME, default} broker_password: ${SOLACE_BROKER_PASSWORD, default} broker_vpn: ${SOLACE_BROKER_VPN, default} temporary_queue: ${USE_TEMPORARY_QUEUES, true} # Ensure high enough limits if many agents are running # max_connection_retries: -1 # Retry forever - models: planning: &planning_model # This dictionary structure tells ADK to use the LiteLlm wrapper. # 'model' uses the specific model identifier your endpoint expects. model: ${LLM_SERVICE_PLANNING_MODEL_NAME} # Use env var for model name # 'api_base' tells LiteLLM where to send the request. api_base: ${LLM_SERVICE_ENDPOINT} # Use env var for endpoint URL # 'api_key' provides authentication. api_key: ${LLM_SERVICE_API_KEY} # Use env var for API key # Enable parallel tool calls for planning model parallel_tool_calls: true # Prompt Caching Strategy cache_strategy: "5m" # none, 5m, 1h # max_tokens: ${MAX_TOKENS, 16000} # Set a reasonable max token limit for planning # temperature: 0.1 # Lower temperature for more deterministic planning general: &general_model # This dictionary structure tells ADK to use the LiteLlm wrapper. # 'model' uses the specific model identifier your endpoint expects. model: ${LLM_SERVICE_GENERAL_MODEL_NAME} # Use env var for model name # 'api_base' tells LiteLLM where to send the request. api_base: ${LLM_SERVICE_ENDPOINT} # Use env var for endpoint URL # 'api_key' provides authentication. api_key: ${LLM_SERVICE_API_KEY} # Use env var for API key # ... (similar structure) - services: # Default session service configuration session_service: &default_session_service type: "memory" default_behavior: "PERSISTENT" # Default artifact service configuration artifact_service: &default_artifact_service type: "filesystem" base_path: "/tmp/samv2" artifact_scope: namespace # Default data tools configuration data_tools_config: &default_data_tools_config sqlite_memory_threshold_mb: 100 max_result_preview_rows: 50 max_result_preview_bytes: 4096   ","version":"Next","tagName":"h2"},{"title":"Event Broker Connection​","type":1,"pageTitle":"Configuring Agent Mesh","url":"/solace-agent-mesh/docs/documentation/installing-and-configuring/configurations#event-broker-connection","content":" The broker_connection section configures the connection to the Solace event broker. The connection parameters are described in the following table:  Parameter\tEnvironment Variable\tDescription\tDefaultdev_mode\tSOLACE_DEV_MODE\tWhen set to true, uses an in-memory broker for testing.\tfalse broker_url\tSOLACE_BROKER_URL\tThe URL of the Solace event broker.\tws://localhost:8008 broker_username\tSOLACE_BROKER_USERNAME\tThe username for authenticating with the event broker.\tdefault broker_password\tSOLACE_BROKER_PASSWORD\tThe password for authenticating with the event broker.\tdefault broker_vpn\tSOLACE_BROKER_VPN\tThe Message VPN to connect to on the event broker.\tdefault temporary_queue\tUSE_TEMPORARY_QUEUES\tWhether to use temporary queues for communication. If false, a durable queue will be created.\ttrue max_connection_retries\tMAX_CONNECTION_RETRIES\tThe maximum number of times to retry connecting to the event broker if the connection fails. A value of -1 means retry forever.\t-1  tip If you need to configure multiple brokers, you can do so by adding additional entries under shared_config with a unique name (For example, broker_connection_eu: &broker_connection_eu or broker_connection_us: &broker_connection_us). Reference these configurations in your agent files using the appropriate anchor, such as <<: *broker_connection_eu.  info Setting the temporary_queue parameter to true (default) will use temporary endpoints for A2A communication. Temporary queues are automatically created and deleted by the broker, which simplifies management and reduces the need for manual cleanup. However, it does not allow for multiple client connections to the same queue, which may be a limitation in some scenarios where you're running multiple instances of the same agent or a new instance needs to be started while an old instance is still running. If you set temporary_queue to false, the system will create a durable queue for the client. Durable queues persist beyond the lifetime of the client connection, allowing multiple clients to connect to the same queue and ensuring that messages are not lost if the client disconnects. However, this requires manual management of the queues, including cleanup of unused queues. Check the Setting up Queue Templates section for guidance on configuring queue templates to manage message TTL.  ","version":"Next","tagName":"h2"},{"title":"LLM Configuration​","type":1,"pageTitle":"Configuring Agent Mesh","url":"/solace-agent-mesh/docs/documentation/installing-and-configuring/configurations#llm-configuration","content":" The models section configures the various Large Language Models and other generative models that power your agents' intelligence. This configuration leverages the LiteLLM library, which provides a standardized interface for interacting with different model providers, simplifying the process of switching between or combining multiple AI services.  ","version":"Next","tagName":"h2"},{"title":"Model Configuration Parameters​","type":1,"pageTitle":"Configuring Agent Mesh","url":"/solace-agent-mesh/docs/documentation/installing-and-configuring/configurations#model-configuration-parameters","content":" Each model configuration requires specific parameters that tell the system how to communicate with the model provider. The model parameter specifies the exact model identifier in the format expected by your provider, such as openai/gpt-4 or anthropic/claude-3-opus-20240229. The API base URL points to your provider's endpoint, but some providers use default endpoints that don't require explicit specification.  Authentication typically requires an API key, but some providers use alternative authentication mechanisms. Additional parameters control model behavior, such as enabling parallel tool calls for models that support this feature, setting maximum token limits to control response length and costs, and adjusting temperature values to influence response creativity versus determinism.  Parameter\tEnvironment Variable\tDescriptionmodel\tLLM_SERVICE_<MODEL_NAME>_MODEL_NAME\tThe specific model identifier that the endpoint expects in the format of provider/model (e.g., openai/gpt-4, anthropic/claude-3-opus-20240229). api_base\tLLM_SERVICE_ENDPOINT\tThe base URL of the LLM provider's API endpoint. api_key\tLLM_SERVICE_API_KEY\tThe API key for authenticating with the service. parallel_tool_calls Enable parallel tool calls for the model. cache_strategy Set the prompt caching strategy (one of: none, 5m, 1h). For more details check LLM Configuration page. max_tokens\tMAX_TOKENS\tSet a reasonable max token limit for the model. temperature\tTEMPERATURE\tLower temperature for more deterministic planning.  For Google's Gemini models, you can use a simplified configuration approach that references the model directly:  model: gemini-2.5-pro   For detailed information about configuring Gemini models and setting up the required environment variables, see the Gemini model documentation.  ","version":"Next","tagName":"h3"},{"title":"Predefined Model Types​","type":1,"pageTitle":"Configuring Agent Mesh","url":"/solace-agent-mesh/docs/documentation/installing-and-configuring/configurations#predefined-model-types","content":" The shared_config.yaml configuration file defines predefined model types that serve as aliases for specific use cases. These aliases allow you to reference models by their intended purpose rather than their technical specifications, making your agent configurations more readable and maintainable. The model types are as follows:  planning: Used by agents for planning and decision-making. It's configured for deterministic outputs (temperature: 0.1) and can use tools in parallel.general: A general-purpose model for various tasks.image_gen: A model for generating images.image_describe: A model for describing the content of images.audio_transcription: A model for transcribing audio files.report_gen: A model specialized for generating reports.multimodal: A simple string reference to a multimodal model (e.g., "gemini-1.5-flash-latest").  You can define any number of models in this section and reference them in your agent configurations. The system uses only the planning and general models by default; you don't need to configure the specialized models unless your agents specifically require those capabilities.  For information about configuring different LLM providers and SSL/TLS security settings, see Configuring LLMs.  ","version":"Next","tagName":"h3"},{"title":"Service Configuration​","type":1,"pageTitle":"Configuring Agent Mesh","url":"/solace-agent-mesh/docs/documentation/installing-and-configuring/configurations#service-configuration","content":" The services section in shared_config.yaml is used to configure various services that are available to agents. These services handle concerns such as session persistence, artifact storage, and data processing optimization.  ","version":"Next","tagName":"h2"},{"title":"Session Service​","type":1,"pageTitle":"Configuring Agent Mesh","url":"/solace-agent-mesh/docs/documentation/installing-and-configuring/configurations#session-service","content":" The session service manages conversation history and context persistence across agent interactions. This service determines whether agents remember previous conversations and how long that memory persists.  Parameter\tOptions\tDescription\tDefaulttype\tmemory, sql, vertex_rag\tConfiguration for ADK Session Service\tmemory default_behavior\tPERSISTENT, RUN_BASED\tThe default behavior of keeping the session history\tPERSISTENT  tip Although the default session service type is memory, both Orchestrator Agent and Web UI gateway use sql as their session service to allow for persistent sessions.  ","version":"Next","tagName":"h3"},{"title":"Artifact Service​","type":1,"pageTitle":"Configuring Agent Mesh","url":"/solace-agent-mesh/docs/documentation/installing-and-configuring/configurations#artifact-service","content":" The artifact_service is responsible for managing artifacts, which are files or data generated by agents, such as generated documents, processed data files, and intermediate results.  Parameter\tOptions\tDescription\tDefaulttype\tmemory, gcs, filesystem\tService type for artifact storage. Use memory for in-memory, gcs for Google Cloud Storage, or filesystem for local file storage.\tmemory base_path\tlocal path\tBase directory path for storing artifacts. Required only if type is filesystem.\t(none) bucket_name\tbucket name\tGoogle Cloud Storage bucket name. Required only if type is gcs.\t(none) artifact_scope\tnamespace, app\tScope for artifact sharing. namespace: shared by all components in the namespace. app: isolated by agent/gateway name. Must be consistent for all components in the same process.\tnamespace artifact_scope_value\tcustom scope id\tCustom identifier for artifact scope. Required if artifact_scope is set to a custom value.\t(none)  ","version":"Next","tagName":"h3"},{"title":"Data Tools Configuration​","type":1,"pageTitle":"Configuring Agent Mesh","url":"/solace-agent-mesh/docs/documentation/installing-and-configuring/configurations#data-tools-configuration","content":" The data tools configuration optimizes how agents handle data analysis and processing tasks. These settings balance performance, memory usage, and user experience when agents work with databases and large datasets.  The SQLite memory threshold determines when the system switches from disk-based to memory-based database operations. Lower thresholds favor memory usage for better performance although consume more system RAM. Higher thresholds reduce memory pressure although may slow database operations.  Result preview settings control how much data agents display when showing query results or data samples. These limits prevent overwhelming users with massive datasets while ensuring they see enough information to understand the results.  Parameter\tType\tDescription\tDefaultsqlite_memory_threshold_mb\tinteger\tThe memory threshold in megabytes for using an in-memory SQLite database.\t100 max_result_preview_rows\tinteger\tThe maximum number of rows to show in a result preview.\t50 max_result_preview_bytes\tinteger\tThe maximum number of bytes to show in a result preview.\t4096 ","version":"Next","tagName":"h3"},{"title":"Creating and Running an Agent Mesh Project","type":0,"sectionRef":"#","url":"/solace-agent-mesh/docs/documentation/installing-and-configuring/run-project","content":"","keywords":"","version":"Next"},{"title":"Prerequisites​","type":1,"pageTitle":"Creating and Running an Agent Mesh Project","url":"/solace-agent-mesh/docs/documentation/installing-and-configuring/run-project#prerequisites","content":" Before you begin, ensure you have the following:  Agent Mesh CLI installed - If not installed, see the installation guideVirtual environment activated - You must have activated the virtual environment you created during installation (not required for containerized deployments)AI provider and API key - For best results, use a state-of-the-art AI model like Anthropic Claude Sonnet 4, Google Gemini 2.5 Pro, or OpenAI GPT-4  ","version":"Next","tagName":"h2"},{"title":"Create Your Project​","type":1,"pageTitle":"Creating and Running an Agent Mesh Project","url":"/solace-agent-mesh/docs/documentation/installing-and-configuring/run-project#create-your-project","content":" ","version":"Next","tagName":"h2"},{"title":"Step 1: Set Up Project Directory​","type":1,"pageTitle":"Creating and Running an Agent Mesh Project","url":"/solace-agent-mesh/docs/documentation/installing-and-configuring/run-project#step-1-set-up-project-directory","content":" Create a directory for your project and navigate to it:  mkdir my-agent-mesh cd my-agent-mesh   ","version":"Next","tagName":"h3"},{"title":"Step 2: Initialize the Project​","type":1,"pageTitle":"Creating and Running an Agent Mesh Project","url":"/solace-agent-mesh/docs/documentation/installing-and-configuring/run-project#step-2-initialize-the-project","content":" Run the init command and follow the prompts to create your project:  solace-agent-mesh init   During initialization, you can choose to configure your project directly in the terminal or through a web-based interface launched at http://127.0.0.1:5002. You are asked for your preference when you run solace-agent-mesh init.  Web-Based Configuration​  To skip the prompt and directly open the web-based configuration interface, use the --gui flag:  solace-agent-mesh init --gui   The web-based interface provides an intuitive way to configure your project settings, including:  AI model selection and configurationSolace event broker setupGateway configurationEnvironment variable management  Command-Line Configuration​  For automated setups or when you prefer command-line interaction, you can run the init command in non-interactive mode by passing --skip and all other configurations as arguments.  To get a list of all available options, run:  solace-agent-mesh init --help   ","version":"Next","tagName":"h3"},{"title":"Step 3: Configure AI Models​","type":1,"pageTitle":"Creating and Running an Agent Mesh Project","url":"/solace-agent-mesh/docs/documentation/installing-and-configuring/run-project#step-3-configure-ai-models","content":" Understanding the model name format is important for proper configuration:  Web-Based Configuration​  When using the web interface:  Select the LLM Provider firstSupported models are populated under LLM Model NameIf you're using a non-OpenAI model hosted on a custom API that follows OpenAI standards (like Ollama or LiteLLM), select the OpenAI Compatible Provider  Command-Line Configuration​  When using the CLI, you must explicitly specify the model in the format provider/name. For example:  openai/gpt-4oanthropic/claude-3-sonnet-20240229  If you're using a non-OpenAI model hosted on a custom API that follows OpenAI standards, you can still use the openai provider. For example: openai/llama-3.3-7b  This format applies to all model types, including LLMs, image generators, and embedding models.  ","version":"Next","tagName":"h3"},{"title":"Docker Alternative for Initialization​","type":1,"pageTitle":"Creating and Running an Agent Mesh Project","url":"/solace-agent-mesh/docs/documentation/installing-and-configuring/run-project#docker-alternative-for-initialization","content":" You can also initialize your Agent Mesh project using the official Docker image. This approach is helpful if you want to avoid local Python/Agent Mesh CLI installation or prefer a containerized workflow.  docker run --rm -it -v "$(pwd):/app" --platform linux/amd64 -p 5002:5002 solace/solace-agent-mesh:latest init --gui   Important Considerations for Docker Initialization:  If your host OS architecture is not linux/amd64, you must add --platform linux/amd64 when you run the containerFor Broker Setup, do not select the Broker Type New local Solace broker container. This option is incompatible with Docker deployments because the Download and Run Container action attempts to download a container image from within the already running container, which causes the operation to fail  ","version":"Next","tagName":"h3"},{"title":"Running Your Project​","type":1,"pageTitle":"Creating and Running an Agent Mesh Project","url":"/solace-agent-mesh/docs/documentation/installing-and-configuring/run-project#running-your-project","content":" ","version":"Next","tagName":"h2"},{"title":"Local Execution​","type":1,"pageTitle":"Creating and Running an Agent Mesh Project","url":"/solace-agent-mesh/docs/documentation/installing-and-configuring/run-project#local-execution","content":" To run the project locally, use the run command to execute all components in a single, multi-threaded application:  solace-agent-mesh run   This command starts all configured agents and gateways, creating a complete agent mesh system.  Environment Variables: By default, environment variables are loaded from your configuration file (typically a .env file at the project root). To use system environment variables instead, use the -u or --system-env option.  Component Separation: While the run command executes all components together, it's possible to split components into separate processes. See the deployment guide for more information about advanced deployment options.  ","version":"Next","tagName":"h3"},{"title":"Docker Execution​","type":1,"pageTitle":"Creating and Running an Agent Mesh Project","url":"/solace-agent-mesh/docs/documentation/installing-and-configuring/run-project#docker-execution","content":" You can also run your Agent Mesh project using the official Docker image:  docker run --rm -it -v "$(pwd):/app" --platform linux/amd64 -p 8000:8000 solace/solace-agent-mesh:latest run   Platform Compatibility: If your host system architecture is not linux/amd64, add the --platform linux/amd64 flag when you run the container.  Docker Configuration Requirements​  For deployments that use the official Docker image, ensure the following:  Do not use a local Solace event broker container - This configuration is incompatible with Docker deploymentsSet FASTAPI_HOST="0.0.0.0" in your .env file or system environment variables. This setting is necessary to expose the FastAPI server to the host machine  Using Custom Dependencies with Docker​  If you are using third-party Python packages or Agent Mesh plugins, you need to build a custom Docker image based on the official image:  FROM solace/solace-agent-mesh:latest # Option 1: Install a specific package RUN python3.11 -m pip install --no-cache-dir <your-package> # Option 2: use a requirements.txt file COPY requirements.txt . RUN python3.11 -m pip install --no-cache-dir -r requirements.txt ENTRYPOINT ["solace-agent-mesh"]   Then build and run your custom image:  docker build --platform linux/amd64 -t my-custom-image . docker run --rm -it -v "$(pwd):/app" --platform linux/amd64 -p 8000:8000 my-custom-image run   ","version":"Next","tagName":"h3"},{"title":"Interacting with Your Agent Mesh​","type":1,"pageTitle":"Creating and Running an Agent Mesh Project","url":"/solace-agent-mesh/docs/documentation/installing-and-configuring/run-project#interacting-with-your-agent-mesh","content":" Agent Mesh supports multiple gateway interfaces for communication, including REST, Web UI, Slack, MS Teams, and more. The web interface provides the most straightforward way to get started.  ","version":"Next","tagName":"h2"},{"title":"Accessing the Web Interface​","type":1,"pageTitle":"Creating and Running an Agent Mesh Project","url":"/solace-agent-mesh/docs/documentation/installing-and-configuring/run-project#accessing-the-web-interface","content":" Navigate to the Interface: Open http://localhost:8000 in your web browserCustom Ports: If you specified a different port during initialization, use that port insteadDocker Port Mappings: For Docker deployments with custom port mappings (using the -p flag), use the host port specified in your port mapping configuration  ","version":"Next","tagName":"h3"},{"title":"Testing Your Setup​","type":1,"pageTitle":"Creating and Running an Agent Mesh Project","url":"/solace-agent-mesh/docs/documentation/installing-and-configuring/run-project#testing-your-setup","content":" Try some example commands to verify your agent mesh is working correctly:  "Suggest some good outdoor activities in London given the season and current weather conditions""Help me plan a project timeline for a software development project""Analyze the latest trends in artificial intelligence"  ","version":"Next","tagName":"h3"},{"title":"Understanding Your System​","type":1,"pageTitle":"Creating and Running an Agent Mesh Project","url":"/solace-agent-mesh/docs/documentation/installing-and-configuring/run-project#understanding-your-system","content":" Your Agent Mesh project consists of two main types of components:  ","version":"Next","tagName":"h2"},{"title":"Agents​","type":1,"pageTitle":"Creating and Running an Agent Mesh Project","url":"/solace-agent-mesh/docs/documentation/installing-and-configuring/run-project#agents","content":" AI-powered components that perform specific tasks and can communicate with each other. Your system includes:  Built-in orchestrator agent: Coordinates tasks and manages communication between other agentsCustom agents: Any additional agents you configure for specific domains or tasks  ","version":"Next","tagName":"h3"},{"title":"Gateways​","type":1,"pageTitle":"Creating and Running an Agent Mesh Project","url":"/solace-agent-mesh/docs/documentation/installing-and-configuring/run-project#gateways","content":" Interface components that allow external systems and users to interact with the agent mesh:  Web user interface gateway: Provides the browser-based interface you enabled during initializationAdditional gateways: REST APIs, Slack integrations, or other interfaces you configure  ","version":"Next","tagName":"h3"},{"title":"Next Steps​","type":1,"pageTitle":"Creating and Running an Agent Mesh Project","url":"/solace-agent-mesh/docs/documentation/installing-and-configuring/run-project#next-steps","content":" Now that you have a working Agent Mesh project, you can:  ","version":"Next","tagName":"h2"},{"title":"Extend Your System​","type":1,"pageTitle":"Creating and Running an Agent Mesh Project","url":"/solace-agent-mesh/docs/documentation/installing-and-configuring/run-project#extend-your-system","content":" Add new agents: Learn about creating your own agents for specific domainsConfigure additional gateways: Explore creating new gateways for different interfacesUse plugins: Discover how to use existing plugins to extend functionality  ","version":"Next","tagName":"h3"},{"title":"Learn More​","type":1,"pageTitle":"Creating and Running an Agent Mesh Project","url":"/solace-agent-mesh/docs/documentation/installing-and-configuring/run-project#learn-more","content":" Understand agents: Deep dive into how agents workExplore gateways: Learn more about gateway types and configurationCLI commands: Discover additional CLI capabilities  ","version":"Next","tagName":"h3"},{"title":"Try Tutorials​","type":1,"pageTitle":"Creating and Running an Agent Mesh Project","url":"/solace-agent-mesh/docs/documentation/installing-and-configuring/run-project#try-tutorials","content":" SQL Database Integration: Follow the tutorial on adding an SQL database agentCustom Integrations: Explore other integration tutorials in the user guide  To learn more about CLI commands and advanced configuration options, see the CLI documentation. ","version":"Next","tagName":"h3"},{"title":"Configuring LLMs","type":0,"sectionRef":"#","url":"/solace-agent-mesh/docs/documentation/installing-and-configuring/large_language_models","content":"","keywords":"","version":"Next"},{"title":"Understanding LiteLLM Integration​","type":1,"pageTitle":"Configuring LLMs","url":"/solace-agent-mesh/docs/documentation/installing-and-configuring/large_language_models#understanding-litellm-integration","content":" Agent Mesh leverages LiteLLM to provide seamless integration with numerous LLM providers. This integration layer abstracts the differences between various provider APIs, allowing you to use a consistent configuration format regardless of whether you're connecting to OpenAI, Anthropic, Google, Amazon, or other supported providers.  The configuration system passes all fields from the models section directly to LiteLLM, giving you access to the full range of provider-specific options and features. This approach ensures that you can take advantage of advanced capabilities offered by different providers while maintaining a consistent configuration experience across your deployment.  Environment variables provide a secure and flexible way to manage sensitive information such as API keys and endpoint URLs. The configuration system supports environment variable substitution using the format ${ENV_VAR_NAME, default_value}, allowing you to keep secrets out of your configuration files while providing sensible defaults for development environments.  ","version":"Next","tagName":"h2"},{"title":"Provider-Specific Configurations​","type":1,"pageTitle":"Configuring LLMs","url":"/solace-agent-mesh/docs/documentation/installing-and-configuring/large_language_models#provider-specific-configurations","content":" ","version":"Next","tagName":"h2"},{"title":"OpenAI​","type":1,"pageTitle":"Configuring LLMs","url":"/solace-agent-mesh/docs/documentation/installing-and-configuring/large_language_models#openai","content":" OpenAI provides some of the most widely-used language models, including the GPT series. The configuration requires minimal setup, needing only the model name and your API key. The system uses OpenAI's default endpoints automatically, simplifying the configuration process.  model: gpt-5 api_key: ${OPENAI_API_KEY}   If your organization belongs to multiple OpenAI organizations, you can specify which organization to use by adding the organization parameter. This parameter helps ensure billing and usage tracking align with your organizational structure.  For comprehensive details about OpenAI-specific configuration options and advanced features, see the OpenAI documentation.  ","version":"Next","tagName":"h3"},{"title":"Azure OpenAI​","type":1,"pageTitle":"Configuring LLMs","url":"/solace-agent-mesh/docs/documentation/installing-and-configuring/large_language_models#azure-openai","content":" Azure OpenAI Service provides OpenAI models through Microsoft's cloud infrastructure, offering additional enterprise features such as private networking and enhanced security controls. The configuration requires specifying your custom Azure endpoint, API key, and API version.  model: azure/gpt-5 api_base: ${AZURE_API_BASE,"https://your-custom-endpoint.openai.azure.com/"} api_key: ${AZURE_API_KEY} api_version: ${AZURE_API_VERSION,"2024-12-01-preview"}   The model name must include the azure/ prefix to indicate you're using Azure OpenAI rather than the standard OpenAI service. The API base URL points to your specific Azure OpenAI resource, which you configure during the Azure setup process.  For detailed information about Azure-specific configuration options, deployment models, and enterprise features, see the Azure OpenAI documentation.  ","version":"Next","tagName":"h3"},{"title":"Google Vertex AI​","type":1,"pageTitle":"Configuring LLMs","url":"/solace-agent-mesh/docs/documentation/installing-and-configuring/large_language_models#google-vertex-ai","content":" Google Vertex AI provides access to both Google's own models and third-party models through a unified platform. This service offers enterprise-grade features including fine-tuning capabilities, model versioning, and integration with other Google Cloud services.  model: vertex_ai/claude-sonnet-4@20250514 vertex_project: ${VERTEX_PROJECT} vertex_location: ${VERTEX_LOCATION,"us-east5"} vertex_credentials: ${VERTEX_CREDENTIALS}   The vertex_credentials parameter requires a JSON string containing your Google Cloud service account key. This credential provides the necessary authentication for accessing Vertex AI services. You can obtain this key from the Google Cloud Console by creating a service account with appropriate Vertex AI permissions.  An example of the credential structure follows this format:  export VERTEX_CREDENTIALS='{"type": "", "project_id": "", "private_key_id": "", "private_key": "", "client_email": "", "client_id": "", "auth_uri": "", "token_uri": "", "auth_provider_x509_cert_url": "", "client_x509_cert_url": "", "universe_domain": ""}'   For comprehensive information about Vertex AI configuration, available models, and advanced features, see the Vertex AI documentation.  ","version":"Next","tagName":"h3"},{"title":"Amazon Bedrock​","type":1,"pageTitle":"Configuring LLMs","url":"/solace-agent-mesh/docs/documentation/installing-and-configuring/large_language_models#amazon-bedrock","content":" Amazon Bedrock provides access to foundation models from various providers through AWS infrastructure. This service offers enterprise features such as private VPC connectivity, AWS IAM integration, and comprehensive logging through AWS CloudTrail.  model: bedrock/anthropic.claude-3-5-sonnet-20240620-v1:0 aws_region_name: ${AWS_REGION_NAME,"us-east-1"} aws_access_key_id: ${AWS_ACCESS_KEY_ID} aws_secret_access_key: ${AWS_SECRET_ACCESS_KEY}   The model name includes the bedrock/ prefix followed by the specific model identifier as defined in the Bedrock service. AWS credentials follow standard AWS authentication patterns, allowing you to use IAM roles, environment variables, or credential files depending on your deployment environment.  For detailed information about Bedrock-specific configuration options, available models, and AWS integration features, see the AWS Bedrock documentation.  ","version":"Next","tagName":"h3"},{"title":"Anthropic​","type":1,"pageTitle":"Configuring LLMs","url":"/solace-agent-mesh/docs/documentation/installing-and-configuring/large_language_models#anthropic","content":" Anthropic provides the Claude family of models, known for their strong reasoning capabilities and helpful, harmless, and honest behavior. The direct Anthropic API offers the most up-to-date model versions and features.  model: claude-4 api_key: ${ANTHROPIC_API_KEY}   The configuration requires only the model name and your Anthropic API key, making it straightforward to integrate Claude models into your agent workflows. Anthropic regularly updates their models with improved capabilities, and the direct API typically provides access to the latest versions first.  For comprehensive details about Anthropic-specific configuration options and model capabilities, see the Anthropic documentation.  ","version":"Next","tagName":"h3"},{"title":"Additional Providers​","type":1,"pageTitle":"Configuring LLMs","url":"/solace-agent-mesh/docs/documentation/installing-and-configuring/large_language_models#additional-providers","content":" LiteLLM supports numerous other providers including Cohere, Hugging Face, Together AI, and many more. Each provider may have specific configuration requirements and capabilities, but the general pattern of specifying model names, endpoints, and authentication credentials remains consistent.  For a complete list of supported providers and their specific configuration requirements, see the LiteLLM providers documentation.  ","version":"Next","tagName":"h3"},{"title":"Prompt Caching​","type":1,"pageTitle":"Configuring LLMs","url":"/solace-agent-mesh/docs/documentation/installing-and-configuring/large_language_models#prompt-caching","content":" Agent Mesh supports prompt caching to significantly reduce costs and latency when using LLM providers that support this feature. Prompt caching allows frequently-used content such as system instructions and tool definitions to be cached by the LLM provider, reducing both processing time and token costs on subsequent requests.  ","version":"Next","tagName":"h2"},{"title":"How Prompt Caching Works​","type":1,"pageTitle":"Configuring LLMs","url":"/solace-agent-mesh/docs/documentation/installing-and-configuring/large_language_models#how-prompt-caching-works","content":" When you configure prompt caching, the system marks specific portions of each request for caching by the LLM provider. These cached portions persist for a provider-defined duration (typically 5 minutes to 1 hour) and can be reused across multiple requests without re-processing. This approach provides substantial cost savings for agents with large system instructions or extensive tool definitions.  ","version":"Next","tagName":"h3"},{"title":"Supported Providers​","type":1,"pageTitle":"Configuring LLMs","url":"/solace-agent-mesh/docs/documentation/installing-and-configuring/large_language_models#supported-providers","content":" The caching mechanism operates transparently through LiteLLM's provider-agnostic interface. Prompt caching support varies by provider:  Anthropic Claude: Full support with explicit cache control, 90% cost reduction on cache hitsOpenAI: Automatic caching for content exceeding 1,024 tokensAzure OpenAI: Automatic caching following OpenAI behaviorAWS Bedrock: Native caching support via LiteLLM translationDeepseek: Native caching support via LiteLLM translation  Providers without caching support safely ignore cache control markers, ensuring backward compatibility across all providers.  ","version":"Next","tagName":"h3"},{"title":"Cache Strategy Configuration​","type":1,"pageTitle":"Configuring LLMs","url":"/solace-agent-mesh/docs/documentation/installing-and-configuring/large_language_models#cache-strategy-configuration","content":" Agent Mesh provides three cache strategies that you can configure per model to optimize costs based on usage patterns:  Strategy\tDescription\tCache Duration\tBest For"5m"\t5-minute ephemeral cache\t5 minutes\tHigh-frequency agents (10+ calls/hour) "1h"\t1-hour extended cache\t1 hour\tBurst patterns with gaps (3-10 calls/hour) "none"\tDisable caching\tN/A\tRarely-used agents (less than 2 calls/hour)  The default strategy is "5m" when not explicitly specified, providing optimal performance for most use cases without requiring configuration changes.  ","version":"Next","tagName":"h3"},{"title":"Configuration Examples​","type":1,"pageTitle":"Configuring LLMs","url":"/solace-agent-mesh/docs/documentation/installing-and-configuring/large_language_models#configuration-examples","content":" Configure prompt caching in your model settings using the cache_strategy parameter:  models: # High-frequency orchestrator with 5-minute cache planning: model: anthropic/claude-sonnet-4-5-20250929 api_key: ${ANTHROPIC_API_KEY} cache_strategy: "5m" temperature: 0.1 # Burst-pattern agent with 1-hour cache analysis: model: anthropic/claude-sonnet-4-5-20250929 api_key: ${ANTHROPIC_API_KEY} cache_strategy: "1h" temperature: 0.7 # Low-frequency agent with caching disabled maintenance: model: anthropic/claude-sonnet-4-5-20250929 api_key: ${ANTHROPIC_API_KEY} cache_strategy: "none"   ","version":"Next","tagName":"h3"},{"title":"Cache Strategy Selection Guidelines​","type":1,"pageTitle":"Configuring LLMs","url":"/solace-agent-mesh/docs/documentation/installing-and-configuring/large_language_models#cache-strategy-selection-guidelines","content":" Choose your cache strategy based on agent usage patterns:  Use "5m" strategy when:  Agent receives 10 or more requests per hourRequests arrive in steady streams rather than isolated burstsCache remains warm through continuous useExample: Primary orchestrator agents handling user interactions  Use "1h" strategy when:  Agent receives 3-10 requests per hour in burst patternsGaps between request bursts exceed 5 minutesExtended cache duration bridges usage gapsExample: Development and testing scenarios, periodic analysis agents  Use "none" strategy when:  Agent receives fewer than 2 requests per hourCache write premium exceeds potential savingsSystem instructions change frequentlyExample: Maintenance agents, backup handlers, rarely-used specialized agents  ","version":"Next","tagName":"h3"},{"title":"What Gets Cached​","type":1,"pageTitle":"Configuring LLMs","url":"/solace-agent-mesh/docs/documentation/installing-and-configuring/large_language_models#what-gets-cached","content":" The caching system optimizes two primary components of LLM requests:  System Instructions: The complete agent system prompt, including capabilities, guidelines, and any static context. System instructions typically represent the largest cacheable content and provide the most significant cost savings.  Tool Definitions: All tool declarations available to the agent, including peer agent communication tools. Agent Mesh ensures tool order stability through alphabetical sorting, maintaining cache validity across requests.  Conversation history and user messages are never cached, as these components change with each request and represent the unique context for each interaction.  ","version":"Next","tagName":"h3"},{"title":"Cache Invalidation​","type":1,"pageTitle":"Configuring LLMs","url":"/solace-agent-mesh/docs/documentation/installing-and-configuring/large_language_models#cache-invalidation","content":" The system automatically handles cache invalidation, requiring no manual intervention. When the cache expires or invalidates, the next request writes new cache content, and subsequent requests benefit from the refreshed cache.  ","version":"Next","tagName":"h3"},{"title":"OAuth 2.0 Authentication​","type":1,"pageTitle":"Configuring LLMs","url":"/solace-agent-mesh/docs/documentation/installing-and-configuring/large_language_models#oauth-20-authentication","content":" Agent Mesh supports OAuth 2.0 Client Credentials authentication for LLM providers that require OAuth-based authentication instead of traditional API keys. This authentication method provides enhanced security through automatic token management, secure credential handling, and seamless integration with OAuth-enabled LLM endpoints.  ","version":"Next","tagName":"h2"},{"title":"Overview​","type":1,"pageTitle":"Configuring LLMs","url":"/solace-agent-mesh/docs/documentation/installing-and-configuring/large_language_models#overview","content":" The OAuth 2.0 Client Credentials flow is a machine-to-machine authentication method defined in RFC 6749. Agent Mesh handles the complete OAuth lifecycle automatically, including token acquisition, caching, refresh, and injection into LLM requests. This implementation ensures secure and efficient authentication without requiring manual token management.  ","version":"Next","tagName":"h3"},{"title":"Configuration Parameters​","type":1,"pageTitle":"Configuring LLMs","url":"/solace-agent-mesh/docs/documentation/installing-and-configuring/large_language_models#configuration-parameters","content":" OAuth authentication requires several configuration parameters that you can specify through environment variables and YAML configuration:  Parameter\tRequired\tDescription\tDefaultoauth_token_url\tYes\tOAuth token endpoint URL\t- oauth_client_id\tYes\tOAuth client identifier\t- oauth_client_secret\tYes\tOAuth client secret\t- oauth_scope\tNo\tOAuth scope (space-separated)\tNone oauth_ca_cert\tNo\tCustom CA certificate path for OAuth endpoint\tNone oauth_token_refresh_buffer_seconds\tNo\tSeconds before expiration to refresh token\t300  ","version":"Next","tagName":"h3"},{"title":"Environment Variables​","type":1,"pageTitle":"Configuring LLMs","url":"/solace-agent-mesh/docs/documentation/installing-and-configuring/large_language_models#environment-variables","content":" Configure OAuth credentials securely using environment variables in your .env file:  # Required OAuth Configuration OAUTH_TOKEN_URL="https://auth.example.com/oauth/token" OAUTH_CLIENT_ID="your_client_id" OAUTH_CLIENT_SECRET="your_client_secret" # Optional OAuth Configuration OAUTH_SCOPE="llm.read llm.write" OAUTH_CA_CERT_PATH="/path/to/ca.crt" OAUTH_TOKEN_REFRESH_BUFFER_SECONDS="300" # LLM Endpoint Configuration OAUTH_LLM_API_BASE="https://api.example.com/v1"   ","version":"Next","tagName":"h3"},{"title":"YAML Configuration​","type":1,"pageTitle":"Configuring LLMs","url":"/solace-agent-mesh/docs/documentation/installing-and-configuring/large_language_models#yaml-configuration","content":" Configure OAuth-authenticated models in your shared_config.yaml file:  models: # OAuth-authenticated planning model planning: model: ${OAUTH_LLM_PLANNING_MODEL_NAME} api_base: ${OAUTH_LLM_API_BASE} # OAuth 2.0 Client Credentials configuration oauth_token_url: ${OAUTH_TOKEN_URL} oauth_client_id: ${OAUTH_CLIENT_ID} oauth_client_secret: ${OAUTH_CLIENT_SECRET} oauth_scope: ${OAUTH_SCOPE} oauth_ca_cert: ${OAUTH_CA_CERT_PATH} oauth_token_refresh_buffer_seconds: ${OAUTH_TOKEN_REFRESH_BUFFER_SECONDS, 300} parallel_tool_calls: true temperature: 0.1 # OAuth-authenticated general model general: model: ${OAUTH_LLM_GENERAL_MODEL_NAME} api_base: ${OAUTH_LLM_API_BASE} # OAuth 2.0 Client Credentials configuration oauth_token_url: ${OAUTH_TOKEN_URL} oauth_client_id: ${OAUTH_CLIENT_ID} oauth_client_secret: ${OAUTH_CLIENT_SECRET} oauth_scope: ${OAUTH_SCOPE} oauth_ca_cert: ${OAUTH_CA_CERT_PATH} oauth_token_refresh_buffer_seconds: ${OAUTH_TOKEN_REFRESH_BUFFER_SECONDS, 300}   ","version":"Next","tagName":"h3"},{"title":"Error Handling and Fallback​","type":1,"pageTitle":"Configuring LLMs","url":"/solace-agent-mesh/docs/documentation/installing-and-configuring/large_language_models#error-handling-and-fallback","content":" The OAuth system implements robust error handling:  4xx Errors: Client configuration errors result in no retries, as these indicate credential or configuration issues5xx Errors: Server errors trigger exponential backoff with jitter for up to 3 retry attemptsNetwork Errors: Connection issues trigger exponential backoff with jitter for up to 3 retry attempts  If OAuth authentication fails and an api_key is configured in the model settings, the system automatically falls back to API key authentication and logs the OAuth failure. If no fallback is available, the request fails with the OAuth error.  ","version":"Next","tagName":"h3"},{"title":"Security Considerations​","type":1,"pageTitle":"Configuring LLMs","url":"/solace-agent-mesh/docs/documentation/installing-and-configuring/large_language_models#security-considerations","content":" When implementing OAuth authentication, follow these security best practices:  Credential Storage: Always store OAuth credentials securely using environment variables, never hardcode them in configuration filesToken Caching: Tokens are cached in memory only and never persisted to diskSSL/TLS: Always use HTTPS for OAuth endpoints to protect credentials in transitCustom CA Certificates: Use the oauth_ca_cert parameter for private or internal OAuth servers with custom certificate authoritiesScope Limitation: Request only the minimal OAuth scopes required for your LLM operations  ","version":"Next","tagName":"h3"},{"title":"Troubleshooting OAuth Issues​","type":1,"pageTitle":"Configuring LLMs","url":"/solace-agent-mesh/docs/documentation/installing-and-configuring/large_language_models#troubleshooting-oauth-issues","content":" Common OAuth authentication issues and their solutions:  Invalid Client Credentials  ERROR: OAuth token request failed with status 401: Invalid client credentials   Verify that OAUTH_CLIENT_ID and OAUTH_CLIENT_SECRET are correct and properly URL-encoded if they contain special characters.  Invalid Scope  ERROR: OAuth token request failed with status 400: Invalid scope   Verify that OAUTH_SCOPE matches your provider's requirements and that scope values are space-separated.  SSL Certificate Issues  ERROR: OAuth token request failed: SSL certificate verification failed   Set OAUTH_CA_CERT_PATH to point to your custom CA certificate file and verify the certificate chain is complete.  Token Refresh Issues  WARNING: OAuth token request failed (attempt 1/4): Connection timeout   Check network connectivity to the OAuth endpoint, verify the OAuth endpoint URL is correct, and consider increasing timeout values if needed.  ","version":"Next","tagName":"h3"},{"title":"Supported Providers​","type":1,"pageTitle":"Configuring LLMs","url":"/solace-agent-mesh/docs/documentation/installing-and-configuring/large_language_models#supported-providers-1","content":" This OAuth implementation works with any LLM provider that supports OAuth 2.0 Client Credentials flow, accepts Bearer tokens in the Authorization header, and is compatible with LiteLLM's request format. Examples include Azure OpenAI with OAuth-enabled endpoints, custom enterprise LLM deployments, and third-party LLM services with OAuth support.  ","version":"Next","tagName":"h3"},{"title":"Security and SSL/TLS Configuration​","type":1,"pageTitle":"Configuring LLMs","url":"/solace-agent-mesh/docs/documentation/installing-and-configuring/large_language_models#security-and-ssltls-configuration","content":" Agent Mesh provides comprehensive security controls for connections to LLM endpoints, allowing you to fine-tune SSL/TLS behavior to meet your organization's security requirements. These settings help ensure secure communication with LLM providers while providing flexibility for various network environments and security policies.  The SSL verification setting controls whether the system validates SSL certificates when connecting to LLM endpoints. Although disabling verification can resolve connectivity issues in development environments, production deployments should always use proper SSL verification to maintain security.  SSL security levels determine the cryptographic standards required for connections. Higher security levels enforce stricter requirements but may cause compatibility issues with older endpoints. The default level provides a good balance between security and compatibility for most deployments.  Custom SSL certificates allow you to specify additional trusted certificate authorities or use self-signed certificates in controlled environments. You can provide certificates either as file paths or as direct certificate content in PEM format.  Parameter\tType\tDescription\tDefaultSSL_VERIFY\tboolean\tControls SSL certificate verification for outbound connections.\ttrue SSL_SECURITY_LEVEL\tinteger\tSets the SSL security level (higher values enforce stricter checks).\t2 SSL_CERT_FILE\tstring\tPath to a custom SSL certificate file to use for verification.\t(none) SSL_CERTIFICATE\tstring\tDirect content of the SSL certificate (PEM format).\t(none) DISABLE_AIOHTTP_TRANSPORT\tboolean\tFlag to disable the use of aiohttp transport for HTTP requests.\tfalse AIOHTTP_TRUST_ENV\tboolean\tFlag to enable aiohttp to trust environment proxy settings.\tfalse  The HTTP transport settings control how the system makes network requests to LLM endpoints. The aiohttp transport provides efficient asynchronous HTTP handling, although some environments may require disabling it for compatibility reasons. The trust environment setting allows the HTTP client to use proxy settings from environment variables, which can be useful in corporate networks.  For detailed information about each security setting and specific use cases, see the LiteLLM security documentation.  ","version":"Next","tagName":"h2"},{"title":"Example Environment Configuration​","type":1,"pageTitle":"Configuring LLMs","url":"/solace-agent-mesh/docs/documentation/installing-and-configuring/large_language_models#example-environment-configuration","content":" # SSL Configuration SSL_VERIFY=true SSL_SECURITY_LEVEL=2 SSL_CERT_FILE=/path/to/your/certificate.pem SSL_CERTIFICATE="-----BEGIN CERTIFICATE----- MIIDXTCCAkWgAwIBAg...T2u3V4w5X6y7Z8 -----END CERTIFICATE-----" # HTTP Transport Configuration DISABLE_AIOHTTP_TRANSPORT=false AIOHTTP_TRUST_ENV=false   This example demonstrates how to configure SSL settings through environment variables, providing a secure foundation for LLM communications while maintaining flexibility for different deployment scenarios. The certificate content should be replaced with your actual certificate data, and file paths should point to your specific certificate locations. ","version":"Next","tagName":"h3"},{"title":"Migration Guide: Upgrading to the A2A SDK","type":0,"sectionRef":"#","url":"/solace-agent-mesh/docs/documentation/migrations/a2a-upgrade/a2a-gateway-upgrade-to-0.3.0","content":"","keywords":"","version":"Next"},{"title":"Why the Change?​","type":1,"pageTitle":"Migration Guide: Upgrading to the A2A SDK","url":"/solace-agent-mesh/docs/documentation/migrations/a2a-upgrade/a2a-gateway-upgrade-to-0.3.0#why-the-change","content":" The migration from our legacy A2A implementation to the official a2a-sdk is a foundational improvement with several key benefits:  Protocol Compliance: Ensures your gateway is fully interoperable with any A2A-compliant agent or system.Standardization: Replaces bespoke code with a community-supported standard, reducing technical debt.Improved Maintainability: Insulates your gateway from future A2A specification changes. The a2a-sdk will be updated, not your core logic.Future-Proofing: Positions your gateway to easily adopt new features as the A2A protocol evolves.  ","version":"Next","tagName":"h2"},{"title":"Core Conceptual Changes​","type":1,"pageTitle":"Migration Guide: Upgrading to the A2A SDK","url":"/solace-agent-mesh/docs/documentation/migrations/a2a-upgrade/a2a-gateway-upgrade-to-0.3.0#core-conceptual-changes","content":" The upgrade introduces a few key changes in how you interact with A2A objects.  ","version":"Next","tagName":"h2"},{"title":"The a2a Helper Layer: The New Best Practice​","type":1,"pageTitle":"Migration Guide: Upgrading to the A2A SDK","url":"/solace-agent-mesh/docs/documentation/migrations/a2a-upgrade/a2a-gateway-upgrade-to-0.3.0#the-a2a-helper-layer-the-new-best-practice","content":" The most significant change is the introduction of a new abstraction layer located at solace_agent_mesh.common.a2a.  You should no longer instantiate a2a.types models directly or access their properties by hand. Instead, use the provided helper functions. This layer is designed to simplify development and protect your code from future SDK changes.  Example:   # BEFORE: Direct instantiation and property access from solace_agent_mesh.common.types import TextPart, Task my_part = TextPart(text="Hello") task_id = my_task.id # AFTER: Using the a2a helper layer from solace_agent_mesh.common import a2a my_part = a2a.create_text_part(text="Hello") task_id = a2a.get_task_id(my_task)   ","version":"Next","tagName":"h3"},{"title":"Type System Migration​","type":1,"pageTitle":"Migration Guide: Upgrading to the A2A SDK","url":"/solace-agent-mesh/docs/documentation/migrations/a2a-upgrade/a2a-gateway-upgrade-to-0.3.0#type-system-migration","content":" The legacy types in solace_agent_mesh.common.types (like A2APart, FileContent) are deprecated.All A2A models now come from the a2a.types library.The type hint for a list of message parts has changed from List[A2APart] to List[ContentPart]. ContentPart is a simple alias for the union of TextPart, DataPart, and FilePart.  ","version":"Next","tagName":"h3"},{"title":"Accessing Object Properties​","type":1,"pageTitle":"Migration Guide: Upgrading to the A2A SDK","url":"/solace-agent-mesh/docs/documentation/migrations/a2a-upgrade/a2a-gateway-upgrade-to-0.3.0#accessing-object-properties","content":" Field names on many A2A objects have changed. Always use the a2a helper functions for safe and future-proof access.  Action\tOld Pattern\tNew Pattern (Recommended)Get Task ID\ttask.id\ta2a.get_task_id(task) Get Task Status\ttask.status.state\ta2a.get_task_status(task) Get Event's Task ID\tevent.id\tevent.task_id Get Message Parts\tmessage.parts\ta2a.get_parts_from_message(message) Get Error Message\terror.message\ta2a.get_error_message(error) Get Error Code\terror.code\ta2a.get_error_code(error) Get Error Data\terror.data\ta2a.get_error_data(error)  ","version":"Next","tagName":"h3"},{"title":"Changes to BaseGatewayComponent​","type":1,"pageTitle":"Migration Guide: Upgrading to the A2A SDK","url":"/solace-agent-mesh/docs/documentation/migrations/a2a-upgrade/a2a-gateway-upgrade-to-0.3.0#changes-to-basegatewaycomponent","content":" The BaseGatewayComponent has been significantly improved. It now handles more of the A2A protocol complexity, simplifying gateway implementations.  Artifact Handling: The base class can now automatically handle artifact URIs, converting them to embedded bytes before sending them to your gateway's _send_... methods. This is controlled by the resolve_artifact_uris_in_gateway parameter in the constructor.Message Publishing: The base class now manages the details of preparing and publishing the A2A request message in submit_a2a_task.Asynchronous Model: The underlying threading model has been removed in favor of a more direct asyncio implementation, simplifying the component lifecycle.  It is highly recommended to review the latest BaseGatewayComponent and re-base your custom gateway on it to inherit these benefits and reduce boilerplate code.  ","version":"Next","tagName":"h3"},{"title":"Migration Checklist​","type":1,"pageTitle":"Migration Guide: Upgrading to the A2A SDK","url":"/solace-agent-mesh/docs/documentation/migrations/a2a-upgrade/a2a-gateway-upgrade-to-0.3.0#migration-checklist","content":" Follow these steps to update your gateway code.  Update Imports: Remove imports from solace_agent_mesh.common.types.Add imports from a2a.types for specific models if needed.Add from solace_agent_mesh.common import a2a.Add from solace_agent_mesh.common.a2a import ContentPart. Update Type Hints: Find all instances of List[A2APart] and change them to List[ContentPart]. Refactor Object Creation: Replace direct model instantiation like TextPart(...) or FilePart(...) with their corresponding helper functions: a2a.create_text_part(...), a2a.create_file_part_from_uri(...), etc. Refactor Property Access: Replace direct property access (task.id, error.message) with calls to the a2a helper functions (a2a.get_task_id(task), a2a.get_error_message(error)). Review Base Class Integration: If you have a custom gateway, compare it against the latest BaseGatewayComponent. Consider refactoring to delegate more responsibility (like artifact handling and message submission) to the base class. Test Thoroughly: Once refactored, run your integration tests to ensure the gateway correctly translates inputs and processes outputs in the new format.  ","version":"Next","tagName":"h2"},{"title":"Code Examples: Before & After​","type":1,"pageTitle":"Migration Guide: Upgrading to the A2A SDK","url":"/solace-agent-mesh/docs/documentation/migrations/a2a-upgrade/a2a-gateway-upgrade-to-0.3.0#code-examples-before--after","content":" Here are some common patterns you will encounter during the migration.  ","version":"Next","tagName":"h2"},{"title":"Example 1: Translating External Input​","type":1,"pageTitle":"Migration Guide: Upgrading to the A2A SDK","url":"/solace-agent-mesh/docs/documentation/migrations/a2a-upgrade/a2a-gateway-upgrade-to-0.3.0#example-1-translating-external-input","content":" This example shows how to create A2A parts from an external event.  _translate_external_input Before: from solace_agent_mesh.common.types import Part as A2APart, TextPart, FilePart, FileContent async def _translate_external_input(self, external_event: Any) -> Tuple[str, List[A2APart], Dict[str, Any]]: # ... a2a_parts: List[A2APart] = [] # Create a file part with a URI uri = "artifact://..." a2a_parts.append( FilePart( file=FileContent(name="report.pdf", uri=uri) ) ) # Create a text part prompt = "Summarize the attached file." a2a_parts.append(TextPart(text=prompt)) return "summary_agent", a2a_parts, {} After: from solace_agent_mesh.common import a2a from solace_agent_mesh.common.a2a import ContentPart async def _translate_external_input(self, external_event: Any) -> Tuple[str, List[ContentPart], Dict[str, Any]]: # ... a2a_parts: List[ContentPart] = [] # Create a file part with a URI using the helper uri = "artifact://..." file_part = a2a.create_file_part_from_uri(uri=uri, name="report.pdf") a2a_parts.append(file_part) # Create a text part using the helper prompt = "Summarize the attached file." text_part = a2a.create_text_part(text=prompt) a2a_parts.append(text_part) return "summary_agent", a2a_parts, {}   ","version":"Next","tagName":"h3"},{"title":"Example 2: Sending a Final Response​","type":1,"pageTitle":"Migration Guide: Upgrading to the A2A SDK","url":"/solace-agent-mesh/docs/documentation/migrations/a2a-upgrade/a2a-gateway-upgrade-to-0.3.0#example-2-sending-a-final-response","content":" This example shows how to process a final Task object.  _send_final_response_to_external Before: from solace_agent_mesh.common.types import Task, TaskState, TextPart async def _send_final_response_to_external(self, context: Dict, task_data: Task) -> None: task_id = task_data.id final_status_text = ":checkered_flag: Task complete." if task_data.status.state == TaskState.FAILED: error_message_text = "" if task_data.status.message and task_data.status.message.parts: for part in task_data.status.message.parts: if isinstance(part, TextPart): error_message_text = part.text break final_status_text = f":x: Error: Task failed. {error_message_text}".strip() # ... use final_status_text and task_id After: from solace_agent_mesh.common import a2a from a2a.types import Task, TaskState async def _send_final_response_to_external(self, context: Dict, task_data: Task) -> None: # Use helpers to safely access properties task_id = a2a.get_task_id(task_data) task_status = a2a.get_task_status(task_data) final_status_text = ":checkered_flag: Task complete." if task_status == TaskState.failed: error_message_text = "" if task_data.status and task_data.status.message: # Use helper to extract all text from the message error_message_text = a2a.get_text_from_message(task_data.status.message) final_status_text = f":x: Error: Task failed. {error_message_text}".strip() # ... use final_status_text and task_id  ","version":"Next","tagName":"h3"},{"title":"A2A Technical Migration Map","type":0,"sectionRef":"#","url":"/solace-agent-mesh/docs/documentation/migrations/a2a-upgrade/a2a-technical-migration-map","content":"","keywords":"","version":"Next"},{"title":"Core Concept Changes​","type":1,"pageTitle":"A2A Technical Migration Map","url":"/solace-agent-mesh/docs/documentation/migrations/a2a-upgrade/a2a-technical-migration-map#core-concept-changes","content":" Session vs. Context: The concept of a session, previously Task.sessionId, is now attached to the Message via Message.contextId. The Task also has a contextId, but it's primarily for grouping. Code that relied on Task.sessionId for conversation history must now use Message.contextId.Request/Response Structure: The structure of JSON-RPC requests and responses is now strictly defined by the SDK's Pydantic models (e.g., SendMessageRequest, JSONRPCResponse as a discriminated union). Direct dictionary manipulation is replaced by model instantiation and validation.Status Signaling: The practice of embedding custom status signals (e.g., tool_invocation_start) in the metadata field of a message is deprecated. The new standard is to use a dedicated, structured DataPart within a multi-part Message.  ","version":"Next","tagName":"h2"},{"title":"Import and Type Mapping​","type":1,"pageTitle":"A2A Technical Migration Map","url":"/solace-agent-mesh/docs/documentation/migrations/a2a-upgrade/a2a-technical-migration-map#import-and-type-mapping","content":" ","version":"Next","tagName":"h2"},{"title":"Import Paths​","type":1,"pageTitle":"A2A Technical Migration Map","url":"/solace-agent-mesh/docs/documentation/migrations/a2a-upgrade/a2a-technical-migration-map#import-paths","content":" Old Import Path\tNew Import Path(s)\tNotessolace_agent_mesh.common.types\ta2a.types, solace_agent_mesh.common.a2a, solace_agent_mesh.common.a2a.types\tLegacy types are removed. Use SDK types and the a2a helper layer. solace_agent_mesh.common.a2a_protocol\tsolace_agent_mesh.common.a2a\tProtocol helpers (topic builders, etc.) are now in the main a2a helper package.  ","version":"Next","tagName":"h3"},{"title":"Type Hints​","type":1,"pageTitle":"A2A Technical Migration Map","url":"/solace-agent-mesh/docs/documentation/migrations/a2a-upgrade/a2a-technical-migration-map#type-hints","content":" Old Type Hint\tNew Type Hint\tNotesA2APart\tContentPart\tContentPart is an alias for Union[TextPart, DataPart, FilePart]. List[A2APart]\tList[ContentPart]\tStandard type hint for a list of message parts. FileContent\tUnion[FileWithBytes, FileWithUri]\tThe file attribute of a FilePart is now a discriminated union.  ","version":"Next","tagName":"h3"},{"title":"Object Creation and Property Access Mapping​","type":1,"pageTitle":"A2A Technical Migration Map","url":"/solace-agent-mesh/docs/documentation/migrations/a2a-upgrade/a2a-technical-migration-map#object-creation-and-property-access-mapping","content":" This table maps common legacy patterns to their new equivalents using the a2a helper layer.  Action\tOld Pattern (Legacy)\tNew Pattern (a2a-sdk + Helpers)Part Creation Create Text Part\tTextPart(text=...)\ta2a.create_text_part(text=...) Create File Part (URI)\tFilePart(file=FileContent(name=..., uri=...))\ta2a.create_file_part_from_uri(uri=..., name=...) Create File Part (Bytes)\tFilePart(file=FileContent(bytes=...))\ta2a.create_file_part_from_bytes(content_bytes=...) Create Data Part\tDataPart(data=...)\ta2a.create_data_part(data=...) Task/Event Access Get Task ID\ttask.id\ta2a.get_task_id(task) Get Task Status\ttask.status.state\ta2a.get_task_status(task) Get Task Context ID\ttask.sessionId\ta2a.get_task_context_id(task) Get Event's Task ID\tevent.id\tevent.task_id Message Access Get Message Parts\tmessage.parts\ta2a.get_parts_from_message(message) Get Text from Message\t(manual loop over parts)\ta2a.get_text_from_message(message) Get Data Parts\t(manual loop over parts)\ta2a.get_data_parts_from_message(message) Error Access Get Error Message\terror.message\ta2a.get_error_message(error) Get Error Code\terror.code\ta2a.get_error_code(error) Get Error Data\terror.data\ta2a.get_error_data(error) Protocol/RPC Create RPC Success\tJSONRPCResponse(id=..., result=...)\ta2a.create_success_response(result=..., request_id=...) Create RPC Error\tJSONRPCResponse(id=..., error=...)\ta2a.create_error_response(error=..., request_id=...) Validate RPC Payload\tJSONRPCResponse(**payload)\tJSONRPCResponse.model_validate(payload) Topic Matching\t_topic_matches_subscription(...)\ta2a.topic_matches_subscription(...) Extract Task ID from Topic\t_extract_task_id_from_topic(...)\ta2a.extract_task_id_from_topic(...)  ","version":"Next","tagName":"h2"},{"title":"Full Method Examples​","type":1,"pageTitle":"A2A Technical Migration Map","url":"/solace-agent-mesh/docs/documentation/migrations/a2a-upgrade/a2a-technical-migration-map#full-method-examples","content":" These examples provide larger, "before and after" contexts for the refactoring patterns.  ","version":"Next","tagName":"h2"},{"title":"Example 1: _translate_external_input​","type":1,"pageTitle":"A2A Technical Migration Map","url":"/solace-agent-mesh/docs/documentation/migrations/a2a-upgrade/a2a-technical-migration-map#example-1-_translate_external_input","content":" Before:  from solace_agent_mesh.common.types import Part as A2APart, TextPart, FilePart, FileContent async def _translate_external_input(self, external_event: Any) -> Tuple[str, List[A2APart], Dict[str, Any]]: # ... a2a_parts: List[A2APart] = [] # ... artifact_uri = f"artifact://{self.gateway_id}/{user_id}/{a2a_session_id}/{filename}?version={version}" file_content_a2a = FileContent(name=filename, mimeType=mime_type, uri=artifact_uri) a2a_parts.append(FilePart(file=file_content_a2a)) # ... a2a_parts.append(TextPart(text=processed_text_for_a2a)) return "agent_name", a2a_parts, {}   After:  from solace_agent_mesh.common import a2a from solace_agent_mesh.common.a2a import ContentPart async def _translate_external_input(self, external_event: Any) -> Tuple[str, List[ContentPart], Dict[str, Any]]: # ... a2a_parts: List[ContentPart] = [] # ... artifact_uri = f"artifact://{self.gateway_id}/{user_id}/{a2a_session_id}/{filename}?version={version}" file_part = a2a.create_file_part_from_uri(uri=artifact_uri, name=filename, mime_type=mime_type) a2a_parts.append(file_part) # ... text_part = a2a.create_text_part(text=processed_text_for_a2a) a2a_parts.append(text_part) return "agent_name", a2a_parts, {}   ","version":"Next","tagName":"h3"},{"title":"Example 2: _send_update_to_external​","type":1,"pageTitle":"A2A Technical Migration Map","url":"/solace-agent-mesh/docs/documentation/migrations/a2a-upgrade/a2a-technical-migration-map#example-2-_send_update_to_external","content":" Before:  from solace_agent_mesh.common.types import TaskStatusUpdateEvent, TextPart, DataPart async def _send_update_to_external(self, context: Dict, event_data: TaskStatusUpdateEvent, is_final: bool) -> None: task_id = event_data.id # ... if event_data.status and event_data.status.message and event_data.status.message.parts: for part in event_data.status.message.parts: if isinstance(part, TextPart): # process part.text elif isinstance(part, DataPart): # process part.data   After:  from a2a.types import TaskStatusUpdateEvent, TextPart, DataPart from solace_agent_mesh.common import a2a async def _send_update_to_external(self, context: Dict, event_data: TaskStatusUpdateEvent, is_final: bool) -> None: task_id = event_data.task_id # ... message = a2a.get_message_from_status_update(event_data) if message: parts = a2a.get_parts_from_message(message) for part in parts: if isinstance(part, TextPart): # process part.text elif isinstance(part, DataPart): # process part.data   ","version":"Next","tagName":"h3"},{"title":"Example 3: _send_final_response_to_external​","type":1,"pageTitle":"A2A Technical Migration Map","url":"/solace-agent-mesh/docs/documentation/migrations/a2a-upgrade/a2a-technical-migration-map#example-3-_send_final_response_to_external","content":" Before:  from solace_agent_mesh.common.types import Task, TaskState async def _send_final_response_to_external(self, context: Dict, task_data: Task) -> None: task_id = task_data.id if task_data.status.state == TaskState.FAILED: # ...   After:  from a2a.types import Task, TaskState from solace_agent_mesh.common import a2a async def _send_final_response_to_external(self, context: Dict, task_data: Task) -> None: task_id = a2a.get_task_id(task_data) task_status = a2a.get_task_status(task_data) if task_status == TaskState.failed: # ...   ","version":"Next","tagName":"h3"},{"title":"Example 4: _send_error_to_external​","type":1,"pageTitle":"A2A Technical Migration Map","url":"/solace-agent-mesh/docs/documentation/migrations/a2a-upgrade/a2a-technical-migration-map#example-4-_send_error_to_external","content":" Before:  from solace_agent_mesh.common.types import JSONRPCError async def _send_error_to_external(self, context: Dict, error_data: JSONRPCError) -> None: error_text = f"Error: {error_data.message} (Code: {error_data.code})" if error_data.data: # process error_data.data   After:  from a2a.types import JSONRPCError from solace_agent_mesh.common import a2a async def _send_error_to_external(self, context: Dict, error_data: JSONRPCError) -> None: error_message = a2a.get_error_message(error_data) error_code = a2a.get_error_code(error_data) error_details = a2a.get_error_data(error_data) error_text = f"Error: {error_message} (Code: {error_code})" if error_details: # process error_details  ","version":"Next","tagName":"h3"}],"options":{"id":"default"}}