PyPI - solace-agent-mesh - Versions diffs - 1.5.0__py3-none-any.whl → 1.6.0__py3-none-any.whl - Mend

solace-agent-mesh 1.5.0py3-none-any.whl → 1.6.0py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Potentially problematic release.

This version of solace-agent-mesh might be problematic. Click here for more details.

Files changed (326) hide show

solace_agent_mesh/assets/docs/assets/js/bac0be12.17de4316.js DELETED Viewed

@@ -1 +0,0 @@

- "use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[2807],{8628:(e,n,t)=>{t.r(n),t.d(n,{assets:()=>l,contentTitle:()=>o,default:()=>h,frontMatter:()=>r,metadata:()=>a,toc:()=>c});const a=JSON.parse('{"id":"documentation/tutorials/event-mesh-gateway","title":"Event Mesh Gateway","description":"If you already have an event mesh in place, you can integrate Solace Agent Mesh into it. This allows you to leverage existing infrastructure while introducing intelligence and automation through Solace Agent Mesh.","source":"@site/docs/documentation/tutorials/event-mesh-gateway.md","sourceDirName":"documentation/tutorials","slug":"/documentation/tutorials/event-mesh-gateway","permalink":"/solace-agent-mesh/docs/documentation/tutorials/event-mesh-gateway","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/tutorials/event-mesh-gateway.md","tags":[],"version":"current","sidebarPosition":20,"frontMatter":{"title":"Event Mesh Gateway","sidebar_position":20},"sidebar":"docSidebar","previous":{"title":"REST Gateway","permalink":"/solace-agent-mesh/docs/documentation/tutorials/rest-gateway"},"next":{"title":"Amazon Bedrock Agents","permalink":"/solace-agent-mesh/docs/documentation/tutorials/bedrock-agents"}}');var s=t(4848),i=t(8453);const r={title:"Event Mesh Gateway",sidebar_position:20},o="Event Mesh Gateway",l={},c=[{value:"Benefits of Integrating with an Event Mesh",id:"benefits-of-integrating-with-an-event-mesh",level:2},{value:"Prerequisites",id:"prerequisites",level:2},{value:"Setting Up the Environment",id:"setting-up-the-environment",level:2},{value:"Adding the Event Mesh Gateway Plugin",id:"adding-the-event-mesh-gateway-plugin",level:2},{value:"Configuring the Event Mesh Gateway",id:"configuring-the-event-mesh-gateway",level:4},{value:"Environment Variables",id:"environment-variables",level:4},{value:"Gateway Configuration",id:"gateway-configuration",level:3},{value:"Event Handlers",id:"event-handlers",level:4},{value:"Output Handlers",id:"output-handlers",level:4},{value:"Complete Configuration Example",id:"complete-configuration-example",level:3},{value:"Running the Event Mesh Gateway",id:"running-the-event-mesh-gateway",level:2},{value:"Testing the Event Mesh Gateway",id:"testing-the-event-mesh-gateway",level:2},{value:"Using The Solace Broker Manager",id:"using-the-solace-broker-manager",level:3},{value:"Advanced Features",id:"advanced-features",level:2},{value:"Artifact Processing",id:"artifact-processing",level:3},{value:"Dynamic Agent Routing",id:"dynamic-agent-routing",level:3},{value:"Context Forwarding",id:"context-forwarding",level:3},{value:"Error Handling",id:"error-handling",level:3}];function d(e){const n={a:"a",code:"code",h1:"h1",h2:"h2",h3:"h3",h4:"h4",header:"header",li:"li",ol:"ol",p:"p",pre:"pre",strong:"strong",ul:"ul",...(0,i.R)(),...e.components};return(0,s.jsxs)(s.Fragment,{children:[(0,s.jsx)(n.header,{children:(0,s.jsx)(n.h1,{id:"event-mesh-gateway",children:"Event Mesh Gateway"})}),"\n",(0,s.jsxs)(n.p,{children:["If you already have an ",(0,s.jsx)(n.a,{href:"https://solace.com/what-is-an-event-mesh/",children:"event mesh"})," in place, you can integrate Solace Agent Mesh into it. This allows you to leverage existing infrastructure while introducing intelligence and automation through Solace Agent Mesh."]}),"\n",(0,s.jsx)(n.h2,{id:"benefits-of-integrating-with-an-event-mesh",children:"Benefits of Integrating with an Event Mesh"}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Seamless Communication"}),": Solace Agent Mesh can subscribe to and publish events across the entire event mesh"]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Event-Driven Automation"}),": Intelligent event processing based on patterns and AI-driven insights"]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Scalability"}),": Solace Agent Mesh can dynamically participate in large-scale event-driven systems"]}),"\n"]}),"\n",(0,s.jsx)(n.p,{children:"The Event Mesh Gateway connects Solace Agent Mesh to your existing event mesh infrastructure. Through its asynchronous interfaces, applications within your event mesh can seamlessly access and utilize Solace Agent Mesh capabilities."}),"\n",(0,s.jsx)(n.p,{children:"This tutorial shows you how to build an Event Mesh Gateway that automatically generates and adds concise summaries to Jira bug reports, making them easier to understand at a glance."}),"\n",(0,s.jsx)(n.h2,{id:"prerequisites",children:"Prerequisites"}),"\n",(0,s.jsx)(n.p,{children:"This tutorial assumes you have an existing Jira application integrated with your event mesh that:"}),"\n",(0,s.jsxs)(n.ol,{children:["\n",(0,s.jsxs)(n.li,{children:['Publishes a "jira_created" event to topic ',(0,s.jsx)(n.code,{children:"jira/issue/created/<jira_id>"})," when a new Jira issue is created"]}),"\n",(0,s.jsxs)(n.li,{children:['Listens for "jira_update" events on topic ',(0,s.jsx)(n.code,{children:"jira/issue/update"})," to update existing issues"]}),"\n"]}),"\n",(0,s.jsx)(n.p,{children:"Create an Event Mesh Gateway that:"}),"\n",(0,s.jsxs)(n.ol,{children:["\n",(0,s.jsx)(n.li,{children:"Monitors for new Jira issues"}),"\n",(0,s.jsx)(n.li,{children:"Automatically generates a concise summary"}),"\n",(0,s.jsx)(n.li,{children:"Creates an event to update the original Jira issue with this summary"}),"\n"]}),"\n",(0,s.jsx)(n.p,{children:"This creates a streamlined workflow where bug reports are automatically enhanced with clear, AI-generated summaries."}),"\n",(0,s.jsx)(n.h2,{id:"setting-up-the-environment",children:"Setting Up the Environment"}),"\n",(0,s.jsxs)(n.p,{children:["First, you need to ",(0,s.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/getting-started/installation",children:"install Solace Agent Mesh and the Solace Agent Mesh CLI"}),", and then ",(0,s.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/getting-started/quick-start",children:"create a new Solace Agent Mesh project"}),"."]}),"\n",(0,s.jsxs)(n.p,{children:["For this tutorial, you need to create or use an existing ",(0,s.jsx)(n.a,{href:"https://solace.com/products/event-broker/",children:"Solace Event Broker"})," or ",(0,s.jsx)(n.a,{href:"https://solace.com/solutions/initiative/event-mesh/",children:"event mesh"})," created using Solace event brokers."]}),"\n",(0,s.jsx)(n.h2,{id:"adding-the-event-mesh-gateway-plugin",children:"Adding the Event Mesh Gateway Plugin"}),"\n",(0,s.jsx)(n.p,{children:"Once you have your project set up, add the Event Mesh Gateway plugin:"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-sh",children:"sam plugin add jira-event-mesh --plugin sam-event-mesh-gateway\n"})}),"\n",(0,s.jsxs)(n.p,{children:["You can use any name for your agent, in this tutorial we use ",(0,s.jsx)(n.code,{children:"jira-event-mesh"}),"."]}),"\n",(0,s.jsx)(n.p,{children:"This command:"}),"\n",(0,s.jsxs)(n.ol,{children:["\n",(0,s.jsxs)(n.li,{children:["Installs the ",(0,s.jsx)(n.code,{children:"sam-event-mesh-gateway"})," plugin"]}),"\n",(0,s.jsxs)(n.li,{children:["Creates a new gateway configuration named ",(0,s.jsx)(n.code,{children:"jira-event-mesh"})," in your ",(0,s.jsx)(n.code,{children:"configs/gateways/"})," directory"]}),"\n"]}),"\n",(0,s.jsx)(n.h4,{id:"configuring-the-event-mesh-gateway",children:"Configuring the Event Mesh Gateway"}),"\n",(0,s.jsxs)(n.p,{children:["After adding the plugin, you can see a new configuration file in ",(0,s.jsx)(n.code,{children:"configs/gateways/jira-event-mesh.yaml"}),". This file contains the gateway configuration that needs to be customized for your Jira integration use case."]}),"\n",(0,s.jsx)(n.h4,{id:"environment-variables",children:"Environment Variables"}),"\n",(0,s.jsx)(n.p,{children:"First, set up the required environment variables for the data plane connection:"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-sh",children:'# Data plane Solace broker connection (can be same or different from control plane)\nexport JIRA_EVENT_MESH_SOLACE_BROKER_URL="ws://localhost:8008"\nexport JIRA_EVENT_MESH_SOLACE_BROKER_VPN="default"\nexport JIRA_EVENT_MESH_SOLACE_BROKER_USERNAME="default"\nexport JIRA_EVENT_MESH_SOLACE_BROKER_PASSWORD="default"\n'})}),"\n",(0,s.jsx)(n.h3,{id:"gateway-configuration",children:"Gateway Configuration"}),"\n",(0,s.jsx)(n.p,{children:"The main configuration includes several key sections:"}),"\n",(0,s.jsx)(n.h4,{id:"event-handlers",children:"Event Handlers"}),"\n",(0,s.jsx)(n.p,{children:"Configure the event handler to listen for new Jira issues and generate summaries:"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-yaml",children:'event_handlers:\n - name: "jira_issue_handler"\n subscriptions:\n - topic: "jira/issue/created/>"\n qos: 1\n input_expression: "template:Create a concise summary for the newly created Jira issue: Title: {{text://input.payload:title}}, Body: {{text://input.payload:body}}, ID: {{text://input.payload:id}}. Return a JSON object with fields \'id\', \'type\' (value should be \'summary\'), and \'summary\'."\n payload_encoding: "utf-8"\n payload_format: "json"\n target_agent_name: "OrchestratorAgent"\n on_success: "jira_summary_handler"\n on_error: "error_response_handler"\n forward_context:\n jira_id: "input.payload:id"\n correlation_id: "input.user_properties:correlation_id"\n'})}),"\n",(0,s.jsx)(n.h4,{id:"output-handlers",children:"Output Handlers"}),"\n",(0,s.jsx)(n.p,{children:"Configure output handlers to publish the summary back to the event mesh:"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-yaml",children:'output_handlers:\n - name: "jira_summary_handler"\n topic_expression: "static:jira/issue/update"\n payload_expression: "task_response:text"\n payload_encoding: "utf-8"\n payload_format: "json"\n \n - name: "error_response_handler"\n topic_expression: "template:jira/issue/error/{{text://user_data.forward_context:jira_id}}"\n payload_expression: "task_response:a2a_task_response.error"\n payload_encoding: "utf-8"\n payload_format: "json"\n'})}),"\n",(0,s.jsx)(n.h3,{id:"complete-configuration-example",children:"Complete Configuration Example"}),"\n",(0,s.jsx)(n.p,{children:"Here is a complete configuration file based on the plugin template:"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-yaml",children:'log:\n stdout_log_level: INFO\n log_file_level: DEBUG\n log_file: jira-event-mesh.log\n\n!include ../shared_config.yaml\n\napps:\n - name: jira-event-mesh-app\n app_module: sam_event_mesh_gateway.app\n broker:\n <<: *broker_connection\n\n app_config:\n namespace: ${NAMESPACE}\n gateway_id: "jira-event-mesh-gw-01"\n artifact_service: *default_artifact_service\n authorization_service:\n type: "none" # Or "default_rbac"\n default_user_identity: "anonymous_event_mesh_user" # If no identity from event\n\n\n\n # Data plane connection\n event_mesh_broker_config:\n broker_url: ${JIRA_EVENT_MESH_SOLACE_BROKER_URL}\n broker_vpn: ${JIRA_EVENT_MESH_SOLACE_BROKER_VPN}\n broker_username: ${JIRA_EVENT_MESH_SOLACE_BROKER_USERNAME}\n broker_password: ${JIRA_EVENT_MESH_SOLACE_BROKER_PASSWORD}\n\n event_handlers:\n - name: "jira_issue_handler"\n subscriptions:\n - topic: "jira/issue/created/>"\n qos: 1\n input_expression: "template:Create a concise summary for the newly created Jira issue: Title: {{text://input.payload:title}}, Body: {{text://input.payload:body}}, ID: {{text://input.payload:id}}. Return a JSON object with fields \'id\', \'type\' (value should be \'summary\'), and \'summary\'."\n payload_encoding: "utf-8"\n payload_format: "json"\n target_agent_name: "OrchestratorAgent"\n on_success: "jira_summary_handler"\n on_error: "error_response_handler"\n forward_context:\n jira_id: "input.payload:id"\n\n output_handlers:\n - name: "jira_summary_handler"\n topic_expression: "static:jira/issue/update"\n payload_expression: "task_response:text"\n payload_encoding: "utf-8"\n payload_format: "json"\n \n - name: "error_response_handler"\n topic_expression: "template:jira/issue/error/{{text://user_data.forward_context:jira_id}}"\n payload_expression: "task_response:a2a_task_response.error"\n payload_encoding: "utf-8"\n payload_format: "json"\n'})}),"\n",(0,s.jsx)(n.h2,{id:"running-the-event-mesh-gateway",children:"Running the Event Mesh Gateway"}),"\n",(0,s.jsx)(n.p,{children:"Now you can run the Event Mesh Gateway:"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-sh",children:"sam run configs/gateways/jira-event-mesh.yaml\n"})}),"\n",(0,s.jsx)(n.p,{children:"The gateway:"}),"\n",(0,s.jsxs)(n.ol,{children:["\n",(0,s.jsx)(n.li,{children:"Connects to both the A2A control plane and the data plane event mesh"}),"\n",(0,s.jsx)(n.li,{children:"Subscribes to the configured topics on the data plane"}),"\n",(0,s.jsx)(n.li,{children:"Starts processing incoming events and routing them to agents"}),"\n"]}),"\n",(0,s.jsx)(n.h2,{id:"testing-the-event-mesh-gateway",children:"Testing the Event Mesh Gateway"}),"\n",(0,s.jsx)(n.p,{children:"Now that the system is running, let's test the Event Mesh Gateway."}),"\n",(0,s.jsx)(n.h3,{id:"using-the-solace-broker-manager",children:"Using The Solace Broker Manager"}),"\n",(0,s.jsxs)(n.ol,{children:["\n",(0,s.jsxs)(n.li,{children:["\n",(0,s.jsxs)(n.p,{children:["Open the ",(0,s.jsx)(n.strong,{children:"Try Me!"})," tab of the ",(0,s.jsx)(n.a,{href:"https://docs.solace.com/Admin/Broker-Manager/PubSub-Manager-Overview.htm",children:"Solace Broker Manager"})]}),"\n"]}),"\n",(0,s.jsxs)(n.li,{children:["\n",(0,s.jsxs)(n.p,{children:["Connect both the ",(0,s.jsx)(n.strong,{children:"Publisher"})," and ",(0,s.jsx)(n.strong,{children:"Subscriber"})," panels by clicking their respective ",(0,s.jsx)(n.strong,{children:"Connect"})," buttons"]}),"\n"]}),"\n",(0,s.jsxs)(n.li,{children:["\n",(0,s.jsx)(n.p,{children:"In the Subscriber panel:"}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:["Enter ",(0,s.jsx)(n.code,{children:"jira/issue/update"})," in the ",(0,s.jsx)(n.code,{children:"Topic Subscriber"})," field"]}),"\n",(0,s.jsxs)(n.li,{children:["Click ",(0,s.jsx)(n.code,{children:"Subscribe"})]}),"\n"]}),"\n"]}),"\n",(0,s.jsxs)(n.li,{children:["\n",(0,s.jsx)(n.p,{children:"In the Publisher panel:"}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:["Use the topic ",(0,s.jsx)(n.code,{children:"jira/issue/created/JIRA-143321"})]}),"\n",(0,s.jsxs)(n.li,{children:["In the ",(0,s.jsx)(n.code,{children:"Message Content"})," field, enter:"]}),"\n"]}),"\n"]}),"\n"]}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-json",children:'{\n "id": "JIRA-143321",\n "title": "Exception when reading customer record",\n "body": "I got a DatabaseReadException when trying to get the data for customer ABC. The error indicated that the customer didn\'t exist, while they are our biggest customer!"\n}\n'})}),"\n",(0,s.jsxs)(n.ol,{start:"5",children:["\n",(0,s.jsxs)(n.li,{children:["Click ",(0,s.jsx)(n.strong,{children:"Publish"})]}),"\n"]}),"\n",(0,s.jsxs)(n.p,{children:["After a few seconds, you can see a new message in the ",(0,s.jsx)(n.strong,{children:"Subscriber"})," messages with the topic ",(0,s.jsx)(n.code,{children:"jira/issue/update"})," and a body similar to:"]}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-json",children:'{\n "id": "JIRA-143321",\n "type": "summary",\n "summary": "Database read error: Unable to retrieve record for key customer ABC despite confirmed existence"\n}\n'})}),"\n",(0,s.jsx)(n.h2,{id:"advanced-features",children:"Advanced Features"}),"\n",(0,s.jsx)(n.p,{children:"The Event Mesh Gateway supports several advanced features:"}),"\n",(0,s.jsx)(n.h3,{id:"artifact-processing",children:"Artifact Processing"}),"\n",(0,s.jsx)(n.p,{children:"You can configure the gateway to automatically create artifacts from incoming message payloads before sending them to agents. This is useful for processing files, images, or other binary data embedded in events."}),"\n",(0,s.jsx)(n.h3,{id:"dynamic-agent-routing",children:"Dynamic Agent Routing"}),"\n",(0,s.jsxs)(n.p,{children:["Instead of using a static ",(0,s.jsx)(n.code,{children:"target_agent_name"}),", you can use ",(0,s.jsx)(n.code,{children:"target_agent_name_expression"})," to dynamically determine which agent should process each event based on the message content."]}),"\n",(0,s.jsx)(n.h3,{id:"context-forwarding",children:"Context Forwarding"}),"\n",(0,s.jsxs)(n.p,{children:["The ",(0,s.jsx)(n.code,{children:"forward_context"})," configuration allows you to extract data from incoming messages and make it available when generating outgoing responses, enabling request-reply patterns and correlation tracking."]}),"\n",(0,s.jsx)(n.h3,{id:"error-handling",children:"Error Handling"}),"\n",(0,s.jsx)(n.p,{children:"Configure separate output handlers for success and error scenarios to ensure proper error reporting and system monitoring."})]})}function h(e={}){const{wrapper:n}={...(0,i.R)(),...e.components};return n?(0,s.jsx)(n,{...e,children:(0,s.jsx)(d,{...e})}):d(e)}},8453:(e,n,t)=>{t.d(n,{R:()=>r,x:()=>o});var a=t(6540);const s={},i=a.createContext(s);function r(e){const n=a.useContext(i);return a.useMemo((function(){return"function"==typeof e?e(n):{...n,...e}}),[n,e])}function o(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(s):e.components||s:r(e.components),a.createElement(i.Provider,{value:n},e.children)}}}]);

solace_agent_mesh/assets/docs/assets/js/c2c06897.87cb1f47.js DELETED Viewed

@@ -1 +0,0 @@

