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

solace_agent_mesh/assets/docs/assets/js/a7d42657.a956689d.js

@@ -0,0 +1 @@
+"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[9335],{7814:(e,n,s)=>{s.r(n),s.d(n,{assets:()=>c,contentTitle:()=>l,default:()=>h,frontMatter:()=>o,metadata:()=>t,toc:()=>d});const t=JSON.parse('{"id":"documentation/deploying/kubernetes/kubernetes-deployment-guide","title":"Kubernetes Deployment Guide","description":"Target Audience: DevOps Engineers & Kubernetes Administrators","source":"@site/docs/documentation/deploying/kubernetes/kubernetes-deployment-guide.md","sourceDirName":"documentation/deploying/kubernetes","slug":"/documentation/deploying/kubernetes/kubernetes-deployment-guide","permalink":"/solace-agent-mesh/docs/documentation/deploying/kubernetes/kubernetes-deployment-guide","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/deploying/kubernetes/kubernetes-deployment-guide.md","tags":[],"version":"current","frontMatter":{},"sidebar":"docSidebar","previous":{"title":"Kubernetes","permalink":"/solace-agent-mesh/docs/documentation/deploying/kubernetes/"},"next":{"title":"Monitoring Your Agent Mesh","permalink":"/solace-agent-mesh/docs/documentation/deploying/observability"}}');var r=s(4848),i=s(8453);const o={},l="Kubernetes Deployment Guide",c={},d=[{value:"1. Kubernetes Platform Support",id:"1-kubernetes-platform-support",level:2},{value:"Supported Versions",id:"supported-versions",level:3},{value:"Distribution Support Matrix",id:"distribution-support-matrix",level:3},{value:"Constraints & Limitations",id:"constraints--limitations",level:3},{value:"2. Compute Resource Guidance",id:"2-compute-resource-guidance",level:2},{value:"Processor Architecture Support",id:"processor-architecture-support",level:3},{value:"Recommended Node Sizing",id:"recommended-node-sizing",level:3},{value:"Component Resource Specifications",id:"component-resource-specifications",level:3},{value:"Custom Mesh Components (Customer-Managed)",id:"custom-mesh-components-customer-managed",level:3},{value:"Capacity Planning (Per Agent)",id:"capacity-planning-per-agent",level:3},{value:"3. Persistence Layer Strategy",id:"3-persistence-layer-strategy",level:2},{value:"A. Production Deployments (Mandatory)",id:"a-production-deployments-mandatory",level:3},{value:"B. Dev / POC Deployments (Optional Starter Layer)",id:"b-dev--poc-deployments-optional-starter-layer",level:3},{value:"5. Network Connectivity & Prerequisites",id:"5-network-connectivity--prerequisites",level:2},{value:"A. Inbound Traffic (Web Gateway)",id:"a-inbound-traffic-web-gateway",level:3},{value:"B. Outbound Platform Access",id:"b-outbound-platform-access",level:3},{value:"C. Application & Mesh Component Connectivity",id:"c-application--mesh-component-connectivity",level:3},{value:"D. Corporate Proxy Configuration",id:"d-corporate-proxy-configuration",level:3},{value:"E. Tooling & Guides",id:"e-tooling--guides",level:3}];function a(e){const n={a:"a",blockquote:"blockquote",code:"code",em:"em",h1:"h1",h2:"h2",h3:"h3",header:"header",li:"li",ol:"ol",p:"p",strong:"strong",ul:"ul",...(0,i.R)(),...e.components};return(0,r.jsxs)(r.Fragment,{children:[(0,r.jsx)(n.header,{children:(0,r.jsx)(n.h1,{id:"kubernetes-deployment-guide",children:"Kubernetes Deployment Guide"})}),"\n",(0,r.jsxs)(n.p,{children:[(0,r.jsx)(n.strong,{children:"Target Audience:"})," DevOps Engineers & Kubernetes Administrators"]}),"\n",(0,r.jsxs)(n.p,{children:[(0,r.jsx)(n.strong,{children:"Purpose:"})," Infrastructure prerequisites and sizing guidance for deploying Solace Agent Mesh (SAM) Enterprise in customer-managed Kubernetes environments."]}),"\n",(0,r.jsx)(n.h2,{id:"1-kubernetes-platform-support",children:"1. Kubernetes Platform Support"}),"\n",(0,r.jsx)(n.p,{children:"SAM is designed to run on standard, CNCF-compliant Kubernetes clusters. While we adhere to open standards, our Quality Assurance (QA) validation focuses on the managed services of major cloud providers."}),"\n",(0,r.jsx)(n.h3,{id:"supported-versions",children:"Supported Versions"}),"\n",(0,r.jsxs)(n.p,{children:["We support the ",(0,r.jsx)(n.strong,{children:"three (3) most recent minor versions of upstream Kubernetes"}),"."]}),"\n",(0,r.jsxs)(n.ul,{children:["\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"For Cloud Managed (EKS, AKS, GKE):"})," We validate against the provider's default release channels."]}),"\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"For On-Premise (OpenShift, Rancher, etc.):"})," Compatibility is determined by the ",(0,r.jsx)(n.strong,{children:"underlying Kubernetes API version"}),", not the vendor's product version. Ensure your distribution's K8s version falls within the supported upstream window."]}),"\n"]}),"\n",(0,r.jsx)(n.h3,{id:"distribution-support-matrix",children:"Distribution Support Matrix"}),"\n",(0,r.jsxs)("table",{children:[(0,r.jsx)("thead",{children:(0,r.jsxs)("tr",{children:[(0,r.jsx)("th",{style:{textAlign:"left"},children:(0,r.jsx)("strong",{children:"Category"})}),(0,r.jsx)("th",{style:{textAlign:"left"},children:(0,r.jsx)("strong",{children:"Distributions"})}),(0,r.jsx)("th",{style:{textAlign:"left"},children:(0,r.jsx)("strong",{children:"Support Level"})})]})}),(0,r.jsxs)("tbody",{children:[(0,r.jsxs)("tr",{children:[(0,r.jsx)("td",{style:{verticalAlign:"top"},children:(0,r.jsx)("strong",{children:"Validated"})}),(0,r.jsxs)("td",{style:{verticalAlign:"top"},children:["\u2022 AWS EKS",(0,r.jsx)("br",{}),"\u2022 Azure AKS",(0,r.jsx)("br",{}),"\u2022 Google GKE"]}),(0,r.jsxs)("td",{style:{verticalAlign:"top"},children:[(0,r.jsx)("strong",{children:"Tier 1 Support."})," We explicitly validate SAM releases against these environments."]})]}),(0,r.jsxs)("tr",{children:[(0,r.jsx)("td",{style:{verticalAlign:"top"},children:(0,r.jsx)("strong",{children:"Compatible"})}),(0,r.jsxs)("td",{style:{verticalAlign:"top"},children:["\u2022 Red Hat OpenShift",(0,r.jsx)("br",{}),"\u2022 VMware Tanzu (TKG)",(0,r.jsx)("br",{}),"\u2022 SUSE Rancher (RKE2)",(0,r.jsx)("br",{}),"\u2022 Oracle Container Engine (OKE)",(0,r.jsx)("br",{}),"\u2022 Canonical Charmed Kubernetes",(0,r.jsx)("br",{}),"\u2022 Upstream K8s (kubeadm)"]}),(0,r.jsxs)("td",{style:{verticalAlign:"top"},children:[(0,r.jsx)("strong",{children:"Tier 2 Support."})," SAM is compatible with standard Kubernetes APIs. For distributions with proprietary security constraints (e.g., OpenShift SCCs, Tanzu PSPs), Solace support is limited to confirming API compatibility only. Solace does not provide setup, configuration, or troubleshooting assistance for customer-specific security policies or proprietary features\u2014these remain the customer's responsibility."]})]})]})]}),"\n",(0,r.jsx)(n.h3,{id:"constraints--limitations",children:"Constraints & Limitations"}),"\n",(0,r.jsx)(n.p,{children:"To prevent deployment failures, ensure your cluster meets the following constraints:"}),"\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:"Node Architecture:"})," SAM requires ",(0,r.jsx)(n.strong,{children:"Standard Worker Nodes"})," backed by VMs or Bare Metal."]}),"\n",(0,r.jsxs)(n.ul,{children:["\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"Not Supported:"})," Serverless or Virtual Nodes (e.g., ",(0,r.jsx)(n.strong,{children:"AWS Fargate, GKE Autopilot"}),", Azure Virtual Nodes) are not supported due to local storage and networking limitations."]}),"\n"]}),"\n"]}),"\n",(0,r.jsxs)(n.li,{children:["\n",(0,r.jsx)(n.p,{children:(0,r.jsx)(n.strong,{children:"Security Context:"})}),"\n",(0,r.jsxs)(n.ul,{children:["\n",(0,r.jsxs)(n.li,{children:["SAM containers run as ",(0,r.jsx)(n.strong,{children:"non-root users"})," (UID 999) by default."]}),"\n",(0,r.jsxs)(n.li,{children:["SAM ",(0,r.jsx)(n.strong,{children:"does NOT"})," require ",(0,r.jsx)(n.code,{children:"privileged: true"})," capabilities or root access."]}),"\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.em,{children:"OpenShift Note:"})," You may need to add the service account to the ",(0,r.jsx)(n.code,{children:"nonroot"})," SCC if your cluster enforces ",(0,r.jsx)(n.code,{children:"restricted-v2"})," by default."]}),"\n"]}),"\n"]}),"\n",(0,r.jsxs)(n.li,{children:["\n",(0,r.jsx)(n.p,{children:(0,r.jsx)(n.strong,{children:"Monitoring:"})}),"\n",(0,r.jsxs)(n.ul,{children:["\n",(0,r.jsxs)(n.li,{children:["SAM ",(0,r.jsx)(n.strong,{children:"does NOT"})," deploy DaemonSets for monitoring."]}),"\n",(0,r.jsx)(n.li,{children:"Observability/Monitoring is the customer's responsibility."}),"\n"]}),"\n"]}),"\n"]}),"\n",(0,r.jsx)(n.h2,{id:"2-compute-resource-guidance",children:"2. Compute Resource Guidance"}),"\n",(0,r.jsx)(n.p,{children:"SAM workloads utilize a microservices architecture. Resource requirements scale based on the number of concurrent Agents you intend to run."}),"\n",(0,r.jsx)(n.h3,{id:"processor-architecture-support",children:"Processor Architecture Support"}),"\n",(0,r.jsx)(n.p,{children:"SAM container images are built for multi-architecture support. You may provision nodes using either architecture based on your organization's standards:"}),"\n",(0,r.jsxs)(n.ul,{children:["\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"ARM64 (Recommended):"})," Offers the best price/performance ratio (e.g., AWS Graviton, Azure Cobalt, Google Axion)."]}),"\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"x86_64 (Intel/AMD):"})," Fully supported for standard deployments."]}),"\n"]}),"\n",(0,r.jsx)(n.h3,{id:"recommended-node-sizing",children:"Recommended Node Sizing"}),"\n",(0,r.jsxs)(n.p,{children:["For Production environments, we recommend using latest-generation ",(0,r.jsx)(n.strong,{children:"General Purpose"})," worker nodes to balance CPU and Memory (with a 1:4 ratio)."]}),"\n",(0,r.jsxs)(n.ul,{children:["\n",(0,r.jsxs)(n.li,{children:["\n",(0,r.jsxs)(n.p,{children:[(0,r.jsx)(n.strong,{children:"Recommended Specification:"})," ",(0,r.jsx)(n.strong,{children:"4 vCPU / 16 GB RAM"})]}),"\n",(0,r.jsxs)(n.ul,{children:["\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.em,{children:"ARM Examples:"})," AWS ",(0,r.jsx)(n.code,{children:"m8g.xlarge"}),", Azure ",(0,r.jsx)(n.code,{children:"Standard_D4ps_v6"}),", GCP ",(0,r.jsx)(n.code,{children:"c4a-standard-4"})]}),"\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.em,{children:"x86 Examples:"})," AWS ",(0,r.jsx)(n.code,{children:"m8i.xlarge"}),", Azure ",(0,r.jsx)(n.code,{children:"Standard_D4s_v6"}),", GCP ",(0,r.jsx)(n.code,{children:"n2-standard-4"})]}),"\n"]}),"\n"]}),"\n",(0,r.jsxs)(n.li,{children:["\n",(0,r.jsxs)(n.p,{children:[(0,r.jsx)(n.strong,{children:"Minimum Specification:"})," ",(0,r.jsx)(n.strong,{children:"2 vCPU / 8 GB RAM"})," (Note: smaller nodes will limit agent density)."]}),"\n",(0,r.jsxs)(n.ul,{children:["\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.em,{children:"ARM Examples:"})," AWS ",(0,r.jsx)(n.code,{children:"m8g.large"}),", Azure ",(0,r.jsx)(n.code,{children:"Standard_D2ps_v6"}),", GCP ",(0,r.jsx)(n.code,{children:"c4a-standard-2"})]}),"\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.em,{children:"x86 Examples:"})," AWS ",(0,r.jsx)(n.code,{children:"m8i.large"}),", Azure ",(0,r.jsx)(n.code,{children:"Standard_D2s_v6"}),", GCP ",(0,r.jsx)(n.code,{children:"n2-standard-2"})]}),"\n"]}),"\n"]}),"\n"]}),"\n",(0,r.jsxs)(n.p,{children:[(0,r.jsx)(n.strong,{children:"Note"}),": For AWS, Azure, and GCP, should any of these instance types be unavailable in your region of choice, we recommend choosing the next closest equivalent (e.g. ",(0,r.jsx)(n.code,{children:"m7g.large"})," instead of ",(0,r.jsx)(n.code,{children:"m8g.large"}),")."]}),"\n",(0,r.jsx)(n.h3,{id:"component-resource-specifications",children:"Component Resource Specifications"}),"\n",(0,r.jsx)(n.p,{children:"To assist with Quota planning and, if in use, Cluster Autoscaler configuration, the following table details the default Resource Requests and Limits for the mandatory core components."}),"\n",(0,r.jsxs)(n.blockquote,{children:["\n",(0,r.jsxs)(n.p,{children:[(0,r.jsx)(n.strong,{children:"Note:"})," These values represent the application container only. If your environment injects sidecars (e.g., Istio, Dapr, Splunk), ensure you calculate additional overhead to prevent scheduling failures."]}),"\n"]}),"\n",(0,r.jsxs)("table",{children:[(0,r.jsx)("thead",{children:(0,r.jsxs)("tr",{children:[(0,r.jsx)("th",{style:{textAlign:"left"},children:(0,r.jsx)("strong",{children:"Component"})}),(0,r.jsx)("th",{style:{textAlign:"left"},children:(0,r.jsx)("strong",{children:"Description"})}),(0,r.jsx)("th",{style:{textAlign:"left"},children:(0,r.jsx)("strong",{children:"CPU Request"})}),(0,r.jsx)("th",{style:{textAlign:"left"},children:(0,r.jsx)("strong",{children:"CPU Limit"})}),(0,r.jsx)("th",{style:{textAlign:"left"},children:(0,r.jsx)("strong",{children:"RAM Request"})}),(0,r.jsx)("th",{style:{textAlign:"left"},children:(0,r.jsx)("strong",{children:"RAM Limit"})}),(0,r.jsx)("th",{style:{textAlign:"left"},children:(0,r.jsx)("strong",{children:"QoS Class"})})]})}),(0,r.jsxs)("tbody",{children:[(0,r.jsxs)("tr",{children:[(0,r.jsx)("td",{style:{verticalAlign:"top"},children:(0,r.jsx)("strong",{children:"Agent Mesh"})}),(0,r.jsx)("td",{style:{verticalAlign:"top"},children:"Includes Core services, Orchestrator Agent, and Web UI Gateway."}),(0,r.jsx)("td",{style:{verticalAlign:"top"},children:"175m"}),(0,r.jsx)("td",{style:{verticalAlign:"top"},children:"200m"}),(0,r.jsx)("td",{style:{verticalAlign:"top"},children:"625 MiB"}),(0,r.jsx)("td",{style:{verticalAlign:"top"},children:"1 GiB"}),(0,r.jsx)("td",{style:{verticalAlign:"top"},children:"Burstable"})]}),(0,r.jsxs)("tr",{children:[(0,r.jsx)("td",{style:{verticalAlign:"top"},children:(0,r.jsx)("strong",{children:"Deployer"})}),(0,r.jsx)("td",{style:{verticalAlign:"top"},children:"Responsible for dynamically deploying SAM-managed Agents, Gateways, and mesh components."}),(0,r.jsx)("td",{style:{verticalAlign:"top"},children:"100m"}),(0,r.jsx)("td",{style:{verticalAlign:"top"},children:"100m"}),(0,r.jsx)("td",{style:{verticalAlign:"top"},children:"100 MiB"}),(0,r.jsx)("td",{style:{verticalAlign:"top"},children:"100 MiB"}),(0,r.jsx)("td",{style:{verticalAlign:"top"},children:"Guaranteed"})]}),(0,r.jsxs)("tr",{children:[(0,r.jsx)("td",{style:{verticalAlign:"top"},children:(0,r.jsx)("strong",{children:"Agent"})}),(0,r.jsx)("td",{style:{verticalAlign:"top"},children:"The runtime for a single Agent instance (scales horizontally)."}),(0,r.jsx)("td",{style:{verticalAlign:"top"},children:"175m"}),(0,r.jsx)("td",{style:{verticalAlign:"top"},children:"200m"}),(0,r.jsx)("td",{style:{verticalAlign:"top"},children:"625 MiB"}),(0,r.jsx)("td",{style:{verticalAlign:"top"},children:"768 MiB"}),(0,r.jsx)("td",{style:{verticalAlign:"top"},children:"Burstable"})]})]})]}),"\n",(0,r.jsx)(n.h3,{id:"custom-mesh-components-customer-managed",children:"Custom Mesh Components (Customer-Managed)"}),"\n",(0,r.jsxs)(n.p,{children:["For ",(0,r.jsx)(n.strong,{children:"Custom Agents"})," or external components that are not managed/provisioned by the Deployer:"]}),"\n",(0,r.jsxs)(n.ul,{children:["\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"Responsibility:"})," The customer is responsible for defining the Deployment manifests and resource requirements."]}),"\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"Sizing:"})," We recommend starting with the ",(0,r.jsx)(n.code,{children:"SAM Agent"})," baseline (175m / 625 MiB) and adjusting based on the specific logic or model inference requirements of your custom code."]}),"\n"]}),"\n",(0,r.jsx)(n.h3,{id:"capacity-planning-per-agent",children:"Capacity Planning (Per Agent)"}),"\n",(0,r.jsxs)(n.p,{children:["When sizing your cluster, budget the following reservations for ",(0,r.jsx)(n.em,{children:"each"})," concurrent Solace Agent you plan to deploy:"]}),"\n",(0,r.jsxs)(n.ul,{children:["\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"Memory Request:"})," ",(0,r.jsx)(n.strong,{children:"625 MiB"})]}),"\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"Memory Limit:"})," ",(0,r.jsx)(n.strong,{children:"768 MiB"})]}),"\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"CPU Request:"})," ",(0,r.jsx)(n.strong,{children:"175m"})," (0.175 vCPU)"]}),"\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"CPU Limit:"})," ",(0,r.jsx)(n.strong,{children:"200m"})," (0.2 vCPU)"]}),"\n"]}),"\n",(0,r.jsx)(n.h2,{id:"3-persistence-layer-strategy",children:"3. Persistence Layer Strategy"}),"\n",(0,r.jsx)(n.p,{children:"SAM requires a relational database (PostgreSQL) and an object store (S3-compatible) to function."}),"\n",(0,r.jsx)(n.h3,{id:"a-production-deployments-mandatory",children:"A. Production Deployments (Mandatory)"}),"\n",(0,r.jsxs)(n.p,{children:["For production environments, you ",(0,r.jsx)(n.strong,{children:"must"})," provide your own managed external persistence services. Solace does not support running stateful databases inside the SAM cluster for production traffic."]}),"\n",(0,r.jsxs)(n.ul,{children:["\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"Database:"})," PostgreSQL 17+ (e.g., AWS RDS, Azure Database for PostgreSQL, Cloud SQL)."]}),"\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"Object Store:"})," S3-Compatible API (e.g., AWS S3, Azure Blob, Google Cloud Storage)."]}),"\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"Configuration:"})," Refer to the ",(0,r.jsx)(n.a,{href:"https://solacelabs.github.io/solace-agent-mesh/docs/documentation/installing-and-configuring/session-storage",children:(0,r.jsx)(n.em,{children:"Session Storage"})})," ",(0,r.jsx)(n.em,{children:"and"})," ",(0,r.jsx)(n.a,{href:"https://solacelabs.github.io/solace-agent-mesh/docs/documentation/installing-and-configuring/artifact-storage",children:(0,r.jsx)(n.em,{children:"Artifact Storage"})})," to configure connection strings and secrets for your installation."]}),"\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"Authentication:"})," Standard Username/Password authentication via Kubernetes Secret is supported."]}),"\n"]}),"\n",(0,r.jsx)(n.h3,{id:"b-dev--poc-deployments-optional-starter-layer",children:"B. Dev / POC Deployments (Optional Starter Layer)"}),"\n",(0,r.jsxs)(n.p,{children:["For convenience, the ",(0,r.jsx)(n.a,{href:"https://solacelabs.github.io/solace-agent-mesh/docs/documentation/deploying/kubernetes-deployment#using-the-helm-quickstart",children:"SAM Helm Quickstart"}),' chart includes an optional "Starter Persistence Layer" (Containerized PostgreSQL + SeaweedFS).']}),"\n",(0,r.jsxs)(n.ul,{children:["\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"Use Case:"})," Strictly for ",(0,r.jsx)(n.strong,{children:"Evaluation, Development, and Proof of Concept (POC)"}),"."]}),"\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"Support Policy:"})," ",(0,r.jsx)(n.strong,{children:"Unsupported."}),' Solace provides these components "as-is" for quick startup. We do not provide patches, backups, or data recovery support for embedded persistence pods.']}),"\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"Data Persistence:"})," If the pods restart, data is preserved only if a valid StorageClass is configured."]}),"\n"]}),"\n",(0,r.jsx)(n.p,{children:(0,r.jsx)(n.strong,{children:"Starter Layer Resource Requirements:"})}),"\n",(0,r.jsxs)("table",{children:[(0,r.jsx)("thead",{children:(0,r.jsxs)("tr",{children:[(0,r.jsx)("th",{style:{textAlign:"left"},children:(0,r.jsx)("strong",{children:"Component"})}),(0,r.jsx)("th",{style:{textAlign:"left"},children:(0,r.jsx)("strong",{children:"Description"})}),(0,r.jsx)("th",{style:{textAlign:"left"},children:(0,r.jsx)("strong",{children:"CPU Request"})}),(0,r.jsx)("th",{style:{textAlign:"left"},children:(0,r.jsx)("strong",{children:"CPU Limit"})}),(0,r.jsx)("th",{style:{textAlign:"left"},children:(0,r.jsx)("strong",{children:"RAM Request"})}),(0,r.jsx)("th",{style:{textAlign:"left"},children:(0,r.jsx)("strong",{children:"RAM Limit"})}),(0,r.jsx)("th",{style:{textAlign:"left"},children:(0,r.jsx)("strong",{children:"Recommended Volume Size"})}),(0,r.jsx)("th",{style:{textAlign:"left"},children:(0,r.jsx)("strong",{children:"QoS Class"})})]})}),(0,r.jsxs)("tbody",{children:[(0,r.jsxs)("tr",{children:[(0,r.jsxs)("td",{style:{verticalAlign:"top"},children:[(0,r.jsx)("strong",{children:"Postgres"})," (Starter)"]}),(0,r.jsx)("td",{style:{verticalAlign:"top"},children:"Embedded database for configuration state (Dev/POC only)."}),(0,r.jsx)("td",{style:{verticalAlign:"top"},children:"175m"}),(0,r.jsx)("td",{style:{verticalAlign:"top"},children:"175m"}),(0,r.jsx)("td",{style:{verticalAlign:"top"},children:"625 MiB"}),(0,r.jsx)("td",{style:{verticalAlign:"top"},children:"625 MiB"}),(0,r.jsx)("td",{style:{verticalAlign:"top"},children:"30 GiB"}),(0,r.jsx)("td",{style:{verticalAlign:"top"},children:"Guaranteed"})]}),(0,r.jsxs)("tr",{children:[(0,r.jsxs)("td",{style:{verticalAlign:"top"},children:[(0,r.jsx)("strong",{children:"SeaweedFS"})," (Starter)"]}),(0,r.jsx)("td",{style:{verticalAlign:"top"},children:"Embedded S3-compatible object storage for artifacts (Dev/POC only)."}),(0,r.jsx)("td",{style:{verticalAlign:"top"},children:"175m"}),(0,r.jsx)("td",{style:{verticalAlign:"top"},children:"175m"}),(0,r.jsx)("td",{style:{verticalAlign:"top"},children:"625 MiB"}),(0,r.jsx)("td",{style:{verticalAlign:"top"},children:"625 MiB"}),(0,r.jsx)("td",{style:{verticalAlign:"top"},children:"50 GiB"}),(0,r.jsx)("td",{style:{verticalAlign:"top"},children:"Guaranteed"})]})]})]}),"\n",(0,r.jsx)(n.p,{children:(0,r.jsx)(n.strong,{children:"Storage Class Recommendations (Starter Layer Only):"})}),"\n",(0,r.jsxs)(n.p,{children:["If you choose to use the ",(0,r.jsx)(n.strong,{children:"Starter Persistence Layer"})," for development, performance is heavily dependent on the underlying disk I/O. Using slow standard disks (HDD) will cause Agent timeouts."]}),"\n",(0,r.jsxs)(n.blockquote,{children:["\n",(0,r.jsx)(n.p,{children:(0,r.jsx)(n.strong,{children:"Warning:"})}),"\n",(0,r.jsxs)(n.ul,{children:["\n",(0,r.jsxs)(n.li,{children:["Default StorageClasses often have ",(0,r.jsx)(n.code,{children:"reclaimPolicy: Delete"}),". If you're using SAM Helm Quickstart, uninstalling the Helm release will permanently delete your Dev data. If data persistence is required across re-installs, please configure a StorageClass with ",(0,r.jsx)(n.code,{children:"reclaimPolicy: Retain"}),"."]}),"\n",(0,r.jsxs)(n.li,{children:["For managed Kubernetes clusters (e.g., EKS, AKS, GKE), use a ",(0,r.jsx)(n.code,{children:"StorageClass"})," with ",(0,r.jsx)(n.code,{children:"volumeBindingMode: WaitForFirstConsumer"})," and ensure the underlying disk is single-zone. This avoids initial scheduling and later re-scheduling failures due to cross-zone volumes."]}),"\n"]}),"\n"]}),"\n",(0,r.jsxs)(n.p,{children:["We recommend using ",(0,r.jsx)(n.strong,{children:"SSD-backed Storage Classes"}),":"]}),"\n",(0,r.jsxs)("table",{children:[(0,r.jsx)("thead",{children:(0,r.jsxs)("tr",{children:[(0,r.jsx)("th",{style:{textAlign:"left"},children:(0,r.jsx)("strong",{children:"Provider"})}),(0,r.jsx)("th",{style:{textAlign:"left"},children:(0,r.jsx)("strong",{children:"Recommended StorageClass"})}),(0,r.jsx)("th",{style:{textAlign:"left"},children:(0,r.jsx)("strong",{children:"Underlying Tech (Disk Type)"})})]})}),(0,r.jsxs)("tbody",{children:[(0,r.jsxs)("tr",{children:[(0,r.jsx)("td",{style:{verticalAlign:"top"},children:(0,r.jsx)("strong",{children:"AWS EKS"})}),(0,r.jsxs)("td",{style:{verticalAlign:"top"},children:["Any storage class using the ",(0,r.jsx)("code",{children:"gp3"})," disk type."]}),(0,r.jsx)("td",{style:{verticalAlign:"top"},children:"EBS General Purpose SSD. EBS volumes are implicitly zoned."})]}),(0,r.jsxs)("tr",{children:[(0,r.jsx)("td",{style:{verticalAlign:"top"},children:(0,r.jsx)("strong",{children:"Azure AKS"})}),(0,r.jsx)("td",{style:{verticalAlign:"top"},children:"Any storage class that uses zoned SSDs."}),(0,r.jsxs)("td",{style:{verticalAlign:"top"},children:["Azure Zoned Premium SSD (",(0,r.jsx)("code",{children:"Premium_LRS"}),")."]})]}),(0,r.jsxs)("tr",{children:[(0,r.jsx)("td",{style:{verticalAlign:"top"},children:(0,r.jsx)("strong",{children:"Google GKE"})}),(0,r.jsx)("td",{style:{verticalAlign:"top"},children:"Variable, depends on chosen instance type."}),(0,r.jsxs)("td",{style:{verticalAlign:"top"},children:["Variable, support depends on instance type. Search for ",(0,r.jsx)("code",{children:"Supported disk types"})," in ",(0,r.jsx)(n.a,{href:"https://docs.cloud.google.com/compute/docs/general-purpose-machines",children:"https://docs.cloud.google.com/compute/docs/general-purpose-machines"}),". Examples: hyperdisk-balanced pd-ssd"]})]}),(0,r.jsxs)("tr",{children:[(0,r.jsx)("td",{style:{verticalAlign:"top"},children:(0,r.jsx)("strong",{children:"Generic"})}),(0,r.jsx)("td",{style:{verticalAlign:"top"},children:"Any CSI driver supporting SSD"}),(0,r.jsx)("td",{style:{verticalAlign:"top"},children:"NVMe / SSD"})]})]})]}),"\n",(0,r.jsx)(n.p,{children:(0,r.jsx)(n.strong,{children:"Node Pool Topology Recommendations (Starter Layer Only):"})}),"\n",(0,r.jsxs)(n.p,{children:["In AKS, EKS, and GKE, if nodes are available in more than one availability zone for a region, one node pool (e.g. node group, or provider-specific equivalent) must be provisioned for each availability zone. The simplest approach with the starter layer is to provision node instances for SAM deployments in ",(0,r.jsx)(n.strong,{children:"one availability zone only"})," to avoid this complexity. Official recommendations from cloud providers are as follows:"]}),"\n",(0,r.jsxs)(n.ul,{children:["\n",(0,r.jsxs)(n.li,{children:["AKS: ",(0,r.jsx)(n.a,{href:"https://learn.microsoft.com/en-us/azure/aks/cluster-autoscaler?tabs=azure-cli#re-enable-the-cluster-autoscaler-on-a-node-pool",children:"https://learn.microsoft.com/en-us/azure/aks/cluster-autoscaler?tabs=azure-cli#re-enable-the-cluster-autoscaler-on-a-node-pool"})]}),"\n",(0,r.jsxs)(n.li,{children:["EKS: ",(0,r.jsx)(n.a,{href:"https://docs.aws.amazon.com/eks/latest/userguide/managed-node-groups.html#managed-node-group-concepts",children:"https://docs.aws.amazon.com/eks/latest/userguide/managed-node-groups.html#managed-node-group-concepts"})]}),"\n",(0,r.jsx)(n.li,{children:"GKE: We recommend following the above pattern for simplicity and consistency."}),"\n"]}),"\n",(0,r.jsx)(n.p,{children:"We recommend a similar approach for other cloud providers as applicable. This does not apply when using external persistence solutions (e.g. managed Postgres and S3-compatible storage) as all SAM workloads will be stateless."}),"\n",(0,r.jsx)(n.h2,{id:"5-network-connectivity--prerequisites",children:"5. Network Connectivity & Prerequisites"}),"\n",(0,r.jsx)(n.p,{children:"SAM operates as a connected application mesh. To ensure proper functionality, your network environment must allow specific inbound and outbound traffic flows."}),"\n",(0,r.jsx)(n.h3,{id:"a-inbound-traffic-web-gateway",children:"A. Inbound Traffic (Web Gateway)"}),"\n",(0,r.jsxs)(n.p,{children:["SAM provisions a ",(0,r.jsx)(n.strong,{children:"Web Gateway"})," service to handle incoming API traffic and UI access."]}),"\n",(0,r.jsxs)(n.ul,{children:["\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"Ingress Controller:"})," An Ingress Controller (e.g., NGINX, ALB) must be present in the cluster to route traffic to this Gateway."]}),"\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"TLS Termination:"})," Production deployments should terminate TLS at the Ingress layer. You must supply your TLS Certificate and Key as a standard Kubernetes Secret and reference it in your Helm ",(0,r.jsx)(n.code,{children:"values.yaml"}),"."]}),"\n"]}),"\n",(0,r.jsx)(n.h3,{id:"b-outbound-platform-access",children:"B. Outbound Platform Access"}),"\n",(0,r.jsx)(n.p,{children:"The core SAM platform requires outbound connectivity to specific infrastructure services."}),"\n",(0,r.jsxs)(n.ul,{children:["\n",(0,r.jsxs)(n.li,{children:["\n",(0,r.jsx)(n.p,{children:(0,r.jsx)(n.strong,{children:"Container Registry:"})}),"\n",(0,r.jsxs)(n.ul,{children:["\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"Direct Access:"})," Outbound access to ",(0,r.jsx)(n.code,{children:"gcr.io/gcp-maas-prod"}),". Requires a Pull Secret obtained from the Solace Cloud Console."]}),"\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"Private Mirror (Air-Gapped):"})," If using a private registry (e.g., Artifactory), you must mirror images from ",(0,r.jsx)(n.code,{children:"gcr.io"})," and configure ",(0,r.jsx)(n.code,{children:"global.imageRegistry"}),"."]}),"\n"]}),"\n"]}),"\n",(0,r.jsxs)(n.li,{children:["\n",(0,r.jsx)(n.p,{children:(0,r.jsx)(n.strong,{children:"Solace Event Broker Access:"})}),"\n",(0,r.jsxs)(n.ul,{children:["\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"Solace Cloud Event Broker Service:"})," Allow connectivity to ",(0,r.jsx)(n.code,{children:"*.messaging.solace.cloud"})," or your specific Solace Cloud region CNAMEs."]}),"\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"Self-Hosted Brokers:"})," Allow traffic to the SMF (55555) or SMF+TLS (55443) ports of your on-premise appliances/software brokers."]}),"\n"]}),"\n"]}),"\n",(0,r.jsxs)(n.li,{children:["\n",(0,r.jsx)(n.p,{children:(0,r.jsx)(n.strong,{children:"LLM Providers:"})}),"\n",(0,r.jsxs)(n.ul,{children:["\n",(0,r.jsxs)(n.li,{children:["The core platform (and Agents) requires access to your configured Model Providers (e.g., ",(0,r.jsx)(n.code,{children:"api.openai.com"}),", ",(0,r.jsx)(n.code,{children:"your-azure-endpoint.openai.azure.com"}),")."]}),"\n"]}),"\n"]}),"\n",(0,r.jsxs)(n.li,{children:["\n",(0,r.jsx)(n.p,{children:(0,r.jsx)(n.strong,{children:"Identity Provider (IdP) Access:"})}),"\n",(0,r.jsxs)(n.ul,{children:["\n",(0,r.jsx)(n.li,{children:"The SAM Control Plane requires outbound network connectivity to your organization's IdP (e.g., Microsoft Entra ID, AWS Cognito, or any SAML/OIDC-compliant provider) for authentication and authorization."}),"\n"]}),"\n"]}),"\n"]}),"\n",(0,r.jsx)(n.h3,{id:"c-application--mesh-component-connectivity",children:"C. Application & Mesh Component Connectivity"}),"\n",(0,r.jsxs)(n.p,{children:["Beyond the core platform, the specific ",(0,r.jsx)(n.strong,{children:"Agents"})," and ",(0,r.jsx)(n.strong,{children:"Gateways"})," you deploy will require their own network paths."]}),"\n",(0,r.jsxs)(n.ul,{children:["\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"Agent Integrations:"})," If you deploy Agents designed to interact with external enterprise systems (e.g., Salesforce, Jira, Snowflake, Oracle DB), you must ensure the Kubernetes worker nodes have network reachability to these target services."]}),"\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"Gateway Exposure:"})," If you deploy additional Mesh Gateways for specific domains or protocols, ensure your Ingress configuration allows for the necessary inbound routes, ports, and protocols."]}),"\n"]}),"\n",(0,r.jsx)(n.h3,{id:"d-corporate-proxy-configuration",children:"D. Corporate Proxy Configuration"}),"\n",(0,r.jsxs)(n.p,{children:["For environments with strict egress filtering, SAM supports routing outbound traffic through a corporate ",(0,r.jsx)(n.strong,{children:"HTTP/HTTPS Proxy"}),"."]}),"\n",(0,r.jsx)(n.h3,{id:"e-tooling--guides",children:"E. Tooling & Guides"}),"\n",(0,r.jsxs)(n.ul,{children:["\n",(0,r.jsxs)(n.li,{children:["\n",(0,r.jsx)(n.p,{children:(0,r.jsx)(n.strong,{children:"Installation Tooling:"})}),"\n",(0,r.jsxs)(n.ul,{children:["\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"Helm v3"})," is the recommended installer."]}),"\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"Alternative:"})," You may use ",(0,r.jsx)(n.code,{children:"helm template"})," to render manifests for direct ",(0,r.jsx)(n.code,{children:"kubectl"})," application or integration with GitOps tools (ArgoCD, Flux)."]}),"\n"]}),"\n"]}),"\n",(0,r.jsxs)(n.li,{children:["\n",(0,r.jsxs)(n.p,{children:[(0,r.jsx)(n.strong,{children:"Documentation:"})," Please refer to the ",(0,r.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/deploying/kubernetes/#using-the-helm-quickstart",children:"SAM Kubernetes Deployment Guide"})," for detailed configuration steps regarding the Helm chart, secrets, proxies, and network rules."]}),"\n"]}),"\n"]})]})}function h(e={}){const{wrapper:n}={...(0,i.R)(),...e.components};return n?(0,r.jsx)(n,{...e,children:(0,r.jsx)(a,{...e})}):a(e)}},8453:(e,n,s)=>{s.d(n,{R:()=>o,x:()=>l});var t=s(6540);const r={},i=t.createContext(r);function o(e){const n=t.useContext(i);return t.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:o(e.components),t.createElement(i.Provider,{value:n},e.children)}}}]);

