solace-agent-mesh 1.4.12__py3-none-any.whl → 1.5.1__py3-none-any.whl

solace_agent_mesh/agent/adk/invocation_monitor.py

@@ -1,295 +0,0 @@
-import copy
-import datetime
-import json
-import os
-import yaml
-
-from solace_ai_connector.common.log import log
-
-
-class InvocationMonitor:
-    LOG_DIRECTORY = "/tmp/solace-agent-mesh"
-    START_TOPIC_SUFFIX = "a2a/v1/agent/request/OrchestratorAgent"
-    END_TOPIC_CONTAINS = "a2a/v1/gateway/response/"
-    EXCLUDE_TOPIC_SUFFIX = "/discovery/agentcards"
-    LOG_FILE_VERSION = "1.0"
-
-    def __init__(self):
-        self._is_logging_active = False
-        self._current_log_buffer = []
-        self._current_logfile_path = None
-        self._invocation_start_time = None
-        self._triggering_event_details = None
-        self._current_invocation_id = None
-        self._current_session_id = None
-
-        try:
-            os.makedirs(self.LOG_DIRECTORY, exist_ok=True)
-            log.info(
-                f"InvocationMonitor initialized. Logging to directory: {self.LOG_DIRECTORY}"
-            )
-        except Exception as e:
-            log.error(
-                f"InvocationMonitor: Failed to create log directory {self.LOG_DIRECTORY}: {e}"
-            )
-            self.LOG_DIRECTORY = None
-
-    def _sanitize(self, value):
-        """Replace underscores with dashes and convert to string."""
-        return str(value).replace("_", "-") if value is not None else "unknown"
-
-    def _generate_logfile_path(self, invocation_id, gateway) -> str:
-        if not self.LOG_DIRECTORY:
-            return None
-        timestamp = str(int(datetime.datetime.now(datetime.timezone.utc).timestamp()))
-        invocation_id = self._sanitize(invocation_id)
-        gateway = self._sanitize(gateway)
-        filename = f"{invocation_id}_{gateway}_{timestamp}.stim"
-        return os.path.join(self.LOG_DIRECTORY, filename)
-
-    def _finalize_log_file(self, terminating_event_details=None):
-        if not self._is_logging_active or not self._current_logfile_path:
-            if self._is_logging_active:
-                log.warning("InvocationMonitor: Finalize called but no log file path.")
-            self._reset_session()
-            return
-
-        if not self._current_log_buffer and not self._triggering_event_details:
-            log.info(
-                f"InvocationMonitor: No messages were logged for {self._current_logfile_path}. Skipping file creation."
-            )
-            self._reset_session()
-            return
-
-        invocation_end_time = datetime.datetime.now(datetime.timezone.utc).timestamp()
-
-        yaml_data = {
-            "invocation_details": {
-                "log_file_version": self.LOG_FILE_VERSION,
-                "start_time": self._invocation_start_time,
-                "end_time": invocation_end_time,
-                "triggering_event": self._triggering_event_details,
-                "terminating_event": terminating_event_details,
-            },
-            "invocation_flow": self._current_log_buffer,
-        }
-
-        try:
-            with open(self._current_logfile_path, "w", encoding="utf-8") as f:
-                yaml.dump(
-                    yaml_data,
-                    f,
-                    sort_keys=False,
-                    allow_unicode=True,
-                    indent=2,
-                    default_flow_style=False,
-                )
-            log.info(
-                f"InvocationMonitor: YAML content saved to .stim file: {self._current_logfile_path}"
-            )
-        except Exception as e:
-            log.error(
-                f"InvocationMonitor: Failed to write YAML content to .stim file {self._current_logfile_path}: {e}"
-            )
-        finally:
-            self._reset_session()
-
-    def _reset_session(self):
-        self._is_logging_active = False
-        self._current_log_buffer = []
-        self._current_logfile_path = None
-        self._invocation_start_time = None
-        self._triggering_event_details = None
-        self._current_invocation_id = None
-        self._current_session_id = None
-
-    def _prepare_payload_for_yaml(self, payload):
-        if isinstance(payload, str):
-            try:
-                return json.loads(payload)
-            except json.JSONDecodeError:
-                return payload
-        elif isinstance(payload, (dict, list)):
-            return payload
-        elif isinstance(payload, bytes):
-            try:
-                return payload.decode("utf-8")
-            except UnicodeDecodeError:
-                return repr(payload)
-        return str(payload)
-
-    def _add_log_entry(
-        self,
-        direction: str,
-        topic: str,
-        payload: any,
-        component_identifier: str,
-        is_trigger_event=False,
-    ):
-        timestamp = datetime.datetime.now(datetime.timezone.utc).timestamp()
-        prepared_payload = self._prepare_payload_for_yaml(payload)
-
-        log_entry_dict = {
-            "topic": topic,
-            "timestamp": timestamp,
-            "component": component_identifier,
-            "direction": direction,
-            "payload": prepared_payload,
-        }
-
-        if is_trigger_event:
-            return {
-                "timestamp": timestamp,
-                "component": component_identifier,
-                "direction": direction,
-                "topic": topic,
-                "payload": prepared_payload,
-            }
-
-        if self._is_logging_active:
-            self._current_log_buffer.append(log_entry_dict)
-
-        return log_entry_dict
-
-    def log_message_event(
-        self,
-        direction: str,
-        topic: str,
-        payload: any,
-        component_identifier: str = "A2A_Host",
-    ):
-        if not self.LOG_DIRECTORY:
-            log.error(
-                "InvocationMonitor: Log directory not available. Skipping log_message_event."
-            )
-            return
-
-        if topic.endswith(self.EXCLUDE_TOPIC_SUFFIX):
-            return
-
-        if self.START_TOPIC_SUFFIX in topic:
-            method = None
-            invocation_id = None
-            session_id = None
-            if isinstance(payload, dict):
-                method = payload.get("method")
-                invocation_id = payload.get("id") or "unknown"
-                session_id = payload.get("params", {}).get("sessionId", None)
-            elif isinstance(payload, str):
-                try:
-                    payload_obj = json.loads(payload)
-                    method = payload_obj.get("method")
-                    invocation_id = payload_obj.get("id") or "unknown"
-                    session_id = payload_obj.get("params", {}).get("sessionId", None)
-                except Exception:
-                    invocation_id = "unknown"
-                    session_id = None
-
-            if method != "tasks/sendSubscribe":
-                if self._is_logging_active and method == "tasks/cancel":
-                    log.warning(
-                        f"InvocationMonitor: Cancel event received for topic {topic} (id={invocation_id}, sessionId={session_id}) while a session for {self._current_logfile_path} was active. "
-                        "Finalizing previous session with reason: 'Request was canceled'."
-                    )
-                    self._finalize_log_file(
-                        terminating_event_details={
-                            "reason": "Request was canceled",
-                            "topic": topic,
-                            "method": method,
-                            "invocation_id": invocation_id,
-                            "session_id": session_id,
-                        }
-                    )
-                return
-
-            if self._is_logging_active:
-                log.warning(
-                    f"InvocationMonitor: New start event received for topic {topic} (id={invocation_id}, sessionId={session_id}, method={method}) while a session for {self._current_logfile_path} was active. "
-                    "Finalizing previous session with reason: 'New session started before old one ended'."
-                )
-                self._finalize_log_file(
-                    terminating_event_details={
-                        "reason": "New session started before old one ended",
-                        "topic": topic,
-                        "method": method,
-                        "invocation_id": invocation_id,
-                        "session_id": session_id,
-                    }
-                )
-
-            self._is_logging_active = True
-            self._current_log_buffer = []
-            self._current_invocation_id = invocation_id
-            self._current_session_id = session_id
-
-            log.debug(
-                f"InvocationMonitor: Received start event for topic {topic}. Payload: {payload}"
-            )
-
-            gateway = "unknown"
-            if session_id and "web-session" in session_id:
-                gateway = "web"
-            elif session_id and "slack" in session_id:
-                gateway = "slack"
-
-            self._current_logfile_path = self._generate_logfile_path(
-                invocation_id, gateway
-            )
-
-            if not self._current_logfile_path:
-                log.error(
-                    "InvocationMonitor: Could not generate logfile path. Aborting logging for this session."
-                )
-                self._reset_session()
-                return
-
-            self._invocation_start_time = datetime.datetime.now(
-                datetime.timezone.utc
-            ).timestamp()
-            self._triggering_event_details = self._add_log_entry(
-                direction, topic, payload, component_identifier, is_trigger_event=True
-            )
-
-            if self._triggering_event_details:
-                first_flow_entry = {
-                    "topic": self._triggering_event_details["topic"],
-                    "timestamp": self._triggering_event_details["timestamp"],
-                    "component": self._triggering_event_details["component"],
-                    "direction": self._triggering_event_details["direction"],
-                    "payload": copy.deepcopy(self._triggering_event_details["payload"]),
-                }
-                self._current_log_buffer.append(first_flow_entry)
-
-            log.info(
-                f"InvocationMonitor: Started YAML logging (to .stim file) for new invocation. File: {self._current_logfile_path}. Trigger: {topic}"
-            )
-
-        elif self._is_logging_active:
-            current_event_details = self._add_log_entry(
-                direction, topic, payload, component_identifier, is_trigger_event=False
-            )
-
-            if self.END_TOPIC_CONTAINS in topic:
-                log.info(
-                    f"InvocationMonitor: End condition met by topic {topic}. Finalizing YAML content to .stim file: {self._current_logfile_path}"
-                )
-                terminating_event_info = {
-                    "timestamp": current_event_details["timestamp"],
-                    "component": current_event_details["component"],
-                    "direction": current_event_details["direction"],
-                    "topic": current_event_details["topic"],
-                    "payload": copy.deepcopy(current_event_details["payload"]),
-                }
-                self._finalize_log_file(
-                    terminating_event_details=terminating_event_info
-                )
-
-    def cleanup(self):
-        log.info("InvocationMonitor: Cleanup called.")
-        if self._is_logging_active and self._current_logfile_path:
-            log.warning(
-                f"InvocationMonitor: Finalizing YAML content to .stim file {self._current_logfile_path} during cleanup."
-            )
-            self._finalize_log_file(
-                terminating_event_details={"reason": "Session finalized during cleanup"}
-            )

solace_agent_mesh/assets/docs/assets/js/04989206.a248f00c.js