- "use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[1955],{1269:(e,r,n)=>{n.r(r),n.d(r,{assets:()=>c,contentTitle:()=>d,default:()=>h,frontMatter:()=>o,metadata:()=>i,toc:()=>a});const i=JSON.parse('{"id":"documentation/user-guide/creating-service-providers","title":"Creating Service Providers","description":"This guide details the process for developers to create service provider plugins for integrating backend systems (for example, HR platforms, CRMs) with Solace Agent Mesh.","source":"@site/docs/documentation/user-guide/creating-service-providers.md","sourceDirName":"documentation/user-guide","slug":"/documentation/user-guide/creating-service-providers","permalink":"/solace-agent-mesh/docs/documentation/user-guide/creating-service-providers","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/user-guide/creating-service-providers.md","tags":[],"version":"current","sidebarPosition":50,"frontMatter":{"title":"Creating Service Providers","sidebar_position":50},"sidebar":"docSidebar","previous":{"title":"Create Gateways","permalink":"/solace-agent-mesh/docs/documentation/user-guide/create-gateways"},"next":{"title":"Configuring Built-in Tools","permalink":"/solace-agent-mesh/docs/documentation/user-guide/builtin-tools/"}}');var t=n(4848),s=n(8453);const o={title:"Creating Service Providers",sidebar_position:50},d="Creating Service Providers",c={},a=[{value:"Understanding Service Providers",id:"understanding-service-providers",level:2},{value:"The "Dual-Role Provider" Pattern",id:"the-dual-role-provider-pattern",level:2},{value:"Step-by-Step Implementation Guide",id:"step-by-step-implementation-guide",level:2},{value:"Step 1: Establish the Plugin Structure",id:"step-1-establish-the-plugin-structure",level:3},{value:"Step 2: Define the Provider Class",id:"step-2-define-the-provider-class",level:3},{value:"Step 3: Map to the Canonical Employee Schema",id:"step-3-map-to-the-canonical-employee-schema",level:3},{value:"Step 4: Register the Plugin",id:"step-4-register-the-plugin",level:3},{value:"Configuring the Provider",id:"configuring-the-provider",level:2}];function l(e){const r={admonition:"admonition",code:"code",h1:"h1",h2:"h2",h3:"h3",header:"header",li:"li",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,t.jsxs)(t.Fragment,{children:[(0,t.jsx)(r.header,{children:(0,t.jsx)(r.h1,{id:"creating-service-providers",children:"Creating Service Providers"})}),"\n",(0,t.jsx)(r.p,{children:"This guide details the process for developers to create service provider plugins for integrating backend systems (for example, HR platforms, CRMs) with Solace Agent Mesh."}),"\n",(0,t.jsx)(r.h2,{id:"understanding-service-providers",children:"Understanding Service Providers"}),"\n",(0,t.jsx)(r.p,{children:"Service Providers function as the abstraction layer between Solace Agent Mesh and enterprise data sources. They are implemented as Python classes that adhere to a specific abstract base class, enabling standardized interaction between Solace Agent Mesh components (Gateways and Agents) and the underlying data."}),"\n",(0,t.jsx)(r.p,{children:"There are two primary service provider interfaces:"}),"\n",(0,t.jsxs)(r.ul,{children:["\n",(0,t.jsxs)(r.li,{children:[(0,t.jsx)(r.strong,{children:(0,t.jsx)(r.code,{children:"BaseIdentityService"})}),": Responsible for ",(0,t.jsx)(r.strong,{children:"identity enrichment"}),". This service is utilized by Gateways to augment the profile of an authenticated user with additional details (for example, full name, job title) based on their initial authentication claims."]}),"\n",(0,t.jsxs)(r.li,{children:[(0,t.jsx)(r.strong,{children:(0,t.jsx)(r.code,{children:"BaseEmployeeService"})}),": Responsible for ",(0,t.jsx)(r.strong,{children:"general directory querying"}),". This service is utilized by agents (for example, the ",(0,t.jsx)(r.code,{children:"EmployeeAgent"}),") to execute lookups across the entire employee directory."]}),"\n"]}),"\n",(0,t.jsx)(r.h2,{id:"the-dual-role-provider-pattern",children:'The "Dual-Role Provider" Pattern'}),"\n",(0,t.jsx)(r.p,{children:'In many enterprise systems, particularly HR platforms, the data source for identity enrichment and general employee queries is identical. To optimize development, Solace Agent Mesh promotes a "Dual-Role Provider" pattern.'}),"\n",(0,t.jsxs)(r.p,{children:["This pattern involves creating a single class that inherits from both ",(0,t.jsx)(r.code,{children:"BaseIdentityService"})," and ",(0,t.jsx)(r.code,{children:"BaseEmployeeService"}),". This consolidated class can then be configured to fulfill either or both roles, thereby reducing code duplication."]}),"\n",(0,t.jsx)(r.h2,{id:"step-by-step-implementation-guide",children:"Step-by-Step Implementation Guide"}),"\n",(0,t.jsx)(r.p,{children:'This section provides a walkthrough for creating a new provider for a fictional "CorpHR" system.'}),"\n",(0,t.jsx)(r.h3,{id:"step-1-establish-the-plugin-structure",children:"Step 1: Establish the Plugin Structure"}),"\n",(0,t.jsxs)(r.p,{children:["The recommended structure for a custom service provider plugin should include a ",(0,t.jsx)(r.code,{children:"pyproject.toml"})," for packaging and a ",(0,t.jsx)(r.code,{children:"src"})," directory for the source code."]}),"\n",(0,t.jsx)(r.pre,{children:(0,t.jsx)(r.code,{className:"language-bash",children:"sam plugin create my_corp_hr_provider --type custom\n"})}),"\n",(0,t.jsx)(r.h3,{id:"step-2-define-the-provider-class",children:"Step 2: Define the Provider Class"}),"\n",(0,t.jsxs)(r.p,{children:["Create a ",(0,t.jsx)(r.code,{children:"provider.py"})," module and define the provider class, ensuring it inherits from both base service classes."]}),"\n",(0,t.jsx)(r.pre,{children:(0,t.jsx)(r.code,{className:"language-python",children:'# my_corp_hr_provider/provider.py\n\n# Import base classes from the Solace Agent Mesh framework\ntry:\n from solace_agent_mesh.common.services.identity_service import BaseIdentityService\n from solace_agent_mesh.common.services.employee_service import BaseEmployeeService\nexcept ImportError:\n # Fallback for local development environments\n from src.solace_agent_mesh.common.services.identity_service import BaseIdentityService\n from src.solace_agent_mesh.common.services.employee_service import BaseEmployeeService\n\n# Import any other necessary libraries, such as \'requests\' or a proprietary SDK\n# from .corp_hr_sdk import CorpHR_SDK\n\nclass CorpHRProvider(BaseIdentityService, BaseEmployeeService):\n """\n A dual-role provider for the CorpHR system, implementing methods\n for both identity enrichment and employee directory services.\n """\n def __init__(self, config):\n super().__init__(config)\n # Initialize the backend service/SDK client here.\n # It is best practice to implement this as a singleton to share\n # connection pools and cache.\n # self.corp_hr_sdk = CorpHR_SDK(api_key=config.get("api_key"))\n\n # --- BaseIdentityService Method Implementations ---\n\n async def get_user_profile(self, auth_claims):\n """Enrich the current user\'s profile based on their auth claims."""\n # TODO: Implement logic to fetch user data from CorpHR\n pass\n\n async def search_users(self, query, limit=10):\n """Search for users, for features like @-mentions."""\n # TODO: Implement user search logic against CorpHR\n pass\n\n # --- BaseEmployeeService Method Implementations ---\n\n async def get_employee_dataframe(self):\n """Return all employees as a pandas DataFrame for directory-wide queries."""\n # TODO: Fetch all employee data and return as a DataFrame\n pass\n\n async def get_employee_profile(self, employee_id):\n """Get a single employee\'s full profile by their ID."""\n # Note: This is a general directory lookup, distinct from get_user_profile.\n # TODO: Implement single employee lookup\n pass\n\n async def get_time_off_data(self, employee_id):\n """Get an employee\'s raw time off data."""\n # Example return format:\n # return [{\'start\': \'2025-07-04\', \'end\': \'2025-07-04\', \'type\': \'Holiday\'}]\n # TODO: Implement time off data retrieval\n pass\n\n async def get_employee_profile_picture(self, employee_id):\n """Fetch a profile picture as a data URI string."""\n # Example return format: "data:image/jpeg;base64,..."\n # TODO: Implement profile picture fetching\n pass\n'})}),"\n",(0,t.jsx)(r.h3,{id:"step-3-map-to-the-canonical-employee-schema",children:"Step 3: Map to the Canonical Employee Schema"}),"\n",(0,t.jsxs)(r.p,{children:["When implementing the service methods, it is ",(0,t.jsx)(r.strong,{children:"mandatory"})," to map the data from the source system to Solace Agent Mesh's ",(0,t.jsx)(r.strong,{children:"canonical employee schema"}),". This ensures data consistency and interoperability with all tools and components across the mesh."]}),"\n",(0,t.jsxs)(r.table,{children:[(0,t.jsx)(r.thead,{children:(0,t.jsxs)(r.tr,{children:[(0,t.jsx)(r.th,{children:"Field Name"}),(0,t.jsx)(r.th,{children:"Data Type"}),(0,t.jsx)(r.th,{children:"Description"})]})}),(0,t.jsxs)(r.tbody,{children:[(0,t.jsxs)(r.tr,{children:[(0,t.jsx)(r.td,{children:(0,t.jsx)(r.code,{children:"id"})}),(0,t.jsx)(r.td,{children:(0,t.jsx)(r.code,{children:"string"})}),(0,t.jsxs)(r.td,{children:["A unique, stable, and ",(0,t.jsx)(r.strong,{children:"lowercase"})," identifier (e.g., email, GUID)."]})]}),(0,t.jsxs)(r.tr,{children:[(0,t.jsx)(r.td,{children:(0,t.jsx)(r.code,{children:"displayName"})}),(0,t.jsx)(r.td,{children:(0,t.jsx)(r.code,{children:"string"})}),(0,t.jsx)(r.td,{children:"The employee's full name for display purposes."})]}),(0,t.jsxs)(r.tr,{children:[(0,t.jsx)(r.td,{children:(0,t.jsx)(r.code,{children:"workEmail"})}),(0,t.jsx)(r.td,{children:(0,t.jsx)(r.code,{children:"string"})}),(0,t.jsx)(r.td,{children:"The employee's primary work email address."})]}),(0,t.jsxs)(r.tr,{children:[(0,t.jsx)(r.td,{children:(0,t.jsx)(r.code,{children:"jobTitle"})}),(0,t.jsx)(r.td,{children:(0,t.jsx)(r.code,{children:"string"})}),(0,t.jsx)(r.td,{children:"The employee's official job title."})]}),(0,t.jsxs)(r.tr,{children:[(0,t.jsx)(r.td,{children:(0,t.jsx)(r.code,{children:"department"})}),(0,t.jsx)(r.td,{children:(0,t.jsx)(r.code,{children:"string"})}),(0,t.jsx)(r.td,{children:"The department to which the employee belongs."})]}),(0,t.jsxs)(r.tr,{children:[(0,t.jsx)(r.td,{children:(0,t.jsx)(r.code,{children:"location"})}),(0,t.jsx)(r.td,{children:(0,t.jsx)(r.code,{children:"string"})}),(0,t.jsx)(r.td,{children:"The physical or regional location of the employee."})]}),(0,t.jsxs)(r.tr,{children:[(0,t.jsx)(r.td,{children:(0,t.jsx)(r.code,{children:"supervisorId"})}),(0,t.jsx)(r.td,{children:(0,t.jsx)(r.code,{children:"string"})}),(0,t.jsxs)(r.td,{children:["The unique ",(0,t.jsx)(r.code,{children:"id"})," of the employee's direct manager."]})]}),(0,t.jsxs)(r.tr,{children:[(0,t.jsx)(r.td,{children:(0,t.jsx)(r.code,{children:"hireDate"})}),(0,t.jsx)(r.td,{children:(0,t.jsx)(r.code,{children:"string"})}),(0,t.jsxs)(r.td,{children:["The date the employee was hired (ISO 8601: ",(0,t.jsx)(r.code,{children:"YYYY-MM-DD"}),")."]})]}),(0,t.jsxs)(r.tr,{children:[(0,t.jsx)(r.td,{children:(0,t.jsx)(r.code,{children:"mobilePhone"})}),(0,t.jsx)(r.td,{children:(0,t.jsx)(r.code,{children:"string"})}),(0,t.jsx)(r.td,{children:"The employee's mobile phone number (optional)."})]})]})]}),"\n",(0,t.jsx)(r.admonition,{type:"info",children:(0,t.jsxs)(r.p,{children:["If a field is not available in the source system, return ",(0,t.jsx)(r.code,{children:"None"})," or omit the key from the returned dictionary."]})}),"\n",(0,t.jsx)(r.h3,{id:"step-4-register-the-plugin",children:"Step 4: Register the Plugin"}),"\n",(0,t.jsx)(r.p,{children:"To make the provider discoverable by Solace Agent Mesh, it must be registered as a plugin via entry points."}),"\n",(0,t.jsxs)(r.p,{children:[(0,t.jsxs)(r.strong,{children:["1. Add an entry point in ",(0,t.jsx)(r.code,{children:"pyproject.toml"}),":"]}),"\nThe key assigned here (",(0,t.jsx)(r.code,{children:"corphr"}),") is used as the ",(0,t.jsx)(r.code,{children:"type"})," identifier in YAML configurations."]}),"\n",(0,t.jsx)(r.pre,{children:(0,t.jsx)(r.code,{className:"language-toml",children:'[project.entry-points."solace_agent_mesh.plugins"]\ncorphr = "my_corp_hr_provider:info"\n'})}),"\n",(0,t.jsxs)(r.p,{children:[(0,t.jsxs)(r.strong,{children:["2. Define the ",(0,t.jsx)(r.code,{children:"info"})," object in the plugin's ",(0,t.jsx)(r.code,{children:"__init__.py"}),":"]}),"\nThis object points to the provider's class path and provides a brief description."]}),"\n",(0,t.jsx)(r.pre,{children:(0,t.jsx)(r.code,{className:"language-python",children:'# my_corp_hr_provider/__init__.py\ninfo = {\n "class_path": "my_corp_hr_provider.provider.CorpHRProvider",\n "description": "Identity and People Service provider for CorpHR.",\n}\n'})}),"\n",(0,t.jsx)(r.h2,{id:"configuring-the-provider",children:"Configuring the Provider"}),"\n",(0,t.jsxs)(r.p,{children:["Once the plugin is created and installed (for example, via ",(0,t.jsx)(r.code,{children:"pip install ."}),"), it can be configured in any Gateway or Agent ",(0,t.jsx)(r.code,{children:"app_config.yml"}),"."]}),"\n",(0,t.jsx)(r.p,{children:(0,t.jsx)(r.strong,{children:"For a Gateway (Identity Service Role):"})}),"\n",(0,t.jsx)(r.pre,{children:(0,t.jsx)(r.code,{className:"language-yaml",children:'app_config:\n identity_service:\n type: "corphr" # Matches the key in pyproject.toml\n api_key: "${CORPHR_API_KEY}"\n lookup_key: "email" # The field from auth_claims to use for lookup\n'})}),"\n",(0,t.jsxs)(r.p,{children:[(0,t.jsx)(r.strong,{children:"For an Agent (Employee Service Role):"}),"\nThis example demonstrates configuring the provider for the ",(0,t.jsx)(r.code,{children:"employee_tools"})," group."]}),"\n",(0,t.jsx)(r.pre,{children:(0,t.jsx)(r.code,{className:"language-yaml",children:'app_config:\n tools:\n - tool_type: builtin-group\n group_name: "employee_tools"\n config:\n type: "corphr" # Same provider, different role\n api_key: "${CORPHR_API_KEY}"\n'})})]})}function h(e={}){const{wrapper:r}={...(0,s.R)(),...e.components};return r?(0,t.jsx)(r,{...e,children:(0,t.jsx)(l,{...e})}):l(e)}},8453:(e,r,n)=>{n.d(r,{R:()=>o,x:()=>d});var i=n(6540);const t={},s=i.createContext(t);function o(e){const r=i.useContext(s);return i.useMemo((function(){return"function"==typeof e?e(r):{...r,...e}}),[r,e])}function d(e){let r;return r=e.disableParentContext?"function"==typeof e.components?e.components(t):e.components||t:o(e.components),i.createElement(s.Provider,{value:r},e.children)}}}]);

solace_agent_mesh/assets/docs/assets/js/c835a94d.ce21f0bf.js DELETED Viewed

@@ -1 +0,0 @@

