solace-agent-mesh 1.6.1__py3-none-any.whl → 1.13.2__py3-none-any.whl

solace_agent_mesh/assets/docs/assets/js/{17896441.a5e82f9b.js.LICENSE.txt → 2279.550aa580.js.LICENSE.txt}

@@ -1,3 +1,7 @@
+/*!
+ * Wait for document loaded before starting the execution
+ */
+
 /*! @license DOMPurify 3.2.6 | (c) Cure53 and other contributors | Released under the Apache license 2.0 and Mozilla Public License 2.0 | github.com/cure53/DOMPurify/blob/3.2.6/LICENSE */
 
 /*! Bundled license information:
@@ -5,3 +9,5 @@
 js-yaml/dist/js-yaml.mjs:
   (*! js-yaml 4.1.0 https://github.com/nodeca/js-yaml @license MIT *)
 */
+
+/*! Check if previously processed */

solace_agent_mesh/assets/docs/assets/js/240a0364.83e37aa8.js

@@ -0,0 +1 @@
+"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[8249],{1049:(e,t,n)=>{n.r(t),n.d(t,{assets:()=>l,contentTitle:()=>o,default:()=>h,frontMatter:()=>i,metadata:()=>s,toc:()=>c});const s=JSON.parse('{"id":"documentation/migrations/a2a-upgrade/a2a-gateway-upgrade-to-0.3.0","title":"Migration Guide: Upgrading to the A2A SDK","description":"This guide is for developers who have built or are maintaining a custom Agent Mesh gateway. A recent architectural update has aligned Agent Mesh with the official Agent-to-Agent (A2A) protocol specification by adopting the a2a-sdk. This migration requires some changes to your gateway code to ensure compatibility.","source":"@site/docs/documentation/migrations/a2a-upgrade/a2a-gateway-upgrade-to-0.3.0.md","sourceDirName":"documentation/migrations/a2a-upgrade","slug":"/documentation/migrations/a2a-upgrade/a2a-gateway-upgrade-to-0.3.0","permalink":"/solace-agent-mesh/docs/documentation/migrations/a2a-upgrade/a2a-gateway-upgrade-to-0.3.0","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/migrations/a2a-upgrade/a2a-gateway-upgrade-to-0.3.0.md","tags":[],"version":"current","sidebarPosition":10,"frontMatter":{"title":"Migration Guide: Upgrading to the A2A SDK","sidebar_position":10},"sidebar":"docSidebar","previous":{"title":"Migration to Platform Service (Enterprise v1.27.0+)","permalink":"/solace-agent-mesh/docs/documentation/migrations/platform-service-split"},"next":{"title":"A2A Technical Migration Map","permalink":"/solace-agent-mesh/docs/documentation/migrations/a2a-upgrade/a2a-technical-migration-map"}}');var a=n(4848),r=n(8453);const i={title:"Migration Guide: Upgrading to the A2A SDK",sidebar_position:10},o=void 0,l={},c=[{value:"Why the Change?",id:"why-the-change",level:2},{value:"Core Conceptual Changes",id:"core-conceptual-changes",level:2},{value:"The <code>a2a</code> Helper Layer: The New Best Practice",id:"the-a2a-helper-layer-the-new-best-practice",level:3},{value:"Type System Migration",id:"type-system-migration",level:3},{value:"Accessing Object Properties",id:"accessing-object-properties",level:3},{value:"Changes to <code>BaseGatewayComponent</code>",id:"changes-to-basegatewaycomponent",level:3},{value:"Migration Checklist",id:"migration-checklist",level:2},{value:"Code Examples: Before &amp; After",id:"code-examples-before--after",level:2},{value:"Example 1: Translating External Input",id:"example-1-translating-external-input",level:3},{value:"Example 2: Sending a Final Response",id:"example-2-sending-a-final-response",level:3}];function d(e){const t={code:"code",h2:"h2",h3:"h3",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,r.R)(),...e.components},{Details:n}=t;return n||function(e,t){throw new Error("Expected "+(t?"component":"object")+" `"+e+"` to be defined: you likely forgot to import, pass, or provide it.")}("Details",!0),(0,a.jsxs)(a.Fragment,{children:[(0,a.jsxs)(t.p,{children:["This guide is for developers who have built or are maintaining a custom Agent Mesh gateway. A recent architectural update has aligned Agent Mesh with the official Agent-to-Agent (A2A) protocol specification by adopting the ",(0,a.jsx)(t.code,{children:"a2a-sdk"}),". This migration requires some changes to your gateway code to ensure compatibility."]}),"\n",(0,a.jsx)(t.p,{children:"This document provides a high-level overview of the conceptual changes and a practical checklist to guide you through the upgrade process."}),"\n",(0,a.jsx)(t.h2,{id:"why-the-change",children:"Why the Change?"}),"\n",(0,a.jsxs)(t.p,{children:["The migration from our legacy A2A implementation to the official ",(0,a.jsx)(t.code,{children:"a2a-sdk"})," is a foundational improvement with several key benefits:"]}),"\n",(0,a.jsxs)(t.ul,{children:["\n",(0,a.jsxs)(t.li,{children:[(0,a.jsx)(t.strong,{children:"Protocol Compliance:"})," Ensures your gateway is fully interoperable with any A2A-compliant agent or system."]}),"\n",(0,a.jsxs)(t.li,{children:[(0,a.jsx)(t.strong,{children:"Standardization:"})," Replaces bespoke code with a community-supported standard, reducing technical debt."]}),"\n",(0,a.jsxs)(t.li,{children:[(0,a.jsx)(t.strong,{children:"Improved Maintainability:"})," Insulates your gateway from future A2A specification changes. The ",(0,a.jsx)(t.code,{children:"a2a-sdk"})," will be updated, not your core logic."]}),"\n",(0,a.jsxs)(t.li,{children:[(0,a.jsx)(t.strong,{children:"Future-Proofing:"})," Positions your gateway to easily adopt new features as the A2A protocol evolves."]}),"\n"]}),"\n",(0,a.jsx)(t.h2,{id:"core-conceptual-changes",children:"Core Conceptual Changes"}),"\n",(0,a.jsx)(t.p,{children:"The upgrade introduces a few key changes in how you interact with A2A objects."}),"\n",(0,a.jsxs)(t.h3,{id:"the-a2a-helper-layer-the-new-best-practice",children:["The ",(0,a.jsx)(t.code,{children:"a2a"})," Helper Layer: The New Best Practice"]}),"\n",(0,a.jsxs)(t.p,{children:["The most significant change is the introduction of a new abstraction layer located at ",(0,a.jsx)(t.code,{children:"solace_agent_mesh.common.a2a"}),"."]}),"\n",(0,a.jsxs)(t.p,{children:["You should ",(0,a.jsxs)(t.strong,{children:["no longer instantiate ",(0,a.jsx)(t.code,{children:"a2a.types"})," models directly"]})," or access their properties by hand. Instead, use the provided helper functions. This layer is designed to simplify development and protect your code from future SDK changes."]}),"\n",(0,a.jsx)(t.p,{children:(0,a.jsx)(t.strong,{children:"Example:"})}),"\n",(0,a.jsx)(t.pre,{children:(0,a.jsx)(t.code,{className:"language-python",children:'\n# BEFORE: Direct instantiation and property access\nfrom solace_agent_mesh.common.types import TextPart, Task\nmy_part = TextPart(text="Hello")\ntask_id = my_task.id\n\n# AFTER: Using the a2a helper layer\nfrom solace_agent_mesh.common import a2a\nmy_part = a2a.create_text_part(text="Hello")\ntask_id = a2a.get_task_id(my_task)\n\n'})}),"\n",(0,a.jsx)(t.h3,{id:"type-system-migration",children:"Type System Migration"}),"\n",(0,a.jsxs)(t.ul,{children:["\n",(0,a.jsxs)(t.li,{children:["The legacy types in ",(0,a.jsx)(t.code,{children:"solace_agent_mesh.common.types"})," (like ",(0,a.jsx)(t.code,{children:"A2APart"}),", ",(0,a.jsx)(t.code,{children:"FileContent"}),") are deprecated."]}),"\n",(0,a.jsxs)(t.li,{children:["All A2A models now come from the ",(0,a.jsx)(t.code,{children:"a2a.types"})," library."]}),"\n",(0,a.jsxs)(t.li,{children:["The type hint for a list of message parts has changed from ",(0,a.jsx)(t.code,{children:"List[A2APart]"})," to ",(0,a.jsx)(t.code,{children:"List[ContentPart]"}),". ",(0,a.jsx)(t.code,{children:"ContentPart"})," is a simple alias for the union of ",(0,a.jsx)(t.code,{children:"TextPart"}),", ",(0,a.jsx)(t.code,{children:"DataPart"}),", and ",(0,a.jsx)(t.code,{children:"FilePart"}),"."]}),"\n"]}),"\n",(0,a.jsx)(t.h3,{id:"accessing-object-properties",children:"Accessing Object Properties"}),"\n",(0,a.jsxs)(t.p,{children:["Field names on many A2A objects have changed. Always use the ",(0,a.jsx)(t.code,{children:"a2a"})," helper functions for safe and future-proof access."]}),"\n",(0,a.jsxs)(t.table,{children:[(0,a.jsx)(t.thead,{children:(0,a.jsxs)(t.tr,{children:[(0,a.jsx)(t.th,{style:{textAlign:"left"},children:"Action"}),(0,a.jsx)(t.th,{style:{textAlign:"left"},children:"Old Pattern"}),(0,a.jsx)(t.th,{style:{textAlign:"left"},children:"New Pattern (Recommended)"})]})}),(0,a.jsxs)(t.tbody,{children:[(0,a.jsxs)(t.tr,{children:[(0,a.jsx)(t.td,{style:{textAlign:"left"},children:"Get Task ID"}),(0,a.jsx)(t.td,{style:{textAlign:"left"},children:(0,a.jsx)(t.code,{children:"task.id"})}),(0,a.jsx)(t.td,{style:{textAlign:"left"},children:(0,a.jsx)(t.code,{children:"a2a.get_task_id(task)"})})]}),(0,a.jsxs)(t.tr,{children:[(0,a.jsx)(t.td,{style:{textAlign:"left"},children:"Get Task Status"}),(0,a.jsx)(t.td,{style:{textAlign:"left"},children:(0,a.jsx)(t.code,{children:"task.status.state"})}),(0,a.jsx)(t.td,{style:{textAlign:"left"},children:(0,a.jsx)(t.code,{children:"a2a.get_task_status(task)"})})]}),(0,a.jsxs)(t.tr,{children:[(0,a.jsx)(t.td,{style:{textAlign:"left"},children:"Get Event's Task ID"}),(0,a.jsx)(t.td,{style:{textAlign:"left"},children:(0,a.jsx)(t.code,{children:"event.id"})}),(0,a.jsx)(t.td,{style:{textAlign:"left"},children:(0,a.jsx)(t.code,{children:"event.task_id"})})]}),(0,a.jsxs)(t.tr,{children:[(0,a.jsx)(t.td,{style:{textAlign:"left"},children:"Get Message Parts"}),(0,a.jsx)(t.td,{style:{textAlign:"left"},children:(0,a.jsx)(t.code,{children:"message.parts"})}),(0,a.jsx)(t.td,{style:{textAlign:"left"},children:(0,a.jsx)(t.code,{children:"a2a.get_parts_from_message(message)"})})]}),(0,a.jsxs)(t.tr,{children:[(0,a.jsx)(t.td,{style:{textAlign:"left"},children:"Get Error Message"}),(0,a.jsx)(t.td,{style:{textAlign:"left"},children:(0,a.jsx)(t.code,{children:"error.message"})}),(0,a.jsx)(t.td,{style:{textAlign:"left"},children:(0,a.jsx)(t.code,{children:"a2a.get_error_message(error)"})})]}),(0,a.jsxs)(t.tr,{children:[(0,a.jsx)(t.td,{style:{textAlign:"left"},children:"Get Error Code"}),(0,a.jsx)(t.td,{style:{textAlign:"left"},children:(0,a.jsx)(t.code,{children:"error.code"})}),(0,a.jsx)(t.td,{style:{textAlign:"left"},children:(0,a.jsx)(t.code,{children:"a2a.get_error_code(error)"})})]}),(0,a.jsxs)(t.tr,{children:[(0,a.jsx)(t.td,{style:{textAlign:"left"},children:"Get Error Data"}),(0,a.jsx)(t.td,{style:{textAlign:"left"},children:(0,a.jsx)(t.code,{children:"error.data"})}),(0,a.jsx)(t.td,{style:{textAlign:"left"},children:(0,a.jsx)(t.code,{children:"a2a.get_error_data(error)"})})]})]})]}),"\n",(0,a.jsxs)(t.h3,{id:"changes-to-basegatewaycomponent",children:["Changes to ",(0,a.jsx)(t.code,{children:"BaseGatewayComponent"})]}),"\n",(0,a.jsxs)(t.p,{children:["The ",(0,a.jsx)(t.code,{children:"BaseGatewayComponent"})," has been significantly improved. It now handles more of the A2A protocol complexity, simplifying gateway implementations."]}),"\n",(0,a.jsxs)(t.ul,{children:["\n",(0,a.jsxs)(t.li,{children:[(0,a.jsx)(t.strong,{children:"Artifact Handling:"})," The base class can now automatically handle artifact URIs, converting them to embedded bytes before sending them to your gateway's ",(0,a.jsx)(t.code,{children:"_send_..."})," methods. This is controlled by the ",(0,a.jsx)(t.code,{children:"resolve_artifact_uris_in_gateway"})," parameter in the constructor."]}),"\n",(0,a.jsxs)(t.li,{children:[(0,a.jsx)(t.strong,{children:"Message Publishing:"})," The base class now manages the details of preparing and publishing the A2A request message in ",(0,a.jsx)(t.code,{children:"submit_a2a_task"}),"."]}),"\n",(0,a.jsxs)(t.li,{children:[(0,a.jsx)(t.strong,{children:"Asynchronous Model:"})," The underlying threading model has been removed in favor of a more direct ",(0,a.jsx)(t.code,{children:"asyncio"})," implementation, simplifying the component lifecycle."]}),"\n"]}),"\n",(0,a.jsxs)(t.p,{children:["It is highly recommended to review the latest ",(0,a.jsx)(t.code,{children:"BaseGatewayComponent"})," and re-base your custom gateway on it to inherit these benefits and reduce boilerplate code."]}),"\n",(0,a.jsx)(t.h2,{id:"migration-checklist",children:"Migration Checklist"}),"\n",(0,a.jsx)(t.p,{children:"Follow these steps to update your gateway code."}),"\n",(0,a.jsxs)(t.ol,{children:["\n",(0,a.jsxs)(t.li,{children:["\n",(0,a.jsx)(t.p,{children:(0,a.jsx)(t.strong,{children:"Update Imports:"})}),"\n",(0,a.jsxs)(t.ul,{children:["\n",(0,a.jsxs)(t.li,{children:["Remove imports from ",(0,a.jsx)(t.code,{children:"solace_agent_mesh.common.types"}),"."]}),"\n",(0,a.jsxs)(t.li,{children:["Add imports from ",(0,a.jsx)(t.code,{children:"a2a.types"})," for specific models if needed."]}),"\n",(0,a.jsxs)(t.li,{children:["Add ",(0,a.jsx)(t.code,{children:"from solace_agent_mesh.common import a2a"}),"."]}),"\n",(0,a.jsxs)(t.li,{children:["Add ",(0,a.jsx)(t.code,{children:"from solace_agent_mesh.common.a2a import ContentPart"}),"."]}),"\n"]}),"\n"]}),"\n",(0,a.jsxs)(t.li,{children:["\n",(0,a.jsx)(t.p,{children:(0,a.jsx)(t.strong,{children:"Update Type Hints:"})}),"\n",(0,a.jsxs)(t.ul,{children:["\n",(0,a.jsxs)(t.li,{children:["Find all instances of ",(0,a.jsx)(t.code,{children:"List[A2APart]"})," and change them to ",(0,a.jsx)(t.code,{children:"List[ContentPart]"}),"."]}),"\n"]}),"\n"]}),"\n",(0,a.jsxs)(t.li,{children:["\n",(0,a.jsx)(t.p,{children:(0,a.jsx)(t.strong,{children:"Refactor Object Creation:"})}),"\n",(0,a.jsxs)(t.ul,{children:["\n",(0,a.jsxs)(t.li,{children:["Replace direct model instantiation like ",(0,a.jsx)(t.code,{children:"TextPart(...)"})," or ",(0,a.jsx)(t.code,{children:"FilePart(...)"})," with their corresponding helper functions: ",(0,a.jsx)(t.code,{children:"a2a.create_text_part(...)"}),", ",(0,a.jsx)(t.code,{children:"a2a.create_file_part_from_uri(...)"}),", etc."]}),"\n"]}),"\n"]}),"\n",(0,a.jsxs)(t.li,{children:["\n",(0,a.jsx)(t.p,{children:(0,a.jsx)(t.strong,{children:"Refactor Property Access:"})}),"\n",(0,a.jsxs)(t.ul,{children:["\n",(0,a.jsxs)(t.li,{children:["Replace direct property access (",(0,a.jsx)(t.code,{children:"task.id"}),", ",(0,a.jsx)(t.code,{children:"error.message"}),") with calls to the ",(0,a.jsx)(t.code,{children:"a2a"})," helper functions (",(0,a.jsx)(t.code,{children:"a2a.get_task_id(task)"}),", ",(0,a.jsx)(t.code,{children:"a2a.get_error_message(error)"}),")."]}),"\n"]}),"\n"]}),"\n",(0,a.jsxs)(t.li,{children:["\n",(0,a.jsx)(t.p,{children:(0,a.jsx)(t.strong,{children:"Review Base Class Integration:"})}),"\n",(0,a.jsxs)(t.ul,{children:["\n",(0,a.jsxs)(t.li,{children:["If you have a custom gateway, compare it against the latest ",(0,a.jsx)(t.code,{children:"BaseGatewayComponent"}),". Consider refactoring to delegate more responsibility (like artifact handling and message submission) to the base class."]}),"\n"]}),"\n"]}),"\n",(0,a.jsxs)(t.li,{children:["\n",(0,a.jsx)(t.p,{children:(0,a.jsx)(t.strong,{children:"Test Thoroughly:"})}),"\n",(0,a.jsxs)(t.ul,{children:["\n",(0,a.jsx)(t.li,{children:"Once refactored, run your integration tests to ensure the gateway correctly translates inputs and processes outputs in the new format."}),"\n"]}),"\n"]}),"\n"]}),"\n",(0,a.jsx)(t.h2,{id:"code-examples-before--after",children:"Code Examples: Before & After"}),"\n",(0,a.jsx)(t.p,{children:"Here are some common patterns you will encounter during the migration."}),"\n",(0,a.jsx)(t.h3,{id:"example-1-translating-external-input",children:"Example 1: Translating External Input"}),"\n",(0,a.jsx)(t.p,{children:"This example shows how to create A2A parts from an external event."}),"\n",(0,a.jsxs)(n,{children:[(0,a.jsx)("summary",{children:(0,a.jsx)("strong",{children:"_translate_external_input"})}),(0,a.jsx)(t.p,{children:(0,a.jsx)(t.strong,{children:"Before:"})}),(0,a.jsx)(t.pre,{children:(0,a.jsx)(t.code,{className:"language-python",children:'from solace_agent_mesh.common.types import Part as A2APart, TextPart, FilePart, FileContent\n\nasync def _translate_external_input(self, external_event: Any) -> Tuple[str, List[A2APart], Dict[str, Any]]:\n    # ...\n    a2a_parts: List[A2APart] = []\n\n    # Create a file part with a URI\n    uri = "artifact://..."\n    a2a_parts.append(\n        FilePart(\n            file=FileContent(name="report.pdf", uri=uri)\n        )\n    )\n\n    # Create a text part\n    prompt = "Summarize the attached file."\n    a2a_parts.append(TextPart(text=prompt))\n\n    return "summary_agent", a2a_parts, {}\n'})}),(0,a.jsx)(t.p,{children:(0,a.jsx)(t.strong,{children:"After:"})}),(0,a.jsx)(t.pre,{children:(0,a.jsx)(t.code,{className:"language-python",children:'from solace_agent_mesh.common import a2a\nfrom solace_agent_mesh.common.a2a import ContentPart\n\nasync def _translate_external_input(self, external_event: Any) -> Tuple[str, List[ContentPart], Dict[str, Any]]:\n    # ...\n    a2a_parts: List[ContentPart] = []\n\n    # Create a file part with a URI using the helper\n    uri = "artifact://..."\n    file_part = a2a.create_file_part_from_uri(uri=uri, name="report.pdf")\n    a2a_parts.append(file_part)\n\n    # Create a text part using the helper\n    prompt = "Summarize the attached file."\n    text_part = a2a.create_text_part(text=prompt)\n    a2a_parts.append(text_part)\n\n    return "summary_agent", a2a_parts, {}\n'})})]}),"\n",(0,a.jsx)(t.h3,{id:"example-2-sending-a-final-response",children:"Example 2: Sending a Final Response"}),"\n",(0,a.jsxs)(t.p,{children:["This example shows how to process a final ",(0,a.jsx)(t.code,{children:"Task"})," object."]}),"\n",(0,a.jsxs)(n,{children:[(0,a.jsx)("summary",{children:(0,a.jsx)("strong",{children:"_send_final_response_to_external"})}),(0,a.jsx)(t.p,{children:(0,a.jsx)(t.strong,{children:"Before:"})}),(0,a.jsx)(t.pre,{children:(0,a.jsx)(t.code,{className:"language-python",children:'from solace_agent_mesh.common.types import Task, TaskState, TextPart\n\nasync def _send_final_response_to_external(self, context: Dict, task_data: Task) -> None:\n    task_id = task_data.id\n    final_status_text = ":checkered_flag: Task complete."\n\n    if task_data.status.state == TaskState.FAILED:\n        error_message_text = ""\n        if task_data.status.message and task_data.status.message.parts:\n            for part in task_data.status.message.parts:\n                if isinstance(part, TextPart):\n                    error_message_text = part.text\n                    break\n        final_status_text = f":x: Error: Task failed. {error_message_text}".strip()\n\n    # ... use final_status_text and task_id\n'})}),(0,a.jsx)(t.p,{children:(0,a.jsx)(t.strong,{children:"After:"})}),(0,a.jsx)(t.pre,{children:(0,a.jsx)(t.code,{className:"language-python",children:'from solace_agent_mesh.common import a2a\nfrom a2a.types import Task, TaskState\n\nasync def _send_final_response_to_external(self, context: Dict, task_data: Task) -> None:\n    # Use helpers to safely access properties\n    task_id = a2a.get_task_id(task_data)\n    task_status = a2a.get_task_status(task_data)\n\n    final_status_text = ":checkered_flag: Task complete."\n\n    if task_status == TaskState.failed:\n        error_message_text = ""\n        if task_data.status and task_data.status.message:\n            # Use helper to extract all text from the message\n            error_message_text = a2a.get_text_from_message(task_data.status.message)\n        final_status_text = f":x: Error: Task failed. {error_message_text}".strip()\n\n    # ... use final_status_text and task_id\n'})})]})]})}function h(e={}){const{wrapper:t}={...(0,r.R)(),...e.components};return t?(0,a.jsx)(t,{...e,children:(0,a.jsx)(d,{...e})}):d(e)}},8453:(e,t,n)=>{n.d(t,{R:()=>i,x:()=>o});var s=n(6540);const a={},r=s.createContext(a);function i(e){const t=s.useContext(r);return s.useMemo((function(){return"function"==typeof e?e(t):{...t,...e}}),[t,e])}function o(e){let t;return t=e.disableParentContext?"function"==typeof e.components?e.components(a):e.components||a:i(e.components),s.createElement(r.Provider,{value:t},e.children)}}}]);