solace_agent_mesh/assets/docs/assets/js/a94703ab.3e5fbcb3.js

@@ -0,0 +1 @@
+"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[9048],{8115:(e,t,n)=>{n.r(t),n.d(t,{default:()=>ke});var a=n(6540),i=n(4164),o=n(5500),s=n(7559),l=n(4718),c=n(609),r=n(1312),d=n(3104),u=n(5062);const m={backToTopButton:"backToTopButton_sjWU",backToTopButtonShow:"backToTopButtonShow_xfvO"};var b=n(4848);function h(){const{shown:e,scrollToTop:t}=function({threshold:e}){const[t,n]=(0,a.useState)(!1),i=(0,a.useRef)(!1),{startScroll:o,cancelScroll:s}=(0,d.gk)();return(0,d.Mq)((({scrollY:t},a)=>{const o=a?.scrollY;o&&(i.current?i.current=!1:t>=o?(s(),n(!1)):t<e?n(!1):t+window.innerHeight<document.documentElement.scrollHeight&&n(!0))})),(0,u.$)((e=>{e.location.hash&&(i.current=!0,n(!1))})),{shown:t,scrollToTop:()=>o(0)}}({threshold:300});return(0,b.jsx)("button",{"aria-label":(0,r.T)({id:"theme.BackToTopButton.buttonAriaLabel",message:"Scroll back to top",description:"The ARIA label for the back to top button"}),className:(0,i.A)("clean-btn",s.G.common.backToTopButton,m.backToTopButton,e&&m.backToTopButtonShow),type:"button",onClick:t})}var p=n(3109),x=n(6347),f=n(4581),j=n(6342),_=n(3465);function g(e){return(0,b.jsx)("svg",{width:"20",height:"20","aria-hidden":"true",...e,children:(0,b.jsxs)("g",{fill:"#7a7a7a",children:[(0,b.jsx)("path",{d:"M9.992 10.023c0 .2-.062.399-.172.547l-4.996 7.492a.982.982 0 01-.828.454H1c-.55 0-1-.453-1-1 0-.2.059-.403.168-.551l4.629-6.942L.168 3.078A.939.939 0 010 2.528c0-.548.45-.997 1-.997h2.996c.352 0 .649.18.828.45L9.82 9.472c.11.148.172.347.172.55zm0 0"}),(0,b.jsx)("path",{d:"M19.98 10.023c0 .2-.058.399-.168.547l-4.996 7.492a.987.987 0 01-.828.454h-3c-.547 0-.996-.453-.996-1 0-.2.059-.403.168-.551l4.625-6.942-4.625-6.945a.939.939 0 01-.168-.55 1 1 0 01.996-.997h3c.348 0 .649.18.828.45l4.996 7.492c.11.148.168.347.168.55zm0 0"})]})})}const v="collapseSidebarButton_PEFL",k="collapseSidebarButtonIcon_kv0_";function A({onClick:e}){return(0,b.jsx)("button",{type:"button",title:(0,r.T)({id:"theme.docs.sidebar.collapseButtonTitle",message:"Collapse sidebar",description:"The title attribute for collapse button of doc sidebar"}),"aria-label":(0,r.T)({id:"theme.docs.sidebar.collapseButtonAriaLabel",message:"Collapse sidebar",description:"The title attribute for collapse button of doc sidebar"}),className:(0,i.A)("button button--secondary button--outline",v),onClick:e,children:(0,b.jsx)(g,{className:k})})}var C=n(5041),S=n(9532);const T=Symbol("EmptyContext"),N=a.createContext(T);function I({children:e}){const[t,n]=(0,a.useState)(null),i=(0,a.useMemo)((()=>({expandedItem:t,setExpandedItem:n})),[t]);return(0,b.jsx)(N.Provider,{value:i,children:e})}var y=n(1422),B=n(9169),L=n(8774),w=n(2303),E=n(6654),M=n(3186);const H="menuExternalLink_NmtK",P="linkLabel_WmDU";function G({label:e}){return(0,b.jsx)("span",{title:e,className:P,children:e})}function W({item:e,onItemClick:t,activePath:n,level:a,index:o,...c}){const{href:r,label:d,className:u,autoAddBaseUrl:m}=e,h=(0,l.w8)(e,n),p=(0,E.A)(r);return(0,b.jsx)("li",{className:(0,i.A)(s.G.docs.docSidebarItemLink,s.G.docs.docSidebarItemLinkLevel(a),"menu__list-item",u),children:(0,b.jsxs)(L.A,{className:(0,i.A)("menu__link",!p&&H,{"menu__link--active":h}),autoAddBaseUrl:m,"aria-current":h?"page":void 0,to:r,...p&&{onClick:t?()=>t(e):void 0},...c,children:[(0,b.jsx)(G,{label:d}),!p&&(0,b.jsx)(M.A,{})]})},d)}const R="categoryLink_byQd",D="categoryLinkLabel_W154";function U({collapsed:e,categoryLabel:t,onClick:n}){return(0,b.jsx)("button",{"aria-label":e?(0,r.T)({id:"theme.DocSidebarItem.expandCategoryAriaLabel",message:"Expand sidebar category '{label}'",description:"The ARIA label to expand the sidebar category"},{label:t}):(0,r.T)({id:"theme.DocSidebarItem.collapseCategoryAriaLabel",message:"Collapse sidebar category '{label}'",description:"The ARIA label to collapse the sidebar category"},{label:t}),"aria-expanded":!e,type:"button",className:"clean-btn menu__caret",onClick:n})}function F({label:e}){return(0,b.jsx)("span",{title:e,className:D,children:e})}function V(e){return 0===(0,l.Y)(e.item.items,e.activePath).length?(0,b.jsx)(Y,{...e}):(0,b.jsx)(K,{...e})}function Y({item:e,...t}){if("string"!=typeof e.href)return null;const{type:n,collapsed:a,collapsible:i,items:o,linkUnlisted:s,...l}=e,c={type:"link",...l};return(0,b.jsx)(W,{item:c,...t})}function K({item:e,onItemClick:t,activePath:n,level:o,index:c,...r}){const{items:d,label:u,collapsible:m,className:h,href:p}=e,{docs:{sidebar:{autoCollapseCategories:x}}}=(0,j.p)(),f=function(e){const t=(0,w.A)();return(0,a.useMemo)((()=>e.href&&!e.linkUnlisted?e.href:!t&&e.collapsible?(0,l.Nr)(e):void 0),[e,t])}(e),_=(0,l.w8)(e,n),g=(0,B.ys)(p,n),{collapsed:v,setCollapsed:k}=(0,y.u)({initialState:()=>!!m&&(!_&&e.collapsed)}),{expandedItem:A,setExpandedItem:C}=function(){const e=(0,a.useContext)(N);if(e===T)throw new S.dV("DocSidebarItemsExpandedStateProvider");return e}(),I=(e=!v)=>{C(e?null:c),k(e)};!function({isActive:e,collapsed:t,updateCollapsed:n,activePath:i}){const o=(0,S.ZC)(e),s=(0,S.ZC)(i);(0,a.useEffect)((()=>{(e&&!o||e&&o&&i!==s)&&t&&n(!1)}),[e,o,t,n,i,s])}({isActive:_,collapsed:v,updateCollapsed:I,activePath:n}),(0,a.useEffect)((()=>{m&&null!=A&&A!==c&&x&&k(!0)}),[m,A,c,k,x]);return(0,b.jsxs)("li",{className:(0,i.A)(s.G.docs.docSidebarItemCategory,s.G.docs.docSidebarItemCategoryLevel(o),"menu__list-item",{"menu__list-item--collapsed":v},h),children:[(0,b.jsxs)("div",{className:(0,i.A)("menu__list-item-collapsible",{"menu__list-item-collapsible--active":g}),children:[(0,b.jsx)(L.A,{className:(0,i.A)(R,"menu__link",{"menu__link--sublist":m,"menu__link--sublist-caret":!p&&m,"menu__link--active":_}),onClick:n=>{t?.(e),m&&(p?g?(n.preventDefault(),I()):I(!1):(n.preventDefault(),I()))},"aria-current":g?"page":void 0,role:m&&!p?"button":void 0,"aria-expanded":m&&!p?!v:void 0,href:m?f??"#":f,...r,children:(0,b.jsx)(F,{label:u})}),p&&m&&(0,b.jsx)(U,{collapsed:v,categoryLabel:u,onClick:e=>{e.preventDefault(),I()}})]}),(0,b.jsx)(y.N,{lazy:!0,as:"ul",className:"menu__list",collapsed:v,children:(0,b.jsx)(Z,{items:d,tabIndex:v?-1:0,onItemClick:t,activePath:n,level:o+1})})]})}const z="menuHtmlItem_M9Kj";function q({item:e,level:t,index:n}){const{value:a,defaultStyle:o,className:l}=e;return(0,b.jsx)("li",{className:(0,i.A)(s.G.docs.docSidebarItemLink,s.G.docs.docSidebarItemLinkLevel(t),o&&[z,"menu__list-item"],l),dangerouslySetInnerHTML:{__html:a}},n)}function O({item:e,...t}){switch(e.type){case"category":return(0,b.jsx)(V,{item:e,...t});case"html":return(0,b.jsx)(q,{item:e,...t});default:return(0,b.jsx)(W,{item:e,...t})}}function Q({items:e,...t}){const n=(0,l.Y)(e,t.activePath);return(0,b.jsx)(I,{children:n.map(((e,n)=>(0,b.jsx)(O,{item:e,index:n,...t},n)))})}const Z=(0,a.memo)(Q),J="menu_SIkG",X="menuWithAnnouncementBar_GW3s";function $({path:e,sidebar:t,className:n}){const o=function(){const{isActive:e}=(0,C.M)(),[t,n]=(0,a.useState)(e);return(0,d.Mq)((({scrollY:t})=>{e&&n(0===t)}),[e]),e&&t}();return(0,b.jsx)("nav",{"aria-label":(0,r.T)({id:"theme.docs.sidebar.navAriaLabel",message:"Docs sidebar",description:"The ARIA label for the sidebar navigation"}),className:(0,i.A)("menu thin-scrollbar",J,o&&X,n),children:(0,b.jsx)("ul",{className:(0,i.A)(s.G.docs.docSidebarMenu,"menu__list"),children:(0,b.jsx)(Z,{items:t,activePath:e,level:1})})})}const ee="sidebar_njMd",te="sidebarWithHideableNavbar_wUlq",ne="sidebarHidden_VK0M",ae="sidebarLogo_isFc";function ie({path:e,sidebar:t,onCollapse:n,isHidden:a}){const{navbar:{hideOnScroll:o},docs:{sidebar:{hideable:s}}}=(0,j.p)();return(0,b.jsxs)("div",{className:(0,i.A)(ee,o&&te,a&&ne),children:[o&&(0,b.jsx)(_.A,{tabIndex:-1,className:ae}),(0,b.jsx)($,{path:e,sidebar:t}),s&&(0,b.jsx)(A,{onClick:n})]})}const oe=a.memo(ie);var se=n(5600),le=n(2069);const ce=({sidebar:e,path:t})=>{const n=(0,le.M)();return(0,b.jsx)("ul",{className:(0,i.A)(s.G.docs.docSidebarMenu,"menu__list"),children:(0,b.jsx)(Z,{items:e,activePath:t,onItemClick:e=>{"category"===e.type&&e.href&&n.toggle(),"link"===e.type&&n.toggle()},level:1})})};function re(e){return(0,b.jsx)(se.GX,{component:ce,props:e})}const de=a.memo(re);function ue(e){const t=(0,f.l)(),n="desktop"===t||"ssr"===t,a="mobile"===t;return(0,b.jsxs)(b.Fragment,{children:[n&&(0,b.jsx)(oe,{...e}),a&&(0,b.jsx)(de,{...e})]})}const me={expandButton:"expandButton_TmdG",expandButtonIcon:"expandButtonIcon_i1dp"};function be({toggleSidebar:e}){return(0,b.jsx)("div",{className:me.expandButton,title:(0,r.T)({id:"theme.docs.sidebar.expandButtonTitle",message:"Expand sidebar",description:"The ARIA label and title attribute for expand button of doc sidebar"}),"aria-label":(0,r.T)({id:"theme.docs.sidebar.expandButtonAriaLabel",message:"Expand sidebar",description:"The ARIA label and title attribute for expand button of doc sidebar"}),tabIndex:0,role:"button",onKeyDown:e,onClick:e,children:(0,b.jsx)(g,{className:me.expandButtonIcon})})}const he={docSidebarContainer:"docSidebarContainer_YfHR",docSidebarContainerHidden:"docSidebarContainerHidden_DPk8",sidebarViewport:"sidebarViewport_aRkj"};function pe({children:e}){const t=(0,c.t)();return(0,b.jsx)(a.Fragment,{children:e},t?.name??"noSidebar")}function xe({sidebar:e,hiddenSidebarContainer:t,setHiddenSidebarContainer:n}){const{pathname:o}=(0,x.zy)(),[l,c]=(0,a.useState)(!1),r=(0,a.useCallback)((()=>{l&&c(!1),!l&&(0,p.O)()&&c(!0),n((e=>!e))}),[n,l]);return(0,b.jsx)("aside",{className:(0,i.A)(s.G.docs.docSidebarContainer,he.docSidebarContainer,t&&he.docSidebarContainerHidden),onTransitionEnd:e=>{e.currentTarget.classList.contains(he.docSidebarContainer)&&t&&c(!0)},children:(0,b.jsx)(pe,{children:(0,b.jsxs)("div",{className:(0,i.A)(he.sidebarViewport,l&&he.sidebarViewportHidden),children:[(0,b.jsx)(ue,{sidebar:e,path:o,onCollapse:r,isHidden:l}),l&&(0,b.jsx)(be,{toggleSidebar:r})]})})})}const fe={docMainContainer:"docMainContainer_TBSr",docMainContainerEnhanced:"docMainContainerEnhanced_lQrH",docItemWrapperEnhanced:"docItemWrapperEnhanced_JWYK"};function je({hiddenSidebarContainer:e,children:t}){const n=(0,c.t)();return(0,b.jsx)("main",{className:(0,i.A)(fe.docMainContainer,(e||!n)&&fe.docMainContainerEnhanced),children:(0,b.jsx)("div",{className:(0,i.A)("container padding-top--md padding-bottom--lg",fe.docItemWrapper,e&&fe.docItemWrapperEnhanced),children:t})})}const _e={docRoot:"docRoot_UBD9",docsWrapper:"docsWrapper_hBAB"};function ge({children:e}){const t=(0,c.t)(),[n,i]=(0,a.useState)(!1);return(0,b.jsxs)("div",{className:_e.docsWrapper,children:[(0,b.jsx)(h,{}),(0,b.jsxs)("div",{className:_e.docRoot,children:[t&&(0,b.jsx)(xe,{sidebar:t.items,hiddenSidebarContainer:n,setHiddenSidebarContainer:i}),(0,b.jsx)(je,{hiddenSidebarContainer:n,children:e})]})]})}var ve=n(3363);function ke(e){const t=(0,l.B5)(e);if(!t)return(0,b.jsx)(ve.A,{});const{docElement:n,sidebarName:a,sidebarItems:r}=t;return(0,b.jsx)(o.e3,{className:(0,i.A)(s.G.page.docsDocPage),children:(0,b.jsx)(c.V,{name:a,items:r,children:(0,b.jsx)(ge,{children:n})})})}},3363:(e,t,n)=>{n.d(t,{A:()=>l});n(6540);var a=n(4164),i=n(1312),o=n(1107),s=n(4848);function l({className:e}){return(0,s.jsx)("main",{className:(0,a.A)("container margin-vert--xl",e),children:(0,s.jsx)("div",{className:"row",children:(0,s.jsxs)("div",{className:"col col--6 col--offset-3",children:[(0,s.jsx)(o.A,{as:"h1",className:"hero__title",children:(0,s.jsx)(i.A,{id:"theme.NotFound.title",description:"The title of the 404 page",children:"Page Not Found"})}),(0,s.jsx)("p",{children:(0,s.jsx)(i.A,{id:"theme.NotFound.p1",description:"The first paragraph of the 404 page",children:"We could not find what you were looking for."})}),(0,s.jsx)("p",{children:(0,s.jsx)(i.A,{id:"theme.NotFound.p2",description:"The 2nd paragraph of the 404 page",children:"Please contact the owner of the site that linked you to the original URL and let them know their link is broken."})})]})})})}}}]);