- "use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[6068],{5469:(e,t,s)=>{s.r(t),s.d(t,{assets:()=>d,contentTitle:()=>i,default:()=>x,frontMatter:()=>l,metadata:()=>n,toc:()=>c});const n=JSON.parse('{"id":"documentation/Migrations/A2A Upgrade To 0.3.0/a2a-technical-migration-map","title":"A2A Technical Migration Map","description":"This document provides a comprehensive, technical mapping for migrating Solace Agent Mesh components from the legacy A2A implementation to the new a2a-sdk-based protocol. It is designed to be used as a reference for automated or semi-automated code refactoring.","source":"@site/docs/documentation/Migrations/A2A Upgrade To 0.3.0/a2a-technical-migration-map.md","sourceDirName":"documentation/Migrations/A2A Upgrade To 0.3.0","slug":"/documentation/Migrations/A2A Upgrade To 0.3.0/a2a-technical-migration-map","permalink":"/solace-agent-mesh/docs/documentation/Migrations/A2A Upgrade To 0.3.0/a2a-technical-migration-map","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/Migrations/A2A Upgrade To 0.3.0/a2a-technical-migration-map.md","tags":[],"version":"current","frontMatter":{},"sidebar":"docSidebar","previous":{"title":"Solace Agent Mesh Gateway Migration Guide: Upgrading to the A2A SDK","permalink":"/solace-agent-mesh/docs/documentation/Migrations/A2A Upgrade To 0.3.0/a2a-gateway-upgrade-to-0.3.0"},"next":{"title":"Installation","permalink":"/solace-agent-mesh/docs/documentation/Enterprise/installation"}}');var r=s(4848),a=s(8453);const l={},i="A2A Technical Migration Map",d={},c=[{value:"1. Core Concept Changes",id:"1-core-concept-changes",level:2},{value:"2. Import & Type Mapping",id:"2-import--type-mapping",level:2},{value:"Import Paths",id:"import-paths",level:3},{value:"Type Hints",id:"type-hints",level:3},{value:"3. Object Creation & Property Access Mapping",id:"3-object-creation--property-access-mapping",level:2},{value:"4. Full Method Examples",id:"4-full-method-examples",level:2},{value:"Example 1: <code>_translate_external_input</code>",id:"example-1-_translate_external_input",level:3},{value:"Example 2: <code>_send_update_to_external</code>",id:"example-2-_send_update_to_external",level:3},{value:"Example 3: <code>_send_final_response_to_external</code>",id:"example-3-_send_final_response_to_external",level:3},{value:"Example 4: <code>_send_error_to_external</code>",id:"example-4-_send_error_to_external",level:3}];function o(e){const t={code:"code",h1:"h1",h2:"h2",h3:"h3",header:"header",li:"li",p:"p",pre:"pre",strong:"strong",table:"table",tbody:"tbody",td:"td",th:"th",thead:"thead",tr:"tr",ul:"ul",...(0,a.R)(),...e.components};return(0,r.jsxs)(r.Fragment,{children:[(0,r.jsx)(t.header,{children:(0,r.jsx)(t.h1,{id:"a2a-technical-migration-map",children:"A2A Technical Migration Map"})}),"\n",(0,r.jsxs)(t.p,{children:["This document provides a comprehensive, technical mapping for migrating Solace Agent Mesh components from the legacy A2A implementation to the new ",(0,r.jsx)(t.code,{children:"a2a-sdk"}),"-based protocol. It is designed to be used as a reference for automated or semi-automated code refactoring."]}),"\n",(0,r.jsx)(t.h2,{id:"1-core-concept-changes",children:"1. Core Concept Changes"}),"\n",(0,r.jsxs)(t.ul,{children:["\n",(0,r.jsxs)(t.li,{children:[(0,r.jsx)(t.strong,{children:"Session vs. Context:"})," The concept of a session, previously ",(0,r.jsx)(t.code,{children:"Task.sessionId"}),", is now attached to the ",(0,r.jsx)(t.code,{children:"Message"})," via ",(0,r.jsx)(t.code,{children:"Message.contextId"}),". The ",(0,r.jsx)(t.code,{children:"Task"})," also has a ",(0,r.jsx)(t.code,{children:"contextId"}),", but it's primarily for grouping. Code that relied on ",(0,r.jsx)(t.code,{children:"Task.sessionId"})," for conversation history must now use ",(0,r.jsx)(t.code,{children:"Message.contextId"}),"."]}),"\n",(0,r.jsxs)(t.li,{children:[(0,r.jsx)(t.strong,{children:"Request/Response Structure:"})," The structure of JSON-RPC requests and responses is now strictly defined by the SDK's Pydantic models (e.g., ",(0,r.jsx)(t.code,{children:"SendMessageRequest"}),", ",(0,r.jsx)(t.code,{children:"JSONRPCResponse"})," as a discriminated union). Direct dictionary manipulation is replaced by model instantiation and validation."]}),"\n",(0,r.jsxs)(t.li,{children:[(0,r.jsx)(t.strong,{children:"Status Signaling:"})," The practice of embedding custom status signals (e.g., ",(0,r.jsx)(t.code,{children:"tool_invocation_start"}),") in the ",(0,r.jsx)(t.code,{children:"metadata"})," field of a message is deprecated. The new standard is to use a dedicated, structured ",(0,r.jsx)(t.code,{children:"DataPart"})," within a multi-part ",(0,r.jsx)(t.code,{children:"Message"}),"."]}),"\n"]}),"\n",(0,r.jsx)(t.h2,{id:"2-import--type-mapping",children:"2. Import & Type Mapping"}),"\n",(0,r.jsx)(t.h3,{id:"import-paths",children:"Import Paths"}),"\n",(0,r.jsxs)(t.table,{children:[(0,r.jsx)(t.thead,{children:(0,r.jsxs)(t.tr,{children:[(0,r.jsx)(t.th,{style:{textAlign:"left"},children:"Old Import Path"}),(0,r.jsx)(t.th,{style:{textAlign:"left"},children:"New Import Path(s)"}),(0,r.jsx)(t.th,{style:{textAlign:"left"},children:"Notes"})]})}),(0,r.jsxs)(t.tbody,{children:[(0,r.jsxs)(t.tr,{children:[(0,r.jsx)(t.td,{style:{textAlign:"left"},children:(0,r.jsx)(t.code,{children:"solace_agent_mesh.common.types"})}),(0,r.jsxs)(t.td,{style:{textAlign:"left"},children:[(0,r.jsx)(t.code,{children:"a2a.types"}),", ",(0,r.jsx)(t.code,{children:"solace_agent_mesh.common.a2a"}),", ",(0,r.jsx)(t.code,{children:"solace_agent_mesh.common.a2a.types"})]}),(0,r.jsxs)(t.td,{style:{textAlign:"left"},children:["Legacy types are removed. Use SDK types and the ",(0,r.jsx)(t.code,{children:"a2a"})," helper layer."]})]}),(0,r.jsxs)(t.tr,{children:[(0,r.jsx)(t.td,{style:{textAlign:"left"},children:(0,r.jsx)(t.code,{children:"solace_agent_mesh.common.a2a_protocol"})}),(0,r.jsx)(t.td,{style:{textAlign:"left"},children:(0,r.jsx)(t.code,{children:"solace_agent_mesh.common.a2a"})}),(0,r.jsxs)(t.td,{style:{textAlign:"left"},children:["Protocol helpers (topic builders, etc.) are now in the main ",(0,r.jsx)(t.code,{children:"a2a"})," helper package."]})]})]})]}),"\n",(0,r.jsx)(t.h3,{id:"type-hints",children:"Type Hints"}),"\n",(0,r.jsxs)(t.table,{children:[(0,r.jsx)(t.thead,{children:(0,r.jsxs)(t.tr,{children:[(0,r.jsx)(t.th,{style:{textAlign:"left"},children:"Old Type Hint"}),(0,r.jsx)(t.th,{style:{textAlign:"left"},children:"New Type Hint"}),(0,r.jsx)(t.th,{style:{textAlign:"left"},children:"Notes"})]})}),(0,r.jsxs)(t.tbody,{children:[(0,r.jsxs)(t.tr,{children:[(0,r.jsx)(t.td,{style:{textAlign:"left"},children:(0,r.jsx)(t.code,{children:"A2APart"})}),(0,r.jsx)(t.td,{style:{textAlign:"left"},children:(0,r.jsx)(t.code,{children:"ContentPart"})}),(0,r.jsxs)(t.td,{style:{textAlign:"left"},children:[(0,r.jsx)(t.code,{children:"ContentPart"})," is an alias for ",(0,r.jsx)(t.code,{children:"Union[TextPart, DataPart, FilePart]"}),"."]})]}),(0,r.jsxs)(t.tr,{children:[(0,r.jsx)(t.td,{style:{textAlign:"left"},children:(0,r.jsx)(t.code,{children:"List[A2APart]"})}),(0,r.jsx)(t.td,{style:{textAlign:"left"},children:(0,r.jsx)(t.code,{children:"List[ContentPart]"})}),(0,r.jsx)(t.td,{style:{textAlign:"left"},children:"Standard type hint for a list of message parts."})]}),(0,r.jsxs)(t.tr,{children:[(0,r.jsx)(t.td,{style:{textAlign:"left"},children:(0,r.jsx)(t.code,{children:"FileContent"})}),(0,r.jsx)(t.td,{style:{textAlign:"left"},children:(0,r.jsx)(t.code,{children:"Union[FileWithBytes, FileWithUri]"})}),(0,r.jsxs)(t.td,{style:{textAlign:"left"},children:["The ",(0,r.jsx)(t.code,{children:"file"})," attribute of a ",(0,r.jsx)(t.code,{children:"FilePart"})," is now a discriminated union."]})]})]})]}),"\n",(0,r.jsx)(t.h2,{id:"3-object-creation--property-access-mapping",children:"3. Object Creation & Property Access Mapping"}),"\n",(0,r.jsxs)(t.p,{children:["This table maps common legacy patterns to their new equivalents using the ",(0,r.jsx)(t.code,{children:"a2a"})," helper layer."]}),"\n",(0,r.jsxs)(t.table,{children:[(0,r.jsx)(t.thead,{children:(0,r.jsxs)(t.tr,{children:[(0,r.jsx)(t.th,{style:{textAlign:"left"},children:"Action"}),(0,r.jsx)(t.th,{style:{textAlign:"left"},children:"Old Pattern (Legacy)"}),(0,r.jsx)(t.th,{style:{textAlign:"left"},children:"New Pattern (a2a-sdk + Helpers)"})]})}),(0,r.jsxs)(t.tbody,{children:[(0,r.jsxs)(t.tr,{children:[(0,r.jsx)(t.td,{style:{textAlign:"left"},children:(0,r.jsx)(t.strong,{children:"Part Creation"})}),(0,r.jsx)(t.td,{style:{textAlign:"left"}}),(0,r.jsx)(t.td,{style:{textAlign:"left"}})]}),(0,r.jsxs)(t.tr,{children:[(0,r.jsx)(t.td,{style:{textAlign:"left"},children:"Create Text Part"}),(0,r.jsx)(t.td,{style:{textAlign:"left"},children:(0,r.jsx)(t.code,{children:"TextPart(text=...)"})}),(0,r.jsx)(t.td,{style:{textAlign:"left"},children:(0,r.jsx)(t.code,{children:"a2a.create_text_part(text=...)"})})]}),(0,r.jsxs)(t.tr,{children:[(0,r.jsx)(t.td,{style:{textAlign:"left"},children:"Create File Part (URI)"}),(0,r.jsx)(t.td,{style:{textAlign:"left"},children:(0,r.jsx)(t.code,{children:"FilePart(file=FileContent(name=..., uri=...))"})}),(0,r.jsx)(t.td,{style:{textAlign:"left"},children:(0,r.jsx)(t.code,{children:"a2a.create_file_part_from_uri(uri=..., name=...)"})})]}),(0,r.jsxs)(t.tr,{children:[(0,r.jsx)(t.td,{style:{textAlign:"left"},children:"Create File Part (Bytes)"}),(0,r.jsx)(t.td,{style:{textAlign:"left"},children:(0,r.jsx)(t.code,{children:"FilePart(file=FileContent(bytes=...))"})}),(0,r.jsx)(t.td,{style:{textAlign:"left"},children:(0,r.jsx)(t.code,{children:"a2a.create_file_part_from_bytes(content_bytes=...)"})})]}),(0,r.jsxs)(t.tr,{children:[(0,r.jsx)(t.td,{style:{textAlign:"left"},children:"Create Data Part"}),(0,r.jsx)(t.td,{style:{textAlign:"left"},children:(0,r.jsx)(t.code,{children:"DataPart(data=...)"})}),(0,r.jsx)(t.td,{style:{textAlign:"left"},children:(0,r.jsx)(t.code,{children:"a2a.create_data_part(data=...)"})})]}),(0,r.jsxs)(t.tr,{children:[(0,r.jsx)(t.td,{style:{textAlign:"left"},children:(0,r.jsx)(t.strong,{children:"Task/Event Access"})}),(0,r.jsx)(t.td,{style:{textAlign:"left"}}),(0,r.jsx)(t.td,{style:{textAlign:"left"}})]}),(0,r.jsxs)(t.tr,{children:[(0,r.jsx)(t.td,{style:{textAlign:"left"},children:"Get Task ID"}),(0,r.jsx)(t.td,{style:{textAlign:"left"},children:(0,r.jsx)(t.code,{children:"task.id"})}),(0,r.jsx)(t.td,{style:{textAlign:"left"},children:(0,r.jsx)(t.code,{children:"a2a.get_task_id(task)"})})]}),(0,r.jsxs)(t.tr,{children:[(0,r.jsx)(t.td,{style:{textAlign:"left"},children:"Get Task Status"}),(0,r.jsx)(t.td,{style:{textAlign:"left"},children:(0,r.jsx)(t.code,{children:"task.status.state"})}),(0,r.jsx)(t.td,{style:{textAlign:"left"},children:(0,r.jsx)(t.code,{children:"a2a.get_task_status(task)"})})]}),(0,r.jsxs)(t.tr,{children:[(0,r.jsx)(t.td,{style:{textAlign:"left"},children:"Get Task Context ID"}),(0,r.jsx)(t.td,{style:{textAlign:"left"},children:(0,r.jsx)(t.code,{children:"task.sessionId"})}),(0,r.jsx)(t.td,{style:{textAlign:"left"},children:(0,r.jsx)(t.code,{children:"a2a.get_task_context_id(task)"})})]}),(0,r.jsxs)(t.tr,{children:[(0,r.jsx)(t.td,{style:{textAlign:"left"},children:"Get Event's Task ID"}),(0,r.jsx)(t.td,{style:{textAlign:"left"},children:(0,r.jsx)(t.code,{children:"event.id"})}),(0,r.jsx)(t.td,{style:{textAlign:"left"},children:(0,r.jsx)(t.code,{children:"event.task_id"})})]}),(0,r.jsxs)(t.tr,{children:[(0,r.jsx)(t.td,{style:{textAlign:"left"},children:(0,r.jsx)(t.strong,{children:"Message Access"})}),(0,r.jsx)(t.td,{style:{textAlign:"left"}}),(0,r.jsx)(t.td,{style:{textAlign:"left"}})]}),(0,r.jsxs)(t.tr,{children:[(0,r.jsx)(t.td,{style:{textAlign:"left"},children:"Get Message Parts"}),(0,r.jsx)(t.td,{style:{textAlign:"left"},children:(0,r.jsx)(t.code,{children:"message.parts"})}),(0,r.jsx)(t.td,{style:{textAlign:"left"},children:(0,r.jsx)(t.code,{children:"a2a.get_parts_from_message(message)"})})]}),(0,r.jsxs)(t.tr,{children:[(0,r.jsx)(t.td,{style:{textAlign:"left"},children:"Get Text from Message"}),(0,r.jsx)(t.td,{style:{textAlign:"left"},children:"(manual loop over parts)"}),(0,r.jsx)(t.td,{style:{textAlign:"left"},children:(0,r.jsx)(t.code,{children:"a2a.get_text_from_message(message)"})})]}),(0,r.jsxs)(t.tr,{children:[(0,r.jsx)(t.td,{style:{textAlign:"left"},children:"Get Data Parts"}),(0,r.jsx)(t.td,{style:{textAlign:"left"},children:"(manual loop over parts)"}),(0,r.jsx)(t.td,{style:{textAlign:"left"},children:(0,r.jsx)(t.code,{children:"a2a.get_data_parts_from_message(message)"})})]}),(0,r.jsxs)(t.tr,{children:[(0,r.jsx)(t.td,{style:{textAlign:"left"},children:(0,r.jsx)(t.strong,{children:"Error Access"})}),(0,r.jsx)(t.td,{style:{textAlign:"left"}}),(0,r.jsx)(t.td,{style:{textAlign:"left"}})]}),(0,r.jsxs)(t.tr,{children:[(0,r.jsx)(t.td,{style:{textAlign:"left"},children:"Get Error Message"}),(0,r.jsx)(t.td,{style:{textAlign:"left"},children:(0,r.jsx)(t.code,{children:"error.message"})}),(0,r.jsx)(t.td,{style:{textAlign:"left"},children:(0,r.jsx)(t.code,{children:"a2a.get_error_message(error)"})})]}),(0,r.jsxs)(t.tr,{children:[(0,r.jsx)(t.td,{style:{textAlign:"left"},children:"Get Error Code"}),(0,r.jsx)(t.td,{style:{textAlign:"left"},children:(0,r.jsx)(t.code,{children:"error.code"})}),(0,r.jsx)(t.td,{style:{textAlign:"left"},children:(0,r.jsx)(t.code,{children:"a2a.get_error_code(error)"})})]}),(0,r.jsxs)(t.tr,{children:[(0,r.jsx)(t.td,{style:{textAlign:"left"},children:"Get Error Data"}),(0,r.jsx)(t.td,{style:{textAlign:"left"},children:(0,r.jsx)(t.code,{children:"error.data"})}),(0,r.jsx)(t.td,{style:{textAlign:"left"},children:(0,r.jsx)(t.code,{children:"a2a.get_error_data(error)"})})]}),(0,r.jsxs)(t.tr,{children:[(0,r.jsx)(t.td,{style:{textAlign:"left"},children:(0,r.jsx)(t.strong,{children:"Protocol/RPC"})}),(0,r.jsx)(t.td,{style:{textAlign:"left"}}),(0,r.jsx)(t.td,{style:{textAlign:"left"}})]}),(0,r.jsxs)(t.tr,{children:[(0,r.jsx)(t.td,{style:{textAlign:"left"},children:"Create RPC Success"}),(0,r.jsx)(t.td,{style:{textAlign:"left"},children:(0,r.jsx)(t.code,{children:"JSONRPCResponse(id=..., result=...)"})}),(0,r.jsx)(t.td,{style:{textAlign:"left"},children:(0,r.jsx)(t.code,{children:"a2a.create_success_response(result=..., request_id=...)"})})]}),(0,r.jsxs)(t.tr,{children:[(0,r.jsx)(t.td,{style:{textAlign:"left"},children:"Create RPC Error"}),(0,r.jsx)(t.td,{style:{textAlign:"left"},children:(0,r.jsx)(t.code,{children:"JSONRPCResponse(id=..., error=...)"})}),(0,r.jsx)(t.td,{style:{textAlign:"left"},children:(0,r.jsx)(t.code,{children:"a2a.create_error_response(error=..., request_id=...)"})})]}),(0,r.jsxs)(t.tr,{children:[(0,r.jsx)(t.td,{style:{textAlign:"left"},children:"Validate RPC Payload"}),(0,r.jsx)(t.td,{style:{textAlign:"left"},children:(0,r.jsx)(t.code,{children:"JSONRPCResponse(**payload)"})}),(0,r.jsx)(t.td,{style:{textAlign:"left"},children:(0,r.jsx)(t.code,{children:"JSONRPCResponse.model_validate(payload)"})})]}),(0,r.jsxs)(t.tr,{children:[(0,r.jsx)(t.td,{style:{textAlign:"left"},children:"Topic Matching"}),(0,r.jsx)(t.td,{style:{textAlign:"left"},children:(0,r.jsx)(t.code,{children:"_topic_matches_subscription(...)"})}),(0,r.jsx)(t.td,{style:{textAlign:"left"},children:(0,r.jsx)(t.code,{children:"a2a.topic_matches_subscription(...)"})})]}),(0,r.jsxs)(t.tr,{children:[(0,r.jsx)(t.td,{style:{textAlign:"left"},children:"Extract Task ID from Topic"}),(0,r.jsx)(t.td,{style:{textAlign:"left"},children:(0,r.jsx)(t.code,{children:"_extract_task_id_from_topic(...)"})}),(0,r.jsx)(t.td,{style:{textAlign:"left"},children:(0,r.jsx)(t.code,{children:"a2a.extract_task_id_from_topic(...)"})})]})]})]}),"\n",(0,r.jsx)(t.h2,{id:"4-full-method-examples",children:"4. Full Method Examples"}),"\n",(0,r.jsx)(t.p,{children:'These examples provide larger, "before and after" contexts for the refactoring patterns.'}),"\n",(0,r.jsxs)(t.h3,{id:"example-1-_translate_external_input",children:["Example 1: ",(0,r.jsx)(t.code,{children:"_translate_external_input"})]}),"\n",(0,r.jsx)(t.p,{children:(0,r.jsx)(t.strong,{children:"Before:"})}),"\n",(0,r.jsx)(t.pre,{children:(0,r.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 artifact_uri = f"artifact://{self.gateway_id}/{user_id}/{a2a_session_id}/{filename}?version={version}"\n file_content_a2a = FileContent(name=filename, mimeType=mime_type, uri=artifact_uri)\n a2a_parts.append(FilePart(file=file_content_a2a))\n # ...\n a2a_parts.append(TextPart(text=processed_text_for_a2a))\n return "agent_name", a2a_parts, {}\n'})}),"\n",(0,r.jsx)(t.p,{children:(0,r.jsx)(t.strong,{children:"After:"})}),"\n",(0,r.jsx)(t.pre,{children:(0,r.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 artifact_uri = f"artifact://{self.gateway_id}/{user_id}/{a2a_session_id}/{filename}?version={version}"\n file_part = a2a.create_file_part_from_uri(uri=artifact_uri, name=filename, mime_type=mime_type)\n a2a_parts.append(file_part)\n # ...\n text_part = a2a.create_text_part(text=processed_text_for_a2a)\n a2a_parts.append(text_part)\n return "agent_name", a2a_parts, {}\n'})}),"\n",(0,r.jsxs)(t.h3,{id:"example-2-_send_update_to_external",children:["Example 2: ",(0,r.jsx)(t.code,{children:"_send_update_to_external"})]}),"\n",(0,r.jsx)(t.p,{children:(0,r.jsx)(t.strong,{children:"Before:"})}),"\n",(0,r.jsx)(t.pre,{children:(0,r.jsx)(t.code,{className:"language-python",children:"from solace_agent_mesh.common.types import TaskStatusUpdateEvent, TextPart, DataPart\n\nasync def _send_update_to_external(self, context: Dict, event_data: TaskStatusUpdateEvent, is_final: bool) -> None:\n task_id = event_data.id\n # ...\n if event_data.status and event_data.status.message and event_data.status.message.parts:\n for part in event_data.status.message.parts:\n if isinstance(part, TextPart):\n # process part.text\n elif isinstance(part, DataPart):\n # process part.data\n"})}),"\n",(0,r.jsx)(t.p,{children:(0,r.jsx)(t.strong,{children:"After:"})}),"\n",(0,r.jsx)(t.pre,{children:(0,r.jsx)(t.code,{className:"language-python",children:"from a2a.types import TaskStatusUpdateEvent, TextPart, DataPart\nfrom solace_agent_mesh.common import a2a\n\nasync def _send_update_to_external(self, context: Dict, event_data: TaskStatusUpdateEvent, is_final: bool) -> None:\n task_id = event_data.task_id\n # ...\n message = a2a.get_message_from_status_update(event_data)\n if message:\n parts = a2a.get_parts_from_message(message)\n for part in parts:\n if isinstance(part, TextPart):\n # process part.text\n elif isinstance(part, DataPart):\n # process part.data\n"})}),"\n",(0,r.jsxs)(t.h3,{id:"example-3-_send_final_response_to_external",children:["Example 3: ",(0,r.jsx)(t.code,{children:"_send_final_response_to_external"})]}),"\n",(0,r.jsx)(t.p,{children:(0,r.jsx)(t.strong,{children:"Before:"})}),"\n",(0,r.jsx)(t.pre,{children:(0,r.jsx)(t.code,{className:"language-python",children:"from solace_agent_mesh.common.types import Task, TaskState\n\nasync def _send_final_response_to_external(self, context: Dict, task_data: Task) -> None:\n task_id = task_data.id\n if task_data.status.state == TaskState.FAILED:\n # ...\n"})}),"\n",(0,r.jsx)(t.p,{children:(0,r.jsx)(t.strong,{children:"After:"})}),"\n",(0,r.jsx)(t.pre,{children:(0,r.jsx)(t.code,{className:"language-python",children:"from a2a.types import Task, TaskState\nfrom solace_agent_mesh.common import a2a\n\nasync def _send_final_response_to_external(self, context: Dict, task_data: Task) -> None:\n task_id = a2a.get_task_id(task_data)\n task_status = a2a.get_task_status(task_data)\n if task_status == TaskState.failed:\n # ...\n"})}),"\n",(0,r.jsxs)(t.h3,{id:"example-4-_send_error_to_external",children:["Example 4: ",(0,r.jsx)(t.code,{children:"_send_error_to_external"})]}),"\n",(0,r.jsx)(t.p,{children:(0,r.jsx)(t.strong,{children:"Before:"})}),"\n",(0,r.jsx)(t.pre,{children:(0,r.jsx)(t.code,{className:"language-python",children:'from solace_agent_mesh.common.types import JSONRPCError\n\nasync def _send_error_to_external(self, context: Dict, error_data: JSONRPCError) -> None:\n error_text = f"Error: {error_data.message} (Code: {error_data.code})"\n if error_data.data:\n # process error_data.data\n'})}),"\n",(0,r.jsx)(t.p,{children:(0,r.jsx)(t.strong,{children:"After:"})}),"\n",(0,r.jsx)(t.pre,{children:(0,r.jsx)(t.code,{className:"language-python",children:'from a2a.types import JSONRPCError\nfrom solace_agent_mesh.common import a2a\n\nasync def _send_error_to_external(self, context: Dict, error_data: JSONRPCError) -> None:\n error_message = a2a.get_error_message(error_data)\n error_code = a2a.get_error_code(error_data)\n error_details = a2a.get_error_data(error_data)\n error_text = f"Error: {error_message} (Code: {error_code})"\n if error_details:\n # process error_details\n'})})]})}function x(e={}){const{wrapper:t}={...(0,a.R)(),...e.components};return t?(0,r.jsx)(t,{...e,children:(0,r.jsx)(o,{...e})}):o(e)}},8453:(e,t,s)=>{s.d(t,{R:()=>l,x:()=>i});var n=s(6540);const r={},a=n.createContext(r);function l(e){const t=n.useContext(a);return n.useMemo((function(){return"function"==typeof e?e(t):{...t,...e}}),[t,e])}function i(e){let t;return t=e.disableParentContext?"function"==typeof e.components?e.components(r):e.components||r:l(e.components),n.createElement(a.Provider,{value:t},e.children)}}}]);

solace_agent_mesh/assets/docs/assets/js/cc969b05.feef7dcc.js DELETED Viewed

@@ -1 +0,0 @@

- "use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[2476],{9955:(e,n,t)=>{t.r(n),t.d(n,{assets:()=>l,contentTitle:()=>r,default:()=>h,frontMatter:()=>i,metadata:()=>o,toc:()=>c});const o=JSON.parse('{"id":"documentation/tutorials/mongodb-integration","title":"MongoDB Integration","description":"This tutorial sets up a MongoDB agent in Solace Agent Mesh, which allows the Solace Agent Mesh agent to answer natural language queries about a Mongo database. The agent translates user questions into MongoDB aggregation pipelines and executes them against your database.","source":"@site/docs/documentation/tutorials/mongodb-integration.md","sourceDirName":"documentation/tutorials","slug":"/documentation/tutorials/mongodb-integration","permalink":"/solace-agent-mesh/docs/documentation/tutorials/mongodb-integration","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/tutorials/mongodb-integration.md","tags":[],"version":"current","sidebarPosition":50,"frontMatter":{"title":"MongoDB Integration","sidebar_position":50},"sidebar":"docSidebar","previous":{"title":"SQL Database Integration","permalink":"/solace-agent-mesh/docs/documentation/tutorials/sql-database"},"next":{"title":"Slack Integration","permalink":"/solace-agent-mesh/docs/documentation/tutorials/slack-integration"}}');var s=t(4848),a=t(8453);const i={title:"MongoDB Integration",sidebar_position:50},r="MongoDB Integration",l={},c=[{value:"Prerequisites",id:"prerequisites",level:2},{value:"Adding the MongoDB Plugin",id:"adding-the-mongodb-plugin",level:2},{value:"Setting Up Your MongoDB Database",id:"setting-up-your-mongodb-database",level:4},{value:"Example Document Structure",id:"example-document-structure",level:4},{value:"Configuring the Agent",id:"configuring-the-agent",level:2},{value:"Setting the Environment Variables",id:"setting-the-environment-variables",level:4},{value:"MongoDB Connection Options",id:"mongodb-connection-options",level:4},{value:"Running the Agent",id:"running-the-agent",level:2},{value:"Interacting with the Database",id:"interacting-with-the-database",level:2},{value:"Advanced Configuration",id:"advanced-configuration",level:2},{value:"Customizing the Agent Card",id:"customizing-the-agent-card",level:2},{value:"Key Agent Card Elements",id:"key-agent-card-elements",level:3},{value:"Example of a Well-Configured Agent Card",id:"example-of-a-well-configured-agent-card",level:3},{value:"MongoDB Query Features",id:"mongodb-query-features",level:2},{value:"Aggregation Queries",id:"aggregation-queries",level:3},{value:"Filtering and Search",id:"filtering-and-search",level:3},{value:"Complex Analytics",id:"complex-analytics",level:3},{value:"Output Formats",id:"output-formats",level:3},{value:"Troubleshooting",id:"troubleshooting",level:2},{value:"Common Issues and Solutions",id:"common-issues-and-solutions",level:3},{value:"Connection Errors",id:"connection-errors",level:4},{value:"Authentication Errors",id:"authentication-errors",level:4},{value:"Query Errors",id:"query-errors",level:4},{value:"Schema Detection Issues",id:"schema-detection-issues",level:4}];function d(e){const n={a:"a",code:"code",h1:"h1",h2:"h2",h3:"h3",h4:"h4",header:"header",li:"li",ol:"ol",p:"p",pre:"pre",strong:"strong",ul:"ul",...(0,a.R)(),...e.components};return(0,s.jsxs)(s.Fragment,{children:[(0,s.jsx)(n.header,{children:(0,s.jsx)(n.h1,{id:"mongodb-integration",children:"MongoDB Integration"})}),"\n",(0,s.jsx)(n.p,{children:"This tutorial sets up a MongoDB agent in Solace Agent Mesh, which allows the Solace Agent Mesh agent to answer natural language queries about a Mongo database. The agent translates user questions into MongoDB aggregation pipelines and executes them against your database."}),"\n",(0,s.jsx)(n.h2,{id:"prerequisites",children:"Prerequisites"}),"\n",(0,s.jsx)(n.p,{children:"Before starting this tutorial, ensure that you have installed and configured Solace Agent Mesh:"}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsx)(n.li,{children:(0,s.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/getting-started/installation",children:"Installed Solace Agent Mesh and the Solace Agent Mesh CLI"})}),"\n",(0,s.jsx)(n.li,{children:(0,s.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/getting-started/quick-start",children:"Created a new Solace Agent Mesh project"})}),"\n",(0,s.jsx)(n.li,{children:"Access to a MongoDB database (local or remote)"}),"\n"]}),"\n",(0,s.jsx)(n.h2,{id:"adding-the-mongodb-plugin",children:"Adding the MongoDB Plugin"}),"\n",(0,s.jsx)(n.p,{children:"Add the MongoDB plugin to your Solace Agent Mesh project:"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-sh",children:"sam plugin add coffee-shop-mongo --plugin sam-mongodb\n"})}),"\n",(0,s.jsxs)(n.p,{children:["You can use any name for your agent, in this tutorial we use ",(0,s.jsx)(n.code,{children:"coffee-shop-mongo"}),"."]}),"\n",(0,s.jsx)(n.p,{children:"This command:"}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:["Installs the ",(0,s.jsx)(n.code,{children:"sam-mongodb"})," plugin"]}),"\n",(0,s.jsxs)(n.li,{children:["Creates a new agent configuration file at ",(0,s.jsx)(n.code,{children:"configs/agents/coffee-shop-mongo.yaml"})]}),"\n"]}),"\n",(0,s.jsx)(n.h4,{id:"setting-up-your-mongodb-database",children:"Setting Up Your MongoDB Database"}),"\n",(0,s.jsx)(n.p,{children:"This tutorial assumes you have a MongoDB database with a collection containing coffee shop data. You can use any MongoDB database, but here is an example structure for a coffee shop:"}),"\n",(0,s.jsx)(n.h4,{id:"example-document-structure",children:"Example Document Structure"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-json",children:'{\n "_id": "64a1b2c3d4e5f6789012345",\n "order_id": "ORD-2024-001",\n "customer": {\n "name": "John Doe",\n "email": "john.doe@example.com",\n "phone": "+1-555-0123"\n },\n "items": [\n {\n "product": "Espresso",\n "quantity": 2,\n "price": 3.50,\n "category": "Coffee"\n },\n {\n "product": "Croissant",\n "quantity": 1,\n "price": 2.75,\n "category": "Pastry"\n }\n ],\n "total_amount": 9.75,\n "order_date": "2024-01-15T10:30:00Z",\n "status": "completed",\n "payment_method": "credit_card",\n "location": "Downtown Store"\n}\n'})}),"\n",(0,s.jsx)(n.h2,{id:"configuring-the-agent",children:"Configuring the Agent"}),"\n",(0,s.jsxs)(n.p,{children:["Open the ",(0,s.jsx)(n.code,{children:"configs/agents/coffee-shop-mongo.yaml"})," file and modify the ",(0,s.jsx)(n.code,{children:"agent_init_function.config"})," section to connect to your MongoDB database."]}),"\n",(0,s.jsx)(n.p,{children:"Here is what you need to modify in the configuration file:"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-yaml",children:'# Find the agent_init_function section and update the config:\nagent_init_function:\n module: "sam_mongodb.lifecycle"\n name: "initialize_mongo_agent"\n config:\n db_host: "${COFFEE_SHOP_MONGO_MONGO_HOST}"\n db_port: ${COFFEE_SHOP_MONGO_MONGO_PORT}\n db_user: "${COFFEE_SHOP_MONGO_MONGO_USER}"\n db_password: "${COFFEE_SHOP_MONGO_MONGO_PASSWORD}"\n db_name: "${COFFEE_SHOP_MONGO_MONGO_DB}"\n database_collection: "${COFFEE_SHOP_MONGO_MONGO_COLLECTION}"\n database_purpose: "${COFFEE_SHOP_MONGO_DB_PURPOSE}"\n data_description: "${COFFEE_SHOP_MONGO_DB_DESCRIPTION}"\n auto_detect_schema: true\n max_inline_results: 10\n'})}),"\n",(0,s.jsx)(n.h4,{id:"setting-the-environment-variables",children:"Setting the Environment Variables"}),"\n",(0,s.jsxs)(n.p,{children:["The MongoDB agent requires several environment variables. Create or update your ",(0,s.jsx)(n.code,{children:".env"})," file with the following variables:"]}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-bash",children:'# MongoDB Connection Settings\nCOFFEE_SHOP_MONGO_MONGO_HOST=localhost\nCOFFEE_SHOP_MONGO_MONGO_PORT=27017\nCOFFEE_SHOP_MONGO_MONGO_USER=your_username\nCOFFEE_SHOP_MONGO_MONGO_PASSWORD=your_password\nCOFFEE_SHOP_MONGO_MONGO_DB=coffee_shop\nCOFFEE_SHOP_MONGO_MONGO_COLLECTION=orders\n\n# Database Description\nCOFFEE_SHOP_MONGO_DB_PURPOSE="Coffee shop order management database"\nCOFFEE_SHOP_MONGO_DB_DESCRIPTION="Contains customer orders, product information, sales data, and transaction history for a coffee shop business."\n\n# Optional Settings\nAUTO_DETECT_SCHEMA=true\nMAX_INLINE_RESULTS=10\n'})}),"\n",(0,s.jsx)(n.h4,{id:"mongodb-connection-options",children:"MongoDB Connection Options"}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Local MongoDB"}),": Use ",(0,s.jsx)(n.code,{children:"localhost"})," as the host and default port ",(0,s.jsx)(n.code,{children:"27017"})]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"MongoDB Atlas"}),": Use your Atlas connection string format"]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Authentication"}),": Provide username and password if your MongoDB requires authentication"]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"No Authentication"}),": Leave username and password empty for local development databases"]}),"\n"]}),"\n",(0,s.jsx)(n.h2,{id:"running-the-agent",children:"Running the Agent"}),"\n",(0,s.jsx)(n.p,{children:"Now you can start your MongoDB agent:"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-sh",children:"sam run configs/agents/coffee-shop-mongo.yaml\n"})}),"\n",(0,s.jsx)(n.p,{children:"The agent:"}),"\n",(0,s.jsxs)(n.ol,{children:["\n",(0,s.jsx)(n.li,{children:"Connects to the A2A control plane"}),"\n",(0,s.jsx)(n.li,{children:"Initializes the MongoDB connection"}),"\n",(0,s.jsx)(n.li,{children:"Detects the database schema automatically"}),"\n",(0,s.jsx)(n.li,{children:"Registers its capabilities with the agent discovery system"}),"\n"]}),"\n",(0,s.jsx)(n.h2,{id:"interacting-with-the-database",children:"Interacting with the Database"}),"\n",(0,s.jsxs)(n.p,{children:["After your MongoDB agent is running, you can interact with the database through any gateway in your Solace Agent Mesh project (such as the Web UI gateway at ",(0,s.jsx)(n.code,{children:"http://localhost:8000"}),")."]}),"\n",(0,s.jsx)(n.p,{children:"You can ask natural language questions about your MongoDB database, such as:"}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsx)(n.li,{children:'"How many orders were placed today?"'}),"\n",(0,s.jsx)(n.li,{children:'"What are the most popular coffee products?"'}),"\n",(0,s.jsx)(n.li,{children:'"Show me all orders from customers in New York"'}),"\n",(0,s.jsx)(n.li,{children:'"What\'s the average order value this month?"'}),"\n",(0,s.jsx)(n.li,{children:'"Find all incomplete orders"'}),"\n",(0,s.jsx)(n.li,{children:'"Group orders by payment method and show totals"'}),"\n"]}),"\n",(0,s.jsx)(n.p,{children:"Try creating reports by asking questions such as:"}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsx)(n.li,{children:'"Create a sales report for the last 7 days"'}),"\n",(0,s.jsx)(n.li,{children:'"Generate a summary of customer preferences"'}),"\n",(0,s.jsx)(n.li,{children:'"Show me the top 10 customers by total spending"'}),"\n"]}),"\n",(0,s.jsx)(n.p,{children:"The MongoDB agent converts your natural language questions into MongoDB aggregation pipelines, executes them against the database, and returns the results. For large result sets, the agent automatically saves the results as artifacts that you can download."}),"\n",(0,s.jsx)(n.h2,{id:"advanced-configuration",children:"Advanced Configuration"}),"\n",(0,s.jsx)(n.p,{children:"The MongoDB plugin supports many advanced configuration options. Here is a complete example based on the plugin structure:"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-yaml",children:'log:\n stdout_log_level: INFO\n log_file_level: DEBUG\n log_file: coffee-shop-mongo.log\n\n!include ../shared_config.yaml\n\napps:\n - name: coffee-shop-mongo-app\n app_module: solace_agent_mesh.agent.sac.app \n broker:\n <<: *broker_connection\n\n app_config:\n namespace: ${NAMESPACE}\n agent_name: "CoffeeShopMongo"\n display_name: "Coffee Shop MongoDB Agent"\n supports_streaming: false\n model: *general_model\n\n instruction: |\n You are an expert MongoDB assistant for the coffee shop database.\n Your primary goal is to translate user questions into accurate MongoDB aggregation pipelines.\n When asked to query the database, generate the pipeline and call the query tool.\n If the tool returns an error, analyze the error message and the original pipeline,\n then try to correct the pipeline and call the tool again.\n Always provide clear explanations of the results you find.\n\n # Agent initialization with database setup\n agent_init_function:\n module: "sam_mongodb.lifecycle"\n name: "initialize_mongo_agent"\n config:\n db_host: "${COFFEE_SHOP_MONGO_MONGO_HOST}"\n db_port: ${COFFEE_SHOP_MONGO_MONGO_PORT}\n db_user: "${COFFEE_SHOP_MONGO_MONGO_USER}"\n db_password: "${COFFEE_SHOP_MONGO_MONGO_PASSWORD}"\n db_name: "${COFFEE_SHOP_MONGO_MONGO_DB}"\n database_collection: "${COFFEE_SHOP_MONGO_MONGO_COLLECTION}"\n database_purpose: "${COFFEE_SHOP_MONGO_DB_PURPOSE}"\n data_description: "${COFFEE_SHOP_MONGO_DB_DESCRIPTION}"\n auto_detect_schema: true\n max_inline_results: 10\n\n agent_cleanup_function:\n module: "sam_mongodb.lifecycle"\n name: "cleanup_mongo_agent_resources"\n\n # MongoDB query tool\n tools:\n - tool_type: builtin-group\n group_name: "artifact_management"\n - tool_type: builtin-group\n group_name: "data_analysis"\n - tool_type: python\n component_module: "sam_mongodb.search_query"\n function_name: "mongo_query"\n tool_config:\n collection: "${COFFEE_SHOP_MONGO_MONGO_COLLECTION}"\n\n session_service: *default_session_service\n artifact_service: *default_artifact_service\n\n # Artifact handling\n artifact_handling_mode: "reference"\n enable_embed_resolution: true\n enable_artifact_content_instruction: true\n\n # Agent capabilities - This is what other agents see during discovery\n agent_card:\n description: "Coffee Shop MongoDB Agent - Access to comprehensive coffee shop order data including customer information, product details, sales transactions, and order history. Can answer questions about sales analytics, customer behavior, product performance, and business metrics."\n defaultInputModes: ["text"]\n defaultOutputModes: ["text", "file"]\n skills:\n - id: "mongo_query"\n name: "Coffee Shop MongoDB Query"\n description: "Queries coffee shop MongoDB database containing customer orders, product catalog, payment transactions, and order history using aggregation pipelines."\n\n # A2A Protocol settings\n agent_card_publishing: { interval_seconds: 30 }\n agent_discovery: { enabled: true }\n inter_agent_communication:\n allow_list: ["*"]\n request_timeout_seconds: 60\n'})}),"\n",(0,s.jsx)(n.h2,{id:"customizing-the-agent-card",children:"Customizing the Agent Card"}),"\n",(0,s.jsxs)(n.p,{children:["The ",(0,s.jsx)(n.code,{children:"agent_card"})," section is crucial as it defines how other agents in your Solace Agent Mesh ecosystem discover and understand this MongoDB agent's capabilities. When other agents use agent discovery, they can see this information to decide whether to delegate tasks to your database agent."]}),"\n",(0,s.jsx)(n.h3,{id:"key-agent-card-elements",children:"Key Agent Card Elements"}),"\n",(0,s.jsxs)(n.ol,{children:["\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Description"}),": Clearly describe what data the agent has access to and what types of questions it can answer"]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Skills"}),": List specific capabilities with concrete examples that show the scope of data available"]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Data Context"}),": Mention the business domain, data types, and scope of information available"]}),"\n"]}),"\n",(0,s.jsx)(n.h3,{id:"example-of-a-well-configured-agent-card",children:"Example of a Well-Configured Agent Card"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-yaml",children:'agent_card:\n description: "Coffee Shop MongoDB Agent - Access to comprehensive coffee shop order data including customer information, product details, sales transactions, and order history. Can answer questions about sales analytics, customer behavior, product performance, and business metrics."\n defaultInputModes: ["text"]\n defaultOutputModes: ["text", "file"]\n skills:\n - id: "mongo_query"\n name: "Coffee Shop MongoDB Query"\n description: "Queries coffee shop MongoDB database containing customer orders, product catalog, payment transactions, and order history using aggregation pipelines."\n'})}),"\n",(0,s.jsx)(n.p,{children:"This detailed information helps other agents understand:"}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsx)(n.li,{children:"What business domain this agent covers (coffee shop operations)"}),"\n",(0,s.jsx)(n.li,{children:"What types of data are available (orders, customers, products, payments)"}),"\n",(0,s.jsx)(n.li,{children:"What kinds of questions can be answered (analytics, behavior, performance, metrics)"}),"\n",(0,s.jsx)(n.li,{children:"Specific examples of queries that work well with MongoDB aggregation pipelines"}),"\n"]}),"\n",(0,s.jsx)(n.p,{children:"When configuring your own MongoDB agent, customize the description and examples to match your specific data structure and use cases."}),"\n",(0,s.jsx)(n.h2,{id:"mongodb-query-features",children:"MongoDB Query Features"}),"\n",(0,s.jsx)(n.p,{children:"The MongoDB agent supports various types of queries through natural language:"}),"\n",(0,s.jsx)(n.h3,{id:"aggregation-queries",children:"Aggregation Queries"}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsx)(n.li,{children:'"Show me the top 5 products by sales volume"'}),"\n",(0,s.jsx)(n.li,{children:'"Calculate the average order value by customer segment"'}),"\n",(0,s.jsx)(n.li,{children:'"Group orders by month and show revenue trends"'}),"\n"]}),"\n",(0,s.jsx)(n.h3,{id:"filtering-and-search",children:"Filtering and Search"}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsx)(n.li,{children:'"Find all orders placed in the last 24 hours"'}),"\n",(0,s.jsx)(n.li,{children:'"Show me orders with a total amount greater than $50"'}),"\n",(0,s.jsx)(n.li,{children:'"Find customers who ordered espresso drinks"'}),"\n"]}),"\n",(0,s.jsx)(n.h3,{id:"complex-analytics",children:"Complex Analytics"}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsx)(n.li,{children:'"What\'s the conversion rate from browsing to purchase?"'}),"\n",(0,s.jsx)(n.li,{children:'"Show me the busiest hours of the day"'}),"\n",(0,s.jsx)(n.li,{children:'"Calculate customer lifetime value"'}),"\n"]}),"\n",(0,s.jsx)(n.h3,{id:"output-formats",children:"Output Formats"}),"\n",(0,s.jsx)(n.p,{children:"The agent supports multiple output formats:"}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"JSON"}),": Default format, good for structured data"]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"YAML"}),": Human-readable format"]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"CSV"}),": Suitable for spreadsheet import"]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Markdown"}),": Formatted for documentation"]}),"\n"]}),"\n",(0,s.jsx)(n.p,{children:'You can specify the format in your query: "Show me today\'s sales in CSV format"'}),"\n",(0,s.jsx)(n.h2,{id:"troubleshooting",children:"Troubleshooting"}),"\n",(0,s.jsx)(n.h3,{id:"common-issues-and-solutions",children:"Common Issues and Solutions"}),"\n",(0,s.jsx)(n.h4,{id:"connection-errors",children:"Connection Errors"}),"\n",(0,s.jsxs)(n.p,{children:[(0,s.jsx)(n.strong,{children:"Issue"}),': "Unable to connect to MongoDB" errors\n',(0,s.jsx)(n.strong,{children:"Solution"}),":"]}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsx)(n.li,{children:"Verify your MongoDB server is running"}),"\n",(0,s.jsx)(n.li,{children:"Check connection parameters (host, port, credentials)"}),"\n",(0,s.jsx)(n.li,{children:"Ensure network connectivity and firewall settings"}),"\n",(0,s.jsx)(n.li,{children:"Test connection using MongoDB client tools"}),"\n"]}),"\n",(0,s.jsx)(n.h4,{id:"authentication-errors",children:"Authentication Errors"}),"\n",(0,s.jsxs)(n.p,{children:[(0,s.jsx)(n.strong,{children:"Issue"}),': "Authentication failed" errors\n',(0,s.jsx)(n.strong,{children:"Solution"}),":"]}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsx)(n.li,{children:"Verify username and password are correct"}),"\n",(0,s.jsx)(n.li,{children:"Check that the user has appropriate database permissions"}),"\n",(0,s.jsx)(n.li,{children:"Ensure the authentication database is correct"}),"\n"]}),"\n",(0,s.jsx)(n.h4,{id:"query-errors",children:"Query Errors"}),"\n",(0,s.jsxs)(n.p,{children:[(0,s.jsx)(n.strong,{children:"Issue"}),': "Invalid aggregation pipeline" errors\n',(0,s.jsx)(n.strong,{children:"Solution"}),":"]}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsx)(n.li,{children:"The agent automatically retries with corrected pipelines"}),"\n",(0,s.jsx)(n.li,{children:"Check that your natural language query is clear and specific"}),"\n",(0,s.jsx)(n.li,{children:"Verify that referenced fields exist in your collection"}),"\n"]}),"\n",(0,s.jsx)(n.h4,{id:"schema-detection-issues",children:"Schema Detection Issues"}),"\n",(0,s.jsxs)(n.p,{children:[(0,s.jsx)(n.strong,{children:"Issue"}),": Agent does not understand your data structure\n",(0,s.jsx)(n.strong,{children:"Solution"}),":"]}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:["Ensure ",(0,s.jsx)(n.code,{children:"auto_detect_schema"})," is set to ",(0,s.jsx)(n.code,{children:"true"})]}),"\n",(0,s.jsxs)(n.li,{children:["Provide detailed ",(0,s.jsx)(n.code,{children:"data_description"})," in your configuration"]}),"\n",(0,s.jsx)(n.li,{children:"Check that your collection has representative sample documents"}),"\n"]})]})}function h(e={}){const{wrapper:n}={...(0,a.R)(),...e.components};return n?(0,s.jsx)(n,{...e,children:(0,s.jsx)(d,{...e})}):d(e)}},8453:(e,n,t)=>{t.d(n,{R:()=>i,x:()=>r});var o=t(6540);const s={},a=o.createContext(s);function i(e){const n=o.useContext(a);return o.useMemo((function(){return"function"==typeof e?e(n):{...n,...e}}),[n,e])}function r(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(s):e.components||s:i(e.components),o.createElement(a.Provider,{value:n},e.children)}}}]);

solace_agent_mesh/assets/docs/assets/js/cd3d4052.a19e7d78.js DELETED Viewed

@@ -1 +0,0 @@

- "use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[4854],{5089:(e,n,s)=>{s.r(n),s.d(n,{assets:()=>l,contentTitle:()=>a,default:()=>h,frontMatter:()=>r,metadata:()=>t,toc:()=>c});const t=JSON.parse('{"id":"documentation/getting-started/installation","title":"Installation","description":"Before you begin, make sure you have the following:","source":"@site/docs/documentation/getting-started/installation.md","sourceDirName":"documentation/getting-started","slug":"/documentation/getting-started/installation","permalink":"/solace-agent-mesh/docs/documentation/getting-started/installation","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/getting-started/installation.md","tags":[],"version":"current","sidebarPosition":20,"frontMatter":{"title":"Installation","sidebar_position":20},"sidebar":"docSidebar","previous":{"title":"Introduction","permalink":"/solace-agent-mesh/docs/documentation/getting-started/introduction"},"next":{"title":"Quick Start","permalink":"/solace-agent-mesh/docs/documentation/getting-started/quick-start"}}');var i=s(4848),o=s(8453);const r={title:"Installation",sidebar_position:20},a="Prerequisites",l={},c=[];function d(e){const n={a:"a",admonition:"admonition",code:"code",h1:"h1",header:"header",li:"li",ol:"ol",p:"p",pre:"pre",strong:"strong",ul:"ul",...(0,o.R)(),...e.components},{Details:s}=n;return s||function(e,n){throw new Error("Expected "+(n?"component":"object")+" `"+e+"` to be defined: you likely forgot to import, pass, or provide it.")}("Details",!0),(0,i.jsxs)(i.Fragment,{children:[(0,i.jsx)(n.header,{children:(0,i.jsx)(n.h1,{id:"prerequisites",children:"Prerequisites"})}),"\n",(0,i.jsx)(n.p,{children:"Before you begin, make sure you have the following:"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsx)(n.li,{children:(0,i.jsx)(n.strong,{children:"Python 3.10.16+"})}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.strong,{children:"pip"})," (usually included with Python) or ",(0,i.jsx)(n.strong,{children:"uv"})," (install ",(0,i.jsx)(n.a,{href:"https://docs.astral.sh/uv/getting-started/installation/",children:"uv"}),")"]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.strong,{children:"Operating System"}),": macOS, Linux, or Windows (via ",(0,i.jsx)(n.a,{href:"https://learn.microsoft.com/en-us/windows/wsl/",children:"WSL"}),")"]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.strong,{children:"LLM API key"})," from any major provider or your own custom endpoint."]}),"\n"]}),"\n",(0,i.jsx)(n.h1,{id:"installation",children:"Installation"}),"\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.a,{href:"https://pypi.org/project/solace-agent-mesh",children:"Solace Agent Mesh Module"})," comes with two components:"]}),"\n",(0,i.jsxs)(n.ol,{children:["\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.strong,{children:"Solace Agent Mesh CLI"}),": To create, build, run, and extend Solace Agent Mesh."]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.strong,{children:"Solace Agent Mesh framework"}),": A Python-based framework that you can build upon to customize and extend the capabilities of Solace Agent Mesh."]}),"\n"]}),"\n",(0,i.jsx)(n.p,{children:"Installing the PyPi package installs both the Solace Agent Mesh CLI and the framework (which is built on the Python SDK)."}),"\n",(0,i.jsx)(n.admonition,{type:"tip",children:(0,i.jsx)(n.p,{children:"We recommend that you install the package in a virtual environment to avoid conflicts with other Python packages."})}),"\n",(0,i.jsxs)(s,{children:[(0,i.jsx)("summary",{children:"Creating a Virtual Environment"}),(0,i.jsxs)(s,{children:[(0,i.jsx)("summary",{children:"Using PIP"}),(0,i.jsxs)(n.ol,{children:["\n",(0,i.jsx)(n.li,{children:"Create a virtual environment."}),"\n"]}),(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{children:"python3 -m venv .venv\n"})}),(0,i.jsxs)(n.ol,{start:"2",children:["\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:"Activate the environment."}),"\n",(0,i.jsx)(n.p,{children:"To activate on Linux or Unix platforms:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-sh",children:"source .venv/bin/activate\n"})}),"\n",(0,i.jsx)(n.p,{children:"To activate on Windows:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-cmd",children:".venv\\Scripts\\activate\n"})}),"\n"]}),"\n"]})]}),(0,i.jsxs)(s,{children:[(0,i.jsx)("summary",{children:"Using UV"}),(0,i.jsxs)(n.ol,{children:["\n",(0,i.jsx)(n.li,{children:"Create a virtual environment."}),"\n"]}),(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{children:"uv venv .venv\n"})}),(0,i.jsxs)(n.ol,{start:"2",children:["\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:"Activate the environment."}),"\n",(0,i.jsx)(n.p,{children:"To activate on Linux or Unix platforms:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-sh",children:"source .venv/bin/activate\n"})}),"\n",(0,i.jsx)(n.p,{children:"To activate on Windows:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-cmd",children:".venv\\Scripts\\activate\n"})}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:"Expose the following environment variables:"}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:"On Linux or Unix platforms:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-sh",children:'export SAM_PLUGIN_INSTALL_COMMAND="uv pip install {package}"\n'})}),"\n",(0,i.jsx)(n.p,{children:"On Windows:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-cmd",children:'set SAM_PLUGIN_INSTALL_COMMAND="uv pip install {package}"\n'})}),"\n"]}),"\n"]})]})]}),"\n",(0,i.jsx)(n.p,{children:(0,i.jsx)(n.strong,{children:"Install Solace Agent Mesh"})}),"\n",(0,i.jsxs)(n.ol,{children:["\n",(0,i.jsx)(n.li,{children:"The following command installs Solace Agent Mesh CLI in your environment:"}),"\n"]}),"\n",(0,i.jsxs)(s,{children:[(0,i.jsx)("summary",{children:"Using PIP"}),(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-sh",children:"pip install solace-agent-mesh\n"})})]}),"\n",(0,i.jsxs)(s,{children:[(0,i.jsx)("summary",{children:"Using UV"}),(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-sh",children:"uv pip install solace-agent-mesh\n"})})]}),"\n",(0,i.jsxs)(n.admonition,{title:"Docker Alternative",type:"info",children:[(0,i.jsxs)(n.p,{children:["Alternatively, you can use our pre-built Docker image to run Solace Agent Mesh CLI commands without a local Python installation. This is useful for quick tasks or CI/CD environments. Note that the pre-built Docker image is configured with group ",(0,i.jsx)(n.code,{children:"solaceai"})," and non-root user ",(0,i.jsx)(n.code,{children:"solaceai"}),"."]}),(0,i.jsx)(n.p,{children:"To verify the installation using Docker, you can run:"}),(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-sh",children:"docker run --rm solace/solace-agent-mesh:latest --version\n"})}),(0,i.jsxs)(n.p,{children:["This command pulls the latest image (if not already present) and executes ",(0,i.jsx)(n.code,{children:"solace-agent-mesh --version"})," inside the container. The ",(0,i.jsx)(n.code,{children:"--rm"})," flag ensures the container is removed after execution."]}),(0,i.jsxs)(n.p,{children:["If the OS architecture on your host is not ",(0,i.jsx)(n.code,{children:"linux/amd64"}),", you would need to add ",(0,i.jsx)(n.code,{children:"--platform linux/amd64"})," when running container."]}),(0,i.jsxs)(n.p,{children:["For more complex operations like building a project, you'll need to mount your project directory into the container. See the ",(0,i.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/getting-started/quick-start",children:"Quick Start guide"})," for an example."]})]}),"\n",(0,i.jsxs)(n.admonition,{title:"Browser Requirement",type:"warning",children:[(0,i.jsxs)(n.p,{children:["The ",(0,i.jsx)(n.code,{children:"Mermaid"})," agent requires a browser with headless mode support to be installed (it uses headless mode to render diagrams). Use ",(0,i.jsx)(n.code,{children:"playwright"})," to install the browser dependencies. If you are using the Docker image, this is already included."]}),(0,i.jsx)(n.p,{children:"To install the browser dependencies, run:"}),(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-sh",children:"playwright install\n"})})]}),"\n",(0,i.jsxs)(n.ol,{start:"2",children:["\n",(0,i.jsxs)(n.li,{children:["Run the following Solace Agent Mesh CLI command (",(0,i.jsx)(n.code,{children:"solace-agent-mesh"}),") to verify your installation:"]}),"\n"]}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-sh",children:"solace-agent-mesh --version\n"})}),"\n",(0,i.jsxs)(n.admonition,{type:"tip",children:[(0,i.jsxs)(n.p,{children:["For easier access to the Solace Agent Mesh CLI, it also comes with the ",(0,i.jsx)(n.code,{children:"sam"})," alias."]}),(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-sh",children:"sam --version\n"})})]}),"\n",(0,i.jsx)(n.p,{children:"To get the list of available commands, run:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-sh",children:"solace-agent-mesh --help\n"})})]})}function h(e={}){const{wrapper:n}={...(0,o.R)(),...e.components};return n?(0,i.jsx)(n,{...e,children:(0,i.jsx)(d,{...e})}):d(e)}},8453:(e,n,s)=>{s.d(n,{R:()=>r,x:()=>a});var t=s(6540);const i={},o=t.createContext(i);function r(e){const n=t.useContext(o);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(i):e.components||i:r(e.components),t.createElement(o.Provider,{value:n},e.children)}}}]);

solace_agent_mesh/assets/docs/assets/js/ced92a13.fb92e7ca.js DELETED Viewed

@@ -1 +0,0 @@

- "use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[817],{8998:(e,t,n)=>{n.r(t),n.d(t,{assets:()=>a,contentTitle:()=>l,default:()=>h,frontMatter:()=>d,metadata:()=>s,toc:()=>c});const s=JSON.parse('{"id":"documentation/user-guide/builtin-tools/embeds","title":"Dynamic Embeds","description":"Dynamic Embeds","source":"@site/docs/documentation/user-guide/builtin-tools/embeds.md","sourceDirName":"documentation/user-guide/builtin-tools","slug":"/documentation/user-guide/builtin-tools/embeds","permalink":"/solace-agent-mesh/docs/documentation/user-guide/builtin-tools/embeds","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/user-guide/builtin-tools/embeds.md","tags":[],"version":"current","sidebarPosition":40,"frontMatter":{"title":"Dynamic Embeds","sidebar_position":40},"sidebar":"docSidebar","previous":{"title":"Audio Tools","permalink":"/solace-agent-mesh/docs/documentation/user-guide/builtin-tools/audio-tools"},"next":{"title":"Deployment","permalink":"/solace-agent-mesh/docs/documentation/deployment/deploy"}}');var i=n(4848),r=n(8453);const d={title:"Dynamic Embeds",sidebar_position:40},l=void 0,a={},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_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_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:"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:()=>d,x:()=>l});var s=n(6540);const i={},r=s.createContext(i);function d(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:d(e.components),s.createElement(r.Provider,{value:t},e.children)}}}]);