@@ -1 +0,0 @@
-"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[1935],{3728:(e,t,n)=>{n.r(t),n.d(t,{assets:()=>c,contentTitle:()=>r,default:()=>d,frontMatter:()=>i,metadata:()=>a,toc:()=>l});const a=JSON.parse('{"id":"documentation/concepts/gateways","title":"Gateways","description":"Gateways are a crucial component of the Solace Agent Mesh framework that expose the agent mesh to external systems through various protocols. Built on a common base gateway architecture, they provide the following functions:","source":"@site/docs/documentation/concepts/gateways.md","sourceDirName":"documentation/concepts","slug":"/documentation/concepts/gateways","permalink":"/solace-agent-mesh/docs/documentation/concepts/gateways","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/concepts/gateways.md","tags":[],"version":"current","sidebarPosition":10,"frontMatter":{"title":"Gateways","sidebar_position":10},"sidebar":"docSidebar","previous":{"title":"Solace Agent Mesh CLI","permalink":"/solace-agent-mesh/docs/documentation/concepts/cli"},"next":{"title":"Agents","permalink":"/solace-agent-mesh/docs/documentation/concepts/agents"}}');var s=n(4848),o=n(8453);const i={title:"Gateways",sidebar_position:10},r="Gateways",c={},l=[{value:"Key Functions",id:"key-functions",level:2},{value:"How Gateways Work",id:"how-gateways-work",level:2},{value:"Available Gateways",id:"available-gateways",level:2},{value:"Core Gateways",id:"core-gateways",level:3},{value:"Plugin Gateways",id:"plugin-gateways",level:3},{value:"Create a Gateway",id:"create-a-gateway",level:2},{value:"Gateway from Scratch",id:"gateway-from-scratch",level:3}];function h(e){const t={a:"a",admonition:"admonition",code:"code",em:"em",h1:"h1",h2:"h2",h3:"h3",header:"header",li:"li",mermaid:"mermaid",ol:"ol",p:"p",pre:"pre",strong:"strong",ul:"ul",...(0,o.R)(),...e.components};return(0,s.jsxs)(s.Fragment,{children:[(0,s.jsx)(t.header,{children:(0,s.jsx)(t.h1,{id:"gateways",children:"Gateways"})}),"\n",(0,s.jsx)(t.p,{children:"Gateways are a crucial component of the Solace Agent Mesh framework that expose the agent mesh to external systems through various protocols. Built on a common base gateway architecture, they provide the following functions:"}),"\n",(0,s.jsxs)(t.ul,{children:["\n",(0,s.jsx)(t.li,{children:"serve as the primary interface between Solace Agent Mesh and the outside world"}),"\n",(0,s.jsx)(t.li,{children:"manage the flow of information in and out of the system through the A2A protocol"}),"\n",(0,s.jsx)(t.li,{children:"handle authentication, user enrichment, and message processing"}),"\n",(0,s.jsx)(t.li,{children:"support multiple interface types including REST, HTTP SSE, webhooks, and event mesh connectivity"}),"\n"]}),"\n",(0,s.jsx)(t.admonition,{title:"In one sentence",type:"tip",children:(0,s.jsx)(t.p,{children:"Gateways are the external interfaces that connect various systems to the A2A agent mesh through standardized protocols."})}),"\n",(0,s.jsx)(t.h2,{id:"key-functions",children:"Key Functions"}),"\n",(0,s.jsxs)(t.ol,{children:["\n",(0,s.jsxs)(t.li,{children:["\n",(0,s.jsxs)(t.p,{children:[(0,s.jsx)(t.strong,{children:"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."]}),"\n"]}),"\n",(0,s.jsxs)(t.li,{children:["\n",(0,s.jsxs)(t.p,{children:[(0,s.jsx)(t.strong,{children:"Authentication & Authorization"}),": Common authentication and user enrichment flow across all gateway types, with pluggable identity providers."]}),"\n"]}),"\n",(0,s.jsxs)(t.li,{children:["\n",(0,s.jsxs)(t.p,{children:[(0,s.jsx)(t.strong,{children:"Configurable System Purpose"}),": Each gateway has a configurable system purpose that sets the context for all stimuli entering Solace Agent Mesh through that gateway. This design allows for tailored processing based on the specific use case or domain."]}),"\n"]}),"\n",(0,s.jsxs)(t.li,{children:["\n",(0,s.jsxs)(t.p,{children:[(0,s.jsx)(t.strong,{children:"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."]}),"\n"]}),"\n",(0,s.jsxs)(t.li,{children:["\n",(0,s.jsxs)(t.p,{children:[(0,s.jsx)(t.strong,{children:"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."]}),"\n"]}),"\n"]}),"\n",(0,s.jsx)(t.h2,{id:"how-gateways-work",children:"How Gateways Work"}),"\n",(0,s.jsx)(t.p,{children:"The following diagram illustrates the complete flow of information through a gateway in Solace Agent Mesh:"}),"\n",(0,s.jsx)(t.mermaid,{value:"sequenceDiagram\n    participant External as External System/User\n    participant Gateway\n    participant Mesh as Solace Agent Mesh\n\n    rect rgba(128, 128, 128, 0.2)\n        Note over External,Gateway: Authentication Phase [Optional]\n        External->>Gateway: Send Request\n        Gateway->> Gateway: Authenticate Request\n        alt Authentication Failed\n            Gateway--\x3e>External: Return Error\n        end\n    end\n\n    rect rgba(128, 128, 128, 0.2)\n        Note over Gateway: Authorization Phase [Optional]\n    end\n\n    rect rgba(128, 128, 128, 0.2)\n        Note over Gateway,Mesh: Processing Phase\n        Gateway->>Gateway: Apply System Purpose\n        Gateway->>Gateway: Attach Format Rules\n        Gateway->>Gateway: Format Response\n        Gateway->>Gateway: Transform to Stimulus\n        Gateway->>Mesh: Send Stimulus\n\n        alt Response Expected\n            Mesh--\x3e>Gateway: Return Response\n            Gateway--\x3e>External: Send Formatted Response\n        end\n    end"}),"\n",(0,s.jsx)(t.h2,{id:"available-gateways",children:"Available Gateways"}),"\n",(0,s.jsx)(t.p,{children:"Solace Agent Mesh comes with several built-in gateway types:"}),"\n",(0,s.jsx)(t.h3,{id:"core-gateways",children:"Core Gateways"}),"\n",(0,s.jsxs)(t.ol,{children:["\n",(0,s.jsxs)(t.li,{children:["\n",(0,s.jsx)(t.p,{children:(0,s.jsx)(t.strong,{children:"HTTP SSE Gateway"})}),"\n",(0,s.jsxs)(t.ul,{children:["\n",(0,s.jsx)(t.li,{children:"Real-time web interface with streaming responses"}),"\n",(0,s.jsx)(t.li,{children:"Server-sent events for live updates"}),"\n",(0,s.jsx)(t.li,{children:"Agent discovery API"}),"\n",(0,s.jsx)(t.li,{children:"File upload and download handling"}),"\n"]}),"\n"]}),"\n",(0,s.jsxs)(t.li,{children:["\n",(0,s.jsx)(t.p,{children:(0,s.jsx)(t.strong,{children:"REST Gateway"})}),"\n",(0,s.jsxs)(t.ul,{children:["\n",(0,s.jsx)(t.li,{children:"Task submission with immediate task ID return"}),"\n",(0,s.jsx)(t.li,{children:"Polling-based result retrieval"}),"\n",(0,s.jsx)(t.li,{children:"Authentication integration"}),"\n"]}),"\n"]}),"\n",(0,s.jsxs)(t.li,{children:["\n",(0,s.jsx)(t.p,{children:(0,s.jsx)(t.strong,{children:"Webhook Gateway"})}),"\n",(0,s.jsxs)(t.ul,{children:["\n",(0,s.jsx)(t.li,{children:"Handles incoming webhook requests"}),"\n",(0,s.jsx)(t.li,{children:"Transforms webhook payloads to A2A messages"}),"\n"]}),"\n"]}),"\n"]}),"\n",(0,s.jsx)(t.h3,{id:"plugin-gateways",children:"Plugin Gateways"}),"\n",(0,s.jsx)(t.p,{children:"Additional gateway types are available through the plugin ecosystem:"}),"\n",(0,s.jsxs)(t.ul,{children:["\n",(0,s.jsxs)(t.li,{children:[(0,s.jsx)(t.strong,{children:"Event Mesh Gateway"}),": External event mesh connectivity with message transformation"]}),"\n",(0,s.jsxs)(t.li,{children:[(0,s.jsx)(t.strong,{children:"Slack Gateway"}),": Slack bot integration for team collaboration"]}),"\n",(0,s.jsxs)(t.li,{children:[(0,s.jsx)(t.strong,{children:"Custom Gateways"}),": Create your own gateway implementations"]}),"\n"]}),"\n",(0,s.jsxs)(t.p,{children:["For more information about plugins and how to configure them, see ",(0,s.jsx)(t.a,{href:"/solace-agent-mesh/docs/documentation/concepts/plugins",children:"Plugins"}),"."]}),"\n",(0,s.jsxs)(t.p,{children:["One of the official core plugin gateway interfaces is the ",(0,s.jsx)(t.a,{href:"https://github.com/SolaceLabs/solace-agent-mesh-core-plugins/tree/main/sam-event-mesh-gateway",children:"Solace Event Mesh Gateway"}),", which enables communication with the PubSub+ event broker directly as an input interface."]}),"\n",(0,s.jsx)(t.admonition,{type:"note",children:(0,s.jsx)(t.p,{children:"Each gateway type has its own configuration options and specific features. See the individual gateway documentation pages for detailed information on setup and usage."})}),"\n",(0,s.jsx)(t.h2,{id:"create-a-gateway",children:"Create a Gateway"}),"\n",(0,s.jsxs)(t.p,{children:["To create a gateway, you can either ",(0,s.jsx)(t.a,{href:"/solace-agent-mesh/docs/documentation/concepts/plugins#use-a-plugin",children:"use one of the pre-existing plugins"})," or create yours from scratch."]}),"\n",(0,s.jsx)(t.h3,{id:"gateway-from-scratch",children:"Gateway from Scratch"}),"\n",(0,s.jsxs)(t.p,{children:["To create a gateway from scratch, you need to use the CLI ",(0,s.jsx)(t.code,{children:"add gateway"})," command without any interfaces. This command creates a ",(0,s.jsx)(t.em,{children:"python gateway template file"})," which you can then customize to your needs."]}),"\n",(0,s.jsx)(t.pre,{children:(0,s.jsx)(t.code,{className:"language-sh",children:"sam add gateway my-interface\n"})}),"\n",(0,s.jsxs)(t.p,{children:["To learn more about creating your own gateway, see ",(0,s.jsx)(t.a,{href:"/solace-agent-mesh/docs/documentation/user-guide/create-gateways",children:"Create Custom Gateways"}),"."]}),"\n",(0,s.jsx)(t.admonition,{title:"Share and Reuse",type:"tip",children:(0,s.jsxs)(t.p,{children:["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 ",(0,s.jsx)(t.a,{href:"/solace-agent-mesh/docs/documentation/concepts/plugins#create-a-plugin",children:"Create Plugins"}),"."]})})]})}function d(e={}){const{wrapper:t}={...(0,o.R)(),...e.components};return t?(0,s.jsx)(t,{...e,children:(0,s.jsx)(h,{...e})}):h(e)}},8453:(e,t,n)=>{n.d(t,{R:()=>i,x:()=>r});var a=n(6540);const s={},o=a.createContext(s);function i(e){const t=a.useContext(o);return a.useMemo((function(){return"function"==typeof e?e(t):{...t,...e}}),[t,e])}function r(e){let t;return t=e.disableParentContext?"function"==typeof e.components?e.components(s):e.components||s:i(e.components),a.createElement(o.Provider,{value:t},e.children)}}}]);

solace_agent_mesh/assets/docs/assets/js/0e682baa.d54b8668.js