solace_agent_mesh/assets/docs/assets/js/2987107d.a80604f9.js

@@ -0,0 +1 @@
+"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[9057],{927:(e,n,t)=>{t.r(n),t.d(n,{assets:()=>l,contentTitle:()=>a,default:()=>d,frontMatter:()=>r,metadata:()=>i,toc:()=>c});const i=JSON.parse('{"id":"documentation/enterprise/wheel-installation","title":"Running from Wheel File","description":"You can run Agent Mesh Enterprise directly from a Python wheel file without using Docker containers. This approach gives you direct control over your Python environment and integrates with existing Python-based deployments.","source":"@site/docs/documentation/enterprise/wheel-installation.md","sourceDirName":"documentation/enterprise","slug":"/documentation/enterprise/wheel-installation","permalink":"/solace-agent-mesh/docs/documentation/enterprise/wheel-installation","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/enterprise/wheel-installation.md","tags":[],"version":"current","sidebarPosition":6,"frontMatter":{"title":"Running from Wheel File","sidebar_position":6},"sidebar":"docSidebar","previous":{"title":"Installing Agent Mesh Enterprise","permalink":"/solace-agent-mesh/docs/documentation/enterprise/installation"},"next":{"title":"Agent Builder","permalink":"/solace-agent-mesh/docs/documentation/enterprise/agent-builder"}}');var s=t(4848),o=t(8453);const r={title:"Running from Wheel File",sidebar_position:6},a="Running Agent Mesh Enterprise from Wheel File",l={},c=[{value:"Prerequisites",id:"prerequisites",level:2},{value:"Step 1: Download the Wheel File",id:"step-1-download-the-wheel-file",level:2},{value:"Step 2: Install the Wheel File",id:"step-2-install-the-wheel-file",level:2},{value:"Step 3: Prepare Your Configuration",id:"step-3-prepare-your-configuration",level:2},{value:"Step 4: Run Agent Mesh Enterprise",id:"step-4-run-agent-mesh-enterprise",level:2},{value:"Running Specific Components",id:"running-specific-components",level:3},{value:"Using the Short Alias",id:"using-the-short-alias",level:3},{value:"Limitations",id:"limitations",level:2},{value:"No Dynamic Agent Deployment",id:"no-dynamic-agent-deployment",level:3},{value:"Custom Agent Code",id:"custom-agent-code",level:3},{value:"Accessing the Web UI",id:"accessing-the-web-ui",level:2},{value:"Next Steps",id:"next-steps",level:2}];function h(e){const n={a:"a",code:"code",h1:"h1",h2:"h2",h3:"h3",header:"header",li:"li",p:"p",pre:"pre",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:"running-agent-mesh-enterprise-from-wheel-file",children:"Running Agent Mesh Enterprise from Wheel File"})}),"\n",(0,s.jsx)(n.p,{children:"You can run Agent Mesh Enterprise directly from a Python wheel file without using Docker containers. This approach gives you direct control over your Python environment and integrates with existing Python-based deployments."}),"\n",(0,s.jsx)(n.h2,{id:"prerequisites",children:"Prerequisites"}),"\n",(0,s.jsx)(n.p,{children:"To run Agent Mesh Enterprise from a wheel file, you need:"}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsx)(n.li,{children:"Python 3.10.16 or later"}),"\n",(0,s.jsx)(n.li,{children:"pip or uv package manager"}),"\n",(0,s.jsxs)(n.li,{children:["Access to the ",(0,s.jsx)(n.a,{href:"https://products.solace.com/prods/Agent_Mesh/Enterprise/",children:"Solace Product Portal"})]}),"\n",(0,s.jsx)(n.li,{children:"An LLM service API key and endpoint"}),"\n",(0,s.jsx)(n.li,{children:"For production deployments, Solace broker credentials"}),"\n"]}),"\n",(0,s.jsx)(n.h2,{id:"step-1-download-the-wheel-file",children:"Step 1: Download the Wheel File"}),"\n",(0,s.jsxs)(n.p,{children:["Download the Agent Mesh Enterprise wheel file from the ",(0,s.jsx)(n.a,{href:"https://products.solace.com/prods/Agent_Mesh/Enterprise/",children:"Solace Product Portal"}),"."]}),"\n",(0,s.jsx)(n.p,{children:"The wheel file follows the naming pattern:"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{children:"solace_agent_mesh_enterprise-<version>-py3-none-any.whl\n"})}),"\n",(0,s.jsx)(n.h2,{id:"step-2-install-the-wheel-file",children:"Step 2: Install the Wheel File"}),"\n",(0,s.jsx)(n.p,{children:"You can install the wheel file with either pip or uv."}),"\n",(0,s.jsx)(n.p,{children:"If you use pip, run:"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-bash",children:"pip install solace_agent_mesh_enterprise-<version>-py3-none-any.whl\n"})}),"\n",(0,s.jsx)(n.p,{children:"If you use uv, run:"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-bash",children:"uv pip install solace_agent_mesh_enterprise-<version>-py3-none-any.whl\n"})}),"\n",(0,s.jsxs)(n.p,{children:["This installation provides the ",(0,s.jsx)(n.code,{children:"solace-agent-mesh"})," CLI tool and the Agent Mesh Enterprise framework."]}),"\n",(0,s.jsx)(n.h2,{id:"step-3-prepare-your-configuration",children:"Step 3: Prepare Your Configuration"}),"\n",(0,s.jsxs)(n.p,{children:["Agent Mesh Enterprise requires configuration files that define your agents, gateways, and system settings. The ",(0,s.jsx)(n.code,{children:"solace-agent-mesh init"})," command creates the project directory structure, environment variables, and configuration files you need."]}),"\n",(0,s.jsxs)(n.p,{children:["Follow the project setup steps in the ",(0,s.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/installing-and-configuring/run-project#create-your-project",children:"Creating and Running an Agent Mesh Project"})," guide to initialize your configuration. You can use the web-based interface or command-line options to configure your project settings."]}),"\n",(0,s.jsxs)(n.p,{children:["After initialization, your project directory contains the necessary ",(0,s.jsx)(n.code,{children:"configs/"})," directory with agent and gateway configurations, plus a ",(0,s.jsx)(n.code,{children:".env"})," file with your credentials."]}),"\n",(0,s.jsx)(n.h2,{id:"step-4-run-agent-mesh-enterprise",children:"Step 4: Run Agent Mesh Enterprise"}),"\n",(0,s.jsxs)(n.p,{children:["Start Agent Mesh Enterprise using the ",(0,s.jsx)(n.code,{children:"solace-agent-mesh run"})," command:"]}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-bash",children:"solace-agent-mesh run\n"})}),"\n",(0,s.jsxs)(n.p,{children:["This command loads environment variables from your ",(0,s.jsx)(n.code,{children:".env"})," file, starts all agents and gateways defined in your ",(0,s.jsx)(n.code,{children:"configs/"})," directory, and launches the web UI if you configured one."]}),"\n",(0,s.jsx)(n.h3,{id:"running-specific-components",children:"Running Specific Components"}),"\n",(0,s.jsx)(n.p,{children:"To run only specific agents or gateways, provide the configuration files as arguments:"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-bash",children:"solace-agent-mesh run configs/agents/orchestrator.yaml configs/gateways/webui.yaml\n"})}),"\n",(0,s.jsx)(n.h3,{id:"using-the-short-alias",children:"Using the Short Alias"}),"\n",(0,s.jsxs)(n.p,{children:["The ",(0,s.jsx)(n.code,{children:"sam"})," alias provides a shorter alternative to the full command name:"]}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-bash",children:"sam run\n"})}),"\n",(0,s.jsx)(n.h2,{id:"limitations",children:"Limitations"}),"\n",(0,s.jsx)(n.p,{children:"When running from a wheel file, certain features have limitations compared to the Docker-based deployment."}),"\n",(0,s.jsx)(n.h3,{id:"no-dynamic-agent-deployment",children:"No Dynamic Agent Deployment"}),"\n",(0,s.jsx)(n.p,{children:"Dynamic agent deployment through the UI or API is not supported when running from a wheel file. You cannot deploy new agents at runtime through the web interface, upload agent configurations through the API, or dynamically add or remove agents without restarting. All agents must be defined in configuration files before you start the application."}),"\n",(0,s.jsx)(n.h3,{id:"custom-agent-code",children:"Custom Agent Code"}),"\n",(0,s.jsxs)(n.p,{children:["To create custom agents with Python tools and lifecycle functions, follow the standard agent creation process. For detailed instructions on creating agents with custom code, see ",(0,s.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/developing/create-agents",children:"Creating Agents"}),"."]}),"\n",(0,s.jsx)(n.h2,{id:"accessing-the-web-ui",children:"Accessing the Web UI"}),"\n",(0,s.jsxs)(n.p,{children:["After starting Agent Mesh Enterprise, access the web interface at the configured port (default: ",(0,s.jsx)(n.code,{children:"http://localhost:8000"}),")."]}),"\n",(0,s.jsx)(n.p,{children:"If you specified a different port in your gateway configuration, use that port instead."}),"\n",(0,s.jsx)(n.h2,{id:"next-steps",children:"Next Steps"}),"\n",(0,s.jsxs)(n.p,{children:["After running Agent Mesh Enterprise from the wheel file, you can configure authentication and authorization for your deployment. For information about setting up authentication, see ",(0,s.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/enterprise/single-sign-on",children:"Single Sign-On"}),". For information about configuring authorization, see ",(0,s.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/enterprise/rbac-setup-guide",children:"Role-Based Access Control"}),". For production deployment considerations, see ",(0,s.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/deploying/deployment-options",children:"deployment options"}),"."]})]})}function d(e={}){const{wrapper:n}={...(0,o.R)(),...e.components};return n?(0,s.jsx)(n,{...e,children:(0,s.jsx)(h,{...e})}):h(e)}},8453:(e,n,t)=>{t.d(n,{R:()=>r,x:()=>a});var i=t(6540);const s={},o=i.createContext(s);function r(e){const n=i.useContext(o);return i.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),i.createElement(o.Provider,{value:n},e.children)}}}]);

solace_agent_mesh/assets/docs/assets/js/2e32b5e0.2f0db237.js

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

solace_agent_mesh/assets/docs/assets/js/3a6c6137.7e61915d.js

@@ -0,0 +1 @@
+"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[1387],{1493:(e,t,n)=>{n.r(t),n.d(t,{assets:()=>c,contentTitle:()=>r,default:()=>m,frontMatter:()=>i,metadata:()=>o,toc:()=>l});const o=JSON.parse('{"id":"documentation/components/components","title":"Components","description":"Agent Mesh provides a comprehensive set of components that work together to create a distributed AI agent ecosystem. Each component serves a specific purpose, from managing the command-line interface to orchestrating complex multi-agent workflows.","source":"@site/docs/documentation/components/components.md","sourceDirName":"documentation/components","slug":"/documentation/components/","permalink":"/solace-agent-mesh/docs/documentation/components/","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/components/components.md","tags":[],"version":"current","sidebarPosition":200,"frontMatter":{"title":"Components","sidebar_position":200},"sidebar":"docSidebar","previous":{"title":"Vibe Coding","permalink":"/solace-agent-mesh/docs/documentation/getting-started/vibe_coding"},"next":{"title":"Agents","permalink":"/solace-agent-mesh/docs/documentation/components/agents"}}');var s=n(4848),a=n(8453);const i={title:"Components",sidebar_position:200},r=void 0,c={},l=[{value:"Agents",id:"agents",level:2},{value:"Gateways",id:"gateways",level:2},{value:"Platform Service",id:"platform-service",level:2},{value:"Orchestrator",id:"orchestrator",level:2},{value:"Plugins",id:"plugins",level:2},{value:"Built-in Tools",id:"built-in-tools",level:2},{value:"Command Line Interface",id:"command-line-interface",level:2}];function d(e){const t={a:"a",h2:"h2",p:"p",...(0,a.R)(),...e.components};return(0,s.jsxs)(s.Fragment,{children:[(0,s.jsx)(t.p,{children:"Agent Mesh provides a comprehensive set of components that work together to create a distributed AI agent ecosystem. Each component serves a specific purpose, from managing the command-line interface to orchestrating complex multi-agent workflows."}),"\n",(0,s.jsx)(t.p,{children:"This section introduces you to the key components and tools that make up the system. You'll find detailed documentation for each component, along with configuration examples and best practices for implementation."}),"\n",(0,s.jsx)(t.h2,{id:"agents",children:"Agents"}),"\n",(0,s.jsxs)(t.p,{children:["Agents are the intelligent processing units that perform tasks within the mesh. Each agent combines the Google Agent Development Kit (ADK) with specialized instructions, LLM configurations, and toolsets to create focused AI capabilities. Agents can work independently or collaborate with other agents to solve complex problems. You can configure agents with different personalities, expertise areas, and access permissions to match your specific use cases. For comprehensive agent configuration and development guidance, see ",(0,s.jsx)(t.a,{href:"/solace-agent-mesh/docs/documentation/components/agents",children:"Agents"}),"."]}),"\n",(0,s.jsx)(t.h2,{id:"gateways",children:"Gateways"}),"\n",(0,s.jsxs)(t.p,{children:["Gateways serve as the entry and exit points for your agent mesh, translating between external protocols and the internal A2A communication standard. Whether you need REST APIs, webhooks, WebSocket connections, or integrations with platforms like Slack, gateways handle the protocol conversion and session management. They also manage authentication and authorization, ensuring that user permissions are properly enforced throughout the system. For gateway development and configuration details, see ",(0,s.jsx)(t.a,{href:"/solace-agent-mesh/docs/documentation/components/gateways",children:"Gateways"}),"."]}),"\n",(0,s.jsx)(t.h2,{id:"platform-service",children:"Platform Service"}),"\n",(0,s.jsxs)(t.p,{children:["The Platform Service is a backend microservice responsible for management operations in Solace Agent Mesh. For more details, see ",(0,s.jsx)(t.a,{href:"/solace-agent-mesh/docs/documentation/components/platform-service",children:"Platform Service"}),"."]}),"\n",(0,s.jsx)(t.h2,{id:"orchestrator",children:"Orchestrator"}),"\n",(0,s.jsxs)(t.p,{children:["The orchestrator is a specialized agent that manages complex workflows by breaking down requests into smaller tasks and coordinating their execution across multiple agents. It understands dependencies between tasks, manages parallel execution, and aggregates results to provide comprehensive responses. The orchestrator is particularly valuable for scenarios that require multiple specialized agents to work together toward a common goal. For orchestrator configuration and workflow design patterns, see ",(0,s.jsx)(t.a,{href:"/solace-agent-mesh/docs/documentation/components/orchestrator",children:"Orchestrator"}),"."]}),"\n",(0,s.jsx)(t.h2,{id:"plugins",children:"Plugins"}),"\n",(0,s.jsxs)(t.p,{children:["Plugins extend the capabilities of Agent Mesh by providing custom tools, integrations, and functionality. You can develop plugins to connect with proprietary systems, add domain-specific tools, or integrate with external services that aren't covered by the built-in toolset. The plugin system provides a standardized way to package and distribute custom functionality across your organization. For plugin development guidelines and examples, see ",(0,s.jsx)(t.a,{href:"/solace-agent-mesh/docs/documentation/components/plugins",children:"Plugins"}),"."]}),"\n",(0,s.jsx)(t.h2,{id:"built-in-tools",children:"Built-in Tools"}),"\n",(0,s.jsxs)(t.p,{children:["Agent Mesh includes a comprehensive set of built-in tools that provide essential capabilities for most AI agent scenarios. These tools handle common tasks like artifact management, data analysis, web interactions, and inter-agent communication. The built-in tools are designed to work seamlessly with the A2A protocol and provide consistent behavior across all agents in your mesh. For detailed documentation of available tools and their usage, see ",(0,s.jsx)(t.a,{href:"/solace-agent-mesh/docs/documentation/components/builtin-tools/",children:"Built-in Tools"}),"."]}),"\n",(0,s.jsx)(t.h2,{id:"command-line-interface",children:"Command Line Interface"}),"\n",(0,s.jsxs)(t.p,{children:["The CLI provides the primary interface for managing your Agent Mesh deployment. You can use it to start agents, configure gateways, monitor system health, and perform administrative tasks. The CLI simplifies complex operations and provides helpful feedback during development and deployment. For complete CLI documentation and command reference, see ",(0,s.jsx)(t.a,{href:"/solace-agent-mesh/docs/documentation/components/cli",children:"CLI"}),"."]})]})}function m(e={}){const{wrapper:t}={...(0,a.R)(),...e.components};return t?(0,s.jsx)(t,{...e,children:(0,s.jsx)(d,{...e})}):d(e)}},8453:(e,t,n)=>{n.d(t,{R:()=>i,x:()=>r});var o=n(6540);const s={},a=o.createContext(s);function i(e){const t=o.useContext(a);return o.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),o.createElement(a.Provider,{value:t},e.children)}}}]);