solace_agent_mesh/assets/docs/assets/js/cee5d587.47904f5e.js DELETED Viewed

@@ -1 +0,0 @@

- "use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[4851],{542:(e,n,i)=>{i.r(n),i.d(n,{assets:()=>c,contentTitle:()=>a,default:()=>u,frontMatter:()=>s,metadata:()=>t,toc:()=>d});const t=JSON.parse('{"id":"documentation/user-guide/structure","title":"Structure","description":"Solace Agent Mesh is built on the A2A (Agent-to-Agent) protocol architecture, powered by Solace AI Event Connector and uses the Solace broker as the communication backbone. The framework is controlled by YAML configuration files that define agents, gateways, and plugins, enabling distributed AI agent communication through event-driven messaging.","source":"@site/docs/documentation/user-guide/structure.md","sourceDirName":"documentation/user-guide","slug":"/documentation/user-guide/structure","permalink":"/solace-agent-mesh/docs/documentation/user-guide/structure","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/user-guide/structure.md","tags":[],"version":"current","sidebarPosition":20,"frontMatter":{"title":"Structure","sidebar_position":20},"sidebar":"docSidebar","previous":{"title":"Solace AI Event Connector","permalink":"/solace-agent-mesh/docs/documentation/user-guide/solace-ai-connector"},"next":{"title":"Create Agents","permalink":"/solace-agent-mesh/docs/documentation/user-guide/create-agents"}}');var o=i(4848),r=i(8453);const s={title:"Structure",sidebar_position:20},a="Structure",c={},d=[{value:"Project Structure",id:"project-structure",level:2},{value:"Configuration Organization",id:"configuration-organization",level:2},{value:"Directory Structure",id:"directory-structure",level:3},{value:"Shared Configuration",id:"shared-configuration",level:3},{value:"YAML Configuration Files",id:"yaml-configuration-files",level:2},{value:"Configuration Management",id:"configuration-management",level:2},{value:"Python Components",id:"python-components",level:2}];function l(e){const n={a:"a",admonition:"admonition",code:"code",h1:"h1",h2:"h2",h3:"h3",header:"header",li:"li",p:"p",pre:"pre",strong:"strong",ul:"ul",...(0,r.R)(),...e.components};return(0,o.jsxs)(o.Fragment,{children:[(0,o.jsx)(n.header,{children:(0,o.jsx)(n.h1,{id:"structure",children:"Structure"})}),"\n",(0,o.jsxs)(n.p,{children:["Solace Agent Mesh is built on the A2A (Agent-to-Agent) protocol architecture, powered by ",(0,o.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/user-guide/solace-ai-connector",children:"Solace AI Event Connector"})," and uses the Solace broker as the communication backbone. The framework is controlled by YAML configuration files that define agents, gateways, and plugins, enabling distributed AI agent communication through event-driven messaging."]}),"\n",(0,o.jsx)(n.h2,{id:"project-structure",children:"Project Structure"}),"\n",(0,o.jsx)(n.p,{children:"A fresh Solace Agent Mesh project follows this structure:"}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{children:"my-sam-project/\n\u251c\u2500\u2500 configs/\n\u2502 \u251c\u2500\u2500 shared_config.yaml # Shared broker, models, and services config\n\u2502 \u251c\u2500\u2500 agents/\n\u2502 \u2502 \u2514\u2500\u2500 main_orchestrator.yaml # Default orchestrator agent\n\u2502 \u2514\u2500\u2500 gateways/\n\u2502 \u2502 \u2514\u2500\u2500 webui.yaml # Default web UI gateway\n\u2502 \u251c\u2500\u2500 plugins/\n\u251c\u2500\u2500 src/ # Custom Python components (optional)\n\u2502 \u2514\u2500\u2500 __init__.py\n"})}),"\n",(0,o.jsx)(n.h2,{id:"configuration-organization",children:"Configuration Organization"}),"\n",(0,o.jsx)(n.h3,{id:"directory-structure",children:"Directory Structure"}),"\n",(0,o.jsxs)(n.p,{children:["The ",(0,o.jsx)(n.code,{children:"configs/"})," directory uses a logical organization:"]}),"\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:"agents/"})})," - Contains agent configuration files"]}),"\n",(0,o.jsxs)(n.li,{children:[(0,o.jsx)(n.strong,{children:(0,o.jsx)(n.code,{children:"gateways/"})})," - Contains gateway configuration files"]}),"\n",(0,o.jsxs)(n.li,{children:[(0,o.jsx)(n.strong,{children:(0,o.jsx)(n.code,{children:"plugins/"})})," - Contains plugin configuration files (created when plugins are added)"]}),"\n"]}),"\n",(0,o.jsxs)(n.p,{children:["Further subdirectories can be created within ",(0,o.jsx)(n.code,{children:"agents/"}),", ",(0,o.jsx)(n.code,{children:"gateways/"}),", and ",(0,o.jsx)(n.code,{children:"plugins/"})," to organize configurations by functionality or purpose."]}),"\n",(0,o.jsxs)(n.admonition,{title:"File Discovery",type:"info",children:[(0,o.jsxs)(n.p,{children:["The CLI automatically crawls through the configs directory to find configuration files. Files that start with ",(0,o.jsx)(n.code,{children:"_"})," (underscore) or ",(0,o.jsx)(n.code,{children:"shared_config"})," are ignored and not processed by the CLI.\nFor example:"]}),(0,o.jsxs)(n.ul,{children:["\n",(0,o.jsxs)(n.li,{children:[(0,o.jsx)(n.code,{children:"_example_agent.yaml"})," is ignored"]}),"\n",(0,o.jsxs)(n.li,{children:[(0,o.jsx)(n.code,{children:"shared_config_for_db_agents.yaml"})," is ignored (Can still be included in other config files using ",(0,o.jsx)(n.code,{children:"!include"})," directive)"]}),"\n"]})]}),"\n",(0,o.jsx)(n.h3,{id:"shared-configuration",children:"Shared Configuration"}),"\n",(0,o.jsxs)(n.p,{children:["The ",(0,o.jsx)(n.code,{children:"shared_config.yaml"})," file is the foundation of your project configuration. It contains common elements that are reused across all agents and gateways using YAML anchors:"]}),"\n",(0,o.jsxs)(n.ul,{children:["\n",(0,o.jsxs)(n.li,{children:[(0,o.jsx)(n.strong,{children:"Broker Connection"}),": Solace broker settings for A2A communication"]}),"\n",(0,o.jsxs)(n.li,{children:[(0,o.jsx)(n.strong,{children:"Model Definitions"}),": LLM model configurations (planning, general, multimodal, etc.)"]}),"\n",(0,o.jsxs)(n.li,{children:[(0,o.jsx)(n.strong,{children:"Services"}),": Artifact service, session service, and data tools configuration"]}),"\n"]}),"\n",(0,o.jsxs)(n.p,{children:["This shared configuration approach eliminates duplication and ensures consistency across your entire project. Each agent and gateway configuration file references these shared elements using YAML anchor syntax (",(0,o.jsx)(n.code,{children:"*reference_name"}),")."]}),"\n",(0,o.jsx)(n.p,{children:"Further values can be added to the shared configuration file as needed, and they are available to all agents and gateways that include it."}),"\n",(0,o.jsx)(n.h2,{id:"yaml-configuration-files",children:"YAML Configuration Files"}),"\n",(0,o.jsx)(n.p,{children:"Each configuration file defines one [recommended] or more applications that can be run independently. The framework supports:"}),"\n",(0,o.jsxs)(n.ul,{children:["\n",(0,o.jsxs)(n.li,{children:[(0,o.jsx)(n.strong,{children:"Agent Applications"}),": A2A-enabled agents that use Google ADK runtime and Solace Agent Mesh framework"]}),"\n",(0,o.jsxs)(n.li,{children:[(0,o.jsx)(n.strong,{children:"Gateway Applications"}),": Protocol translators that bridge external interfaces to adopted A2A protocol"]}),"\n",(0,o.jsxs)(n.li,{children:[(0,o.jsx)(n.strong,{children:"Plugin Applications"}),": Specialized components that extend framework capabilities"]}),"\n"]}),"\n",(0,o.jsx)(n.h2,{id:"configuration-management",children:"Configuration Management"}),"\n",(0,o.jsxs)(n.ul,{children:["\n",(0,o.jsxs)(n.li,{children:[(0,o.jsx)(n.strong,{children:"Environment Variables"}),": Configuration values use environment variables for flexibility across environments"]}),"\n",(0,o.jsxs)(n.li,{children:[(0,o.jsx)(n.strong,{children:"Shared Configuration"}),": Common settings are defined once in ",(0,o.jsx)(n.code,{children:"shared_config.yaml"})," and referenced using YAML anchors (",(0,o.jsx)(n.code,{children:"&"})," and ",(0,o.jsx)(n.code,{children:"*"}),")"]}),"\n",(0,o.jsxs)(n.li,{children:[(0,o.jsx)(n.strong,{children:"Automatic Generation"}),": The ",(0,o.jsx)(n.code,{children:"sam add agent"}),", ",(0,o.jsx)(n.code,{children:"sam add gateway"}),", and ",(0,o.jsx)(n.code,{children:"sam plugin add"})," commands automatically generate appropriate configuration files"]}),"\n",(0,o.jsxs)(n.li,{children:[(0,o.jsx)(n.strong,{children:"Standalone Execution"}),": Each configuration file can be run independently using ",(0,o.jsx)(n.code,{children:"sam run <config-file>"})]}),"\n"]}),"\n",(0,o.jsx)(n.h2,{id:"python-components",children:"Python Components"}),"\n",(0,o.jsxs)(n.p,{children:["While most functionality is configured through YAML, custom Python components can be added to the ",(0,o.jsx)(n.code,{children:"src/"})," directory when needed. The framework provides base classes for extending functionality such as custom agent tools, gateway protocol handlers, and service providers."]})]})}function u(e={}){const{wrapper:n}={...(0,r.R)(),...e.components};return n?(0,o.jsx)(n,{...e,children:(0,o.jsx)(l,{...e})}):l(e)}},8453:(e,n,i)=>{i.d(n,{R:()=>s,x:()=>a});var t=i(6540);const o={},r=t.createContext(o);function s(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(o):e.components||o:s(e.components),t.createElement(r.Provider,{value:n},e.children)}}}]);