solace_agent_mesh/assets/docs/assets/js/ab9708a8.3e563275.js

@@ -0,0 +1 @@
+"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[9257],{4074:(e,t,n)=>{n.r(t),n.d(t,{assets:()=>c,contentTitle:()=>r,default:()=>h,frontMatter:()=>a,metadata:()=>o,toc:()=>l});const o=JSON.parse('{"id":"documentation/getting-started/getting-started","title":"Getting Started","description":"Agent Mesh is an open-source framework for building event-driven multi-agent AI systems that solve complex problems through intelligent collaboration. You can use it to create teams of specialized AI agents that work together seamlessly, each bringing unique capabilities while communicating through Solace\'s proven event-driven architecture.","source":"@site/docs/documentation/getting-started/getting-started.md","sourceDirName":"documentation/getting-started","slug":"/documentation/getting-started/","permalink":"/solace-agent-mesh/docs/documentation/getting-started/","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/getting-started/getting-started.md","tags":[],"version":"current","sidebarPosition":12,"frontMatter":{"title":"Getting Started","sidebar_position":12},"sidebar":"docSidebar","next":{"title":"What is Agent Mesh?","permalink":"/solace-agent-mesh/docs/documentation/getting-started/introduction"}}');var s=n(4848),i=n(8453);const a={title:"Getting Started",sidebar_position:12},r="Get Started with Agent Mesh",c={},l=[{value:"Understanding Agent Mesh",id:"understanding-agent-mesh",level:2},{value:"Getting Started Quickly",id:"getting-started-quickly",level:2},{value:"Building with Agent Mesh",id:"building-with-agent-mesh",level:2},{value:"Core Components",id:"core-components",level:2},{value:"Advanced Capabilities",id:"advanced-capabilities",level:2},{value:"Learning Through Examples",id:"learning-through-examples",level:2},{value:"Additional Resources",id:"additional-resources",level:2}];function d(e){const t={a:"a",h1:"h1",h2:"h2",header:"header",p:"p",...(0,i.R)(),...e.components};return(0,s.jsxs)(s.Fragment,{children:[(0,s.jsx)(t.header,{children:(0,s.jsx)(t.h1,{id:"get-started-with-agent-mesh",children:"Get Started with Agent Mesh"})}),"\n",(0,s.jsx)(t.p,{children:"Agent Mesh is an open-source framework for building event-driven multi-agent AI systems that solve complex problems through intelligent collaboration. You can use it to create teams of specialized AI agents that work together seamlessly, each bringing unique capabilities while communicating through Solace's proven event-driven architecture."}),"\n",(0,s.jsx)(t.p,{children:"Whether you're building intelligent automation systems, creating sophisticated AI workflows, or integrating AI capabilities across your enterprise, Agent Mesh provides the foundation you need. The framework handles agent communication automatically, so you can focus on building powerful AI experiences that scale with your needs."}),"\n",(0,s.jsx)(t.h2,{id:"understanding-agent-mesh",children:"Understanding Agent Mesh"}),"\n",(0,s.jsxs)(t.p,{children:["Before diving into implementation, it's helpful to understand what makes Agent Mesh unique. The framework combines the power of Google's Agent Development Kit with Solace's event-driven messaging platform, creating a robust foundation for multi-agent AI systems. To learn about the core concepts and architectural principles that drive the framework's design, see ",(0,s.jsx)(t.a,{href:"/solace-agent-mesh/docs/documentation/getting-started/introduction",children:"What is Agent Mesh?"})]}),"\n",(0,s.jsxs)(t.p,{children:["The system's event-driven architecture enables true scalability and reliability, allowing agents to communicate asynchronously while maintaining loose coupling between components. For detailed insights into how these components work together to create a cohesive AI ecosystem, see ",(0,s.jsx)(t.a,{href:"/solace-agent-mesh/docs/documentation/getting-started/architecture",children:"Architecture Overview"})]}),"\n",(0,s.jsxs)(t.p,{children:["To see how all the pieces fit together, you can explore the key building blocks that make up every Agent Mesh deployment. For more information, see ",(0,s.jsx)(t.a,{href:"/solace-agent-mesh/docs/documentation/components/",children:"Components Overview"})]}),"\n",(0,s.jsx)(t.h2,{id:"getting-started-quickly",children:"Getting Started Quickly"}),"\n",(0,s.jsxs)(t.p,{children:["The fastest way to experience Agent Mesh is through our pre-configured Docker setup that gets you up and running with a working system in minutes. This approach lets you explore the framework's capabilities immediately without any installation or complex configuration. To get started right away, see ",(0,s.jsx)(t.a,{href:"/solace-agent-mesh/docs/documentation/getting-started/try-agent-mesh",children:"Try Agent Mesh"})]}),"\n",(0,s.jsxs)(t.p,{children:["Once you've explored the basic functionality and want to set up your own development environment, you'll need to install the CLI and framework tools. The installation process supports multiple approaches including pip, uv, and Docker, making it easy to integrate with your existing workflow. For complete setup instructions, see ",(0,s.jsx)(t.a,{href:"/solace-agent-mesh/docs/documentation/installing-and-configuring/installation",children:"Installation"})]}),"\n",(0,s.jsxs)(t.p,{children:["For those ready to build their own projects from scratch, comprehensive guidance is available for creating and configuring custom deployments with full control over your agent mesh. This approach provides the flexibility needed for serious development work and production environments. To learn about project creation and configuration, see ",(0,s.jsx)(t.a,{href:"/solace-agent-mesh/docs/documentation/installing-and-configuring/run-project",children:"Creating and Running an Agent Mesh Project"})]}),"\n",(0,s.jsxs)(t.p,{children:["Vibe coding is an alternative approach for learning and building projects from scratch with minimal prior knowledge of Solace Agent Mesh. To learn more about vibe coding, see ",(0,s.jsx)(t.a,{href:"/solace-agent-mesh/docs/documentation/getting-started/vibe_coding",children:"Vibe Coding"})]}),"\n",(0,s.jsx)(t.h2,{id:"building-with-agent-mesh",children:"Building with Agent Mesh"}),"\n",(0,s.jsx)(t.p,{children:"Creating effective AI systems requires understanding how to design and implement the right components for your use case. The framework provides several key building blocks that you can combine and customize to meet your specific needs."}),"\n",(0,s.jsxs)(t.p,{children:["Specialized AI components can perform specific tasks, access particular data sources, or integrate with external systems, with each agent bringing its own capabilities while participating in the larger collaborative ecosystem. To learn how to build these components, see ",(0,s.jsx)(t.a,{href:"/solace-agent-mesh/docs/documentation/developing/create-agents",children:"Creating Agents"})]}),"\n",(0,s.jsxs)(t.p,{children:["Interfaces that connect your agent mesh to the outside world enable integration through REST APIs, web interfaces, chat platforms, or custom integrations. For guidance on building these connection points, see ",(0,s.jsx)(t.a,{href:"/solace-agent-mesh/docs/documentation/developing/create-gateways",children:"Creating Gateways"})]}),"\n",(0,s.jsxs)(t.p,{children:["Custom tools extend functionality beyond the built-in capabilities, allowing agents to interact with databases, APIs, file systems, or any other resources your applications require. To understand how to add these extensions, see ",(0,s.jsx)(t.a,{href:"/solace-agent-mesh/docs/documentation/developing/creating-python-tools",children:"Creating Python Tools"})]}),"\n",(0,s.jsx)(t.h2,{id:"core-components",children:"Core Components"}),"\n",(0,s.jsx)(t.p,{children:"Agent Mesh is built around several fundamental components that work together to create intelligent, collaborative systems. Understanding these components helps you design effective solutions and troubleshoot issues when they arise."}),"\n",(0,s.jsxs)(t.p,{children:["The intelligent workers of your system are powered by AI models and equipped with specialized tools, capable of analyzing data, generating content, making decisions, and delegating tasks to other agents when needed. For more information, see ",(0,s.jsx)(t.a,{href:"/solace-agent-mesh/docs/documentation/components/agents",children:"Agents"})]}),"\n",(0,s.jsxs)(t.p,{children:["Bridges between your agent mesh and external systems translate requests from users, applications, or other systems into the standardized communication protocol that agents understand. To learn about these interface components, see ",(0,s.jsx)(t.a,{href:"/solace-agent-mesh/docs/documentation/components/gateways",children:"Gateways"})]}),"\n",(0,s.jsxs)(t.p,{children:["The conductor of your agent symphony breaks down complex requests into manageable tasks and coordinates the work of multiple agents to achieve sophisticated outcomes. For details about this coordination system, see ",(0,s.jsx)(t.a,{href:"/solace-agent-mesh/docs/documentation/components/orchestrator",children:"Orchestrator"})]}),"\n",(0,s.jsxs)(t.p,{children:["A powerful extension mechanism lets you add new capabilities to your system without modifying core components, making it easy to integrate with existing tools and services. To understand how to extend your system, see ",(0,s.jsx)(t.a,{href:"/solace-agent-mesh/docs/documentation/components/plugins",children:"Plugins"})]}),"\n",(0,s.jsxs)(t.p,{children:["Comprehensive command-line tools manage your projects from initial setup through deployment and ongoing maintenance. For information about these development tools, see ",(0,s.jsx)(t.a,{href:"/solace-agent-mesh/docs/documentation/components/cli",children:"CLI"})]}),"\n",(0,s.jsx)(t.h2,{id:"advanced-capabilities",children:"Advanced Capabilities"}),"\n",(0,s.jsx)(t.p,{children:"As your AI systems grow in complexity and scale, Agent Mesh provides advanced features to support enterprise deployments and sophisticated use cases."}),"\n",(0,s.jsxs)(t.p,{children:["Various approaches for running Agent Mesh in production range from single-machine setups to distributed enterprise deployments across multiple environments. To explore your deployment options, see ",(0,s.jsx)(t.a,{href:"/solace-agent-mesh/docs/documentation/deploying/deployment-options",children:"Deployment Options"}),"."]}),"\n",(0,s.jsxs)(t.p,{children:["For comprehensive guidance on deploying to Kubernetes with Helm charts and enterprise configurations, see ",(0,s.jsx)(t.a,{href:"/solace-agent-mesh/docs/documentation/deploying/kubernetes/",children:"Kubernetes"}),"."]}),"\n",(0,s.jsxs)(t.p,{children:["Real-time monitoring capabilities help you track performance metrics and debug issues when they occur, with the framework's event-driven architecture providing natural visibility into all system interactions. For guidance on system monitoring, see ",(0,s.jsx)(t.a,{href:"/solace-agent-mesh/docs/documentation/deploying/observability",children:"Observability"})]}),"\n",(0,s.jsxs)(t.p,{children:["Organizations with specific security and governance requirements can leverage advanced capabilities including role-based access control, single sign-on integration, and enterprise-grade security features. To learn about these advanced features, see ",(0,s.jsx)(t.a,{href:"/solace-agent-mesh/docs/documentation/enterprise/",children:"Enterprise Features"})]}),"\n",(0,s.jsx)(t.h2,{id:"learning-through-examples",children:"Learning Through Examples"}),"\n",(0,s.jsx)(t.p,{children:"Practical tutorials help you understand how to apply Agent Mesh to real-world scenarios. These hands-on guides walk you through building complete solutions that demonstrate the framework's capabilities."}),"\n",(0,s.jsxs)(t.p,{children:["Creating agents that can query databases and provide intelligent responses based on your organization's data demonstrates how to integrate with existing data sources. For a complete walkthrough, see ",(0,s.jsx)(t.a,{href:"/solace-agent-mesh/docs/documentation/developing/tutorials/sql-database",children:"SQL Database Integration"})]}),"\n",(0,s.jsxs)(t.p,{children:["Building a gateway that lets users interact with your agent mesh directly through Slack brings AI capabilities into existing workflows and communication platforms. To learn how to set this up, see ",(0,s.jsx)(t.a,{href:"/solace-agent-mesh/docs/documentation/developing/tutorials/slack-integration",children:"Slack Integration"})]}),"\n",(0,s.jsxs)(t.p,{children:["Creating a specialized agent from scratch, including tool integration and configuration, shows you the complete development process for custom components. For step-by-step guidance, see ",(0,s.jsx)(t.a,{href:"/solace-agent-mesh/docs/documentation/developing/tutorials/custom-agent",children:"Custom Agent Tutorial"})]}),"\n",(0,s.jsxs)(t.p,{children:["Incorporating Model Context Protocol servers into your agent mesh extends capabilities through standardized integrations with external tools and services. To understand this integration approach, see ",(0,s.jsx)(t.a,{href:"/solace-agent-mesh/docs/documentation/developing/tutorials/mcp-integration",children:"MCP Integration"})]}),"\n",(0,s.jsx)(t.h2,{id:"additional-resources",children:"Additional Resources"}),"\n",(0,s.jsxs)(t.p,{children:["Beyond the core documentation, several resources can help you get the most out of Agent Mesh. The latest source code, example configurations, and community discussions are available in the ",(0,s.jsx)(t.a,{href:"https://github.com/SolaceLabs/solace-agent-mesh",children:"GitHub repository"})]}),"\n",(0,s.jsxs)(t.p,{children:["Pre-built functionality for common use cases provides tested integrations that you can incorporate into your own projects. You can find these extensions in the ",(0,s.jsx)(t.a,{href:"https://github.com/SolaceLabs/solace-agent-mesh-core-plugins",children:"official plugins repository"})]}),"\n",(0,s.jsxs)(t.p,{children:["Participating in the project's development is possible through reporting issues, suggesting improvements, or contributing code. To learn how you can get involved, see the ",(0,s.jsx)(t.a,{href:"https://github.com/SolaceLabs/solace-agent-mesh/blob/main/CONTRIBUTING.md",children:"Contributing Guide"})]})]})}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:()=>a,x:()=>r});var o=n(6540);const s={},i=o.createContext(s);function a(e){const t=o.useContext(i);return o.useMemo((function(){return"function"==typeof e?e(t):{...t,...e}}),[t,e])}function r(e){let t;return t=e.disableParentContext?"function"==typeof e.components?e.components(s):e.components||s:a(e.components),o.createElement(i.Provider,{value:t},e.children)}}}]);