solace_agent_mesh/assets/docs/assets/js/3ac1795d.7f7ab1c1.js

@@ -0,0 +1 @@
+"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[3556],{2084:(e,t,n)=>{n.r(t),n.d(t,{assets:()=>d,contentTitle:()=>l,default:()=>h,frontMatter:()=>a,metadata:()=>s,toc:()=>c});const s=JSON.parse('{"id":"documentation/components/builtin-tools/embeds","title":"Dynamic Embeds","description":"Dynamic Embeds","source":"@site/docs/documentation/components/builtin-tools/embeds.md","sourceDirName":"documentation/components/builtin-tools","slug":"/documentation/components/builtin-tools/embeds","permalink":"/solace-agent-mesh/docs/documentation/components/builtin-tools/embeds","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/components/builtin-tools/embeds.md","tags":[],"version":"current","sidebarPosition":40,"frontMatter":{"title":"Dynamic Embeds","sidebar_position":40},"sidebar":"docSidebar","previous":{"title":"Image Tools","permalink":"/solace-agent-mesh/docs/documentation/components/builtin-tools/image-tools"},"next":{"title":"Research Tools","permalink":"/solace-agent-mesh/docs/documentation/components/builtin-tools/research-tools"}}');var i=n(4848),r=n(8453);const a={title:"Dynamic Embeds",sidebar_position:40},l=void 0,d={},c=[{value:"Dynamic Embeds",id:"dynamic-embeds",level:2},{value:"Overview",id:"overview",level:3},{value:"Syntax",id:"syntax",level:3},{value:"Simple Syntax",id:"simple-syntax",level:4},{value:"Chain Syntax",id:"chain-syntax",level:4},{value:"Available Embed Types",id:"available-embed-types",level:3},{value:"General Purpose Embeds",id:"general-purpose-embeds",level:4},{value:"Artifact-Related Embeds",id:"artifact-related-embeds",level:4},{value:"<code>artifact_meta</code>",id:"artifact_meta",level:5},{value:"<code>artifact_return</code>",id:"artifact_return",level:5},{value:"<code>artifact_content</code>",id:"artifact_content",level:5},{value:"Technical Details",id:"technical-details",level:3},{value:"Resolution Stages",id:"resolution-stages",level:4},{value:"Configuration",id:"configuration",level:4},{value:"Error Handling",id:"error-handling",level:3},{value:"Templates",id:"templates",level:2},{value:"Using Templates for Formatted Output",id:"using-templates-for-formatted-output",level:3},{value:"The Templating Workflow",id:"the-templating-workflow",level:3},{value:"Step 1: Create a Mustache Template",id:"step-1-create-a-mustache-template",level:4},{value:"Step 2: Store the Template as an Artifact",id:"step-2-store-the-template-as-an-artifact",level:4},{value:"Step 3: Render the Template with an Embed",id:"step-3-render-the-template-with-an-embed",level:4},{value:"Error Handling",id:"error-handling-1",level:3}];function o(e){const t={a:"a",blockquote:"blockquote",code:"code",em:"em",h2:"h2",h3:"h3",h4:"h4",h5:"h5",hr:"hr",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,r.R)(),...e.components};return(0,i.jsxs)(i.Fragment,{children:[(0,i.jsx)(t.h2,{id:"dynamic-embeds",children:"Dynamic Embeds"}),"\n",(0,i.jsxs)(t.p,{children:["Dynamic embeds provide a mechanism for agents to insert context-dependent information into their text responses or tool parameters using a specialized ",(0,i.jsx)(t.code,{children:"\xab...\xbb"})," syntax. This feature allows for the dynamic retrieval and formatting of data without requiring explicit tool calls for simple data retrieval or calculations."]}),"\n",(0,i.jsx)(t.h3,{id:"overview",children:"Overview"}),"\n",(0,i.jsx)(t.p,{children:"Dynamic embeds allow an agent to defer the inclusion of data until it is needed, resolving the value just before the final response is sent to the user."}),"\n",(0,i.jsxs)(t.ul,{children:["\n",(0,i.jsxs)(t.li,{children:[(0,i.jsx)(t.strong,{children:"Standard Approach"}),': "The current time is [call ',(0,i.jsx)(t.code,{children:"get_time"}),' tool]."']}),"\n",(0,i.jsxs)(t.li,{children:[(0,i.jsx)(t.strong,{children:"With Dynamic Embeds"}),': "The current time is ',(0,i.jsx)(t.code,{children:"\xabdatetime:%H:%M\xbb"}),'."']}),"\n"]}),"\n",(0,i.jsx)(t.p,{children:'The system resolves the embed directive, a dynamic placeholder for data that gets computed at runtime, replacing it with the evaluated result (for example, "The current time is 10:45.").'}),"\n",(0,i.jsx)(t.h3,{id:"syntax",children:"Syntax"}),"\n",(0,i.jsx)(t.p,{children:"There are two primary syntaxes for embed directives."}),"\n",(0,i.jsx)(t.h4,{id:"simple-syntax",children:"Simple Syntax"}),"\n",(0,i.jsx)(t.p,{children:"This syntax is used for most general-purpose embeds."}),"\n",(0,i.jsx)(t.pre,{children:(0,i.jsx)(t.code,{children:"\xabtype:expression | format_spec\xbb\n"})}),"\n",(0,i.jsxs)(t.ul,{children:["\n",(0,i.jsxs)(t.li,{children:[(0,i.jsx)(t.strong,{children:(0,i.jsx)(t.code,{children:"type"})}),": A keyword indicating the type of information to embed (for example, ",(0,i.jsx)(t.code,{children:"state"}),", ",(0,i.jsx)(t.code,{children:"math"}),", ",(0,i.jsx)(t.code,{children:"datetime"}),")."]}),"\n",(0,i.jsxs)(t.li,{children:[(0,i.jsx)(t.strong,{children:(0,i.jsx)(t.code,{children:"expression"})}),": The specific data to retrieve or the expression to evaluate."]}),"\n",(0,i.jsxs)(t.li,{children:[(0,i.jsx)(t.strong,{children:(0,i.jsx)(t.code,{children:"format_spec"})}),": (Optional) A specifier for formatting the output value (for example, a number precision ",(0,i.jsx)(t.code,{children:".2f"})," or a ",(0,i.jsx)(t.code,{children:"strftime"})," string ",(0,i.jsx)(t.code,{children:"%Y-%m-%d"}),")."]}),"\n"]}),"\n",(0,i.jsx)(t.h4,{id:"chain-syntax",children:"Chain Syntax"}),"\n",(0,i.jsxs)(t.p,{children:["This syntax is used exclusively for the ",(0,i.jsx)(t.code,{children:"artifact_content"})," embed type to apply a sequence of transformations."]}),"\n",(0,i.jsx)(t.pre,{children:(0,i.jsx)(t.code,{children:"\xabartifact_content:spec >>> modifier1 >>> modifier2 >>> format:output_format\xbb\n"})}),"\n",(0,i.jsxs)(t.ul,{children:["\n",(0,i.jsxs)(t.li,{children:[(0,i.jsx)(t.strong,{children:(0,i.jsx)(t.code,{children:"artifact_spec"})}),": The artifact identifier (",(0,i.jsx)(t.code,{children:"filename[:version]"}),")."]}),"\n",(0,i.jsxs)(t.li,{children:[(0,i.jsx)(t.strong,{children:(0,i.jsx)(t.code,{children:">>>"})}),": The chain delimiter, separating transformation steps."]}),"\n",(0,i.jsxs)(t.li,{children:[(0,i.jsx)(t.strong,{children:(0,i.jsx)(t.code,{children:"modifier"})}),": A transformation to apply to the data (for example, ",(0,i.jsx)(t.code,{children:"jsonpath"}),", ",(0,i.jsx)(t.code,{children:"grep"}),", ",(0,i.jsx)(t.code,{children:"slice_lines"}),")."]}),"\n",(0,i.jsxs)(t.li,{children:[(0,i.jsx)(t.strong,{children:(0,i.jsx)(t.code,{children:"format"})}),": A ",(0,i.jsx)(t.strong,{children:"required"})," final step that specifies the output format (for example, ",(0,i.jsx)(t.code,{children:"text"}),", ",(0,i.jsx)(t.code,{children:"json"}),", ",(0,i.jsx)(t.code,{children:"datauri"}),")."]}),"\n"]}),"\n",(0,i.jsx)(t.h3,{id:"available-embed-types",children:"Available Embed Types"}),"\n",(0,i.jsx)(t.h4,{id:"general-purpose-embeds",children:"General Purpose Embeds"}),"\n",(0,i.jsx)(t.p,{children:"These are typically resolved by the agent host during execution."}),"\n",(0,i.jsxs)(t.table,{children:[(0,i.jsx)(t.thead,{children:(0,i.jsxs)(t.tr,{children:[(0,i.jsx)(t.th,{children:"Type"}),(0,i.jsx)(t.th,{children:"Description"}),(0,i.jsx)(t.th,{children:"Example"})]})}),(0,i.jsxs)(t.tbody,{children:[(0,i.jsxs)(t.tr,{children:[(0,i.jsx)(t.td,{children:(0,i.jsx)(t.strong,{children:(0,i.jsx)(t.code,{children:"state"})})}),(0,i.jsx)(t.td,{children:"Accesses a session state variable."}),(0,i.jsx)(t.td,{children:(0,i.jsx)(t.code,{children:"\xabstate:user_name\xbb"})})]}),(0,i.jsxs)(t.tr,{children:[(0,i.jsx)(t.td,{children:(0,i.jsx)(t.strong,{children:(0,i.jsx)(t.code,{children:"math"})})}),(0,i.jsx)(t.td,{children:"Evaluates a mathematical expression."}),(0,i.jsxs)(t.td,{children:[(0,i.jsx)(t.code,{children:"\xabmath:100 * 0.05 | .2f\xbb"})," (Result: ",(0,i.jsx)(t.code,{children:"5.00"}),")"]})]}),(0,i.jsxs)(t.tr,{children:[(0,i.jsx)(t.td,{children:(0,i.jsx)(t.strong,{children:(0,i.jsx)(t.code,{children:"datetime"})})}),(0,i.jsx)(t.td,{children:"Inserts the current date and/or time."}),(0,i.jsxs)(t.td,{children:[(0,i.jsx)(t.code,{children:"\xabdatetime:%Y-%m-%d\xbb"})," (Result: ",(0,i.jsx)(t.code,{children:"2023-10-27"}),")"]})]}),(0,i.jsxs)(t.tr,{children:[(0,i.jsx)(t.td,{children:(0,i.jsx)(t.strong,{children:(0,i.jsx)(t.code,{children:"uuid"})})}),(0,i.jsx)(t.td,{children:"Inserts a random Version 4 UUID."}),(0,i.jsx)(t.td,{children:(0,i.jsx)(t.code,{children:"\xabuuid:\xbb"})})]}),(0,i.jsxs)(t.tr,{children:[(0,i.jsx)(t.td,{children:(0,i.jsx)(t.strong,{children:(0,i.jsx)(t.code,{children:"status_update"})})}),(0,i.jsx)(t.td,{children:"Signals a temporary status update to the UI."}),(0,i.jsx)(t.td,{children:(0,i.jsx)(t.code,{children:"\xabstatus_update:Searching knowledge base...\xbb"})})]})]})]}),"\n",(0,i.jsx)(t.h4,{id:"artifact-related-embeds",children:"Artifact-Related Embeds"}),"\n",(0,i.jsx)(t.h5,{id:"artifact_meta",children:(0,i.jsx)(t.code,{children:"artifact_meta"})}),"\n",(0,i.jsx)(t.p,{children:"Retrieves a JSON string containing the full metadata of a specified artifact."}),"\n",(0,i.jsxs)(t.ul,{children:["\n",(0,i.jsxs)(t.li,{children:[(0,i.jsx)(t.strong,{children:"Syntax"}),": ",(0,i.jsx)(t.code,{children:"\xabartifact_meta:filename[:version]\xbb"})]}),"\n",(0,i.jsxs)(t.li,{children:[(0,i.jsx)(t.strong,{children:"Example"}),": ",(0,i.jsx)(t.code,{children:"\xabartifact_meta:report.csv\xbb"})]}),"\n"]}),"\n",(0,i.jsx)(t.h5,{id:"artifact_return",children:(0,i.jsx)(t.code,{children:"artifact_return"})}),"\n",(0,i.jsxs)(t.p,{children:[(0,i.jsx)(t.strong,{children:"This is the primary way to return an artifact to the user."})," It attaches the specified artifact to the message as a file attachment. The embed itself is removed from the text during gateway processing."]}),"\n",(0,i.jsxs)(t.ul,{children:["\n",(0,i.jsxs)(t.li,{children:[(0,i.jsx)(t.strong,{children:"Syntax"}),": ",(0,i.jsx)(t.code,{children:"\xabartifact_return:filename[:version]\xbb"})]}),"\n",(0,i.jsxs)(t.li,{children:[(0,i.jsx)(t.strong,{children:"Resolution"}),": Late-stage (processed by gateway before sending to user)"]}),"\n",(0,i.jsxs)(t.li,{children:[(0,i.jsx)(t.strong,{children:"Examples"}),":","\n",(0,i.jsxs)(t.ul,{children:["\n",(0,i.jsxs)(t.li,{children:[(0,i.jsx)(t.code,{children:"\xabartifact_return:report.pdf\xbb"})," - Returns the latest version of report.pdf"]}),"\n",(0,i.jsxs)(t.li,{children:[(0,i.jsx)(t.code,{children:"\xabartifact_return:data.csv:3\xbb"})," - Returns version 3 of data.csv"]}),"\n"]}),"\n"]}),"\n",(0,i.jsxs)(t.li,{children:[(0,i.jsx)(t.strong,{children:"Note"}),": ",(0,i.jsx)(t.code,{children:"artifact_return"})," is not necessary if the artifact was just created in the same response, since newly created artifacts are automatically attached to messages."]}),"\n"]}),"\n",(0,i.jsx)(t.h5,{id:"artifact_content",children:(0,i.jsx)(t.code,{children:"artifact_content"})}),"\n",(0,i.jsx)(t.p,{children:"Embeds the content of an artifact, with support for a chain of transformations. This is the most advanced embed type."}),"\n",(0,i.jsxs)(t.p,{children:[(0,i.jsx)(t.strong,{children:"Note"}),": If this embed resolves to binary content (like an image), it will be automatically converted into an attached file, similar to ",(0,i.jsx)(t.code,{children:"artifact_return"}),"."]}),"\n",(0,i.jsxs)(t.p,{children:[(0,i.jsx)(t.strong,{children:"Modifiers (Data Transformations)"}),"\nModifiers are applied sequentially to transform the data."]}),"\n",(0,i.jsxs)(t.table,{children:[(0,i.jsx)(t.thead,{children:(0,i.jsxs)(t.tr,{children:[(0,i.jsx)(t.th,{children:"Modifier"}),(0,i.jsx)(t.th,{children:"Description"})]})}),(0,i.jsxs)(t.tbody,{children:[(0,i.jsxs)(t.tr,{children:[(0,i.jsx)(t.td,{children:(0,i.jsx)(t.code,{children:"jsonpath:<expr>"})}),(0,i.jsx)(t.td,{children:"Applies a JSONPath query to JSON data."})]}),(0,i.jsxs)(t.tr,{children:[(0,i.jsx)(t.td,{children:(0,i.jsx)(t.code,{children:"select_cols:<c1,c2>"})}),(0,i.jsx)(t.td,{children:"Selects specific columns from CSV data."})]}),(0,i.jsxs)(t.tr,{children:[(0,i.jsx)(t.td,{children:(0,i.jsx)(t.code,{children:"filter_rows_eq:<col>:<val>"})}),(0,i.jsx)(t.td,{children:"Filters CSV rows where a column's value equals the specified value."})]}),(0,i.jsxs)(t.tr,{children:[(0,i.jsx)(t.td,{children:(0,i.jsx)(t.code,{children:"slice_rows:<start>:<end>"})}),(0,i.jsx)(t.td,{children:"Selects a slice of rows from CSV data."})]}),(0,i.jsxs)(t.tr,{children:[(0,i.jsx)(t.td,{children:(0,i.jsx)(t.code,{children:"slice_lines:<start>:<end>"})}),(0,i.jsx)(t.td,{children:"Selects a slice of lines from text data."})]}),(0,i.jsxs)(t.tr,{children:[(0,i.jsx)(t.td,{children:(0,i.jsx)(t.code,{children:"grep:<pattern>"})}),(0,i.jsx)(t.td,{children:"Filters lines matching a regular expression in text data."})]}),(0,i.jsxs)(t.tr,{children:[(0,i.jsxs)(t.td,{children:[(0,i.jsx)(t.code,{children:"head:<N>"})," / ",(0,i.jsx)(t.code,{children:"tail:<N>"})]}),(0,i.jsx)(t.td,{children:"Returns the first or last N lines of text data."})]}),(0,i.jsxs)(t.tr,{children:[(0,i.jsx)(t.td,{children:(0,i.jsx)(t.code,{children:"select_fields:<f1,f2>"})}),(0,i.jsx)(t.td,{children:"Selects specific fields from a list of dictionaries."})]}),(0,i.jsxs)(t.tr,{children:[(0,i.jsx)(t.td,{children:(0,i.jsx)(t.code,{children:"apply_to_template:<file>"})}),(0,i.jsxs)(t.td,{children:["Renders data using a Mustache template artifact. See the ",(0,i.jsx)(t.a,{href:"#templates",children:"Templates Guide"}),"."]})]})]})]}),"\n",(0,i.jsxs)(t.p,{children:[(0,i.jsx)(t.strong,{children:"Formatters (Final Output)"}),"\nThis is the ",(0,i.jsx)(t.strong,{children:"required"})," final step in an ",(0,i.jsx)(t.code,{children:"artifact_content"})," chain, defining the output format."]}),"\n",(0,i.jsxs)(t.table,{children:[(0,i.jsx)(t.thead,{children:(0,i.jsxs)(t.tr,{children:[(0,i.jsx)(t.th,{children:"Formatter"}),(0,i.jsx)(t.th,{children:"Description"})]})}),(0,i.jsxs)(t.tbody,{children:[(0,i.jsxs)(t.tr,{children:[(0,i.jsx)(t.td,{children:(0,i.jsx)(t.code,{children:"text"})}),(0,i.jsx)(t.td,{children:"Plain text, decoded as UTF-8."})]}),(0,i.jsxs)(t.tr,{children:[(0,i.jsxs)(t.td,{children:[(0,i.jsx)(t.code,{children:"json"})," / ",(0,i.jsx)(t.code,{children:"json_pretty"})]}),(0,i.jsx)(t.td,{children:"A compact or indented JSON string."})]}),(0,i.jsxs)(t.tr,{children:[(0,i.jsx)(t.td,{children:(0,i.jsx)(t.code,{children:"csv"})}),(0,i.jsx)(t.td,{children:"A CSV formatted string."})]}),(0,i.jsxs)(t.tr,{children:[(0,i.jsx)(t.td,{children:(0,i.jsx)(t.code,{children:"datauri"})}),(0,i.jsxs)(t.td,{children:["A Base64-encoded data URI, typically for images (",(0,i.jsx)(t.code,{children:"data:image/png;base64,..."}),")."]})]})]})]}),"\n",(0,i.jsx)(t.p,{children:(0,i.jsxs)(t.strong,{children:[(0,i.jsx)(t.code,{children:"artifact_content"})," Examples:"]})}),"\n",(0,i.jsxs)(t.ul,{children:["\n",(0,i.jsxs)(t.li,{children:["To embed an image for display in a UI:\n",(0,i.jsx)(t.code,{children:"\xabartifact_content:logo.png >>> format:datauri\xbb"})]}),"\n",(0,i.jsxs)(t.li,{children:["To extract and format specific data from a JSON file:\n",(0,i.jsx)(t.code,{children:"\xabartifact_content:results.json >>> jsonpath:$.data[*].name >>> format:json\xbb"})]}),"\n",(0,i.jsxs)(t.li,{children:["To get the last 10 lines of a log file:\n",(0,i.jsx)(t.code,{children:"\xabartifact_content:debug.log >>> tail:10 >>> format:text\xbb"})]}),"\n",(0,i.jsxs)(t.li,{children:["To filter a CSV file and render it using an HTML template:\n",(0,i.jsx)(t.code,{children:"\xabartifact_content:users.csv >>> filter_rows_eq:Status:Active >>> apply_to_template:active_users.html >>> format:text\xbb"})]}),"\n"]}),"\n",(0,i.jsx)(t.h3,{id:"technical-details",children:"Technical Details"}),"\n",(0,i.jsx)(t.h4,{id:"resolution-stages",children:"Resolution Stages"}),"\n",(0,i.jsx)(t.p,{children:"Embeds are resolved in two distinct stages, depending on where the required data is available:"}),"\n",(0,i.jsxs)(t.ol,{children:["\n",(0,i.jsxs)(t.li,{children:[(0,i.jsx)(t.strong,{children:"Early Stage (Agent Host)"}),": Resolved by the agent runtime itself. This stage handles simple, context-local embeds like ",(0,i.jsx)(t.code,{children:"state"}),", ",(0,i.jsx)(t.code,{children:"math"}),", and ",(0,i.jsx)(t.code,{children:"datetime"}),"."]}),"\n",(0,i.jsxs)(t.li,{children:[(0,i.jsx)(t.strong,{children:"Late Stage (Gateway)"}),": Resolved by the Gateway component before the final message is sent to the client. This is necessary for ",(0,i.jsx)(t.code,{children:"artifact_content"})," embeds, which may involve large files or transformations that are too resource-intensive for the agent host."]}),"\n"]}),"\n",(0,i.jsx)(t.h4,{id:"configuration",children:"Configuration"}),"\n",(0,i.jsxs)(t.ul,{children:["\n",(0,i.jsxs)(t.li,{children:[(0,i.jsx)(t.strong,{children:"Enabling/Disabling"}),": Embed resolution is enabled by default. It can be disabled in the ",(0,i.jsx)(t.code,{children:"app_config"})," of the agent host or gateway by setting ",(0,i.jsx)(t.code,{children:"enable_embed_resolution: false"}),"."]}),"\n",(0,i.jsxs)(t.li,{children:[(0,i.jsx)(t.strong,{children:"Resource Limits"}),": The gateway enforces configurable limits to prevent abuse, including ",(0,i.jsx)(t.code,{children:"gateway_artifact_content_limit_bytes"})," (default: 32KB) and ",(0,i.jsx)(t.code,{children:"gateway_recursive_embed_depth"})," (default: 3)."]}),"\n"]}),"\n",(0,i.jsx)(t.h3,{id:"error-handling",children:"Error Handling"}),"\n",(0,i.jsx)(t.p,{children:"If an embed directive fails during parsing or evaluation, it is replaced with a descriptive error message in the final output."}),"\n",(0,i.jsxs)(t.ul,{children:["\n",(0,i.jsxs)(t.li,{children:[(0,i.jsx)(t.strong,{children:"Parsing Error"}),": ",(0,i.jsx)(t.code,{children:"[Error: Invalid modifier format: 'badmodifier']"})]}),"\n",(0,i.jsxs)(t.li,{children:[(0,i.jsx)(t.strong,{children:"Evaluation Error"}),": ",(0,i.jsx)(t.code,{children:"[Error: State variable 'user_id' not found]"})]}),"\n",(0,i.jsxs)(t.li,{children:[(0,i.jsx)(t.strong,{children:"Limit Exceeded"}),": ",(0,i.jsx)(t.code,{children:"[Error: Artifact 'large_file.zip' exceeds size limit]"})]}),"\n"]}),"\n",(0,i.jsx)(t.h2,{id:"templates",children:"Templates"}),"\n",(0,i.jsx)(t.h3,{id:"using-templates-for-formatted-output",children:"Using Templates for Formatted Output"}),"\n",(0,i.jsxs)(t.p,{children:["The ",(0,i.jsx)(t.code,{children:"apply_to_template"})," modifier, used within an ",(0,i.jsx)(t.code,{children:"\xabartifact_content:...\xbb"})," embed directive, enables an agent to render structured data using a ",(0,i.jsx)(t.strong,{children:"Mustache template"}),". This mechanism allows for the separation of data and presentation, enabling the agent to control the output format (for example, HTML, Markdown) without generating the formatting markup itself."]}),"\n",(0,i.jsx)(t.h3,{id:"the-templating-workflow",children:"The Templating Workflow"}),"\n",(0,i.jsx)(t.p,{children:"The process involves three distinct steps:"}),"\n",(0,i.jsxs)(t.ol,{children:["\n",(0,i.jsxs)(t.li,{children:[(0,i.jsx)(t.strong,{children:"Template Creation"}),": Author a Mustache template file that defines the desired output structure."]}),"\n",(0,i.jsxs)(t.li,{children:[(0,i.jsx)(t.strong,{children:"Artifact Storage"}),": Persist the template file as an artifact in the agent's artifact storage using the ",(0,i.jsx)(t.code,{children:"create_artifact"})," tool."]}),"\n",(0,i.jsxs)(t.li,{children:[(0,i.jsx)(t.strong,{children:"Template Rendering"}),": Utilize an ",(0,i.jsx)(t.code,{children:"\xabartifact_content:...\xbb"})," embed chain to process a data artifact and then apply the stored template to the result."]}),"\n"]}),"\n",(0,i.jsx)(t.hr,{}),"\n",(0,i.jsx)(t.h4,{id:"step-1-create-a-mustache-template",children:"Step 1: Create a Mustache Template"}),"\n",(0,i.jsxs)(t.p,{children:["Mustache is a logic-less template syntax. Templates are created as text files (for example, ",(0,i.jsx)(t.code,{children:"user_table.html.mustache"}),") containing placeholders for data injection."]}),"\n",(0,i.jsxs)(t.p,{children:[(0,i.jsx)(t.strong,{children:"Key Mustache Syntax"}),":"]}),"\n",(0,i.jsxs)(t.ul,{children:["\n",(0,i.jsxs)(t.li,{children:[(0,i.jsx)(t.strong,{children:(0,i.jsx)(t.code,{children:"{{variable}}"})}),": A variable placeholder. It is replaced with the corresponding value from the data context."]}),"\n",(0,i.jsxs)(t.li,{children:[(0,i.jsx)(t.strong,{children:(0,i.jsx)(t.code,{children:"{{#section}}...{{/section}}"})}),": A section tag. The enclosed block is rendered for each item in a list or if the section variable is a non-empty object or truthy value."]}),"\n",(0,i.jsxs)(t.li,{children:[(0,i.jsx)(t.strong,{children:(0,i.jsx)(t.code,{children:"{{^section}}...{{/section}}"})}),": An inverted section tag. The enclosed block is rendered only if the section variable is false, null, or an empty list."]}),"\n",(0,i.jsxs)(t.li,{children:[(0,i.jsx)(t.strong,{children:(0,i.jsx)(t.code,{children:"{{! comment }}"})}),": A comment tag. The content is ignored during rendering."]}),"\n"]}),"\n",(0,i.jsxs)(t.p,{children:[(0,i.jsxs)(t.strong,{children:["Example: ",(0,i.jsx)(t.code,{children:"user_table.html.mustache"})]}),"\nThis template generates an HTML table from a list of user objects."]}),"\n",(0,i.jsx)(t.pre,{children:(0,i.jsx)(t.code,{className:"language-html",children:"<h2>User List</h2>\n{{#items}}\n<table>\n  <thead>\n    <tr>\n      <th>Name</th>\n      <th>Status</th>\n    </tr>\n  </thead>\n  <tbody>\n    {{#.}}\n    <tr>\n      <td>{{name}}</td>\n      <td>{{status}}</td>\n    </tr>\n    {{/.}}\n  </tbody>\n</table>\n{{/items}}\n{{^items}}\n<p>No users found.</p>\n{{/items}}\n"})}),"\n",(0,i.jsx)(t.hr,{}),"\n",(0,i.jsx)(t.h4,{id:"step-2-store-the-template-as-an-artifact",children:"Step 2: Store the Template as an Artifact"}),"\n",(0,i.jsxs)(t.p,{children:["The template must be stored as an artifact to be accessible by the Gateway during the late-stage embed resolution process. This is accomplished using the ",(0,i.jsx)(t.code,{children:"create_artifact"})," tool."]}),"\n",(0,i.jsxs)(t.p,{children:[(0,i.jsx)(t.strong,{children:"Example Agent Interaction"}),":"]}),"\n",(0,i.jsxs)(t.blockquote,{children:["\n",(0,i.jsxs)(t.p,{children:[(0,i.jsx)(t.strong,{children:"User"}),': "Please create an HTML template to display a list of users."\n',(0,i.jsx)(t.strong,{children:"Agent"}),': "Acknowledged. I will create the template artifact ',(0,i.jsx)(t.code,{children:"user_table.html.mustache"}),'."\n',(0,i.jsxs)(t.em,{children:["(The agent then invokes the ",(0,i.jsx)(t.code,{children:"create_artifact"})," tool with the specified filename and the HTML content from Step 1.)"]})]}),"\n"]}),"\n",(0,i.jsx)(t.hr,{}),"\n",(0,i.jsx)(t.h4,{id:"step-3-render-the-template-with-an-embed",children:"Step 3: Render the Template with an Embed"}),"\n",(0,i.jsxs)(t.p,{children:["With the data and template artifacts stored, the agent can construct an ",(0,i.jsx)(t.code,{children:"artifact_content"})," embed chain to perform the rendering."]}),"\n",(0,i.jsxs)(t.ul,{children:["\n",(0,i.jsxs)(t.li,{children:[(0,i.jsx)(t.strong,{children:"Syntax"}),": ",(0,i.jsx)(t.code,{children:"... >>> apply_to_template:template_filename[:version] >>> ..."})]}),"\n",(0,i.jsxs)(t.li,{children:[(0,i.jsx)(t.strong,{children:"Data Context"}),": The data provided to the template engine is the output of the preceding modifier in the chain.","\n",(0,i.jsxs)(t.ul,{children:["\n",(0,i.jsxs)(t.li,{children:["If the data is a ",(0,i.jsx)(t.strong,{children:"list"}),", it is automatically wrapped in a dictionary of the form ",(0,i.jsx)(t.code,{children:"{'items': your_list}"}),". The template should use ",(0,i.jsx)(t.code,{children:"{{#items}}"})," to iterate over this list."]}),"\n",(0,i.jsxs)(t.li,{children:["If the data is a ",(0,i.jsx)(t.strong,{children:"dictionary"}),", it is used directly as the rendering context."]}),"\n"]}),"\n"]}),"\n",(0,i.jsxs)(t.li,{children:[(0,i.jsx)(t.strong,{children:"Output Format"}),": It is ",(0,i.jsx)(t.strong,{children:"mandatory"})," to terminate the chain with a ",(0,i.jsx)(t.code,{children:"format:"})," step (for example, ",(0,i.jsx)(t.code,{children:"format:text"}),") to specify the MIME type of the final rendered output."]}),"\n"]}),"\n",(0,i.jsxs)(t.p,{children:[(0,i.jsx)(t.strong,{children:"Complete Example"}),":\nThe following embed chain processes a JSON file and renders its content using the HTML template created in Step 1."]}),"\n",(0,i.jsx)(t.pre,{children:(0,i.jsx)(t.code,{children:"\xabartifact_content:user_data.json >>> jsonpath:$.users[*] >>> select_fields:name,status >>> apply_to_template:user_table.html.mustache >>> format:text\xbb\n"})}),"\n",(0,i.jsxs)(t.p,{children:[(0,i.jsx)(t.strong,{children:"Execution Flow"}),":"]}),"\n",(0,i.jsxs)(t.ol,{children:["\n",(0,i.jsxs)(t.li,{children:[(0,i.jsx)(t.code,{children:"artifact_content:user_data.json"}),": Loads the raw data from the ",(0,i.jsx)(t.code,{children:"user_data.json"})," artifact."]}),"\n",(0,i.jsxs)(t.li,{children:[(0,i.jsx)(t.code,{children:"jsonpath:$.users[*]"}),": Applies a JSONPath expression to extract the list of user objects."]}),"\n",(0,i.jsxs)(t.li,{children:[(0,i.jsx)(t.code,{children:"select_fields:name,status"}),": Filters each object in the list to retain only the ",(0,i.jsx)(t.code,{children:"name"})," and ",(0,i.jsx)(t.code,{children:"status"})," fields."]}),"\n",(0,i.jsxs)(t.li,{children:[(0,i.jsx)(t.code,{children:"apply_to_template:user_table.html.mustache"}),": Renders the resulting list of users using the specified Mustache template."]}),"\n"]}),"\n",(0,i.jsx)(t.h3,{id:"error-handling-1",children:"Error Handling"}),"\n",(0,i.jsxs)(t.ul,{children:["\n",(0,i.jsxs)(t.li,{children:[(0,i.jsx)(t.strong,{children:"Template Not Found"}),": If the specified template artifact does not exist, the embed resolves to ",(0,i.jsx)(t.code,{children:"[Error: Template artifact '...' not found]"}),"."]}),"\n",(0,i.jsxs)(t.li,{children:[(0,i.jsx)(t.strong,{children:"Rendering Error"}),": If the data structure is incompatible with the template's expectations, the embed resolves to ",(0,i.jsx)(t.code,{children:"[Error: Error rendering template '...']"}),"."]}),"\n"]})]})}function h(e={}){const{wrapper:t}={...(0,r.R)(),...e.components};return t?(0,i.jsx)(t,{...e,children:(0,i.jsx)(o,{...e})}):o(e)}},8453:(e,t,n)=>{n.d(t,{R:()=>a,x:()=>l});var s=n(6540);const i={},r=s.createContext(i);function a(e){const t=s.useContext(r);return s.useMemo((function(){return"function"==typeof e?e(t):{...t,...e}}),[t,e])}function l(e){let t;return t=e.disableParentContext?"function"==typeof e.components?e.components(i):e.components||i:a(e.components),s.createElement(r.Provider,{value:t},e.children)}}}]);

solace_agent_mesh/assets/docs/assets/js/3ff0015d.e53c9b78.js

@@ -0,0 +1 @@
+"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[9740],{4792:(e,n,i)=>{i.r(n),i.d(n,{assets:()=>c,contentTitle:()=>a,default:()=>h,frontMatter:()=>t,metadata:()=>s,toc:()=>d});const s=JSON.parse('{"id":"documentation/components/cli","title":"Agent Mesh CLI","description":"Agent Mesh comes with a comprehensive CLI tool that you can use to create, and run an instance of Agent Mesh, which is referred to as an Agent Mesh application. Agent Mesh CLI also allows you to add agents and gateways, manage plugins, help you debug, and much more.","source":"@site/docs/documentation/components/cli.md","sourceDirName":"documentation/components","slug":"/documentation/components/cli","permalink":"/solace-agent-mesh/docs/documentation/components/cli","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/components/cli.md","tags":[],"version":"current","sidebarPosition":280,"frontMatter":{"title":"Agent Mesh CLI","sidebar_position":280,"toc_max_heading_level":4},"sidebar":"docSidebar","previous":{"title":"Projects","permalink":"/solace-agent-mesh/docs/documentation/components/projects"},"next":{"title":"Configuring Built-in Tools","permalink":"/solace-agent-mesh/docs/documentation/components/builtin-tools/"}}');var l=i(4848),o=i(8453);const t={title:"Agent Mesh CLI",sidebar_position:280,toc_max_heading_level:4},a="Agent Mesh CLI",c={},d=[{value:"Installation",id:"installation",level:2},{value:"Commands",id:"commands",level:2},{value:"<code>init</code> - Initialize an Agent Mesh Application",id:"init---initialize-an-agent-mesh-application",level:3},{value:"Options:",id:"options",level:5},{value:"<code>add</code> - Create a New Component",id:"add---create-a-new-component",level:3},{value:"Add <code>agent</code>",id:"add-agent",level:4},{value:"Options:",id:"options-1",level:5},{value:"Add <code>gateway</code>",id:"add-gateway",level:4},{value:"Options:",id:"options-2",level:5},{value:"Add <code>proxy</code>",id:"add-proxy",level:4},{value:"Options:",id:"options-3",level:5},{value:"Example:",id:"example",level:5},{value:"<code>run</code> - Run the Agent Mesh Application",id:"run---run-the-agent-mesh-application",level:3},{value:"Options:",id:"options-4",level:5},{value:"<code>docs</code> - Serve the documentation locally",id:"docs---serve-the-documentation-locally",level:3},{value:"Options:",id:"options-5",level:5},{value:"<code>tools</code> - Manage and Explore Built-in Tools",id:"tools---manage-and-explore-built-in-tools",level:3},{value:"<code>list</code> - List Built-in Tools",id:"list---list-built-in-tools",level:4},{value:"Options:",id:"options-6",level:5},{value:"<code>plugin</code> - Manage Plugins",id:"plugin---manage-plugins",level:3},{value:"<code>create</code> - Create a Plugin",id:"create---create-a-plugin",level:4},{value:"Options:",id:"options-7",level:5},{value:"<code>build</code> - Build the Plugin",id:"build---build-the-plugin",level:4},{value:"Options:",id:"options-8",level:5},{value:"<code>add</code> - Add an Existing Plugin",id:"add---add-an-existing-plugin",level:4},{value:"Options:",id:"options-9",level:5},{value:"<code>installs</code> - Installs a Plugin",id:"installs---installs-a-plugin",level:4},{value:"Options:",id:"options-10",level:5},{value:"<code>catalog</code> - Launch Plugin Catalog",id:"catalog---launch-plugin-catalog",level:4},{value:"Options:",id:"options-11",level:5}];function r(e){const n={a:"a",admonition:"admonition",code:"code",h1:"h1",h2:"h2",h3:"h3",h4:"h4",h5:"h5",header:"header",li:"li",p:"p",pre:"pre",ul:"ul",...(0,o.R)(),...e.components};return(0,l.jsxs)(l.Fragment,{children:[(0,l.jsx)(n.header,{children:(0,l.jsx)(n.h1,{id:"agent-mesh-cli",children:"Agent Mesh CLI"})}),"\n",(0,l.jsx)(n.p,{children:"Agent Mesh comes with a comprehensive CLI tool that you can use to create, and run an instance of Agent Mesh, which is referred to as an Agent Mesh application. Agent Mesh CLI also allows you to add agents and gateways, manage plugins, help you debug, and much more."}),"\n",(0,l.jsx)(n.h2,{id:"installation",children:"Installation"}),"\n",(0,l.jsxs)(n.p,{children:["The Agent Mesh CLI is installed as part of the Agent Mesh package. For more information, see ",(0,l.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/installing-and-configuring/installation",children:"Installation"}),"."]}),"\n",(0,l.jsx)(n.admonition,{title:"CLI Tips",type:"tip",children:(0,l.jsxs)(n.ul,{children:["\n",(0,l.jsxs)(n.li,{children:["The Agent Mesh CLI comes with a short alias of ",(0,l.jsx)(n.code,{children:"sam"})," which can be used in place of ",(0,l.jsx)(n.code,{children:"solace-agent-mesh"}),"."]}),"\n",(0,l.jsxs)(n.li,{children:["You can determine the version of the Agent Mesh CLI by running ",(0,l.jsx)(n.code,{children:"solace-agent-mesh --version"}),"."]}),"\n",(0,l.jsxs)(n.li,{children:["You can get help on any command by running ",(0,l.jsx)(n.code,{children:"solace-agent-mesh [COMMAND] --help"}),"."]}),"\n"]})}),"\n",(0,l.jsx)(n.h2,{id:"commands",children:"Commands"}),"\n",(0,l.jsxs)(n.h3,{id:"init---initialize-an-agent-mesh-application",children:[(0,l.jsx)(n.code,{children:"init"})," - Initialize an Agent Mesh Application"]}),"\n",(0,l.jsx)(n.pre,{children:(0,l.jsx)(n.code,{className:"language-sh",children:"sam init [OPTIONS]\n"})}),"\n",(0,l.jsx)(n.p,{children:"When this command is run with no options, it runs in interactive mode. It first prompts you to choose between configuring your project in the terminal or through a browser-based interface."}),"\n",(0,l.jsxs)(n.p,{children:["If you choose to use the browser, the Agent Mesh CLI starts a local web configuration portal, available at ",(0,l.jsx)(n.code,{children:"http://127.0.0.1:5002"})]}),"\n",(0,l.jsx)(n.p,{children:"You can skip some questions by providing the appropriate options for that step during the Agent Mesh CLI-based setup."}),"\n",(0,l.jsxs)(n.p,{children:["Optionally, you can skip all the questions by providing the ",(0,l.jsx)(n.code,{children:"--skip"})," option. This option uses the provided or default values for all the questions."]}),"\n",(0,l.jsx)(n.admonition,{title:"automated workflows",type:"tip",children:(0,l.jsxs)(n.p,{children:["Use the ",(0,l.jsx)(n.code,{children:"--skip"})," option and provide the necessary options to run the command in non-interactive mode, useful for automated workflows."]})}),"\n",(0,l.jsx)(n.h5,{id:"options",children:"Options:"}),"\n",(0,l.jsxs)(n.ul,{children:["\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"--gui"})," \u2013 Launch the browser-based initialization interface directly, skipping the prompt. (Recommended way to configure Agent Mesh applications)"]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"--skip"})," \u2013 Runs in non-interactive mode, using default values where available."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"--llm-service-endpoint TEXT"})," \u2013 LLM Service Endpoint URL."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"--llm-service-api-key TEXT"})," \u2013 LLM Service API Key."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"--llm-service-planning-model-name TEXT"})," \u2013 LLM Planning Model Name."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"--llm-service-general-model-name TEXT"})," \u2013 LLM General Model Name."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"--namespace TEXT"})," \u2013 Namespace for the project."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"--broker-type TEXT"})," \u2013 Broker type: 1/solace (existing), 2/container (new local), 3/dev (dev mode). Options: 1, 2, 3, solace, container, dev_mode, dev_broker, dev."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"--broker-url TEXT"})," \u2013 Solace broker URL endpoint."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"--broker-vpn TEXT"})," \u2013 Solace broker VPN name."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"--broker-username TEXT"})," \u2013 Solace broker username."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"--broker-password TEXT"})," \u2013 Solace broker password."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"--container-engine TEXT"})," \u2013 Container engine for local broker. Options: podman, docker."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"--dev-mode"})," \u2013 Shortcut to select dev mode for broker (equivalent to --broker-type 3/dev)."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"--agent-name TEXT"})," \u2013 Agent name for the main orchestrator."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"--supports-streaming"})," \u2013 Enable streaming support for the agent."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"--session-service-type TEXT"})," \u2013 Session service type. Options: memory, vertex_rag."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"--session-service-behavior TEXT"})," \u2013 Session service behavior. Options: PERSISTENT, RUN_BASED."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"--artifact-service-type TEXT"})," \u2013 Artifact service type. Options: memory, filesystem, gcs."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"--artifact-service-base-path TEXT"})," \u2013 Artifact service base path (for filesystem type)."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"--artifact-service-scope TEXT"})," \u2013 Artifact service scope. Options: namespace, app, custom."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"--artifact-handling-mode TEXT"})," \u2013 Artifact handling mode. Options: ignore, embed, reference."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"--enable-embed-resolution"})," \u2013 Enable embed resolution."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"--enable-artifact-content-instruction"})," \u2013 Enable artifact content instruction."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"--enable-builtin-artifact-tools"})," \u2013 Enable built-in artifact tools."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"--enable-builtin-data-tools"})," \u2013 Enable built-in data tools."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"--agent-card-description TEXT"})," \u2013 Agent card description."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"--agent-card-default-input-modes TEXT"})," \u2013 Agent card default input modes (comma-separated)."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"--agent-card-default-output-modes TEXT"})," \u2013 Agent card default output modes (comma-separated)."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"--agent-discovery-enabled"})," \u2013 Enable agent discovery."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"--agent-card-publishing-interval INTEGER"})," \u2013 Agent card publishing interval (seconds)."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"--inter-agent-communication-allow-list TEXT"})," \u2013 Inter-agent communication allow list (comma-separated, use * for all)."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"--inter-agent-communication-deny-list TEXT"})," \u2013 Inter-agent communication deny list (comma-separated)."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"--inter-agent-communication-timeout INTEGER"})," \u2013 Inter-agent communication timeout (seconds)."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"--add-webui-gateway"})," \u2013 Add a default Web UI gateway configuration."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"--webui-session-secret-key TEXT"})," \u2013 Session secret key for Web UI."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"--webui-fastapi-host TEXT"})," \u2013 Host for Web UI FastAPI server."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"--webui-fastapi-port INTEGER"})," \u2013 Port for Web UI FastAPI server."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"--webui-enable-embed-resolution"})," \u2013 Enable embed resolution for Web UI."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"--webui-frontend-welcome-message TEXT"})," \u2013 Frontend welcome message for Web UI."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"--webui-frontend-bot-name TEXT"})," \u2013 Frontend bot name for Web UI."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"--webui-frontend-logo-url TEXT"})," \u2013 URL to a custom logo image for the Web UI interface. Supports PNG, SVG, JPG formats, as well as data URIs for embedded images."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"--webui-frontend-collect-feedback"})," \u2013 Enable feedback collection in Web UI."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"-h, --help"})," \u2013 Displays the help message and exits."]}),"\n"]}),"\n",(0,l.jsxs)(n.h3,{id:"add---create-a-new-component",children:[(0,l.jsx)(n.code,{children:"add"})," - Create a New Component"]}),"\n",(0,l.jsxs)(n.p,{children:["To add a new component, such as an agent, gateway, or proxy, use the ",(0,l.jsx)(n.code,{children:"add"})," command with the appropriate options."]}),"\n",(0,l.jsx)(n.pre,{children:(0,l.jsx)(n.code,{className:"language-sh",children:"sam add [agent|gateway|proxy] [OPTIONS] NAME\n"})}),"\n",(0,l.jsxs)(n.h4,{id:"add-agent",children:["Add ",(0,l.jsx)(n.code,{children:"agent"})]}),"\n",(0,l.jsxs)(n.p,{children:["Use ",(0,l.jsx)(n.code,{children:"agent"})," to add an agent component."]}),"\n",(0,l.jsx)(n.pre,{children:(0,l.jsx)(n.code,{className:"language-sh",children:"sam add agent [OPTIONS] [NAME]\n"})}),"\n",(0,l.jsx)(n.h5,{id:"options-1",children:"Options:"}),"\n",(0,l.jsxs)(n.ul,{children:["\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"--gui"})," \u2013 Launch the browser-based configuration interface for agent setup. (Recommended way to configure agents)"]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"--skip"})," \u2013 Skip interactive prompts and use defaults (Agent Mesh CLI mode only)."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"--namespace TEXT"})," \u2013 namespace (for example, myorg/dev)."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"--supports-streaming BOOLEAN"})," \u2013 Enable streaming support."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"--model-type TEXT"})," \u2013 Model type for the agent. Options: planning, general, image_gen, report_gen, multimodal, gemini_pro."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"--instruction TEXT"})," \u2013 Custom instruction for the agent."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"--session-service-type TEXT"})," \u2013 Session service type. Options: memory, vertex_rag."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"--session-service-behavior TEXT"})," \u2013 Session service behavior. Options: PERSISTENT, RUN_BASED."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"--artifact-service-type TEXT"})," \u2013 Artifact service type. Options: memory, filesystem, gcs."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"--artifact-service-base-path TEXT"})," \u2013 Base path for filesystem artifact service."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"--artifact-service-scope TEXT"})," \u2013 Artifact service scope. Options: namespace, app, custom."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"--artifact-handling-mode TEXT"})," \u2013 Artifact handling mode. Options: ignore, embed, reference."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"--enable-embed-resolution BOOLEAN"})," \u2013 Enable embed resolution."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"--enable-artifact-content-instruction BOOLEAN"})," \u2013 Enable artifact content instruction."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"--enable-builtin-artifact-tools BOOLEAN"})," \u2013 Enable built-in artifact tools."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"--enable-builtin-data-tools BOOLEAN"})," \u2013 Enable built-in data tools."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"--agent-card-description TEXT"})," \u2013 Description for the agent card."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"--agent-card-default-input-modes-str TEXT"})," \u2013 Comma-separated default input modes for agent card."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"--agent-card-default-output-modes-str TEXT"})," \u2013 Comma-separated default output modes for agent card."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"--agent-card-publishing-interval INTEGER"})," \u2013 Agent card publishing interval in seconds."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"--agent-discovery-enabled BOOLEAN"})," \u2013 Enable agent discovery."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"--inter-agent-communication-allow-list-str TEXT"})," \u2013 Comma-separated allow list for inter-agent communication."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"--inter-agent-communication-deny-list-str TEXT"})," \u2013 Comma-separated deny list for inter-agent communication."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"--inter-agent-communication-timeout INTEGER"})," \u2013 Timeout in seconds for inter-agent communication."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"-h, --help"})," \u2013 Displays the help message and exits."]}),"\n"]}),"\n",(0,l.jsxs)(n.p,{children:["For more information, see ",(0,l.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/components/agents",children:"Agents"}),"."]}),"\n",(0,l.jsxs)(n.h4,{id:"add-gateway",children:["Add ",(0,l.jsx)(n.code,{children:"gateway"})]}),"\n",(0,l.jsxs)(n.p,{children:["Use ",(0,l.jsx)(n.code,{children:"gateway"})," to add a gateway component."]}),"\n",(0,l.jsx)(n.pre,{children:(0,l.jsx)(n.code,{className:"language-sh",children:"sam add gateway [OPTIONS] [NAME]\n"})}),"\n",(0,l.jsx)(n.h5,{id:"options-2",children:"Options:"}),"\n",(0,l.jsxs)(n.ul,{children:["\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"--gui"})," \u2013 Launch the browser-based configuration interface for gateway setup. (Recommended way to configure gateways)"]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"--skip"})," \u2013 Skip interactive prompts and use defaults (Agent Mesh CLI mode only)."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"--namespace TEXT"})," \u2013 namespace for the gateway (for example, myorg/dev)."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"--gateway-id TEXT"})," \u2013 Custom Gateway ID for the gateway."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"--artifact-service-type TEXT"})," \u2013 Artifact service type for the gateway. Options: memory, filesystem, gcs."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"--artifact-service-base-path TEXT"})," \u2013 Base path for filesystem artifact service (if type is 'filesystem')."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"--artifact-service-scope TEXT"})," \u2013 Artifact service scope (if not using default shared artifact service). Options: namespace, app, custom."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"--system-purpose TEXT"})," \u2013 System purpose for the gateway (can be multi-line)."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"--response-format TEXT"})," \u2013 Response format for the gateway (can be multi-line)."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"-h, --help"})," \u2013 Displays the help message and exits."]}),"\n"]}),"\n",(0,l.jsxs)(n.p,{children:["For more information, see ",(0,l.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/components/gateways",children:"Gateways"}),"."]}),"\n",(0,l.jsxs)(n.h4,{id:"add-proxy",children:["Add ",(0,l.jsx)(n.code,{children:"proxy"})]}),"\n",(0,l.jsxs)(n.p,{children:["Use ",(0,l.jsx)(n.code,{children:"proxy"})," to add an A2A proxy component that bridges external HTTP-based agents to the Solace Agent Mesh."]}),"\n",(0,l.jsx)(n.pre,{children:(0,l.jsx)(n.code,{className:"language-sh",children:"sam add proxy [OPTIONS] [NAME]\n"})}),"\n",(0,l.jsxs)(n.p,{children:["The proxy command creates a configuration file in ",(0,l.jsx)(n.code,{children:"configs/agents/"})," that you can customize to connect external agents to the mesh."]}),"\n",(0,l.jsx)(n.h5,{id:"options-3",children:"Options:"}),"\n",(0,l.jsxs)(n.ul,{children:["\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"--skip"})," \u2013 Skip interactive prompts and create the proxy with default template."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"-h, --help"})," \u2013 Displays the help message and exits."]}),"\n"]}),"\n",(0,l.jsx)(n.h5,{id:"example",children:"Example:"}),"\n",(0,l.jsx)(n.pre,{children:(0,l.jsx)(n.code,{className:"language-sh",children:"sam add proxy myProxy --skip\n"})}),"\n",(0,l.jsxs)(n.p,{children:["This creates ",(0,l.jsx)(n.code,{children:"configs/agents/my_proxy_proxy.yaml"})," with the default proxy configuration template."]}),"\n",(0,l.jsxs)(n.h3,{id:"run---run-the-agent-mesh-application",children:[(0,l.jsx)(n.code,{children:"run"})," - Run the Agent Mesh Application"]}),"\n",(0,l.jsxs)(n.p,{children:["To run the Agent Mesh application, use the ",(0,l.jsx)(n.code,{children:"run"})," command."]}),"\n",(0,l.jsx)(n.pre,{children:(0,l.jsx)(n.code,{className:"language-sh",children:"sam run [OPTIONS] [FILES]...\n"})}),"\n",(0,l.jsxs)(n.admonition,{title:"Environment variables",type:"info",children:[(0,l.jsxs)(n.p,{children:["The ",(0,l.jsx)(n.code,{children:"sam run"})," command automatically loads environment variables from your configuration file (typically a ",(0,l.jsx)(n.code,{children:".env"})," file at the project root) by default."]}),(0,l.jsxs)(n.p,{children:["If you want to use your system's environment variables instead, you can add the ",(0,l.jsx)(n.code,{children:"-u"})," or ",(0,l.jsx)(n.code,{children:"--system-env"})," option."]})]}),"\n",(0,l.jsxs)(n.p,{children:["While running the ",(0,l.jsx)(n.code,{children:"run"})," command, you can also skip specific files by providing the ",(0,l.jsx)(n.code,{children:"-s"})," or ",(0,l.jsx)(n.code,{children:"--skip"})," option."]}),"\n",(0,l.jsxs)(n.p,{children:["You can provide paths to specific YAML configuration files or directories. When you provide a directory, ",(0,l.jsx)(n.code,{children:"run"})," will recursively search for and load all ",(0,l.jsx)(n.code,{children:".yaml"})," and ",(0,l.jsx)(n.code,{children:".yml"})," files within that directory. This allows you to organize your configurations and run them together easily."]}),"\n",(0,l.jsx)(n.p,{children:"For example, to run specific files:"}),"\n",(0,l.jsx)(n.pre,{children:(0,l.jsx)(n.code,{className:"language-sh",children:"solace-agent-mesh run configs/agent1.yaml configs/gateway.yaml\n"})}),"\n",(0,l.jsxs)(n.p,{children:["To run all YAML files within the ",(0,l.jsx)(n.code,{children:"configs"})," directory:"]}),"\n",(0,l.jsx)(n.pre,{children:(0,l.jsx)(n.code,{className:"language-sh",children:"solace-agent-mesh run configs/\n"})}),"\n",(0,l.jsx)(n.h5,{id:"options-4",children:"Options:"}),"\n",(0,l.jsxs)(n.ul,{children:["\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"-u, --system-env"})," \u2013 Use system environment variables only; do not load .env file."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"-s, --skip TEXT"})," \u2013 File name(s) to exclude from the run (for example, -s my_agent.yaml)."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"-h, --help"})," \u2013 Displays the help message and exits."]}),"\n"]}),"\n",(0,l.jsxs)(n.h3,{id:"docs---serve-the-documentation-locally",children:[(0,l.jsx)(n.code,{children:"docs"})," - Serve the documentation locally"]}),"\n",(0,l.jsx)(n.p,{children:"Serves the project documentation on a local web server."}),"\n",(0,l.jsx)(n.pre,{children:(0,l.jsx)(n.code,{className:"language-sh",children:"sam docs [OPTIONS]\n"})}),"\n",(0,l.jsxs)(n.p,{children:["This command starts a web server to host the documentation, which is useful for offline viewing or development. By default, it serves the documentation at ",(0,l.jsx)(n.code,{children:"http://localhost:8585/solace-agent-mesh/"})," and automatically opens your web browser to the getting started page."]}),"\n",(0,l.jsx)(n.p,{children:"If a requested page is not found, it will redirect to the main documentation page."}),"\n",(0,l.jsx)(n.h5,{id:"options-5",children:"Options:"}),"\n",(0,l.jsxs)(n.ul,{children:["\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"-p, --port INTEGER"})," \u2013 Port to run the web server on. (default: 8585)"]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"-h, --help"})," \u2013 Displays the help message and exits."]}),"\n"]}),"\n",(0,l.jsxs)(n.h3,{id:"tools---manage-and-explore-built-in-tools",children:[(0,l.jsx)(n.code,{children:"tools"})," - Manage and Explore Built-in Tools"]}),"\n",(0,l.jsxs)(n.p,{children:["The ",(0,l.jsx)(n.code,{children:"tools"})," command allows you to explore and manage built-in tools available in Solace Agent Mesh."]}),"\n",(0,l.jsx)(n.pre,{children:(0,l.jsx)(n.code,{className:"language-sh",children:"sam tools [COMMAND] [OPTIONS]\n"})}),"\n",(0,l.jsxs)(n.h4,{id:"list---list-built-in-tools",children:[(0,l.jsx)(n.code,{children:"list"})," - List Built-in Tools"]}),"\n",(0,l.jsx)(n.p,{children:"Lists all built-in tools available in Solace Agent Mesh. By default, shows brief information with tool names and descriptions."}),"\n",(0,l.jsx)(n.pre,{children:(0,l.jsx)(n.code,{className:"language-sh",children:"sam tools list [OPTIONS]\n"})}),"\n",(0,l.jsx)(n.p,{children:"This command is useful for:"}),"\n",(0,l.jsxs)(n.ul,{children:["\n",(0,l.jsx)(n.li,{children:"Discovering what built-in tools are available for your agents"}),"\n",(0,l.jsx)(n.li,{children:"Understanding tool capabilities and required parameters"}),"\n",(0,l.jsx)(n.li,{children:"Filtering tools by category"}),"\n",(0,l.jsx)(n.li,{children:"Exporting tool information in JSON format"}),"\n"]}),"\n",(0,l.jsx)(n.h5,{id:"options-6",children:"Options:"}),"\n",(0,l.jsxs)(n.ul,{children:["\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"-c, --category TEXT"})," \u2013 Filter tools by category (e.g., 'artifact_management', 'data_analysis', 'web')."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"-d, --detailed"})," \u2013 Show detailed information including parameters and required scopes."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"--json"})," \u2013 Output in JSON format instead of pretty table."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"-h, --help"})," \u2013 Displays the help message."]}),"\n"]}),"\n",(0,l.jsxs)(n.p,{children:["For more information about built-in tools, see ",(0,l.jsx)(n.a,{href:"builtin-tools/",children:"Built-in Tools"})]}),"\n",(0,l.jsxs)(n.h3,{id:"plugin---manage-plugins",children:[(0,l.jsx)(n.code,{children:"plugin"})," - Manage Plugins"]}),"\n",(0,l.jsxs)(n.p,{children:["The ",(0,l.jsx)(n.code,{children:"plugin"})," command allows you to manage plugins for Agent Mesh application."]}),"\n",(0,l.jsx)(n.pre,{children:(0,l.jsx)(n.code,{className:"language-sh",children:"sam plugin [COMMAND] [OPTIONS]\n"})}),"\n",(0,l.jsxs)(n.p,{children:["For more information, see ",(0,l.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/components/plugins",children:"Plugins"}),"."]}),"\n",(0,l.jsxs)(n.h4,{id:"create---create-a-plugin",children:[(0,l.jsx)(n.code,{children:"create"})," - Create a Plugin"]}),"\n",(0,l.jsx)(n.p,{children:"Initializes and creates a new plugin with customizable options."}),"\n",(0,l.jsx)(n.pre,{children:(0,l.jsx)(n.code,{className:"language-sh",children:"sam plugin create [OPTIONS] NAME\n"})}),"\n",(0,l.jsx)(n.p,{children:"When this command is run with no options, it runs in interactive mode and prompts you to provide the necessary information to set up the plugin for Agent Mesh."}),"\n",(0,l.jsx)(n.p,{children:"You can skip some questions by providing the appropriate options for that step."}),"\n",(0,l.jsxs)(n.p,{children:["Optionally, you can skip all the questions by providing the ",(0,l.jsx)(n.code,{children:"--skip"})," option. This option uses the provided or default values for all the questions, which is useful for automated workflows."]}),"\n",(0,l.jsx)(n.h5,{id:"options-7",children:"Options:"}),"\n",(0,l.jsxs)(n.ul,{children:["\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"--type TEXT"})," \u2013 Plugin type. Options: agent, gateway, custom."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"--author-name TEXT"})," \u2013 Author's name."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"--author-email TEXT"})," \u2013 Author's email."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"--description TEXT"})," \u2013 Plugin description."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"--version TEXT"})," \u2013 Initial plugin version."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"--skip"})," \u2013 Skip interactive prompts and use defaults or provided flags."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"-h, --help"})," \u2013 Displays the help message and exits."]}),"\n"]}),"\n",(0,l.jsxs)(n.h4,{id:"build---build-the-plugin",children:[(0,l.jsx)(n.code,{children:"build"})," - Build the Plugin"]}),"\n",(0,l.jsx)(n.p,{children:"Compiles and prepares the plugin for use."}),"\n",(0,l.jsx)(n.pre,{children:(0,l.jsx)(n.code,{className:"language-sh",children:"sam plugin build [PLUGIN_PATH]\n"})}),"\n",(0,l.jsx)(n.p,{children:"Builds the Agent Mesh plugin in the specified directory (defaults to current directory)."}),"\n",(0,l.jsx)(n.h5,{id:"options-8",children:"Options:"}),"\n",(0,l.jsxs)(n.ul,{children:["\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"PLUGIN_PATH"})," \u2013 Path to the plugin directory (defaults to current directory)."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"-h, --help"})," \u2013 Displays the help message and exits."]}),"\n"]}),"\n",(0,l.jsxs)(n.h4,{id:"add---add-an-existing-plugin",children:[(0,l.jsx)(n.code,{children:"add"})," - Add an Existing Plugin"]}),"\n",(0,l.jsx)(n.p,{children:"Installs the plugins and creates a new component instance from a specified plugin source."}),"\n",(0,l.jsx)(n.pre,{children:(0,l.jsx)(n.code,{className:"language-sh",children:"sam plugin add [OPTIONS] COMPONENT_NAME\n"})}),"\n",(0,l.jsx)(n.h5,{id:"options-9",children:"Options:"}),"\n",(0,l.jsxs)(n.ul,{children:["\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"--plugin TEXT"})," \u2013 Plugin source: installed module name, local path, or Git URL. (Required)"]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"--install-command TEXT"})," \u2013 Command to use to install a python package. Must follow the format ",(0,l.jsx)(n.code,{children:"command {package} args"}),", by default ",(0,l.jsx)(n.code,{children:"pip3 install {package}"}),". Can also be set through the environment variable SAM_PLUGIN_INSTALL_COMMAND."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"-h, --help"})," \u2013 Displays the help message and exits."]}),"\n"]}),"\n",(0,l.jsxs)(n.h4,{id:"installs---installs-a-plugin",children:[(0,l.jsx)(n.code,{children:"installs"})," - Installs a Plugin"]}),"\n",(0,l.jsx)(n.p,{children:"Installs a plugin from a specified plugin source."}),"\n",(0,l.jsx)(n.pre,{children:(0,l.jsx)(n.code,{className:"language-sh",children:"sam plugin install [OPTIONS] PLUGIN_SOURCE\n"})}),"\n",(0,l.jsx)(n.p,{children:"PLUGIN_SOURCE can be:"}),"\n",(0,l.jsxs)(n.ul,{children:["\n",(0,l.jsx)(n.li,{children:"A local path to a directory (e.g., '/path/to/plugin')"}),"\n",(0,l.jsx)(n.li,{children:"A local path to a wheel file (e.g., '/path/to/plugin.whl')"}),"\n",(0,l.jsxs)(n.li,{children:["A Git URL (e.g., '",(0,l.jsx)(n.a,{href:"https://github.com/user/repo.git",children:"https://github.com/user/repo.git"}),"')"]}),"\n",(0,l.jsxs)(n.li,{children:["The name of the plugin from ",(0,l.jsx)(n.a,{href:"https://github.com/SolaceLabs/solace-agent-mesh-core-plugins",children:"https://github.com/SolaceLabs/solace-agent-mesh-core-plugins"})]}),"\n"]}),"\n",(0,l.jsx)(n.h5,{id:"options-10",children:"Options:"}),"\n",(0,l.jsxs)(n.ul,{children:["\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"--install-command TEXT"})," \u2013 Command to use to install a python package. Must follow the format ",(0,l.jsx)(n.code,{children:"command {package} args"}),", by default ",(0,l.jsx)(n.code,{children:"pip3 install {package}"}),". Can also be set through the environment variable SAM_PLUGIN_INSTALL_COMMAND."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"-h, --help"})," \u2013 Displays the help message and exits."]}),"\n"]}),"\n",(0,l.jsxs)(n.h4,{id:"catalog---launch-plugin-catalog",children:[(0,l.jsx)(n.code,{children:"catalog"})," - Launch Plugin Catalog"]}),"\n",(0,l.jsx)(n.p,{children:"Launch the Agent Mesh Plugin Catalog web interface."}),"\n",(0,l.jsx)(n.pre,{children:(0,l.jsx)(n.code,{className:"language-sh",children:"sam plugin catalog [OPTIONS]\n"})}),"\n",(0,l.jsx)(n.h5,{id:"options-11",children:"Options:"}),"\n",(0,l.jsxs)(n.ul,{children:["\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"--port INTEGER"})," \u2013 Port to run the plugin catalog web server on. (default: 5003)"]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"--install-command TEXT"})," \u2013 Command to use to install a python package. Must follow the format ",(0,l.jsx)(n.code,{children:"command {package} args"}),"."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"-h, --help"})," \u2013 Displays the help message and exits."]}),"\n"]})]})}function h(e={}){const{wrapper:n}={...(0,o.R)(),...e.components};return n?(0,l.jsx)(n,{...e,children:(0,l.jsx)(r,{...e})}):r(e)}},8453:(e,n,i)=>{i.d(n,{R:()=>t,x:()=>a});var s=i(6540);const l={},o=s.createContext(l);function t(e){const n=s.useContext(o);return s.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(l):e.components||l:t(e.components),s.createElement(o.Provider,{value:n},e.children)}}}]);

solace_agent_mesh/assets/docs/assets/js/41adc471.0e95b87c.js

@@ -0,0 +1 @@
+"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[80],{9538:(e,n,i)=>{i.r(n),i.d(n,{assets:()=>l,contentTitle:()=>a,default:()=>h,frontMatter:()=>o,metadata:()=>t,toc:()=>c});const t=JSON.parse('{"id":"documentation/components/prompts","title":"Prompt Library","description":"The Prompt Library is a powerful feature that enables you to create, manage, and reuse prompt templates across your AI conversations. Instead of retyping common instructions or workflows, you can save them as reusable templates with variable placeholders, making your interactions with AI agents more efficient and consistent.","source":"@site/docs/documentation/components/prompts.md","sourceDirName":"documentation/components","slug":"/documentation/components/prompts","permalink":"/solace-agent-mesh/docs/documentation/components/prompts","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/components/prompts.md","tags":[],"version":"current","sidebarPosition":290,"frontMatter":{"title":"Prompt Library","sidebar_position":290},"sidebar":"docSidebar","previous":{"title":"Research Tools","permalink":"/solace-agent-mesh/docs/documentation/components/builtin-tools/research-tools"},"next":{"title":"Speech Integration","permalink":"/solace-agent-mesh/docs/documentation/components/speech"}}');var s=i(4848),r=i(8453);const o={title:"Prompt Library",sidebar_position:290},a="Prompt Library",l={},c=[{value:"Key Features",id:"key-features",level:2},{value:"Understanding Prompts",id:"understanding-prompts",level:2},{value:"Prompt Groups",id:"prompt-groups",level:3},{value:"Prompt Versions",id:"prompt-versions",level:3},{value:"Variables",id:"variables",level:3},{value:"Creating and Managing Prompts",id:"creating-and-managing-prompts",level:2},{value:"Creating Your First Prompt",id:"creating-your-first-prompt",level:3},{value:"Using the AI Prompt Builder",id:"using-the-ai-prompt-builder",level:4},{value:"Updating Prompts",id:"updating-prompts",level:3},{value:"Using Prompts in Chat",id:"using-prompts-in-chat",level:2},{value:"Quick Access with <code>/</code> Command",id:"quick-access-with--command",level:3},{value:"Using Chat Shortcuts",id:"using-chat-shortcuts",level:3},{value:"Configuration",id:"configuration",level:2},{value:"Enabling the Prompt Library",id:"enabling-the-prompt-library",level:3},{value:"Feature Flag Control",id:"feature-flag-control",level:3},{value:"Database Migration",id:"database-migration",level:3},{value:"Best Practices",id:"best-practices",level:2},{value:"Designing Effective Prompts",id:"designing-effective-prompts",level:3},{value:"Troubleshooting",id:"troubleshooting",level:2},{value:"Prompts Not Visible",id:"prompts-not-visible",level:3}];function d(e){const n={admonition:"admonition",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,r.R)(),...e.components};return(0,s.jsxs)(s.Fragment,{children:[(0,s.jsx)(n.header,{children:(0,s.jsx)(n.h1,{id:"prompt-library",children:"Prompt Library"})}),"\n",(0,s.jsx)(n.p,{children:"The Prompt Library is a powerful feature that enables you to create, manage, and reuse prompt templates across your AI conversations. Instead of retyping common instructions or workflows, you can save them as reusable templates with variable placeholders, making your interactions with AI agents more efficient and consistent."}),"\n",(0,s.jsx)(n.admonition,{title:"In one sentence",type:"tip",children:(0,s.jsx)(n.p,{children:"The Prompt Library lets you create reusable prompt templates with variables, accessible via quick commands in chat, enabling faster and more consistent AI interactions."})}),"\n",(0,s.jsx)(n.h2,{id:"key-features",children:"Key Features"}),"\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:"Quick Access"}),": Type ",(0,s.jsx)(n.code,{children:"/"})," in any chat to instantly search and insert prompts using keyboard shortcuts."]}),"\n"]}),"\n",(0,s.jsxs)(n.li,{children:["\n",(0,s.jsxs)(n.p,{children:[(0,s.jsx)(n.strong,{children:"Variable Substitution"}),": Use ",(0,s.jsx)(n.code,{children:"{{Variable Name}}"})," placeholders in your prompts to create flexible templates that adapt to different contexts."]}),"\n"]}),"\n",(0,s.jsxs)(n.li,{children:["\n",(0,s.jsxs)(n.p,{children:[(0,s.jsx)(n.strong,{children:"Version Management"}),': Track changes to your prompts over time with automatic versioning, and designate specific versions as "Active" for active use.']}),"\n"]}),"\n",(0,s.jsxs)(n.li,{children:["\n",(0,s.jsxs)(n.p,{children:[(0,s.jsx)(n.strong,{children:"Organization"}),": Tag prompts by topic (Development, Analysis, Documentation, etc.) and assign custom chat shortcuts for even faster access."]}),"\n"]}),"\n",(0,s.jsxs)(n.li,{children:["\n",(0,s.jsxs)(n.p,{children:[(0,s.jsx)(n.strong,{children:"AI-Assisted Creation"}),": Use the built-in prompt builder assistant to help you design effective templates through natural conversation."]}),"\n"]}),"\n"]}),"\n",(0,s.jsx)(n.h2,{id:"understanding-prompts",children:"Understanding Prompts"}),"\n",(0,s.jsx)(n.h3,{id:"prompt-groups",children:"Prompt Groups"}),"\n",(0,s.jsx)(n.p,{children:"A prompt group is a container that holds multiple versions of a prompt template. Each group includes:"}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Name"}),': A descriptive title for the prompt (e.g., "Code Review Template")']}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Description"}),": Optional details about the prompt's purpose"]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Tag"}),': Organizational label (e.g., "Development", "Analysis", "Documentation")']}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Shortcut"}),": Optional shortcut for quick access (e.g., typing ",(0,s.jsx)(n.code,{children:"/review"})," instantly finds your code review prompt)"]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Active Version"}),": The currently active version of the prompt that appears when you use the shortcut"]}),"\n"]}),"\n",(0,s.jsx)(n.h3,{id:"prompt-versions",children:"Prompt Versions"}),"\n",(0,s.jsx)(n.p,{children:"Each time you modify a prompt, a new version is created automatically. This allows you to:"}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsx)(n.li,{children:"Track the evolution of your prompts over time"}),"\n",(0,s.jsx)(n.li,{children:"Revert to previous versions if needed"}),"\n",(0,s.jsx)(n.li,{children:"Compare different approaches"}),"\n",(0,s.jsx)(n.li,{children:'Designate which version is "active"'}),"\n"]}),"\n",(0,s.jsx)(n.h3,{id:"variables",children:"Variables"}),"\n",(0,s.jsxs)(n.p,{children:["Variables are placeholders in your prompts that you fill in each time you use them. They use the format ",(0,s.jsx)(n.code,{children:"{{Variable Name}}"})," with Title Case and spaces. For example:"]}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{children:"Review the {{Module Name}} module located at {{File Path}}.\n\nFocus on:\n- Security vulnerabilities\n- Error handling\n- {{Specific Concerns}}\n"})}),"\n",(0,s.jsx)(n.p,{children:"When you select this prompt, you'll be prompted to fill in the Module Name, File Path, and Specific Concerns before the prompt is inserted into your chat."}),"\n",(0,s.jsx)(n.h2,{id:"creating-and-managing-prompts",children:"Creating and Managing Prompts"}),"\n",(0,s.jsx)(n.h3,{id:"creating-your-first-prompt",children:"Creating Your First Prompt"}),"\n",(0,s.jsx)(n.p,{children:"You can create prompts in two ways: using the AI-assisted prompt builder, or manually by specifying the required parameters."}),"\n",(0,s.jsx)(n.h4,{id:"using-the-ai-prompt-builder",children:"Using the AI Prompt Builder"}),"\n",(0,s.jsx)(n.p,{children:"The prompt builder assistant helps you create effective templates through conversation:"}),"\n",(0,s.jsxs)(n.ol,{children:["\n",(0,s.jsx)(n.li,{children:"Navigate to the Prompts section in the UI"}),"\n",(0,s.jsx)(n.li,{children:'Click "Build with AI"'}),"\n",(0,s.jsx)(n.li,{children:"Describe what you want the template to do"}),"\n",(0,s.jsx)(n.li,{children:"The AI will ask clarifying questions about what information changes each time"}),"\n",(0,s.jsx)(n.li,{children:"Review the generated template and make adjustments"}),"\n",(0,s.jsx)(n.li,{children:"Save when ready"}),"\n"]}),"\n",(0,s.jsx)(n.p,{children:"The assistant understands that only data that changes (like file paths, names, dates) should be variables, while instructions and steps should remain as fixed text."}),"\n",(0,s.jsx)(n.h3,{id:"updating-prompts",children:"Updating Prompts"}),"\n",(0,s.jsx)(n.p,{children:"When you update a prompt's text, a new version is automatically created. This preserves your history while allowing you to improve your templates over time."}),"\n",(0,s.jsx)(n.h2,{id:"using-prompts-in-chat",children:"Using Prompts in Chat"}),"\n",(0,s.jsxs)(n.h3,{id:"quick-access-with--command",children:["Quick Access with ",(0,s.jsx)(n.code,{children:"/"})," Command"]}),"\n",(0,s.jsxs)(n.p,{children:["The fastest way to use prompts is through the ",(0,s.jsx)(n.code,{children:"/"})," command in chat:"]}),"\n",(0,s.jsxs)(n.ol,{children:["\n",(0,s.jsxs)(n.li,{children:["Type ",(0,s.jsx)(n.code,{children:"/"})," in the chat input field"]}),"\n",(0,s.jsx)(n.li,{children:"A search popover appears showing all your prompts"}),"\n",(0,s.jsx)(n.li,{children:"Start typing to filter by name or chat shortcut"}),"\n",(0,s.jsx)(n.li,{children:"Use arrow keys to navigate the list"}),"\n",(0,s.jsx)(n.li,{children:"Press Enter to select a prompt"}),"\n",(0,s.jsx)(n.li,{children:"If the prompt has variables, a dialog appears for you to fill them in"}),"\n",(0,s.jsx)(n.li,{children:"The completed prompt is inserted into your chat input"}),"\n"]}),"\n",(0,s.jsx)(n.h3,{id:"using-chat-shortcuts",children:"Using Chat Shortcuts"}),"\n",(0,s.jsx)(n.p,{children:'If you\'ve assigned a shortcut to a prompt (e.g., "review"), you can type it directly:'}),"\n",(0,s.jsxs)(n.ol,{children:["\n",(0,s.jsxs)(n.li,{children:["Type ",(0,s.jsx)(n.code,{children:"/review"})," in chat"]}),"\n",(0,s.jsx)(n.li,{children:"The prompt appears immediately"}),"\n",(0,s.jsx)(n.li,{children:"Fill in any variables"}),"\n",(0,s.jsx)(n.li,{children:"The prompt is inserted"}),"\n"]}),"\n",(0,s.jsx)(n.h2,{id:"configuration",children:"Configuration"}),"\n",(0,s.jsx)(n.h3,{id:"enabling-the-prompt-library",children:"Enabling the Prompt Library"}),"\n",(0,s.jsxs)(n.p,{children:["The Prompt Library requires SQL database persistence to function. Configure persistence in your ",(0,s.jsx)(n.code,{children:"shared_config.yaml"}),":"]}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-yaml",children:'session_service:\n  type: sql\n  database_url: "sqlite:///./data/sessions.db"\n'})}),"\n",(0,s.jsx)(n.p,{children:"The Prompt Library is enabled by default when persistence is configured. To explicitly control it:"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-yaml",children:"# Enable or disable the prompt library\nprompt_library:\n  enabled: true\n"})}),"\n",(0,s.jsx)(n.h3,{id:"feature-flag-control",children:"Feature Flag Control"}),"\n",(0,s.jsx)(n.p,{children:"You can also control the Prompt Library via feature flags:"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-yaml",children:"frontend_feature_enablement:\n  promptLibrary: true  # Enable prompt library\n  projects: true\n  taskLogging: true\n"})}),"\n",(0,s.jsxs)(n.admonition,{title:"Configuration Priority",type:"note",children:[(0,s.jsx)(n.p,{children:"The feature flag resolution follows this priority:"}),(0,s.jsxs)(n.ol,{children:["\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Persistence Check"}),": If persistence is disabled, prompts are disabled (non-negotiable)"]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Explicit Config"}),": ",(0,s.jsx)(n.code,{children:"prompt_library.enabled"})," setting"]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Feature Flag"}),": ",(0,s.jsx)(n.code,{children:"frontend_feature_enablement.promptLibrary"})," setting"]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Default"}),": Enabled (if persistence is enabled and no explicit disable)"]}),"\n"]})]}),"\n",(0,s.jsx)(n.h3,{id:"database-migration",children:"Database Migration"}),"\n",(0,s.jsx)(n.p,{children:"When you first enable the Prompt Library, the database tables are created automatically through Alembic migrations. The migration creates:"}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.code,{children:"prompt_groups"})," table: Stores prompt metadata and organization"]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.code,{children:"prompts"})," table: Stores individual prompt versions"]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.code,{children:"prompt_group_users"})," table: Manages sharing and permissions"]}),"\n"]}),"\n",(0,s.jsx)(n.p,{children:"No manual intervention is required - the tables are created when you start the application with persistence enabled."}),"\n",(0,s.jsx)(n.h2,{id:"best-practices",children:"Best Practices"}),"\n",(0,s.jsx)(n.h3,{id:"designing-effective-prompts",children:"Designing Effective Prompts"}),"\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:"Use Clear Variable Names"}),": Choose descriptive names like ",(0,s.jsx)(n.code,{children:"{{File Path}}"})," instead of ",(0,s.jsx)(n.code,{children:"{{x}}"})," or ",(0,s.jsx)(n.code,{children:"{{input}}"})]}),"\n"]}),"\n",(0,s.jsxs)(n.li,{children:["\n",(0,s.jsxs)(n.p,{children:[(0,s.jsx)(n.strong,{children:"Keep Instructions Fixed"}),": Only make data that changes into variables. Instructions, steps, and requirements should be part of the template text."]}),"\n"]}),"\n",(0,s.jsxs)(n.li,{children:["\n",(0,s.jsxs)(n.p,{children:[(0,s.jsx)(n.strong,{children:"Provide Context"}),": Include enough context in the prompt so the AI understands what you're asking for."]}),"\n"]}),"\n"]}),"\n",(0,s.jsx)(n.h2,{id:"troubleshooting",children:"Troubleshooting"}),"\n",(0,s.jsx)(n.h3,{id:"prompts-not-visible",children:"Prompts Not Visible"}),"\n",(0,s.jsx)(n.p,{children:"If prompts are not showing up in the UI:"}),"\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:"Check Persistence Configuration"}),":"]}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-yaml",children:"session_service:\n  type: sql  # Must be 'sql', not 'memory'\n"})}),"\n"]}),"\n",(0,s.jsxs)(n.li,{children:["\n",(0,s.jsxs)(n.p,{children:[(0,s.jsx)(n.strong,{children:"Check if Prompts are Explicitly Disabled"}),":"]}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-yaml",children:"prompt_library:\n  enabled: false  # Remove this line or set to true\n"})}),"\n"]}),"\n",(0,s.jsxs)(n.li,{children:["\n",(0,s.jsxs)(n.p,{children:[(0,s.jsx)(n.strong,{children:"Check Feature Flags"}),":"]}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-yaml",children:"frontend_feature_enablement:\n  promptLibrary: true  # Should be true or omitted\n"})}),"\n"]}),"\n"]})]})}function h(e={}){const{wrapper:n}={...(0,r.R)(),...e.components};return n?(0,s.jsx)(n,{...e,children:(0,s.jsx)(d,{...e})}):d(e)}},8453:(e,n,i)=>{i.d(n,{R:()=>o,x:()=>a});var t=i(6540);const s={},r=t.createContext(s);function o(e){const n=t.useContext(r);return t.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:o(e.components),t.createElement(r.Provider,{value:n},e.children)}}}]);

solace_agent_mesh/assets/docs/assets/js/4667dc50.bf2ad456.js

@@ -0,0 +1 @@
+"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[868],{1740:(e,n,t)=>{t.r(n),t.d(n,{assets:()=>l,contentTitle:()=>a,default:()=>d,frontMatter:()=>r,metadata:()=>s,toc:()=>c});const s=JSON.parse('{"id":"documentation/deploying/kubernetes/kubernetes","title":"Kubernetes","description":"You can deploy Agent Mesh to Kubernetes using Helm charts, which handle the complexity of creating and configuring Kubernetes resources such as deployments, services, persistent volumes, and configuration management.","source":"@site/docs/documentation/deploying/kubernetes/kubernetes.md","sourceDirName":"documentation/deploying/kubernetes","slug":"/documentation/deploying/kubernetes/","permalink":"/solace-agent-mesh/docs/documentation/deploying/kubernetes/","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/deploying/kubernetes/kubernetes.md","tags":[],"version":"current","sidebarPosition":11,"frontMatter":{"title":"Kubernetes","sidebar_position":11},"sidebar":"docSidebar","previous":{"title":"Choosing Deployment Options","permalink":"/solace-agent-mesh/docs/documentation/deploying/deployment-options"},"next":{"title":"Kubernetes Deployment Guide","permalink":"/solace-agent-mesh/docs/documentation/deploying/kubernetes/kubernetes-deployment-guide"}}');var o=t(4848),i=t(8453);const r={title:"Kubernetes",sidebar_position:11},a="Deploying Agent Mesh to Kubernetes",l={},c=[{value:"Prerequisites",id:"prerequisites",level:2},{value:"Understanding Kubernetes Deployment",id:"understanding-kubernetes-deployment",level:2},{value:"Using the Helm Quickstart",id:"using-the-helm-quickstart",level:2},{value:"Kubernetes Deployment Architecture",id:"kubernetes-deployment-architecture",level:2},{value:"Configuring for Kubernetes",id:"configuring-for-kubernetes",level:2},{value:"Queue Configuration",id:"queue-configuration",level:3},{value:"Secrets Management",id:"secrets-management",level:3},{value:"Storage",id:"storage",level:3},{value:"Resource Limits",id:"resource-limits",level:3}];function u(e){const n={a:"a",code:"code",h1:"h1",h2:"h2",h3:"h3",header:"header",li:"li",p:"p",pre:"pre",ul:"ul",...(0,i.R)(),...e.components};return(0,o.jsxs)(o.Fragment,{children:[(0,o.jsx)(n.header,{children:(0,o.jsx)(n.h1,{id:"deploying-agent-mesh-to-kubernetes",children:"Deploying Agent Mesh to Kubernetes"})}),"\n",(0,o.jsx)(n.p,{children:"You can deploy Agent Mesh to Kubernetes using Helm charts, which handle the complexity of creating and configuring Kubernetes resources such as deployments, services, persistent volumes, and configuration management."}),"\n",(0,o.jsx)(n.h2,{id:"prerequisites",children:"Prerequisites"}),"\n",(0,o.jsx)(n.p,{children:"To deploy Agent Mesh to Kubernetes, you need:"}),"\n",(0,o.jsxs)(n.ul,{children:["\n",(0,o.jsx)(n.li,{children:"A running Kubernetes cluster (version 1.20 or later)"}),"\n",(0,o.jsxs)(n.li,{children:["The ",(0,o.jsx)(n.code,{children:"kubectl"})," command-line tool configured to access your cluster"]}),"\n",(0,o.jsx)(n.li,{children:"Helm installed on your system (version 3.0 or later)"}),"\n",(0,o.jsx)(n.li,{children:"Container registry credentials (if you use private registries)"}),"\n",(0,o.jsx)(n.li,{children:"Solace broker credentials or Solace Cloud connection details"}),"\n"]}),"\n",(0,o.jsx)(n.h2,{id:"understanding-kubernetes-deployment",children:"Understanding Kubernetes Deployment"}),"\n",(0,o.jsx)(n.p,{children:"The deployment process involves adding the Helm chart repository, customizing values for your environment, and deploying Agent Mesh to your cluster. The Helm charts simplify this process compared to manually managing individual YAML manifests."}),"\n",(0,o.jsx)(n.h2,{id:"using-the-helm-quickstart",children:"Using the Helm Quickstart"}),"\n",(0,o.jsx)(n.p,{children:"The Solace Agent Mesh Helm quickstart includes pre-configured Helm values, deployment examples, and detailed documentation for common deployment scenarios."}),"\n",(0,o.jsxs)(n.p,{children:["For the quickstart repository and installation files, see ",(0,o.jsx)(n.a,{href:"https://github.com/SolaceProducts/solace-agent-mesh-helm-quickstart",children:"solace-agent-mesh-helm-quickstart"}),"."]}),"\n",(0,o.jsxs)(n.p,{children:["For step-by-step deployment instructions, see the ",(0,o.jsx)(n.a,{href:"https://solaceproducts.github.io/solace-agent-mesh-helm-quickstart/docs-site/",children:"Helm Deployment Guide"}),"."]}),"\n",(0,o.jsx)(n.h2,{id:"kubernetes-deployment-architecture",children:"Kubernetes Deployment Architecture"}),"\n",(0,o.jsx)(n.p,{children:"You can deploy Agent Mesh as a single monolithic deployment or as multiple specialized deployments that scale independently. The Helm charts support both patterns based on your scale requirements and operational preferences."}),"\n",(0,o.jsx)(n.p,{children:"When you deploy multiple components as separate deployments, each component runs independently and communicates through the Solace event broker. This approach provides better fault isolation and allows you to scale specific components based on demand. All components must connect to the same Solace broker and use consistent storage configurations to maintain system coherence."}),"\n",(0,o.jsx)(n.h2,{id:"configuring-for-kubernetes",children:"Configuring for Kubernetes"}),"\n",(0,o.jsx)(n.p,{children:"Several configuration considerations apply specifically to Kubernetes deployments."}),"\n",(0,o.jsx)(n.h3,{id:"queue-configuration",children:"Queue Configuration"}),"\n",(0,o.jsx)(n.p,{children:"For Kubernetes environments with container restarts, you should configure Agent Mesh to use durable queues instead of temporary queues. Set the environment variable:"}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-bash",children:"USE_TEMPORARY_QUEUES=false\n"})}),"\n",(0,o.jsxs)(n.p,{children:["This configuration ensures that messages persist even when pods restart and allows multiple instances to connect to the same queue. For detailed queue configuration guidance, including Queue Template setup in Solace Cloud, see ",(0,o.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/deploying/deployment-options#setting-up-queue-templates",children:"Choosing Deployment Options"}),"."]}),"\n",(0,o.jsx)(n.h3,{id:"secrets-management",children:"Secrets Management"}),"\n",(0,o.jsx)(n.p,{children:"You should use Kubernetes Secrets to store sensitive information such as API keys, broker credentials, and authentication tokens. Never embed these values in container images or configuration files."}),"\n",(0,o.jsx)(n.h3,{id:"storage",children:"Storage"}),"\n",(0,o.jsx)(n.p,{children:"If you run multiple pod replicas, ensure all instances access the same persistent storage with identical configurations. Inconsistent storage across instances can cause data synchronization issues."}),"\n",(0,o.jsx)(n.h3,{id:"resource-limits",children:"Resource Limits"}),"\n",(0,o.jsx)(n.p,{children:"You should define resource requests and limits for your containers to ensure stable operation and enable effective autoscaling. The Helm quickstart includes recommended resource configurations."})]})}function d(e={}){const{wrapper:n}={...(0,i.R)(),...e.components};return n?(0,o.jsx)(n,{...e,children:(0,o.jsx)(u,{...e})}):u(e)}},8453:(e,n,t)=>{t.d(n,{R:()=>r,x:()=>a});var s=t(6540);const o={},i=s.createContext(o);function r(e){const n=s.useContext(i);return s.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(o):e.components||o:r(e.components),s.createElement(i.Provider,{value:n},e.children)}}}]);

solace_agent_mesh/assets/docs/assets/js/49eed117.493d6f99.js

@@ -0,0 +1 @@
+"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[5953],{182:(e,n,s)=>{s.r(n),s.d(n,{assets:()=>c,contentTitle:()=>l,default:()=>h,frontMatter:()=>o,metadata:()=>r,toc:()=>d});const r=JSON.parse('{"id":"documentation/components/builtin-tools/research-tools","title":"Research Tools","description":"Agent Mesh provides research tools that enable agents to search the web and conduct comprehensive research on complex topics. These tools give agents access to current information beyond their training data and the ability to synthesize findings from multiple sources into detailed reports.","source":"@site/docs/documentation/components/builtin-tools/research-tools.md","sourceDirName":"documentation/components/builtin-tools","slug":"/documentation/components/builtin-tools/research-tools","permalink":"/solace-agent-mesh/docs/documentation/components/builtin-tools/research-tools","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/components/builtin-tools/research-tools.md","tags":[],"version":"current","sidebarPosition":50,"frontMatter":{"title":"Research Tools","sidebar_position":50},"sidebar":"docSidebar","previous":{"title":"Dynamic Embeds","permalink":"/solace-agent-mesh/docs/documentation/components/builtin-tools/embeds"},"next":{"title":"Prompt Library","permalink":"/solace-agent-mesh/docs/documentation/components/prompts"}}');var i=s(4848),t=s(8453);const o={title:"Research Tools",sidebar_position:50},l="Research 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:"Environment Variables",id:"environment-variables",level:3},{value:"Enabling the Tools",id:"enabling-the-tools",level:3},{value:"Tool Configuration",id:"tool-configuration",level:3},{value:"Web Search Tool",id:"web-search-tool",level:2},{value:"Parameters",id:"parameters",level:3},{value:"Usage Examples",id:"usage-examples",level:3},{value:"Response Format",id:"response-format",level:3},{value:"Deep Research Tool",id:"deep-research-tool",level:2},{value:"How Deep Research Works",id:"how-deep-research-works",level:3},{value:"Parameters",id:"parameters-1",level:3},{value:"Configuration Priority",id:"configuration-priority",level:3},{value:"Research Types",id:"research-types",level:3},{value:"Advanced Configuration",id:"advanced-configuration",level:3},{value:"Usage Examples",id:"usage-examples-1",level:3},{value:"Output",id:"output",level:3},{value:"Progress Updates",id:"progress-updates",level:3},{value:"Required Scopes",id:"required-scopes",level:2},{value:"Alternative Search Providers",id:"alternative-search-providers",level:2},{value:"Technical Considerations",id:"technical-considerations",level:2},{value:"Rate Limits",id:"rate-limits",level:3},{value:"Content Fetching",id:"content-fetching",level:3},{value:"Report Quality",id:"report-quality",level:3}];function a(e){const n={admonition:"admonition",code:"code",h1:"h1",h2:"h2",h3:"h3",header:"header",li:"li",ol:"ol",p:"p",pre:"pre",table:"table",tbody:"tbody",td:"td",th:"th",thead:"thead",tr:"tr",ul:"ul",...(0,t.R)(),...e.components};return(0,i.jsxs)(i.Fragment,{children:[(0,i.jsx)(n.header,{children:(0,i.jsx)(n.h1,{id:"research-tools",children:"Research Tools"})}),"\n",(0,i.jsx)(n.p,{children:"Agent Mesh provides research tools that enable agents to search the web and conduct comprehensive research on complex topics. These tools give agents access to current information beyond their training data and the ability to synthesize findings from multiple sources into detailed reports."}),"\n",(0,i.jsx)(n.h2,{id:"overview",children:"Overview"}),"\n",(0,i.jsx)(n.p,{children:"The research tools consist of two categories:"}),"\n",(0,i.jsx)(n.p,{children:"The web search tools provide direct access to web search engines, allowing agents to retrieve current information, news, and facts. The deep research tool builds on web search to conduct iterative research with LLM-powered reflection and report generation."}),"\n",(0,i.jsx)(n.h2,{id:"setup-and-configuration",children:"Setup and Configuration"}),"\n",(0,i.jsx)(n.h3,{id:"prerequisites",children:"Prerequisites"}),"\n",(0,i.jsx)(n.p,{children:"To use the web search functionality, you need a Google Custom Search API key and a Custom Search Engine ID. You can obtain these from the Google Cloud Console."}),"\n",(0,i.jsx)(n.h3,{id:"environment-variables",children:"Environment Variables"}),"\n",(0,i.jsx)(n.p,{children:"Set the following environment variables:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:'export GOOGLE_API_KEY="your_google_api_key_here"\nexport GOOGLE_CSE_ID="your_custom_search_engine_id_here"\n'})}),"\n",(0,i.jsx)(n.h3,{id:"enabling-the-tools",children:"Enabling the Tools"}),"\n",(0,i.jsxs)(n.p,{children:["Enable the research tools in your agent's ",(0,i.jsx)(n.code,{children:"app_config.yml"}),":"]}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-yaml",children:'tools:\n  - tool_type: builtin-group\n    group_name: "web_search"\n\n  - tool_type: builtin-group\n    group_name: "research"\n'})}),"\n",(0,i.jsx)(n.p,{children:"You can also enable individual tools:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-yaml",children:'tools:\n  - tool_type: builtin\n    tool_name: "web_search_google"\n  - tool_type: builtin\n    tool_name: "deep_research"\n'})}),"\n",(0,i.jsx)(n.h3,{id:"tool-configuration",children:"Tool Configuration"}),"\n",(0,i.jsxs)(n.p,{children:["Both tools accept configuration through the ",(0,i.jsx)(n.code,{children:"tool_config"})," block:"]}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-yaml",children:'- tool_type: builtin\n  tool_name: "web_search_google"\n  tool_config:\n    google_search_api_key: ${GOOGLE_API_KEY}\n    google_cse_id: ${GOOGLE_CSE_ID}\n\n- tool_type: builtin\n  tool_name: "deep_research"\n  tool_config:\n    google_search_api_key: ${GOOGLE_API_KEY}\n    google_cse_id: ${GOOGLE_CSE_ID}\n    max_iterations: 5\n    max_runtime_seconds: 300\n    sources:\n      - web\n'})}),"\n",(0,i.jsx)(n.h2,{id:"web-search-tool",children:"Web Search Tool"}),"\n",(0,i.jsxs)(n.p,{children:["The ",(0,i.jsx)(n.code,{children:"web_search_google"})," tool searches the web using Google Custom Search API and returns results with source citations."]}),"\n",(0,i.jsx)(n.h3,{id:"parameters",children:"Parameters"}),"\n",(0,i.jsxs)(n.table,{children:[(0,i.jsx)(n.thead,{children:(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.th,{children:"Parameter"}),(0,i.jsx)(n.th,{children:"Type"}),(0,i.jsx)(n.th,{children:"Description"})]})}),(0,i.jsxs)(n.tbody,{children:[(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.td,{children:(0,i.jsx)(n.code,{children:"query"})}),(0,i.jsx)(n.td,{children:"string"}),(0,i.jsx)(n.td,{children:"The search query (required)"})]}),(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.td,{children:(0,i.jsx)(n.code,{children:"max_results"})}),(0,i.jsx)(n.td,{children:"integer"}),(0,i.jsx)(n.td,{children:"Maximum number of results to return (1-10, default: 5)"})]}),(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.td,{children:(0,i.jsx)(n.code,{children:"search_type"})}),(0,i.jsx)(n.td,{children:"string"}),(0,i.jsxs)(n.td,{children:["Set to ",(0,i.jsx)(n.code,{children:'"image"'})," for image search"]})]}),(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.td,{children:(0,i.jsx)(n.code,{children:"date_restrict"})}),(0,i.jsx)(n.td,{children:"string"}),(0,i.jsxs)(n.td,{children:["Restrict results by recency (for example, ",(0,i.jsx)(n.code,{children:'"d7"'})," for last 7 days)"]})]}),(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.td,{children:(0,i.jsx)(n.code,{children:"safe_search"})}),(0,i.jsx)(n.td,{children:"string"}),(0,i.jsxs)(n.td,{children:["Safe search level: ",(0,i.jsx)(n.code,{children:'"off"'}),", ",(0,i.jsx)(n.code,{children:'"medium"'}),", or ",(0,i.jsx)(n.code,{children:'"high"'})]})]})]})]}),"\n",(0,i.jsx)(n.h3,{id:"usage-examples",children:"Usage Examples"}),"\n",(0,i.jsx)(n.p,{children:"A basic web search:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{children:'Search the web for "latest developments in quantum computing"\n'})}),"\n",(0,i.jsx)(n.p,{children:"An image search:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{children:'Search for images of "aurora borealis"\n'})}),"\n",(0,i.jsx)(n.p,{children:"A search with date restriction:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{children:'Search for news about "AI regulations" from the last 7 days\n'})}),"\n",(0,i.jsx)(n.h3,{id:"response-format",children:"Response Format"}),"\n",(0,i.jsx)(n.p,{children:"The tool returns search results with the following information for each result:"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsx)(n.li,{children:"Title and URL of the source"}),"\n",(0,i.jsx)(n.li,{children:"A text snippet from the page"}),"\n",(0,i.jsx)(n.li,{children:"Attribution information for citations"}),"\n",(0,i.jsx)(n.li,{children:"Favicon URL for display purposes"}),"\n"]}),"\n",(0,i.jsx)(n.p,{children:"The results include metadata that enables automatic citation rendering in the UI. Agents should cite sources using the citation format provided in their instructions."}),"\n",(0,i.jsx)(n.admonition,{type:"info",children:(0,i.jsx)(n.p,{children:"Image results are displayed automatically in the UI. Agents should not cite images or mention image URLs in their response text."})}),"\n",(0,i.jsx)(n.h2,{id:"deep-research-tool",children:"Deep Research Tool"}),"\n",(0,i.jsxs)(n.p,{children:["The ",(0,i.jsx)(n.code,{children:"deep_research"})," tool conducts comprehensive, iterative research across multiple sources. It uses LLM-powered reflection to identify knowledge gaps and refine search queries, then synthesizes findings into a detailed report with proper citations."]}),"\n",(0,i.jsx)(n.h3,{id:"how-deep-research-works",children:"How Deep Research Works"}),"\n",(0,i.jsx)(n.p,{children:"The deep research process follows these steps:"}),"\n",(0,i.jsxs)(n.ol,{children:["\n",(0,i.jsx)(n.li,{children:"The tool breaks down the research question into multiple search queries using LLM analysis"}),"\n",(0,i.jsx)(n.li,{children:"It searches across configured sources (currently web search, with knowledge base support planned)"}),"\n",(0,i.jsx)(n.li,{children:"The LLM reflects on the findings to assess completeness and identify gaps"}),"\n",(0,i.jsx)(n.li,{children:"Based on the reflection, the tool generates refined queries and conducts additional searches"}),"\n",(0,i.jsx)(n.li,{children:"The tool selects the most authoritative sources and fetches their full content"}),"\n",(0,i.jsx)(n.li,{children:"Finally, it synthesizes all findings into a comprehensive report with citations"}),"\n"]}),"\n",(0,i.jsx)(n.p,{children:"Throughout this process, the tool sends progress updates to the frontend, allowing users to see the current research phase, queries being executed, and sources being analyzed."}),"\n",(0,i.jsx)(n.h3,{id:"parameters-1",children:"Parameters"}),"\n",(0,i.jsxs)(n.table,{children:[(0,i.jsx)(n.thead,{children:(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.th,{children:"Parameter"}),(0,i.jsx)(n.th,{children:"Type"}),(0,i.jsx)(n.th,{children:"Description"})]})}),(0,i.jsxs)(n.tbody,{children:[(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.td,{children:(0,i.jsx)(n.code,{children:"research_question"})}),(0,i.jsx)(n.td,{children:"string"}),(0,i.jsx)(n.td,{children:"The research question or topic to investigate (required)"})]}),(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.td,{children:(0,i.jsx)(n.code,{children:"research_type"})}),(0,i.jsx)(n.td,{children:"string"}),(0,i.jsxs)(n.td,{children:[(0,i.jsx)(n.code,{children:'"quick"'})," (5 min, 3 iterations) or ",(0,i.jsx)(n.code,{children:'"in-depth"'})," (10 min, 10 iterations)"]})]}),(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.td,{children:(0,i.jsx)(n.code,{children:"max_iterations"})}),(0,i.jsx)(n.td,{children:"integer"}),(0,i.jsx)(n.td,{children:"Maximum research iterations (1-10, overrides research_type)"})]}),(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.td,{children:(0,i.jsx)(n.code,{children:"max_runtime_minutes"})}),(0,i.jsx)(n.td,{children:"integer"}),(0,i.jsx)(n.td,{children:"Maximum runtime in minutes (1-10, overrides research_type)"})]}),(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.td,{children:(0,i.jsx)(n.code,{children:"max_runtime_seconds"})}),(0,i.jsx)(n.td,{children:"integer"}),(0,i.jsx)(n.td,{children:"Maximum runtime in seconds (60-600)"})]}),(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.td,{children:(0,i.jsx)(n.code,{children:"sources"})}),(0,i.jsx)(n.td,{children:"array"}),(0,i.jsxs)(n.td,{children:["Sources to search: ",(0,i.jsx)(n.code,{children:'["web"]'})," or ",(0,i.jsx)(n.code,{children:'["web", "kb"]'})]})]}),(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.td,{children:(0,i.jsx)(n.code,{children:"kb_ids"})}),(0,i.jsx)(n.td,{children:"array"}),(0,i.jsxs)(n.td,{children:["Specific knowledge base IDs to search (when ",(0,i.jsx)(n.code,{children:'"kb"'})," is in sources)"]})]})]})]}),"\n",(0,i.jsx)(n.h3,{id:"configuration-priority",children:"Configuration Priority"}),"\n",(0,i.jsx)(n.p,{children:"The tool resolves configuration in this order (highest to lowest priority):"}),"\n",(0,i.jsxs)(n.ol,{children:["\n",(0,i.jsx)(n.li,{children:"Explicit parameters passed to the tool"}),"\n",(0,i.jsxs)(n.li,{children:["Values from ",(0,i.jsx)(n.code,{children:"tool_config"})," in the agent configuration"]}),"\n",(0,i.jsxs)(n.li,{children:["Defaults based on ",(0,i.jsx)(n.code,{children:"research_type"}),' ("quick" or "in-depth")']}),"\n"]}),"\n",(0,i.jsx)(n.h3,{id:"research-types",children:"Research Types"}),"\n",(0,i.jsxs)(n.p,{children:["The ",(0,i.jsx)(n.code,{children:"research_type"})," parameter provides convenient presets:"]}),"\n",(0,i.jsxs)(n.table,{children:[(0,i.jsx)(n.thead,{children:(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.th,{children:"Type"}),(0,i.jsx)(n.th,{children:"Duration"}),(0,i.jsx)(n.th,{children:"Iterations"}),(0,i.jsx)(n.th,{children:"Use Case"})]})}),(0,i.jsxs)(n.tbody,{children:[(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.td,{children:(0,i.jsx)(n.code,{children:"quick"})}),(0,i.jsx)(n.td,{children:"5 minutes"}),(0,i.jsx)(n.td,{children:"3"}),(0,i.jsx)(n.td,{children:"Fast answers, simple topics"})]}),(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.td,{children:(0,i.jsx)(n.code,{children:"in-depth"})}),(0,i.jsx)(n.td,{children:"10 minutes"}),(0,i.jsx)(n.td,{children:"10"}),(0,i.jsx)(n.td,{children:"Complex topics, comprehensive analysis"})]})]})]}),"\n",(0,i.jsx)(n.h3,{id:"advanced-configuration",children:"Advanced Configuration"}),"\n",(0,i.jsx)(n.p,{children:"You can configure phase-specific models for cost optimization or quality control:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-yaml",children:'- tool_type: builtin\n  tool_name: "deep_research"\n  tool_config:\n    google_search_api_key: ${GOOGLE_API_KEY}\n    google_cse_id: ${GOOGLE_CSE_ID}\n    \n    # Use faster models for query generation and reflection\n    models:\n      query_generation: "gpt-4o-mini"\n      reflection: "gpt-4o-mini"\n      source_selection: "gpt-4o-mini"\n    \n    # Use a more capable model for report generation\n    model_configs:\n      report_generation:\n        model: "claude-3-5-sonnet-20241022"\n        temperature: 0.7\n        max_tokens: 16000\n'})}),"\n",(0,i.jsx)(n.h3,{id:"usage-examples-1",children:"Usage Examples"}),"\n",(0,i.jsx)(n.p,{children:"A quick research request:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{children:"Research the current state of renewable energy adoption in Europe\n"})}),"\n",(0,i.jsx)(n.p,{children:"An in-depth research request:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{children:"Conduct in-depth research on the economic impact of artificial intelligence on the job market over the next decade\n"})}),"\n",(0,i.jsx)(n.p,{children:"A research request with specific parameters:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{children:"Research quantum computing applications in drug discovery. Use 5 iterations and limit to 3 minutes.\n"})}),"\n",(0,i.jsx)(n.h3,{id:"output",children:"Output"}),"\n",(0,i.jsx)(n.p,{children:"The deep research tool produces:"}),"\n",(0,i.jsxs)(n.ol,{children:["\n",(0,i.jsx)(n.li,{children:"A comprehensive research report saved as a Markdown artifact"}),"\n",(0,i.jsx)(n.li,{children:"Metadata with all sources and citations for UI rendering"}),"\n",(0,i.jsx)(n.li,{children:"Progress updates throughout the research process"}),"\n"]}),"\n",(0,i.jsx)(n.p,{children:"The report includes:"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsx)(n.li,{children:"Executive summary"}),"\n",(0,i.jsx)(n.li,{children:"Introduction with context"}),"\n",(0,i.jsx)(n.li,{children:"Main analysis organized by themes"}),"\n",(0,i.jsx)(n.li,{children:"Comparative analysis of different perspectives"}),"\n",(0,i.jsx)(n.li,{children:"Implications and conclusions"}),"\n",(0,i.jsx)(n.li,{children:"References section with all cited sources"}),"\n",(0,i.jsx)(n.li,{children:"Research methodology section"}),"\n"]}),"\n",(0,i.jsx)(n.h3,{id:"progress-updates",children:"Progress Updates"}),"\n",(0,i.jsx)(n.p,{children:"During research, the tool sends structured progress updates that include:"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsx)(n.li,{children:"Current phase (planning, searching, analyzing, writing)"}),"\n",(0,i.jsx)(n.li,{children:"Progress percentage"}),"\n",(0,i.jsx)(n.li,{children:"Current iteration and total iterations"}),"\n",(0,i.jsx)(n.li,{children:"Number of sources found"}),"\n",(0,i.jsx)(n.li,{children:"Current search query"}),"\n",(0,i.jsx)(n.li,{children:"URLs being fetched"}),"\n"]}),"\n",(0,i.jsx)(n.p,{children:"These updates enable rich UI visualizations of the research process."}),"\n",(0,i.jsx)(n.h2,{id:"required-scopes",children:"Required Scopes"}),"\n",(0,i.jsx)(n.p,{children:"The research tools require the following scopes for authorization:"}),"\n",(0,i.jsxs)(n.table,{children:[(0,i.jsx)(n.thead,{children:(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.th,{children:"Tool"}),(0,i.jsx)(n.th,{children:"Required Scope"})]})}),(0,i.jsxs)(n.tbody,{children:[(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.td,{children:(0,i.jsx)(n.code,{children:"web_search_google"})}),(0,i.jsx)(n.td,{children:(0,i.jsx)(n.code,{children:"tool:web_search:execute"})})]}),(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.td,{children:(0,i.jsx)(n.code,{children:"deep_research"})}),(0,i.jsx)(n.td,{children:(0,i.jsx)(n.code,{children:"tool:research:deep_research"})})]})]})]}),"\n",(0,i.jsx)(n.h2,{id:"alternative-search-providers",children:"Alternative Search Providers"}),"\n",(0,i.jsx)(n.p,{children:"The built-in web search uses Google Custom Search API. For other search providers such as Exa, Brave, or Tavily, use the corresponding plugins from the solace-agent-mesh-plugins repository."}),"\n",(0,i.jsx)(n.h2,{id:"technical-considerations",children:"Technical Considerations"}),"\n",(0,i.jsx)(n.h3,{id:"rate-limits",children:"Rate Limits"}),"\n",(0,i.jsx)(n.p,{children:"Google Custom Search API has usage limits. Monitor your API usage and implement appropriate rate limiting for production deployments."}),"\n",(0,i.jsx)(n.h3,{id:"content-fetching",children:"Content Fetching"}),"\n",(0,i.jsx)(n.p,{children:"When the deep research tool fetches full content from web pages, some sites may block automated requests or return incomplete content. The tool handles these failures gracefully and continues with available sources."}),"\n",(0,i.jsx)(n.h3,{id:"report-quality",children:"Report Quality"}),"\n",(0,i.jsx)(n.p,{children:"The quality of research reports depends on:"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsx)(n.li,{children:"The quality and relevance of search results"}),"\n",(0,i.jsx)(n.li,{children:"The number of iterations and sources analyzed"}),"\n",(0,i.jsx)(n.li,{children:"The capabilities of the LLM used for report generation"}),"\n"]}),"\n",(0,i.jsx)(n.p,{children:"For best results, use capable models for the report generation phase and allow sufficient iterations for complex topics."})]})}function h(e={}){const{wrapper:n}={...(0,t.R)(),...e.components};return n?(0,i.jsx)(n,{...e,children:(0,i.jsx)(a,{...e})}):a(e)}},8453:(e,n,s)=>{s.d(n,{R:()=>o,x:()=>l});var r=s(6540);const i={},t=r.createContext(i);function o(e){const n=r.useContext(t);return r.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(i):e.components||i:o(e.components),r.createElement(t.Provider,{value:n},e.children)}}}]);

solace_agent_mesh/assets/docs/assets/js/{509e993c.4c7a1a6d.js → 509e993c.a1fbf45a.js}

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