solace_agent_mesh/assets/docs/assets/js/d6a81ee7.829198f1.js DELETED Viewed

@@ -1 +0,0 @@

- "use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[4600],{8263:(e,n,i)=>{i.r(n),i.d(n,{assets:()=>l,contentTitle:()=>d,default:()=>h,frontMatter:()=>o,metadata:()=>t,toc:()=>c});const t=JSON.parse('{"id":"documentation/getting-started/configurations/litellm_models","title":"LLM Models","description":"Configuring Different LLM Providers","source":"@site/docs/documentation/getting-started/configurations/litellm_models.md","sourceDirName":"documentation/getting-started/configurations","slug":"/documentation/getting-started/configurations/litellm_models","permalink":"/solace-agent-mesh/docs/documentation/getting-started/configurations/litellm_models","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/getting-started/configurations/litellm_models.md","tags":[],"version":"current","sidebarPosition":12,"frontMatter":{"title":"LLM Models","sidebar_position":12},"sidebar":"docSidebar","previous":{"title":"Configurations","permalink":"/solace-agent-mesh/docs/documentation/getting-started/configurations/"},"next":{"title":"Architecture","permalink":"/solace-agent-mesh/docs/documentation/concepts/architecture"}}');var s=i(4848),r=i(8453);const o={title:"LLM Models",sidebar_position:12},d="LLM Models",l={},c=[{value:"Configuring Different LLM Providers",id:"configuring-different-llm-providers",level:2},{value:"OpenAI",id:"openai",level:3},{value:"Azure OpenAI",id:"azure-openai",level:3},{value:"Vertex AI",id:"vertex-ai",level:3},{value:"Bedrock",id:"bedrock",level:3},{value:"Anthropic",id:"anthropic",level:3},{value:"Others",id:"others",level:3},{value:"SSL/TLS Configuration",id:"ssltls-configuration",level:2},{value:"Example <code>.env</code> file",id:"example-env-file",level:5}];function a(e){const n={a:"a",code:"code",h1:"h1",h2:"h2",h3:"h3",h5:"h5",header:"header",li:"li",p:"p",pre:"pre",table:"table",tbody:"tbody",td:"td",th:"th",thead:"thead",tr:"tr",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:"llm-models",children:"LLM Models"})}),"\n",(0,s.jsx)(n.h2,{id:"configuring-different-llm-providers",children:"Configuring Different LLM Providers"}),"\n",(0,s.jsxs)(n.p,{children:["The ",(0,s.jsx)(n.code,{children:"apps.app_config.model"})," field which can also be configured globally in ",(0,s.jsx)(n.code,{children:"shared_config.yaml"})," under the ",(0,s.jsx)(n.code,{children:"models"})," section, allows you to specify the connection details for different Large Language Model (LLM) providers. Solace Agent Mesh leverages ",(0,s.jsx)(n.a,{href:"https://docs.litellm.ai/docs/providers",children:"LiteLLM"})," to support a variety of LLM providers seamlessly. All fields provided in the ",(0,s.jsx)(n.code,{children:"models"})," section are directly passed to LiteLLM, allowing you to configure any supported model."]}),"\n",(0,s.jsxs)(n.p,{children:["Use the following provided YAML snippets for the model section in your YAML configuration files. You can use environment variables to manage sensitive information like API keys as well using the format ",(0,s.jsx)(n.code,{children:"${ENV_VAR_NAME, default_value}"}),"."]}),"\n",(0,s.jsx)(n.h3,{id:"openai",children:"OpenAI"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-yaml",children:"model: gpt-5\napi_key: ${OPENAI_API_KEY}\n"})}),"\n",(0,s.jsxs)(n.p,{children:["Optionally, you can pass the parameter ",(0,s.jsx)(n.code,{children:"organization"})," if you are part of multiple organizations."]}),"\n",(0,s.jsxs)(n.p,{children:["More details at ",(0,s.jsx)(n.a,{href:"https://docs.litellm.ai/docs/providers/openai",children:"OpenAI documentation"}),"."]}),"\n",(0,s.jsx)(n.h3,{id:"azure-openai",children:"Azure OpenAI"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-yaml",children:'model: azure/gpt-5\napi_base: ${AZURE_API_BASE,"https://your-custom-endpoint.openai.azure.com/"}\napi_key: ${AZURE_API_KEY}\napi_version: ${AZURE_API_VERSION,"2024-12-01-preview"}\n'})}),"\n",(0,s.jsxs)(n.p,{children:["More details at ",(0,s.jsx)(n.a,{href:"https://docs.litellm.ai/docs/providers/azure/",children:"Azure OpenAI documentation"}),"."]}),"\n",(0,s.jsx)(n.h3,{id:"vertex-ai",children:"Vertex AI"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-yaml",children:'model: vertex_ai/claude-sonnet-4@20250514\nvertex_project: ${VERTEX_PROJECT}\nvertex_location: ${VERTEX_LOCATION,"us-east5"}\nvertex_credentials: ${VERTEX_CREDENTIALS}\n'})}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.code,{children:"vertex_credentials"})," is a JSON string of the service account key.\nAn example of the content is as follows:","\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-sh",children:'export VERTEX_CREDENTIALS=\'{"type": "", "project_id": "", "private_key_id": "", "private_key": "", "client_email": "", "client_id": "", "auth_uri": "", "token_uri": "", "auth_provider_x509_cert_url": "", "client_x509_cert_url": "", "universe_domain": ""}\'\n'})}),"\n"]}),"\n"]}),"\n",(0,s.jsxs)(n.p,{children:["More details at ",(0,s.jsx)(n.a,{href:"https://docs.litellm.ai/docs/providers/vertex",children:"Vertex AI documentation"}),"."]}),"\n",(0,s.jsx)(n.h3,{id:"bedrock",children:"Bedrock"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-yaml",children:'model: bedrock/anthropic.claude-3-5-sonnet-20240620-v1:0\naws_region_name: ${AWS_REGION_NAME,"us-east-1"}\naws_access_key_id: ${AWS_ACCESS_KEY_ID}\naws_secret_access_key: ${AWS_SECRET_ACCESS_KEY}\n'})}),"\n",(0,s.jsxs)(n.p,{children:["More details at ",(0,s.jsx)(n.a,{href:"https://docs.litellm.ai/docs/providers/bedrock",children:"AWS Bedrock documentation"}),"."]}),"\n",(0,s.jsx)(n.h3,{id:"anthropic",children:"Anthropic"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-yaml",children:"model: claude-4\napi_key: ${ANTHROPIC_API_KEY}\n"})}),"\n",(0,s.jsxs)(n.p,{children:["More details at ",(0,s.jsx)(n.a,{href:"https://docs.litellm.ai/docs/providers/anthropic",children:"Anthropic documentation"}),"."]}),"\n",(0,s.jsx)(n.h3,{id:"others",children:"Others"}),"\n",(0,s.jsxs)(n.p,{children:["For a complete list of supported models and their configuration options, refer to LiteLlM's official documentation ",(0,s.jsx)(n.a,{href:"https://docs.litellm.ai/docs/providers",children:"here"}),"."]}),"\n",(0,s.jsx)(n.h2,{id:"ssltls-configuration",children:"SSL/TLS Configuration"}),"\n",(0,s.jsx)(n.p,{children:"Solace Agent Mesh allows for fine tuning the security parameters on connections to your LLM endpoints through environment variables. The connection parameters are described in the following table:"}),"\n",(0,s.jsxs)(n.table,{children:[(0,s.jsx)(n.thead,{children:(0,s.jsxs)(n.tr,{children:[(0,s.jsx)(n.th,{children:"Parameter"}),(0,s.jsx)(n.th,{children:"Type"}),(0,s.jsx)(n.th,{children:"Description"}),(0,s.jsx)(n.th,{children:"Default"})]})}),(0,s.jsxs)(n.tbody,{children:[(0,s.jsxs)(n.tr,{children:[(0,s.jsx)(n.td,{children:(0,s.jsx)(n.code,{children:"SSL_VERIFY"})}),(0,s.jsx)(n.td,{children:(0,s.jsx)(n.code,{children:"boolean"})}),(0,s.jsx)(n.td,{children:"Controls SSL certificate verification for outbound connections."}),(0,s.jsx)(n.td,{children:(0,s.jsx)(n.code,{children:"true"})})]}),(0,s.jsxs)(n.tr,{children:[(0,s.jsx)(n.td,{children:(0,s.jsx)(n.code,{children:"SSL_SECURITY_LEVEL"})}),(0,s.jsx)(n.td,{children:(0,s.jsx)(n.code,{children:"integer"})}),(0,s.jsx)(n.td,{children:"Sets the SSL security level (higher values enforce stricter checks)."}),(0,s.jsx)(n.td,{children:(0,s.jsx)(n.code,{children:"2"})})]}),(0,s.jsxs)(n.tr,{children:[(0,s.jsx)(n.td,{children:(0,s.jsx)(n.code,{children:"SSL_CERT_FILE"})}),(0,s.jsx)(n.td,{children:(0,s.jsx)(n.code,{children:"string"})}),(0,s.jsx)(n.td,{children:"Path to a custom SSL certificate file to use for verification."}),(0,s.jsx)(n.td,{children:"(none)"})]}),(0,s.jsxs)(n.tr,{children:[(0,s.jsx)(n.td,{children:(0,s.jsx)(n.code,{children:"SSL_CERTIFICATE"})}),(0,s.jsx)(n.td,{children:(0,s.jsx)(n.code,{children:"string"})}),(0,s.jsx)(n.td,{children:"Direct content of the SSL certificate (PEM format)."}),(0,s.jsx)(n.td,{children:"(none)"})]}),(0,s.jsxs)(n.tr,{children:[(0,s.jsx)(n.td,{children:(0,s.jsx)(n.code,{children:"DISABLE_AIOHTTP_TRANSPORT"})}),(0,s.jsx)(n.td,{children:(0,s.jsx)(n.code,{children:"boolean"})}),(0,s.jsx)(n.td,{children:"Flag to disable the use of aiohttp transport for HTTP requests."}),(0,s.jsx)(n.td,{children:(0,s.jsx)(n.code,{children:"false"})})]}),(0,s.jsxs)(n.tr,{children:[(0,s.jsx)(n.td,{children:(0,s.jsx)(n.code,{children:"AIOHTTP_TRUST_ENV"})}),(0,s.jsx)(n.td,{children:(0,s.jsx)(n.code,{children:"boolean"})}),(0,s.jsx)(n.td,{children:"Flag to enable aiohttp to trust environment proxy settings."}),(0,s.jsx)(n.td,{children:(0,s.jsx)(n.code,{children:"false"})})]})]})]}),"\n",(0,s.jsxs)(n.p,{children:["More information about each setting and it's use case can be found in the ",(0,s.jsx)(n.a,{href:"https://docs.litellm.ai/docs/guides/security_settings",children:"LiteLLM docs"})]}),"\n",(0,s.jsxs)(n.h5,{id:"example-env-file",children:["Example ",(0,s.jsx)(n.code,{children:".env"})," file"]}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-bash",children:'# SSL Configuration\nSSL_VERIFY=true\nSSL_SECURITY_LEVEL=2\nSSL_CERT_FILE=/path/to/your/certificate.pem\nSSL_CERTIFICATE="-----BEGIN CERTIFICATE-----\nMIIDXTCCAkWgAwIBAg...T2u3V4w5X6y7Z8\n-----END CERTIFICATE-----"\n\n# HTTP Transport Configuration\nDISABLE_AIOHTTP_TRANSPORT=false\nAIOHTTP_TRUST_ENV=false\n'})})]})}function h(e={}){const{wrapper:n}={...(0,r.R)(),...e.components};return n?(0,s.jsx)(n,{...e,children:(0,s.jsx)(a,{...e})}):a(e)}},8453:(e,n,i)=>{i.d(n,{R:()=>o,x:()=>d});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 d(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/f284c35a.ed8dd236.js DELETED Viewed