@@ -1 +0,0 @@
-"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[1430],{7977:(e,n,t)=>{t.r(n),t.d(n,{assets:()=>l,contentTitle:()=>a,default:()=>m,frontMatter:()=>r,metadata:()=>o,toc:()=>c});const o=JSON.parse('{"id":"documentation/tutorials/mcp-integration","title":"MCP Integration","description":"This tutorial walks you through the process of integrating a Model Context Protocol (MCP) Server into Solace Agent Mesh.","source":"@site/docs/documentation/tutorials/mcp-integration.md","sourceDirName":"documentation/tutorials","slug":"/documentation/tutorials/mcp-integration","permalink":"/solace-agent-mesh/docs/documentation/tutorials/mcp-integration","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/tutorials/mcp-integration.md","tags":[],"version":"current","sidebarPosition":10,"frontMatter":{"title":"MCP Integration","sidebar_position":10},"sidebar":"docSidebar","previous":{"title":"Build Your Own Agent","permalink":"/solace-agent-mesh/docs/documentation/tutorials/custom-agent"},"next":{"title":"REST Gateway","permalink":"/solace-agent-mesh/docs/documentation/tutorials/rest-gateway"}}');var s=t(4848),i=t(8453);const r={title:"MCP Integration",sidebar_position:10},a="MCP Integration",l={},c=[{value:"Setting Up the Environment",id:"setting-up-the-environment",level:2},{value:"Adding MCP Tools to an Agent",id:"adding-mcp-tools-to-an-agent",level:2},{value:"1. Stdio Connection (Local MCP Servers)",id:"1-stdio-connection-local-mcp-servers",level:3},{value:"2. SSE Connection (Remote MCP Servers)",id:"2-sse-connection-remote-mcp-servers",level:3},{value:"3. StreamableHTTP Connection (Remote MCP Servers)",id:"3-streamablehttp-connection-remote-mcp-servers",level:3},{value:"4. Docker Connection (Containerized MCP Servers)",id:"4-docker-connection-containerized-mcp-servers",level:3},{value:"Complete Example: Filesystem MCP Agent",id:"complete-example-filesystem-mcp-agent",level:2},{value:"Configuration Options",id:"configuration-options",level:2},{value:"Tool-Specific Configuration",id:"tool-specific-configuration",level:3},{value:"Environment Variables",id:"environment-variables",level:3},{value:"Running Your MCP-Enabled Agent",id:"running-your-mcp-enabled-agent",level:2},{value:"How MCP Integration Works",id:"how-mcp-integration-works",level:2},{value:"Testing Your MCP Integration",id:"testing-your-mcp-integration",level:2}];function d(e){const n={a:"a",admonition:"admonition",code:"code",h1:"h1",h2:"h2",h3:"h3",header:"header",li:"li",ol:"ol",p:"p",pre:"pre",strong:"strong",ul:"ul",...(0,i.R)(),...e.components};return(0,s.jsxs)(s.Fragment,{children:[(0,s.jsx)(n.header,{children:(0,s.jsx)(n.h1,{id:"mcp-integration",children:"MCP Integration"})}),"\n",(0,s.jsx)(n.p,{children:"This tutorial walks you through the process of integrating a Model Context Protocol (MCP) Server into Solace Agent Mesh."}),"\n",(0,s.jsx)(n.admonition,{title:"Learn about agents",type:"info",children:(0,s.jsxs)(n.p,{children:["You should have an understanding of agents in Solace Agent Mesh. For more information, see ",(0,s.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/concepts/agents",children:"Agents"}),"."]})}),"\n",(0,s.jsxs)(n.p,{children:["Solace Agent Mesh now provides ",(0,s.jsx)(n.strong,{children:"native MCP support"})," through the framework itself. No additional plugins are required - you can connect to MCP servers directly by configuring your agent YAML file with MCP tools."]}),"\n",(0,s.jsx)(n.p,{children:"MCP integration allows your agents to connect to external MCP servers and use their tools, resources, and prompts seamlessly within the A2A protocol ecosystem."}),"\n",(0,s.jsx)(n.h2,{id:"setting-up-the-environment",children:"Setting Up the Environment"}),"\n",(0,s.jsxs)(n.p,{children:["You must ",(0,s.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/getting-started/installation",children:"install Solace Agent Mesh and Solace Agent Mesh CLI"}),", and then ",(0,s.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/getting-started/quick-start",children:"create a new Solace Agent Mesh project"}),"."]}),"\n",(0,s.jsx)(n.p,{children:"For this tutorial using the filesystem MCP server, you also need Node.js and NPM installed."}),"\n",(0,s.jsx)(n.h2,{id:"adding-mcp-tools-to-an-agent",children:"Adding MCP Tools to an Agent"}),"\n",(0,s.jsx)(n.p,{children:"MCP integration is accomplished by adding MCP tools directly to your agent configuration. There are three main connection types supported:"}),"\n",(0,s.jsx)(n.h3,{id:"1-stdio-connection-local-mcp-servers",children:"1. Stdio Connection (Local MCP Servers)"}),"\n",(0,s.jsx)(n.p,{children:"This is the most common method for connecting to MCP servers that run as local processes:"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-yaml",children:'tools:\n  - tool_type: mcp\n    connection_params:\n      type: stdio\n      command: "npx"\n      args:\n        - "-y"\n        - "@modelcontextprotocol/server-filesystem"\n        - "/tmp/samv2"\n'})}),"\n",(0,s.jsx)(n.h3,{id:"2-sse-connection-remote-mcp-servers",children:"2. SSE Connection (Remote MCP Servers)"}),"\n",(0,s.jsx)(n.p,{children:"For connecting to remote MCP servers using Server-Sent Events:"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-yaml",children:'tools:\n  - tool_type: mcp\n    connection_params:\n      type: sse\n      url: "https://mcp.example.com/v1/sse"\n      headers:\n        Authorization: "Bearer ${MCP_AUTH_TOKEN}"\n'})}),"\n",(0,s.jsx)(n.h3,{id:"3-streamablehttp-connection-remote-mcp-servers",children:"3. StreamableHTTP Connection (Remote MCP Servers)"}),"\n",(0,s.jsx)(n.p,{children:"For connecting to remote MCP servers using Server-Sent Events:"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-yaml",children:'tools:\n  - tool_type: mcp\n    connection_params:\n      type: streamable-http\n      url: "https://mcp.example.com:<port>/mcp/message"\n      headers:\n        Authorization: "Bearer ${MCP_AUTH_TOKEN}"\n'})}),"\n",(0,s.jsx)(n.h3,{id:"4-docker-connection-containerized-mcp-servers",children:"4. Docker Connection (Containerized MCP Servers)"}),"\n",(0,s.jsx)(n.p,{children:"For running MCP servers in Docker containers:"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-yaml",children:'tools:\n  - tool_type: mcp\n    connection_params:\n      type: stdio\n      command: "docker"\n      args:\n        - "run"\n        - "-i"\n        - "--rm"\n        - "-e"\n        - "API_KEY"\n        - "mcp-server-image:latest"\n    environment_variables:\n      API_KEY: ${MY_API_KEY}\n'})}),"\n",(0,s.jsx)(n.h2,{id:"complete-example-filesystem-mcp-agent",children:"Complete Example: Filesystem MCP Agent"}),"\n",(0,s.jsx)(n.p,{children:"Here is a complete example of an agent that uses the filesystem MCP server:"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-yaml",children:'# configs/agents/filesystem_agent.yaml\nlog:\n  stdout_log_level: INFO\n  log_file_level: DEBUG\n  log_file: filesystem_agent.log\n\n!include ../shared_config.yaml\n\napps:\n  - name: filesystem_mcp_agent_app\n    app_base_path: .\n    app_module: solace_agent_mesh.agent.sac.app\n    broker:\n      <<: *broker_connection\n\n    app_config:\n      namespace: ${NAMESPACE}\n      supports_streaming: true\n      agent_name: "FileSystemAgent"\n      display_name: "File System"\n      model: *general_model\n      \n      instruction: |\n        You can interact with the local filesystem using MCP tools.\n        Use the available tools to read, write, and manage files as requested.\n\n      tools:\n        - tool_type: mcp\n          connection_params:\n            type: stdio\n            command: "npx"\n            args:\n              - "-y"\n              - "@modelcontextprotocol/server-filesystem"\n              - "/tmp/samv2"\n        - tool_type: builtin-group\n          group_name: "artifact_management"\n\n      session_service: *default_session_service\n      artifact_service: *default_artifact_service\n\n      # Agent discovery and communication\n      agent_card:\n        description: "An agent that interacts with the local filesystem via MCP."\n        defaultInputModes: ["text"]\n        defaultOutputModes: ["text", "file"]\n        skills: []\n\n      agent_card_publishing: { interval_seconds: 10 }\n      agent_discovery: { enabled: true }\n      inter_agent_communication:\n        allow_list: ["*"]\n        request_timeout_seconds: 30\n'})}),"\n",(0,s.jsx)(n.h2,{id:"configuration-options",children:"Configuration Options"}),"\n",(0,s.jsx)(n.h3,{id:"tool-specific-configuration",children:"Tool-Specific Configuration"}),"\n",(0,s.jsx)(n.p,{children:"You can limit which tools from an MCP server are available by specifying a specific tool name:"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-yaml",children:'tools:\n  - tool_type: mcp\n    tool_name: "read_file"  # Only expose the read_file tool\n    connection_params:\n      type: stdio\n      command: "npx"\n      args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp/samv2"]\n'})}),"\n",(0,s.jsx)(n.h3,{id:"environment-variables",children:"Environment Variables"}),"\n",(0,s.jsxs)(n.p,{children:["Pass environment variables to MCP servers using the ",(0,s.jsx)(n.code,{children:"environment_variables"})," block:"]}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-yaml",children:'tools:\n  - tool_type: mcp\n    connection_params:\n      type: stdio\n      command: "my-mcp-server"\n    environment_variables:\n      API_KEY: ${MY_API_KEY}\n      DEBUG_MODE: "true"\n      CONFIG_PATH: "/etc/myconfig"\n'})}),"\n",(0,s.jsx)(n.h2,{id:"running-your-mcp-enabled-agent",children:"Running Your MCP-Enabled Agent"}),"\n",(0,s.jsxs)(n.ol,{children:["\n",(0,s.jsxs)(n.li,{children:["\n",(0,s.jsxs)(n.p,{children:[(0,s.jsx)(n.strong,{children:"Create the working directory"})," (for filesystem example):"]}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-sh",children:'mkdir -p /tmp/samv2\necho "Hello MCP!" > /tmp/samv2/test.txt\n'})}),"\n"]}),"\n",(0,s.jsxs)(n.li,{children:["\n",(0,s.jsxs)(n.p,{children:[(0,s.jsx)(n.strong,{children:"Set required environment variables"}),":"]}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-sh",children:'export NAMESPACE="myorg/dev"\nexport SOLACE_BROKER_URL="ws://localhost:8008"\n# ... other Solace broker settings\n'})}),"\n"]}),"\n",(0,s.jsxs)(n.li,{children:["\n",(0,s.jsxs)(n.p,{children:[(0,s.jsx)(n.strong,{children:"Run the agent"}),":"]}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-sh",children:"sam run configs/agents/filesystem_agent.yaml\n"})}),"\n"]}),"\n"]}),"\n",(0,s.jsx)(n.h2,{id:"how-mcp-integration-works",children:"How MCP Integration Works"}),"\n",(0,s.jsx)(n.p,{children:"When your agent starts:"}),"\n",(0,s.jsxs)(n.ol,{children:["\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Connection"}),": The framework establishes a connection to the MCP server using the specified connection parameters"]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Discovery"}),": It queries the MCP server for available tools, resources, and prompts"]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Registration"}),": Available capabilities are registered as agent tools."]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Communication"}),": The agent can use these tools through the standard A2A protocol, with the framework handling MCP protocol translation"]}),"\n"]}),"\n",(0,s.jsx)(n.h2,{id:"testing-your-mcp-integration",children:"Testing Your MCP Integration"}),"\n",(0,s.jsx)(n.p,{children:"Once your MCP-enabled agent is running, you can test it through any gateway in your project (such as the Web UI gateway):"}),"\n",(0,s.jsxs)(n.ol,{children:["\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Access your gateway"})," (for example, Web UI at ",(0,s.jsx)(n.code,{children:"http://localhost:8000"}),")"]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Send a request"})," to test the MCP functionality:","\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsx)(n.li,{children:'"List the files in the directory"'}),"\n",(0,s.jsx)(n.li,{children:'"Create a simple text file with some content"'}),"\n",(0,s.jsx)(n.li,{children:'"Read the contents of test.txt"'}),"\n"]}),"\n"]}),"\n"]}),"\n",(0,s.jsx)(n.p,{children:"The agent uses the MCP tools to interact with the filesystem and provide responses through the A2A protocol."})]})}function m(e={}){const{wrapper:n}={...(0,i.R)(),...e.components};return n?(0,s.jsx)(n,{...e,children:(0,s.jsx)(d,{...e})}):d(e)}},8453:(e,n,t)=>{t.d(n,{R:()=>r,x:()=>a});var o=t(6540);const s={},i=o.createContext(s);function r(e){const n=o.useContext(i);return o.useMemo((function(){return"function"==typeof e?e(n):{...n,...e}}),[n,e])}function a(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(s):e.components||s:r(e.components),o.createElement(i.Provider,{value:n},e.children)}}}]);

solace_agent_mesh/assets/docs/assets/js/1023fc19.8a8a9309.js

@@ -1 +0,0 @@
-"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[1462],{3519:(e,n,t)=>{t.r(n),t.d(n,{assets:()=>l,contentTitle:()=>o,default:()=>h,frontMatter:()=>a,metadata:()=>i,toc:()=>d});const i=JSON.parse('{"id":"documentation/user-guide/builtin-tools/data-analysis-tools","title":"Data Analysis Tools","description":"Solace Agent Mesh includes a suite of optional built-in tools that enable agents to perform data analysis tasks directly on artifacts. These tools provide functionality for SQL querying, JQ transformations, and Plotly chart generation.","source":"@site/docs/documentation/user-guide/builtin-tools/data-analysis-tools.md","sourceDirName":"documentation/user-guide/builtin-tools","slug":"/documentation/user-guide/builtin-tools/data-analysis-tools","permalink":"/solace-agent-mesh/docs/documentation/user-guide/builtin-tools/data-analysis-tools","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/user-guide/builtin-tools/data-analysis-tools.md","tags":[],"version":"current","sidebarPosition":20,"frontMatter":{"title":"Data Analysis Tools","sidebar_position":20},"sidebar":"docSidebar","previous":{"title":"Artifact Management Tools","permalink":"/solace-agent-mesh/docs/documentation/user-guide/builtin-tools/artifact-management"},"next":{"title":"Audio Tools","permalink":"/solace-agent-mesh/docs/documentation/user-guide/builtin-tools/audio-tools"}}');var s=t(4848),r=t(8453);const a={title:"Data Analysis Tools",sidebar_position:20},o="Data Analysis Tools",l={},d=[{value:"Setup and Configuration",id:"setup-and-configuration",level:2},{value:"Available Tools",id:"available-tools",level:2},{value:"<code>query_data_with_sql</code>",id:"query_data_with_sql",level:3},{value:"<code>create_sqlite_db</code>",id:"create_sqlite_db",level:3},{value:"<code>transform_data_with_jq</code>",id:"transform_data_with_jq",level:3},{value:"<code>create_chart_from_plotly_config</code>",id:"create_chart_from_plotly_config",level:3},{value:"Example Workflow: Querying a Large CSV",id:"example-workflow-querying-a-large-csv",level:2},{value:"Technical Considerations",id:"technical-considerations",level:2},{value:"Result Handling",id:"result-handling",level:3},{value:"Security",id:"security",level:3}];function c(e){const n={a:"a",admonition:"admonition",code:"code",h1:"h1",h2:"h2",h3:"h3",header:"header",hr:"hr",li:"li",ol:"ol",p:"p",pre:"pre",strong:"strong",ul:"ul",...(0,r.R)(),...e.components};return(0,s.jsxs)(s.Fragment,{children:[(0,s.jsx)(n.header,{children:(0,s.jsx)(n.h1,{id:"data-analysis-tools",children:"Data Analysis Tools"})}),"\n",(0,s.jsx)(n.p,{children:"Solace Agent Mesh includes a suite of optional built-in tools that enable agents to perform data analysis tasks directly on artifacts. These tools provide functionality for SQL querying, JQ transformations, and Plotly chart generation."}),"\n",(0,s.jsx)(n.h2,{id:"setup-and-configuration",children:"Setup and Configuration"}),"\n",(0,s.jsxs)(n.p,{children:["Enable the data analysis tool group in the agent's ",(0,s.jsx)(n.code,{children:"app_config.yml"})," file."]}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-yaml",children:'# In your agent\'s app_config:\ntools:\n  - tool_type: builtin-group\n    group_name: "data_analysis"\n\n# Optional: Configure tool behavior\ndata_tools_config:\n  sqlite_memory_threshold_mb: 100\n  max_result_preview_rows: 50\n  max_result_preview_bytes: 4096\n'})}),"\n",(0,s.jsx)(n.h2,{id:"available-tools",children:"Available Tools"}),"\n",(0,s.jsx)(n.h3,{id:"query_data_with_sql",children:(0,s.jsx)(n.code,{children:"query_data_with_sql"})}),"\n",(0,s.jsx)(n.admonition,{title:"Enterprise Only",type:"info",children:(0,s.jsx)(n.p,{children:"This feature is available in the Enterprise Edition only."})}),"\n",(0,s.jsx)(n.p,{children:"Executes a SQL query against data stored in a CSV or SQLite artifact."}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Parameters"}),":","\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.code,{children:"input_filename"})," (str): The filename of the input artifact (for example, ",(0,s.jsx)(n.code,{children:"'data.csv'"}),", ",(0,s.jsx)(n.code,{children:"'mydatabase.sqlite'"}),"). Supports versioning (for example, ",(0,s.jsx)(n.code,{children:"'data.csv:2'"}),")."]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.code,{children:"sql_query"})," (str): The SQL query string to execute."]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.code,{children:"output_format"})," (str, optional): The desired format for the output artifact (",(0,s.jsx)(n.code,{children:"'csv'"})," or ",(0,s.jsx)(n.code,{children:"'json'"}),"). Defaults to ",(0,s.jsx)(n.code,{children:"'csv'"}),"."]}),"\n"]}),"\n"]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Behavior"}),":","\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"For CSV Input"}),": The tool loads the CSV data into a temporary in-memory SQLite database table named ",(0,s.jsx)(n.code,{children:"data"})," and executes the query against it."]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"For SQLite Input"}),": The tool connects directly to the specified SQLite database artifact in ",(0,s.jsx)(n.strong,{children:"read-only mode"}),"."]}),"\n"]}),"\n"]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Returns"}),": A dictionary containing the execution status, a preview of the query result, and the ",(0,s.jsx)(n.code,{children:"output_filename"})," where the full result set is stored."]}),"\n"]}),"\n",(0,s.jsx)(n.hr,{}),"\n",(0,s.jsx)(n.h3,{id:"create_sqlite_db",children:(0,s.jsx)(n.code,{children:"create_sqlite_db"})}),"\n",(0,s.jsx)(n.admonition,{title:"Enterprise Only",type:"info",children:(0,s.jsx)(n.p,{children:"This feature is available in the Enterprise Edition only."})}),"\n",(0,s.jsx)(n.p,{children:"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."}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Parameters"}),":","\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.code,{children:"input_filename"})," (str): The filename of the input CSV or JSON artifact."]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.code,{children:"output_db_filename"})," (str): The desired filename for the output SQLite database artifact (for example, ",(0,s.jsx)(n.code,{children:"'queryable_dataset.sqlite'"}),")."]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.code,{children:"table_name"})," (str, optional): The name of the table to be created within the SQLite database. Defaults to ",(0,s.jsx)(n.code,{children:"'data'"}),"."]}),"\n"]}),"\n"]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Returns"}),": A dictionary confirming the successful creation of the database artifact and providing its ",(0,s.jsx)(n.code,{children:"output_filename"}),"."]}),"\n"]}),"\n",(0,s.jsx)(n.hr,{}),"\n",(0,s.jsx)(n.h3,{id:"transform_data_with_jq",children:(0,s.jsx)(n.code,{children:"transform_data_with_jq"})}),"\n",(0,s.jsx)(n.admonition,{title:"Enterprise Only",type:"info",children:(0,s.jsx)(n.p,{children:"This feature is available in the Enterprise Edition only."})}),"\n",(0,s.jsx)(n.p,{children:"Applies a JQ expression to transform data from a JSON, YAML, or CSV artifact."}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Parameters"}),":","\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.code,{children:"input_filename"})," (str): The filename of the input artifact."]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.code,{children:"jq_expression"})," (str): The JQ filter or transformation expression string (for example, ",(0,s.jsx)(n.code,{children:"'.users[] | {name, id}'"}),")."]}),"\n"]}),"\n"]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Returns"}),": A dictionary containing the execution status, a preview of the transformed data, and the ",(0,s.jsx)(n.code,{children:"output_filename"})," where the full JSON result is stored."]}),"\n"]}),"\n",(0,s.jsx)(n.hr,{}),"\n",(0,s.jsx)(n.h3,{id:"create_chart_from_plotly_config",children:(0,s.jsx)(n.code,{children:"create_chart_from_plotly_config"})}),"\n",(0,s.jsx)(n.p,{children:"Generates a static chart image (for example, PNG, JPG, SVG) from a Plotly configuration provided as a string."}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Parameters"}),":","\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.code,{children:"config_content"})," (str): A JSON or YAML formatted string representing the Plotly ",(0,s.jsx)(n.code,{children:"figure"})," dictionary."]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.code,{children:"config_format"})," (str): Specifies whether ",(0,s.jsx)(n.code,{children:"config_content"})," is ",(0,s.jsx)(n.code,{children:"'json'"})," or ",(0,s.jsx)(n.code,{children:"'yaml'"}),"."]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.code,{children:"output_filename"})," (str): The desired filename for the output image artifact (for example, ",(0,s.jsx)(n.code,{children:"'sales_chart.png'"}),")."]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.code,{children:"output_format"})," (str, optional): The desired image format (",(0,s.jsx)(n.code,{children:"'png'"}),", ",(0,s.jsx)(n.code,{children:"'jpeg'"}),", ",(0,s.jsx)(n.code,{children:"'svg'"}),", etc.). Defaults to ",(0,s.jsx)(n.code,{children:"'png'"}),"."]}),"\n"]}),"\n"]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Returns"}),": A dictionary confirming the chart's creation and providing its ",(0,s.jsx)(n.code,{children:"output_filename"}),"."]}),"\n"]}),"\n",(0,s.jsx)(n.h2,{id:"example-workflow-querying-a-large-csv",children:"Example Workflow: Querying a Large CSV"}),"\n",(0,s.jsx)(n.p,{children:"The following workflow demonstrates an efficient method for analyzing a large CSV file:"}),"\n",(0,s.jsxs)(n.ol,{children:["\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"User Request"}),': "I need to run several queries on ',(0,s.jsx)(n.code,{children:"large_data.csv"}),'."']}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Agent Strategy"}),": The agent determines that converting the CSV to a SQLite database is more performant for subsequent queries."]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Agent Call 1"}),": The agent calls ",(0,s.jsx)(n.code,{children:"create_sqlite_db"})," to convert ",(0,s.jsx)(n.code,{children:"large_data.csv"})," into a new artifact, ",(0,s.jsx)(n.code,{children:"queryable_data.sqlite"}),"."]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Agent Response"}),': "The data has been prepared for querying. What is your first question?"']}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"User Request"}),": \"Find all records where the category is 'Sales'.\""]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Agent Call 2"}),": The agent calls ",(0,s.jsx)(n.code,{children:"query_data_with_sql"}),", targeting the ",(0,s.jsx)(n.strong,{children:(0,s.jsx)(n.code,{children:"queryable_data.sqlite"})})," artifact."]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Agent Response"}),": The agent provides the results of the query."]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"User Request"}),": \"Now, find the average amount for the 'Marketing' category.\""]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Agent Call 3"}),": The agent calls ",(0,s.jsx)(n.code,{children:"query_data_with_sql"})," again on the ",(0,s.jsxs)(n.strong,{children:["same ",(0,s.jsx)(n.code,{children:"queryable_data.sqlite"})," artifact"]}),", avoiding the overhead of reprocessing the original CSV file."]}),"\n"]}),"\n",(0,s.jsx)(n.h2,{id:"technical-considerations",children:"Technical Considerations"}),"\n",(0,s.jsx)(n.h3,{id:"result-handling",children:"Result Handling"}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Previews"}),": For ",(0,s.jsx)(n.code,{children:"query_data_with_sql"})," and ",(0,s.jsx)(n.code,{children:"transform_data_with_jq"}),", the tools return a truncated preview of the result directly to the LLM for immediate context."]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"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."]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Accessing Full Results"}),": To utilize the full results, the agent can employ file management tools (",(0,s.jsx)(n.code,{children:"load_artifact"}),") or ",(0,s.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/user-guide/builtin-tools/embeds",children:"Dynamic Embeds"})," (",(0,s.jsx)(n.code,{children:"\xabartifact_content:...\xbb"}),")."]}),"\n"]}),"\n",(0,s.jsx)(n.h3,{id:"security",children:"Security"}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"SQL Execution"}),": Queries against existing SQLite artifacts are performed in ",(0,s.jsx)(n.strong,{children:"read-only mode"})," to prevent data modification. Queries against temporary databases generated from CSVs are isolated."]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"JQ Execution"}),": JQ expressions are executed within a sandboxed Python library, not via shell execution."]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Resource Usage"}),": Complex queries or transformations can be resource-intensive. Monitor performance and resource consumption accordingly."]}),"\n"]})]})}function h(e={}){const{wrapper:n}={...(0,r.R)(),...e.components};return n?(0,s.jsx)(n,{...e,children:(0,s.jsx)(c,{...e})}):c(e)}},8453:(e,n,t)=>{t.d(n,{R:()=>a,x:()=>o});var i=t(6540);const s={},r=i.createContext(s);function a(e){const n=i.useContext(r);return i.useMemo((function(){return"function"==typeof e?e(n):{...n,...e}}),[n,e])}function o(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(s):e.components||s:a(e.components),i.createElement(r.Provider,{value:n},e.children)}}}]);

solace_agent_mesh/assets/docs/assets/js/1523c6b4.2645ef68.js

@@ -1 +0,0 @@
-"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[4777],{3112:(e,n,i)=>{i.r(n),i.d(n,{assets:()=>c,contentTitle:()=>r,default:()=>h,frontMatter:()=>l,metadata:()=>t,toc:()=>d});const t=JSON.parse('{"id":"documentation/user-guide/builtin-tools/audio-tools","title":"Audio Tools","description":"This guide provides technical documentation for the text-to-speech (TTS) tools available in Solace Agent Mesh.","source":"@site/docs/documentation/user-guide/builtin-tools/audio-tools.md","sourceDirName":"documentation/user-guide/builtin-tools","slug":"/documentation/user-guide/builtin-tools/audio-tools","permalink":"/solace-agent-mesh/docs/documentation/user-guide/builtin-tools/audio-tools","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/user-guide/builtin-tools/audio-tools.md","tags":[],"version":"current","sidebarPosition":30,"frontMatter":{"title":"Audio Tools","sidebar_position":30},"sidebar":"docSidebar","previous":{"title":"Data Analysis Tools","permalink":"/solace-agent-mesh/docs/documentation/user-guide/builtin-tools/data-analysis-tools"},"next":{"title":"Dynamic Embeds","permalink":"/solace-agent-mesh/docs/documentation/user-guide/builtin-tools/embeds"}}');var s=i(4848),o=i(8453);const l={title:"Audio Tools",sidebar_position:30},r="Using Text-to-Speech (TTS) Tools",c={},d=[{value:"Overview",id:"overview",level:2},{value:"Setup and Configuration",id:"setup-and-configuration",level:2},{value:"Prerequisites",id:"prerequisites",level:3},{value:"Basic Configuration",id:"basic-configuration",level:3},{value:"Advanced Configuration",id:"advanced-configuration",level:2},{value:"<code>text_to_speech</code> Configuration",id:"text_to_speech-configuration",level:3},{value:"<code>multi_speaker_text_to_speech</code> Configuration",id:"multi_speaker_text_to_speech-configuration",level:3},{value:"Features",id:"features",level:2},{value:"Intelligent Tone Selection",id:"intelligent-tone-selection",level:3},{value:"Multi-Language Support",id:"multi-language-support",level:3},{value:"Usage Examples",id:"usage-examples",level:2},{value:"Single-Voice Text-to-Speech (<code>text_to_speech</code>)",id:"single-voice-text-to-speech-text_to_speech",level:3},{value:"Multi-Speaker Text-to-Speech (<code>multi_speaker_text_to_speech</code>)",id:"multi-speaker-text-to-speech-multi_speaker_text_to_speech",level:3},{value:"Tool Reference",id:"tool-reference",level:2},{value:"<code>text_to_speech</code>",id:"text_to_speech",level:3},{value:"<code>multi_speaker_text_to_speech</code>",id:"multi_speaker_text_to_speech",level:3},{value:"Output and Metadata",id:"output-and-metadata",level:2},{value:"Troubleshooting",id:"troubleshooting",level:2}];function a(e){const n={code:"code",h1:"h1",h2:"h2",h3:"h3",header:"header",li:"li",ol:"ol",p:"p",pre:"pre",strong:"strong",table:"table",tbody:"tbody",td:"td",th:"th",thead:"thead",tr:"tr",ul:"ul",...(0,o.R)(),...e.components};return(0,s.jsxs)(s.Fragment,{children:[(0,s.jsx)(n.header,{children:(0,s.jsx)(n.h1,{id:"using-text-to-speech-tts-tools",children:"Using Text-to-Speech (TTS) Tools"})}),"\n",(0,s.jsx)(n.p,{children:"This guide provides technical documentation for the text-to-speech (TTS) tools available in Solace Agent Mesh."}),"\n",(0,s.jsx)(n.h2,{id:"overview",children:"Overview"}),"\n",(0,s.jsxs)(n.p,{children:["The ",(0,s.jsx)(n.code,{children:"audio"})," tool group provides two primary TTS tools for generating high-quality audio artifacts:"]}),"\n",(0,s.jsxs)(n.ol,{children:["\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:(0,s.jsx)(n.code,{children:"text_to_speech"})}),": Converts a string of text to speech using a single voice, featuring intelligent tone selection."]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:(0,s.jsx)(n.code,{children:"multi_speaker_text_to_speech"})}),": Converts a conversational script, delineated by speaker, into a multi-speaker audio file."]}),"\n"]}),"\n",(0,s.jsx)(n.h2,{id:"setup-and-configuration",children:"Setup and Configuration"}),"\n",(0,s.jsx)(n.h3,{id:"prerequisites",children:"Prerequisites"}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"API Key"}),": A valid Google Gemini API key with access to the TTS model is required."]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Dependencies"}),": The ",(0,s.jsx)(n.code,{children:"pydub"})," library is necessary for audio processing and format conversion. It can be installed via ",(0,s.jsx)(n.code,{children:"pip install pydub"}),"."]}),"\n"]}),"\n",(0,s.jsx)(n.h3,{id:"basic-configuration",children:"Basic Configuration"}),"\n",(0,s.jsxs)(n.ol,{children:["\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Environment Variable"}),": The Gemini API key must be set as an environment variable.","\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-bash",children:'export GEMINI_API_KEY="your_gemini_api_key_here"\n'})}),"\n"]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Enablement"}),": The ",(0,s.jsx)(n.code,{children:"audio"})," tool group must be enabled in the agent's ",(0,s.jsx)(n.code,{children:"app_config.yml"}),".","\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-yaml",children:'tools:\n  - tool_type: builtin-group\n    group_name: "audio"\n'})}),"\n"]}),"\n"]}),"\n",(0,s.jsx)(n.h2,{id:"advanced-configuration",children:"Advanced Configuration"}),"\n",(0,s.jsxs)(n.p,{children:["You can exercise more granular control over the TTS tools by providing a ",(0,s.jsx)(n.code,{children:"tool_config"})," block for each tool in your ",(0,s.jsx)(n.code,{children:"app_config.yml"}),"."]}),"\n",(0,s.jsxs)(n.h3,{id:"text_to_speech-configuration",children:[(0,s.jsx)(n.code,{children:"text_to_speech"})," Configuration"]}),"\n",(0,s.jsx)(n.p,{children:"This example shows how to set a default voice and define the mapping between tones and specific voice models."}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-yaml",children:'- tool_type: builtin\n  tool_name: "text_to_speech"\n  tool_config:\n    gemini_api_key: ${GEMINI_API_KEY}\n    model: "gemini-2.5-flash-preview-tts"\n    voice_name: "Kore"  # Default voice if no tone is matched\n    language: "en-US"   # Default language\n    output_format: "mp3"\n    # Voice selection by tone mapping\n    voice_tone_mapping:\n      bright: ["Zephyr", "Autonoe"]\n      upbeat: ["Puck", "Laomedeia"]\n      informative: ["Charon", "Rasalgethi"]\n      firm: ["Kore", "Orus", "Alnilam"]\n      friendly: ["Achird"]\n      casual: ["Zubenelgenubi"]\n      warm: ["Sulafar"]\n'})}),"\n",(0,s.jsxs)(n.h3,{id:"multi_speaker_text_to_speech-configuration",children:[(0,s.jsx)(n.code,{children:"multi_speaker_text_to_speech"})," Configuration"]}),"\n",(0,s.jsx)(n.p,{children:"This example defines default voice configurations for up to five speakers."}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-yaml",children:'- tool_type: builtin\n  tool_name: "multi_speaker_text_to_speech"\n  tool_config:\n    gemini_api_key: ${GEMINI_API_KEY}\n    model: "gemini-2.5-flash-preview-tts"\n    language: "en-US"\n    output_format: "mp3"\n    # Default speaker voice configurations\n    default_speakers:\n      - { name: "Speaker1", voice: "Kore", tone: "firm" }\n      - { name: "Speaker2", voice: "Puck", tone: "upbeat" }\n      - { name: "Speaker3", voice: "Charon", tone: "informative" }\n      - { name: "Speaker4", voice: "Achird", tone: "friendly" }\n      - { name: "Speaker5", voice: "Sulafar", tone: "warm" }\n    # The voice_tone_mapping can also be included here\n'})}),"\n",(0,s.jsx)(n.h2,{id:"features",children:"Features"}),"\n",(0,s.jsx)(n.h3,{id:"intelligent-tone-selection",children:"Intelligent Tone Selection"}),"\n",(0,s.jsx)(n.p,{children:"The system supports tone-based voice selection, allowing for dynamic voice choice based on desired emotional or stylistic output, rather than explicit voice names."}),"\n",(0,s.jsxs)(n.p,{children:[(0,s.jsx)(n.strong,{children:"Available Tones"}),":\n",(0,s.jsx)(n.code,{children:"bright"}),", ",(0,s.jsx)(n.code,{children:"upbeat"}),", ",(0,s.jsx)(n.code,{children:"informative"}),", ",(0,s.jsx)(n.code,{children:"firm"}),", ",(0,s.jsx)(n.code,{children:"excitable"}),", ",(0,s.jsx)(n.code,{children:"youthful"}),", ",(0,s.jsx)(n.code,{children:"breezy"}),", ",(0,s.jsx)(n.code,{children:"easy-going"}),", ",(0,s.jsx)(n.code,{children:"breathy"}),", ",(0,s.jsx)(n.code,{children:"clear"}),", ",(0,s.jsx)(n.code,{children:"smooth"}),", ",(0,s.jsx)(n.code,{children:"gravelly"}),", ",(0,s.jsx)(n.code,{children:"soft"}),", ",(0,s.jsx)(n.code,{children:"even"}),", ",(0,s.jsx)(n.code,{children:"mature"}),", ",(0,s.jsx)(n.code,{children:"forward"}),", ",(0,s.jsx)(n.code,{children:"friendly"}),", ",(0,s.jsx)(n.code,{children:"casual"}),", ",(0,s.jsx)(n.code,{children:"gentle"}),", ",(0,s.jsx)(n.code,{children:"lively"}),", ",(0,s.jsx)(n.code,{children:"knowledgeable"}),", ",(0,s.jsx)(n.code,{children:"warm"})]}),"\n",(0,s.jsxs)(n.p,{children:[(0,s.jsx)(n.strong,{children:"Tone Aliases"}),":"]}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.code,{children:"professional"})," \u2192 ",(0,s.jsx)(n.code,{children:"firm"})]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.code,{children:"cheerful"})," \u2192 ",(0,s.jsx)(n.code,{children:"upbeat"})]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.code,{children:"calm"})," \u2192 ",(0,s.jsx)(n.code,{children:"soft"})]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.code,{children:"conversational"})," \u2192 ",(0,s.jsx)(n.code,{children:"casual"})]}),"\n"]}),"\n",(0,s.jsx)(n.h3,{id:"multi-language-support",children:"Multi-Language Support"}),"\n",(0,s.jsxs)(n.p,{children:["The tools support over 25 languages, specified via BCP-47 language codes (for example, ",(0,s.jsx)(n.code,{children:"en-US"}),", ",(0,s.jsx)(n.code,{children:"fr-FR"}),", ",(0,s.jsx)(n.code,{children:"es-US"}),", ",(0,s.jsx)(n.code,{children:"ja-JP"}),")."]}),"\n",(0,s.jsx)(n.h2,{id:"usage-examples",children:"Usage Examples"}),"\n",(0,s.jsxs)(n.h3,{id:"single-voice-text-to-speech-text_to_speech",children:["Single-Voice Text-to-Speech (",(0,s.jsx)(n.code,{children:"text_to_speech"}),")"]}),"\n",(0,s.jsx)(n.p,{children:(0,s.jsx)(n.strong,{children:"Basic Usage"})}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{children:'Convert the following text to speech: "Welcome to the technical briefing on artificial intelligence."\n'})}),"\n",(0,s.jsx)(n.p,{children:(0,s.jsx)(n.strong,{children:"With Tone Selection"})}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{children:'Convert this text to speech with a professional tone: "Thank you for joining today\'s technical review."\n'})}),"\n",(0,s.jsxs)(n.h3,{id:"multi-speaker-text-to-speech-multi_speaker_text_to_speech",children:["Multi-Speaker Text-to-Speech (",(0,s.jsx)(n.code,{children:"multi_speaker_text_to_speech"}),")"]}),"\n",(0,s.jsx)(n.p,{children:(0,s.jsx)(n.strong,{children:"Basic Conversation"})}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{children:"Convert this conversation to speech:\nSpeaker1: Welcome to the podcast.\nSpeaker2: Thank you for having me.\n"})}),"\n",(0,s.jsx)(n.p,{children:(0,s.jsx)(n.strong,{children:"With Custom Speaker Tones"})}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{children:"Convert this conversation using specific tones for each speaker:\n- Speaker1 should sound professional\n- Speaker2 should sound friendly\n\nConversation:\nSpeaker1: Good morning, this is the daily security briefing.\nSpeaker2: Hi everyone, let's review the agenda for today's session.\n"})}),"\n",(0,s.jsx)(n.h2,{id:"tool-reference",children:"Tool Reference"}),"\n",(0,s.jsx)(n.h3,{id:"text_to_speech",children:(0,s.jsx)(n.code,{children:"text_to_speech"})}),"\n",(0,s.jsxs)(n.table,{children:[(0,s.jsx)(n.thead,{children:(0,s.jsxs)(n.tr,{children:[(0,s.jsx)(n.th,{children:"Parameter"}),(0,s.jsx)(n.th,{children:"Type"}),(0,s.jsx)(n.th,{children:"Description"})]})}),(0,s.jsxs)(n.tbody,{children:[(0,s.jsxs)(n.tr,{children:[(0,s.jsx)(n.td,{children:(0,s.jsx)(n.code,{children:"text"})}),(0,s.jsx)(n.td,{children:"string"}),(0,s.jsx)(n.td,{children:"The text to be synthesized."})]}),(0,s.jsxs)(n.tr,{children:[(0,s.jsx)(n.td,{children:(0,s.jsx)(n.code,{children:"output_filename"})}),(0,s.jsx)(n.td,{children:"string"}),(0,s.jsx)(n.td,{children:"(Optional) A custom MP3 filename."})]}),(0,s.jsxs)(n.tr,{children:[(0,s.jsx)(n.td,{children:(0,s.jsx)(n.code,{children:"voice_name"})}),(0,s.jsx)(n.td,{children:"string"}),(0,s.jsx)(n.td,{children:"(Optional) A specific voice name to use."})]}),(0,s.jsxs)(n.tr,{children:[(0,s.jsx)(n.td,{children:(0,s.jsx)(n.code,{children:"tone"})}),(0,s.jsx)(n.td,{children:"string"}),(0,s.jsx)(n.td,{children:"(Optional) The desired voice tone."})]}),(0,s.jsxs)(n.tr,{children:[(0,s.jsx)(n.td,{children:(0,s.jsx)(n.code,{children:"language"})}),(0,s.jsx)(n.td,{children:"string"}),(0,s.jsx)(n.td,{children:"(Optional) The BCP-47 language code."})]})]})]}),"\n",(0,s.jsx)(n.h3,{id:"multi_speaker_text_to_speech",children:(0,s.jsx)(n.code,{children:"multi_speaker_text_to_speech"})}),"\n",(0,s.jsxs)(n.table,{children:[(0,s.jsx)(n.thead,{children:(0,s.jsxs)(n.tr,{children:[(0,s.jsx)(n.th,{children:"Parameter"}),(0,s.jsx)(n.th,{children:"Type"}),(0,s.jsx)(n.th,{children:"Description"})]})}),(0,s.jsxs)(n.tbody,{children:[(0,s.jsxs)(n.tr,{children:[(0,s.jsx)(n.td,{children:(0,s.jsx)(n.code,{children:"conversation_text"})}),(0,s.jsx)(n.td,{children:"string"}),(0,s.jsxs)(n.td,{children:["A string of text with speaker labels (for example, ",(0,s.jsx)(n.code,{children:"S1: ..."}),")."]})]}),(0,s.jsxs)(n.tr,{children:[(0,s.jsx)(n.td,{children:(0,s.jsx)(n.code,{children:"output_filename"})}),(0,s.jsx)(n.td,{children:"string"}),(0,s.jsx)(n.td,{children:"(Optional) A custom MP3 filename."})]}),(0,s.jsxs)(n.tr,{children:[(0,s.jsx)(n.td,{children:(0,s.jsx)(n.code,{children:"speaker_configs"})}),(0,s.jsx)(n.td,{children:"array"}),(0,s.jsx)(n.td,{children:"(Optional) An array to configure tones for specific speakers."})]}),(0,s.jsxs)(n.tr,{children:[(0,s.jsx)(n.td,{children:(0,s.jsx)(n.code,{children:"language"})}),(0,s.jsx)(n.td,{children:"string"}),(0,s.jsx)(n.td,{children:"(Optional) The BCP-47 language code."})]})]})]}),"\n",(0,s.jsx)(n.h2,{id:"output-and-metadata",children:"Output and Metadata"}),"\n",(0,s.jsx)(n.p,{children:"Both tools generate an MP3 audio artifact that includes a rich set of metadata:"}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsx)(n.li,{children:"The source text (or a truncated version for long inputs)"}),"\n",(0,s.jsx)(n.li,{children:"The voice(s) and language used for synthesis"}),"\n",(0,s.jsx)(n.li,{children:"The generation timestamp and the specific tool invoked"}),"\n",(0,s.jsx)(n.li,{children:"The requested tone and any speaker-specific configurations"}),"\n"]}),"\n",(0,s.jsx)(n.h2,{id:"troubleshooting",children:"Troubleshooting"}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:(0,s.jsx)(n.code,{children:"Error: GEMINI_API_KEY is required"})}),": This indicates that the ",(0,s.jsx)(n.code,{children:"GEMINI_API_KEY"})," environment variable has not been set correctly."]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:(0,s.jsx)(n.code,{children:"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."]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:(0,s.jsx)(n.code,{children:"Error: Failed to convert WAV to MP3"})}),": This typically indicates that ",(0,s.jsx)(n.code,{children:"pydub"})," is not installed or that the underlying system is missing necessary audio codecs (for example, ",(0,s.jsx)(n.code,{children:"ffmpeg"}),")."]}),"\n"]})]})}function h(e={}){const{wrapper:n}={...(0,o.R)(),...e.components};return n?(0,s.jsx)(n,{...e,children:(0,s.jsx)(a,{...e})}):a(e)}},8453:(e,n,i)=>{i.d(n,{R:()=>l,x:()=>r});var t=i(6540);const s={},o=t.createContext(s);function l(e){const n=t.useContext(o);return t.useMemo((function(){return"function"==typeof e?e(n):{...n,...e}}),[n,e])}function r(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(s):e.components||s:l(e.components),t.createElement(o.Provider,{value:n},e.children)}}}]);