solace_agent_mesh/assets/docs/assets/js/c93cbaa0.0e0d8baf.js

@@ -0,0 +1 @@
+"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[1537],{9377:(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/developing/tutorials/rag-integration","title":"RAG Integration","description":"This tutorial guides you through setting up and configuring 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/developing/tutorials/rag-integration.md","sourceDirName":"documentation/developing/tutorials","slug":"/documentation/developing/tutorials/rag-integration","permalink":"/solace-agent-mesh/docs/documentation/developing/tutorials/rag-integration","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/developing/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/developing/tutorials/slack-integration"},"next":{"title":"Microsoft Teams Integration (Enterprise)","permalink":"/solace-agent-mesh/docs/documentation/developing/tutorials/teams-integration"}}');var r=t(4848),a=t(8453);const o={title:"RAG Integration",sidebar_position:70,toc_max_heading_level:4},s="RAG Integration",l={},c=[{value:"What is Agent Mesh RAG?",id:"what-is-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,a.R)(),...e.components};return(0,r.jsxs)(r.Fragment,{children:[(0,r.jsx)(n.header,{children:(0,r.jsx)(n.h1,{id:"rag-integration",children:"RAG Integration"})}),"\n",(0,r.jsx)(n.p,{children:"This tutorial guides you through setting up and configuring 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,r.jsx)(n.h2,{id:"what-is-agent-mesh-rag",children:"What is Agent Mesh RAG?"}),"\n",(0,r.jsx)(n.p,{children:"The Agent Mesh RAG plugin enhances your agents with the ability to perform retrieval-augmented generation. This means the agent can:"}),"\n",(0,r.jsxs)(n.ul,{children:["\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"Scan"})," documents from various sources (local filesystem, Google Drive, etc.)."]}),"\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"Preprocess"})," and ",(0,r.jsx)(n.strong,{children:"split"})," the text into manageable chunks."]}),"\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"Embed"})," these chunks into vectors and store them in a vector database."]}),"\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"Retrieve"})," relevant chunks of text based on a user's query."]}),"\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"Generate"})," an answer using a large language model (LLM) augmented with the retrieved information."]}),"\n"]}),"\n",(0,r.jsx)(n.p,{children:"This allows you to build agents that can answer questions about your own private data."}),"\n",(0,r.jsx)(n.h2,{id:"prerequisites",children:"Prerequisites"}),"\n",(0,r.jsx)(n.p,{children:"Before you begin, ensure you have:"}),"\n",(0,r.jsxs)(n.ul,{children:["\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/installing-and-configuring/installation",children:"Installed Agent Mesh and the Agent Mesh CLI"}),"."]}),"\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/installing-and-configuring/run-project",children:"Created a new Agent Mesh project"}),"."]}),"\n",(0,r.jsx)(n.li,{children:"Access to a vector database (for example, Qdrant, Chroma, and Pinecone)."}),"\n",(0,r.jsx)(n.li,{children:"Access to an LLM for generation and an embedding model."}),"\n",(0,r.jsx)(n.li,{children:"A directory with some documents for the agent to ingest."}),"\n"]}),"\n",(0,r.jsx)(n.h2,{id:"adding-the-rag-plugin",children:"Adding the RAG Plugin"}),"\n",(0,r.jsx)(n.p,{children:"To add the RAG plugin to your Agent Mesh project, run the following command:"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-sh",children:"sam plugin add my-rag-agent --plugin sam-rag\n"})}),"\n",(0,r.jsxs)(n.p,{children:["Replace ",(0,r.jsx)(n.code,{children:"my-rag-agent"})," with your preferred agent name. This command:"]}),"\n",(0,r.jsxs)(n.ul,{children:["\n",(0,r.jsxs)(n.li,{children:["Installs the ",(0,r.jsx)(n.code,{children:"sam-rag"})," plugin."]}),"\n",(0,r.jsxs)(n.li,{children:["Creates a new agent configuration file at ",(0,r.jsx)(n.code,{children:"configs/agents/my-rag-agent.yaml"}),"."]}),"\n"]}),"\n",(0,r.jsx)(n.h2,{id:"configuring-the-rag-agent",children:"Configuring the RAG Agent"}),"\n",(0,r.jsxs)(n.p,{children:["The RAG agent requires a detailed configuration. Open ",(0,r.jsx)(n.code,{children:"configs/agents/my-rag-agent.yaml"})," to configure the following sections:"]}),"\n",(0,r.jsx)(n.h3,{id:"shared-configuration",children:"Shared Configuration"}),"\n",(0,r.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,r.jsx)(n.code,{children:"shared_config.yaml"})," file."]}),"\n",(0,r.jsx)(n.pre,{children:(0,r.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,r.jsx)(n.h3,{id:"rag-pipeline-configuration",children:"RAG Pipeline Configuration"}),"\n",(0,r.jsxs)(n.p,{children:["The RAG pipeline has several stages, each with its own configuration block within the ",(0,r.jsx)(n.code,{children:"app_config"})," section of your ",(0,r.jsx)(n.code,{children:"my-rag-agent.yaml"})," file."]}),"\n",(0,r.jsx)(n.h4,{id:"1-scanner-configuration",children:"1. Scanner Configuration"}),"\n",(0,r.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,r.jsx)(n.p,{children:(0,r.jsx)(n.strong,{children:"Local Filesystem Example:"})}),"\n",(0,r.jsx)(n.pre,{children:(0,r.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,r.jsxs)(n.p,{children:[(0,r.jsx)(n.strong,{children:"Multi-Cloud Source Example:"}),"\nYou can also configure multiple sources, including Google Drive, OneDrive, and S3."]}),"\n",(0,r.jsx)(n.pre,{children:(0,r.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,r.jsx)(n.h4,{id:"2-preprocessor-configuration",children:"2. Preprocessor Configuration"}),"\n",(0,r.jsx)(n.p,{children:"The preprocessor cleans the text extracted from documents."}),"\n",(0,r.jsx)(n.pre,{children:(0,r.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,r.jsx)(n.h4,{id:"3-splitter-configuration",children:"3. Splitter Configuration"}),"\n",(0,r.jsx)(n.p,{children:"The splitter breaks down large documents into smaller chunks. Different splitters are available for different file types."}),"\n",(0,r.jsx)(n.pre,{children:(0,r.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,r.jsx)(n.h4,{id:"4-embedding-configuration",children:"4. Embedding Configuration"}),"\n",(0,r.jsx)(n.p,{children:"This section defines the model used to create vector embeddings from the text chunks."}),"\n",(0,r.jsx)(n.pre,{children:(0,r.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,r.jsx)(n.h4,{id:"5-vector-database-configuration",children:"5. Vector Database Configuration"}),"\n",(0,r.jsx)(n.p,{children:"Configure the connection to your vector database where the embeddings are stored."}),"\n",(0,r.jsx)(n.p,{children:(0,r.jsx)(n.strong,{children:"Qdrant Example:"})}),"\n",(0,r.jsx)(n.pre,{children:(0,r.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,r.jsx)(n.p,{children:(0,r.jsx)(n.strong,{children:"Chroma Example:"})}),"\n",(0,r.jsx)(n.pre,{children:(0,r.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,r.jsx)(n.h4,{id:"6-llm-configuration",children:"6. LLM Configuration"}),"\n",(0,r.jsx)(n.p,{children:"Configure the LLM that is used to generate answers based on the retrieved context."}),"\n",(0,r.jsx)(n.pre,{children:(0,r.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,r.jsx)(n.h4,{id:"7-retrieval-configuration",children:"7. Retrieval Configuration"}),"\n",(0,r.jsx)(n.p,{children:"This defines how many document chunks are retrieved to answer a query."}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-yaml",children:"retrieval:\n  top_k: 7\n"})}),"\n",(0,r.jsx)(n.h3,{id:"environment-variables",children:"Environment Variables"}),"\n",(0,r.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,r.jsx)(n.code,{children:".env"})," file:"]}),"\n",(0,r.jsx)(n.pre,{children:(0,r.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\nDOCUMENTS_PATH="./my_documents" # Relative path to your documents folder\n'})}),"\n",(0,r.jsxs)(n.p,{children:["Create a directory named ",(0,r.jsx)(n.code,{children:"my_documents"})," in your project root and place some text or markdown files inside it."]}),"\n",(0,r.jsx)(n.h2,{id:"running-the-rag-agent",children:"Running the RAG Agent"}),"\n",(0,r.jsx)(n.p,{children:"Once you have configured your agent and set the environment variables, you can run it:"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-sh",children:"sam run configs/agents/my-rag-agent.yaml\n"})}),"\n",(0,r.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,r.jsx)(n.h2,{id:"testing-the-rag-agent",children:"Testing the RAG Agent"}),"\n",(0,r.jsx)(n.p,{children:"Once your agent is running, you can test its retrieval capabilities and ingest new documents."}),"\n",(0,r.jsx)(n.h3,{id:"ingesting-documents",children:"Ingesting Documents"}),"\n",(0,r.jsx)(n.p,{children:"There are two primary ways to ingest documents into your RAG agent's knowledge base:"}),"\n",(0,r.jsx)(n.h4,{id:"option-1-automatic-scanning-batch-ingestion",children:"Option 1: Automatic Scanning (Batch Ingestion)"}),"\n",(0,r.jsxs)(n.p,{children:["This method uses the configured ",(0,r.jsx)(n.code,{children:"scanner"})," component. The agent automatically ingests documents from the directories specified in your configuration upon startup."]}),"\n",(0,r.jsx)(n.p,{children:(0,r.jsx)(n.strong,{children:"Step 1: Create a Document"})}),"\n",(0,r.jsxs)(n.p,{children:["First, create a simple text file named ",(0,r.jsx)(n.code,{children:"sam_features.txt"})," and add some content to it. For example:"]}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-text",children:"Agent Mesh is a powerful framework for building AI agents.\nKey features of 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,r.jsx)(n.p,{children:(0,r.jsx)(n.strong,{children:"Step 2: Place the Document in the Scanned Directory"})}),"\n",(0,r.jsxs)(n.p,{children:['In the "Environment Variables" section, we configured ',(0,r.jsx)(n.code,{children:"LOCAL_DOCUMENTS_PATH"})," to point to a directory (e.g., ",(0,r.jsx)(n.code,{children:"./my_documents"}),")."]}),"\n",(0,r.jsxs)(n.p,{children:["Create this directory in your project's root folder if you haven't already, and move your ",(0,r.jsx)(n.code,{children:"sam_features.txt"})," file into it."]}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-sh",children:"mkdir -p my_documents\nmv sam_features.txt my_documents/\n"})}),"\n",(0,r.jsx)(n.p,{children:(0,r.jsx)(n.strong,{children:"Step 3: Run the Agent to Trigger Ingestion"})}),"\n",(0,r.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,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-sh",children:"sam run configs/agents/my-rag-agent.yaml\n"})}),"\n",(0,r.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,r.jsx)(n.h4,{id:"option-2-manual-upload-via-gateway",children:"Option 2: Manual Upload via Gateway"}),"\n",(0,r.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,r.jsx)(n.p,{children:(0,r.jsx)(n.strong,{children:"Step 1: Start the RAG Agent and Web UI"})}),"\n",(0,r.jsx)(n.p,{children:"Ensure both your RAG agent and the Web UI gateway are running."}),"\n",(0,r.jsx)(n.p,{children:(0,r.jsx)(n.strong,{children:"Step 2: Upload a Document in the Web UI"})}),"\n",(0,r.jsxs)(n.ol,{children:["\n",(0,r.jsxs)(n.li,{children:["Open the Web UI (usually at ",(0,r.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,r.jsx)(n.li,{children:"Use the file attachment button to select a document from your local machine."}),"\n",(0,r.jsxs)(n.li,{children:["Send a prompt along with the file, instructing the agent to ingest it. For example:","\n",(0,r.jsxs)(n.blockquote,{children:["\n",(0,r.jsx)(n.p,{children:'"Please ingest the attached document into your knowledge base."'}),"\n"]}),"\n"]}),"\n"]}),"\n",(0,r.jsxs)(n.p,{children:["The RAG agent uses its ",(0,r.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,r.jsx)(n.p,{children:(0,r.jsx)(n.strong,{children:"Step 3: Confirm Ingestion"})}),"\n",(0,r.jsx)(n.p,{children:"After the agent confirms that the document has been ingested, you can immediately ask questions about its content."}),"\n",(0,r.jsx)(n.h3,{id:"querying-the-knowledge-base",children:"Querying the Knowledge Base"}),"\n",(0,r.jsx)(n.p,{children:"You can interact with your RAG agent through any gateway, such as the Web UI gateway."}),"\n",(0,r.jsxs)(n.ol,{children:["\n",(0,r.jsx)(n.li,{children:"Make sure you have a Web UI gateway running (or add one to your project)."}),"\n",(0,r.jsxs)(n.li,{children:["Open the Web UI (usually at ",(0,r.jsx)(n.code,{children:"http://localhost:8000"}),")."]}),"\n",(0,r.jsxs)(n.li,{children:["Start a conversation with ",(0,r.jsx)(n.code,{children:"my-rag-agent"}),"."]}),"\n",(0,r.jsx)(n.li,{children:"Ask a question related to the content of the documents you provided during the initial scan."}),"\n"]}),"\n",(0,r.jsx)(n.p,{children:"For example, if you have a document about product features, you could ask:"}),"\n",(0,r.jsxs)(n.blockquote,{children:["\n",(0,r.jsx)(n.p,{children:'"What are the key features of Product X?"'}),"\n"]}),"\n",(0,r.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,r.jsx)(n.h2,{id:"troubleshooting",children:"Troubleshooting"}),"\n",(0,r.jsxs)(n.ul,{children:["\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"Connection Errors"}),": Double-check all your URLs, API keys, and credentials for your LLM and vector database."]}),"\n",(0,r.jsxs)(n.li,{children:[(0,r.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,r.jsxs)(n.li,{children:[(0,r.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,r.jsx)(n.code,{children:"top_k"})," retrieval setting is too low."]}),"\n"]})]})}function h(e={}){const{wrapper:n}={...(0,a.R)(),...e.components};return n?(0,r.jsx)(n,{...e,children:(0,r.jsx)(d,{...e})}):d(e)}},8453:(e,n,t)=>{t.d(n,{R:()=>o,x:()=>s});var i=t(6540);const r={},a=i.createContext(r);function o(e){const n=i.useContext(a);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(r):e.components||r:o(e.components),i.createElement(a.Provider,{value:n},e.children)}}}]);

solace_agent_mesh/assets/docs/assets/js/cab03b5b.6a073091.js

@@ -0,0 +1 @@
+"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[3731],{7376:(e,n,i)=>{i.r(n),i.d(n,{assets:()=>c,contentTitle:()=>o,default:()=>h,frontMatter:()=>l,metadata:()=>s,toc:()=>a});const s=JSON.parse('{"id":"documentation/enterprise/openapi-tools","title":"OpenAPI Tools","description":"This guide walks you through configuring OpenAPI-based tools for Agent Mesh Enterprise. You will learn how to integrate REST APIs into your agents using OpenAPI specifications, enabling them to interact with any OpenAPI-compliant service.","source":"@site/docs/documentation/enterprise/openapi-tools.md","sourceDirName":"documentation/enterprise","slug":"/documentation/enterprise/openapi-tools","permalink":"/solace-agent-mesh/docs/documentation/enterprise/openapi-tools","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/enterprise/openapi-tools.md","tags":[],"version":"current","sidebarPosition":16,"frontMatter":{"title":"OpenAPI Tools","sidebar_position":16},"sidebar":"docSidebar","previous":{"title":"Secure User Delegated Access","permalink":"/solace-agent-mesh/docs/documentation/enterprise/secure-user-delegated-access"}}');var t=i(4848),r=i(8453);const l={title:"OpenAPI Tools",sidebar_position:16},o=void 0,c={},a=[{value:"Table of Contents",id:"table-of-contents",level:2},{value:"Overview",id:"overview",level:2},{value:"Why Use OpenAPI Tools",id:"why-use-openapi-tools",level:3},{value:"Supported Features",id:"supported-features",level:3},{value:"Understanding OpenAPI Tools",id:"understanding-openapi-tools",level:2},{value:"How OpenAPI Tools Work",id:"how-openapi-tools-work",level:3},{value:"Prerequisites",id:"prerequisites",level:2},{value:"OpenAPI Specification",id:"openapi-specification",level:3},{value:"API Access",id:"api-access",level:3},{value:"Target Server URL",id:"target-server-url",level:3},{value:"Configuration Steps",id:"configuration-steps",level:2},{value:"Basic Configuration Structure",id:"basic-configuration-structure",level:3},{value:"Configuration Parameters",id:"configuration-parameters",level:3},{value:"tool_type",id:"tool_type",level:4},{value:"Specification Source (Mutually Exclusive)",id:"specification-source-mutually-exclusive",level:4},{value:"base_url",id:"base_url",level:4},{value:"Complete Example",id:"complete-example",level:3},{value:"Tool Filtering",id:"tool-filtering",level:2},{value:"Why Filter Tools",id:"why-filter-tools",level:3},{value:"Filter Types",id:"filter-types",level:3},{value:"allow_list",id:"allow_list",level:4},{value:"deny_list",id:"deny_list",level:4},{value:"Filter Configuration",id:"filter-configuration",level:3},{value:"Filtering Examples",id:"filtering-examples",level:3},{value:"Authentication",id:"authentication",level:2},{value:"API Key Authentication",id:"api-key-authentication",level:3},{value:"Service Account Authentication",id:"service-account-authentication",level:3},{value:"Best Practices",id:"best-practices",level:2},{value:"Use Environment Variables for Secrets",id:"use-environment-variables-for-secrets",level:3},{value:"Fetch Specs from URLs When Possible",id:"fetch-specs-from-urls-when-possible",level:3},{value:"Use allow_list for Security-Sensitive APIs",id:"use-allow_list-for-security-sensitive-apis",level:3},{value:"Provide Clear Agent Instructions",id:"provide-clear-agent-instructions",level:3},{value:"Test with Local APIs First",id:"test-with-local-apis-first",level:3},{value:"Troubleshooting",id:"troubleshooting",level:2},{value:"Specification Loading Fails",id:"specification-loading-fails",level:3},{value:"Tools Not Available to Agent",id:"tools-not-available-to-agent",level:3},{value:"Authentication Errors",id:"authentication-errors",level:3},{value:"API Calls Fail or Return Errors",id:"api-calls-fail-or-return-errors",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,r.R)(),...e.components};return(0,t.jsxs)(t.Fragment,{children:[(0,t.jsx)(n.p,{children:"This guide walks you through configuring OpenAPI-based tools for Agent Mesh Enterprise. You will learn how to integrate REST APIs into your agents using OpenAPI specifications, enabling them to interact with any OpenAPI-compliant service."}),"\n",(0,t.jsx)(n.h2,{id:"table-of-contents",children:"Table of Contents"}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsx)(n.li,{children:(0,t.jsx)(n.a,{href:"#overview",children:"Overview"})}),"\n",(0,t.jsx)(n.li,{children:(0,t.jsx)(n.a,{href:"#understanding-openapi-tools",children:"Understanding OpenAPI Tools"})}),"\n",(0,t.jsx)(n.li,{children:(0,t.jsx)(n.a,{href:"#prerequisites",children:"Prerequisites"})}),"\n",(0,t.jsx)(n.li,{children:(0,t.jsx)(n.a,{href:"#configuration-steps",children:"Configuration Steps"})}),"\n",(0,t.jsx)(n.li,{children:(0,t.jsx)(n.a,{href:"#tool-filtering",children:"Tool Filtering"})}),"\n",(0,t.jsx)(n.li,{children:(0,t.jsx)(n.a,{href:"#authentication",children:"Authentication"})}),"\n",(0,t.jsx)(n.li,{children:(0,t.jsx)(n.a,{href:"#best-practices",children:"Best Practices"})}),"\n",(0,t.jsx)(n.li,{children:(0,t.jsx)(n.a,{href:"#troubleshooting",children:"Troubleshooting"})}),"\n"]}),"\n",(0,t.jsx)(n.h2,{id:"overview",children:"Overview"}),"\n",(0,t.jsx)(n.p,{children:"OpenAPI Tools allow agents to interact with REST APIs by automatically generating tool definitions from OpenAPI (Swagger) specifications. This enables agents to call API endpoints as if they were native tools, with proper parameter validation, type checking, and documentation."}),"\n",(0,t.jsx)(n.h3,{id:"why-use-openapi-tools",children:"Why Use OpenAPI Tools"}),"\n",(0,t.jsx)(n.p,{children:"OpenAPI tools provide several important benefits for agent development:"}),"\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Automatic Tool Generation"}),": Define REST API integrations declaratively using existing OpenAPI specifications. No manual tool implementation required."]}),"\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Type Safety"}),": Parameter types, validation, and required fields are automatically enforced based on the OpenAPI schema."]}),"\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Documentation"}),": Tool descriptions and parameter documentation are extracted from the OpenAPI spec, helping the AI model understand how to use each tool effectively."]}),"\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Flexibility"}),": Support for multiple OpenAPI spec sources (files, URLs, inline), server URL overrides, and authentication methods."]}),"\n",(0,t.jsx)(n.h3,{id:"supported-features",children:"Supported Features"}),"\n",(0,t.jsx)(n.p,{children:"Agent Mesh Enterprise's OpenAPI tool integration supports:"}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:"OpenAPI 3.0+ specifications"})," in JSON or YAML format"]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:"Multiple specification sources"}),": local files, remote URLs, or inline specs"]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:"Server URL overrides"}),": Point specs to different environments (development, staging, production)"]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:"Tool filtering"}),": Include or exclude specific API operations using allow/deny lists"]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:"Authentication"}),": API key, and service account authentication"]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:"Automatic name conversion"}),": Handles camelCase operation IDs correctly"]}),"\n"]}),"\n",(0,t.jsx)(n.h2,{id:"understanding-openapi-tools",children:"Understanding OpenAPI Tools"}),"\n",(0,t.jsx)(n.p,{children:"Before you configure OpenAPI tools, you need to understand how they work and how API operations become callable tools."}),"\n",(0,t.jsx)(n.h3,{id:"how-openapi-tools-work",children:"How OpenAPI Tools Work"}),"\n",(0,t.jsx)(n.p,{children:"When you configure an OpenAPI tool, Agent Mesh Enterprise performs the following steps:"}),"\n",(0,t.jsxs)(n.ol,{children:["\n",(0,t.jsxs)(n.li,{children:["\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Specification Loading"}),": The system loads the OpenAPI specification from the configured source (file, URL, or inline)."]}),"\n"]}),"\n",(0,t.jsxs)(n.li,{children:["\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Operation Discovery"}),": Each path and HTTP method combination in the spec becomes a potential tool. The operation's ",(0,t.jsx)(n.code,{children:"operationId"})," becomes the tool name."]}),"\n"]}),"\n",(0,t.jsxs)(n.li,{children:["\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Schema Conversion"}),": OpenAPI parameter schemas are converted to the format expected by the AI model, including type information, validation rules, and descriptions."]}),"\n"]}),"\n",(0,t.jsxs)(n.li,{children:["\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Tool Registration"}),": Each operation is registered as a callable tool with the agent. The AI model can then invoke these tools by name."]}),"\n"]}),"\n",(0,t.jsxs)(n.li,{children:["\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Request Execution"}),": When the agent calls a tool, Agent Mesh Enterprise constructs the appropriate HTTP request based on the OpenAPI spec and executes it against the target API."]}),"\n"]}),"\n",(0,t.jsxs)(n.li,{children:["\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Response Handling"}),": API responses are returned to the agent and can be used in subsequent tool calls or included in the agent's response to the user."]}),"\n"]}),"\n"]}),"\n",(0,t.jsx)(n.h2,{id:"prerequisites",children:"Prerequisites"}),"\n",(0,t.jsx)(n.p,{children:"Before you configure OpenAPI tools, ensure you have the following:"}),"\n",(0,t.jsx)(n.h3,{id:"openapi-specification",children:"OpenAPI Specification"}),"\n",(0,t.jsx)(n.p,{children:"You need access to an OpenAPI specification for the API you want to integrate. This can be:"}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsx)(n.li,{children:"A local OpenAPI spec file (JSON or YAML)"}),"\n",(0,t.jsx)(n.li,{children:"A URL to a remote OpenAPI spec"}),"\n",(0,t.jsx)(n.li,{children:"An inline OpenAPI spec defined in your configuration"}),"\n"]}),"\n",(0,t.jsx)(n.p,{children:"Most modern REST APIs provide OpenAPI specifications. Check the API provider's documentation for:"}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsx)(n.li,{children:"Swagger/OpenAPI spec download links"}),"\n",(0,t.jsx)(n.li,{children:"API documentation pages (often generated from the spec)"}),"\n",(0,t.jsx)(n.li,{children:"Developer portals that provide spec access"}),"\n"]}),"\n",(0,t.jsx)(n.h3,{id:"api-access",children:"API Access"}),"\n",(0,t.jsx)(n.p,{children:"Depending on the API's authentication requirements, you may need:"}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:"API Keys"}),": For APIs using API key authentication"]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:"Service Account"}),": For Google Cloud and similar services"]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:"Network Access"}),": Ensure your Agent Mesh Enterprise deployment can reach the API endpoints"]}),"\n"]}),"\n",(0,t.jsx)(n.h3,{id:"target-server-url",children:"Target Server URL"}),"\n",(0,t.jsx)(n.p,{children:"If the OpenAPI spec's server URLs don't match your target environment, you'll need the correct base URL for the API. For example:"}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsxs)(n.li,{children:["Spec may contain: ",(0,t.jsx)(n.code,{children:"https://api.production.com"})]}),"\n",(0,t.jsxs)(n.li,{children:["You may want to use: ",(0,t.jsx)(n.code,{children:"http://localhost:8080"})," (local development)"]}),"\n"]}),"\n",(0,t.jsx)(n.h2,{id:"configuration-steps",children:"Configuration Steps"}),"\n",(0,t.jsx)(n.p,{children:"Configuring OpenAPI tools involves specifying the spec source, optional server URL override, authentication, and tool filtering."}),"\n",(0,t.jsx)(n.h3,{id:"basic-configuration-structure",children:"Basic Configuration Structure"}),"\n",(0,t.jsx)(n.p,{children:"An OpenAPI tool configuration follows this structure:"}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-yaml",children:'tools:\n  - tool_type: openapi\n    specification_url: "https://petstore3.swagger.io/api/v3/openapi.json"\n    base_url: "http://localhost:8080"\n    auth:\n      type: apikey\n      in: header\n      name: api_key\n      value: ${API_KEY}\n'})}),"\n",(0,t.jsx)(n.h3,{id:"configuration-parameters",children:"Configuration Parameters"}),"\n",(0,t.jsx)(n.h4,{id:"tool_type",children:"tool_type"}),"\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Required"}),": Yes"]}),"\n",(0,t.jsx)(n.p,{children:"Identifies this as an OpenAPI tool configuration."}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-yaml",children:"tool_type: openapi\n"})}),"\n",(0,t.jsx)(n.h4,{id:"specification-source-mutually-exclusive",children:"Specification Source (Mutually Exclusive)"}),"\n",(0,t.jsx)(n.p,{children:"You must provide exactly one of the following specification sources:"}),"\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"specification_file"})," - Path to a local OpenAPI spec file:"]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-yaml",children:'specification_file: "examples/petstore_openapi.json"\n'})}),"\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"specification_url"})," - URL to fetch the OpenAPI spec from:"]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-yaml",children:'specification_url: "https://petstore3.swagger.io/api/v3/openapi.json"\n'})}),"\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"specification"})," - Inline OpenAPI spec as a string:"]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-yaml",children:'specification: |\n  {\n    "openapi": "3.0.0",\n    "info": {\n      "title": "My API",\n      "version": "1.0.0"\n    },\n    "paths": {}\n  }\nspecification_format: "json" # Optional: "json" or "yaml"\n'})}),"\n",(0,t.jsxs)(n.p,{children:["When using inline ",(0,t.jsx)(n.code,{children:"specification"}),", you can optionally provide ",(0,t.jsx)(n.code,{children:"specification_format"})," to hint at the format. The system auto-detects the format if not specified. Provide this only if auto-detection fails."]}),"\n",(0,t.jsx)(n.h4,{id:"base_url",children:"base_url"}),"\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Required"}),": No"]}),"\n",(0,t.jsx)(n.p,{children:"Override the server URLs in the OpenAPI specification. This is useful when:"}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsxs)(n.li,{children:["The spec contains only a path (e.g., ",(0,t.jsx)(n.code,{children:"/api/v3"}),") without a base URL"]}),"\n",(0,t.jsx)(n.li,{children:"You want to point to a different environment (development, staging, production)"}),"\n",(0,t.jsx)(n.li,{children:"You're using a spec from one source but targeting a different server"}),"\n"]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-yaml",children:'base_url: "http://localhost:8080"\n'})}),"\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"How it works"}),":"]}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsxs)(n.li,{children:["If the original spec URL is ",(0,t.jsx)(n.code,{children:"/api/v3"})," and ",(0,t.jsx)(n.code,{children:"base_url"})," is ",(0,t.jsx)(n.code,{children:"http://localhost:8080"}),", the result is ",(0,t.jsx)(n.code,{children:"http://localhost:8080/api/v3"})]}),"\n",(0,t.jsxs)(n.li,{children:["If the original spec URL is ",(0,t.jsx)(n.code,{children:"https://petstore.swagger.io/api/v3"})," and ",(0,t.jsx)(n.code,{children:"base_url"})," is ",(0,t.jsx)(n.code,{children:"http://localhost:8080"}),", the result is ",(0,t.jsx)(n.code,{children:"http://localhost:8080/api/v3"})," (path is preserved, base is replaced)"]}),"\n",(0,t.jsx)(n.li,{children:"Duplicate slashes are automatically handled"}),"\n"]}),"\n",(0,t.jsx)(n.h3,{id:"complete-example",children:"Complete Example"}),"\n",(0,t.jsx)(n.p,{children:"Here's a complete agent configuration using an OpenAPI tool:"}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-yaml",children:'apps:\n  - name: pet_store_agent\n    app_config:\n      agent_name: "PetStoreAgent"\n      display_name: "Pet Store API Agent"\n\n      model: gemini-2.5-pro\n\n      instruction: |\n        You are a Pet Store API agent that can manage pets, orders, and users.\n        Always provide the required fields when creating or updating resources.\n\n      tools:\n        - tool_type: openapi\n          specification_url: "https://petstore3.swagger.io/api/v3/openapi.json"\n          base_url: "http://localhost:8080"\n          auth:\n            type: apikey\n            in: header\n            name: api_key\n            value: ${PET_STORE_API_KEY}\n\n      session_service:\n        type: "sql"\n        database_url: "${DATABASE_URL}"\n        default_behavior: "PERSISTENT"\n'})}),"\n",(0,t.jsx)(n.h2,{id:"tool-filtering",children:"Tool Filtering"}),"\n",(0,t.jsx)(n.p,{children:"OpenAPI specifications often include many operations, but you may only want to expose a subset to your agent. Tool filtering allows you to control which operations are available."}),"\n",(0,t.jsx)(n.h3,{id:"why-filter-tools",children:"Why Filter Tools"}),"\n",(0,t.jsx)(n.p,{children:"Filtering tools provides several benefits:"}),"\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Security"}),": Exclude dangerous or administrative operations from agent access."]}),"\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Focused Agents"}),": Create specialized agents that only access relevant operations."]}),"\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Performance"}),": Reduce the number of tools the AI model must consider, improving response time and accuracy."]}),"\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Cost Control"}),": Fewer tools mean less token usage when the AI model selects tools."]}),"\n",(0,t.jsx)(n.h3,{id:"filter-types",children:"Filter Types"}),"\n",(0,t.jsx)(n.p,{children:"You can use two mutually exclusive filter types:"}),"\n",(0,t.jsx)(n.h4,{id:"allow_list",children:"allow_list"}),"\n",(0,t.jsx)(n.p,{children:"Include only specific operations. All other operations are excluded."}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-yaml",children:'tools:\n  - tool_type: openapi\n    specification_url: "https://petstore3.swagger.io/api/v3/openapi.json"\n    allow_list:\n      - "getPetById"\n      - "findPetsByStatus"\n      - "updatePet"\n'})}),"\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Use when"}),": You want explicit control over allowed operations, typically for security-sensitive APIs."]}),"\n",(0,t.jsx)(n.h4,{id:"deny_list",children:"deny_list"}),"\n",(0,t.jsx)(n.p,{children:"Exclude specific operations. All other operations are included."}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-yaml",children:'tools:\n  - tool_type: openapi\n    specification_url: "https://petstore3.swagger.io/api/v3/openapi.json"\n    deny_list:\n      - "deletePet"\n      - "deleteOrder"\n      - "deleteUser"\n'})}),"\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Use when"}),": You want most operations available but need to exclude a few dangerous or unnecessary ones."]}),"\n",(0,t.jsx)(n.h3,{id:"filter-configuration",children:"Filter Configuration"}),"\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Specifying Operation IDs"}),": Use the ",(0,t.jsx)(n.code,{children:"operationId"})," as they appear in the OpenAPI spec."]}),"\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Finding Operation IDs"}),": Look in the OpenAPI spec under ",(0,t.jsx)(n.code,{children:"paths[path][method].operationId"}),":"]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-json",children:'{\n  "paths": {\n    "/pet/{petId}": {\n      "get": {\n        "operationId": "getPetById",\n        "summary": "Find pet by ID"\n      }\n    }\n  }\n}\n'})}),"\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Mutual Exclusivity"}),": You cannot specify both ",(0,t.jsx)(n.code,{children:"allow_list"})," and ",(0,t.jsx)(n.code,{children:"deny_list"}),". The system will reject the configuration with a validation error."]}),"\n",(0,t.jsx)(n.h3,{id:"filtering-examples",children:"Filtering Examples"}),"\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Read-Only Agent"}),":"]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-yaml",children:'tools:\n  - tool_type: openapi\n    specification_url: "https://petstore3.swagger.io/api/v3/openapi.json"\n    allow_list:\n      - "getPetById"\n      - "findPetsByStatus"\n      - "findPetsByTags"\n      - "getInventory"\n      - "getOrderById"\n      - "getUserByName"\n'})}),"\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Full Access Except Deletes"}),":"]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-yaml",children:'tools:\n  - tool_type: openapi\n    specification_url: "https://petstore3.swagger.io/api/v3/openapi.json"\n    deny_list:\n      - "deletePet"\n      - "deleteOrder"\n      - "deleteUser"\n'})}),"\n",(0,t.jsx)(n.h2,{id:"authentication",children:"Authentication"}),"\n",(0,t.jsx)(n.p,{children:"OpenAPI tools support two authentication methods: API key, and service account authentication."}),"\n",(0,t.jsx)(n.h3,{id:"api-key-authentication",children:"API Key Authentication"}),"\n",(0,t.jsx)(n.p,{children:"API key authentication sends a key in either the request header or query parameter."}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-yaml",children:'auth:\n  type: apikey\n  in: header # or "query"\n  name: api_key\n  value: ${API_KEY}\n'})}),"\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Parameters"}),":"]}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.code,{children:"type"}),": Must be ",(0,t.jsx)(n.code,{children:'"apikey"'})]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.code,{children:"in"}),": Where to send the key - ",(0,t.jsx)(n.code,{children:'"header"'})," or ",(0,t.jsx)(n.code,{children:'"query"'})]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.code,{children:"name"}),": The name of the header or query parameter"]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.code,{children:"value"}),": The API key value (use environment variables for security)"]}),"\n"]}),"\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Example"})," (header-based):"]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-yaml",children:"auth:\n  type: apikey\n  in: header\n  name: X-API-Key\n  value: ${MY_API_KEY}\n"})}),"\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Example"})," (query-based):"]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-yaml",children:"auth:\n  type: apikey\n  in: query\n  name: apikey\n  value: ${MY_API_KEY}\n"})}),"\n",(0,t.jsx)(n.h3,{id:"service-account-authentication",children:"Service Account Authentication"}),"\n",(0,t.jsx)(n.p,{children:"Service account authentication uses Google Cloud service account credentials."}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-yaml",children:'auth:\n  type: serviceaccount\n  service_account_json: ${SERVICE_ACCOUNT_JSON}\n  scopes:\n    - "https://www.googleapis.com/auth/cloud-platform"\n'})}),"\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Parameters"}),":"]}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.code,{children:"type"}),": Must be ",(0,t.jsx)(n.code,{children:'"serviceaccount"'})]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.code,{children:"service_account_json"}),": JSON string containing the service account credentials"]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.code,{children:"scopes"}),": List of API scopes to request"]}),"\n"]}),"\n",(0,t.jsx)(n.h2,{id:"best-practices",children:"Best Practices"}),"\n",(0,t.jsx)(n.p,{children:"Following these best practices helps you deploy OpenAPI tools effectively."}),"\n",(0,t.jsx)(n.h3,{id:"use-environment-variables-for-secrets",children:"Use Environment Variables for Secrets"}),"\n",(0,t.jsx)(n.p,{children:"Never hardcode API keys or other credentials in configuration files:"}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-yaml",children:'# Good - use environment variables\nauth:\n  type: apikey\n  in: header\n  name: api_key\n  value: ${API_KEY}\n\n# Bad - hardcoded credentials\nauth:\n  type: apikey\n  in: header\n  name: api_key\n  value: "sk-1234567890abcdef"  # Don\'t do this!\n'})}),"\n",(0,t.jsx)(n.h3,{id:"fetch-specs-from-urls-when-possible",children:"Fetch Specs from URLs When Possible"}),"\n",(0,t.jsx)(n.p,{children:"Fetching specs from URLs ensures you always use the latest version:"}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-yaml",children:'# Good - fetches latest spec\nspecification_url: "https://api.example.com/openapi.json"\n\n# Less ideal - may become outdated\nspecification_file: "examples/api_spec.json"\n'})}),"\n",(0,t.jsx)(n.p,{children:"Use local files only when:"}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsx)(n.li,{children:"The API doesn't provide a public spec URL"}),"\n",(0,t.jsx)(n.li,{children:"You need to use a modified or customized spec"}),"\n",(0,t.jsx)(n.li,{children:"You want to lock to a specific API version"}),"\n"]}),"\n",(0,t.jsx)(n.h3,{id:"use-allow_list-for-security-sensitive-apis",children:"Use allow_list for Security-Sensitive APIs"}),"\n",(0,t.jsxs)(n.p,{children:["For APIs with dangerous operations (delete, administrative functions), use ",(0,t.jsx)(n.code,{children:"allow_list"})," to explicitly control access:"]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-yaml",children:'allow_list:\n  - "getResource"\n  - "listResources"\n  - "updateResource"\n# Deliberately exclude "deleteResource"\n'})}),"\n",(0,t.jsxs)(n.p,{children:["Use ",(0,t.jsx)(n.code,{children:"deny_list"})," only when you're confident about the safety of unlisted operations."]}),"\n",(0,t.jsx)(n.h3,{id:"provide-clear-agent-instructions",children:"Provide Clear Agent Instructions"}),"\n",(0,t.jsx)(n.p,{children:"Include guidance in your agent's instructions about the API and required parameters:"}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-yaml",children:'instruction: |\n  You are a Pet Store API agent.\n\n  When creating pets:\n  - name (required): The pet\'s name\n  - photoUrls (required): Array of photo URLs\n  - id (required): Unique integer ID\n  - category: Optional object with id and name\n  - status: "available", "pending", or "sold"\n\n  Always validate required fields before making requests.\n'})}),"\n",(0,t.jsx)(n.h3,{id:"test-with-local-apis-first",children:"Test with Local APIs First"}),"\n",(0,t.jsx)(n.p,{children:"Test your configuration against local or development API instances before connecting to production:"}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-yaml",children:'# Development\nbase_url: "http://localhost:8080"\n\n# Production (after testing)\nbase_url: "https://api.production.com"\n'})}),"\n",(0,t.jsx)(n.h2,{id:"troubleshooting",children:"Troubleshooting"}),"\n",(0,t.jsx)(n.p,{children:"This section addresses common issues when configuring OpenAPI tools."}),"\n",(0,t.jsx)(n.h3,{id:"specification-loading-fails",children:"Specification Loading Fails"}),"\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Symptoms"}),": Agent fails to start with errors about loading or parsing the OpenAPI specification."]}),"\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Possible Causes and Solutions"}),":"]}),"\n",(0,t.jsxs)(n.ol,{children:["\n",(0,t.jsxs)(n.li,{children:["\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Invalid Specification Format"}),":"]}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsx)(n.li,{children:"Verify the spec is valid JSON or YAML"}),"\n",(0,t.jsx)(n.li,{children:"Validate using online tools (Swagger Editor, OpenAPI Validator)"}),"\n",(0,t.jsx)(n.li,{children:"Check for syntax errors (missing commas, quotes, etc.)"}),"\n"]}),"\n"]}),"\n",(0,t.jsxs)(n.li,{children:["\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"URL Not Accessible"}),":"]}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsxs)(n.li,{children:["Verify the ",(0,t.jsx)(n.code,{children:"specification_url"})," is accessible from your deployment"]}),"\n",(0,t.jsx)(n.li,{children:"Check network connectivity and firewall rules"}),"\n",(0,t.jsx)(n.li,{children:"Ensure HTTPS certificates are valid"}),"\n"]}),"\n"]}),"\n",(0,t.jsxs)(n.li,{children:["\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"File Not Found"}),":"]}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsxs)(n.li,{children:["Verify the ",(0,t.jsx)(n.code,{children:"specification_file"})," path is correct relative to the working directory"]}),"\n",(0,t.jsx)(n.li,{children:"Check file permissions"}),"\n",(0,t.jsx)(n.li,{children:"Use absolute paths if relative paths fail"}),"\n"]}),"\n"]}),"\n"]}),"\n",(0,t.jsx)(n.h3,{id:"tools-not-available-to-agent",children:"Tools Not Available to Agent"}),"\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Symptoms"}),": The AI model reports that tools are not available or cannot be found."]}),"\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Possible Causes and Solutions"}),":"]}),"\n",(0,t.jsxs)(n.ol,{children:["\n",(0,t.jsxs)(n.li,{children:["\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Filtering Excluded All Tools"}),":"]}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsxs)(n.li,{children:["Review your ",(0,t.jsx)(n.code,{children:"allow_list"})," or ",(0,t.jsx)(n.code,{children:"deny_list"})," configuration"]}),"\n",(0,t.jsx)(n.li,{children:"Verify operation IDs match those in the spec (case-sensitive)"}),"\n",(0,t.jsx)(n.li,{children:"Check agent logs for tool loading messages"}),"\n"]}),"\n"]}),"\n",(0,t.jsxs)(n.li,{children:["\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Empty Specification"}),":"]}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsxs)(n.li,{children:["Verify the OpenAPI spec contains ",(0,t.jsx)(n.code,{children:"paths"})," with operations"]}),"\n",(0,t.jsxs)(n.li,{children:["Check that operations have ",(0,t.jsx)(n.code,{children:"operationId"})," fields"]}),"\n"]}),"\n"]}),"\n"]}),"\n",(0,t.jsx)(n.h3,{id:"authentication-errors",children:"Authentication Errors"}),"\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Symptoms"}),": API calls fail with 401 or 403 errors."]}),"\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Possible Causes and Solutions"}),":"]}),"\n",(0,t.jsxs)(n.ol,{children:["\n",(0,t.jsxs)(n.li,{children:["\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Invalid or Missing Credentials"}),":"]}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsx)(n.li,{children:"Verify environment variables are set correctly"}),"\n",(0,t.jsx)(n.li,{children:"Check that credentials haven't expired"}),"\n",(0,t.jsx)(n.li,{children:"Test credentials directly with the API using curl or Postman"}),"\n"]}),"\n"]}),"\n",(0,t.jsxs)(n.li,{children:["\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Wrong Authentication Location"}),":"]}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsxs)(n.li,{children:["Verify ",(0,t.jsx)(n.code,{children:"in: header"})," vs ",(0,t.jsx)(n.code,{children:"in: query"})," matches API requirements"]}),"\n",(0,t.jsxs)(n.li,{children:["Check the ",(0,t.jsx)(n.code,{children:"name"})," parameter matches what the API expects"]}),"\n",(0,t.jsx)(n.li,{children:"Review API documentation for exact auth requirements"}),"\n"]}),"\n"]}),"\n"]}),"\n",(0,t.jsx)(n.h3,{id:"api-calls-fail-or-return-errors",children:"API Calls Fail or Return Errors"}),"\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Symptoms"}),": Tools execute but API returns errors or unexpected responses."]}),"\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Possible Causes and Solutions"}),":"]}),"\n",(0,t.jsxs)(n.ol,{children:["\n",(0,t.jsxs)(n.li,{children:["\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Wrong Server URL"}),":"]}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsxs)(n.li,{children:["Verify ",(0,t.jsx)(n.code,{children:"base_url"})," points to the correct environment"]}),"\n",(0,t.jsx)(n.li,{children:"Check that paths are correctly combined with base URL"}),"\n",(0,t.jsx)(n.li,{children:"Review server URL in agent logs"}),"\n"]}),"\n"]}),"\n",(0,t.jsxs)(n.li,{children:["\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Missing Required Parameters"}),":"]}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsx)(n.li,{children:"Review API error messages for missing parameters"}),"\n",(0,t.jsx)(n.li,{children:"Update agent instructions to include required parameter guidance"}),"\n",(0,t.jsx)(n.li,{children:"Check OpenAPI spec for parameter requirements"}),"\n"]}),"\n"]}),"\n",(0,t.jsxs)(n.li,{children:["\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Type Mismatches"}),":"]}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsx)(n.li,{children:"Verify parameter types match spec (string vs integer, etc.)"}),"\n",(0,t.jsx)(n.li,{children:"Check that enum values are valid"}),"\n",(0,t.jsx)(n.li,{children:"Review validation errors in API responses"}),"\n"]}),"\n"]}),"\n"]}),"\n",(0,t.jsx)(n.h2,{id:"conclusion",children:"Conclusion"}),"\n",(0,t.jsx)(n.p,{children:"OpenAPI tools provide a powerful way to integrate REST APIs into your agents without manual tool implementation. By following the configuration steps, authentication methods, and best practices in this guide, you can quickly enable agents to interact with any OpenAPI-compliant service."}),"\n",(0,t.jsx)(n.p,{children:"Key takeaways:"}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsxs)(n.li,{children:["Use ",(0,t.jsx)(n.code,{children:"specification_url"})," to fetch specs from URLs when possible"]}),"\n",(0,t.jsxs)(n.li,{children:["Override server URLs with ",(0,t.jsx)(n.code,{children:"base_url"})," for environment-specific deployments"]}),"\n",(0,t.jsxs)(n.li,{children:["Filter tools using ",(0,t.jsx)(n.code,{children:"allow_list"})," (security-sensitive) or ",(0,t.jsx)(n.code,{children:"deny_list"})," (convenience)"]}),"\n",(0,t.jsx)(n.li,{children:"Always use environment variables for credentials"}),"\n",(0,t.jsx)(n.li,{children:"Use camelCase operation IDs in filter configurations"}),"\n",(0,t.jsx)(n.li,{children:"Test with local/development APIs before production deployment"}),"\n",(0,t.jsx)(n.li,{children:"Monitor tool usage and API errors through logging"}),"\n"]})]})}function h(e={}){const{wrapper:n}={...(0,r.R)(),...e.components};return n?(0,t.jsx)(n,{...e,children:(0,t.jsx)(d,{...e})}):d(e)}},8453:(e,n,i)=>{i.d(n,{R:()=>l,x:()=>o});var s=i(6540);const t={},r=s.createContext(t);function l(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(t):e.components||t:l(e.components),s.createElement(r.Provider,{value:n},e.children)}}}]);

solace_agent_mesh/assets/docs/assets/js/cbe2e9ea.07e170dd.js

@@ -0,0 +1 @@
+"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[9489],{8730:(e,n,t)=>{t.r(n),t.d(n,{assets:()=>c,contentTitle:()=>r,default:()=>u,frontMatter:()=>i,metadata:()=>s,toc:()=>d});const s=JSON.parse('{"id":"documentation/enterprise/connectors/connectors","title":"Connectors","description":"Connectors link agents to external data sources and services. Each connector type provides access to different systems using configured credentials and connection details. Agents use connectors to retrieve information, execute queries, and interact with external platforms through natural language conversations.","source":"@site/docs/documentation/enterprise/connectors/connectors.md","sourceDirName":"documentation/enterprise/connectors","slug":"/documentation/enterprise/connectors/","permalink":"/solace-agent-mesh/docs/documentation/enterprise/connectors/","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/enterprise/connectors/connectors.md","tags":[],"version":"current","sidebarPosition":10,"frontMatter":{"title":"Connectors","sidebar_position":10},"sidebar":"docSidebar","previous":{"title":"Agent Builder","permalink":"/solace-agent-mesh/docs/documentation/enterprise/agent-builder"},"next":{"title":"Setting Up RBAC","permalink":"/solace-agent-mesh/docs/documentation/enterprise/rbac-setup-guide"}}');var a=t(4848),o=t(8453);const i={title:"Connectors",sidebar_position:10},r="Connectors",c={},d=[{value:"SQL Connectors",id:"sql-connectors",level:2},{value:"Supported Databases",id:"supported-databases",level:3},{value:"Creating SQL Connectors",id:"creating-sql-connectors",level:3},{value:"Security Considerations",id:"security-considerations",level:3},{value:"Shared Credential Architecture",id:"shared-credential-architecture",level:4},{value:"Implementing Database-Level Security",id:"implementing-database-level-security",level:4},{value:"Natural Language Query Risks",id:"natural-language-query-risks",level:4},{value:"Best Practices",id:"best-practices",level:4},{value:"Assigning Connectors to Agents",id:"assigning-connectors-to-agents",level:3},{value:"Managing Connectors",id:"managing-connectors",level:3},{value:"Editing Connectors",id:"editing-connectors",level:4},{value:"Testing Connections",id:"testing-connections",level:4},{value:"Deleting Connectors",id:"deleting-connectors",level:4},{value:"Troubleshooting",id:"troubleshooting",level:3},{value:"Access Control",id:"access-control",level:2}];function l(e){const n={a:"a",code:"code",h1:"h1",h2:"h2",h3:"h3",h4:"h4",header:"header",li:"li",p:"p",table:"table",tbody:"tbody",td:"td",th:"th",thead:"thead",tr:"tr",ul:"ul",...(0,o.R)(),...e.components};return(0,a.jsxs)(a.Fragment,{children:[(0,a.jsx)(n.header,{children:(0,a.jsx)(n.h1,{id:"connectors",children:"Connectors"})}),"\n",(0,a.jsx)(n.p,{children:"Connectors link agents to external data sources and services. Each connector type provides access to different systems using configured credentials and connection details. Agents use connectors to retrieve information, execute queries, and interact with external platforms through natural language conversations."}),"\n",(0,a.jsx)(n.h2,{id:"sql-connectors",children:"SQL Connectors"}),"\n",(0,a.jsx)(n.p,{children:"SQL connectors enable agents to query and analyze database information using natural language. These connectors convert user questions into SQL queries, execute them against configured databases, and return results in a conversational format. This capability makes database information accessible through agent interactions without requiring users to write SQL code."}),"\n",(0,a.jsx)(n.h3,{id:"supported-databases",children:"Supported Databases"}),"\n",(0,a.jsx)(n.p,{children:"SQL connectors support three database types:"}),"\n",(0,a.jsxs)(n.ul,{children:["\n",(0,a.jsx)(n.li,{children:"MySQL"}),"\n",(0,a.jsx)(n.li,{children:"PostgreSQL"}),"\n",(0,a.jsx)(n.li,{children:"MariaDB"}),"\n"]}),"\n",(0,a.jsx)(n.p,{children:"Each database type follows the same configuration process but may have specific connection string requirements or authentication methods."}),"\n",(0,a.jsx)(n.h3,{id:"creating-sql-connectors",children:"Creating SQL Connectors"}),"\n",(0,a.jsx)(n.p,{children:"You create SQL connectors in the Connectors section of the Enterprise web interface. This process must be completed before you can assign connectors to agents."}),"\n",(0,a.jsx)(n.p,{children:"Each SQL connector configuration includes the database type selection, connection details (host address, port number, and database name), and authentication credentials (username and password). The connection configuration establishes a persistent connection pool that agents use to execute queries. You should verify that the database server allows connections from the Agent Mesh deployment and that any required firewall rules permit access."}),"\n",(0,a.jsx)(n.p,{children:"Once you create a connector, it becomes available for assignment to any agent in your deployment. This reusability means you can connect multiple agents to the same database without duplicating connection configuration. All agents assigned to a connector share the same database connection pool and credentials."}),"\n",(0,a.jsx)(n.h3,{id:"security-considerations",children:"Security Considerations"}),"\n",(0,a.jsx)(n.p,{children:"The framework implements a shared credential model that has significant implications for access control when planning your deployment architecture."}),"\n",(0,a.jsx)(n.h4,{id:"shared-credential-architecture",children:"Shared Credential Architecture"}),"\n",(0,a.jsx)(n.p,{children:"The framework does not sandbox database access at the agent level. All agents assigned to a connector share the same database credentials and permissions. This design means that any agent with the connector can access all data the connector's credentials permit. Security boundaries exist at the database level, not between agents."}),"\n",(0,a.jsx)(n.h4,{id:"implementing-database-level-security",children:"Implementing Database-Level Security"}),"\n",(0,a.jsx)(n.p,{children:"Database-level access control is your primary security mechanism. You should create database users with minimal necessary privileges, use database views or restricted schemas to limit what agents can access, and audit database queries to monitor what agents are accessing."}),"\n",(0,a.jsx)(n.p,{children:"For example, if you have agents that should only read customer data and other agents that need full database access, you must create separate connectors with different database users. Each database user has appropriate permissions configured at the database level. You cannot restrict access by assigning the same connector to different agents because all agents sharing a connector have identical database permissions."}),"\n",(0,a.jsx)(n.h4,{id:"natural-language-query-risks",children:"Natural Language Query Risks"}),"\n",(0,a.jsx)(n.p,{children:"The natural language to SQL conversion capability makes databases accessible through conversation, but this also means users can potentially request any data the connector can access. You should plan your database permissions accordingly and consider what information should be available through agent interactions."}),"\n",(0,a.jsx)(n.p,{children:"Users might phrase questions in ways that expose data you intended to restrict, or they might discover table and column names through exploratory questions. Database views that present only approved data columns, user accounts with read-only permissions on specific tables, and query result size limits all help mitigate these risks."}),"\n",(0,a.jsx)(n.h4,{id:"best-practices",children:"Best Practices"}),"\n",(0,a.jsx)(n.p,{children:"Create separate connectors for different security boundaries. If agents require different levels of database access, configure multiple connectors with appropriately scoped database users rather than sharing a single connector across all agents."}),"\n",(0,a.jsx)(n.p,{children:"Use read-only database accounts whenever possible. Many agent use cases only require reading data, and read-only permissions prevent accidental or malicious data modification."}),"\n",(0,a.jsx)(n.p,{children:"Implement database views to present filtered data. Views can hide sensitive columns, join tables to present aggregated information, or implement row-level security logic at the database level."}),"\n",(0,a.jsx)(n.p,{children:"Enable query logging and monitoring to track what agents access. Database audit logs help you detect suspicious query patterns or unauthorized data access attempts."}),"\n",(0,a.jsx)(n.h3,{id:"assigning-connectors-to-agents",children:"Assigning Connectors to Agents"}),"\n",(0,a.jsx)(n.p,{children:"You assign connectors to agents through Agent Builder. When creating or editing an agent, you select connectors from a list during agent configuration. You can assign connectors before or after deployment, and changes to connector assignments take effect when you deploy or update the agent."}),"\n",(0,a.jsx)(n.h3,{id:"managing-connectors",children:"Managing Connectors"}),"\n",(0,a.jsx)(n.p,{children:"Connector management operations require specific RBAC capabilities and follow particular patterns to prevent service disruptions."}),"\n",(0,a.jsx)(n.h4,{id:"editing-connectors",children:"Editing Connectors"}),"\n",(0,a.jsx)(n.p,{children:"You can modify connector configurations at any time. Changes to connection details or credentials take effect immediately for new database connections. Existing connections in the pool may continue using previous credentials until they expire and reconnect."}),"\n",(0,a.jsx)(n.p,{children:"If agents are actively using a connector when you modify it, query failures may occur during the transition period. You should plan connector updates during maintenance windows or coordinate with agent users to minimize disruptions."}),"\n",(0,a.jsx)(n.h4,{id:"testing-connections",children:"Testing Connections"}),"\n",(0,a.jsx)(n.p,{children:"The Connectors interface provides connection testing functionality that validates credentials and connectivity before you save the connector configuration. This testing helps identify configuration errors before agents attempt to use the connector."}),"\n",(0,a.jsx)(n.h4,{id:"deleting-connectors",children:"Deleting Connectors"}),"\n",(0,a.jsx)(n.p,{children:"You can delete connectors, but the system enforces restrictions to prevent breaking deployed agents. If any agents are assigned to a connector, you must first remove the connector from those agents or undeploy them before deletion succeeds."}),"\n",(0,a.jsx)(n.p,{children:"The deletion process removes the connector configuration but does not affect the database itself. Database users and permissions remain in place, requiring separate cleanup if you no longer need them."}),"\n",(0,a.jsx)(n.h3,{id:"troubleshooting",children:"Troubleshooting"}),"\n",(0,a.jsx)(n.p,{children:"When connecting SAM to a PostgreSQL databases hosted on Supabase, you may encounter network errors like:"}),"\n",(0,a.jsx)(n.p,{children:(0,a.jsx)(n.code,{children:'{ "detail": "Invalid token", "error_type": "invalid_token" }'})}),"\n",(0,a.jsx)(n.p,{children:"This is because Supabase's direct connection endpoint uses IPv6, however most Kubernetes clusters are IPv4 by default.\nThe solution is to use the Session Pooler endpoint as it is IPv4 compatible."}),"\n",(0,a.jsx)(n.h2,{id:"access-control",children:"Access Control"}),"\n",(0,a.jsx)(n.p,{children:"Connector operations require specific RBAC capabilities. The table below shows the capabilities and what they control:"}),"\n",(0,a.jsxs)(n.table,{children:[(0,a.jsx)(n.thead,{children:(0,a.jsxs)(n.tr,{children:[(0,a.jsx)(n.th,{children:"Capability"}),(0,a.jsx)(n.th,{children:"Purpose"})]})}),(0,a.jsxs)(n.tbody,{children:[(0,a.jsxs)(n.tr,{children:[(0,a.jsx)(n.td,{children:(0,a.jsx)(n.code,{children:"sam:connectors:create"})}),(0,a.jsx)(n.td,{children:"Create new connectors in the Connectors section"})]}),(0,a.jsxs)(n.tr,{children:[(0,a.jsx)(n.td,{children:(0,a.jsx)(n.code,{children:"sam:connectors:read"})}),(0,a.jsx)(n.td,{children:"View connector configurations and list available connectors"})]}),(0,a.jsxs)(n.tr,{children:[(0,a.jsx)(n.td,{children:(0,a.jsx)(n.code,{children:"sam:connectors:update"})}),(0,a.jsx)(n.td,{children:"Modify connector configurations and credentials"})]}),(0,a.jsxs)(n.tr,{children:[(0,a.jsx)(n.td,{children:(0,a.jsx)(n.code,{children:"sam:connectors:delete"})}),(0,a.jsx)(n.td,{children:"Remove connectors from the system"})]})]})]}),"\n",(0,a.jsxs)(n.p,{children:["For detailed information about configuring role-based access control, see ",(0,a.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/enterprise/rbac-setup-guide",children:"Setting Up RBAC"}),"."]})]})}function u(e={}){const{wrapper:n}={...(0,o.R)(),...e.components};return n?(0,a.jsx)(n,{...e,children:(0,a.jsx)(l,{...e})}):l(e)}},8453:(e,n,t)=>{t.d(n,{R:()=>i,x:()=>r});var s=t(6540);const a={},o=s.createContext(a);function i(e){const n=s.useContext(o);return s.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(a):e.components||a:i(e.components),s.createElement(o.Provider,{value:n},e.children)}}}]);

