solace-agent-mesh 1.4.6__py3-none-any.whl → 1.4.8__py3-none-any.whl

solace_agent_mesh/assets/docs/assets/js/{5b4258a4.dff11eca.js → 5b4258a4.fdfd2325.js}

@@ -1 +1 @@
-"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[7132],{8097:(e,n,t)=>{t.r(n),t.d(n,{assets:()=>c,contentTitle:()=>r,default:()=>h,frontMatter:()=>o,metadata:()=>a,toc:()=>l});const a=JSON.parse('{"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.","source":"@site/docs/documentation/tutorials/rest-gateway.md","sourceDirName":"documentation/tutorials","slug":"/documentation/tutorials/rest-gateway","permalink":"/solace-agent-mesh/docs/documentation/tutorials/rest-gateway","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/tutorials/rest-gateway.md","tags":[],"version":"current","sidebarPosition":15,"frontMatter":{"title":"REST Gateway","sidebar_position":15},"sidebar":"docSidebar","previous":{"title":"MCP Integration","permalink":"/solace-agent-mesh/docs/documentation/tutorials/mcp-integration"},"next":{"title":"Event Mesh Gateway","permalink":"/solace-agent-mesh/docs/documentation/tutorials/event-mesh-gateway"}}');var s=t(4848),i=t(8453);const o={title:"REST Gateway",sidebar_position:15},r=void 0,c={},l=[{value:"Key Features",id:"key-features",level:2},{value:"Setting Up the Environment",id:"setting-up-the-environment",level:2},{value:"Adding the REST Gateway Plugin",id:"adding-the-rest-gateway-plugin",level:2},{value:"Configuring the REST Gateway",id:"configuring-the-rest-gateway",level:3},{value:"Running the REST Gateway",id:"running-the-rest-gateway",level:2},{value:"Sending a Request via REST API",id:"sending-a-request-via-rest-api",level:2},{value:"Modern API (v2) - Asynchronous",id:"modern-api-v2---asynchronous",level:3},{value:"Legacy API (v1) - Synchronous",id:"legacy-api-v1---synchronous",level:3}];function d(e){const n={a:"a",admonition:"admonition",code:"code",h2:"h2",h3:"h3",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.p,{children:"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."}),"\n",(0,s.jsx)(n.p,{children:"The gateway is designed to be highly configurable and supports two distinct operational modes to cater to both modern, asynchronous workflows and legacy, synchronous systems."}),"\n",(0,s.jsx)(n.h2,{id:"key-features",children:"Key Features"}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Dual API Versions"}),": Supports both a modern asynchronous API (v2) and a deprecated synchronous API (v1) for backward compatibility."]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Asynchronous by Default"}),': The v2 API uses a "202 Accepted + Poll" pattern, ideal for long-running agent tasks.']}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Delegated Authentication"}),": Integrates with an external authentication service via bearer tokens for secure access."]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"File Handling"}),": Supports file uploads for tasks and provides download URLs for generated artifacts."]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Dynamic Configuration"}),": All gateway behaviors, including server settings and authentication, are configured via the main Solace Agent Mesh Host YAML file."]}),"\n"]}),"\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.jsx)(n.h2,{id:"adding-the-rest-gateway-plugin",children:"Adding the REST Gateway Plugin"}),"\n",(0,s.jsx)(n.p,{children:"Once you have your project set up, add the REST Gateway plugin:"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-sh",children:"sam plugin add my-http-rest --plugin sam-rest-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:"my-http-rest"}),"."]}),"\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-rest-gateway"})," plugin"]}),"\n",(0,s.jsxs)(n.li,{children:["Creates a new gateway configuration named ",(0,s.jsx)(n.code,{children:"my-http-rest"})," in your ",(0,s.jsx)(n.code,{children:"configs/gateways/"})," directory"]}),"\n"]}),"\n",(0,s.jsx)(n.h3,{id:"configuring-the-rest-gateway",children:"Configuring the REST Gateway"}),"\n",(0,s.jsxs)(n.p,{children:["For further configuration, you can edit the ",(0,s.jsx)(n.code,{children:"configs/gateways/my-http-rest.yaml"})," file. This file contains the gateway configuration that can be customized for your use case."]}),"\n",(0,s.jsxs)(n.admonition,{title:"Using local Solace PubSub+ Broker container",type:"info",children:[(0,s.jsxs)(n.p,{children:["Solace PubSub+ Broker container uses port 8080. You need to edit the ",(0,s.jsx)(n.code,{children:"rest_api_server_port"})," field and ",(0,s.jsx)(n.code,{children:"external_auth_service_url"})," field in the ",(0,s.jsx)(n.code,{children:"configs/gateways/my-http-rest.yaml"})," file to a free port other than 8080 (for example: 8081)."]}),(0,s.jsxs)(n.p,{children:["You can edit the YAML file directly or add environment variables ",(0,s.jsx)(n.code,{children:"REST_API_PORT=8081"})," and ",(0,s.jsx)(n.code,{children:"EXTERNAL_AUTH_SERVICE_URL=http://localhost:8081"}),"."]}),(0,s.jsx)(n.p,{children:"Make sure you change the REST API gateway to your new port in the following request examples."})]}),"\n",(0,s.jsx)(n.h2,{id:"running-the-rest-gateway",children:"Running the REST Gateway"}),"\n",(0,s.jsx)(n.p,{children:"To run the REST Gateway, use the following command:"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-sh",children:"sam run configs/gateways/my-http-rest.yaml\n"})}),"\n",(0,s.jsx)(n.h2,{id:"sending-a-request-via-rest-api",children:"Sending a Request via REST API"}),"\n",(0,s.jsxs)(n.p,{children:["You can also interact with Solace Agent Mesh via the ",(0,s.jsx)(n.strong,{children:"REST API"}),"."]}),"\n",(0,s.jsxs)(n.p,{children:["The REST API gateway runs on ",(0,s.jsx)(n.code,{children:"http://localhost:8080"})," by default. You can use either the legacy v1 API or the modern async v2 API."]}),"\n",(0,s.jsx)(n.h3,{id:"modern-api-v2---asynchronous",children:"Modern API (v2) - Asynchronous"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-sh",children:"# Submit task\ncurl --location 'http://localhost:8080/api/v2/tasks' \\\n--header 'Authorization: Bearer token' \\\n--form 'agent_name=\"OrchestratorAgent\"' \\\n--form 'prompt=\"Hi\\!\"'\n\n# Poll for result using returned task ID\ncurl --location 'http://localhost:8080/api/v2/tasks/{taskId}' \\\n--header 'Authorization: Bearer token'\n"})}),"\n",(0,s.jsx)(n.admonition,{type:"warning",children:(0,s.jsxs)(n.p,{children:["It might take a while for the system to respond. See the ",(0,s.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/deployment/observability",children:"observability"})," page for more information about monitoring the system while it processes the request."]})}),"\n",(0,s.jsx)(n.p,{children:"Sample output:"}),"\n",(0,s.jsxs)(n.p,{children:["From ",(0,s.jsx)(n.code,{children:"api/v2/tasks"})]}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-json",children:'{\n  "taskId":"task-6a0e682f4f6c4927a5997e4fd06eea83"\n}\n'})}),"\n",(0,s.jsxs)(n.p,{children:["From ",(0,s.jsx)(n.code,{children:"api/v2/tasks/{taskId}"})]}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-json",children:'{\n  "id": "task-6a0e682f4f6c4927a5997e4fd06eea83",\n  "sessionId": "rest-session-4df0c24fcecc45fcb69692db9876bc5c",\n  "status": {\n    "state": "completed",\n    "message": {\n      "role": "agent",\n      "parts": [{ "type": "text", "text": "Outdoor Activities in London: Spring Edition. Today\'s Perfect Activities (13\xb0C, Light Cloud): - Royal Parks Exploration : Hyde Park and Kensington Gardens..." }]\n    },\n    "timestamp": "2025-07-03T16:54:15.273085"\n  },\n  "artifacts": [],\n  "metadata": { "agent_name": "OrchestratorAgent" }\n}\n'})}),"\n",(0,s.jsx)(n.h3,{id:"legacy-api-v1---synchronous",children:"Legacy API (v1) - Synchronous"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-sh",children:"curl --location 'http://localhost:8080/api/v1/invoke' \\\n--header 'Authorization: Bearer None' \\\n--form 'prompt=\"Suggest some good outdoor activities in London given the season and current weather conditions.\"' \\\n--form 'agent_name=\"OrchestratorAgent\"' \\\n--form 'stream=\"false\"'\n"})}),"\n",(0,s.jsx)(n.p,{children:"Sample output:"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-json",children:'{\n  "id": "task-9f7d5f465f5a4f1ca799e8e5ecb35a43",\n  "sessionId": "rest-session-36b36eeb69b04da7b67708f90e5512dc",\n  "status": {\n    "state": "completed",\n    "message": {\n      "role": "agent",\n      "parts": [\n        { "type": "text", "text": "Outdoor Activities in London: Spring Edition. Today\'s Perfect Activities (13\xb0C, Light Cloud): - Royal Parks Exploration : Hyde Park and Kensington Gardens..." }\n      ]\n    },\n    "timestamp": "2025-07-03T16:59:37.486480"\n  },\n  "artifacts": [],\n  "metadata": { "agent_name": "OrchestratorAgent" }\n}\n'})})]})}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:()=>o,x:()=>r});var a=t(6540);const s={},i=a.createContext(s);function o(e){const n=a.useContext(i);return a.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:o(e.components),a.createElement(i.Provider,{value:n},e.children)}}}]);
+"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[7132],{8097:(e,n,t)=>{t.r(n),t.d(n,{assets:()=>c,contentTitle:()=>r,default:()=>h,frontMatter:()=>o,metadata:()=>a,toc:()=>l});const a=JSON.parse('{"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.","source":"@site/docs/documentation/tutorials/rest-gateway.md","sourceDirName":"documentation/tutorials","slug":"/documentation/tutorials/rest-gateway","permalink":"/solace-agent-mesh/docs/documentation/tutorials/rest-gateway","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/tutorials/rest-gateway.md","tags":[],"version":"current","sidebarPosition":15,"frontMatter":{"title":"REST Gateway","sidebar_position":15},"sidebar":"docSidebar","previous":{"title":"MCP Integration","permalink":"/solace-agent-mesh/docs/documentation/tutorials/mcp-integration"},"next":{"title":"Event Mesh Gateway","permalink":"/solace-agent-mesh/docs/documentation/tutorials/event-mesh-gateway"}}');var s=t(4848),i=t(8453);const o={title:"REST Gateway",sidebar_position:15},r=void 0,c={},l=[{value:"Key Features",id:"key-features",level:2},{value:"Setting Up the Environment",id:"setting-up-the-environment",level:2},{value:"Adding the REST Gateway Plugin",id:"adding-the-rest-gateway-plugin",level:2},{value:"Configuring the REST Gateway",id:"configuring-the-rest-gateway",level:3},{value:"Running the REST Gateway",id:"running-the-rest-gateway",level:2},{value:"Sending a Request via REST API",id:"sending-a-request-via-rest-api",level:2},{value:"Modern API (v2) - Asynchronous",id:"modern-api-v2---asynchronous",level:3},{value:"Legacy API (v1) - Synchronous",id:"legacy-api-v1---synchronous",level:3}];function d(e){const n={a:"a",admonition:"admonition",code:"code",h2:"h2",h3:"h3",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.p,{children:"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."}),"\n",(0,s.jsx)(n.p,{children:"The gateway is designed to be highly configurable and supports two distinct operational modes to cater to both modern, asynchronous workflows and legacy, synchronous systems."}),"\n",(0,s.jsx)(n.h2,{id:"key-features",children:"Key Features"}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Dual API Versions"}),": Supports both a modern asynchronous API (v2) and a deprecated synchronous API (v1) for backward compatibility."]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Asynchronous by Default"}),': The v2 API uses a "202 Accepted + Poll" pattern, ideal for long-running agent tasks.']}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Delegated Authentication"}),": Integrates with an external authentication service via bearer tokens for secure access."]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"File Handling"}),": Supports file uploads for tasks and provides download URLs for generated artifacts."]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Dynamic Configuration"}),": All gateway behaviors, including server settings and authentication, are configured via the main Solace Agent Mesh Host YAML file."]}),"\n"]}),"\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.jsx)(n.h2,{id:"adding-the-rest-gateway-plugin",children:"Adding the REST Gateway Plugin"}),"\n",(0,s.jsx)(n.p,{children:"Once you have your project set up, add the REST Gateway plugin:"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-sh",children:"sam plugin add my-http-rest --plugin sam-rest-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:"my-http-rest"}),"."]}),"\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-rest-gateway"})," plugin"]}),"\n",(0,s.jsxs)(n.li,{children:["Creates a new gateway configuration named ",(0,s.jsx)(n.code,{children:"my-http-rest"})," in your ",(0,s.jsx)(n.code,{children:"configs/gateways/"})," directory"]}),"\n"]}),"\n",(0,s.jsx)(n.h3,{id:"configuring-the-rest-gateway",children:"Configuring the REST Gateway"}),"\n",(0,s.jsxs)(n.p,{children:["For further configuration, you can edit the ",(0,s.jsx)(n.code,{children:"configs/gateways/my-http-rest.yaml"})," file. This file contains the gateway configuration that can be customized for your use case."]}),"\n",(0,s.jsxs)(n.admonition,{title:"Using a local Solace Broker container",type:"info",children:[(0,s.jsxs)(n.p,{children:["The Solace broker container uses port 8080. You need to edit the ",(0,s.jsx)(n.code,{children:"rest_api_server_port"})," field and ",(0,s.jsx)(n.code,{children:"external_auth_service_url"})," field in the ",(0,s.jsx)(n.code,{children:"configs/gateways/my-http-rest.yaml"})," file to a free port other than 8080 (for example: 8081)."]}),(0,s.jsxs)(n.p,{children:["You can edit the YAML file directly or add environment variables ",(0,s.jsx)(n.code,{children:"REST_API_PORT=8081"})," and ",(0,s.jsx)(n.code,{children:"EXTERNAL_AUTH_SERVICE_URL=http://localhost:8081"}),"."]}),(0,s.jsx)(n.p,{children:"Make sure you change the REST API gateway to your new port in the following request examples."})]}),"\n",(0,s.jsx)(n.h2,{id:"running-the-rest-gateway",children:"Running the REST Gateway"}),"\n",(0,s.jsx)(n.p,{children:"To run the REST Gateway, use the following command:"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-sh",children:"sam run configs/gateways/my-http-rest.yaml\n"})}),"\n",(0,s.jsx)(n.h2,{id:"sending-a-request-via-rest-api",children:"Sending a Request via REST API"}),"\n",(0,s.jsxs)(n.p,{children:["You can also interact with Solace Agent Mesh via the ",(0,s.jsx)(n.strong,{children:"REST API"}),"."]}),"\n",(0,s.jsxs)(n.p,{children:["The REST API gateway runs on ",(0,s.jsx)(n.code,{children:"http://localhost:8080"})," by default. You can use either the legacy v1 API or the modern async v2 API."]}),"\n",(0,s.jsx)(n.h3,{id:"modern-api-v2---asynchronous",children:"Modern API (v2) - Asynchronous"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-sh",children:"# Submit task\ncurl --location 'http://localhost:8080/api/v2/tasks' \\\n--header 'Authorization: Bearer token' \\\n--form 'agent_name=\"OrchestratorAgent\"' \\\n--form 'prompt=\"Hi\\!\"'\n\n# Poll for result using returned task ID\ncurl --location 'http://localhost:8080/api/v2/tasks/{taskId}' \\\n--header 'Authorization: Bearer token'\n"})}),"\n",(0,s.jsx)(n.admonition,{type:"warning",children:(0,s.jsxs)(n.p,{children:["It might take a while for the system to respond. See the ",(0,s.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/deployment/observability",children:"observability"})," page for more information about monitoring the system while it processes the request."]})}),"\n",(0,s.jsx)(n.p,{children:"Sample output:"}),"\n",(0,s.jsxs)(n.p,{children:["From ",(0,s.jsx)(n.code,{children:"api/v2/tasks"})]}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-json",children:'{\n  "taskId":"task-6a0e682f4f6c4927a5997e4fd06eea83"\n}\n'})}),"\n",(0,s.jsxs)(n.p,{children:["From ",(0,s.jsx)(n.code,{children:"api/v2/tasks/{taskId}"})]}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-json",children:'{\n  "id": "task-6a0e682f4f6c4927a5997e4fd06eea83",\n  "sessionId": "rest-session-4df0c24fcecc45fcb69692db9876bc5c",\n  "status": {\n    "state": "completed",\n    "message": {\n      "role": "agent",\n      "parts": [{ "type": "text", "text": "Outdoor Activities in London: Spring Edition. Today\'s Perfect Activities (13\xb0C, Light Cloud): - Royal Parks Exploration : Hyde Park and Kensington Gardens..." }]\n    },\n    "timestamp": "2025-07-03T16:54:15.273085"\n  },\n  "artifacts": [],\n  "metadata": { "agent_name": "OrchestratorAgent" }\n}\n'})}),"\n",(0,s.jsx)(n.h3,{id:"legacy-api-v1---synchronous",children:"Legacy API (v1) - Synchronous"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-sh",children:"curl --location 'http://localhost:8080/api/v1/invoke' \\\n--header 'Authorization: Bearer None' \\\n--form 'prompt=\"Suggest some good outdoor activities in London given the season and current weather conditions.\"' \\\n--form 'agent_name=\"OrchestratorAgent\"' \\\n--form 'stream=\"false\"'\n"})}),"\n",(0,s.jsx)(n.p,{children:"Sample output:"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-json",children:'{\n  "id": "task-9f7d5f465f5a4f1ca799e8e5ecb35a43",\n  "sessionId": "rest-session-36b36eeb69b04da7b67708f90e5512dc",\n  "status": {\n    "state": "completed",\n    "message": {\n      "role": "agent",\n      "parts": [\n        { "type": "text", "text": "Outdoor Activities in London: Spring Edition. Today\'s Perfect Activities (13\xb0C, Light Cloud): - Royal Parks Exploration : Hyde Park and Kensington Gardens..." }\n      ]\n    },\n    "timestamp": "2025-07-03T16:59:37.486480"\n  },\n  "artifacts": [],\n  "metadata": { "agent_name": "OrchestratorAgent" }\n}\n'})})]})}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:()=>o,x:()=>r});var a=t(6540);const s={},i=a.createContext(s);function o(e){const n=a.useContext(i);return a.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:o(e.components),a.createElement(i.Provider,{value:n},e.children)}}}]);

solace_agent_mesh/assets/docs/assets/js/{75384d09.abdf9cf9.js → 75384d09.c19e8b51.js}

@@ -1 +1 @@
-"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[8055],{5343:(e,n,t)=>{t.r(n),t.d(n,{assets:()=>l,contentTitle:()=>s,default:()=>h,frontMatter:()=>o,metadata:()=>i,toc:()=>c});const i=JSON.parse('{"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.","source":"@site/docs/documentation/tutorials/rag-integration.md","sourceDirName":"documentation/tutorials","slug":"/documentation/tutorials/rag-integration","permalink":"/solace-agent-mesh/docs/documentation/tutorials/rag-integration","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/tutorials/rag-integration.md","tags":[],"version":"current","sidebarPosition":70,"frontMatter":{"title":"RAG Integration","sidebar_position":70,"toc_max_heading_level":4},"sidebar":"docSidebar","previous":{"title":"Slack Integration","permalink":"/solace-agent-mesh/docs/documentation/tutorials/slack-integration"},"next":{"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"}}');var a=t(4848),r=t(8453);const o={title:"RAG Integration",sidebar_position:70,toc_max_heading_level:4},s="RAG Integration",l={},c=[{value:"What is Solace Agent Mesh RAG?",id:"what-is-solace-agent-mesh-rag",level:2},{value:"Prerequisites",id:"prerequisites",level:2},{value:"Adding the RAG Plugin",id:"adding-the-rag-plugin",level:2},{value:"Configuring the RAG Agent",id:"configuring-the-rag-agent",level:2},{value:"Shared Configuration",id:"shared-configuration",level:3},{value:"RAG Pipeline Configuration",id:"rag-pipeline-configuration",level:3},{value:"1. Scanner Configuration",id:"1-scanner-configuration",level:4},{value:"2. Preprocessor Configuration",id:"2-preprocessor-configuration",level:4},{value:"3. Splitter Configuration",id:"3-splitter-configuration",level:4},{value:"4. Embedding Configuration",id:"4-embedding-configuration",level:4},{value:"5. Vector Database Configuration",id:"5-vector-database-configuration",level:4},{value:"6. LLM Configuration",id:"6-llm-configuration",level:4},{value:"7. Retrieval Configuration",id:"7-retrieval-configuration",level:4},{value:"Environment Variables",id:"environment-variables",level:3},{value:"Running the RAG Agent",id:"running-the-rag-agent",level:2},{value:"Testing the RAG Agent",id:"testing-the-rag-agent",level:2},{value:"Ingesting Documents",id:"ingesting-documents",level:3},{value:"Option 1: Automatic Scanning (Batch Ingestion)",id:"option-1-automatic-scanning-batch-ingestion",level:4},{value:"Option 2: Manual Upload via Gateway",id:"option-2-manual-upload-via-gateway",level:4},{value:"Querying the Knowledge Base",id:"querying-the-knowledge-base",level:3},{value:"Troubleshooting",id:"troubleshooting",level:2}];function d(e){const n={a:"a",blockquote:"blockquote",code:"code",h1:"h1",h2:"h2",h3:"h3",h4:"h4",header:"header",li:"li",ol:"ol",p:"p",pre:"pre",strong:"strong",ul:"ul",...(0,r.R)(),...e.components};return(0,a.jsxs)(a.Fragment,{children:[(0,a.jsx)(n.header,{children:(0,a.jsx)(n.h1,{id:"rag-integration",children:"RAG Integration"})}),"\n",(0,a.jsx)(n.p,{children:"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."}),"\n",(0,a.jsx)(n.h2,{id:"what-is-solace-agent-mesh-rag",children:"What is Solace Agent Mesh RAG?"}),"\n",(0,a.jsx)(n.p,{children:"The Solace Agent Mesh RAG plugin enhances your agents with the ability to perform retrieval-augmented generation. This means the agent can:"}),"\n",(0,a.jsxs)(n.ul,{children:["\n",(0,a.jsxs)(n.li,{children:[(0,a.jsx)(n.strong,{children:"Scan"})," documents from various sources (local filesystem, Google Drive, etc.)."]}),"\n",(0,a.jsxs)(n.li,{children:[(0,a.jsx)(n.strong,{children:"Preprocess"})," and ",(0,a.jsx)(n.strong,{children:"split"})," the text into manageable chunks."]}),"\n",(0,a.jsxs)(n.li,{children:[(0,a.jsx)(n.strong,{children:"Embed"})," these chunks into vectors and store them in a vector database."]}),"\n",(0,a.jsxs)(n.li,{children:[(0,a.jsx)(n.strong,{children:"Retrieve"})," relevant chunks of text based on a user's query."]}),"\n",(0,a.jsxs)(n.li,{children:[(0,a.jsx)(n.strong,{children:"Generate"})," an answer using a large language model (LLM) augmented with the retrieved information."]}),"\n"]}),"\n",(0,a.jsx)(n.p,{children:"This allows you to build agents that can answer questions about your own private data."}),"\n",(0,a.jsx)(n.h2,{id:"prerequisites",children:"Prerequisites"}),"\n",(0,a.jsx)(n.p,{children:"Before you begin, ensure you have:"}),"\n",(0,a.jsxs)(n.ul,{children:["\n",(0,a.jsxs)(n.li,{children:[(0,a.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,a.jsxs)(n.li,{children:[(0,a.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/getting-started/quick-start",children:"Created a new Solace Agent Mesh project"}),"."]}),"\n",(0,a.jsx)(n.li,{children:"Access to a vector database (for example, Qdrant, Chroma, and Pinecone)."}),"\n",(0,a.jsx)(n.li,{children:"Access to an LLM for generation and an embedding model."}),"\n",(0,a.jsx)(n.li,{children:"A directory with some documents for the agent to ingest."}),"\n"]}),"\n",(0,a.jsx)(n.h2,{id:"adding-the-rag-plugin",children:"Adding the RAG Plugin"}),"\n",(0,a.jsx)(n.p,{children:"To add the RAG plugin to your Solace Agent Mesh project, run the following command:"}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-sh",children:"sam plugin add my-rag-agent --plugin sam-rag\n"})}),"\n",(0,a.jsxs)(n.p,{children:["Replace ",(0,a.jsx)(n.code,{children:"my-rag-agent"})," with your preferred agent name. This command:"]}),"\n",(0,a.jsxs)(n.ul,{children:["\n",(0,a.jsxs)(n.li,{children:["Installs the ",(0,a.jsx)(n.code,{children:"sam-rag"})," plugin."]}),"\n",(0,a.jsxs)(n.li,{children:["Creates a new agent configuration file at ",(0,a.jsx)(n.code,{children:"configs/agents/my-rag-agent.yaml"}),"."]}),"\n"]}),"\n",(0,a.jsx)(n.h2,{id:"configuring-the-rag-agent",children:"Configuring the RAG Agent"}),"\n",(0,a.jsxs)(n.p,{children:["The RAG agent requires a detailed configuration. Open ",(0,a.jsx)(n.code,{children:"configs/agents/my-rag-agent.yaml"})," to configure the following sections:"]}),"\n",(0,a.jsx)(n.h3,{id:"shared-configuration",children:"Shared Configuration"}),"\n",(0,a.jsxs)(n.p,{children:["Like other agents, the RAG agent needs a connection to the Solace broker and a configured LLM. This is typically done in a ",(0,a.jsx)(n.code,{children:"shared_config.yaml"})," file."]}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-yaml",children:"# configs/shared_config.yaml\nshared_config:\n  - broker_connection: &broker_connection\n      dev_mode: ${SOLACE_DEV_MODE, false}\n      broker_url: ${SOLACE_BROKER_URL, ws://localhost:8080}\n      broker_username: ${SOLACE_BROKER_USERNAME, default}\n      broker_password: ${SOLACE_BROKER_PASSWORD, default}\n      broker_vpn: ${SOLACE_BROKER_VPN, default}\n      temporary_queue: ${USE_TEMPORARY_QUEUES, true}\n\n  - models:\n    general: &general_model\n      model: ${LLM_SERVICE_GENERAL_MODEL_NAME}\n      api_base: ${LLM_SERVICE_ENDPOINT}\n      api_key: ${LLM_SERVICE_API_KEY}\n"})}),"\n",(0,a.jsx)(n.h3,{id:"rag-pipeline-configuration",children:"RAG Pipeline Configuration"}),"\n",(0,a.jsxs)(n.p,{children:["The RAG pipeline has several stages, each with its own configuration block within the ",(0,a.jsx)(n.code,{children:"app_config"})," section of your ",(0,a.jsx)(n.code,{children:"my-rag-agent.yaml"})," file."]}),"\n",(0,a.jsx)(n.h4,{id:"1-scanner-configuration",children:"1. Scanner Configuration"}),"\n",(0,a.jsx)(n.p,{children:"The scanner discovers documents to be ingested. You can configure it to scan a local filesystem or cloud sources."}),"\n",(0,a.jsx)(n.p,{children:(0,a.jsx)(n.strong,{children:"Local Filesystem Example:"})}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-yaml",children:'scanner:\n  batch: true\n  use_memory_storage: true\n  source:\n    type: filesystem\n    directories:\n      - "/path/to/your/documents" # Important: Replace with your actual document directory path\n    filters:\n      file_formats:\n        - ".txt"\n        - ".pdf"\n        - ".md"\n'})}),"\n",(0,a.jsxs)(n.p,{children:[(0,a.jsx)(n.strong,{children:"Multi-Cloud Source Example:"}),"\nYou can also configure multiple sources, including Google Drive, OneDrive, and S3."]}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-yaml",children:'scanner:\n  batch: true\n  use_memory_storage: true\n  sources:\n    - type: filesystem\n      directories: ["${LOCAL_DOCUMENTS_PATH}"]\n    - type: google_drive\n      credentials_path: "${GOOGLE_DRIVE_CREDENTIALS_PATH}"\n      folders:\n        - folder_id: "${GOOGLE_DRIVE_FOLDER_ID_1}"\n          name: "Documents"\n          recursive: true\n'})}),"\n",(0,a.jsx)(n.h4,{id:"2-preprocessor-configuration",children:"2. Preprocessor Configuration"}),"\n",(0,a.jsx)(n.p,{children:"The preprocessor cleans the text extracted from documents."}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-yaml",children:"preprocessor:\n  default_preprocessor:\n    type: enhanced\n    params:\n      lowercase: true\n      normalize_whitespace: true\n      remove_urls: true\n  preprocessors:\n    pdf: \n      type: document\n      params:\n        lowercase: true\n        normalize_whitespace: true\n        remove_non_ascii: true\n        remove_urls: true\n"})}),"\n",(0,a.jsx)(n.h4,{id:"3-splitter-configuration",children:"3. Splitter Configuration"}),"\n",(0,a.jsx)(n.p,{children:"The splitter breaks down large documents into smaller chunks. Different splitters are available for different file types."}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-yaml",children:"splitter:\n  default_splitter:\n    type: recursive_character\n    params:\n      chunk_size: 2048\n      chunk_overlap: 400\n  splitters:\n    markdown:\n      type: markdown\n      params:\n        chunk_size: 2048\n        chunk_overlap: 400\n    pdf:\n      type: token\n      params:\n        chunk_size: 500\n        chunk_overlap: 100\n"})}),"\n",(0,a.jsx)(n.h4,{id:"4-embedding-configuration",children:"4. Embedding Configuration"}),"\n",(0,a.jsx)(n.p,{children:"This section defines the model used to create vector embeddings from the text chunks."}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-yaml",children:'embedding:\n  embedder_type: "openai"\n  embedder_params:\n    model: "${OPENAI_EMBEDDING_MODEL}"\n    api_key: "${OPENAI_API_KEY}"\n    api_base: "${OPENAI_API_ENDPOINT}"\n  normalize_embeddings: true\n'})}),"\n",(0,a.jsx)(n.h4,{id:"5-vector-database-configuration",children:"5. Vector Database Configuration"}),"\n",(0,a.jsx)(n.p,{children:"Configure the connection to your vector database where the embeddings are stored."}),"\n",(0,a.jsx)(n.p,{children:(0,a.jsx)(n.strong,{children:"Qdrant Example:"})}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-yaml",children:'vector_db:\n  db_type: "qdrant"\n  db_params:\n    url: "${QDRANT_URL}"\n    api_key: "${QDRANT_API_KEY}"\n    collection_name: "${QDRANT_COLLECTION}"\n    embedding_dimension: ${QDRANT_EMBEDDING_DIMENSION}\n'})}),"\n",(0,a.jsx)(n.p,{children:(0,a.jsx)(n.strong,{children:"Chroma Example:"})}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-yaml",children:'vector_db:\n  db_type: "chroma"\n  db_params:\n    host: "${CHROMA_HOST}"\n    port: "${CHROMA_PORT}"\n    collection_name: "${CHROMA_COLLECTION}"\n'})}),"\n",(0,a.jsx)(n.h4,{id:"6-llm-configuration",children:"6. LLM Configuration"}),"\n",(0,a.jsx)(n.p,{children:"Configure the LLM that is used to generate answers based on the retrieved context."}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-yaml",children:'llm:\n  load_balancer:\n    - model_name: "gpt-4o"\n      litellm_params:\n        model: "openai/${OPENAI_MODEL_NAME}"\n        api_key: "${OPENAI_API_KEY}"\n        api_base: "${OPENAI_API_ENDPOINT}"\n'})}),"\n",(0,a.jsx)(n.h4,{id:"7-retrieval-configuration",children:"7. Retrieval Configuration"}),"\n",(0,a.jsx)(n.p,{children:"This defines how many document chunks are retrieved to answer a query."}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-yaml",children:"retrieval:\n  top_k: 7\n"})}),"\n",(0,a.jsx)(n.h3,{id:"environment-variables",children:"Environment Variables"}),"\n",(0,a.jsxs)(n.p,{children:["The RAG agent relies heavily on environment variables. Here are some of the most important ones you'll need to set in your ",(0,a.jsx)(n.code,{children:".env"})," file:"]}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-bash",children:'# Solace Connection\nSOLACE_BROKER_URL=ws://localhost:8080\nSOLACE_BROKER_VPN=default\nSOLACE_BROKER_USERNAME=default\nSOLACE_BROKER_PASSWORD=default\nNAMESPACE=my-org/dev\n\n# LLM and Embedding Models\nOPENAI_API_KEY="your-openai-api-key"\nOPENAI_API_ENDPOINT="your-openai-api-endpoint"\nOPENAI_MODEL_NAME="model name. E.g., gpt-4o"\nOPENAI_EMBEDDING_MODEL="embedding model name. E.g., text-embedding-3-small"\n\n# Vector Database (Qdrant example)\nQDRANT_URL="Qdrant url"\nQDRANT_API_KEY="API key"\nQDRANT_COLLECTION="my-rag-collection"\nQDRANT_EMBEDDING_DIMENSION=1536 # Depends on your embedding model\n\n# Scanner\nLOCAL_DOCUMENTS_PATH="./my_documents" # Relative path to your documents folder\n'})}),"\n",(0,a.jsxs)(n.p,{children:["Create a directory named ",(0,a.jsx)(n.code,{children:"my_documents"})," in your project root and place some text or markdown files inside it."]}),"\n",(0,a.jsx)(n.h2,{id:"running-the-rag-agent",children:"Running the RAG Agent"}),"\n",(0,a.jsx)(n.p,{children:"Once you have configured your agent and set the environment variables, you can run it:"}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-sh",children:"sam run configs/agents/my-rag-agent.yaml\n"})}),"\n",(0,a.jsx)(n.p,{children:"When the agent starts, it begins scanning the documents in the configured source, processing and ingesting them into your vector database. This process may take some time, depending on the number and size of your documents."}),"\n",(0,a.jsx)(n.h2,{id:"testing-the-rag-agent",children:"Testing the RAG Agent"}),"\n",(0,a.jsx)(n.p,{children:"Once your agent is running, you can test its retrieval capabilities and ingest new documents."}),"\n",(0,a.jsx)(n.h3,{id:"ingesting-documents",children:"Ingesting Documents"}),"\n",(0,a.jsx)(n.p,{children:"There are two primary ways to ingest documents into your RAG agent's knowledge base:"}),"\n",(0,a.jsx)(n.h4,{id:"option-1-automatic-scanning-batch-ingestion",children:"Option 1: Automatic Scanning (Batch Ingestion)"}),"\n",(0,a.jsxs)(n.p,{children:["This method uses the configured ",(0,a.jsx)(n.code,{children:"scanner"})," component. The agent automatically ingests documents from the directories specified in your configuration upon startup."]}),"\n",(0,a.jsx)(n.p,{children:(0,a.jsx)(n.strong,{children:"Step 1: Create a Document"})}),"\n",(0,a.jsxs)(n.p,{children:["First, create a simple text file named ",(0,a.jsx)(n.code,{children:"sam_features.txt"})," and add some content to it. For example:"]}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-text",children:"Solace Agent Mesh is a powerful framework for building AI agents.\nKey features of Solace Agent Mesh include:\n- A flexible plugin architecture.\n- Integration with various LLMs and vector databases.\n- Scalable gateways for different communication protocols.\n- An event-driven design based on Solace PubSub+.\n"})}),"\n",(0,a.jsx)(n.p,{children:(0,a.jsx)(n.strong,{children:"Step 2: Place the Document in the Scanned Directory"})}),"\n",(0,a.jsxs)(n.p,{children:['In the "Environment Variables" section, we configured ',(0,a.jsx)(n.code,{children:"LOCAL_DOCUMENTS_PATH"})," to point to a directory (e.g., ",(0,a.jsx)(n.code,{children:"./my_documents"}),")."]}),"\n",(0,a.jsxs)(n.p,{children:["Create this directory in your project's root folder if you haven't already, and move your ",(0,a.jsx)(n.code,{children:"sam_features.txt"})," file into it."]}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-sh",children:"mkdir -p my_documents\nmv sam_features.txt my_documents/\n"})}),"\n",(0,a.jsx)(n.p,{children:(0,a.jsx)(n.strong,{children:"Step 3: Run the Agent to Trigger Ingestion"})}),"\n",(0,a.jsx)(n.p,{children:"If your agent is already running, you'll need to restart it to trigger the batch scan. If it's not running, start it now:"}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-sh",children:"sam run configs/agents/my-rag-agent.yaml\n"})}),"\n",(0,a.jsx)(n.p,{children:"You will see logs indicating that the file is being processed. Once the agent is running and the initial scan is complete, the document is successfully ingested and ready for retrieval."}),"\n",(0,a.jsx)(n.h4,{id:"option-2-manual-upload-via-gateway",children:"Option 2: Manual Upload via Gateway"}),"\n",(0,a.jsx)(n.p,{children:"You can also ingest documents dynamically by uploading them directly through a gateway, like the Web UI. This is useful for adding single documents without restarting the agent. The RAG agent exposes a tool for this purpose."}),"\n",(0,a.jsx)(n.p,{children:(0,a.jsx)(n.strong,{children:"Step 1: Start the RAG Agent and Web UI"})}),"\n",(0,a.jsx)(n.p,{children:"Ensure both your RAG agent and the Web UI gateway are running."}),"\n",(0,a.jsx)(n.p,{children:(0,a.jsx)(n.strong,{children:"Step 2: Upload a Document in the Web UI"})}),"\n",(0,a.jsxs)(n.ol,{children:["\n",(0,a.jsxs)(n.li,{children:["Open the Web UI (usually at ",(0,a.jsx)(n.a,{href:"http://localhost:8000",children:"http://localhost:8000"}),", or check your gateway configuration for the correct URL) and start a chat with your RAG agent."]}),"\n",(0,a.jsx)(n.li,{children:"Use the file attachment button to select a document from your local machine."}),"\n",(0,a.jsxs)(n.li,{children:["Send a prompt along with the file, instructing the agent to ingest it. For example:","\n",(0,a.jsxs)(n.blockquote,{children:["\n",(0,a.jsx)(n.p,{children:'"Please ingest the attached document into your knowledge base."'}),"\n"]}),"\n"]}),"\n"]}),"\n",(0,a.jsxs)(n.p,{children:["The RAG agent uses its ",(0,a.jsx)(n.code,{children:"built-in"})," ingest_document tool to process the file you uploaded. The file goes through the same preprocessing, splitting, and embedding pipeline as the documents from the automatic scan."]}),"\n",(0,a.jsx)(n.p,{children:(0,a.jsx)(n.strong,{children:"Step 3: Confirm Ingestion"})}),"\n",(0,a.jsx)(n.p,{children:"After the agent confirms that the document has been ingested, you can immediately ask questions about its content."}),"\n",(0,a.jsx)(n.h3,{id:"querying-the-knowledge-base",children:"Querying the Knowledge Base"}),"\n",(0,a.jsx)(n.p,{children:"You can interact with your RAG agent through any gateway, such as the Web UI gateway."}),"\n",(0,a.jsxs)(n.ol,{children:["\n",(0,a.jsx)(n.li,{children:"Make sure you have a Web UI gateway running (or add one to your project)."}),"\n",(0,a.jsxs)(n.li,{children:["Open the Web UI (usually at ",(0,a.jsx)(n.code,{children:"http://localhost:8000"}),")."]}),"\n",(0,a.jsxs)(n.li,{children:["Start a conversation with ",(0,a.jsx)(n.code,{children:"my-rag-agent"}),"."]}),"\n",(0,a.jsx)(n.li,{children:"Ask a question related to the content of the documents you provided during the initial scan."}),"\n"]}),"\n",(0,a.jsx)(n.p,{children:"For example, if you have a document about product features, you could ask:"}),"\n",(0,a.jsxs)(n.blockquote,{children:["\n",(0,a.jsx)(n.p,{children:'"What are the key features of Product X?"'}),"\n"]}),"\n",(0,a.jsx)(n.p,{children:"The agent searches its knowledge base, finds the relevant information, and generates an answer based on the content of your documents."}),"\n",(0,a.jsx)(n.h2,{id:"troubleshooting",children:"Troubleshooting"}),"\n",(0,a.jsxs)(n.ul,{children:["\n",(0,a.jsxs)(n.li,{children:[(0,a.jsx)(n.strong,{children:"Connection Errors"}),": Double-check all your URLs, API keys, and credentials for your LLM and vector database."]}),"\n",(0,a.jsxs)(n.li,{children:[(0,a.jsx)(n.strong,{children:"Ingestion Issues"}),": Check the agent logs for errors during the scanning, preprocessing, or embedding stages. Ensure the file formats are supported and the paths are correct."]}),"\n",(0,a.jsxs)(n.li,{children:[(0,a.jsx)(n.strong,{children:"No Answers"}),": If the agent can't answer, it might be because the information is not in the documents, or the ",(0,a.jsx)(n.code,{children:"top_k"})," retrieval setting is too low."]}),"\n"]})]})}function h(e={}){const{wrapper:n}={...(0,r.R)(),...e.components};return n?(0,a.jsx)(n,{...e,children:(0,a.jsx)(d,{...e})}):d(e)}},8453:(e,n,t)=>{t.d(n,{R:()=>o,x:()=>s});var i=t(6540);const a={},r=i.createContext(a);function o(e){const n=i.useContext(r);return i.useMemo((function(){return"function"==typeof e?e(n):{...n,...e}}),[n,e])}function s(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(a):e.components||a:o(e.components),i.createElement(r.Provider,{value:n},e.children)}}}]);
+"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[8055],{5343:(e,n,t)=>{t.r(n),t.d(n,{assets:()=>l,contentTitle:()=>s,default:()=>h,frontMatter:()=>o,metadata:()=>i,toc:()=>c});const i=JSON.parse('{"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.","source":"@site/docs/documentation/tutorials/rag-integration.md","sourceDirName":"documentation/tutorials","slug":"/documentation/tutorials/rag-integration","permalink":"/solace-agent-mesh/docs/documentation/tutorials/rag-integration","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/tutorials/rag-integration.md","tags":[],"version":"current","sidebarPosition":70,"frontMatter":{"title":"RAG Integration","sidebar_position":70,"toc_max_heading_level":4},"sidebar":"docSidebar","previous":{"title":"Slack Integration","permalink":"/solace-agent-mesh/docs/documentation/tutorials/slack-integration"},"next":{"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"}}');var a=t(4848),r=t(8453);const o={title:"RAG Integration",sidebar_position:70,toc_max_heading_level:4},s="RAG Integration",l={},c=[{value:"What is Solace Agent Mesh RAG?",id:"what-is-solace-agent-mesh-rag",level:2},{value:"Prerequisites",id:"prerequisites",level:2},{value:"Adding the RAG Plugin",id:"adding-the-rag-plugin",level:2},{value:"Configuring the RAG Agent",id:"configuring-the-rag-agent",level:2},{value:"Shared Configuration",id:"shared-configuration",level:3},{value:"RAG Pipeline Configuration",id:"rag-pipeline-configuration",level:3},{value:"1. Scanner Configuration",id:"1-scanner-configuration",level:4},{value:"2. Preprocessor Configuration",id:"2-preprocessor-configuration",level:4},{value:"3. Splitter Configuration",id:"3-splitter-configuration",level:4},{value:"4. Embedding Configuration",id:"4-embedding-configuration",level:4},{value:"5. Vector Database Configuration",id:"5-vector-database-configuration",level:4},{value:"6. LLM Configuration",id:"6-llm-configuration",level:4},{value:"7. Retrieval Configuration",id:"7-retrieval-configuration",level:4},{value:"Environment Variables",id:"environment-variables",level:3},{value:"Running the RAG Agent",id:"running-the-rag-agent",level:2},{value:"Testing the RAG Agent",id:"testing-the-rag-agent",level:2},{value:"Ingesting Documents",id:"ingesting-documents",level:3},{value:"Option 1: Automatic Scanning (Batch Ingestion)",id:"option-1-automatic-scanning-batch-ingestion",level:4},{value:"Option 2: Manual Upload via Gateway",id:"option-2-manual-upload-via-gateway",level:4},{value:"Querying the Knowledge Base",id:"querying-the-knowledge-base",level:3},{value:"Troubleshooting",id:"troubleshooting",level:2}];function d(e){const n={a:"a",blockquote:"blockquote",code:"code",h1:"h1",h2:"h2",h3:"h3",h4:"h4",header:"header",li:"li",ol:"ol",p:"p",pre:"pre",strong:"strong",ul:"ul",...(0,r.R)(),...e.components};return(0,a.jsxs)(a.Fragment,{children:[(0,a.jsx)(n.header,{children:(0,a.jsx)(n.h1,{id:"rag-integration",children:"RAG Integration"})}),"\n",(0,a.jsx)(n.p,{children:"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."}),"\n",(0,a.jsx)(n.h2,{id:"what-is-solace-agent-mesh-rag",children:"What is Solace Agent Mesh RAG?"}),"\n",(0,a.jsx)(n.p,{children:"The Solace Agent Mesh RAG plugin enhances your agents with the ability to perform retrieval-augmented generation. This means the agent can:"}),"\n",(0,a.jsxs)(n.ul,{children:["\n",(0,a.jsxs)(n.li,{children:[(0,a.jsx)(n.strong,{children:"Scan"})," documents from various sources (local filesystem, Google Drive, etc.)."]}),"\n",(0,a.jsxs)(n.li,{children:[(0,a.jsx)(n.strong,{children:"Preprocess"})," and ",(0,a.jsx)(n.strong,{children:"split"})," the text into manageable chunks."]}),"\n",(0,a.jsxs)(n.li,{children:[(0,a.jsx)(n.strong,{children:"Embed"})," these chunks into vectors and store them in a vector database."]}),"\n",(0,a.jsxs)(n.li,{children:[(0,a.jsx)(n.strong,{children:"Retrieve"})," relevant chunks of text based on a user's query."]}),"\n",(0,a.jsxs)(n.li,{children:[(0,a.jsx)(n.strong,{children:"Generate"})," an answer using a large language model (LLM) augmented with the retrieved information."]}),"\n"]}),"\n",(0,a.jsx)(n.p,{children:"This allows you to build agents that can answer questions about your own private data."}),"\n",(0,a.jsx)(n.h2,{id:"prerequisites",children:"Prerequisites"}),"\n",(0,a.jsx)(n.p,{children:"Before you begin, ensure you have:"}),"\n",(0,a.jsxs)(n.ul,{children:["\n",(0,a.jsxs)(n.li,{children:[(0,a.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,a.jsxs)(n.li,{children:[(0,a.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/getting-started/quick-start",children:"Created a new Solace Agent Mesh project"}),"."]}),"\n",(0,a.jsx)(n.li,{children:"Access to a vector database (for example, Qdrant, Chroma, and Pinecone)."}),"\n",(0,a.jsx)(n.li,{children:"Access to an LLM for generation and an embedding model."}),"\n",(0,a.jsx)(n.li,{children:"A directory with some documents for the agent to ingest."}),"\n"]}),"\n",(0,a.jsx)(n.h2,{id:"adding-the-rag-plugin",children:"Adding the RAG Plugin"}),"\n",(0,a.jsx)(n.p,{children:"To add the RAG plugin to your Solace Agent Mesh project, run the following command:"}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-sh",children:"sam plugin add my-rag-agent --plugin sam-rag\n"})}),"\n",(0,a.jsxs)(n.p,{children:["Replace ",(0,a.jsx)(n.code,{children:"my-rag-agent"})," with your preferred agent name. This command:"]}),"\n",(0,a.jsxs)(n.ul,{children:["\n",(0,a.jsxs)(n.li,{children:["Installs the ",(0,a.jsx)(n.code,{children:"sam-rag"})," plugin."]}),"\n",(0,a.jsxs)(n.li,{children:["Creates a new agent configuration file at ",(0,a.jsx)(n.code,{children:"configs/agents/my-rag-agent.yaml"}),"."]}),"\n"]}),"\n",(0,a.jsx)(n.h2,{id:"configuring-the-rag-agent",children:"Configuring the RAG Agent"}),"\n",(0,a.jsxs)(n.p,{children:["The RAG agent requires a detailed configuration. Open ",(0,a.jsx)(n.code,{children:"configs/agents/my-rag-agent.yaml"})," to configure the following sections:"]}),"\n",(0,a.jsx)(n.h3,{id:"shared-configuration",children:"Shared Configuration"}),"\n",(0,a.jsxs)(n.p,{children:["Like other agents, the RAG agent needs a connection to the Solace broker and a configured LLM. This is typically done in a ",(0,a.jsx)(n.code,{children:"shared_config.yaml"})," file."]}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-yaml",children:"# configs/shared_config.yaml\nshared_config:\n  - broker_connection: &broker_connection\n      dev_mode: ${SOLACE_DEV_MODE, false}\n      broker_url: ${SOLACE_BROKER_URL, ws://localhost:8008}\n      broker_username: ${SOLACE_BROKER_USERNAME, default}\n      broker_password: ${SOLACE_BROKER_PASSWORD, default}\n      broker_vpn: ${SOLACE_BROKER_VPN, default}\n      temporary_queue: ${USE_TEMPORARY_QUEUES, true}\n\n  - models:\n    general: &general_model\n      model: ${LLM_SERVICE_GENERAL_MODEL_NAME}\n      api_base: ${LLM_SERVICE_ENDPOINT}\n      api_key: ${LLM_SERVICE_API_KEY}\n"})}),"\n",(0,a.jsx)(n.h3,{id:"rag-pipeline-configuration",children:"RAG Pipeline Configuration"}),"\n",(0,a.jsxs)(n.p,{children:["The RAG pipeline has several stages, each with its own configuration block within the ",(0,a.jsx)(n.code,{children:"app_config"})," section of your ",(0,a.jsx)(n.code,{children:"my-rag-agent.yaml"})," file."]}),"\n",(0,a.jsx)(n.h4,{id:"1-scanner-configuration",children:"1. Scanner Configuration"}),"\n",(0,a.jsx)(n.p,{children:"The scanner discovers documents to be ingested. You can configure it to scan a local filesystem or cloud sources."}),"\n",(0,a.jsx)(n.p,{children:(0,a.jsx)(n.strong,{children:"Local Filesystem Example:"})}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-yaml",children:'scanner:\n  batch: true\n  use_memory_storage: true\n  source:\n    type: filesystem\n    directories:\n      - "/path/to/your/documents" # Important: Replace with your actual document directory path\n    filters:\n      file_formats:\n        - ".txt"\n        - ".pdf"\n        - ".md"\n'})}),"\n",(0,a.jsxs)(n.p,{children:[(0,a.jsx)(n.strong,{children:"Multi-Cloud Source Example:"}),"\nYou can also configure multiple sources, including Google Drive, OneDrive, and S3."]}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-yaml",children:'scanner:\n  batch: true\n  use_memory_storage: true\n  sources:\n    - type: filesystem\n      directories: ["${LOCAL_DOCUMENTS_PATH}"]\n    - type: google_drive\n      credentials_path: "${GOOGLE_DRIVE_CREDENTIALS_PATH}"\n      folders:\n        - folder_id: "${GOOGLE_DRIVE_FOLDER_ID_1}"\n          name: "Documents"\n          recursive: true\n'})}),"\n",(0,a.jsx)(n.h4,{id:"2-preprocessor-configuration",children:"2. Preprocessor Configuration"}),"\n",(0,a.jsx)(n.p,{children:"The preprocessor cleans the text extracted from documents."}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-yaml",children:"preprocessor:\n  default_preprocessor:\n    type: enhanced\n    params:\n      lowercase: true\n      normalize_whitespace: true\n      remove_urls: true\n  preprocessors:\n    pdf: \n      type: document\n      params:\n        lowercase: true\n        normalize_whitespace: true\n        remove_non_ascii: true\n        remove_urls: true\n"})}),"\n",(0,a.jsx)(n.h4,{id:"3-splitter-configuration",children:"3. Splitter Configuration"}),"\n",(0,a.jsx)(n.p,{children:"The splitter breaks down large documents into smaller chunks. Different splitters are available for different file types."}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-yaml",children:"splitter:\n  default_splitter:\n    type: recursive_character\n    params:\n      chunk_size: 2048\n      chunk_overlap: 400\n  splitters:\n    markdown:\n      type: markdown\n      params:\n        chunk_size: 2048\n        chunk_overlap: 400\n    pdf:\n      type: token\n      params:\n        chunk_size: 500\n        chunk_overlap: 100\n"})}),"\n",(0,a.jsx)(n.h4,{id:"4-embedding-configuration",children:"4. Embedding Configuration"}),"\n",(0,a.jsx)(n.p,{children:"This section defines the model used to create vector embeddings from the text chunks."}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-yaml",children:'embedding:\n  embedder_type: "openai"\n  embedder_params:\n    model: "${OPENAI_EMBEDDING_MODEL}"\n    api_key: "${OPENAI_API_KEY}"\n    api_base: "${OPENAI_API_ENDPOINT}"\n  normalize_embeddings: true\n'})}),"\n",(0,a.jsx)(n.h4,{id:"5-vector-database-configuration",children:"5. Vector Database Configuration"}),"\n",(0,a.jsx)(n.p,{children:"Configure the connection to your vector database where the embeddings are stored."}),"\n",(0,a.jsx)(n.p,{children:(0,a.jsx)(n.strong,{children:"Qdrant Example:"})}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-yaml",children:'vector_db:\n  db_type: "qdrant"\n  db_params:\n    url: "${QDRANT_URL}"\n    api_key: "${QDRANT_API_KEY}"\n    collection_name: "${QDRANT_COLLECTION}"\n    embedding_dimension: ${QDRANT_EMBEDDING_DIMENSION}\n'})}),"\n",(0,a.jsx)(n.p,{children:(0,a.jsx)(n.strong,{children:"Chroma Example:"})}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-yaml",children:'vector_db:\n  db_type: "chroma"\n  db_params:\n    host: "${CHROMA_HOST}"\n    port: "${CHROMA_PORT}"\n    collection_name: "${CHROMA_COLLECTION}"\n'})}),"\n",(0,a.jsx)(n.h4,{id:"6-llm-configuration",children:"6. LLM Configuration"}),"\n",(0,a.jsx)(n.p,{children:"Configure the LLM that is used to generate answers based on the retrieved context."}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-yaml",children:'llm:\n  load_balancer:\n    - model_name: "gpt-4o"\n      litellm_params:\n        model: "openai/${OPENAI_MODEL_NAME}"\n        api_key: "${OPENAI_API_KEY}"\n        api_base: "${OPENAI_API_ENDPOINT}"\n'})}),"\n",(0,a.jsx)(n.h4,{id:"7-retrieval-configuration",children:"7. Retrieval Configuration"}),"\n",(0,a.jsx)(n.p,{children:"This defines how many document chunks are retrieved to answer a query."}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-yaml",children:"retrieval:\n  top_k: 7\n"})}),"\n",(0,a.jsx)(n.h3,{id:"environment-variables",children:"Environment Variables"}),"\n",(0,a.jsxs)(n.p,{children:["The RAG agent relies heavily on environment variables. Here are some of the most important ones you'll need to set in your ",(0,a.jsx)(n.code,{children:".env"})," file:"]}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-bash",children:'# Solace Connection\nSOLACE_BROKER_URL=ws://localhost:8008\nSOLACE_BROKER_VPN=default\nSOLACE_BROKER_USERNAME=default\nSOLACE_BROKER_PASSWORD=default\nNAMESPACE=my-org/dev\n\n# LLM and Embedding Models\nOPENAI_API_KEY="your-openai-api-key"\nOPENAI_API_ENDPOINT="your-openai-api-endpoint"\nOPENAI_MODEL_NAME="model name. E.g., gpt-4o"\nOPENAI_EMBEDDING_MODEL="embedding model name. E.g., text-embedding-3-small"\n\n# Vector Database (Qdrant example)\nQDRANT_URL="Qdrant url"\nQDRANT_API_KEY="API key"\nQDRANT_COLLECTION="my-rag-collection"\nQDRANT_EMBEDDING_DIMENSION=1536 # Depends on your embedding model\n\n# Scanner\nLOCAL_DOCUMENTS_PATH="./my_documents" # Relative path to your documents folder\n'})}),"\n",(0,a.jsxs)(n.p,{children:["Create a directory named ",(0,a.jsx)(n.code,{children:"my_documents"})," in your project root and place some text or markdown files inside it."]}),"\n",(0,a.jsx)(n.h2,{id:"running-the-rag-agent",children:"Running the RAG Agent"}),"\n",(0,a.jsx)(n.p,{children:"Once you have configured your agent and set the environment variables, you can run it:"}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-sh",children:"sam run configs/agents/my-rag-agent.yaml\n"})}),"\n",(0,a.jsx)(n.p,{children:"When the agent starts, it begins scanning the documents in the configured source, processing and ingesting them into your vector database. This process may take some time, depending on the number and size of your documents."}),"\n",(0,a.jsx)(n.h2,{id:"testing-the-rag-agent",children:"Testing the RAG Agent"}),"\n",(0,a.jsx)(n.p,{children:"Once your agent is running, you can test its retrieval capabilities and ingest new documents."}),"\n",(0,a.jsx)(n.h3,{id:"ingesting-documents",children:"Ingesting Documents"}),"\n",(0,a.jsx)(n.p,{children:"There are two primary ways to ingest documents into your RAG agent's knowledge base:"}),"\n",(0,a.jsx)(n.h4,{id:"option-1-automatic-scanning-batch-ingestion",children:"Option 1: Automatic Scanning (Batch Ingestion)"}),"\n",(0,a.jsxs)(n.p,{children:["This method uses the configured ",(0,a.jsx)(n.code,{children:"scanner"})," component. The agent automatically ingests documents from the directories specified in your configuration upon startup."]}),"\n",(0,a.jsx)(n.p,{children:(0,a.jsx)(n.strong,{children:"Step 1: Create a Document"})}),"\n",(0,a.jsxs)(n.p,{children:["First, create a simple text file named ",(0,a.jsx)(n.code,{children:"sam_features.txt"})," and add some content to it. For example:"]}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-text",children:"Solace Agent Mesh is a powerful framework for building AI agents.\nKey features of Solace Agent Mesh include:\n- A flexible plugin architecture.\n- Integration with various LLMs and vector databases.\n- Scalable gateways for different communication protocols.\n- An event-driven design based on Solace event broker.\n"})}),"\n",(0,a.jsx)(n.p,{children:(0,a.jsx)(n.strong,{children:"Step 2: Place the Document in the Scanned Directory"})}),"\n",(0,a.jsxs)(n.p,{children:['In the "Environment Variables" section, we configured ',(0,a.jsx)(n.code,{children:"LOCAL_DOCUMENTS_PATH"})," to point to a directory (e.g., ",(0,a.jsx)(n.code,{children:"./my_documents"}),")."]}),"\n",(0,a.jsxs)(n.p,{children:["Create this directory in your project's root folder if you haven't already, and move your ",(0,a.jsx)(n.code,{children:"sam_features.txt"})," file into it."]}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-sh",children:"mkdir -p my_documents\nmv sam_features.txt my_documents/\n"})}),"\n",(0,a.jsx)(n.p,{children:(0,a.jsx)(n.strong,{children:"Step 3: Run the Agent to Trigger Ingestion"})}),"\n",(0,a.jsx)(n.p,{children:"If your agent is already running, you'll need to restart it to trigger the batch scan. If it's not running, start it now:"}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-sh",children:"sam run configs/agents/my-rag-agent.yaml\n"})}),"\n",(0,a.jsx)(n.p,{children:"You will see logs indicating that the file is being processed. Once the agent is running and the initial scan is complete, the document is successfully ingested and ready for retrieval."}),"\n",(0,a.jsx)(n.h4,{id:"option-2-manual-upload-via-gateway",children:"Option 2: Manual Upload via Gateway"}),"\n",(0,a.jsx)(n.p,{children:"You can also ingest documents dynamically by uploading them directly through a gateway, like the Web UI. This is useful for adding single documents without restarting the agent. The RAG agent exposes a tool for this purpose."}),"\n",(0,a.jsx)(n.p,{children:(0,a.jsx)(n.strong,{children:"Step 1: Start the RAG Agent and Web UI"})}),"\n",(0,a.jsx)(n.p,{children:"Ensure both your RAG agent and the Web UI gateway are running."}),"\n",(0,a.jsx)(n.p,{children:(0,a.jsx)(n.strong,{children:"Step 2: Upload a Document in the Web UI"})}),"\n",(0,a.jsxs)(n.ol,{children:["\n",(0,a.jsxs)(n.li,{children:["Open the Web UI (usually at ",(0,a.jsx)(n.a,{href:"http://localhost:8000",children:"http://localhost:8000"}),", or check your gateway configuration for the correct URL) and start a chat with your RAG agent."]}),"\n",(0,a.jsx)(n.li,{children:"Use the file attachment button to select a document from your local machine."}),"\n",(0,a.jsxs)(n.li,{children:["Send a prompt along with the file, instructing the agent to ingest it. For example:","\n",(0,a.jsxs)(n.blockquote,{children:["\n",(0,a.jsx)(n.p,{children:'"Please ingest the attached document into your knowledge base."'}),"\n"]}),"\n"]}),"\n"]}),"\n",(0,a.jsxs)(n.p,{children:["The RAG agent uses its ",(0,a.jsx)(n.code,{children:"built-in"})," ingest_document tool to process the file you uploaded. The file goes through the same preprocessing, splitting, and embedding pipeline as the documents from the automatic scan."]}),"\n",(0,a.jsx)(n.p,{children:(0,a.jsx)(n.strong,{children:"Step 3: Confirm Ingestion"})}),"\n",(0,a.jsx)(n.p,{children:"After the agent confirms that the document has been ingested, you can immediately ask questions about its content."}),"\n",(0,a.jsx)(n.h3,{id:"querying-the-knowledge-base",children:"Querying the Knowledge Base"}),"\n",(0,a.jsx)(n.p,{children:"You can interact with your RAG agent through any gateway, such as the Web UI gateway."}),"\n",(0,a.jsxs)(n.ol,{children:["\n",(0,a.jsx)(n.li,{children:"Make sure you have a Web UI gateway running (or add one to your project)."}),"\n",(0,a.jsxs)(n.li,{children:["Open the Web UI (usually at ",(0,a.jsx)(n.code,{children:"http://localhost:8000"}),")."]}),"\n",(0,a.jsxs)(n.li,{children:["Start a conversation with ",(0,a.jsx)(n.code,{children:"my-rag-agent"}),"."]}),"\n",(0,a.jsx)(n.li,{children:"Ask a question related to the content of the documents you provided during the initial scan."}),"\n"]}),"\n",(0,a.jsx)(n.p,{children:"For example, if you have a document about product features, you could ask:"}),"\n",(0,a.jsxs)(n.blockquote,{children:["\n",(0,a.jsx)(n.p,{children:'"What are the key features of Product X?"'}),"\n"]}),"\n",(0,a.jsx)(n.p,{children:"The agent searches its knowledge base, finds the relevant information, and generates an answer based on the content of your documents."}),"\n",(0,a.jsx)(n.h2,{id:"troubleshooting",children:"Troubleshooting"}),"\n",(0,a.jsxs)(n.ul,{children:["\n",(0,a.jsxs)(n.li,{children:[(0,a.jsx)(n.strong,{children:"Connection Errors"}),": Double-check all your URLs, API keys, and credentials for your LLM and vector database."]}),"\n",(0,a.jsxs)(n.li,{children:[(0,a.jsx)(n.strong,{children:"Ingestion Issues"}),": Check the agent logs for errors during the scanning, preprocessing, or embedding stages. Ensure the file formats are supported and the paths are correct."]}),"\n",(0,a.jsxs)(n.li,{children:[(0,a.jsx)(n.strong,{children:"No Answers"}),": If the agent can't answer, it might be because the information is not in the documents, or the ",(0,a.jsx)(n.code,{children:"top_k"})," retrieval setting is too low."]}),"\n"]})]})}function h(e={}){const{wrapper:n}={...(0,r.R)(),...e.components};return n?(0,a.jsx)(n,{...e,children:(0,a.jsx)(d,{...e})}):d(e)}},8453:(e,n,t)=>{t.d(n,{R:()=>o,x:()=>s});var i=t(6540);const a={},r=i.createContext(a);function o(e){const n=i.useContext(r);return i.useMemo((function(){return"function"==typeof e?e(n):{...n,...e}}),[n,e])}function s(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(a):e.components||a:o(e.components),i.createElement(r.Provider,{value:n},e.children)}}}]);

solace_agent_mesh/assets/docs/assets/js/85387663.be2bc838.js

@@ -0,0 +1 @@
+"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[665],{6433:(e,n,t)=>{t.r(n),t.d(n,{assets:()=>l,contentTitle:()=>c,default:()=>h,frontMatter:()=>r,metadata:()=>s,toc:()=>a});const s=JSON.parse('{"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.","source":"@site/docs/documentation/user-guide/solace-ai-connector.md","sourceDirName":"documentation/user-guide","slug":"/documentation/user-guide/solace-ai-connector","permalink":"/solace-agent-mesh/docs/documentation/user-guide/solace-ai-connector","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/user-guide/solace-ai-connector.md","tags":[],"version":"current","sidebarPosition":10,"frontMatter":{"title":"Solace AI Event Connector","sidebar_position":10},"sidebar":"docSidebar","previous":{"title":"Plugins","permalink":"/solace-agent-mesh/docs/documentation/concepts/plugins"},"next":{"title":"Structure","permalink":"/solace-agent-mesh/docs/documentation/user-guide/structure"}}');var o=t(4848),i=t(8453);const r={title:"Solace AI Event Connector",sidebar_position:10},c="Solace AI Event Connector",l={},a=[{value:"Key Features",id:"key-features",level:2},{value:"How It Works",id:"how-it-works",level:2},{value:"Configuration",id:"configuration",level:2}];function d(e){const n={a:"a",admonition:"admonition",h1:"h1",h2:"h2",header:"header",img:"img",li:"li",ol:"ol",p:"p",strong:"strong",ul:"ul",...(0,i.R)(),...e.components};return(0,o.jsxs)(o.Fragment,{children:[(0,o.jsx)(n.header,{children:(0,o.jsx)(n.h1,{id:"solace-ai-event-connector",children:"Solace AI Event Connector"})}),"\n",(0,o.jsx)(n.p,{children:"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."}),"\n",(0,o.jsx)(n.admonition,{title:"GitHub",type:"info",children:(0,o.jsxs)(n.p,{children:["For more information, see ",(0,o.jsx)(n.a,{href:"https://github.com/SolaceLabs/solace-ai-connector",children:"Solace AI Event Connector Github"}),"."]})}),"\n",(0,o.jsx)(n.h2,{id:"key-features",children:"Key Features"}),"\n",(0,o.jsxs)(n.ul,{children:["\n",(0,o.jsxs)(n.li,{children:[(0,o.jsx)(n.strong,{children:"Event Processing Pipeline"}),": Creates flows consisting of input components, processing components, and output components."]}),"\n",(0,o.jsxs)(n.li,{children:[(0,o.jsx)(n.strong,{children:"AI Model Integration"}),": Built on LangChain and LiteLLM supporting various AI models and providers."]}),"\n",(0,o.jsxs)(n.li,{children:[(0,o.jsx)(n.strong,{children:"Extensible Architecture"}),": Supports custom plugins and components for specialized processing needs."]}),"\n",(0,o.jsxs)(n.li,{children:[(0,o.jsx)(n.strong,{children:"Resilient Processing"}),": Ensures reliable event handling with acknowledgment-based processing."]}),"\n",(0,o.jsxs)(n.li,{children:[(0,o.jsx)(n.strong,{children:"Scalable Design"}),": Supports parallel processing and multiple component instances."]}),"\n"]}),"\n",(0,o.jsx)(n.h2,{id:"how-it-works",children:"How It Works"}),"\n",(0,o.jsx)(n.p,{children:"Solace AI Event Connector operates through a series of interconnected components:"}),"\n",(0,o.jsx)(n.p,{children:(0,o.jsx)(n.img,{alt:"SAC Flow Diagram",src:t(248).A+"",width:"896",height:"299"})}),"\n",(0,o.jsxs)(n.ol,{children:["\n",(0,o.jsxs)(n.li,{children:["\n",(0,o.jsx)(n.p,{children:(0,o.jsx)(n.strong,{children:"Flow Structure"})}),"\n",(0,o.jsxs)(n.ul,{children:["\n",(0,o.jsx)(n.li,{children:"Each flow has one input component"}),"\n",(0,o.jsx)(n.li,{children:"Multiple processing components"}),"\n",(0,o.jsx)(n.li,{children:"One output component"}),"\n",(0,o.jsx)(n.li,{children:"Components are connected via queues for buffering"}),"\n"]}),"\n"]}),"\n",(0,o.jsxs)(n.li,{children:["\n",(0,o.jsx)(n.p,{children:(0,o.jsx)(n.strong,{children:"Component Processing"})}),"\n",(0,o.jsxs)(n.ul,{children:["\n",(0,o.jsx)(n.li,{children:"Each component runs in its own thread"}),"\n",(0,o.jsx)(n.li,{children:"Processes one message at a time"}),"\n",(0,o.jsx)(n.li,{children:"Supports input transforms and selections"}),"\n",(0,o.jsx)(n.li,{children:"Can be scaled with multiple instances for parallel processing"}),"\n"]}),"\n",(0,o.jsx)(n.p,{children:(0,o.jsx)(n.img,{alt:"SAC Component Diagram",src:t(1683).A+"",width:"723",height:"292"})}),"\n"]}),"\n",(0,o.jsxs)(n.li,{children:["\n",(0,o.jsx)(n.p,{children:(0,o.jsx)(n.strong,{children:"Event Management"})}),"\n",(0,o.jsxs)(n.ul,{children:["\n",(0,o.jsx)(n.li,{children:"Tracks events throughout the processing pipeline"}),"\n",(0,o.jsx)(n.li,{children:"Uses acknowledgment system for reliable delivery"}),"\n",(0,o.jsx)(n.li,{children:"Ensures no event loss during processing"}),"\n"]}),"\n"]}),"\n"]}),"\n",(0,o.jsx)(n.h2,{id:"configuration",children:"Configuration"}),"\n",(0,o.jsx)(n.p,{children:"The Solace AI Event Connector is configured through YAML files that allow you to:"}),"\n",(0,o.jsxs)(n.ul,{children:["\n",(0,o.jsx)(n.li,{children:"Define flow components and their sequence"}),"\n",(0,o.jsx)(n.li,{children:"Set queue depths between components"}),"\n",(0,o.jsx)(n.li,{children:"Configure the number of parallel instances"}),"\n",(0,o.jsx)(n.li,{children:"Specify input/output parameters"}),"\n",(0,o.jsx)(n.li,{children:"Define processing logic and transformations"}),"\n",(0,o.jsx)(n.li,{children:"Pass the source path for the custom python components"}),"\n"]}),"\n",(0,o.jsxs)(n.p,{children:["For more information about the connector, see ",(0,o.jsx)(n.a,{href:"https://github.com/SolaceLabs/solace-ai-connector/blob/main/docs/index.md",children:"Solace AI Event Connector"}),"."]})]})}function h(e={}){const{wrapper:n}={...(0,i.R)(),...e.components};return n?(0,o.jsx)(n,{...e,children:(0,o.jsx)(d,{...e})}):d(e)}},248:(e,n,t)=>{t.d(n,{A:()=>s});const s=t.p+"assets/images/sac-flows-80d5b603c6aafd33e87945680ce0abf3.png"},1683:(e,n,t)=>{t.d(n,{A:()=>s});const s=t.p+"assets/images/sac_parts_of_a_component-cb3d0424b1d0c17734c5435cca6b4082.png"},8453:(e,n,t)=>{t.d(n,{R:()=>r,x:()=>c});var s=t(6540);const o={},i=s.createContext(o);function r(e){const n=s.useContext(i);return s.useMemo((function(){return"function"==typeof e?e(n):{...n,...e}}),[n,e])}function c(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(o):e.components||o:r(e.components),s.createElement(i.Provider,{value:n},e.children)}}}]);

solace_agent_mesh/assets/docs/assets/js/945fb41e.16e00776.js

@@ -0,0 +1 @@
+"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[1721],{3878:(e,n,t)=>{t.r(n),t.d(n,{assets:()=>l,contentTitle:()=>o,default:()=>h,frontMatter:()=>a,metadata:()=>s,toc:()=>c});const s=JSON.parse('{"id":"documentation/getting-started/introduction","title":"Introduction","description":"Solace Agent Mesh","source":"@site/docs/documentation/getting-started/introduction.md","sourceDirName":"documentation/getting-started","slug":"/documentation/getting-started/introduction","permalink":"/solace-agent-mesh/docs/documentation/getting-started/introduction","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/getting-started/introduction.md","tags":[],"version":"current","sidebarPosition":10,"frontMatter":{"title":"Introduction","sidebar_position":10},"sidebar":"docSidebar","next":{"title":"Installation","permalink":"/solace-agent-mesh/docs/documentation/getting-started/installation"}}');var i=t(4848),r=t(8453);const a={title:"Introduction",sidebar_position:10},o=void 0,l={},c=[{value:"Solace Agent Mesh",id:"solace-agent-mesh",level:2},{value:"What Problems Does the Mesh Solve?",id:"what-problems-does-the-mesh-solve",level:3},{value:"Why Choose Solace Agent Mesh?",id:"why-choose-solace-agent-mesh",level:3},{value:"Real-World Applications",id:"real-world-applications",level:2},{value:"Evolution Through Usage",id:"evolution-through-usage",level:3},{value:"For Developers",id:"for-developers",level:2},{value:"Getting Started",id:"getting-started",level:2}];function d(e){const n={a:"a",br:"br",h2:"h2",h3:"h3",img:"img",li:"li",p:"p",strong:"strong",ul:"ul",...(0,r.R)(),...e.components};return(0,i.jsxs)(i.Fragment,{children:[(0,i.jsx)(n.h2,{id:"solace-agent-mesh",children:"Solace Agent Mesh"}),"\n",(0,i.jsx)(n.p,{children:"Modern AI development faces a fundamental challenge: while powerful AI models are readily available, the real complexity lies in connecting them to the data and systems where they can provide value. Data exists in isolated silos - spread across databases, SaaS platforms, APIs, and legacy systems - making it difficult to build AI applications that can work across these boundaries."}),"\n",(0,i.jsx)(n.p,{children:'Solace Agent Mesh is an open-source framework that tackles this challenge head-on by integrating the Google Agent Development Kit (ADK) with the Solace AI Connector (SAC) to provide a "Universal A2A Agent Host" that enables scalable, distributed AI agent communication through the Solace event broker. Whether you\'re an AI enthusiast experimenting with new models, or an enterprise developer building production systems, Solace Agent Mesh gives you the tools to:'}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsx)(n.li,{children:"connect AI agents to real-world data sources and systems through a standardized A2A (Agent-to-Agent) protocol"}),"\n",(0,i.jsx)(n.li,{children:"add gateways to provide event-based integrations or interactive UI connections"}),"\n",(0,i.jsx)(n.li,{children:"monitor and debug AI interactions in real-time through comprehensive observability"}),"\n",(0,i.jsx)(n.li,{children:"deploy solutions that scale from prototype to production with enterprise-grade reliability"}),"\n"]}),"\n",(0,i.jsx)(n.p,{children:"Rather than trying to be a monolithic AI platform, Solace Agent Mesh focuses on being an excellent integration layer built on proven event-driven architecture. It brings together specialized agents - whether they're using local databases, accessing cloud APIs, or interfacing with enterprise systems - and helps them collaborate through standardized A2A communication to solve complex problems."}),"\n",(0,i.jsx)(n.p,{children:"Built on event-driven architecture technology from Solace with Google ADK integration, Solace Agent Mesh provides the robust foundation needed for both experimental and production deployments."}),"\n",(0,i.jsx)(n.p,{children:(0,i.jsx)(n.img,{alt:"Solace Agent Mesh Overview",src:t(1351).A+"",width:"2558",height:"1788"})}),"\n",(0,i.jsx)(n.h3,{id:"what-problems-does-the-mesh-solve",children:"What Problems Does the Mesh Solve?"}),"\n",(0,i.jsx)(n.p,{children:"Solace Agent Mesh tackles the hardest challenges in building collaborative AI systems: agent coordination, system integration, and extensibility at scale. This section reveals the key problems it solves and shows how organizations are using it today."}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.strong,{children:"Event-Driven Architecture at the Core:"}),(0,i.jsx)(n.br,{}),"\n","The beating heart of Solace Agent Mesh is its event mesh\u2014a neural network for your AI components. This architecture creates a fluid, asynchronous communication layer where messages flow naturally between agents, gateways, and external systems. By decoupling senders from receivers, the mesh dramatically simplifies agent interactions, ensures message delivery even during component failures, and lets you add, remove, or restart components on the fly without disrupting workflows."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.strong,{children:"Breaking Down AI Silos:"}),(0,i.jsx)(n.br,{}),"\n","Specialized agents operate independently yet collaborate effortlessly\u2014like expert teammates rather than isolated tools."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.strong,{children:"Orchestrating Complex Workflows:"}),(0,i.jsx)(n.br,{}),"\n","Create sophisticated multi-agent processes where tasks flow naturally between specialists, executing in sequence or parallel based on dynamic needs."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.strong,{children:"Speaking a Common Language:"}),(0,i.jsx)(n.br,{}),"\n","The A2A protocol creates a universal communication standard, ensuring all agents and gateways understand each other regardless of their internal implementation."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.strong,{children:"Unifying AI Capabilities:"}),(0,i.jsx)(n.br,{}),"\n","Blend diverse AI models, custom tools (Python functions, MCP tools), and enterprise data sources into a cohesive ecosystem."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.strong,{children:"Connecting to Your World:"}),(0,i.jsx)(n.br,{}),"\n","Purpose-built gateways bridge the gap between the agent mesh and your existing systems\u2014web interfaces, Slack workspaces, APIs, and event streams."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.strong,{children:"Handling the Unpredictable:"}),(0,i.jsx)(n.br,{}),"\n","The event-driven backbone gracefully manages long-running tasks and asynchronous patterns that are inherent in AI agent interactions."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.strong,{children:"Adding Agents to Increase Capabilities"}),":\nEach new agent adds more capabilities to the system. Adding a new agent is not additive\u2014it is exponential. With each agent being able to enhance all other agents as they collaborate for more and more complex tasks."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.strong,{children:"Adding Gateways to Increase the Supported Use Cases"}),":\nEach new gateway opens up new use cases for the system. A new gateway can provide a new interface to the system, with a different system purpose and response rules."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.strong,{children:"Enterprise-Ready"}),":\nEngineered from the ground up for production deployment, this solution leverages expertise from Solace in building mission-critical distributed systems."]}),"\n"]}),"\n"]}),"\n",(0,i.jsx)(n.h3,{id:"why-choose-solace-agent-mesh",children:"Why Choose Solace Agent Mesh?"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.strong,{children:"Enterprise-Grade Performance:"}),(0,i.jsx)(n.br,{}),"\n","Built on Solace Event Broker, the mesh delivers high-throughput, fault-tolerant messaging that scales with your needs."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.strong,{children:"Plug-and-Play Extensibility:"}),(0,i.jsx)(n.br,{}),"\n","The event-driven architecture makes adding new capabilities remarkably simple. Deploy a new agent, and it instantly publishes its capabilities to the mesh. Other components discover it automatically\u2014no manual configuration, no downtime, no integration headaches."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.strong,{children:"Modular by Design:"}),(0,i.jsx)(n.br,{}),"\n","Every component\u2014agents, gateways, tools\u2014is a self-contained module you can reuse, replace, or enhance independently."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.strong,{children:"Configuration-Driven:"}),(0,i.jsx)(n.br,{}),"\n","YAML-based configuration gives you precise control over agent behavior, service integrations, and security settings without code changes."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.strong,{children:"Security-First Approach:"}),(0,i.jsx)(n.br,{}),"\n","The built-in authorization framework provides fine-grained access control over agents and tools based on user roles and scopes."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.strong,{children:"Resilient by Nature:"}),(0,i.jsx)(n.br,{}),"\n","Event-driven design creates responsive, self-healing interactions that recover gracefully from disruptions."]}),"\n"]}),"\n"]}),"\n",(0,i.jsx)(n.h2,{id:"real-world-applications",children:"Real-World Applications"}),"\n",(0,i.jsx)(n.p,{children:"Organizations are using Solace Agent Mesh in diverse scenarios:"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:(0,i.jsx)(n.strong,{children:"Intelligent Enterprise Automation:"})}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsx)(n.li,{children:"Customer service systems that route inquiries to specialized agents based on intent and context."}),"\n",(0,i.jsx)(n.li,{children:"Data processing pipelines where specialized agents transform, analyze, and enrich information from multiple sources."}),"\n"]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:(0,i.jsx)(n.strong,{children:"AI Task Specialization:"})}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsx)(n.li,{children:"Image analysis workflows where one agent processes visual data and delegates text generation to a language specialist."}),"\n",(0,i.jsx)(n.li,{children:"Document processing systems that extract text, summarize content, and translate results\u2014each step handled by the perfect specialist."}),"\n"]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.strong,{children:"Human-AI Collaboration:"}),(0,i.jsx)(n.br,{}),"\n","Agents that perform complex tasks while keeping humans in the loop for approvals, clarifications, or expert guidance via web or chat interfaces."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.strong,{children:"Multi-Agent Research:"}),(0,i.jsx)(n.br,{}),"\n","A production-ready platform for exploring agent collaboration patterns, delegation strategies, and distributed AI problem-solving."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.strong,{children:"Data-Driven Intelligence:"}),(0,i.jsx)(n.br,{}),"\n","Agents that query databases, transform results, and generate visualizations based on natural language requests or system events."]}),"\n"]}),"\n"]}),"\n",(0,i.jsx)(n.h3,{id:"evolution-through-usage",children:"Evolution Through Usage"}),"\n",(0,i.jsx)(n.p,{children:"Solace Agent Mesh grows with your needs. For example, at Solace we started with basic agents and have continuously expanded the system's capabilities:"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsx)(n.li,{children:"Added specialized agents for JIRA and Confluence integration"}),"\n",(0,i.jsx)(n.li,{children:"Implemented multiple interface options including browser-based user interfaces and REST API gateways"}),"\n",(0,i.jsx)(n.li,{children:"Integrated with various AI models and data sources"}),"\n"]}),"\n",(0,i.jsx)(n.h2,{id:"for-developers",children:"For Developers"}),"\n",(0,i.jsx)(n.p,{children:"Solace Agent Mesh is an agentic framework that provides several key technical advantages:"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.strong,{children:"Complete Observability"}),": Because all communication flows through the event broker, you can monitor and debug the entire system in real-time"]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.strong,{children:"Flexible Integration"}),": Built-in support for common enterprise systems and AI frameworks"]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.strong,{children:"Plugin Architecture"}),": Easily extend the system with custom agents and gateways"]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.strong,{children:"Developer Tools"}),": Comprehensive CLI and debugging utilities"]}),"\n"]}),"\n",(0,i.jsx)(n.h2,{id:"getting-started",children:"Getting Started"}),"\n",(0,i.jsx)(n.p,{children:"Whether you're building a proof-of-concept or planning a production deployment, Solace Agent Mesh provides the foundation you need. For more information, see:"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/getting-started/installation",children:"Installation"}),": For installing and setting up Solace Agent Mesh."]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/getting-started/quick-start",children:"Quick Start"}),": For creating a project, build, and run Solace Agent Mesh."]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/getting-started/component-overview",children:"Components Overview"}),": Understand the parts of Solace Agent Mesh."]}),"\n"]})]})}function h(e={}){const{wrapper:n}={...(0,r.R)(),...e.components};return n?(0,i.jsx)(n,{...e,children:(0,i.jsx)(d,{...e})}):d(e)}},1351:(e,n,t)=>{t.d(n,{A:()=>s});const s=t.p+"assets/images/Solace_AI_Framework_With_Broker-85f0a306a9bcdd20b390b7a949f6d862.png"},8453:(e,n,t)=>{t.d(n,{R:()=>a,x:()=>o});var s=t(6540);const i={},r=s.createContext(i);function a(e){const n=s.useContext(r);return s.useMemo((function(){return"function"==typeof e?e(n):{...n,...e}}),[n,e])}function o(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(i):e.components||i:a(e.components),s.createElement(r.Provider,{value:n},e.children)}}}]);

solace_agent_mesh/assets/docs/assets/js/a12a4955.25fbed32.js

@@ -0,0 +1 @@
+"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[1657],{2045:(e,n,i)=>{i.r(n),i.d(n,{assets:()=>a,contentTitle:()=>l,default:()=>h,frontMatter:()=>t,metadata:()=>s,toc:()=>c});const s=JSON.parse('{"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.","source":"@site/docs/documentation/Enterprise/rbac-setup-guilde.md","sourceDirName":"documentation/Enterprise","slug":"/documentation/Enterprise/rbac-setup-guilde","permalink":"/solace-agent-mesh/docs/documentation/Enterprise/rbac-setup-guilde","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/Enterprise/rbac-setup-guilde.md","tags":[],"version":"current","sidebarPosition":10,"frontMatter":{"title":"RBAC Setup Guide","sidebar_position":10},"sidebar":"docSidebar","previous":{"title":"Installation","permalink":"/solace-agent-mesh/docs/documentation/Enterprise/installation"},"next":{"title":"SSO","permalink":"/solace-agent-mesh/docs/documentation/Enterprise/single-sign-on"}}');var r=i(4848),o=i(8453);const t={title:"RBAC Setup Guide",sidebar_position:10},l=void 0,a={},c=[{value:"Table of Contents",id:"table-of-contents",level:2},{value:"Introduction to RBAC in SAM Enterprise",id:"introduction-to-rbac-in-sam-enterprise",level:2},{value:"Docker Installation with RBAC",id:"docker-installation-with-rbac",level:2},{value:"Prerequisites",id:"prerequisites",level:3},{value:"Step 1: Create RBAC Configuration Files",id:"step-1-create-rbac-configuration-files",level:3},{value:"Step 2: Configure Role Definitions",id:"step-2-configure-role-definitions",level:3},{value:"Step 3: Configure User Assignments",id:"step-3-configure-user-assignments",level:3},{value:"Step 4: Create Enterprise Configuration",id:"step-4-create-enterprise-configuration",level:3},{value:"Step 5: Run the Docker Container with Mounted Configurations",id:"step-5-run-the-docker-container-with-mounted-configurations",level:3},{value:"Step 6: Verify RBAC Configuration",id:"step-6-verify-rbac-configuration",level:3},{value:"Configuration File Structure",id:"configuration-file-structure",level:2},{value:"Role-to-Scope Definitions",id:"role-to-scope-definitions",level:3},{value:"User-to-Role Assignments",id:"user-to-role-assignments",level:3},{value:"Enterprise Configuration",id:"enterprise-configuration",level:3},{value:"Example Configurations",id:"example-configurations",level:2},{value:"Basic Production Configuration",id:"basic-production-configuration",level:3},{value:"Using MS Graph for User Role Assignments",id:"using-ms-graph-for-user-role-assignments",level:3},{value:"Best Practices",id:"best-practices",level:2},{value:"Security Recommendations",id:"security-recommendations",level:3},{value:"Role Design Principles",id:"role-design-principles",level:3},{value:"Docker-Specific Recommendations",id:"docker-specific-recommendations",level:3},{value:"Troubleshooting",id:"troubleshooting",level:2},{value:"Common Issues and Solutions",id:"common-issues-and-solutions",level:3},{value:"Issue: Authorization Denied for Valid User",id:"issue-authorization-denied-for-valid-user",level:4},{value:"Issue: Configuration Files Not Found",id:"issue-configuration-files-not-found",level:4},{value:"Issue: MS Graph Integration Not Working",id:"issue-ms-graph-integration-not-working",level:4},{value:"Debugging Authorization",id:"debugging-authorization",level:3},{value:"Getting Help",id:"getting-help",level:3},{value:"Conclusion",id:"conclusion",level:2}];function d(e){const n={a:"a",code:"code",h2:"h2",h3:"h3",h4:"h4",li:"li",ol:"ol",p:"p",pre:"pre",strong:"strong",ul:"ul",...(0,o.R)(),...e.components};return(0,r.jsxs)(r.Fragment,{children:[(0,r.jsx)(n.p,{children:"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."}),"\n",(0,r.jsx)(n.h2,{id:"table-of-contents",children:"Table of Contents"}),"\n",(0,r.jsxs)(n.ul,{children:["\n",(0,r.jsx)(n.li,{children:(0,r.jsx)(n.a,{href:"#introduction-to-rbac-in-sam-enterprise",children:"Introduction to RBAC in SAM Enterprise"})}),"\n",(0,r.jsx)(n.li,{children:(0,r.jsx)(n.a,{href:"#docker-installation-with-rbac",children:"Docker Installation with RBAC"})}),"\n",(0,r.jsx)(n.li,{children:(0,r.jsx)(n.a,{href:"#configuration-file-structure",children:"Configuration File Structure"})}),"\n",(0,r.jsx)(n.li,{children:(0,r.jsx)(n.a,{href:"#example-configurations",children:"Example Configurations"})}),"\n",(0,r.jsx)(n.li,{children:(0,r.jsx)(n.a,{href:"#best-practices",children:"Best Practices"})}),"\n",(0,r.jsx)(n.li,{children:(0,r.jsx)(n.a,{href:"#troubleshooting",children:"Troubleshooting"})}),"\n"]}),"\n",(0,r.jsx)(n.h2,{id:"introduction-to-rbac-in-sam-enterprise",children:"Introduction to RBAC in SAM Enterprise"}),"\n",(0,r.jsx)(n.p,{children:"Role-Based Access Control (RBAC) in SAM Enterprise provides a flexible and secure way to manage user permissions. The RBAC system consists of:"}),"\n",(0,r.jsxs)(n.ul,{children:["\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"Roles"}),": Collections of permissions (scopes) that define what actions can be performed"]}),"\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"Scopes"}),": Specific permissions that grant access to features or resources"]}),"\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"Users"}),": Identities that are assigned one or more roles"]}),"\n"]}),"\n",(0,r.jsx)(n.p,{children:"Key benefits of using RBAC in SAM Enterprise:"}),"\n",(0,r.jsxs)(n.ul,{children:["\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"Granular Access Control"}),": Define precise permissions for different user types"]}),"\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"Simplified Administration"}),": Manage permissions through roles rather than individual user assignments"]}),"\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"Enhanced Security"}),": Implement the principle of least privilege"]}),"\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"Audit Trail"}),": Clearly see which users have which permissions"]}),"\n"]}),"\n",(0,r.jsx)(n.h2,{id:"docker-installation-with-rbac",children:"Docker Installation with RBAC"}),"\n",(0,r.jsx)(n.h3,{id:"prerequisites",children:"Prerequisites"}),"\n",(0,r.jsxs)(n.ul,{children:["\n",(0,r.jsx)(n.li,{children:"Docker installed on your system"}),"\n",(0,r.jsxs)(n.li,{children:["SAM Enterprise Docker image (",(0,r.jsx)(n.code,{children:"solace-agent-mesh-enterprise"}),")"]}),"\n",(0,r.jsx)(n.li,{children:"Basic understanding of Docker volumes and configuration"}),"\n"]}),"\n",(0,r.jsx)(n.h3,{id:"step-1-create-rbac-configuration-files",children:"Step 1: Create RBAC Configuration Files"}),"\n",(0,r.jsx)(n.p,{children:"Create a directory on your host system to store the RBAC configuration files:"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-bash",children:"mkdir -p sam-enterprise/configs/auth\n"})}),"\n",(0,r.jsxs)(n.p,{children:["Create the following files in the ",(0,r.jsx)(n.code,{children:"sam-enterprise/configs/auth"})," directory:"]}),"\n",(0,r.jsxs)(n.ol,{children:["\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.code,{children:"role-to-scope-definitions.yaml"}),": Defines roles and their associated permissions"]}),"\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.code,{children:"user-to-role-assignments.yaml"}),": Maps users to roles"]}),"\n"]}),"\n",(0,r.jsx)(n.h3,{id:"step-2-configure-role-definitions",children:"Step 2: Configure Role Definitions"}),"\n",(0,r.jsxs)(n.p,{children:["Create the ",(0,r.jsx)(n.code,{children:"role-to-scope-definitions.yaml"})," file with your role definitions:"]}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-yaml",children:'# role-to-scope-definitions.yaml\nroles:\n  enterprise_admin:\n    description: "Full access for enterprise administrators"\n    scopes:\n      - "*"  # Wildcard grants all permissions\n    \n  data_analyst:\n    description: "Data analysis and visualization specialist"\n    scopes:\n      - "tool:data:*"  # All data tools\n      - "artifact:read"\n      - "artifact:create"\n      - "monitor/namespace/*:a2a_messages:subscribe"  # Can monitor any namespace\n    \n  standard_user:\n    description: "Standard user with basic access"\n    scopes:\n      - "artifact:read"\n      - "tool:basic:read"\n      - "tool:basic:search"\n'})}),"\n",(0,r.jsx)(n.h3,{id:"step-3-configure-user-assignments",children:"Step 3: Configure User Assignments"}),"\n",(0,r.jsxs)(n.p,{children:["Create the ",(0,r.jsx)(n.code,{children:"user-to-role-assignments.yaml"})," file with your user assignments:"]}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-yaml",children:'# user-to-role-assignments.yaml\nusers:\n  admin@example.com:\n    roles: ["enterprise_admin"]\n    description: "Enterprise Administrator Account"\n    \n  data.analyst@example.com:\n    roles: ["data_analyst"]\n    description: "Senior Data Analyst"\n    \n  user1@example.com:\n    roles: ["standard_user"]\n    description: "Standard Enterprise User"\n'})}),"\n",(0,r.jsx)(n.h3,{id:"step-4-create-enterprise-configuration",children:"Step 4: Create Enterprise Configuration"}),"\n",(0,r.jsxs)(n.p,{children:["Create a file named ",(0,r.jsx)(n.code,{children:"enterprise_config.yaml"})," in the ",(0,r.jsx)(n.code,{children:"sam-enterprise/configs"})," directory:"]}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-yaml",children:'# enterprise_config.yaml\nauthorization_service:\n  type: "default_rbac"\n  role_to_scope_definitions_path: "configs/auth/role-to-scope-definitions.yaml"\n  user_to_role_assignments_path: "configs/auth/user-to-role-assignments.yaml"\n\nnamespace: "enterprise_prod"\ngateway_id: "enterprise_gateway"\n'})}),"\n",(0,r.jsx)(n.h3,{id:"step-5-run-the-docker-container-with-mounted-configurations",children:"Step 5: Run the Docker Container with Mounted Configurations"}),"\n",(0,r.jsx)(n.p,{children:"Run the SAM Enterprise Docker container with the configuration files mounted:"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-bash",children:'cd sam-enterprise\n\ndocker run -d \\\n  --name sam-enterprise \\\n  -p 8000:8000 \\\n  -p 5002:5002 \\\n  -v "$(pwd)/configs:/app/configs" \\\n  -e SAM_AUTHORIZATION_CONFIG="/app/configs/enterprise_config.yaml" \n  -e NAMESPACE=enterprise_prod \\\n  -e WEBUI_GATEWAY_ID=enterprise_gateway \\\n  -e ... list here all other necessary env vars ...\n  solace-agent-mesh-enterprise:<tagname> run configs\n'})}),"\n",(0,r.jsx)(n.p,{children:"This command:"}),"\n",(0,r.jsxs)(n.ul,{children:["\n",(0,r.jsx)(n.li,{children:"Maps ports 8000 and 5002 to the host"}),"\n",(0,r.jsxs)(n.li,{children:["Mounts your local configuration directory to ",(0,r.jsx)(n.code,{children:"/app/config"})," in the container"]}),"\n",(0,r.jsx)(n.li,{children:"Sets environment variables for the namespace and gateway ID"}),"\n",(0,r.jsx)(n.li,{children:"Runs the container in detached mode"}),"\n"]}),"\n",(0,r.jsx)(n.h3,{id:"step-6-verify-rbac-configuration",children:"Step 6: Verify RBAC Configuration"}),"\n",(0,r.jsx)(n.p,{children:"To verify that your RBAC configuration is working correctly:"}),"\n",(0,r.jsxs)(n.ol,{children:["\n",(0,r.jsxs)(n.li,{children:["Access the SAM Enterprise web interface at ",(0,r.jsx)(n.code,{children:"http://localhost:5002"})]}),"\n",(0,r.jsxs)(n.li,{children:["Log in with one of the user identities defined in your ",(0,r.jsx)(n.code,{children:"user-to-role-assignments.yaml"})," file"]}),"\n",(0,r.jsx)(n.li,{children:"Confirm that the user has access to the appropriate features based on their assigned roles"}),"\n"]}),"\n",(0,r.jsx)(n.h2,{id:"configuration-file-structure",children:"Configuration File Structure"}),"\n",(0,r.jsx)(n.h3,{id:"role-to-scope-definitions",children:"Role-to-Scope Definitions"}),"\n",(0,r.jsxs)(n.p,{children:["The ",(0,r.jsx)(n.code,{children:"role-to-scope-definitions.yaml"})," file defines roles and their associated permissions:"]}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-yaml",children:'roles:\n  role_name:\n    description: "Role description"\n    scopes:\n      - "scope1"\n      - "scope2"\n    inherits:  # Optional - inherit scopes from other roles\n      - "parent_role1"\n      - "parent_role2"\n'})}),"\n",(0,r.jsx)(n.h3,{id:"user-to-role-assignments",children:"User-to-Role Assignments"}),"\n",(0,r.jsxs)(n.p,{children:["The ",(0,r.jsx)(n.code,{children:"user-to-role-assignments.yaml"})," file maps users to roles:"]}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-yaml",children:'users:\n  user_identity:\n    roles: ["role1", "role2"]\n    description: "User description"\n\n# Optional: Gateway-specific user identities\ngateway_specific_identities:\n  gateway_id:user_identity:\n    roles: ["role1", "role2"]\n    description: "User with specific roles on this gateway"\n'})}),"\n",(0,r.jsx)(n.h3,{id:"enterprise-configuration",children:"Enterprise Configuration"}),"\n",(0,r.jsx)(n.p,{children:"The enterprise configuration file references the RBAC configuration files:"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-yaml",children:'authorization_service:\n  type: "default_rbac"\n  role_to_scope_definitions_path: "path/to/role-to-scope-definitions.yaml"\n  user_to_role_assignments_path: "path/to/user-to-role-assignments.yaml"\n'})}),"\n",(0,r.jsx)(n.h2,{id:"example-configurations",children:"Example Configurations"}),"\n",(0,r.jsx)(n.h3,{id:"basic-production-configuration",children:"Basic Production Configuration"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-yaml",children:'# role-to-scope-definitions.yaml\nroles:\n  admin:\n    description: "Administrator with full access"\n    scopes:\n      - "*"\n  \n  operator:\n    description: "System operator"\n    scopes:\n      - "tool:basic:*"\n      - "tool:advanced:read"\n      - "artifact:read"\n      - "artifact:create"\n      - "monitor/namespace/*:a2a_messages:subscribe"\n  \n  viewer:\n    description: "Read-only access"\n    scopes:\n      - "tool:basic:read"\n      - "artifact:read"\n      - "monitor/namespace/*:a2a_messages:subscribe"\n'})}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-yaml",children:'# user-to-role-assignments.yaml\nusers:\n  admin@company.com:\n    roles: ["admin"]\n    description: "System Administrator"\n  \n  operator@company.com:\n    roles: ["operator"]\n    description: "System Operator"\n  \n  viewer@company.com:\n    roles: ["viewer"]\n    description: "Read-only User"\n'})}),"\n",(0,r.jsx)(n.h3,{id:"using-ms-graph-for-user-role-assignments",children:"Using MS Graph for User Role Assignments"}),"\n",(0,r.jsx)(n.p,{children:"For enterprise environments that use Microsoft Graph for user management:"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-yaml",children:'# enterprise_config.yaml\nauthorization_service:\n  type: "default_rbac"\n  role_to_scope_definitions_path: "configs/auth/role-to-scope-definitions.yaml"\n  user_to_role_provider: "ms_graph"\n  \n  ms_graph_config:\n    ms_graph_tenant_id: ${MS_GRAPH_TENANT_ID}\n    ms_graph_client_id: ${MS_GRAPH_CLIENT_ID}\n    ms_graph_client_secret: ${MS_GRAPH_CLIENT_SECRET}\n'})}),"\n",(0,r.jsx)(n.p,{children:"When using this configuration, set the environment variables in your Docker run command:"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-bash",children:'docker run -d \\\n  --name sam-enterprise \\\n  -p 8000:8000 \\\n  -p 5002:5002 \\\n  -v "$(pwd)/config:/app/configs" \\\n  -e MS_GRAPH_TENANT_ID=your-tenant-id \\\n  -e MS_GRAPH_CLIENT_ID=your-client-id \\\n  -e MS_GRAPH_CLIENT_SECRET=your-client-secret \\\n  -e NAMESPACE=enterprise_prod \\\n  -e WEBUI_GATEWAY_ID=enterprise_gateway \\\n  solace-agent-mesh-enterprise:<tag>\n'})}),"\n",(0,r.jsx)(n.h2,{id:"best-practices",children:"Best Practices"}),"\n",(0,r.jsx)(n.h3,{id:"security-recommendations",children:"Security Recommendations"}),"\n",(0,r.jsxs)(n.ol,{children:["\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"Principle of Least Privilege"}),": Assign users the minimum permissions necessary for their tasks"]}),"\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"Regular Audits"}),": Periodically review role assignments and permissions"]}),"\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"Secure Configuration Files"}),": Protect your RBAC configuration files with appropriate file permissions"]}),"\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"Use Environment Variables"}),": Store sensitive information like MS Graph credentials as environment variables"]}),"\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"Avoid Development Configurations"}),": Never use development configurations in production environments"]}),"\n"]}),"\n",(0,r.jsx)(n.h3,{id:"role-design-principles",children:"Role Design Principles"}),"\n",(0,r.jsxs)(n.ol,{children:["\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"Role Granularity"}),": Create roles that align with job functions"]}),"\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"Role Hierarchy"}),": Use role inheritance to build a logical hierarchy"]}),"\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"Descriptive Names"}),": Use clear, descriptive names for roles"]}),"\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"Documentation"}),": Document the purpose and scope of each role"]}),"\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"Minimize Wildcard Usage"}),": Avoid using wildcards (",(0,r.jsx)(n.code,{children:"*"}),") except for admin roles"]}),"\n"]}),"\n",(0,r.jsx)(n.h3,{id:"docker-specific-recommendations",children:"Docker-Specific Recommendations"}),"\n",(0,r.jsxs)(n.ol,{children:["\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"Persistent Volumes"}),": Use Docker volumes for persistent configuration storage"]}),"\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"Environment-Specific Configs"}),": Create separate configuration files for different environments"]}),"\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"Health Checks"}),": Implement health checks to verify RBAC is functioning correctly"]}),"\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"Backup Configurations"}),": Regularly backup your RBAC configuration files"]}),"\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"Container Security"}),": Follow Docker security best practices (non-root user, read-only filesystem where possible)"]}),"\n"]}),"\n",(0,r.jsx)(n.h2,{id:"troubleshooting",children:"Troubleshooting"}),"\n",(0,r.jsx)(n.h3,{id:"common-issues-and-solutions",children:"Common Issues and Solutions"}),"\n",(0,r.jsx)(n.h4,{id:"issue-authorization-denied-for-valid-user",children:"Issue: Authorization Denied for Valid User"}),"\n",(0,r.jsxs)(n.p,{children:[(0,r.jsx)(n.strong,{children:"Symptoms"}),":"]}),"\n",(0,r.jsxs)(n.ul,{children:["\n",(0,r.jsx)(n.li,{children:"User cannot access features they should have permission to use"}),"\n",(0,r.jsx)(n.li,{children:"Authorization denied messages in logs"}),"\n"]}),"\n",(0,r.jsxs)(n.p,{children:[(0,r.jsx)(n.strong,{children:"Solutions"}),":"]}),"\n",(0,r.jsxs)(n.ol,{children:["\n",(0,r.jsxs)(n.li,{children:["Verify the user identity matches exactly what's in ",(0,r.jsx)(n.code,{children:"user-to-role-assignments.yaml"})]}),"\n",(0,r.jsx)(n.li,{children:"Check that the role has the necessary scopes"}),"\n",(0,r.jsx)(n.li,{children:"Ensure configuration files are correctly mounted in the Docker container"}),"\n",(0,r.jsx)(n.li,{children:"Check logs for authorization service errors\nex:"}),"\n"]}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-bash",children:"INFO:solace_ai_connector:[ConfigurableRbacAuthSvc] Successfully loaded role-to-scope definitions from: /app/configs/auth/role-to-scope-definitions1.yaml\nDEBUG:solace_ai_connector:[ConfigurableRbacAuthSvc] Role 'enterprise_admin' loaded with 1 direct scopes, 1 resolved scopes.\nDEBUG:solace_ai_connector:[ConfigurableRbacAuthSvc] Role 'data_analyst' loaded with 4 direct scopes, 4 resolved scopes.\nDEBUG:solace_ai_connector:[ConfigurableRbacAuthSvc] Role 'standard_user' loaded with 1 direct scopes, 1 resolved scopes.\n"})}),"\n",(0,r.jsx)(n.h4,{id:"issue-configuration-files-not-found",children:"Issue: Configuration Files Not Found"}),"\n",(0,r.jsxs)(n.p,{children:[(0,r.jsx)(n.strong,{children:"Symptoms"}),":"]}),"\n",(0,r.jsxs)(n.ul,{children:["\n",(0,r.jsx)(n.li,{children:"Error messages about missing configuration files"}),"\n",(0,r.jsx)(n.li,{children:"Default/fallback authorization behavior"}),"\n"]}),"\n",(0,r.jsxs)(n.p,{children:[(0,r.jsx)(n.strong,{children:"Solutions"}),":"]}),"\n",(0,r.jsxs)(n.ol,{children:["\n",(0,r.jsx)(n.li,{children:"Verify the file paths in your enterprise configuration"}),"\n",(0,r.jsx)(n.li,{children:"Check that the volume mount is correct in your Docker run command"}),"\n",(0,r.jsx)(n.li,{children:"Ensure file permissions allow the container user to read the files"}),"\n",(0,r.jsx)(n.li,{children:"Check for typos in file names or paths"}),"\n"]}),"\n",(0,r.jsx)(n.h4,{id:"issue-ms-graph-integration-not-working",children:"Issue: MS Graph Integration Not Working"}),"\n",(0,r.jsxs)(n.p,{children:[(0,r.jsx)(n.strong,{children:"Symptoms"}),":"]}),"\n",(0,r.jsxs)(n.ul,{children:["\n",(0,r.jsx)(n.li,{children:"Users cannot authenticate"}),"\n",(0,r.jsx)(n.li,{children:"Error messages related to MS Graph in logs"}),"\n"]}),"\n",(0,r.jsxs)(n.p,{children:[(0,r.jsx)(n.strong,{children:"Solutions"}),":"]}),"\n",(0,r.jsxs)(n.ol,{children:["\n",(0,r.jsx)(n.li,{children:"Verify MS Graph credentials are correct"}),"\n",(0,r.jsx)(n.li,{children:"Check that environment variables are properly set"}),"\n",(0,r.jsx)(n.li,{children:"Ensure the MS Graph application has the necessary permissions"}),"\n",(0,r.jsx)(n.li,{children:"Check network connectivity from the container to MS Graph endpoints"}),"\n"]}),"\n",(0,r.jsx)(n.h3,{id:"debugging-authorization",children:"Debugging Authorization"}),"\n",(0,r.jsx)(n.p,{children:"To debug authorization issues:"}),"\n",(0,r.jsxs)(n.ol,{children:["\n",(0,r.jsxs)(n.li,{children:["\n",(0,r.jsxs)(n.p,{children:[(0,r.jsx)(n.strong,{children:"Enable Debug Logging"}),":"]}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-yaml",children:'# Add to your enterprise_config.yaml\nlog_level: "DEBUG"\n'})}),"\n"]}),"\n",(0,r.jsxs)(n.li,{children:["\n",(0,r.jsxs)(n.p,{children:[(0,r.jsx)(n.strong,{children:"Check Container Logs"}),":"]}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-bash",children:"docker logs sam-enterprise\n"})}),"\n"]}),"\n",(0,r.jsxs)(n.li,{children:["\n",(0,r.jsxs)(n.p,{children:[(0,r.jsx)(n.strong,{children:"Verify Configuration Loading"}),":\nLook for log messages with ",(0,r.jsx)(n.code,{children:"[EnterpriseConfigResolverImpl]"})," or ",(0,r.jsx)(n.code,{children:"[ConfigurableRbacAuthSvc]"})," prefixes"]}),"\n"]}),"\n",(0,r.jsxs)(n.li,{children:["\n",(0,r.jsxs)(n.p,{children:[(0,r.jsx)(n.strong,{children:"Test with Admin User"}),":\nTemporarily assign the user to an admin role to verify if it's a permission issue"]}),"\n"]}),"\n",(0,r.jsxs)(n.li,{children:["\n",(0,r.jsxs)(n.p,{children:[(0,r.jsx)(n.strong,{children:"Inspect Mounted Files"}),":"]}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-bash",children:"docker exec -it sam-enterprise ls -la /app/configs/auth\ndocker exec -it sam-enterprise cat /app/configs/auth/role-to-scope-definitions.yaml\n"})}),"\n"]}),"\n"]}),"\n",(0,r.jsx)(n.h3,{id:"getting-help",children:"Getting Help"}),"\n",(0,r.jsx)(n.p,{children:"If you continue to experience issues:"}),"\n",(0,r.jsxs)(n.ol,{children:["\n",(0,r.jsx)(n.li,{children:"Check the SAM Enterprise documentation"}),"\n",(0,r.jsx)(n.li,{children:"Review the logs for specific error messages"}),"\n",(0,r.jsx)(n.li,{children:"Contact Solace support with details of your configuration and the issues you're experiencing"}),"\n"]}),"\n",(0,r.jsx)(n.h2,{id:"conclusion",children:"Conclusion"}),"\n",(0,r.jsx)(n.p,{children:"Setting up Role-Based Access Control in your SAM Enterprise Docker installation provides enhanced security and granular access control. By following this guide, you can configure RBAC to meet your organization's specific requirements while maintaining a secure and manageable environment."}),"\n",(0,r.jsx)(n.p,{children:"Remember to regularly review and update your RBAC configuration as your organization's needs evolve, and always follow security best practices when managing access control."})]})}function h(e={}){const{wrapper:n}={...(0,o.R)(),...e.components};return n?(0,r.jsx)(n,{...e,children:(0,r.jsx)(d,{...e})}):d(e)}},8453:(e,n,i)=>{i.d(n,{R:()=>t,x:()=>l});var s=i(6540);const r={},o=s.createContext(r);function t(e){const n=s.useContext(o);return s.useMemo((function(){return"function"==typeof e?e(n):{...n,...e}}),[n,e])}function l(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(r):e.components||r:t(e.components),s.createElement(o.Provider,{value:n},e.children)}}}]);

solace_agent_mesh/assets/docs/assets/js/a3a92b25.af35e313.js

@@ -0,0 +1 @@
+"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[6634],{1893:(e,t,n)=>{n.r(t),n.d(t,{assets:()=>c,contentTitle:()=>a,default:()=>h,frontMatter:()=>r,metadata:()=>o,toc:()=>l});const o=JSON.parse('{"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.","source":"@site/docs/documentation/getting-started/component-overview.md","sourceDirName":"documentation/getting-started","slug":"/documentation/getting-started/component-overview","permalink":"/solace-agent-mesh/docs/documentation/getting-started/component-overview","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/getting-started/component-overview.md","tags":[],"version":"current","sidebarPosition":40,"frontMatter":{"title":"Component Overview","sidebar_position":40},"sidebar":"docSidebar","previous":{"title":"Quick Start","permalink":"/solace-agent-mesh/docs/documentation/getting-started/quick-start"},"next":{"title":"Configurations","permalink":"/solace-agent-mesh/docs/documentation/getting-started/configurations/"}}');var s=n(4848),i=n(8453);const r={title:"Component Overview",sidebar_position:40},a="Component Overview",c={},l=[];function d(e){const t={a:"a",h1:"h1",header:"header",li:"li",ol:"ol",p:"p",strong:"strong",...(0,i.R)(),...e.components};return(0,s.jsxs)(s.Fragment,{children:[(0,s.jsx)(t.header,{children:(0,s.jsx)(t.h1,{id:"component-overview",children:"Component Overview"})}),"\n",(0,s.jsx)(t.p,{children:"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."}),"\n",(0,s.jsx)(t.p,{children:'Solace Agent Mesh integrates the Google Agent Development Kit (ADK) with a Solace event mesh to provide a "Universal A2A Agent Host" that enables distributed AI agent communication. Each component is designed to perform specific roles while working together seamlessly through the A2A protocol.'}),"\n",(0,s.jsx)(t.p,{children:"The key components that make up Solace Agent Mesh are:"}),"\n",(0,s.jsxs)(t.ol,{children:["\n",(0,s.jsxs)(t.li,{children:["\n",(0,s.jsxs)(t.p,{children:[(0,s.jsx)(t.strong,{children:"Solace Event Broker or Event Mesh"}),": The central nervous system of the framework, facilitating A2A protocol communication between all components. ",(0,s.jsx)(t.a,{href:"https://solace.com/products/event-broker/",children:"more \ud83d\udd17"})]}),"\n"]}),"\n",(0,s.jsxs)(t.li,{children:["\n",(0,s.jsxs)(t.p,{children:[(0,s.jsx)(t.strong,{children:"A2A Protocol & Agent Registry"}),": The standardized communication protocol that enables agent discovery, task delegation, and peer-to-peer communication."]}),"\n"]}),"\n",(0,s.jsxs)(t.li,{children:["\n",(0,s.jsxs)(t.p,{children:[(0,s.jsx)(t.strong,{children:"Orchestrator"}),": A specialized agent responsible for breaking down requests into tasks and managing the overall workflow. ",(0,s.jsx)(t.a,{href:"/solace-agent-mesh/docs/documentation/concepts/orchestrator",children:"more \ud83d\udd17"})]}),"\n"]}),"\n",(0,s.jsxs)(t.li,{children:["\n",(0,s.jsxs)(t.p,{children:[(0,s.jsx)(t.strong,{children:"Gateways"}),": The entry and exit points for the system, providing various interfaces (REST, HTTP SSE, webhooks, event mesh) that translate external requests into A2A protocol messages. ",(0,s.jsx)(t.a,{href:"/solace-agent-mesh/docs/documentation/concepts/gateways",children:"more \ud83d\udd17"})]}),"\n"]}),"\n",(0,s.jsxs)(t.li,{children:["\n",(0,s.jsxs)(t.p,{children:[(0,s.jsx)(t.strong,{children:"Agents"}),": ADK-powered processing units that communicate through the A2A protocol, each bringing specialized capabilities and tools. ",(0,s.jsx)(t.a,{href:"/solace-agent-mesh/docs/documentation/concepts/agents",children:"more \ud83d\udd17"})]}),"\n"]}),"\n",(0,s.jsxs)(t.li,{children:["\n",(0,s.jsxs)(t.p,{children:[(0,s.jsx)(t.strong,{children:"ADK Runtime"}),": The Google Agent Development Kit provides the core intelligence layer with tool execution, session management, and artifact handling capabilities."]}),"\n"]}),"\n",(0,s.jsxs)(t.li,{children:["\n",(0,s.jsxs)(t.p,{children:[(0,s.jsx)(t.strong,{children:"Built-in Tools"}),": Comprehensive tool ecosystem including artifact management, data analysis, web tools, and peer agent delegation capabilities."]}),"\n"]}),"\n",(0,s.jsxs)(t.li,{children:["\n",(0,s.jsxs)(t.p,{children:[(0,s.jsx)(t.strong,{children:"Real-time Monitoring and Debugging Component"}),": Enables real-time monitoring of system activities and provides interactive debugging capabilities for administrators. ",(0,s.jsx)(t.a,{href:"/solace-agent-mesh/docs/documentation/deployment/observability",children:"more \ud83d\udd17"})]}),"\n"]}),"\n"]})]})}function h(e={}){const{wrapper:t}={...(0,i.R)(),...e.components};return t?(0,s.jsx)(t,{...e,children:(0,s.jsx)(d,{...e})}):d(e)}},8453:(e,t,n)=>{n.d(t,{R:()=>r,x:()=>a});var o=n(6540);const s={},i=o.createContext(s);function r(e){const t=o.useContext(i);return o.useMemo((function(){return"function"==typeof e?e(t):{...t,...e}}),[t,e])}function a(e){let t;return t=e.disableParentContext?"function"==typeof e.components?e.components(s):e.components||s:r(e.components),o.createElement(i.Provider,{value:t},e.children)}}}]);

solace_agent_mesh/assets/docs/assets/js/ae0e903d.5fe5203f.js

@@ -0,0 +1 @@
+"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[3486],{3782:(e,n,t)=>{t.r(n),t.d(n,{assets:()=>c,contentTitle:()=>i,default:()=>h,frontMatter:()=>r,metadata:()=>s,toc:()=>l});const s=JSON.parse('{"id":"documentation/Enterprise/installation","title":"Installation","description":"Step 1: Prepare the Enterprise Image","source":"@site/docs/documentation/Enterprise/installation.md","sourceDirName":"documentation/Enterprise","slug":"/documentation/Enterprise/installation","permalink":"/solace-agent-mesh/docs/documentation/Enterprise/installation","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/Enterprise/installation.md","tags":[],"version":"current","sidebarPosition":5,"frontMatter":{"title":"Installation","sidebar_position":5},"sidebar":"docSidebar","previous":{"title":"A2A Technical Migration Map","permalink":"/solace-agent-mesh/docs/documentation/Migrations/A2A Upgrade To 0.3.0/a2a-technical-migration-map"},"next":{"title":"RBAC Setup Guide","permalink":"/solace-agent-mesh/docs/documentation/Enterprise/rbac-setup-guilde"}}');var a=t(4848),o=t(8453);const r={title:"Installation",sidebar_position:5},i=void 0,c={},l=[{value:"Step 1: Prepare the Enterprise Image",id:"step-1-prepare-the-enterprise-image",level:2},{value:"Step 2: Get Image name",id:"step-2-get-image-name",level:2},{value:"Step 3: Running Solace Agent Mesh Enterprise",id:"step-3-running-solace-agent-mesh-enterprise",level:2},{value:"Development Use Case",id:"development-use-case",level:3},{value:"Production Use Case",id:"production-use-case",level:3}];function d(e){const n={a:"a",admonition:"admonition",code:"code",h2:"h2",h3:"h3",img:"img",li:"li",p:"p",pre:"pre",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,a.jsxs)(a.Fragment,{children:[(0,a.jsx)(n.h2,{id:"step-1-prepare-the-enterprise-image",children:"Step 1: Prepare the Enterprise Image"}),"\n",(0,a.jsx)(n.admonition,{type:"tip",children:(0,a.jsxs)(n.p,{children:["All the docker commands can also be ran using any docker compatbile tool like ",(0,a.jsx)(n.a,{href:"https://podman.io/",children:"podman"})]})}),"\n",(0,a.jsxs)(n.p,{children:["Download the latest enterprise docker image tarball from the ",(0,a.jsx)(n.a,{href:"https://products.solace.com/prods/Agent_Mesh/Enterprise/",children:"Solace Product Portal"}),"."]}),"\n",(0,a.jsx)(n.p,{children:"Load the image using Docker with the following command."}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-bash",children:"docker load -i solace-agent-mesh-enterprise-<tag>.tar.gz\n"})}),"\n",(0,a.jsxs)(n.p,{children:["Ensure you replace ",(0,a.jsx)(n.code,{children:"<tag>"})," with the appropriate version."]}),"\n",(0,a.jsx)(n.h2,{id:"step-2-get-image-name",children:"Step 2: Get Image name"}),"\n",(0,a.jsx)(n.p,{children:"Once loaded, run the following command to verify your installation."}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-bash",children:"docker images\n"})}),"\n",(0,a.jsx)(n.p,{children:"Example output:"}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-bash",children:"REPOSITORY                                                                 TAG                IMAGE ID      CREATED      SIZE\n868978040651.dkr.ecr.us-east-1.amazonaws.com/solace-agent-mesh-enterprise  1.0.37-c8890c7f31  2589d25d0917  9 days ago   5.25 GB\n"})}),"\n",(0,a.jsx)(n.p,{children:"Take note of the name and tag of the image."}),"\n",(0,a.jsxs)(n.p,{children:["In this case our image name would be: ",(0,a.jsx)("br",{}),"\n",(0,a.jsx)(n.code,{children:"868978040651.dkr.ecr.us-east-1.amazonaws.com/solace-agent-mesh-enterprise:1.0.37-c8890c7f31"})]}),"\n",(0,a.jsxs)(n.p,{children:["Note the hashes at the beginning and end (",(0,a.jsx)(n.code,{children:"868978040651"})," and ",(0,a.jsx)(n.code,{children:"c8890c7f31"}),", respectively) could be different for each version."]}),"\n",(0,a.jsx)(n.h2,{id:"step-3-running-solace-agent-mesh-enterprise",children:"Step 3: Running Solace Agent Mesh Enterprise"}),"\n",(0,a.jsx)(n.p,{children:"Here are two examples of Docker run commands for both a development use case as well as a production use case:"}),"\n",(0,a.jsx)(n.admonition,{type:"tip",children:(0,a.jsxs)(n.p,{children:["You may need to include ",(0,a.jsx)(n.code,{children:"--platform linux/amd64"})," depending on the host machine you\u2019re using."]})}),"\n",(0,a.jsx)(n.h3,{id:"development-use-case",children:"Development Use Case"}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-bash",children:'docker run -itd -p 8001:8000 \\\n  -e LLM_SERVICE_API_KEY="<YOUR_LLM_TOKEN>" \\\n  -e LLM_SERVICE_ENDPOINT="<YOUR_LLM_SERVICE_ENDPOINT>" \\\n  -e LLM_SERVICE_PLANNING_MODEL_NAME="<YOUR_MODEL_NAME>" \\\n  -e LLM_SERVICE_GENERAL_MODEL_NAME="<YOUR_MODEL_NAME>" \\\n  -e NAMESPACE="<YOUR_NAMESPACE>" \\\n  -e SOLACE_DEV_MODE="true" \\\n  --name sam-ent-dev \\\n  solace-agent-mesh-enterprise:<tag>\n'})}),"\n",(0,a.jsxs)(s,{children:[(0,a.jsx)("summary",{children:"Example"}),(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-bash",children:'docker run -itd -p 8001:8000 \\\n  -e LLM_SERVICE_API_KEY="<YOUR_LLM_TOKEN>" \\\n  -e LLM_SERVICE_ENDPOINT="https://lite-llm.mymaas.net/" \\\n  -e LLM_SERVICE_PLANNING_MODEL_NAME="openai/vertex-claude-4-sonnet" \\\n  -e LLM_SERVICE_GENERAL_MODEL_NAME="openai/vertex-claude-4-sonnet" \\\n  -e NAMESPACE="sam-dev" \\\n  -e SOLACE_DEV_MODE="true" \\\n  --name sam-ent-dev \\\n  868978040651.dkr.ecr.us-east-1.amazonaws.com/solace-agent-mesh-enterprise:1.0.37-c8890c7f31\n'})})]}),"\n",(0,a.jsx)(n.h3,{id:"production-use-case",children:"Production Use Case"}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-bash",children:'docker run -itd -p 8001:8000 \\\n  -e LLM_SERVICE_API_KEY="<YOUR_LLM_TOKEN>" \\\n  -e LLM_SERVICE_ENDPOINT="<YOUR_LLM_SERVICE_ENDPOINT>" \\\n  -e LLM_SERVICE_PLANNING_MODEL_NAME="<YOUR_MODEL_NAME>" \\\n  -e LLM_SERVICE_GENERAL_MODEL_NAME="<YOUR_MODEL_NAME>" \\\n  -e NAMESPACE="<YOUR_NAMESPACE>" \\\n  -e SOLACE_DEV_MODE="false" \\\n  -e SOLACE_BROKER_URL="<YOUR_BROKER_URL>" \\\n  -e SOLACE_BROKER_VPN="<YOUR_BROKER_VPN>" \\\n  -e SOLACE_BROKER_USERNAME="<YOUR_BROKER_USERNAME>" \\\n  -e SOLACE_BROKER_PASSWORD="<YOUR_BROKER_PASSWORD>" \\\n  --name sam-ent-prod \\\n  solace-agent-mesh-enterprise:<tag>\n'})}),"\n",(0,a.jsxs)(s,{children:[(0,a.jsx)("summary",{children:"How to find your credentials"}),(0,a.jsx)(n.p,{children:"Go to Solace Cloud."}),(0,a.jsx)(n.p,{children:"Cluster manager > Your Service > Connect"}),(0,a.jsx)(n.p,{children:"Switch dropdown to View by Language"}),(0,a.jsx)(n.p,{children:"Open the connect with Python dropdown"}),(0,a.jsx)(n.p,{children:"Click Solace Python with smf as the protocol."}),(0,a.jsx)(n.p,{children:"Copy:"}),(0,a.jsxs)(n.ul,{children:["\n",(0,a.jsx)(n.li,{children:"Username for SOLACE_BROKER_USERNAME,"}),"\n",(0,a.jsx)(n.li,{children:"Password for SOLACE_BROKER_PASSWORD,"}),"\n",(0,a.jsx)(n.li,{children:"Message VPN for SOLACE_BROKER_VPN"}),"\n",(0,a.jsx)(n.li,{children:"Secured SMF URI for SOLACE_BROKER_URL"}),"\n"]}),(0,a.jsx)(n.p,{children:(0,a.jsx)(n.img,{alt:"How to get credentials",src:t(5981).A+"",width:"3456",height:"1916"})})]}),"\n",(0,a.jsxs)(n.p,{children:["You can then access Solace Agent Mesh Enterprise UI through ",(0,a.jsx)(n.a,{href:"http://localhost:8001",children:"http://localhost:8001"})]}),"\n",(0,a.jsx)(n.admonition,{type:"tip",children:(0,a.jsxs)(n.p,{children:["If you want to see logs for debugging, check ",(0,a.jsx)(n.code,{children:".log"})," files. If you want to change debug levels, see more ",(0,a.jsx)(n.a,{href:"https://solacelabs.github.io/solace-agent-mesh/docs/documentation/deployment/debugging/",children:"here"})]})})]})}function h(e={}){const{wrapper:n}={...(0,o.R)(),...e.components};return n?(0,a.jsx)(n,{...e,children:(0,a.jsx)(d,{...e})}):d(e)}},5981:(e,n,t)=>{t.d(n,{A:()=>s});const s=t.p+"assets/images/sam-enterprise-credentials-b269f095349473118b2b33bdfcc40122.png"},8453:(e,n,t)=>{t.d(n,{R:()=>r,x:()=>i});var s=t(6540);const a={},o=s.createContext(a);function r(e){const n=s.useContext(o);return s.useMemo((function(){return"function"==typeof e?e(n):{...n,...e}}),[n,e])}function i(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(a):e.components||a:r(e.components),s.createElement(o.Provider,{value:n},e.children)}}}]);

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

@@ -0,0 +1 @@
+"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/cee5d587.47904f5e.js

@@ -0,0 +1 @@
+"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

@@ -0,0 +1 @@
+"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

@@ -0,0 +1 @@
+"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"}}}}')}}]);