solace_agent_mesh/assets/docs/assets/js/166ab619.e27886d9.js

@@ -1 +0,0 @@
-"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[515],{644:(e,s,t)=>{t.r(s),t.d(s,{assets:()=>c,contentTitle:()=>a,default:()=>h,frontMatter:()=>o,metadata:()=>n,toc:()=>l});const n=JSON.parse('{"id":"documentation/concepts/architecture","title":"Architecture","description":"Overview","source":"@site/docs/documentation/concepts/architecture.md","sourceDirName":"documentation/concepts","slug":"/documentation/concepts/architecture","permalink":"/solace-agent-mesh/docs/documentation/concepts/architecture","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/concepts/architecture.md","tags":[],"version":"current","sidebarPosition":4,"frontMatter":{"title":"Architecture","sidebar_position":4},"sidebar":"docSidebar","previous":{"title":"LLM Models","permalink":"/solace-agent-mesh/docs/documentation/getting-started/configurations/litellm_models"},"next":{"title":"Solace Agent Mesh CLI","permalink":"/solace-agent-mesh/docs/documentation/concepts/cli"}}');var i=t(4848),r=t(8453);const o={title:"Architecture",sidebar_position:4},a="Solace Agent Mesh Architecture",c={},l=[{value:"Overview",id:"overview",level:2},{value:"Architectural Principles",id:"architectural-principles",level:2},{value:"System Components",id:"system-components",level:2},{value:"Solace Event Broker",id:"solace-event-broker",level:3},{value:"Gateways",id:"gateways",level:3},{value:"Agent Hosts",id:"agent-hosts",level:3},{value:"Agents",id:"agents",level:3},{value:"Key Architectural Flows",id:"key-architectural-flows",level:2},{value:"User Task Processing Flow",id:"user-task-processing-flow",level:3},{value:"Agent-to-Agent Delegation Flow",id:"agent-to-agent-delegation-flow",level:3},{value:"Agent Discovery Flow",id:"agent-discovery-flow",level:3},{value:"A2A Protocol and Topic Structure",id:"a2a-protocol-and-topic-structure",level:2}];function d(e){const s={code:"code",h1:"h1",h2:"h2",h3:"h3",header:"header",li:"li",mermaid:"mermaid",ol:"ol",p:"p",strong:"strong",table:"table",tbody:"tbody",td:"td",th:"th",thead:"thead",tr:"tr",ul:"ul",...(0,r.R)(),...e.components};return(0,i.jsxs)(i.Fragment,{children:[(0,i.jsx)(s.header,{children:(0,i.jsx)(s.h1,{id:"solace-agent-mesh-architecture",children:"Solace Agent Mesh Architecture"})}),"\n",(0,i.jsx)(s.h2,{id:"overview",children:"Overview"}),"\n",(0,i.jsx)(s.p,{children:"Solace Agent Mesh is an event-driven framework for creating a distributed ecosystem of collaborative AI agents. The architecture is designed to decouple agent logic from communication and orchestration, enabling scalability, resilience, and modularity."}),"\n",(0,i.jsx)(s.p,{children:"It integrates three primary technologies:"}),"\n",(0,i.jsxs)(s.ul,{children:["\n",(0,i.jsxs)(s.li,{children:[(0,i.jsx)(s.strong,{children:"Solace Event Broker"}),": Provides the messaging fabric for all asynchronous communication, utilizing topic-based routing for the Agent-to-Agent (A2A) protocol."]}),"\n",(0,i.jsxs)(s.li,{children:[(0,i.jsx)(s.strong,{children:"Solace AI Connector (SAC)"}),": Serves as the runtime environment for hosting and managing the lifecycle of all system components (Agents and Gateways)."]}),"\n",(0,i.jsxs)(s.li,{children:[(0,i.jsx)(s.strong,{children:"Google Agent Development Kit (ADK)"}),": Provides the core logic for individual agents, including LLM interaction, tool execution, and state management."]}),"\n"]}),"\n",(0,i.jsx)(s.h2,{id:"architectural-principles",children:"Architectural Principles"}),"\n",(0,i.jsx)(s.p,{children:"The design of Solace Agent Mesh is founded on several key architectural principles:"}),"\n",(0,i.jsxs)(s.ul,{children:["\n",(0,i.jsxs)(s.li,{children:[(0,i.jsx)(s.strong,{children:"Event-Driven Architecture (EDA)"}),": All interactions between major components are asynchronous and mediated by the event broker. This eliminates direct dependencies, allowing components to be developed, deployed, and scaled independently."]}),"\n",(0,i.jsxs)(s.li,{children:[(0,i.jsx)(s.strong,{children:"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."]}),"\n",(0,i.jsxs)(s.li,{children:[(0,i.jsx)(s.strong,{children:"Scalability and Resilience"}),": The architecture supports horizontal scaling of Agent Hosts and Gateways. The event broker provides fault tolerance and guaranteed message delivery, ensuring system resilience even if individual components fail or are restarted."]}),"\n"]}),"\n",(0,i.jsx)(s.h2,{id:"system-components",children:"System Components"}),"\n",(0,i.jsx)(s.p,{children:"The architecture comprises several distinct types of components that interact through the Solace broker."}),"\n",(0,i.jsx)(s.mermaid,{value:'graph TD\n    subgraph External Systems\n        direction TB\n        UserInterfaces["User Interfaces<br/>(Web UI, Slack, CLI)"]\n        APIs["External Systems & APIs"]\n    end\n\n    subgraph SolaceAgentMesh [Solace Agent Mesh]\n        direction TB\n        subgraph Gateways\n            WebUIGateway["Web UI Gateway"]\n            CustomGateway["Custom Gateway"]\n        end\n\n        Broker["Solace Broker<br/>(A2A Protocol over Topics)"]\n\n        subgraph AgentHosts ["Agent Hosts (SAC Applications)"]\n            AgentHost1["Agent Host<br/>(Runs Agent A)"]\n            AgentHost2["Agent Host<br/>(Runs Agent B)"]\n            AgentHostN["..."]\n        end\n    end\n\n    subgraph BackendServices [Backend Services & Tools]\n        LLM["Large Language Models"]\n        CustomTools["Custom Tools<br/>(Python, MCP)"]\n        DataStores["Databases & Vector Stores"]\n        ArtifactService["Artifact Service<br/>(Filesystem, Cloud Storage)"]\n    end\n\n    %% Connections\n    UserInterfaces -- Interacts with --\x3e Gateways\n    APIs -- Interacts with --\x3e Gateways\n\n    Gateways -- Pub/Sub --\x3e Broker\n    AgentHosts -- Pub/Sub --\x3e Broker\n\n    AgentHost1 -- Uses --\x3e LLM\n    AgentHost1 -- Uses --\x3e CustomTools\n    AgentHost1 -- Uses --\x3e DataStores\n    AgentHost1 -- Uses --\x3e ArtifactService\n\n    AgentHost2 -- Uses --\x3e LLM\n    AgentHost2 -- Uses --\x3e CustomTools\n    AgentHost2 -- Uses --\x3e DataStores\n    AgentHost2 -- Uses --\x3e ArtifactService\n\n    %% Styling\n    classDef external fill:#E3F2FD,stroke:#1976D2,stroke-width:2px,color:#0D47A1;\n    classDef gateway fill:#E8F5E8,stroke:#388E3C,stroke-width:2px,color:#1B5E20;\n    classDef mesh fill:#FFF8E1,stroke:#F57C00,stroke-width:2px,color:#E65100;\n    classDef agent fill:#FFF3E0,stroke:#FF9800,stroke-width:2px,color:#E65100;\n    classDef service fill:#F3E5F5,stroke:#7B1FA2,stroke-width:2px,color:#4A148C;\n\n    class UserInterfaces,APIs external;\n    class WebUIGateway,CustomGateway gateway;\n    class Broker,SolaceAgentMesh mesh;\n    class AgentHosts,AgentHost1,AgentHost2,AgentHostN agent;\n    class LLM,CustomTools,DataStores,ArtifactService service;'}),"\n",(0,i.jsx)(s.h3,{id:"solace-event-broker",children:"Solace Event Broker"}),"\n",(0,i.jsx)(s.p,{children:"The broker is the central messaging fabric. It is responsible for routing all A2A protocol messages between components using a hierarchical topic structure. This enables patterns like request/reply, streaming updates, and publish/subscribe for discovery."}),"\n",(0,i.jsx)(s.h3,{id:"gateways",children:"Gateways"}),"\n",(0,i.jsx)(s.p,{children:"Gateways are SAC applications that act as bridges between external systems and the agent mesh. Their primary responsibilities are:"}),"\n",(0,i.jsxs)(s.ul,{children:["\n",(0,i.jsxs)(s.li,{children:[(0,i.jsx)(s.strong,{children:"Protocol Translation"}),": Convert external protocols (for example, HTTP, WebSockets, Slack RTM) into the standardized A2A protocol, and vice-versa."]}),"\n",(0,i.jsxs)(s.li,{children:[(0,i.jsx)(s.strong,{children:"Authentication and Authorization"}),": Authenticate incoming requests and, using a pluggable ",(0,i.jsx)(s.code,{children:"AuthorizationService"}),", retrieve the user's permission scopes."]}),"\n",(0,i.jsxs)(s.li,{children:[(0,i.jsx)(s.strong,{children:"Session Management"}),": Manage external user sessions and map them to A2A task lifecycles."]}),"\n",(0,i.jsxs)(s.li,{children:[(0,i.jsx)(s.strong,{children:"Response Handling"}),": Receive asynchronous A2A responses and status updates from agents and deliver them to the external client."]}),"\n"]}),"\n",(0,i.jsxs)(s.p,{children:["The ",(0,i.jsx)(s.strong,{children:"Gateway Development Kit (GDK)"})," provides ",(0,i.jsx)(s.code,{children:"BaseGatewayApp"})," and ",(0,i.jsx)(s.code,{children:"BaseGatewayComponent"})," classes to abstract common gateway logic, such as A2A protocol handling, agent discovery, and late-stage embed resolution, simplifying the creation of new gateways."]}),"\n",(0,i.jsx)(s.h3,{id:"agent-hosts",children:"Agent Hosts"}),"\n",(0,i.jsxs)(s.p,{children:["An Agent Host is a SAC application (",(0,i.jsx)(s.code,{children:"SamAgentApp"}),") that hosts a single ADK-based agent. Its key architectural functions include:"]}),"\n",(0,i.jsxs)(s.ul,{children:["\n",(0,i.jsxs)(s.li,{children:[(0,i.jsx)(s.strong,{children:"Hosting the ADK Runtime"}),": It manages the lifecycle of the ADK ",(0,i.jsx)(s.code,{children:"Runner"})," and ",(0,i.jsx)(s.code,{children:"LlmAgent"}),"."]}),"\n",(0,i.jsxs)(s.li,{children:[(0,i.jsx)(s.strong,{children:"A2A Protocol Handling"}),": The internal ",(0,i.jsx)(s.code,{children:"SamAgentComponent"})," translates incoming A2A requests into ADK ",(0,i.jsx)(s.code,{children:"Task"})," objects and converts ADK ",(0,i.jsx)(s.code,{children:"Event"})," objects into outgoing A2A ",(0,i.jsx)(s.code,{children:"TaskStatusUpdateEvent"}),", ",(0,i.jsx)(s.code,{children:"TaskArtifactUpdateEvent"}),", or final response messages."]}),"\n",(0,i.jsxs)(s.li,{children:[(0,i.jsx)(s.strong,{children:"Scope Enforcement"}),": It extracts permission scopes from incoming message properties and filters the agent's available tools accordingly."]}),"\n",(0,i.jsxs)(s.li,{children:[(0,i.jsx)(s.strong,{children:"Service Initialization"}),": It initializes ADK services like the ",(0,i.jsx)(s.code,{children:"ArtifactService"})," and ",(0,i.jsx)(s.code,{children:"MemoryService"})," based on its configuration."]}),"\n"]}),"\n",(0,i.jsx)(s.h3,{id:"agents",children:"Agents"}),"\n",(0,i.jsx)(s.p,{children:"An agent is the logical entity within an Agent Host that performs tasks. It is defined by its configuration, which includes:"}),"\n",(0,i.jsxs)(s.ul,{children:["\n",(0,i.jsxs)(s.li,{children:[(0,i.jsx)(s.strong,{children:"Instructions"}),": The base prompt that defines its persona, capabilities, and constraints."]}),"\n",(0,i.jsxs)(s.li,{children:[(0,i.jsx)(s.strong,{children:"LLM Configuration"}),": The specific large language model to use."]}),"\n",(0,i.jsxs)(s.li,{children:[(0,i.jsx)(s.strong,{children:"Toolset"}),": A collection of available tools, which can be built-in, custom Python functions, or MCP Toolsets."]}),"\n"]}),"\n",(0,i.jsx)(s.h2,{id:"key-architectural-flows",children:"Key Architectural Flows"}),"\n",(0,i.jsx)(s.h3,{id:"user-task-processing-flow",children:"User Task Processing Flow"}),"\n",(0,i.jsxs)(s.ol,{children:["\n",(0,i.jsxs)(s.li,{children:["An external client sends a request to a ",(0,i.jsx)(s.strong,{children:"Gateway"}),"."]}),"\n",(0,i.jsxs)(s.li,{children:["The Gateway authenticates the request, retrieves the user's permission scopes via its ",(0,i.jsx)(s.code,{children:"AuthorizationService"}),", and translates the request into an A2A task message. It includes the scopes in the Solace message's user properties."]}),"\n",(0,i.jsxs)(s.li,{children:["The Gateway publishes the message to the target agent's request topic on the ",(0,i.jsx)(s.strong,{children:"Solace Broker"}),"."]}),"\n",(0,i.jsxs)(s.li,{children:["The corresponding ",(0,i.jsx)(s.strong,{children:"Agent Host"})," receives the message. The ",(0,i.jsx)(s.code,{children:"SamAgentComponent"})," extracts the scopes and initiates an ADK task."]}),"\n",(0,i.jsxs)(s.li,{children:["The ADK ",(0,i.jsx)(s.code,{children:"LlmAgent"})," processes the task. Before invoking the LLM, a ",(0,i.jsx)(s.code,{children:"before_model_callback"})," filters the available tools based on the user's scopes."]}),"\n",(0,i.jsxs)(s.li,{children:["As the agent executes, the ",(0,i.jsx)(s.code,{children:"SamAgentComponent"})," translates ADK events into A2A status and artifact update messages, publishing them to the originating Gateway's status topic."]}),"\n",(0,i.jsxs)(s.li,{children:["The Gateway receives these streaming updates, performs any necessary late-stage processing (like resolving ",(0,i.jsx)(s.code,{children:"artifact_content"})," embeds), and forwards them to the client."]}),"\n",(0,i.jsx)(s.li,{children:"Upon completion, the Agent Host sends a final A2A response message to the Gateway, which delivers it to the client."}),"\n"]}),"\n",(0,i.jsx)(s.h3,{id:"agent-to-agent-delegation-flow",children:"Agent-to-Agent Delegation Flow"}),"\n",(0,i.jsxs)(s.ol,{children:["\n",(0,i.jsxs)(s.li,{children:[(0,i.jsx)(s.strong,{children:"Agent A"}),", while processing a task, determines a sub-task should be delegated to ",(0,i.jsx)(s.strong,{children:"Agent B"}),"."]}),"\n",(0,i.jsxs)(s.li,{children:["Agent A uses its ",(0,i.jsx)(s.code,{children:"PeerAgentTool"})," to construct a new A2A task request for Agent B. It propagates the original user's permission scopes to maintain the security context."]}),"\n",(0,i.jsx)(s.li,{children:"The request is published to Agent B's request topic."}),"\n",(0,i.jsxs)(s.li,{children:[(0,i.jsx)(s.strong,{children:"Agent B's Host"})," receives and processes the sub-task, enforcing the propagated scopes on its own toolset."]}),"\n",(0,i.jsx)(s.li,{children:"Agent B sends status updates and a final response to topics designated by Agent A."}),"\n",(0,i.jsx)(s.li,{children:"Agent A receives the results and incorporates them into its ongoing task."}),"\n"]}),"\n",(0,i.jsx)(s.h3,{id:"agent-discovery-flow",children:"Agent Discovery Flow"}),"\n",(0,i.jsxs)(s.ol,{children:["\n",(0,i.jsxs)(s.li,{children:["On startup and periodically, each ",(0,i.jsx)(s.strong,{children:"Agent Host"})," publishes an ",(0,i.jsx)(s.code,{children:"AgentCard"})," (a JSON document describing its agent's capabilities) to a well-known discovery topic (for example, ",(0,i.jsx)(s.code,{children:"{namespace}/a2a/v1/discovery/agentcards"}),")."]}),"\n",(0,i.jsxs)(s.li,{children:[(0,i.jsx)(s.strong,{children:"Gateways"})," and other ",(0,i.jsx)(s.strong,{children:"Agent Hosts"})," subscribe to this topic."]}),"\n",(0,i.jsxs)(s.li,{children:["Upon receiving an ",(0,i.jsx)(s.code,{children:"AgentCard"}),", components update their local ",(0,i.jsx)(s.code,{children:"AgentRegistry"}),", making them aware of available agents for user selection (at the Gateway) or peer delegation (at the Agent)."]}),"\n"]}),"\n",(0,i.jsx)(s.h2,{id:"a2a-protocol-and-topic-structure",children:"A2A Protocol and Topic Structure"}),"\n",(0,i.jsx)(s.p,{children:"The A2A protocol is based on JSON-RPC 2.0 and defines the message formats for all interactions. Communication is routed via a hierarchical topic structure on the Solace broker."}),"\n",(0,i.jsxs)(s.table,{children:[(0,i.jsx)(s.thead,{children:(0,i.jsxs)(s.tr,{children:[(0,i.jsx)(s.th,{children:"Purpose"}),(0,i.jsx)(s.th,{children:"Topic Pattern"})]})}),(0,i.jsxs)(s.tbody,{children:[(0,i.jsxs)(s.tr,{children:[(0,i.jsx)(s.td,{children:(0,i.jsx)(s.strong,{children:"Agent Discovery"})}),(0,i.jsx)(s.td,{children:(0,i.jsx)(s.code,{children:"{namespace}/a2a/v1/discovery/agentcards"})})]}),(0,i.jsxs)(s.tr,{children:[(0,i.jsx)(s.td,{children:(0,i.jsx)(s.strong,{children:"Task Requests"})}),(0,i.jsx)(s.td,{children:(0,i.jsx)(s.code,{children:"{namespace}/a2a/v1/agent/request/{target_agent_name}"})})]}),(0,i.jsxs)(s.tr,{children:[(0,i.jsx)(s.td,{children:(0,i.jsx)(s.strong,{children:"Status Updates"})}),(0,i.jsx)(s.td,{children:(0,i.jsx)(s.code,{children:"{namespace}/a2a/v1/gateway/status/{gateway_id}/{task_id}"})})]}),(0,i.jsxs)(s.tr,{children:[(0,i.jsx)(s.td,{children:(0,i.jsx)(s.strong,{children:"Final Responses"})}),(0,i.jsx)(s.td,{children:(0,i.jsx)(s.code,{children:"{namespace}/a2a/v1/gateway/response/{gateway_id}/{task_id}"})})]}),(0,i.jsxs)(s.tr,{children:[(0,i.jsx)(s.td,{children:(0,i.jsx)(s.strong,{children:"Peer Delegation Status"})}),(0,i.jsx)(s.td,{children:(0,i.jsx)(s.code,{children:"{namespace}/a2a/v1/agent/status/{delegating_agent_name}/{sub_task_id}"})})]}),(0,i.jsxs)(s.tr,{children:[(0,i.jsx)(s.td,{children:(0,i.jsx)(s.strong,{children:"Peer Delegation Response"})}),(0,i.jsx)(s.td,{children:(0,i.jsx)(s.code,{children:"{namespace}/a2a/v1/agent/response/{delegating_agent_name}/{sub_task_id}"})})]})]})]}),"\n",(0,i.jsx)(s.p,{children:"This topic structure allows for precise, point-to-point routing in a decoupled, asynchronous environment."})]})}function h(e={}){const{wrapper:s}={...(0,r.R)(),...e.components};return s?(0,i.jsx)(s,{...e,children:(0,i.jsx)(d,{...e})}):d(e)}},8453:(e,s,t)=>{t.d(s,{R:()=>o,x:()=>a});var n=t(6540);const i={},r=n.createContext(i);function o(e){const s=n.useContext(r);return n.useMemo((function(){return"function"==typeof e?e(s):{...s,...e}}),[s,e])}function a(e){let s;return s=e.disableParentContext?"function"==typeof e.components?e.components(i):e.components||i:o(e.components),n.createElement(r.Provider,{value:s},e.children)}}}]);

solace_agent_mesh/assets/docs/assets/js/1c6e87d2.e056b7e0.js

@@ -1 +0,0 @@
-"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[2037],{6317:(e,n,s)=>{s.r(n),s.d(n,{assets:()=>a,contentTitle:()=>l,default:()=>g,frontMatter:()=>r,metadata:()=>i,toc:()=>d});const i=JSON.parse('{"id":"documentation/deployment/debugging","title":"Debugging","description":"Debugging issues in Solace Agent Mesh starts with identifying the problem. You can monitor your system to debug it more effectively. For more information, see Observability.","source":"@site/docs/documentation/deployment/debugging.md","sourceDirName":"documentation/deployment","slug":"/documentation/deployment/debugging","permalink":"/solace-agent-mesh/docs/documentation/deployment/debugging","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/deployment/debugging.md","tags":[],"version":"current","sidebarPosition":30,"frontMatter":{"title":"Debugging","sidebar_position":30},"sidebar":"docSidebar","previous":{"title":"Observability","permalink":"/solace-agent-mesh/docs/documentation/deployment/observability"},"next":{"title":"Build Your Own Agent","permalink":"/solace-agent-mesh/docs/documentation/tutorials/custom-agent"}}');var o=s(4848),t=s(8453);const r={title:"Debugging",sidebar_position:30},l="Debugging",a={},d=[{value:"Isolate Components",id:"isolate-components",level:2},{value:"Examine STIM Files",id:"examine-stim-files",level:2},{value:"Monitor Broker Activity",id:"monitor-broker-activity",level:2},{value:"Debug Mode",id:"debug-mode",level:2},{value:"Debugging in VSCode",id:"debugging-in-vscode",level:3},{value:"Invoke the Agent Directly",id:"invoke-the-agent-directly",level:2},{value:"Tools for Sending Messages",id:"tools-for-sending-messages",level:4},{value:"Message Format",id:"message-format",level:4},{value:"System Logs",id:"system-logs",level:2},{value:"Configuring Log Rotation",id:"configuring-log-rotation",level:3}];function c(e){const n={a:"a",code:"code",h1:"h1",h2:"h2",h3:"h3",h4:"h4",header:"header",li:"li",ol:"ol",p:"p",pre:"pre",strong:"strong",ul:"ul",...(0,t.R)(),...e.components};return(0,o.jsxs)(o.Fragment,{children:[(0,o.jsx)(n.header,{children:(0,o.jsx)(n.h1,{id:"debugging",children:"Debugging"})}),"\n",(0,o.jsxs)(n.p,{children:["Debugging issues in Solace Agent Mesh starts with identifying the problem. You can monitor your system to debug it more effectively. For more information, see ",(0,o.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/deployment/observability",children:"Observability"}),".\nThe following sections provide common debugging approaches to help you diagnose and resolve issues."]}),"\n",(0,o.jsx)(n.h2,{id:"isolate-components",children:"Isolate Components"}),"\n",(0,o.jsxs)(n.p,{children:["Running only the necessary components in isolation can help pinpoint issues. The ",(0,o.jsx)(n.code,{children:"run"})," Solace Agent Mesh CLI command allows you to specify which files to run."]}),"\n",(0,o.jsx)(n.p,{children:"For example:"}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-bash",children:"sam run configs/agents/my_tool_1.yaml configs/agents/my_tool_2.yaml\n"})}),"\n",(0,o.jsxs)(n.p,{children:["This command runs only the agents defined in ",(0,o.jsx)(n.code,{children:"my_tool_1.yaml"})," and ",(0,o.jsx)(n.code,{children:"my_tool_2.yaml"}),", reducing noise from unrelated components."]}),"\n",(0,o.jsx)(n.h2,{id:"examine-stim-files",children:"Examine STIM Files"}),"\n",(0,o.jsxs)(n.p,{children:[(0,o.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/deployment/observability#stimulus-logs",children:"STIM files"})," provide detailed traces of stimulus life cycles. If you have access to the storage location, you can inspect them to analyze message flows."]}),"\n",(0,o.jsxs)(n.p,{children:["Each ",(0,o.jsx)(n.code,{children:".stim"})," file contains all broker events related to a single stimulus, from the initial request to the final response."]}),"\n",(0,o.jsx)(n.h2,{id:"monitor-broker-activity",children:"Monitor Broker Activity"}),"\n",(0,o.jsxs)(n.p,{children:["For insights into message flows and event interactions, see ",(0,o.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/deployment/observability#broker-observability",children:"Broker Observability"}),"."]}),"\n",(0,o.jsx)(n.h2,{id:"debug-mode",children:"Debug Mode"}),"\n",(0,o.jsx)(n.p,{children:"Because Solace Agent Mesh is a Python-based framework, you can run it in debug mode using an IDE with breakpoints."}),"\n",(0,o.jsx)(n.h3,{id:"debugging-in-vscode",children:"Debugging in VSCode"}),"\n",(0,o.jsxs)(n.p,{children:["If you're using VSCode, configure debugging in ",(0,o.jsx)(n.code,{children:".vscode/launch.json"}),":"]}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-json",children:'{\n  "version": "0.2.0",\n  "configurations": [\n    {\n      "name": "sam-debug",\n      "type": "debugpy",\n      "request": "launch",\n      "module": "solace_agent_mesh.cli.main",\n      "console": "integratedTerminal",\n      "envFile": "${workspaceFolder}/.env",\n      "args": [\n        "run",\n        "configs/agents/main_orchestrator.yaml",\n        "configs/gateways/webui.yaml"\n        // Add any other components you want to run here\n      ],\n      "justMyCode": false\n    }\n  ]\n}\n'})}),"\n",(0,o.jsx)(n.p,{children:"To start debugging:"}),"\n",(0,o.jsxs)(n.ol,{children:["\n",(0,o.jsxs)(n.li,{children:["Open the ",(0,o.jsx)(n.strong,{children:"RUN AND DEBUG"})," panel on the left sidebar."]}),"\n",(0,o.jsxs)(n.li,{children:["Select ",(0,o.jsx)(n.code,{children:"sam-debug"})," from the dropdown."]}),"\n",(0,o.jsxs)(n.li,{children:["Click the ",(0,o.jsx)(n.strong,{children:"Play"})," to start in debug mode."]}),"\n"]}),"\n",(0,o.jsx)(n.p,{children:"Set breakpoints in your code to pause execution and inspect variable states."}),"\n",(0,o.jsx)(n.h2,{id:"invoke-the-agent-directly",children:"Invoke the Agent Directly"}),"\n",(0,o.jsx)(n.p,{children:"For debugging and testing, you can send direct messages to an agent by directly selecting the agent in the web UI agent dropdown or by using the Solace event broker. This requires specifying the appropriate topic, user properties, and payload."}),"\n",(0,o.jsx)(n.h4,{id:"tools-for-sending-messages",children:"Tools for Sending Messages"}),"\n",(0,o.jsxs)(n.ul,{children:["\n",(0,o.jsx)(n.li,{children:(0,o.jsx)(n.strong,{children:(0,o.jsx)(n.a,{href:"https://marketplace.visualstudio.com/items?itemName=solace-tools.solace-try-me-vsc-extension",children:"Solace Try Me VSCode Extension"})})}),"\n",(0,o.jsx)(n.li,{children:(0,o.jsx)(n.strong,{children:(0,o.jsx)(n.a,{href:"https://github.com/SolaceLabs/solace-tryme-cli",children:"Solace Try Me (STM) CLI Tool"})})}),"\n"]}),"\n",(0,o.jsx)(n.h4,{id:"message-format",children:"Message Format"}),"\n",(0,o.jsxs)(n.p,{children:[(0,o.jsx)(n.strong,{children:"Topic"}),":"]}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{children:"[NAME_SPACES]a2a/v1/agent/request/<agent_name>\n"})}),"\n",(0,o.jsxs)(n.p,{children:[(0,o.jsx)(n.strong,{children:"User Properties"}),":"]}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{children:"userId: test-0000\nclientId: test-0000\nreplyTo: [NAME_SPACES]a2a/v1/gateway/response/0000000/task-0000000\na2aUserConfig: {}\n"})}),"\n",(0,o.jsxs)(n.p,{children:[(0,o.jsx)(n.strong,{children:"Payload"}),":"]}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-json",children:'{\n    "jsonrpc": "2.0",\n    "id": "000000000",\n    "method": "tasks/sendSubscribe",\n    "params": {\n      "id": "task-0000000",\n      "sessionId": "web-session-00000000",\n      "message": {\n        "role": "user",\n        "parts": [\n          {\n            "type": "text",\n            "text": "Hello World!"\n          }\n        ]\n      },\n      "acceptedOutputModes": [\n        "text"\n      ],\n      "metadata": {\n        "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",\n        "response_format": "Responses should be clear, concise, and professionally toned. Format responses to the user in Markdown using appropriate formatting.\\n"\n      }\n  }\n}\n'})}),"\n",(0,o.jsxs)(n.p,{children:[(0,o.jsx)(n.strong,{children:"Response Topic"}),":"]}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{children:"[NAME_SPACES]a2a/v1/gateway/response/0000000/task-0000000\n"})}),"\n",(0,o.jsx)(n.p,{children:"By sending a request and observing the response, you can verify an agent's behavior in isolation, making it easier to identify issues."}),"\n",(0,o.jsx)(n.h2,{id:"system-logs",children:"System Logs"}),"\n",(0,o.jsxs)(n.p,{children:["System logs provide detailed insights into the system's behavior. The logging behavior is configured in the ",(0,o.jsx)(n.code,{children:"configs/logging_config.ini"})," file, which controls both console (STDOUT) and file-based logging."]}),"\n",(0,o.jsx)(n.p,{children:"By default, the system is configured to:"}),"\n",(0,o.jsxs)(n.ul,{children:["\n",(0,o.jsxs)(n.li,{children:["Output logs with a severity of ",(0,o.jsx)(n.code,{children:"INFO"})," and higher to the console (STDOUT)."]}),"\n",(0,o.jsxs)(n.li,{children:["Write more detailed logs with a severity of ",(0,o.jsx)(n.code,{children:"DEBUG"})," and higher to a rotating log file named ",(0,o.jsx)(n.code,{children:"sam.log"})," in the project's root directory."]}),"\n"]}),"\n",(0,o.jsx)(n.h3,{id:"configuring-log-rotation",children:"Configuring Log Rotation"}),"\n",(0,o.jsxs)(n.p,{children:["The log file rotation is managed by the ",(0,o.jsx)(n.code,{children:"rotatingFileHandler"})," in ",(0,o.jsx)(n.code,{children:"configs/logging_config.ini"}),". You can customize its behavior by modifying the ",(0,o.jsx)(n.code,{children:"args"})," line:"]}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-ini",children:"[handler_rotatingFileHandler]\nclass=logging.handlers.RotatingFileHandler\nlevel=DEBUG\nformatter=simpleFormatter\nargs=('sam.log', 'a', 52428800, 10)\n"})}),"\n",(0,o.jsxs)(n.p,{children:["The ",(0,o.jsx)(n.code,{children:"args"})," tuple is defined as follows:"]}),"\n",(0,o.jsxs)(n.ul,{children:["\n",(0,o.jsxs)(n.li,{children:[(0,o.jsx)(n.code,{children:"'sam.log'"}),": The name of the log file."]}),"\n",(0,o.jsxs)(n.li,{children:[(0,o.jsx)(n.code,{children:"'a'"}),": The file mode (append)."]}),"\n",(0,o.jsxs)(n.li,{children:[(0,o.jsx)(n.code,{children:"52428800"}),": The maximum size of the log file in bytes before it is rotated. In this case, it's 50 MB."]}),"\n",(0,o.jsxs)(n.li,{children:[(0,o.jsx)(n.code,{children:"10"}),": The number of backup log files to keep."]}),"\n"]}),"\n",(0,o.jsxs)(n.p,{children:["For example, to change the log file size to 20 MB and keep 5 backup files, you would modify the line to:\n",(0,o.jsx)(n.code,{children:"args=('sam.log', 'a', 20971520, 5)"})]}),"\n",(0,o.jsx)(n.p,{children:"This level of configuration allows you to manage log verbosity and disk space usage according to your needs."})]})}function g(e={}){const{wrapper:n}={...(0,t.R)(),...e.components};return n?(0,o.jsx)(n,{...e,children:(0,o.jsx)(c,{...e})}):c(e)}},8453:(e,n,s)=>{s.d(n,{R:()=>r,x:()=>l});var i=s(6540);const o={},t=i.createContext(o);function r(e){const n=i.useContext(t);return i.useMemo((function(){return"function"==typeof e?e(n):{...n,...e}}),[n,e])}function l(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(o):e.components||o:r(e.components),i.createElement(t.Provider,{value:n},e.children)}}}]);

solace_agent_mesh/assets/docs/assets/js/21ceee5f.3bf39250.js

@@ -1 +0,0 @@
-"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[8423],{8782:(e,n,t)=>{t.r(n),t.d(n,{assets:()=>c,contentTitle:()=>i,default:()=>h,frontMatter:()=>r,metadata:()=>s,toc:()=>l});const s=JSON.parse('{"id":"documentation/concepts/orchestrator","title":"Orchestrator","description":"The A2A (Agent-to-Agent) protocol is the communication backbone of Solace Agent Mesh that enables distributed agent coordination and workflow management. Unlike traditional centralized orchestration, the A2A protocol enables agents to discover each other, delegate tasks, and collaborate directly through standardized message patterns.","source":"@site/docs/documentation/concepts/orchestrator.md","sourceDirName":"documentation/concepts","slug":"/documentation/concepts/orchestrator","permalink":"/solace-agent-mesh/docs/documentation/concepts/orchestrator","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/concepts/orchestrator.md","tags":[],"version":"current","sidebarPosition":40,"frontMatter":{"title":"Orchestrator","sidebar_position":40},"sidebar":"docSidebar","previous":{"title":"Agents","permalink":"/solace-agent-mesh/docs/documentation/concepts/agents"},"next":{"title":"Plugins","permalink":"/solace-agent-mesh/docs/documentation/concepts/plugins"}}');var o=t(4848),a=t(8453);const r={title:"Orchestrator",sidebar_position:40},i="Orchestrator Agent",c={},l=[{value:"Key Functions",id:"key-functions",level:2}];function d(e){const n={admonition:"admonition",h1:"h1",h2:"h2",header:"header",li:"li",ol:"ol",p:"p",strong:"strong",ul:"ul",...(0,a.R)(),...e.components};return(0,o.jsxs)(o.Fragment,{children:[(0,o.jsx)(n.header,{children:(0,o.jsx)(n.h1,{id:"orchestrator-agent",children:"Orchestrator Agent"})}),"\n",(0,o.jsx)(n.p,{children:"The A2A (Agent-to-Agent) protocol is the communication backbone of Solace Agent Mesh that enables distributed agent coordination and workflow management. Unlike traditional centralized orchestration, the A2A protocol enables agents to discover each other, delegate tasks, and collaborate directly through standardized message patterns."}),"\n",(0,o.jsxs)(n.p,{children:["The advantages of centralized orchestration such as task breakdown and management, centralized point of communication and session management are still achieved in Solace Agent Mesh through a specialized agent called the ",(0,o.jsx)(n.strong,{children:"OrchestratorAgent"})," that acts as the central coordinator for complex workflows."]}),"\n",(0,o.jsx)(n.admonition,{title:"In one sentence",type:"tip",children:(0,o.jsx)(n.p,{children:"The OrchestratorAgent allows for a centralized workflow management in Solace Agent Mesh by coordinating tasks and communication between agents."})}),"\n",(0,o.jsx)(n.p,{children:"The system is not limited to a single orchestrator agent, and multiple orchestrator agents can be deployed to handle different workflows or domains. This allows for flexibility and scalability in managing complex tasks."}),"\n",(0,o.jsx)(n.h2,{id:"key-functions",children:"Key Functions"}),"\n",(0,o.jsx)(n.p,{children:"The orchestrator agent provides the following key functions:"}),"\n",(0,o.jsxs)(n.ol,{children:["\n",(0,o.jsxs)(n.li,{children:["\n",(0,o.jsxs)(n.p,{children:[(0,o.jsx)(n.strong,{children:"Request Analysis and Action Planning"}),":"]}),"\n",(0,o.jsxs)(n.ul,{children:["\n",(0,o.jsx)(n.li,{children:"Receives high-level goals or requests"}),"\n",(0,o.jsx)(n.li,{children:"Analyzes them in the context of available actions registered by agents in the system"}),"\n",(0,o.jsx)(n.li,{children:"Uses state-of-the-art generative AI techniques to plan a sequence of actions to fulfill the request"}),"\n"]}),"\n"]}),"\n",(0,o.jsxs)(n.li,{children:["\n",(0,o.jsxs)(n.p,{children:[(0,o.jsx)(n.strong,{children:"Task Creation and Distribution"}),":"]}),"\n",(0,o.jsxs)(n.ul,{children:["\n",(0,o.jsx)(n.li,{children:"Creates tasks based on the action plan"}),"\n",(0,o.jsx)(n.li,{children:"Distributes tasks to appropriate agents"}),"\n",(0,o.jsx)(n.li,{children:"Enables efficient parallel processing and optimal resource utilization"}),"\n"]}),"\n"]}),"\n",(0,o.jsxs)(n.li,{children:["\n",(0,o.jsxs)(n.p,{children:[(0,o.jsx)(n.strong,{children:"Workflow Management"}),":"]}),"\n",(0,o.jsxs)(n.ul,{children:["\n",(0,o.jsx)(n.li,{children:"Tracks outstanding tasks"}),"\n",(0,o.jsx)(n.li,{children:"Aggregates responses from various agents"}),"\n",(0,o.jsx)(n.li,{children:"Ensures all parts of a complex request are processed and combined coherently"}),"\n"]}),"\n"]}),"\n",(0,o.jsxs)(n.li,{children:["\n",(0,o.jsxs)(n.p,{children:[(0,o.jsx)(n.strong,{children:"Response Formatting"}),":"]}),"\n",(0,o.jsxs)(n.ul,{children:["\n",(0,o.jsx)(n.li,{children:"Formats aggregated responses suitable for the gateway"}),"\n",(0,o.jsx)(n.li,{children:"Ensures the final output meets the requirements of the specific use case or interface"}),"\n"]}),"\n"]}),"\n"]})]})}function h(e={}){const{wrapper:n}={...(0,a.R)(),...e.components};return n?(0,o.jsx)(n,{...e,children:(0,o.jsx)(d,{...e})}):d(e)}},8453:(e,n,t)=>{t.d(n,{R:()=>r,x:()=>i});var s=t(6540);const o={},a=s.createContext(o);function r(e){const n=s.useContext(a);return s.useMemo((function(){return"function"==typeof e?e(n):{...n,...e}}),[n,e])}function i(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(o):e.components||o:r(e.components),s.createElement(a.Provider,{value:n},e.children)}}}]);

solace_agent_mesh/assets/docs/assets/js/2a9cab12.2afaee76.js

@@ -1 +0,0 @@
-"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[3520],{8100:(e,a,n)=>{n.r(a),n.d(a,{assets:()=>l,contentTitle:()=>r,default:()=>h,frontMatter:()=>i,metadata:()=>t,toc:()=>c});const t=JSON.parse('{"id":"documentation/tutorials/sql-database","title":"SQL Database Integration","description":"This tutorial sets up a SQL database agent in Solace Agent Mesh, which allows the Solace Agent Mesh agent to answer natural language queries about a sample coffee company database. This tutorial provides some sample data to set up an SQLite database, but you can use the same approach to connect to other database types, such as MySQL or PostgreSQL.","source":"@site/docs/documentation/tutorials/sql-database.md","sourceDirName":"documentation/tutorials","slug":"/documentation/tutorials/sql-database","permalink":"/solace-agent-mesh/docs/documentation/tutorials/sql-database","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/tutorials/sql-database.md","tags":[],"version":"current","sidebarPosition":40,"frontMatter":{"title":"SQL Database Integration","sidebar_position":40},"sidebar":"docSidebar","previous":{"title":"Amazon Bedrock Agents","permalink":"/solace-agent-mesh/docs/documentation/tutorials/bedrock-agents"},"next":{"title":"MongoDB Integration","permalink":"/solace-agent-mesh/docs/documentation/tutorials/mongodb-integration"}}');var s=n(4848),o=n(8453);const i={title:"SQL Database Integration",sidebar_position:40},r="SQL Database Integration",l={},c=[{value:"Prerequisites",id:"prerequisites",level:2},{value:"Adding the SQL Database Plugin",id:"adding-the-sql-database-plugin",level:2},{value:"Downloading Example Data",id:"downloading-example-data",level:2},{value:"Using wget",id:"using-wget",level:4},{value:"Using curl",id:"using-curl",level:4},{value:"Configuring the Agent",id:"configuring-the-agent",level:2},{value:"Setting the Environment Variables",id:"setting-the-environment-variables",level:2},{value:"Running the Agent",id:"running-the-agent",level:2},{value:"Interacting with the Database",id:"interacting-with-the-database",level:2},{value:"Advanced Configuration",id:"advanced-configuration",level:2},{value:"Customizing the Agent Card",id:"customizing-the-agent-card",level:2},{value:"Key Agent Card Elements",id:"key-agent-card-elements",level:3},{value:"Example of a Well-Configured Agent Card",id:"example-of-a-well-configured-agent-card",level:3}];function d(e){const a={a:"a",code:"code",h1:"h1",h2:"h2",h3:"h3",h4:"h4",header:"header",li:"li",ol:"ol",p:"p",pre:"pre",strong:"strong",ul:"ul",...(0,o.R)(),...e.components};return(0,s.jsxs)(s.Fragment,{children:[(0,s.jsx)(a.header,{children:(0,s.jsx)(a.h1,{id:"sql-database-integration",children:"SQL Database Integration"})}),"\n",(0,s.jsx)(a.p,{children:"This tutorial sets up a SQL database agent in Solace Agent Mesh, which allows the Solace Agent Mesh agent to answer natural language queries about a sample coffee company database. This tutorial provides some sample data to set up an SQLite database, but you can use the same approach to connect to other database types, such as MySQL or PostgreSQL."}),"\n",(0,s.jsx)(a.h2,{id:"prerequisites",children:"Prerequisites"}),"\n",(0,s.jsx)(a.p,{children:"Before starting this tutorial, ensure that you have installed and configured Solace Agent Mesh:"}),"\n",(0,s.jsxs)(a.ul,{children:["\n",(0,s.jsx)(a.li,{children:(0,s.jsx)(a.a,{href:"/solace-agent-mesh/docs/documentation/getting-started/installation",children:"Installed Solace Agent Mesh and the Solace Agent Mesh CLI"})}),"\n",(0,s.jsx)(a.li,{children:(0,s.jsx)(a.a,{href:"/solace-agent-mesh/docs/documentation/getting-started/quick-start",children:"Created a new Solace Agent Mesh project"})}),"\n",(0,s.jsx)(a.li,{children:"Access to a SQL database (local or remote)"}),"\n"]}),"\n",(0,s.jsx)(a.h2,{id:"adding-the-sql-database-plugin",children:"Adding the SQL Database Plugin"}),"\n",(0,s.jsx)(a.p,{children:"Add the SQL Database plugin to your Solace Agent Mesh project:"}),"\n",(0,s.jsx)(a.pre,{children:(0,s.jsx)(a.code,{className:"language-sh",children:"sam plugin add abc-coffee-info --plugin sam-sql-database\n"})}),"\n",(0,s.jsxs)(a.p,{children:["You can use any name for your agent, in this tutorial we use ",(0,s.jsx)(a.code,{children:"abc-coffee-info"}),"."]}),"\n",(0,s.jsx)(a.p,{children:"This command:"}),"\n",(0,s.jsxs)(a.ul,{children:["\n",(0,s.jsxs)(a.li,{children:["Installs the ",(0,s.jsx)(a.code,{children:"sam-sql-database"})," plugin"]}),"\n",(0,s.jsxs)(a.li,{children:["Creates a new agent configuration file at ",(0,s.jsx)(a.code,{children:"configs/agents/abc-coffee-info.yaml"})]}),"\n"]}),"\n",(0,s.jsx)(a.h2,{id:"downloading-example-data",children:"Downloading Example Data"}),"\n",(0,s.jsx)(a.p,{children:"For this tutorial, you can use a sample SQLite database for a fictional coffee company called ABC Coffee Co."}),"\n",(0,s.jsx)(a.p,{children:"First, download the example data."}),"\n",(0,s.jsx)(a.p,{children:"You can either visit this link to download with your browser:"}),"\n",(0,s.jsx)(a.p,{children:(0,s.jsx)(a.a,{href:"https://github.com/SolaceLabs/solace-agent-mesh-core-plugins/raw/refs/heads/main/sam-sql-database/example-data/abc_coffee_co.zip",children:"https://github.com/SolaceLabs/solace-agent-mesh-core-plugins/raw/refs/heads/main/sam-sql-database/example-data/abc_coffee_co.zip"})}),"\n",(0,s.jsx)(a.p,{children:"Or you can use the command line to download the ZIP file:"}),"\n",(0,s.jsx)(a.h4,{id:"using-wget",children:"Using wget"}),"\n",(0,s.jsx)(a.pre,{children:(0,s.jsx)(a.code,{className:"language-sh",children:"wget https://github.com/SolaceLabs/solace-agent-mesh-core-plugins/raw/refs/heads/main/sam-sql-database/example-data/abc_coffee_co.zip\n"})}),"\n",(0,s.jsx)(a.h4,{id:"using-curl",children:"Using curl"}),"\n",(0,s.jsx)(a.pre,{children:(0,s.jsx)(a.code,{className:"language-sh",children:"curl -LO https://github.com/SolaceLabs/solace-agent-mesh-core-plugins/raw/refs/heads/main/sam-sql-database/example-data/abc_coffee_co.zip\n"})}),"\n",(0,s.jsx)(a.p,{children:"After downloading the ZIP file, extract it to a directory of your choice. You can use the following command to extract the ZIP file:"}),"\n",(0,s.jsx)(a.pre,{children:(0,s.jsx)(a.code,{className:"language-sh",children:"unzip abc_coffee_co.zip\n"})}),"\n",(0,s.jsx)(a.h2,{id:"configuring-the-agent",children:"Configuring the Agent"}),"\n",(0,s.jsxs)(a.p,{children:["Now, update the agent configuration to use the SQLite database and import the CSV files.\nOpen the ",(0,s.jsx)(a.code,{children:"configs/agents/abc-coffee-info.yaml"})," file and modify the ",(0,s.jsx)(a.code,{children:"agent_init_function.config"})," section to specify the CSV directory."]}),"\n",(0,s.jsx)(a.p,{children:"Here is what you need to modify in the configuration file:"}),"\n",(0,s.jsx)(a.pre,{children:(0,s.jsx)(a.code,{className:"language-yaml",children:'# Find the agent_init_function section and update the config:\nagent_init_function:\n  module: "sam_sql_database.lifecycle"\n  name: "initialize_sql_agent"\n  config:\n    db_type: "${ABC_COFFEE_INFO_DB_TYPE}"\n    db_name: "${ABC_COFFEE_INFO_DB_NAME}"\n    database_purpose: "${ABC_COFFEE_INFO_DB_PURPOSE}"\n    data_description: "${ABC_COFFEE_INFO_DB_DESCRIPTION}"\n    # Add the CSV directory path\n    csv_directories:\n      - /path/to/your/unzipped/data\n'})}),"\n",(0,s.jsxs)(a.p,{children:["Ensure you replace ",(0,s.jsx)(a.code,{children:"/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 Solace Agent Mesh project, you can use ",(0,s.jsx)(a.code,{children:"abc_coffee_co"}),"."]}),"\n",(0,s.jsx)(a.h2,{id:"setting-the-environment-variables",children:"Setting the Environment Variables"}),"\n",(0,s.jsxs)(a.p,{children:["The SQL Database agent requires that you configure several environment variables. You must create or update your ",(0,s.jsx)(a.code,{children:".env"})," file with the following variables for this tutorial:"]}),"\n",(0,s.jsx)(a.pre,{children:(0,s.jsx)(a.code,{className:"language-bash",children:'ABC_COFFEE_INFO_DB_TYPE=sqlite\nABC_COFFEE_INFO_DB_NAME=abc_coffee.db\nABC_COFFEE_INFO_DB_PURPOSE="ABC Coffee Co. sales and operations database"\nABC_COFFEE_INFO_DB_DESCRIPTION="Contains information about ABC Coffee Co. products, sales, customers, employees, and store locations."\n# You can leave other environment variables as unset or empty\n'})}),"\n",(0,s.jsx)(a.p,{children:"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."}),"\n",(0,s.jsx)(a.h2,{id:"running-the-agent",children:"Running the Agent"}),"\n",(0,s.jsx)(a.p,{children:"Now, you can start your SQL database agent:"}),"\n",(0,s.jsx)(a.pre,{children:(0,s.jsx)(a.code,{className:"language-sh",children:"sam run configs/agents/abc-coffee-info.yaml\n"})}),"\n",(0,s.jsx)(a.p,{children:"The agent:"}),"\n",(0,s.jsxs)(a.ol,{children:["\n",(0,s.jsx)(a.li,{children:"Connects to the A2A control plane"}),"\n",(0,s.jsx)(a.li,{children:"Initializes the SQLite database and imports CSV data from the specified directory"}),"\n",(0,s.jsx)(a.li,{children:"Detects the database schema automatically"}),"\n",(0,s.jsx)(a.li,{children:"Registers its capabilities with the agent discovery system"}),"\n"]}),"\n",(0,s.jsx)(a.h2,{id:"interacting-with-the-database",children:"Interacting with the Database"}),"\n",(0,s.jsxs)(a.p,{children:["After your SQL database agent is running, you can interact with the ABC Coffee database through any gateway in your Solace Agent Mesh project (such as the Web UI gateway at ",(0,s.jsx)(a.code,{children:"http://localhost:8000"}),")."]}),"\n",(0,s.jsx)(a.p,{children:"You can ask natural language questions about the ABC Coffee Co. database, such as:"}),"\n",(0,s.jsxs)(a.ul,{children:["\n",(0,s.jsx)(a.li,{children:'"How many customers does ABC Coffee have?"'}),"\n",(0,s.jsx)(a.li,{children:'"What are the top-selling products?"'}),"\n",(0,s.jsx)(a.li,{children:'"Show me the sales by region"'}),"\n",(0,s.jsx)(a.li,{children:'"List all orders from the last 30 days"'}),"\n",(0,s.jsx)(a.li,{children:'"What products are currently low in inventory?"'}),"\n"]}),"\n",(0,s.jsx)(a.p,{children:"Try creating reports by asking questions such as:"}),"\n",(0,s.jsxs)(a.ul,{children:["\n",(0,s.jsx)(a.li,{children:'"Create a report of our sales in 2024"'}),"\n",(0,s.jsx)(a.li,{children:'"Generate a summary of customer demographics"'}),"\n"]}),"\n",(0,s.jsx)(a.p,{children:"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."}),"\n",(0,s.jsx)(a.h2,{id:"advanced-configuration",children:"Advanced Configuration"}),"\n",(0,s.jsx)(a.p,{children:"The SQL Database plugin supports many advanced configuration options. Here is a complete example based on the plugin structure:"}),"\n",(0,s.jsx)(a.pre,{children:(0,s.jsx)(a.code,{className:"language-yaml",children:'log:\n  stdout_log_level: INFO\n  log_file_level: DEBUG\n  log_file: abc-coffee-info.log\n\n!include ../shared_config.yaml\n\napps:\n  - name: abc-coffee-info-app\n    app_module: solace_agent_mesh.agent.sac.app \n    broker:\n      <<: *broker_connection\n\n    app_config:\n      namespace: ${NAMESPACE}\n      agent_name: "AbcCoffeeInfo"\n      display_name: "ABC Coffee Database Agent"\n      supports_streaming: false\n      model: *general_model\n\n      instruction: |\n        You are an expert SQL assistant for the ABC Coffee Co. database.\n        The database schema and query examples are provided to you.\n        Your primary goal is to translate user questions into accurate SQL queries.\n        If a user asks to query the database, generate the SQL and call the \'execute_sql_query\' tool.\n        If the \'execute_sql_query\' tool returns an error, analyze the error message and the original SQL,\n        then try to correct the SQL query and call the tool again.\n        If the results are large and the tool indicates they were saved as an artifact, inform the user about the artifact.\n        Always use the \'execute_sql_query\' tool to interact with the database.\n\n      # Agent initialization with database setup\n      agent_init_function:\n        module: "sam_sql_database.lifecycle"\n        name: "initialize_sql_agent"\n        config:\n          db_type: "${ABC_COFFEE_INFO_DB_TYPE}"\n          db_name: "${ABC_COFFEE_INFO_DB_NAME}"\n          database_purpose: "${ABC_COFFEE_INFO_DB_PURPOSE}"\n          data_description: "${ABC_COFFEE_INFO_DB_DESCRIPTION}"\n          auto_detect_schema: true\n          csv_directories:\n            - "abc_coffee_co"  # Path to your extracted data\n          query_examples:\n            - natural_language: "Show all customers from New York"\n              sql_query: "SELECT * FROM customers WHERE city = \'New York\';"\n            - natural_language: "What are the top 5 best-selling products?"\n              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;"\n\n      agent_cleanup_function:\n        module: "sam_sql_database.lifecycle"\n        name: "cleanup_sql_agent_resources"\n\n      # SQL query tool\n      tools:\n        - tool_type: python\n          component_module: "sam_sql_database.tools"\n          function_name: "execute_sql_query"\n\n      session_service: *default_session_service\n      artifact_service: *default_artifact_service\n\n      # Agent capabilities - This is what other agents see during discovery\n      agent_card:\n        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."\n        defaultInputModes: ["text"]\n        defaultOutputModes: ["text", "file"]\n        skills:\n          - id: "sql_query"\n            name: "Coffee Shop Database Query"\n            description: "Queries ABC Coffee Co. database containing customer orders, product catalog, inventory levels, sales history, and employee data."\n\n      # A2A Protocol settings\n      agent_card_publishing: { interval_seconds: 30 }\n      agent_discovery: { enabled: true }\n      inter_agent_communication:\n        allow_list: ["*"]\n        request_timeout_seconds: 60\n'})}),"\n",(0,s.jsx)(a.h2,{id:"customizing-the-agent-card",children:"Customizing the Agent Card"}),"\n",(0,s.jsxs)(a.p,{children:["The ",(0,s.jsx)(a.code,{children:"agent_card"})," section is crucial as it defines how other agents in your Solace 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."]}),"\n",(0,s.jsx)(a.h3,{id:"key-agent-card-elements",children:"Key Agent Card Elements"}),"\n",(0,s.jsxs)(a.ol,{children:["\n",(0,s.jsxs)(a.li,{children:[(0,s.jsx)(a.strong,{children:"Description"}),": Clearly describe what data the agent has access to and what types of questions it can answer"]}),"\n",(0,s.jsxs)(a.li,{children:[(0,s.jsx)(a.strong,{children:"Skills"}),": List specific capabilities with concrete examples that show the scope of data available"]}),"\n",(0,s.jsxs)(a.li,{children:[(0,s.jsx)(a.strong,{children:"Data Context"}),": Mention the business domain, data types, and scope of information available"]}),"\n"]}),"\n",(0,s.jsx)(a.h3,{id:"example-of-a-well-configured-agent-card",children:"Example of a Well-Configured Agent Card"}),"\n",(0,s.jsx)(a.pre,{children:(0,s.jsx)(a.code,{className:"language-yaml",children:'agent_card:\n  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."\n  defaultInputModes: ["text"]\n  defaultOutputModes: ["text", "file"]\n  skills:\n    - id: "sql_query"\n      name: "Coffee Shop Database Query"\n      description: "Queries ABC Coffee Co. database containing customer orders, product catalog, inventory levels, sales history, and employee data."\n'})}),"\n",(0,s.jsx)(a.p,{children:"This detailed information helps other agents understand:"}),"\n",(0,s.jsxs)(a.ul,{children:["\n",(0,s.jsx)(a.li,{children:"What business domain this agent covers (coffee shop operations)"}),"\n",(0,s.jsx)(a.li,{children:"What types of data are available (customers, orders, products, inventory, sales)"}),"\n",(0,s.jsx)(a.li,{children:"What kinds of questions can be answered (metrics, analytics, performance data)"}),"\n",(0,s.jsx)(a.li,{children:"Specific examples of queries that work well"}),"\n"]}),"\n",(0,s.jsx)(a.p,{children:"When configuring your own database agent, customize the description and examples to match your specific data and use cases."})]})}function h(e={}){const{wrapper:a}={...(0,o.R)(),...e.components};return a?(0,s.jsx)(a,{...e,children:(0,s.jsx)(d,{...e})}):d(e)}},8453:(e,a,n)=>{n.d(a,{R:()=>i,x:()=>r});var t=n(6540);const s={},o=t.createContext(s);function i(e){const a=t.useContext(o);return t.useMemo((function(){return"function"==typeof e?e(a):{...a,...e}}),[a,e])}function r(e){let a;return a=e.disableParentContext?"function"==typeof e.components?e.components(s):e.components||s:i(e.components),t.createElement(o.Provider,{value:a},e.children)}}}]);