@@ -1 +0,0 @@

- "use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[3011],{8549:e=>{e.exports=JSON.parse('{"version":{"pluginId":"default","version":"current","label":"Next","banner":null,"badge":false,"noIndex":false,"className":"docs-version-current","isLast":true,"docsSidebars":{"docSidebar":[{"type":"category","label":"Getting Started","collapsible":true,"collapsed":false,"items":[{"type":"link","label":"Introduction","href":"/solace-agent-mesh/docs/documentation/getting-started/introduction","docId":"documentation/getting-started/introduction","unlisted":false},{"type":"link","label":"Installation","href":"/solace-agent-mesh/docs/documentation/getting-started/installation","docId":"documentation/getting-started/installation","unlisted":false},{"type":"link","label":"Quick Start","href":"/solace-agent-mesh/docs/documentation/getting-started/quick-start","docId":"documentation/getting-started/quick-start","unlisted":false},{"type":"link","label":"Component Overview","href":"/solace-agent-mesh/docs/documentation/getting-started/component-overview","docId":"documentation/getting-started/component-overview","unlisted":false},{"type":"category","label":"Configurations","collapsible":false,"collapsed":false,"items":[{"type":"link","label":"LLM Models","href":"/solace-agent-mesh/docs/documentation/getting-started/configurations/litellm_models","docId":"documentation/getting-started/configurations/litellm_models","unlisted":false}],"href":"/solace-agent-mesh/docs/documentation/getting-started/configurations/"}]},{"type":"category","label":"Components and Concepts","collapsible":true,"collapsed":true,"items":[{"type":"link","label":"Architecture","href":"/solace-agent-mesh/docs/documentation/concepts/architecture","docId":"documentation/concepts/architecture","unlisted":false},{"type":"link","label":"Solace Agent Mesh CLI","href":"/solace-agent-mesh/docs/documentation/concepts/cli","docId":"documentation/concepts/cli","unlisted":false},{"type":"link","label":"Gateways","href":"/solace-agent-mesh/docs/documentation/concepts/gateways","docId":"documentation/concepts/gateways","unlisted":false},{"type":"link","label":"Agents","href":"/solace-agent-mesh/docs/documentation/concepts/agents","docId":"documentation/concepts/agents","unlisted":false},{"type":"link","label":"Orchestrator","href":"/solace-agent-mesh/docs/documentation/concepts/orchestrator","docId":"documentation/concepts/orchestrator","unlisted":false},{"type":"link","label":"Plugins","href":"/solace-agent-mesh/docs/documentation/concepts/plugins","docId":"documentation/concepts/plugins","unlisted":false}]},{"type":"category","label":"User Guide","collapsible":true,"collapsed":true,"items":[{"type":"link","label":"Solace AI Event Connector","href":"/solace-agent-mesh/docs/documentation/user-guide/solace-ai-connector","docId":"documentation/user-guide/solace-ai-connector","unlisted":false},{"type":"link","label":"Structure","href":"/solace-agent-mesh/docs/documentation/user-guide/structure","docId":"documentation/user-guide/structure","unlisted":false},{"type":"link","label":"Create Agents","href":"/solace-agent-mesh/docs/documentation/user-guide/create-agents","docId":"documentation/user-guide/create-agents","unlisted":false},{"type":"link","label":"Creating Python Tools","href":"/solace-agent-mesh/docs/documentation/user-guide/creating-python-tools","docId":"documentation/user-guide/creating-python-tools","unlisted":false},{"type":"link","label":"Create Gateways","href":"/solace-agent-mesh/docs/documentation/user-guide/create-gateways","docId":"documentation/user-guide/create-gateways","unlisted":false},{"type":"link","label":"Creating Service Providers","href":"/solace-agent-mesh/docs/documentation/user-guide/creating-service-providers","docId":"documentation/user-guide/creating-service-providers","unlisted":false},{"type":"category","label":"Built-in Tools","collapsible":true,"collapsed":true,"items":[{"type":"link","label":"Artifact Management Tools","href":"/solace-agent-mesh/docs/documentation/user-guide/builtin-tools/artifact-management","docId":"documentation/user-guide/builtin-tools/artifact-management","unlisted":false},{"type":"link","label":"Data Analysis Tools","href":"/solace-agent-mesh/docs/documentation/user-guide/builtin-tools/data-analysis-tools","docId":"documentation/user-guide/builtin-tools/data-analysis-tools","unlisted":false},{"type":"link","label":"Audio Tools","href":"/solace-agent-mesh/docs/documentation/user-guide/builtin-tools/audio-tools","docId":"documentation/user-guide/builtin-tools/audio-tools","unlisted":false},{"type":"link","label":"Dynamic Embeds","href":"/solace-agent-mesh/docs/documentation/user-guide/builtin-tools/embeds","docId":"documentation/user-guide/builtin-tools/embeds","unlisted":false}],"href":"/solace-agent-mesh/docs/documentation/user-guide/builtin-tools/"}]},{"type":"category","label":"Deployment","collapsible":true,"collapsed":true,"items":[{"type":"link","label":"Deployment","href":"/solace-agent-mesh/docs/documentation/deployment/deploy","docId":"documentation/deployment/deploy","unlisted":false},{"type":"link","label":"Observability","href":"/solace-agent-mesh/docs/documentation/deployment/observability","docId":"documentation/deployment/observability","unlisted":false},{"type":"link","label":"Debugging","href":"/solace-agent-mesh/docs/documentation/deployment/debugging","docId":"documentation/deployment/debugging","unlisted":false}]},{"type":"category","label":"Tutorials","collapsible":true,"collapsed":true,"items":[{"type":"link","label":"Build Your Own Agent","href":"/solace-agent-mesh/docs/documentation/tutorials/custom-agent","docId":"documentation/tutorials/custom-agent","unlisted":false},{"type":"link","label":"MCP Integration","href":"/solace-agent-mesh/docs/documentation/tutorials/mcp-integration","docId":"documentation/tutorials/mcp-integration","unlisted":false},{"type":"link","label":"REST Gateway","href":"/solace-agent-mesh/docs/documentation/tutorials/rest-gateway","docId":"documentation/tutorials/rest-gateway","unlisted":false},{"type":"link","label":"Event Mesh Gateway","href":"/solace-agent-mesh/docs/documentation/tutorials/event-mesh-gateway","docId":"documentation/tutorials/event-mesh-gateway","unlisted":false},{"type":"link","label":"Amazon Bedrock Agents","href":"/solace-agent-mesh/docs/documentation/tutorials/bedrock-agents","docId":"documentation/tutorials/bedrock-agents","unlisted":false},{"type":"link","label":"SQL Database Integration","href":"/solace-agent-mesh/docs/documentation/tutorials/sql-database","docId":"documentation/tutorials/sql-database","unlisted":false},{"type":"link","label":"MongoDB Integration","href":"/solace-agent-mesh/docs/documentation/tutorials/mongodb-integration","docId":"documentation/tutorials/mongodb-integration","unlisted":false},{"type":"link","label":"Slack Integration","href":"/solace-agent-mesh/docs/documentation/tutorials/slack-integration","docId":"documentation/tutorials/slack-integration","unlisted":false},{"type":"link","label":"RAG Integration","href":"/solace-agent-mesh/docs/documentation/tutorials/rag-integration","docId":"documentation/tutorials/rag-integration","unlisted":false}]},{"type":"category","label":"Migrations","collapsible":true,"collapsed":true,"items":[{"type":"category","label":"A2A Upgrade To 0.3.0","collapsible":true,"collapsed":true,"items":[{"type":"link","label":"Solace Agent Mesh Gateway Migration Guide: Upgrading to the A2A SDK","href":"/solace-agent-mesh/docs/documentation/Migrations/A2A Upgrade To 0.3.0/a2a-gateway-upgrade-to-0.3.0","docId":"documentation/Migrations/A2A Upgrade To 0.3.0/a2a-gateway-upgrade-to-0.3.0","unlisted":false},{"type":"link","label":"A2A Technical Migration Map","href":"/solace-agent-mesh/docs/documentation/Migrations/A2A Upgrade To 0.3.0/a2a-technical-migration-map","docId":"documentation/Migrations/A2A Upgrade To 0.3.0/a2a-technical-migration-map","unlisted":false}]}]},{"type":"category","label":"Enterprise","collapsible":true,"collapsed":true,"items":[{"type":"link","label":"Installation","href":"/solace-agent-mesh/docs/documentation/Enterprise/installation","docId":"documentation/Enterprise/installation","unlisted":false},{"type":"link","label":"RBAC Setup Guide","href":"/solace-agent-mesh/docs/documentation/Enterprise/rbac-setup-guilde","docId":"documentation/Enterprise/rbac-setup-guilde","unlisted":false},{"type":"link","label":"SSO","href":"/solace-agent-mesh/docs/documentation/Enterprise/single-sign-on","docId":"documentation/Enterprise/single-sign-on","unlisted":false}]}]},"docs":{"documentation/concepts/agents":{"id":"documentation/concepts/agents","title":"Agents","description":"Agents are specialized processing units within the Solace Agent Mesh framework that are built around the Google Agent Development Kit (ADK) and provide the core intelligence layer. They:","sidebar":"docSidebar"},"documentation/concepts/architecture":{"id":"documentation/concepts/architecture","title":"Architecture","description":"Overview","sidebar":"docSidebar"},"documentation/concepts/cli":{"id":"documentation/concepts/cli","title":"Solace Agent Mesh CLI","description":"Solace Agent Mesh comes with a comprehensive CLI tool that you can use to create, and run an instance of Solace Agent Mesh, which is referred to as a Solace Agent Mesh application. Solace Agent Mesh CLI also allows you to add agents and gateways, manage plugins, help you debug, and much more.","sidebar":"docSidebar"},"documentation/concepts/gateways":{"id":"documentation/concepts/gateways","title":"Gateways","description":"Gateways are a crucial component of the Solace Agent Mesh framework that expose the agent mesh to external systems through various protocols. Built on a common base gateway architecture, they provide the following functions:","sidebar":"docSidebar"},"documentation/concepts/orchestrator":{"id":"documentation/concepts/orchestrator","title":"Orchestrator","description":"The A2A (Agent-to-Agent) protocol is the communication backbone of Solace Agent Mesh that enables distributed agent coordination and workflow management. Unlike traditional centralized orchestration, the A2A protocol enables agents to discover each other, delegate tasks, and collaborate directly through standardized message patterns.","sidebar":"docSidebar"},"documentation/concepts/plugins":{"id":"documentation/concepts/plugins","title":"Plugins","description":"Plugins","sidebar":"docSidebar"},"documentation/deployment/debugging":{"id":"documentation/deployment/debugging","title":"Debugging","description":"Debugging issues in Solace Agent Mesh starts with identifying the problem. You can monitor your system to debug it more effectively. For more information, see Observability.","sidebar":"docSidebar"},"documentation/deployment/deploy":{"id":"documentation/deployment/deploy","title":"Deployment","description":"Development","sidebar":"docSidebar"},"documentation/deployment/observability":{"id":"documentation/deployment/observability","title":"Observability","description":"Solace Agent Mesh provides a comprehensive set of tools for real-time system monitoring and key insights to help you understand system states, request flows, and key insights for debugging and optimizing your system.","sidebar":"docSidebar"},"documentation/Enterprise/installation":{"id":"documentation/Enterprise/installation","title":"Installation","description":"Step 1: Prepare the Enterprise Image","sidebar":"docSidebar"},"documentation/Enterprise/rbac-setup-guilde":{"id":"documentation/Enterprise/rbac-setup-guilde","title":"RBAC Setup Guide","description":"This guide provides detailed instructions for configuring Role-Based Access Control (RBAC) in a Solace Agent Mesh (SAM) Enterprise Docker installation. RBAC allows you to control access to SAM Enterprise features and resources based on user roles and permissions.","sidebar":"docSidebar"},"documentation/Enterprise/single-sign-on":{"id":"documentation/Enterprise/single-sign-on","title":"SSO","description":"How to enable SSO","sidebar":"docSidebar"},"documentation/getting-started/component-overview":{"id":"documentation/getting-started/component-overview","title":"Component Overview","description":"Solace Agent Mesh is built on event-driven architecture principles using the A2A (Agent-to-Agent) protocol, with all components communicating through a standardized protocol over the Solace broker. This architectural choice enables loose coupling between components, making the system highly flexible and scalable.","sidebar":"docSidebar"},"documentation/getting-started/configurations/configurations":{"id":"documentation/getting-started/configurations/configurations","title":"Configurations","description":"Shared Configurations","sidebar":"docSidebar"},"documentation/getting-started/configurations/litellm_models":{"id":"documentation/getting-started/configurations/litellm_models","title":"LLM Models","description":"Configuring Different LLM Providers","sidebar":"docSidebar"},"documentation/getting-started/installation":{"id":"documentation/getting-started/installation","title":"Installation","description":"Before you begin, make sure you have the following:","sidebar":"docSidebar"},"documentation/getting-started/introduction":{"id":"documentation/getting-started/introduction","title":"Introduction","description":"Solace Agent Mesh","sidebar":"docSidebar"},"documentation/getting-started/quick-start":{"id":"documentation/getting-started/quick-start","title":"Quick Start","description":"To get started with Solace Agent Mesh, you can either use the preset configuration from the Docker image or create your own complete project.","sidebar":"docSidebar"},"documentation/Migrations/A2A Upgrade To 0.3.0/a2a-gateway-upgrade-to-0.3.0":{"id":"documentation/Migrations/A2A Upgrade To 0.3.0/a2a-gateway-upgrade-to-0.3.0","title":"Solace Agent Mesh Gateway Migration Guide: Upgrading to the A2A SDK","description":"This guide is for developers who have built or are maintaining a custom Solace Agent Mesh gateway. A recent architectural update has aligned Solace Agent Mesh with the official Agent-to-Agent (A2A) protocol","sidebar":"docSidebar"},"documentation/Migrations/A2A Upgrade To 0.3.0/a2a-technical-migration-map":{"id":"documentation/Migrations/A2A Upgrade To 0.3.0/a2a-technical-migration-map","title":"A2A Technical Migration Map","description":"This document provides a comprehensive, technical mapping for migrating Solace Agent Mesh components from the legacy A2A implementation to the new a2a-sdk-based protocol. It is designed to be used as a reference for automated or semi-automated code refactoring.","sidebar":"docSidebar"},"documentation/tutorials/bedrock-agents":{"id":"documentation/tutorials/bedrock-agents","title":"Amazon Bedrock Agents","description":"This tutorial walks you through the process of integrating Amazon Bedrock Agents and Flows into Solace Agent Mesh. This integration allows you to create agents that can interact with one or multiple Bedrock Agents or Flows, extending your Solace Agent Mesh project with powerful AI capabilities from AWS.","sidebar":"docSidebar"},"documentation/tutorials/custom-agent":{"id":"documentation/tutorials/custom-agent","title":"Build Your Own Agent","description":"This tutorial shows you how to build a sophisticated weather agent using the Solace Agent Mesh framework. Learn how to integrate with external APIs, manage resources properly, and create production-ready agents.","sidebar":"docSidebar"},"documentation/tutorials/event-mesh-gateway":{"id":"documentation/tutorials/event-mesh-gateway","title":"Event Mesh Gateway","description":"If you already have an event mesh in place, you can integrate Solace Agent Mesh into it. This allows you to leverage existing infrastructure while introducing intelligence and automation through Solace Agent Mesh.","sidebar":"docSidebar"},"documentation/tutorials/mcp-integration":{"id":"documentation/tutorials/mcp-integration","title":"MCP Integration","description":"This tutorial walks you through the process of integrating a Model Context Protocol (MCP) Server into Solace Agent Mesh.","sidebar":"docSidebar"},"documentation/tutorials/mongodb-integration":{"id":"documentation/tutorials/mongodb-integration","title":"MongoDB Integration","description":"This tutorial sets up a MongoDB agent in Solace Agent Mesh, which allows the Solace Agent Mesh agent to answer natural language queries about a Mongo database. The agent translates user questions into MongoDB aggregation pipelines and executes them against your database.","sidebar":"docSidebar"},"documentation/tutorials/rag-integration":{"id":"documentation/tutorials/rag-integration","title":"RAG Integration","description":"This tutorial guides you through setting up and configuring Solace Agent Mesh Retrieval Augmented Generation (RAG) plugin. The RAG plugin enables your agents to answer questions by retrieving information from a knowledge base of your documents.","sidebar":"docSidebar"},"documentation/tutorials/rest-gateway":{"id":"documentation/tutorials/rest-gateway","title":"REST Gateway","description":"Solace Agent Mesh REST API Gateway provides a standard, robust, and secure HTTP-based entry point for programmatic and system-to-system integrations. It allows external clients to submit tasks to Solace Agent Mesh agents, manage files, and discover agent capabilities using a familiar RESTful interface.","sidebar":"docSidebar"},"documentation/tutorials/slack-integration":{"id":"documentation/tutorials/slack-integration","title":"Slack Integration","description":"This tutorial integrates a Slack interface into Solace Agent Mesh, enabling interaction with the system directly from your Slack workspace and channels.","sidebar":"docSidebar"},"documentation/tutorials/sql-database":{"id":"documentation/tutorials/sql-database","title":"SQL Database Integration","description":"This tutorial sets up a SQL database agent in Solace Agent Mesh, which allows the Solace Agent Mesh agent to answer natural language queries about a sample coffee company database. This tutorial provides some sample data to set up an SQLite database, but you can use the same approach to connect to other database types, such as MySQL or PostgreSQL.","sidebar":"docSidebar"},"documentation/user-guide/builtin-tools/artifact-management":{"id":"documentation/user-guide/builtin-tools/artifact-management","title":"Artifact Management Tools","description":"This guide details how agents utilize built-in tools to manage file artifacts and their associated metadata. The system employs an explicit, metadata-aware methodology wherein the agent maintains full control over the lifecycle of artifacts, including their creation, listing, loading, and return.","sidebar":"docSidebar"},"documentation/user-guide/builtin-tools/audio-tools":{"id":"documentation/user-guide/builtin-tools/audio-tools","title":"Audio Tools","description":"This guide provides technical documentation for the text-to-speech (TTS) tools available in Solace Agent Mesh.","sidebar":"docSidebar"},"documentation/user-guide/builtin-tools/builtin-tools":{"id":"documentation/user-guide/builtin-tools/builtin-tools","title":"Configuring Built-in Tools","description":"This guide provides instructions for enabling and configuring the built-in tools provided by Solace Agent Mesh framework.","sidebar":"docSidebar"},"documentation/user-guide/builtin-tools/data-analysis-tools":{"id":"documentation/user-guide/builtin-tools/data-analysis-tools","title":"Data Analysis Tools","description":"Solace Agent Mesh includes a suite of optional built-in tools that enable agents to perform data analysis tasks directly on artifacts. These tools provide functionality for SQL querying, JQ transformations, and Plotly chart generation.","sidebar":"docSidebar"},"documentation/user-guide/builtin-tools/embeds":{"id":"documentation/user-guide/builtin-tools/embeds","title":"Dynamic Embeds","description":"Dynamic Embeds","sidebar":"docSidebar"},"documentation/user-guide/create-agents":{"id":"documentation/user-guide/create-agents","title":"Create Agents","description":"Introduction","sidebar":"docSidebar"},"documentation/user-guide/create-gateways":{"id":"documentation/user-guide/create-gateways","title":"Create Gateways","description":"Gateways in Solace Agent Mesh serve as bridges between external systems and the A2A (Agent-to-Agent) ecosystem. They enable your agents to receive information from and send responses to diverse external platforms like chat systems, web applications, IoT devices, APIs, and file systems.","sidebar":"docSidebar"},"documentation/user-guide/creating-python-tools":{"id":"documentation/user-guide/creating-python-tools","title":"Creating Python Tools","description":"Solace Agent Mesh provides a powerful and unified system for creating custom agent tools using Python. This is the primary way to extend an agent\'s capabilities with your own business logic, integrate with proprietary APIs, or perform specialized data processing.","sidebar":"docSidebar"},"documentation/user-guide/creating-service-providers":{"id":"documentation/user-guide/creating-service-providers","title":"Creating Service Providers","description":"This guide details the process for developers to create service provider plugins for integrating backend systems (for example, HR platforms, CRMs) with Solace Agent Mesh.","sidebar":"docSidebar"},"documentation/user-guide/solace-ai-connector":{"id":"documentation/user-guide/solace-ai-connector","title":"Solace AI Event Connector","description":"The Solace AI Event Connector is an important part of Solace Agent Mesh. It is a powerful tool designed to seamlessly integrate AI capabilities into your event-driven architecture. It enables you to create efficient pipelines that can process events from the Solace event brokers, using AI and other types of components, and then publish the results back to the Solace event brokers.","sidebar":"docSidebar"},"documentation/user-guide/structure":{"id":"documentation/user-guide/structure","title":"Structure","description":"Solace Agent Mesh is built on the A2A (Agent-to-Agent) protocol architecture, powered by Solace AI Event Connector and uses the Solace broker as the communication backbone. The framework is controlled by YAML configuration files that define agents, gateways, and plugins, enabling distributed AI agent communication through event-driven messaging.","sidebar":"docSidebar"}}}}')}}]);