solace_agent_mesh/assets/docs/assets/js/e04b235d.06d23db6.js

@@ -0,0 +1 @@
+"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[6840],{405:(e,n,t)=>{t.r(n),t.d(n,{assets:()=>l,contentTitle:()=>r,default:()=>h,frontMatter:()=>o,metadata:()=>i,toc:()=>d});const i=JSON.parse('{"id":"documentation/enterprise/agent-builder","title":"Agent Builder","description":"Agent Builder provides a visual, form-based interface for creating and managing agents without writing configuration files. This tool offers optional AI assistance that suggests initial configuration values based on a description of the agent you want to build.","source":"@site/docs/documentation/enterprise/agent-builder.md","sourceDirName":"documentation/enterprise","slug":"/documentation/enterprise/agent-builder","permalink":"/solace-agent-mesh/docs/documentation/enterprise/agent-builder","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/enterprise/agent-builder.md","tags":[],"version":"current","sidebarPosition":8,"frontMatter":{"title":"Agent Builder","sidebar_position":8},"sidebar":"docSidebar","previous":{"title":"Running from Wheel File","permalink":"/solace-agent-mesh/docs/documentation/enterprise/wheel-installation"},"next":{"title":"Connectors","permalink":"/solace-agent-mesh/docs/documentation/enterprise/connectors/"}}');var s=t(4848),a=t(8453);const o={title:"Agent Builder",sidebar_position:8},r="Agent Builder",l={},d=[{value:"Creating Your First Agent",id:"creating-your-first-agent",level:2},{value:"AI-Assisted Creation",id:"ai-assisted-creation",level:3},{value:"Manual Creation",id:"manual-creation",level:3},{value:"Configuring the Agent",id:"configuring-the-agent",level:2},{value:"Agent Details",id:"agent-details",level:3},{value:"Instructions",id:"instructions",level:3},{value:"Toolsets",id:"toolsets",level:3},{value:"Connectors",id:"connectors",level:3},{value:"Deploying and Managing Agents",id:"deploying-and-managing-agents",level:2},{value:"How Deployment Works",id:"how-deployment-works",level:3},{value:"Agent States",id:"agent-states",level:3},{value:"Managing Deployed Agents",id:"managing-deployed-agents",level:3},{value:"Downloading Agent Configurations",id:"downloading-agent-configurations",level:2},{value:"What Downloaded YAML Files Are Designed For",id:"what-downloaded-yaml-files-are-designed-for",level:3},{value:"When to Download",id:"when-to-download",level:3},{value:"Access Control",id:"access-control",level:2}];function c(e){const n={a:"a",admonition:"admonition",code:"code",h1:"h1",h2:"h2",h3:"h3",header:"header",li:"li",p:"p",strong:"strong",table:"table",tbody:"tbody",td:"td",th:"th",thead:"thead",tr:"tr",ul:"ul",...(0,a.R)(),...e.components};return(0,s.jsxs)(s.Fragment,{children:[(0,s.jsx)(n.header,{children:(0,s.jsx)(n.h1,{id:"agent-builder",children:"Agent Builder"})}),"\n",(0,s.jsx)(n.p,{children:"Agent Builder provides a visual, form-based interface for creating and managing agents without writing configuration files. This tool offers optional AI assistance that suggests initial configuration values based on a description of the agent you want to build."}),"\n",(0,s.jsx)(n.p,{children:'When you click the "Create Agent" button from the Agents page, a dialog appears offering AI assistance. You can describe what you want the agent to do in natural language, and the AI generates initial configuration values for you to review and modify. Alternatively, you can skip AI assistance and manually enter all configuration details yourself.'}),"\n",(0,s.jsx)(n.p,{children:"After you configure the agent in the form and save it, the agent appears in the Inactive tab with Not Deployed status. At this point, you can further edit the configuration, download it as a YAML file, or deploy it to make it available for use in Chat."}),"\n",(0,s.jsx)(n.h2,{id:"creating-your-first-agent",children:"Creating Your First Agent"}),"\n",(0,s.jsx)(n.p,{children:"Agent Builder offers two paths for beginning your agent configuration."}),"\n",(0,s.jsx)(n.h3,{id:"ai-assisted-creation",children:"AI-Assisted Creation"}),"\n",(0,s.jsx)(n.p,{children:'You can provide a natural language description of what you want the agent to do. Explain the agent\'s purpose, the types of tasks it handles, and any specific capabilities it needs. For example, "An agent that helps users search company documentation and answer questions about internal policies" or "An agent that analyzes sales data and generates reports."'}),"\n",(0,s.jsx)(n.p,{children:"When you submit your description, the AI analyzes it and generates suggested values for several configuration fields. The AI creates a unique agent name, writes a description explaining the agent's purpose, drafts system instructions defining agent behavior, suggests appropriate toolsets, recommends connectors if applicable, and provides default settings for skills and communication modes."}),"\n",(0,s.jsx)(n.p,{children:"These AI-generated values serve as suggestions only. You proceed to the configuration form where you can review, modify, or completely rewrite any of these values before saving the agent."}),"\n",(0,s.jsx)(n.h3,{id:"manual-creation",children:"Manual Creation"}),"\n",(0,s.jsx)(n.p,{children:"You can skip AI assistance entirely by clicking the secondary button. The system prompts you to manually enter the agent's name and description in a simple dialog. After you provide these details and click continue, you proceed to the agent configuration form where the Agent Details section is pre-filled with your entered name and description. Other sections (instructions, toolsets, and connectors) remain empty for you to configure manually."}),"\n",(0,s.jsx)(n.h2,{id:"configuring-the-agent",children:"Configuring the Agent"}),"\n",(0,s.jsx)(n.p,{children:"The agent configuration form is where you configure all agent settings. You have complete control to manually configure or refine every setting, whether you work with AI-generated suggestions or enter values from scratch."}),"\n",(0,s.jsx)(n.h3,{id:"agent-details",children:"Agent Details"}),"\n",(0,s.jsx)(n.p,{children:"The name field provides a unique identifier that describes the agent's purpose. Names must be unique across your deployment."}),"\n",(0,s.jsx)(n.p,{children:"The description field explains what the agent does and when users should interact with it. This description helps users understand the agent's purpose and capabilities."}),"\n",(0,s.jsx)(n.h3,{id:"instructions",children:"Instructions"}),"\n",(0,s.jsx)(n.p,{children:"Instructions define how the agent behaves during interactions and form the basis of the agent system prompt. Your instructions should explain the agent's role, communication style, and any specific rules or constraints it should follow."}),"\n",(0,s.jsx)(n.p,{children:"For example, you can instruct an agent to always provide sources for information, maintain a formal or casual tone, follow specific steps when handling requests, or apply particular business rules or constraints."}),"\n",(0,s.jsx)(n.h3,{id:"toolsets",children:"Toolsets"}),"\n",(0,s.jsx)(n.p,{children:"Toolsets provide the agent with capabilities it can use to accomplish tasks. Available toolsets include Artifact Management (list, read, create, update and delete artifacts), Data Analysis (query, transform and visualize data from artifacts), and Web (perform internet searches)."}),"\n",(0,s.jsx)(n.p,{children:"You can assign multiple toolsets to a single agent, giving it access to diverse capabilities. If you select Data Analysis, you should also include Artifact Management because data analysis operations typically require artifact access."}),"\n",(0,s.jsx)(n.h3,{id:"connectors",children:"Connectors"}),"\n",(0,s.jsx)(n.p,{children:"Connectors link agents to external data sources such as databases and APIs. You assign connectors that were previously created in the Connectors section. All agents sharing a connector use the same credentials."}),"\n",(0,s.jsxs)(n.p,{children:["For detailed information about creating and configuring connectors, see ",(0,s.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/enterprise/connectors/",children:"Connectors"}),"."]}),"\n",(0,s.jsx)(n.h2,{id:"deploying-and-managing-agents",children:"Deploying and Managing Agents"}),"\n",(0,s.jsx)(n.h3,{id:"how-deployment-works",children:"How Deployment Works"}),"\n",(0,s.jsx)(n.p,{children:"When you deploy an agent through Agent Builder, the deployment process involves several components working together to create running agent instances."}),"\n",(0,s.jsx)(n.p,{children:"The Platform Service receives your deployment request and validates the agent configuration. It creates a deployment record in the database and publishes a deployment message to the Solace broker. The Deployer component (a separate containerized service) receives this message and creates a running agent instance using the configuration you provided. The Deployer sends status updates back to the Platform Service through heartbeat messages, and the Platform Service updates the deployment status you see in the UI."}),"\n",(0,s.jsx)(n.p,{children:"This architecture enables multiple Deployer instances to run independently for scalability and allows deployment operations to complete asynchronously without blocking the UI. You see status transitions (Deploying, Deployed, or Deployment Failed) as the Deployer works in the background."}),"\n",(0,s.jsxs)(n.p,{children:["Agent deployments are currently only supported through Helm. The Deployer runs as a containerized service using the ",(0,s.jsx)(n.code,{children:"sam-agent-deployer"})," image. For detailed deployment configuration and setup instructions, see the ",(0,s.jsx)(n.a,{href:"https://solaceproducts.github.io/solace-agent-mesh-helm-quickstart/docs-site/",children:"Solace Agent Mesh Helm Quickstart"}),"."]}),"\n",(0,s.jsx)(n.h3,{id:"agent-states",children:"Agent States"}),"\n",(0,s.jsx)(n.p,{children:"Agents move through distinct states as you create, edit, and deploy them."}),"\n",(0,s.jsx)(n.p,{children:"Not Deployed is the initial status for newly created agents. These agents appear in the Inactive tab where you can edit their configurations, download them as YAML files, or prepare them for deployment. Agents remain in this status until you explicitly deploy them."}),"\n",(0,s.jsx)(n.p,{children:"Deploying and Undeploying are the in-progress statuses that appear when an agent is being deployed or undeployed. You should not interact with an agent when it is in this transitory state."}),"\n",(0,s.jsx)(n.p,{children:"Deployed agents move to the Active tab and become available for user interactions. You cannot delete deployed agents\u2014you must undeploy them first to remove them from the system."}),"\n",(0,s.jsx)(n.p,{children:"Deployment Failed displays if your agent failed to deploy for any reason. You should verify all agent configuration and try again, or contact an administrator if the problem persists."}),"\n",(0,s.jsx)(n.h3,{id:"managing-deployed-agents",children:"Managing Deployed Agents"}),"\n",(0,s.jsx)(n.p,{children:'When you deploy an agent, the system records its configuration. If you later edit the agent\'s configuration in the UI, the system detects this mismatch and displays "Undeployed changes" on both the Active and Inactive agent tiles. The "Preview Updates" action in the agent side panel compares the running agent with its undeployed configuration. Changes to deployed agents require the "Deploy Updates" action to take effect in the running agent.'}),"\n",(0,s.jsx)(n.p,{children:"Downloading agents as YAML files provides portability and version control. These files support backing up agent configurations, sharing configurations between deployments, tracking configuration changes in version control systems, and deploying agents using infrastructure-as-code tools."}),"\n",(0,s.jsx)(n.h2,{id:"downloading-agent-configurations",children:"Downloading Agent Configurations"}),"\n",(0,s.jsxs)(n.p,{children:["The Download button allows you to export agent configurations as YAML files. These files are designed for the ",(0,s.jsx)(n.strong,{children:"Agent Deployer"})," running in Kubernetes/Helm environments."]}),"\n",(0,s.jsx)(n.h3,{id:"what-downloaded-yaml-files-are-designed-for",children:"What Downloaded YAML Files Are Designed For"}),"\n",(0,s.jsx)(n.p,{children:"Agent Builder generates YAML files optimized for automated deployment through the Agent Deployer. These files:"}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsx)(n.li,{children:"Use S3-compatible artifact storage (expects SeaweedFS or similar in K8s)"}),"\n",(0,s.jsx)(n.li,{children:"Contain environment variable placeholders for credentials and settings"}),"\n",(0,s.jsxs)(n.li,{children:["Do not reference ",(0,s.jsx)(n.code,{children:"shared_config.yaml"})," (unlike agents created with ",(0,s.jsx)(n.code,{children:"sam add agent"}),")"]}),"\n",(0,s.jsx)(n.li,{children:"Are ready to deploy through the Agent Deployer without modification"}),"\n"]}),"\n",(0,s.jsxs)(n.admonition,{title:"Agent Deployer vs Manual Deployment",type:"info",children:[(0,s.jsxs)(n.p,{children:[(0,s.jsx)(n.strong,{children:"Agent Deployer (Recommended):"}),' Click "Deploy" in Agent Builder to deploy agents directly to your Kubernetes cluster. The agent deployer handles all configuration automatically.']}),(0,s.jsxs)(n.p,{children:[(0,s.jsx)(n.strong,{children:"Download for Manual Use:"})," Download the YAML file if you need to run agents outside Kubernetes or want to review/customize the configuration."]})]}),"\n",(0,s.jsx)(n.h3,{id:"when-to-download",children:"When to Download"}),"\n",(0,s.jsx)(n.p,{children:(0,s.jsx)(n.strong,{children:"Use the Download button when you need to:"})}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsx)(n.li,{children:"Back up agent configurations for version control"}),"\n",(0,s.jsx)(n.li,{children:"Review generated configuration before deployment"}),"\n",(0,s.jsx)(n.li,{children:"Share agent configurations between teams or environments"}),"\n",(0,s.jsx)(n.li,{children:"Run agents in workshops or demos without K8s infrastructure"}),"\n"]}),"\n",(0,s.jsx)(n.p,{children:(0,s.jsx)(n.strong,{children:"Use the Deploy button when:"})}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsx)(n.li,{children:"You have Kubernetes/Helm infrastructure set up"}),"\n",(0,s.jsx)(n.li,{children:"You want automated deployment without manual configuration"}),"\n",(0,s.jsx)(n.li,{children:"You want the agent deployer to manage the agent lifecycle"}),"\n"]}),"\n",(0,s.jsx)(n.admonition,{title:"Configuration Required",type:"warning",children:(0,s.jsxs)(n.p,{children:["Downloaded YAML files are designed for the agent deployer and require manual configuration changes to run locally. For local development, consider using ",(0,s.jsx)(n.code,{children:"sam add agent"})," instead, which generates files with ",(0,s.jsx)(n.code,{children:"shared_config"})," references."]})}),"\n",(0,s.jsx)(n.h2,{id:"access-control",children:"Access Control"}),"\n",(0,s.jsx)(n.p,{children:"Agent Builder operations require specific RBAC capabilities. The table below shows the capabilities and what they control:"}),"\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:"Capability"}),(0,s.jsx)(n.th,{children:"Purpose"})]})}),(0,s.jsxs)(n.tbody,{children:[(0,s.jsxs)(n.tr,{children:[(0,s.jsx)(n.td,{children:(0,s.jsx)(n.code,{children:"sam:agent_builder:create"})}),(0,s.jsx)(n.td,{children:"Create new agents through Agent Builder interface"})]}),(0,s.jsxs)(n.tr,{children:[(0,s.jsx)(n.td,{children:(0,s.jsx)(n.code,{children:"sam:agent_builder:update"})}),(0,s.jsx)(n.td,{children:"Edit existing agent configurations"})]}),(0,s.jsxs)(n.tr,{children:[(0,s.jsx)(n.td,{children:(0,s.jsx)(n.code,{children:"sam:agent_builder:delete"})}),(0,s.jsx)(n.td,{children:"Delete agents (must undeploy first)"})]}),(0,s.jsxs)(n.tr,{children:[(0,s.jsx)(n.td,{children:(0,s.jsx)(n.code,{children:"sam:deployments:create"})}),(0,s.jsx)(n.td,{children:"Deploy agents to make them available in Chat"})]}),(0,s.jsxs)(n.tr,{children:[(0,s.jsx)(n.td,{children:(0,s.jsx)(n.code,{children:"sam:deployments:read"})}),(0,s.jsx)(n.td,{children:"View deployment status and history"})]})]})]}),"\n",(0,s.jsxs)(n.p,{children:["For information about connector-related capabilities, see ",(0,s.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/enterprise/connectors/#access-control",children:"Connectors"}),". For detailed information about configuring role-based access control and assigning capabilities to users, see ",(0,s.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/enterprise/rbac-setup-guide",children:"Setting Up RBAC"}),". For Kubernetes-specific RBAC configuration, see the ",(0,s.jsx)(n.a,{href:"https://solaceproducts.github.io/solace-agent-mesh-helm-quickstart/docs-site/#role-based-access-control-rbac",children:"Helm Chart RBAC documentation"}),"."]})]})}function h(e={}){const{wrapper:n}={...(0,a.R)(),...e.components};return n?(0,s.jsx)(n,{...e,children:(0,s.jsx)(c,{...e})}):c(e)}},8453:(e,n,t)=>{t.d(n,{R:()=>o,x:()=>r});var i=t(6540);const s={},a=i.createContext(s);function o(e){const n=i.useContext(a);return i.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),i.createElement(a.Provider,{value:n},e.children)}}}]);

solace_agent_mesh/assets/docs/assets/js/e1b6eeb4.deb2b62e.js

@@ -0,0 +1 @@
+"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[8773],{135:(e,n,t)=>{t.r(n),t.d(n,{assets:()=>c,contentTitle:()=>a,default:()=>m,frontMatter:()=>o,metadata:()=>i,toc:()=>l});const i=JSON.parse('{"id":"documentation/deploying/proxy_configuration","title":"Proxy Configuration","description":"When deploying Agent Mesh in environments with restricted network access, you may need to configure proxy settings to enable communication with external services. This guide explains how to configure HTTPS proxy settings for Agent Mesh.","source":"@site/docs/documentation/deploying/proxy_configuration.md","sourceDirName":"documentation/deploying","slug":"/documentation/deploying/proxy_configuration","permalink":"/solace-agent-mesh/docs/documentation/deploying/proxy_configuration","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/deploying/proxy_configuration.md","tags":[],"version":"current","sidebarPosition":550,"frontMatter":{"title":"Proxy Configuration","sidebar_position":550},"sidebar":"docSidebar","previous":{"title":"Logging","permalink":"/solace-agent-mesh/docs/documentation/deploying/logging"},"next":{"title":"Migration to Platform Service (Enterprise v1.27.0+)","permalink":"/solace-agent-mesh/docs/documentation/migrations/platform-service-split"}}');var r=t(4848),s=t(8453);const o={title:"Proxy Configuration",sidebar_position:550},a="Proxy Configuration",c={},l=[{value:"Environment Variables for Proxy Configuration",id:"environment-variables-for-proxy-configuration",level:2},{value:"Proxy Configuration Details",id:"proxy-configuration-details",level:2},{value:"Setting Proxy Environment Variables",id:"setting-proxy-environment-variables",level:2},{value:"Linux/macOS",id:"linuxmacos",level:3},{value:"Windows",id:"windows",level:3},{value:"Docker",id:"docker",level:3},{value:"Kubernetes",id:"kubernetes",level:3},{value:"Certificate Bundle Merging",id:"certificate-bundle-merging",level:2}];function d(e){const n={code:"code",h1:"h1",h2:"h2",h3:"h3",header:"header",p:"p",pre:"pre",table:"table",tbody:"tbody",td:"td",th:"th",thead:"thead",tr:"tr",...(0,s.R)(),...e.components};return(0,r.jsxs)(r.Fragment,{children:[(0,r.jsx)(n.header,{children:(0,r.jsx)(n.h1,{id:"proxy-configuration",children:"Proxy Configuration"})}),"\n",(0,r.jsx)(n.p,{children:"When deploying Agent Mesh in environments with restricted network access, you may need to configure proxy settings to enable communication with external services. This guide explains how to configure HTTPS proxy settings for Agent Mesh."}),"\n",(0,r.jsx)(n.h2,{id:"environment-variables-for-proxy-configuration",children:"Environment Variables for Proxy Configuration"}),"\n",(0,r.jsx)(n.p,{children:"Agent Mesh respects standard proxy environment variables that are commonly used across many applications:"}),"\n",(0,r.jsxs)(n.table,{children:[(0,r.jsx)(n.thead,{children:(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.th,{children:"Environment Variable"}),(0,r.jsx)(n.th,{children:"Description"}),(0,r.jsx)(n.th,{children:"Format"}),(0,r.jsx)(n.th,{children:"Example"})]})}),(0,r.jsxs)(n.tbody,{children:[(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"HTTPS_PROXY"})}),(0,r.jsx)(n.td,{children:"Specifies the proxy server for HTTPS requests"}),(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"protocol://[username:password@]host[:port]"})}),(0,r.jsxs)(n.td,{children:[(0,r.jsx)(n.code,{children:"http://proxy.example.com:8080"})," or ",(0,r.jsx)(n.code,{children:"https://proxy.example.com:443"})]})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"REQUESTS_CA_BUNDLE"})}),(0,r.jsx)(n.td,{children:"Path to a custom CA certificate file or bundle used by requests and a number of other libraries. Use alongside SSL_CERT_FILE to maximize compatibility."}),(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"Path to certificate"})}),(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"/path/to/certificate.crt"})})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"SSL_CERT_FILE"})}),(0,r.jsx)(n.td,{children:"Path to a custom CA certificate file or bundle used by requests and a number of other libraries. Use alongside REQUESTS_CA_BUNDLE to maximize compatibility."}),(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"Path to certificate"})}),(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"/path/to/certificate.crt"})})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"DISABLE_SSL_VERIFY"})}),(0,r.jsx)(n.td,{children:"When set to a true value disables SSL certificate validation for outgoing LLM requests."}),(0,r.jsx)(n.td,{children:"boolean"}),(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"true"})})]})]})]}),"\n",(0,r.jsx)(n.p,{children:"These environment variables can be set at the system level or specifically for the Agent Mesh process."}),"\n",(0,r.jsx)(n.h2,{id:"proxy-configuration-details",children:"Proxy Configuration Details"}),"\n",(0,r.jsx)(n.p,{children:"If DISABLE_SSL_VERIFY is true \u2192 TLS verification is disabled (applies globally).\nElse if REQUESTS_CA_BUNDLE or SSL_CERT_FILE is set \u2192 the provided file is used as the trusted CA bundle for TLS validation. Recommendation: set both REQUESTS_CA_BUNDLE and SSL_CERT_FILE to the same path to maximize compatibility, because different components/libraries may read one or the other.\nElse \u2192 the system's default/trusted CA bundle is used."}),"\n",(0,r.jsx)(n.h2,{id:"setting-proxy-environment-variables",children:"Setting Proxy Environment Variables"}),"\n",(0,r.jsx)(n.h3,{id:"linuxmacos",children:"Linux/macOS"}),"\n",(0,r.jsx)(n.p,{children:"For temporary settings (current terminal session only):"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-bash",children:'export HTTPS_PROXY="http://proxy.example.com:8080"\nexport REQUESTS_CA_BUNDLE="/path/to/certificate.pem"\nexport SSL_CERT_FILE="$REQUESTS_CA_BUNDLE"\n'})}),"\n",(0,r.jsxs)(n.p,{children:["For persistent settings, add these lines to your ",(0,r.jsx)(n.code,{children:"~/.bashrc"}),", ",(0,r.jsx)(n.code,{children:"~/.bash_profile"}),", or ",(0,r.jsx)(n.code,{children:"~/.zshrc"})," file."]}),"\n",(0,r.jsx)(n.h3,{id:"windows",children:"Windows"}),"\n",(0,r.jsx)(n.p,{children:"For temporary settings (current command prompt session only):"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-cmd",children:'set HTTPS_PROXY=http://proxy.example.com:8080\nset REQUESTS_CA_BUNDLE="/path/to/certificate.pem"\nset SSL_CERT_FILE="/path/to/certificate.pem"\n'})}),"\n",(0,r.jsx)(n.h3,{id:"docker",children:"Docker"}),"\n",(0,r.jsx)(n.p,{children:"When running Agent Mesh in Docker, you can set 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 --rm \\\n  -e HTTPS_PROXY="http://proxy.example.com:8080" \\\n  -e REQUESTS_CA_BUNDLE="/etc/ssl/certs/custom-ca.pem" \\\n  -e SSL_CERT_FILE="/etc/ssl/certs/custom-ca.pem" \\\n  -v "$HOME/.mitmproxy/mitmproxy-ca.pem:/etc/ssl/certs/custom-ca.pem:ro" \\\n  solace/agent-mesh:latest\n\n'})}),"\n",(0,r.jsx)(n.p,{children:"Or in your Docker Compose file:"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-yaml",children:"services:\n  agent-mesh:\n    image: solace/agent-mesh:latest\n    environment:\n      - HTTPS_PROXY=http://proxy.example.com:8080\n      - REQUESTS_CA_BUNDLE=/etc/ssl/certs/custom-ca.pem\n      - SSL_CERT_FILE=/etc/ssl/certs/custom-ca.pem\n    volumes:\n      - ./certs/mitmproxy-ca.pem:/etc/ssl/certs/custom-ca.pem:ro\n....\n\n"})}),"\n",(0,r.jsx)(n.h3,{id:"kubernetes",children:"Kubernetes"}),"\n",(0,r.jsx)(n.p,{children:"For Kubernetes deployments:"}),"\n",(0,r.jsx)(n.p,{children:"Ensure configmap:"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-shell",children:"kubectl create configmap mitm-ca \\\n  --from-file=mitmproxy-ca.pem=./certs/mitmproxy-ca.pem \\\n  -n my-namespace\n\n"})}),"\n",(0,r.jsx)(n.p,{children:"reference in deployment manifest:"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-yaml",children:'apiVersion: apps/v1\nkind: Deployment\nmetadata:\n  name: agent-mesh\n  namespace: my-namespace\nspec:\n  replicas: 1\n  selector:\n    matchLabels:\n      app: agent-mesh\n  template:\n    metadata:\n      labels:\n        app: agent-mesh\n    spec:\n      containers:\n        - name: agent-mesh\n          image: solace/agent-mesh:latest\n          env:\n            - name: HTTPS_PROXY\n              value: "http://my-proxy.example.com:8080"\n            - name: REQUESTS_CA_BUNDLE\n              value: "/etc/ssl/certs/mitmproxy-ca.pem"\n            - name: SSL_CERT_FILE\n              value: "/etc/ssl/certs/mitmproxy-ca.pem"\n          volumeMounts:\n            - name: mitm-ca\n              mountPath: /etc/ssl/certs/mitmproxy-ca.pem\n              subPath: mitmproxy-ca.pem\n              readOnly: true\n      volumes:\n        - name: mitm-ca\n          configMap:\n            name: mitm-ca\n            items:\n              - key: mitmproxy-ca.pem\n                path: mitmproxy-ca.pem\n\n'})}),"\n",(0,r.jsx)(n.h2,{id:"certificate-bundle-merging",children:"Certificate Bundle Merging"}),"\n",(0,r.jsx)(n.p,{children:"In some environments, especially when using forward or corporate proxies, you may need to add your internal CA to the default certifi trust bundle used by Python.\nThis ensures both public and internal certificates are trusted without disabling SSL verification."}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-code",children:'# Path to your custom CA certificate\nCUSTOM_CA=/path/to/custom-ca.pem\n\n# Locate the default certifi bundle\nCERTIFI_BUNDLE=$(python -m certifi)\n\n# Choose output path for the merged bundle\nMERGED_BUNDLE=/tmp/combined-ca.pem\n\n# Merge the two bundles\ncat "$CERTIFI_BUNDLE" "$CUSTOM_CA" > "$MERGED_BUNDLE"\n\n# Point Python SSL libraries to the merged file\nexport REQUESTS_CA_BUNDLE="$MERGED_BUNDLE"\nexport SSL_CERT_FILE="$MERGED_BUNDLE"\n\n# (Optional) verify\npython -c "import requests; print(requests.get(\'https://example.com\').status_code)"\n\n'})}),"\n",(0,r.jsx)(n.p,{children:"This augments the existing certifi CA bundle with your custom certificate while keeping the original file intact."})]})}function m(e={}){const{wrapper:n}={...(0,s.R)(),...e.components};return n?(0,r.jsx)(n,{...e,children:(0,r.jsx)(d,{...e})}):d(e)}},8453:(e,n,t)=>{t.d(n,{R:()=>o,x:()=>a});var i=t(6540);const r={},s=i.createContext(r);function o(e){const n=i.useContext(s);return i.useMemo((function(){return"function"==typeof e?e(n):{...n,...e}}),[n,e])}function a(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(r):e.components||r:o(e.components),i.createElement(s.Provider,{value:n},e.children)}}}]);

solace_agent_mesh/assets/docs/assets/js/e3d9abda.1476f570.js

@@ -0,0 +1 @@
+"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[7798],{7098:(e,n,i)=>{i.r(n),i.d(n,{assets:()=>d,contentTitle:()=>a,default:()=>h,frontMatter:()=>s,metadata:()=>t,toc:()=>l});const t=JSON.parse('{"id":"documentation/enterprise/installation","title":"Installing Agent Mesh Enterprise","description":"This guide walks you through installing and running Agent Mesh Enterprise using Docker. You will download the enterprise image, load it into Docker, and launch a container configured for either development or production use.","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":"Installing Agent Mesh Enterprise","sidebar_position":5},"sidebar":"docSidebar","previous":{"title":"Agent Mesh Enterprise","permalink":"/solace-agent-mesh/docs/documentation/enterprise/"},"next":{"title":"Running from Wheel File","permalink":"/solace-agent-mesh/docs/documentation/enterprise/wheel-installation"}}');var o=i(4848),r=i(8453);const s={title:"Installing Agent Mesh Enterprise",sidebar_position:5},a=void 0,d={},l=[{value:"Prerequisites",id:"prerequisites",level:2},{value:"Understanding the Installation Process",id:"understanding-the-installation-process",level:2},{value:"Step 1: Download and Load the Enterprise Image",id:"step-1-download-and-load-the-enterprise-image",level:2},{value:"Step 2: Identify the Image Name",id:"step-2-identify-the-image-name",level:2},{value:"Step 3: Run the Container",id:"step-3-run-the-container",level:2},{value:"Running in Development Mode",id:"running-in-development-mode",level:3},{value:"Running in Production Mode",id:"running-in-production-mode",level:3},{value:"Accessing the Web UI",id:"accessing-the-web-ui",level:2},{value:"Troubleshooting and Debugging",id:"troubleshooting-and-debugging",level:2}];function c(e){const n={a:"a",admonition:"admonition",code:"code",h2:"h2",h3:"h3",img:"img",li:"li",p:"p",pre:"pre",strong:"strong",ul:"ul",...(0,r.R)(),...e.components},{Details:t}=n;return t||function(e,n){throw new Error("Expected "+(n?"component":"object")+" `"+e+"` to be defined: you likely forgot to import, pass, or provide it.")}("Details",!0),(0,o.jsxs)(o.Fragment,{children:[(0,o.jsx)(n.p,{children:"This guide walks you through installing and running Agent Mesh Enterprise using Docker. You will download the enterprise image, load it into Docker, and launch a container configured for either development or production use."}),"\n",(0,o.jsx)(n.admonition,{type:"tip",children:(0,o.jsxs)(n.p,{children:["All the ",(0,o.jsx)(n.code,{children:"docker"})," commands can also be run using any Docker-compatible tool, such as ",(0,o.jsx)(n.a,{href:"https://podman.io/",children:"Podman"}),"."]})}),"\n",(0,o.jsx)(n.h2,{id:"prerequisites",children:"Prerequisites"}),"\n",(0,o.jsx)(n.p,{children:"Before you begin, ensure you have the following:"}),"\n",(0,o.jsxs)(n.ul,{children:["\n",(0,o.jsx)(n.li,{children:"Docker installed on your system"}),"\n",(0,o.jsxs)(n.li,{children:["Access to the ",(0,o.jsx)(n.a,{href:"https://products.solace.com/prods/Agent_Mesh/Enterprise/",children:"Solace Product Portal"})]}),"\n",(0,o.jsx)(n.li,{children:"An LLM service API key and endpoint"}),"\n",(0,o.jsx)(n.li,{children:"For production deployments, Solace broker credentials"}),"\n"]}),"\n",(0,o.jsx)(n.h2,{id:"understanding-the-installation-process",children:"Understanding the Installation Process"}),"\n",(0,o.jsx)(n.p,{children:"The installation process consists of three main steps. First, you download and load the Docker image into your local Docker environment. This makes the Agent Mesh Enterprise software available on your system. Second, you identify the exact image name and tag that Docker assigned during the load process. You need this information to reference the correct image when starting your container. Finally, you run the container with the appropriate configuration for your use case\u2014either development mode with an embedded broker or production mode connected to an external Solace broker."}),"\n",(0,o.jsx)(n.h2,{id:"step-1-download-and-load-the-enterprise-image",children:"Step 1: Download and Load the Enterprise Image"}),"\n",(0,o.jsx)(n.p,{children:"You need to obtain the Agent Mesh Enterprise Docker image from the Solace Product Portal and load it into your Docker environment."}),"\n",(0,o.jsxs)(n.p,{children:["Download the latest enterprise docker image tarball from the ",(0,o.jsx)(n.a,{href:"https://products.solace.com/prods/Agent_Mesh/Enterprise/",children:"Solace Product Portal"}),"."]}),"\n",(0,o.jsx)(n.p,{children:"After downloading the tarball, load the image into Docker. This command extracts the image from the compressed archive and makes it available in your local Docker image repository."}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-bash",children:"docker load -i solace-agent-mesh-enterprise-<tag>.tar.gz\n"})}),"\n",(0,o.jsxs)(n.p,{children:["Ensure you replace ",(0,o.jsx)(n.code,{children:"<tag>"})," with the appropriate version number from your downloaded file."]}),"\n",(0,o.jsx)(n.h2,{id:"step-2-identify-the-image-name",children:"Step 2: Identify the Image Name"}),"\n",(0,o.jsx)(n.p,{children:"After loading the image, you need to identify its full name and tag. Docker assigns a repository name and tag to the image during the load process, and you will use this information when running the container."}),"\n",(0,o.jsx)(n.p,{children:"Run the following command to list all Docker images on your system:"}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-bash",children:"docker images\n"})}),"\n",(0,o.jsx)(n.p,{children:"The output displays all available images with their repository names, tags, image IDs, creation dates, and sizes. Look for the Agent Mesh Enterprise image in the list."}),"\n",(0,o.jsx)(n.p,{children:"Example output:"}),"\n",(0,o.jsx)(n.pre,{children:(0,o.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,o.jsxs)(n.p,{children:["Take note of the complete repository name and tag. You will need this full identifier when starting the container. In the example above, the complete image name is ",(0,o.jsx)(n.code,{children:"868978040651.dkr.ecr.us-east-1.amazonaws.com/solace-agent-mesh-enterprise:1.0.37-c8890c7f31"}),"."]}),"\n",(0,o.jsxs)(n.p,{children:["The numeric hashes at the beginning and end of the repository name (such as ",(0,o.jsx)(n.code,{children:"868978040651"})," and ",(0,o.jsx)(n.code,{children:"c8890c7f31"}),") vary between versions and builds. Your image will have different hash values."]}),"\n",(0,o.jsx)(n.h2,{id:"step-3-run-the-container",children:"Step 3: Run the Container"}),"\n",(0,o.jsx)(n.p,{children:"You can run Agent Mesh Enterprise in two different modes depending on your needs. Development mode uses an embedded Solace broker for quick testing and experimentation, while production mode connects to an external Solace broker for enterprise deployments."}),"\n",(0,o.jsx)(n.admonition,{type:"tip",children:(0,o.jsxs)(n.p,{children:["You may need to include ",(0,o.jsx)(n.code,{children:"--platform linux/amd64"})," depending on the host machine you're using."]})}),"\n",(0,o.jsxs)(n.admonition,{title:"Authorization Required",type:"warning",children:[(0,o.jsxs)(n.p,{children:[(0,o.jsx)(n.strong,{children:"Agent Mesh Enterprise uses secure-by-default authorization."})," Without explicit authorization configuration, the system will ",(0,o.jsx)(n.strong,{children:"deny all access"})," to protect your deployment."]}),(0,o.jsxs)(n.p,{children:["For production use, you must configure RBAC (Role-Based Access Control) to grant access to users. See the ",(0,o.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/enterprise/rbac-setup-guide",children:"RBAC Setup Guide"})," for details."]}),(0,o.jsxs)(n.p,{children:["For development/testing only, you can disable authorization by setting ",(0,o.jsx)(n.code,{children:"type: none"})," in your configuration, but this should ",(0,o.jsx)(n.strong,{children:"never"})," be used in production. (see example below)"]})]}),"\n",(0,o.jsx)(n.h3,{id:"running-in-development-mode",children:"Running in Development Mode"}),"\n",(0,o.jsx)(n.p,{children:"Development mode simplifies getting started by using an embedded Solace broker. This configuration requires fewer parameters and allows you to test Agent Mesh Enterprise without setting up external infrastructure. Use this mode for local development, testing, and evaluation."}),"\n",(0,o.jsxs)(n.p,{children:["The following command starts a container in development mode. The ",(0,o.jsx)(n.code,{children:"-itd"})," flags run the container in interactive mode with a pseudo-TTY, detached in the background. The ",(0,o.jsx)(n.code,{children:"-p 8001:8000"})," flag maps port 8000 inside the container to port 8001 on your host machine, making the web UI accessible at ",(0,o.jsx)(n.code,{children:"http://localhost:8001"}),"."]}),"\n",(0,o.jsx)(n.pre,{children:(0,o.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  -e SAM_AUTHORIZATION_CONFIG="/preset/auth/insecure_permissive_auth_config.yaml" \\\n  --name sam-ent-dev \\\n  solace-agent-mesh-enterprise:<tag>\n'})}),"\n",(0,o.jsx)(n.p,{children:"Replace the placeholder values with your actual configuration:"}),"\n",(0,o.jsxs)(n.ul,{children:["\n",(0,o.jsxs)(n.li,{children:[(0,o.jsx)(n.code,{children:"<YOUR_LLM_TOKEN>"}),": Your API key for the LLM service"]}),"\n",(0,o.jsxs)(n.li,{children:[(0,o.jsx)(n.code,{children:"<YOUR_LLM_SERVICE_ENDPOINT>"}),": The URL endpoint for your LLM service"]}),"\n",(0,o.jsxs)(n.li,{children:[(0,o.jsx)(n.code,{children:"<YOUR_MODEL_NAME>"}),": The name of the LLM model you want to use (you can specify the same model for both planning and general tasks, or use different models)"]}),"\n",(0,o.jsxs)(n.li,{children:[(0,o.jsx)(n.code,{children:"<YOUR_NAMESPACE>"}),': A unique identifier for your deployment (such as "sam-dev")']}),"\n",(0,o.jsxs)(n.li,{children:[(0,o.jsx)(n.code,{children:"<tag>"}),": The image tag you identified in Step 2"]}),"\n"]}),"\n",(0,o.jsxs)(n.p,{children:["The ",(0,o.jsx)(n.code,{children:'SOLACE_DEV_MODE="true"'})," environment variable tells the container to use the embedded broker instead of connecting to an external one."]}),"\n",(0,o.jsxs)(t,{children:[(0,o.jsx)("summary",{children:"Example: Basic Development Mode (Secure Default - Access Denied)"}),(0,o.jsx)(n.pre,{children:(0,o.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'})}),(0,o.jsxs)(n.p,{children:[(0,o.jsx)(n.strong,{children:"Note:"})," This configuration uses secure defaults and will deny all access. You must configure RBAC or use the permissive development configuration below."]})]}),"\n",(0,o.jsxs)(t,{children:[(0,o.jsx)("summary",{children:"Example: Development Mode with Permissive Authorization (Development Only)"}),(0,o.jsxs)(n.p,{children:["You can use the pre-configured development configuration file provided in the ",(0,o.jsx)(n.code,{children:"preset"})," directory. Run the container with the ",(0,o.jsx)(n.code,{children:"SAM_AUTHORIZATION_CONFIG"})," environment variable pointing to this file to disable authorization checks."]}),(0,o.jsx)(n.pre,{children:(0,o.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  -e SAM_AUTHORIZATION_CONFIG="/preset/auth/insecure_permissive_auth_config.yaml" \\\n  --name sam-ent-dev \\\n  868978040651.dkr.ecr.us-east-1.amazonaws.com/solace-agent-mesh-enterprise:1.0.37-c8890c7f31\n'})}),(0,o.jsxs)(n.p,{children:[(0,o.jsx)(n.strong,{children:"\u26a0\ufe0f Warning:"})," This configuration disables authorization and grants full access. Use only for local development."]})]}),"\n",(0,o.jsx)(n.h3,{id:"running-in-production-mode",children:"Running in Production Mode"}),"\n",(0,o.jsx)(n.p,{children:"Production mode connects to an external Solace broker, which provides enterprise-grade messaging capabilities including high availability, disaster recovery, and scalability. Use this mode when deploying Agent Mesh Enterprise in production environments."}),"\n",(0,o.jsx)(n.p,{children:"The production configuration requires additional environment variables to specify the Solace broker connection details. These credentials allow the container to connect to your Solace Cloud service or on-premises broker."}),"\n",(0,o.jsx)(n.pre,{children:(0,o.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,o.jsx)(n.p,{children:"Replace the placeholder values with your actual configuration. In addition to the LLM service parameters described in the development mode section, you need to provide:"}),"\n",(0,o.jsxs)(n.ul,{children:["\n",(0,o.jsxs)(n.li,{children:[(0,o.jsx)(n.code,{children:"<YOUR_BROKER_URL>"}),": The secured SMF URI for your Solace broker"]}),"\n",(0,o.jsxs)(n.li,{children:[(0,o.jsx)(n.code,{children:"<YOUR_BROKER_VPN>"}),": The Message VPN name for your Solace service"]}),"\n",(0,o.jsxs)(n.li,{children:[(0,o.jsx)(n.code,{children:"<YOUR_BROKER_USERNAME>"}),": The username for broker authentication"]}),"\n",(0,o.jsxs)(n.li,{children:[(0,o.jsx)(n.code,{children:"<YOUR_BROKER_PASSWORD>"}),": The password for broker authentication"]}),"\n"]}),"\n",(0,o.jsxs)(n.p,{children:["The ",(0,o.jsx)(n.code,{children:'SOLACE_DEV_MODE="false"'})," environment variable tells the container to connect to the external broker specified by the other SOLACE_BROKER parameters instead of using the embedded broker."]}),"\n",(0,o.jsxs)(n.p,{children:[(0,o.jsx)(n.strong,{children:"Ensure you have set up proper RBAC authorization for production deployments."})," For more information, see ",(0,o.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/enterprise/rbac-setup-guide",children:"RBAC Setup Guide"}),"."]}),"\n",(0,o.jsxs)(t,{children:[(0,o.jsx)("summary",{children:"How to find your credentials"}),(0,o.jsx)(n.p,{children:"Go to Solace Cloud."}),(0,o.jsx)(n.p,{children:"Cluster manager > Your Service > Connect"}),(0,o.jsx)(n.p,{children:"Switch dropdown to View by Language"}),(0,o.jsx)(n.p,{children:"Open the connect with Python dropdown"}),(0,o.jsx)(n.p,{children:"Click Solace Python with smf as the protocol."}),(0,o.jsx)(n.p,{children:"Copy:"}),(0,o.jsxs)(n.ul,{children:["\n",(0,o.jsx)(n.li,{children:"Username for SOLACE_BROKER_USERNAME,"}),"\n",(0,o.jsx)(n.li,{children:"Password for SOLACE_BROKER_PASSWORD,"}),"\n",(0,o.jsx)(n.li,{children:"Message VPN for SOLACE_BROKER_VPN"}),"\n",(0,o.jsx)(n.li,{children:"Secured SMF URI for SOLACE_BROKER_URL"}),"\n"]}),(0,o.jsx)(n.p,{children:(0,o.jsx)(n.img,{alt:"How to get credentials",src:i(5981).A+"",width:"3456",height:"1916"})})]}),"\n",(0,o.jsx)(n.h2,{id:"accessing-the-web-ui",children:"Accessing the Web UI"}),"\n",(0,o.jsx)(n.p,{children:"After starting the container in either development or production mode, you can access the Agent Mesh Enterprise web interface through your browser. The UI provides a graphical interface for managing agents, monitoring activity, and configuring your deployment."}),"\n",(0,o.jsxs)(n.p,{children:["Navigate to ",(0,o.jsx)(n.code,{children:"http://localhost:8001"})," in your web browser. The port number corresponds to the host port you specified in the ",(0,o.jsx)(n.code,{children:"-p 8001:8000"})," flag when running the container."]}),"\n",(0,o.jsx)(n.h2,{id:"troubleshooting-and-debugging",children:"Troubleshooting and Debugging"}),"\n",(0,o.jsx)(n.p,{children:"If you encounter issues or need to investigate the behavior of your Agent Mesh Enterprise deployment, you can examine the log files generated by the container. These logs provide detailed information about system operations, errors, and debugging information."}),"\n",(0,o.jsxs)(n.p,{children:["To view logs, check the ",(0,o.jsx)(n.code,{children:".log"})," files in your container. For information about changing debug levels and advanced debugging techniques, see ",(0,o.jsx)(n.a,{href:"../deploying/debugging",children:"Diagnosing and Resolving Problems"}),"."]})]})}function h(e={}){const{wrapper:n}={...(0,r.R)(),...e.components};return n?(0,o.jsx)(n,{...e,children:(0,o.jsx)(c,{...e})}):c(e)}},5981:(e,n,i)=>{i.d(n,{A:()=>t});const t=i.p+"assets/images/sam-enterprise-credentials-b269f095349473118b2b33bdfcc40122.png"},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/e6f9706b.acc800d3.js

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