solace_agent_mesh/assets/docs/assets/js/f897a61a.126663fe.js DELETED Viewed

@@ -1 +0,0 @@

- "use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[3514],{4373:(e,n,t)=>{t.r(n),t.d(n,{assets:()=>l,contentTitle:()=>r,default:()=>h,frontMatter:()=>i,metadata:()=>o,toc:()=>c});const o=JSON.parse('{"id":"documentation/getting-started/quick-start","title":"Quick Start","description":"To get started with Solace Agent Mesh, you can either use the preset configuration from the Docker image or create your own complete project.","source":"@site/docs/documentation/getting-started/quick-start.md","sourceDirName":"documentation/getting-started","slug":"/documentation/getting-started/quick-start","permalink":"/solace-agent-mesh/docs/documentation/getting-started/quick-start","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/getting-started/quick-start.md","tags":[],"version":"current","sidebarPosition":30,"frontMatter":{"title":"Quick Start","sidebar_position":30},"sidebar":"docSidebar","previous":{"title":"Installation","permalink":"/solace-agent-mesh/docs/documentation/getting-started/installation"},"next":{"title":"Component Overview","permalink":"/solace-agent-mesh/docs/documentation/getting-started/component-overview"}}');var s=t(4848),a=t(8453);const i={title:"Quick Start",sidebar_position:30},r="Quick Start",l={},c=[{value:"Use Preset Agents",id:"use-preset-agents",level:2},{value:"Prerequisites",id:"prerequisites",level:3},{value:"Run Preset Agents",id:"run-preset-agents",level:3},{value:"Create a Project",id:"create-a-project",level:2},{value:"Prerequisites",id:"prerequisites-1",level:3},{value:"Running the Project",id:"running-the-project",level:2},{value:"Interacting with Solace Agent Mesh",id:"interacting-with-solace-agent-mesh",level:2},{value:"Try a Tutorial",id:"try-a-tutorial",level:2},{value:"Next Steps",id:"next-steps",level:2}];function d(e){const n={a:"a",admonition:"admonition",code:"code",h1:"h1",h2:"h2",h3:"h3",header:"header",li:"li",ol:"ol",p:"p",pre:"pre",strong:"strong",ul:"ul",...(0,a.R)(),...e.components},{Details:t}=n;return t||function(e,n){throw new Error("Expected "+(n?"component":"object")+" `"+e+"` to be defined: you likely forgot to import, pass, or provide it.")}("Details",!0),(0,s.jsxs)(s.Fragment,{children:[(0,s.jsx)(n.header,{children:(0,s.jsx)(n.h1,{id:"quick-start",children:"Quick Start"})}),"\n",(0,s.jsx)(n.p,{children:"To get started with Solace Agent Mesh, you can either use the preset configuration from the Docker image or create your own complete project."}),"\n",(0,s.jsx)(n.h2,{id:"use-preset-agents",children:"Use Preset Agents"}),"\n",(0,s.jsx)(n.h3,{id:"prerequisites",children:"Prerequisites"}),"\n",(0,s.jsxs)(n.ol,{children:["\n",(0,s.jsx)(n.li,{children:"You must have Docker (or Podman) installed."}),"\n",(0,s.jsx)(n.li,{children:"You must have an available AI provider and API key. For best results, use a state-of-the-art AI model like Anthropic Claude Sonnet 4, Google Gemini 2.5 pro, or OpenAI GPT-5."}),"\n"]}),"\n",(0,s.jsx)(n.h3,{id:"run-preset-agents",children:"Run Preset Agents"}),"\n",(0,s.jsx)(n.p,{children:"You can run pre-made Solace Agent Mesh agents to quickly get started with Solace Agent Mesh without needing to set up a project from scratch."}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-sh",children:"docker run --rm -it -p 8000:8000 --platform linux/amd64 --env-file <your-env-file-path> solace/solace-agent-mesh:latest\n"})}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:["Provide the required environment variables. You can also pass them as command-line arguments using the ",(0,s.jsx)(n.code,{children:"-e"})," flag."]}),"\n"]}),"\n",(0,s.jsx)(n.p,{children:"Alternatively, you can combine your project with the preset app or only run specific agents from it."}),"\n",(0,s.jsxs)(n.p,{children:["You can find a list of all available preset apps in the ",(0,s.jsx)(n.a,{href:"https://github.com/SolaceLabs/solace-agent-mesh/tree/main/preset/agents",children:"Solace Agent Mesh GitHub repository"}),"."]}),"\n",(0,s.jsxs)(n.admonition,{type:"tip",children:[(0,s.jsx)(n.p,{children:"To run your custom agent without creating a new project, you can use the Docker image as follows:"}),(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-bash",children:"docker run --rm -it --platform linux/amd64 -p 8000:8000 -v $(pwd):/app \\\n -e LLM_SERVICE_ENDPOINT=<your-llm-endpoint> \\\n -e LLM_SERVICE_API_KEY=<your-llm-api-key> \\\n -e LLM_SERVICE_PLANNING_MODEL_NAME=<your-llm-planning-model-name> \\\n -e LLM_SERVICE_GENERAL_MODEL_NAME=<your-llm-general-model-name> \\\n solace/solace-agent-mesh:latest run /preset/agents/basic /app/my-agent\n"})}),(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:["You can update ",(0,s.jsx)(n.code,{children:"/app/my-agent"})," with the path to your agent YAML config. Note: You will still need either a ",(0,s.jsx)(n.code,{children:"shared_config.yaml"})," file or to hard code the settings in your agent configuration."]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.code,{children:"/preset/agents/basic"})," only runs the required agents, you can use ",(0,s.jsx)(n.code,{children:"/preset/agents"})," to load all agents."]}),"\n",(0,s.jsx)(n.li,{children:"This example command only has the minimum required environment variables."}),"\n"]})]}),"\n",(0,s.jsx)(n.h2,{id:"create-a-project",children:"Create a Project"}),"\n",(0,s.jsx)(n.admonition,{title:"Plugins",type:"note",children:(0,s.jsxs)(n.p,{children:["Looking to get started with plugins? For more information, see the ",(0,s.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/concepts/plugins",children:"Plugins"}),"."]})}),"\n",(0,s.jsx)(n.h3,{id:"prerequisites-1",children:"Prerequisites"}),"\n",(0,s.jsxs)(n.ol,{children:["\n",(0,s.jsxs)(n.li,{children:["You must have installed the Solace Agent Mesh CLI. If not, see the ",(0,s.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/getting-started/installation",children:"Installation"})," page."]}),"\n",(0,s.jsxs)(n.li,{children:["You must have activated the virtual environment you created following the ",(0,s.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/getting-started/installation",children:"Installation"})," page. For containerized deployment such as Docker, ignore this prerequisite."]}),"\n",(0,s.jsx)(n.li,{children:"You must have an available AI provider and API key. For best results, use a state-of-the-art AI model like Anthropic Claude Sonnet 4, Google Gemini 2.5 pro, or OpenAI GPT-5."}),"\n"]}),"\n",(0,s.jsx)(n.p,{children:"Create a directory for your project and navigate to it."}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-sh",children:"mkdir my-agent-mesh\ncd my-agent-mesh\n"})}),"\n",(0,s.jsxs)(n.p,{children:["Run the ",(0,s.jsx)(n.code,{children:"init"})," command and follow the prompts to create your project."]}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-sh",children:"solace-agent-mesh init\n"})}),"\n",(0,s.jsxs)(n.p,{children:["During initialization, you can choose to configure your project directly in the terminal or through a web-based interface launched at ",(0,s.jsx)(n.code,{children:"http://127.0.0.1:5002"}),". You are asked for your preference once you run ",(0,s.jsx)(n.code,{children:"solace-agent-mesh init"}),"."]}),"\n",(0,s.jsxs)(n.p,{children:["Alternatively, you can use the ",(0,s.jsx)(n.code,{children:"--gui"})," flag to skip the prompt and directly open the web-based configuration interface:"]}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-sh",children:"solace-agent-mesh init --gui\n"})}),"\n",(0,s.jsxs)(t,{children:[(0,s.jsx)("summary",{children:"Docker Alternative for Initialization"}),(0,s.jsx)(n.p,{children:"You can also initialize your Solace Agent Mesh project using the official Docker image. This is helpful if you want to avoid local Python/Solace Agent Mesh CLI installation or prefer a containerized workflow from the start."}),(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-sh",children:'docker run --rm -it -v "$(pwd):/app" --platform linux/amd64 -p 5002:5002 solace/solace-agent-mesh:latest init --gui\n'})}),(0,s.jsx)(n.p,{children:"If the OS architecture on your host is not linux/amd64, you must add --platform linux/amd64 when you run the container."}),(0,s.jsxs)(n.p,{children:["For Broker Setup, do not select the Broker Type ",(0,s.jsx)(n.code,{children:"New local Solace broker container"}),". This option is incompatible with Docker deployments because the ",(0,s.jsx)(n.code,{children:"Download and Run Container"})," action attempts to download a container image from within the already running container, which causes the operation to fail."]})]}),"\n",(0,s.jsxs)(n.admonition,{title:"Non-Interactive Mode",type:"tip",children:[(0,s.jsxs)(n.p,{children:["You can run the ",(0,s.jsx)(n.code,{children:"init"})," command in a non-interactive mode by passing ",(0,s.jsx)(n.code,{children:"--skip"})," and all the other configurations as arguments."]}),(0,s.jsxs)(n.p,{children:["To get a list of all the available options, run ",(0,s.jsx)(n.code,{children:"solace-agent-mesh init --help"})]})]}),"\n",(0,s.jsxs)(n.admonition,{title:"Model name format",type:"info",children:[(0,s.jsxs)(t,{children:[(0,s.jsx)("summary",{children:"Browser-based Configurations"}),(0,s.jsx)(n.p,{children:"You need to select the LLM Provider first and supported models are populated under LLM Model Name."}),(0,s.jsxs)(n.p,{children:["If you're using a non-openai model but hosting it on a custom API that follows the OpenAI standards, like Ollama or LiteLLM, you can select the ",(0,s.jsx)(n.code,{children:"OpenAI Compatible Provider"}),"."]})]}),(0,s.jsxs)(t,{children:[(0,s.jsx)("summary",{children:"CLI-based Configurations"}),(0,s.jsxs)(n.p,{children:["You need to explicitly specify the model in the format provider/name. For example, ",(0,s.jsx)(n.code,{children:"openai/gpt-4o"}),"."]}),(0,s.jsxs)(n.p,{children:["If you're using a non-openai model but hosting it on a custom API that follows the OpenAI standards, like Ollama or LiteLLM, you can still use the ",(0,s.jsx)(n.code,{children:"openai"})," provider."]}),(0,s.jsxs)(n.p,{children:["For example: ",(0,s.jsx)(n.code,{children:"openai/llama-3.3-7b"})]})]}),(0,s.jsx)(n.p,{children:"This is the case for all the model names, such as LLMs, image generators, embedding models, etc."})]}),"\n",(0,s.jsx)(n.h2,{id:"running-the-project",children:"Running the Project"}),"\n",(0,s.jsxs)(n.p,{children:["To run the project, you can use the ",(0,s.jsx)(n.code,{children:"run"})," command to execute all the components in a single, multi-threaded application. It's possible to split the components into separate processes. See the ",(0,s.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/deployment/deploy",children:"deployment"})," page for more information."]}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-sh",children:"solace-agent-mesh run\n"})}),"\n",(0,s.jsx)(n.admonition,{type:"tip",children:(0,s.jsxs)(n.p,{children:["Environment variables are loaded from your configuration file (typically a ",(0,s.jsx)(n.code,{children:".env"})," file at the project root) by default. To use system environment variables instead, use the ",(0,s.jsx)(n.code,{children:"-u"})," or ",(0,s.jsx)(n.code,{children:"--system-env"})," option."]})}),"\n",(0,s.jsxs)(n.p,{children:["To learn more about the other CLI commands, see the ",(0,s.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/concepts/cli",children:"CLI documentation"}),"."]}),"\n",(0,s.jsxs)(t,{children:[(0,s.jsx)("summary",{children:"Docker Alternative for Running the Project"}),(0,s.jsx)(n.p,{children:"You can also run your Solace Agent Mesh project using the official Docker image. This is helpful if you want to avoid local Python/Solace Agent Mesh CLI installation or prefer a containerized workflow from the start."}),(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-sh",children:'docker run --rm -it -v "$(pwd):/app" --platform linux/amd64 -p 8000:8000 solace/solace-agent-mesh:latest run\n'})}),(0,s.jsxs)(n.p,{children:["If your host system architecture is not ",(0,s.jsx)(n.code,{children:"linux/amd64"}),", add the ",(0,s.jsx)(n.code,{children:"--platform linux/amd64"})," flag when you run the container."]}),(0,s.jsxs)(n.admonition,{title:"Required Configurations",type:"info",children:[(0,s.jsx)(n.p,{children:"For deployments that use the official Docker image, ensure the following:"}),(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsx)(n.li,{children:"Do not use a local Solace broker container."}),"\n",(0,s.jsxs)(n.li,{children:["Set the environment variables ",(0,s.jsx)(n.code,{children:'FASTAPI_HOST="0.0.0.0"'})," in your ",(0,s.jsx)(n.code,{children:".env"})," file or system environment variables. This is necessary to expose the FastAPI server to the host machine."]}),"\n"]})]}),(0,s.jsxs)(n.admonition,{type:"warning",children:[(0,s.jsx)(n.p,{children:"If you are using third-party Python packages or Solace Agent Mesh plugins, you need to build a custom Docker image off the official image and install the required packages there, and then run that custom image instead."}),(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-Dockerfile",children:'FROM solace/solace-agent-mesh:latest\n# Option 1: Install a specific package\nRUN python3.11 -m pip install --no-cache-dir <your-package>\n# Option 2: use a requirements.txt file\nCOPY requirements.txt .\nRUN python3.11 -m pip install --no-cache-dir -r requirements.txt\n\nENTRYPOINT ["solace-agent-mesh"]\n'})}),(0,s.jsx)(n.p,{children:"Then build and run your custom image:"}),(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-sh",children:'docker build --platform linux/amd64 -t my-custom-image .\ndocker run --rm -it -v "$(pwd):/app" --platform linux/amd64 -p 8000:8000 my-custom-image run\n'})})]})]}),"\n",(0,s.jsx)(n.h2,{id:"interacting-with-solace-agent-mesh",children:"Interacting with Solace Agent Mesh"}),"\n",(0,s.jsx)(n.p,{children:"You can use different gateway interfaces to communicate with the system such as REST, Web UI, Slack, MS Teams, and so on. To keep it simple for this demo, we use the browser UI."}),"\n",(0,s.jsxs)(n.p,{children:["To access the browser UI, navigate to ",(0,s.jsx)(n.code,{children:"http://localhost:8000"})," in your web browser. If you specified a different port during the init step, use that port instead. For Docker deployments with custom port mappings (using the ",(0,s.jsx)(n.code,{children:"-p"})," flag), use the host port specified in your port mapping configuration."]}),"\n",(0,s.jsxs)(n.p,{children:["Try some commands like ",(0,s.jsx)(n.code,{children:"Suggest some good outdoor activities in London given the season and current weather conditions."}),"."]}),"\n",(0,s.jsx)(n.h2,{id:"try-a-tutorial",children:"Try a Tutorial"}),"\n",(0,s.jsxs)(n.p,{children:["Try adding a new agent to the system by following the tutorial on adding an ",(0,s.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/tutorials/sql-database",children:"SQL database agent"}),". This tutorial guides you through the process of adding the SQL agent plugin and adding some sample data to the database."]}),"\n",(0,s.jsx)(n.h2,{id:"next-steps",children:"Next Steps"}),"\n",(0,s.jsxs)(n.p,{children:["Solace Agent Mesh uses two main types of components, ",(0,s.jsx)(n.strong,{children:"agents"})," and ",(0,s.jsx)(n.strong,{children:"gateways"}),". The system comes with a built-in orchestrator agent and a web user interface gateway (which you enabled during the ",(0,s.jsx)(n.code,{children:"init"})," step)."]}),"\n",(0,s.jsxs)(n.p,{children:["You can learn more about ",(0,s.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/concepts/gateways",children:"gateways"}),". Alternatively, you can learn about ",(0,s.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/concepts/plugins#use-a-plugin",children:"using plugins"})," or ",(0,s.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/user-guide/create-gateways",children:"creating your own new gateways"}),"."]}),"\n",(0,s.jsxs)(n.p,{children:["Also, you can learn more about ",(0,s.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/concepts/agents",children:"agents"})," or about ",(0,s.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/user-guide/create-agents",children:"creating your own agents"}),"."]})]})}function h(e={}){const{wrapper:n}={...(0,a.R)(),...e.components};return n?(0,s.jsx)(n,{...e,children:(0,s.jsx)(d,{...e})}):d(e)}},8453:(e,n,t)=>{t.d(n,{R:()=>i,x:()=>r});var o=t(6540);const s={},a=o.createContext(s);function i(e){const n=o.useContext(a);return o.useMemo((function(){return"function"==typeof e?e(n):{...n,...e}}),[n,e])}function r(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(s):e.components||s:i(e.components),o.createElement(a.Provider,{value:n},e.children)}}}]);

solace_agent_mesh/assets/docs/assets/js/fbfa3e75.e144b16c.js DELETED Viewed

@@ -1 +0,0 @@

- "use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[2424],{2998:(e,s,i)=>{i.r(s),i.d(s,{assets:()=>a,contentTitle:()=>l,default:()=>h,frontMatter:()=>r,metadata:()=>n,toc:()=>c});const n=JSON.parse('{"id":"documentation/deployment/observability","title":"Observability","description":"Solace Agent Mesh provides a comprehensive set of tools for real-time system monitoring and key insights to help you understand system states, request flows, and key insights for debugging and optimizing your system.","source":"@site/docs/documentation/deployment/observability.md","sourceDirName":"documentation/deployment","slug":"/documentation/deployment/observability","permalink":"/solace-agent-mesh/docs/documentation/deployment/observability","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/deployment/observability.md","tags":[],"version":"current","sidebarPosition":20,"frontMatter":{"title":"Observability","sidebar_position":20},"sidebar":"docSidebar","previous":{"title":"Deployment","permalink":"/solace-agent-mesh/docs/documentation/deployment/deploy"},"next":{"title":"Debugging","permalink":"/solace-agent-mesh/docs/documentation/deployment/debugging"}}');var t=i(4848),o=i(8453);const r={title:"Observability",sidebar_position:20},l="Observability",a={},c=[{value:"Workflow Viewer",id:"workflow-viewer",level:2},{value:"Agents View",id:"agents-view",level:2},{value:"Broker Observability",id:"broker-observability",level:2},{value:"Stimulus Logs",id:"stimulus-logs",level:2}];function d(e){const s={a:"a",admonition:"admonition",code:"code",em:"em",h1:"h1",h2:"h2",header:"header",li:"li",p:"p",pre:"pre",strong:"strong",ul:"ul",...(0,o.R)(),...e.components};return(0,t.jsxs)(t.Fragment,{children:[(0,t.jsx)(s.header,{children:(0,t.jsx)(s.h1,{id:"observability",children:"Observability"})}),"\n",(0,t.jsx)(s.p,{children:"Solace Agent Mesh provides a comprehensive set of tools for real-time system monitoring and key insights to help you understand system states, request flows, and key insights for debugging and optimizing your system."}),"\n",(0,t.jsx)(s.h2,{id:"workflow-viewer",children:"Workflow Viewer"}),"\n",(0,t.jsx)(s.p,{children:"The Solace Agent Mesh web UI includes a built-in workflow viewer, which provides an interactive web-based UI for each user query and its corresponding response. This visualizer allows you to:"}),"\n",(0,t.jsxs)(s.ul,{children:["\n",(0,t.jsx)(s.li,{children:"Track the complete life cycle of a stimulus (request) as it moves through the system."}),"\n",(0,t.jsx)(s.li,{children:"Visualize the flow of requests/responses among agents, the user gateway and LLM."}),"\n",(0,t.jsx)(s.li,{children:"Monitor all participating agents and their activity in real-time."}),"\n"]}),"\n",(0,t.jsxs)(s.p,{children:["To launch the workflow viewer for a specific query/response pair, click the ",(0,t.jsx)(s.strong,{children:"View Agent Workflow"})," icon located at the bottom left of the final response. The complete workflow chart appears in the side panel on the right."]}),"\n",(0,t.jsx)(s.h2,{id:"agents-view",children:"Agents View"}),"\n",(0,t.jsxs)(s.p,{children:["The Solace Agent Mesh web UI also includes an ",(0,t.jsx)(s.strong,{children:"Agents"})," view, which provides a comprehensive overview of all registered agents in the system in real-time. This view allows you to:"]}),"\n",(0,t.jsxs)(s.ul,{children:["\n",(0,t.jsx)(s.li,{children:"See all agents currently registered in the system."}),"\n",(0,t.jsx)(s.li,{children:"View agents description, capabilities, and skills"}),"\n",(0,t.jsx)(s.li,{children:"View agent hierarchical topology and relationships."}),"\n"]}),"\n",(0,t.jsxs)(s.p,{children:["To access the Agents view, open the web interface in your browser and switch to the ",(0,t.jsx)(s.strong,{children:"Agents"})," tab."]}),"\n",(0,t.jsx)(s.h2,{id:"broker-observability",children:"Broker Observability"}),"\n",(0,t.jsx)(s.p,{children:"Solace Agent Mesh relies on a Solace event broker for all its communication. Various tools are available to monitor the event broker\u2019s activity and message flows:"}),"\n",(0,t.jsxs)(s.ul,{children:["\n",(0,t.jsxs)(s.li,{children:[(0,t.jsx)(s.strong,{children:"Solace Broker Manager"})," \u2013 A web-based interface where you can use the ",(0,t.jsx)(s.em,{children:"Try Me!"})," tab to send and receive messages interactively."]}),"\n",(0,t.jsxs)(s.li,{children:[(0,t.jsx)(s.strong,{children:(0,t.jsx)(s.a,{href:"https://marketplace.visualstudio.com/items?itemName=solace-tools.solace-try-me-vsc-extension",children:"Solace Try Me VSCode Extension"})})," \u2013 A convenient way to test message flows within Visual Studio Code."]}),"\n",(0,t.jsxs)(s.li,{children:[(0,t.jsx)(s.strong,{children:(0,t.jsx)(s.a,{href:"https://github.com/SolaceLabs/solace-tryme-cli",children:"Solace Try Me (STM) CLI Tool"})})," \u2013 A command-line tool for sending and receiving messages."]}),"\n"]}),"\n",(0,t.jsx)(s.p,{children:"To observe all message flows within the event broker, subscribe to the following topic:"}),"\n",(0,t.jsx)(s.pre,{children:(0,t.jsx)(s.code,{children:"[NAME_SPACES]a2a/v1/>\n"})}),"\n",(0,t.jsxs)(s.p,{children:["Replace ",(0,t.jsx)(s.code,{children:"[NAME_SPACES]"})," with the namespace you are using. If none, omit the ",(0,t.jsx)(s.code,{children:"[NAME_SPACES]"})," part."]}),"\n",(0,t.jsxs)(s.admonition,{type:"tip",children:[(0,t.jsx)(s.p,{children:"Agents periodically send registration messages, which may clutter your UI if you're using the STM VSCode extension. To filter out these messages, you can add the following topic to the ignore list:"}),(0,t.jsx)(s.pre,{children:(0,t.jsx)(s.code,{children:"[NAME_SPACES]/a2a/v1/discovery/agentcards\n"})})]}),"\n",(0,t.jsx)(s.h2,{id:"stimulus-logs",children:"Stimulus Logs"}),"\n",(0,t.jsxs)(s.p,{children:["Solace Agent Mesh includes a default monitor that records each request (stimulus) life cycle. These logs are stored as ",(0,t.jsx)(s.code,{children:".stim"})," files."]}),"\n",(0,t.jsxs)(s.p,{children:["Each ",(0,t.jsx)(s.code,{children:".stim"})," file captures a complete trace of a stimulus, including:"]}),"\n",(0,t.jsxs)(s.ul,{children:["\n",(0,t.jsx)(s.li,{children:"Every component it passed through."}),"\n",(0,t.jsx)(s.li,{children:"Timing and sequencing details."}),"\n",(0,t.jsx)(s.li,{children:"Additional contextual metadata."}),"\n"]}),"\n",(0,t.jsx)(s.p,{children:"These logs provide a valuable data source for further visualization, troubleshooting, and performance analysis."}),"\n",(0,t.jsxs)(s.p,{children:["By default, ",(0,t.jsx)(s.code,{children:".stim"})," files are written to the ",(0,t.jsx)(s.code,{children:"/tmp/solace-agent-mesh/"})," directory."]})]})}function h(e={}){const{wrapper:s}={...(0,o.R)(),...e.components};return s?(0,t.jsx)(s,{...e,children:(0,t.jsx)(d,{...e})}):d(e)}},8453:(e,s,i)=>{i.d(s,{R:()=>r,x:()=>l});var n=i(6540);const t={},o=n.createContext(t);function r(e){const s=n.useContext(o);return n.useMemo((function(){return"function"==typeof e?e(s):{...s,...e}}),[s,e])}function l(e){let s;return s=e.disableParentContext?"function"==typeof e.components?e.components(t):e.components||t:r(e.components),n.createElement(o.Provider,{value:s},e.children)}}}]);

solace-agent-mesh 1.5.0__py3-none-any.whl → 1.6.0__py3-none-any.whl

Potentially problematic release.

solace-agent-mesh 1.5.0py3-none-any.whl → 1.6.0py3-none-any.whl