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

solace_agent_mesh/assets/docs/assets/js/924ffdeb.975e428a.js

@@ -0,0 +1 @@
+"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[8907],{3780:(e,n,t)=>{t.r(n),t.d(n,{assets:()=>l,contentTitle:()=>o,default:()=>h,frontMatter:()=>i,metadata:()=>s,toc:()=>c});const s=JSON.parse('{"id":"documentation/components/proxies","title":"Proxies","description":"Proxies act as protocol bridges that connect Agent Mesh to external A2A agents. By translating between A2A over Solace event mesh and A2A over HTTPS protocols, proxies enable agents within the mesh to delegate tasks to external agents and include them in collaborative workflows.","source":"@site/docs/documentation/components/proxies.md","sourceDirName":"documentation/components","slug":"/documentation/components/proxies","permalink":"/solace-agent-mesh/docs/documentation/components/proxies","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/components/proxies.md","tags":[],"version":"current","sidebarPosition":250,"frontMatter":{"title":"Proxies","sidebar_position":250},"sidebar":"docSidebar","previous":{"title":"Orchestrator","permalink":"/solace-agent-mesh/docs/documentation/components/orchestrator"},"next":{"title":"Gateways","permalink":"/solace-agent-mesh/docs/documentation/components/gateways"}}');var a=t(4848),r=t(8453);const i={title:"Proxies",sidebar_position:250},o="Proxies",l={},c=[{value:"Key Functions",id:"key-functions",level:2},{value:"When to Use a Proxy",id:"when-to-use-a-proxy",level:2},{value:"Proxy vs. Native Agent",id:"proxy-vs-native-agent",level:3},{value:"Architecture Overview",id:"architecture-overview",level:2},{value:"Configuration",id:"configuration",level:2},{value:"Basic Configuration",id:"basic-configuration",level:3},{value:"Configuration Parameters",id:"configuration-parameters",level:3},{value:"Authentication Types",id:"authentication-types",level:2},{value:"Static Bearer Token",id:"static-bearer-token",level:3},{value:"Static API Key",id:"static-api-key",level:3},{value:"OAuth 2.0 Client Credentials",id:"oauth-20-client-credentials",level:3},{value:"Custom HTTP Headers",id:"custom-http-headers",level:2},{value:"Header Configuration",id:"header-configuration",level:3},{value:"Header Precedence Rules",id:"header-precedence-rules",level:3},{value:"Use Cases",id:"use-cases",level:3},{value:"Artifact Handling",id:"artifact-handling",level:2},{value:"Request Flow: Agent Mesh to External Agent",id:"request-flow-agent-mesh-to-external-agent",level:3},{value:"Response Flow: External Agent to Agent Mesh",id:"response-flow-external-agent-to-agent-mesh",level:3},{value:"Artifact Metadata",id:"artifact-metadata",level:3},{value:"Status Update Conversion",id:"status-update-conversion",level:2},{value:"Conversion Scope",id:"conversion-scope",level:3},{value:"When to Disable",id:"when-to-disable",level:3},{value:"Discovery and Health",id:"discovery-and-health",level:2},{value:"Initial Discovery",id:"initial-discovery",level:3},{value:"Periodic Refresh",id:"periodic-refresh",level:3},{value:"Agent Card Transformation",id:"agent-card-transformation",level:3},{value:"URL Behavior",id:"url-behavior",level:3},{value:"Task Lifecycle Management",id:"task-lifecycle-management",level:2},{value:"Task Initiation",id:"task-initiation",level:3},{value:"Task Cancellation",id:"task-cancellation",level:3},{value:"Task Completion",id:"task-completion",level:3},{value:"Error Handling and Retry Logic",id:"error-handling-and-retry-logic",level:2},{value:"OAuth 2.0 Automatic Retry",id:"oauth-20-automatic-retry",level:3},{value:"Connection Errors",id:"connection-errors",level:3},{value:"Error Responses",id:"error-responses",level:3},{value:"Creating a Proxy",id:"creating-a-proxy",level:2},{value:"Creating the Configuration File",id:"creating-the-configuration-file",level:3},{value:"Running the Proxy",id:"running-the-proxy",level:3},{value:"Multiple Proxy Configurations",id:"multiple-proxy-configurations",level:3},{value:"Advanced Configuration",id:"advanced-configuration",level:2},{value:"Per-Agent Timeout Override",id:"per-agent-timeout-override",level:3},{value:"Custom Headers with Authentication",id:"custom-headers-with-authentication",level:3},{value:"URL Override for Task Invocations",id:"url-override-for-task-invocations",level:3},{value:"Custom Artifact Service Scope",id:"custom-artifact-service-scope",level:3},{value:"Multiple Proxies",id:"multiple-proxies",level:3},{value:"Troubleshooting",id:"troubleshooting",level:2},{value:"Agent Not Discoverable",id:"agent-not-discoverable",level:3},{value:"Authentication Failures",id:"authentication-failures",level:3},{value:"Timeout Errors",id:"timeout-errors",level:3},{value:"Artifact Issues",id:"artifact-issues",level:3},{value:"Issues Running A2A Samples with <code>Containerfile</code>",id:"issues-running-a2a-samples-with-containerfile",level:3}];function d(e){const n={a:"a",admonition:"admonition",code:"code",h1:"h1",h2:"h2",h3:"h3",header:"header",li:"li",mermaid:"mermaid",ol:"ol",p:"p",pre:"pre",strong:"strong",table:"table",tbody:"tbody",td:"td",th:"th",thead:"thead",tr:"tr",ul:"ul",...(0,r.R)(),...e.components};return(0,a.jsxs)(a.Fragment,{children:[(0,a.jsx)(n.header,{children:(0,a.jsx)(n.h1,{id:"proxies",children:"Proxies"})}),"\n",(0,a.jsx)(n.p,{children:"Proxies act as protocol bridges that connect Agent Mesh to external A2A agents. By translating between A2A over Solace event mesh and A2A over HTTPS protocols, proxies enable agents within the mesh to delegate tasks to external agents and include them in collaborative workflows."}),"\n",(0,a.jsx)(n.p,{children:"A single proxy instance can manage multiple external agents, each with its own URL, authentication configuration, and timeout settings."}),"\n",(0,a.jsx)(n.admonition,{title:"In one sentence",type:"tip",children:(0,a.jsx)(n.p,{children:"Proxies are protocol bridges that connect multiple external A2A-over-HTTPS agents to the Solace event mesh, enabling hybrid agent architectures."})}),"\n",(0,a.jsx)(n.h2,{id:"key-functions",children:"Key Functions"}),"\n",(0,a.jsxs)(n.ol,{children:["\n",(0,a.jsxs)(n.li,{children:["\n",(0,a.jsxs)(n.p,{children:[(0,a.jsx)(n.strong,{children:"Protocol Translation"}),": Proxies translate between A2A over HTTPS and A2A over Solace event mesh, enabling external agents to communicate with agents on the mesh without modification."]}),"\n"]}),"\n",(0,a.jsxs)(n.li,{children:["\n",(0,a.jsxs)(n.p,{children:[(0,a.jsx)(n.strong,{children:"Authentication Management"}),": Proxies handle authentication to downstream agents, supporting multiple authentication schemes including static bearer tokens, API keys, and OAuth 2.0 client credentials flow with automatic token refresh."]}),"\n"]}),"\n",(0,a.jsxs)(n.li,{children:["\n",(0,a.jsxs)(n.p,{children:[(0,a.jsx)(n.strong,{children:"Agent Discovery"}),": Proxies fetch agent cards from external agents and publish them to the mesh discovery topic, making external agents discoverable to other agents in the system."]}),"\n"]}),"\n",(0,a.jsxs)(n.li,{children:["\n",(0,a.jsxs)(n.p,{children:[(0,a.jsx)(n.strong,{children:"Artifact Handling"}),": Proxies manage artifact flow between the mesh and external agents, resolving artifact URIs to byte content before forwarding requests and saving returned artifacts to the mesh's artifact service."]}),"\n"]}),"\n",(0,a.jsxs)(n.li,{children:["\n",(0,a.jsxs)(n.p,{children:[(0,a.jsx)(n.strong,{children:"Task Lifecycle Management"}),": Proxies track active tasks, handle cancellation requests, and ensure proper cleanup when tasks complete or fail."]}),"\n"]}),"\n",(0,a.jsxs)(n.li,{children:["\n",(0,a.jsxs)(n.p,{children:[(0,a.jsx)(n.strong,{children:"Automatic Retry Logic"}),": For OAuth 2.0 authenticated agents, proxies automatically detect authentication failures (401 responses), refresh tokens, and retry requests without manual intervention."]}),"\n"]}),"\n"]}),"\n",(0,a.jsx)(n.h2,{id:"when-to-use-a-proxy",children:"When to Use a Proxy"}),"\n",(0,a.jsx)(n.p,{children:"Proxies are the right choice when you need:"}),"\n",(0,a.jsxs)(n.ul,{children:["\n",(0,a.jsxs)(n.li,{children:["\n",(0,a.jsxs)(n.p,{children:[(0,a.jsx)(n.strong,{children:"Integration with Third-Party Agents"}),": Connect to external A2A agents provided by vendors or partners that run on their own infrastructure."]}),"\n"]}),"\n",(0,a.jsxs)(n.li,{children:["\n",(0,a.jsxs)(n.p,{children:[(0,a.jsx)(n.strong,{children:"Hybrid Cloud Architectures"}),": Bridge agents running in different cloud environments or on-premises systems with your Solace mesh."]}),"\n"]}),"\n",(0,a.jsxs)(n.li,{children:["\n",(0,a.jsxs)(n.p,{children:[(0,a.jsx)(n.strong,{children:"Legacy System Integration"}),": Connect existing A2A agents that cannot be modified to use Solace messaging directly."]}),"\n"]}),"\n",(0,a.jsxs)(n.li,{children:["\n",(0,a.jsxs)(n.p,{children:[(0,a.jsx)(n.strong,{children:"Gradual Migration"}),": Incrementally migrate agents to the Solace mesh while maintaining compatibility with external systems."]}),"\n"]}),"\n",(0,a.jsxs)(n.li,{children:["\n",(0,a.jsxs)(n.p,{children:[(0,a.jsx)(n.strong,{children:"Service Isolation"}),": Keep certain agents isolated on separate infrastructure while still enabling them to participate in collaborative workflows."]}),"\n"]}),"\n"]}),"\n",(0,a.jsx)(n.h3,{id:"proxy-vs-native-agent",children:"Proxy vs. Native Agent"}),"\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:"Aspect"}),(0,a.jsx)(n.th,{children:"Proxy"}),(0,a.jsx)(n.th,{children:"Native Agent"})]})}),(0,a.jsxs)(n.tbody,{children:[(0,a.jsxs)(n.tr,{children:[(0,a.jsx)(n.td,{children:(0,a.jsx)(n.strong,{children:"Communication"})}),(0,a.jsx)(n.td,{children:"A2A over HTTPS to external agent"}),(0,a.jsx)(n.td,{children:"A2A over Solace event mesh directly"})]}),(0,a.jsxs)(n.tr,{children:[(0,a.jsx)(n.td,{children:(0,a.jsx)(n.strong,{children:"Deployment"})}),(0,a.jsx)(n.td,{children:"External agent runs separately"}),(0,a.jsx)(n.td,{children:"Runs within Agent Mesh"})]}),(0,a.jsxs)(n.tr,{children:[(0,a.jsx)(n.td,{children:(0,a.jsx)(n.strong,{children:"Authentication"})}),(0,a.jsx)(n.td,{children:"Proxy handles auth to external agent"}),(0,a.jsx)(n.td,{children:"Mesh-level authentication"})]}),(0,a.jsxs)(n.tr,{children:[(0,a.jsx)(n.td,{children:(0,a.jsx)(n.strong,{children:"Latency"})}),(0,a.jsx)(n.td,{children:"Additional HTTP hop"}),(0,a.jsx)(n.td,{children:"Direct mesh communication"})]}),(0,a.jsxs)(n.tr,{children:[(0,a.jsx)(n.td,{children:(0,a.jsx)(n.strong,{children:"Task Initiation"})}),(0,a.jsx)(n.td,{children:"Can only receive tasks from mesh agents"}),(0,a.jsx)(n.td,{children:"Can initiate tasks to any agent"})]}),(0,a.jsxs)(n.tr,{children:[(0,a.jsx)(n.td,{children:(0,a.jsx)(n.strong,{children:"Use Case"})}),(0,a.jsx)(n.td,{children:"External/third-party agents"}),(0,a.jsx)(n.td,{children:"Agents you control"})]})]})]}),"\n",(0,a.jsx)(n.h2,{id:"architecture-overview",children:"Architecture Overview"}),"\n",(0,a.jsx)(n.p,{children:"The proxy sits between the Solace event mesh and external A2A agents, performing bidirectional protocol translation:"}),"\n",(0,a.jsx)(n.mermaid,{value:"graph LR\n    A[Agent Mesh<br/>A2A over Solace Event Mesh] <--\x3e|Solace Topics| B[Proxy Component]\n    B <--\x3e|HTTPS| C[External Agent 1<br/>A2A over HTTPS]\n    B <--\x3e|HTTPS| D[External Agent 2<br/>A2A over HTTPS]\n    B <--\x3e|HTTPS| E[External Agent N<br/>A2A over HTTPS]\n    \n    style B fill:none,stroke:#00C895,stroke-width:2px\n    style A fill:none,stroke:#333,stroke-width:2px\n    style C fill:none,stroke:#333,stroke-width:2px\n    style D fill:none,stroke:#333,stroke-width:2px\n    style E fill:none,stroke:#333,stroke-width:2px"}),"\n",(0,a.jsx)(n.p,{children:"The proxy performs these operations:"}),"\n",(0,a.jsxs)(n.ol,{children:["\n",(0,a.jsxs)(n.li,{children:["\n",(0,a.jsxs)(n.p,{children:[(0,a.jsx)(n.strong,{children:"Request Flow"}),": Receives A2A requests from Agent Mesh, resolves artifact URIs to byte content, forwards HTTPS requests to external agents, and streams responses back to Agent Mesh."]}),"\n"]}),"\n",(0,a.jsxs)(n.li,{children:["\n",(0,a.jsxs)(n.p,{children:[(0,a.jsx)(n.strong,{children:"Response Flow"}),": Receives responses from external agents, saves artifacts to Agent Mesh's artifact service, replaces byte content with artifact URIs, and publishes responses to Agent Mesh topics."]}),"\n"]}),"\n",(0,a.jsxs)(n.li,{children:["\n",(0,a.jsxs)(n.p,{children:[(0,a.jsx)(n.strong,{children:"Discovery Flow"}),": Periodically fetches agent cards from external agents, updates the local registry, and publishes cards to the Agent Mesh discovery topic."]}),"\n"]}),"\n"]}),"\n",(0,a.jsx)(n.h2,{id:"configuration",children:"Configuration"}),"\n",(0,a.jsx)(n.p,{children:"Proxies are configured through YAML files that specify the namespace, downstream agents, authentication, and service settings."}),"\n",(0,a.jsx)(n.h3,{id:"basic-configuration",children:"Basic Configuration"}),"\n",(0,a.jsxs)(n.p,{children:["A single proxy can manage multiple external agents. Each agent in the ",(0,a.jsx)(n.code,{children:"proxied_agents"})," list can have its own URL, authentication, and timeout configuration:"]}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-yaml",children:'app:\n  class_name: solace_agent_mesh.agent.proxies.a2a.app.A2AProxyApp\n  name: my-a2a-proxy\n  app_config:\n    namespace: "myorg/production"\n    proxied_agents:\n      - name: "external-data-agent"\n        url: "https://api.example.com/agent"\n        request_timeout_seconds: 120\n        # Optional: Apply auth to agent card fetching\n        # use_auth_for_agent_card: true\n        # Optional: Use configured URL instead of agent card URL for tasks\n        # use_agent_card_url: false\n        # Optional: Custom headers for agent card fetching\n        # agent_card_headers:\n        #   - name: "X-API-Version"\n        #     value: "v2"\n        # Optional: Custom headers for task invocations\n        # task_headers:\n        #   - name: "X-Tenant-ID"\n        #     value: "${TENANT_ID}"\n      - name: "external-analytics-agent"\n        url: "https://analytics.example.com/agent"\n        request_timeout_seconds: 180\n      - name: "external-reporting-agent"\n        url: "https://reports.example.com/agent"\n    artifact_service:\n      type: "filesystem"\n      base_path: "/tmp/proxy-artifacts"\n    discovery_interval_seconds: 60\n    default_request_timeout_seconds: 300\n\nbroker:\n  # Broker configuration inherited from environment or specified here\n'})}),"\n",(0,a.jsx)(n.h3,{id:"configuration-parameters",children:"Configuration Parameters"}),"\n",(0,a.jsxs)(n.ul,{children:["\n",(0,a.jsxs)(n.li,{children:[(0,a.jsx)(n.code,{children:"namespace"}),': The topic prefix for A2A communication (for example, "myorg/production").']}),"\n",(0,a.jsxs)(n.li,{children:[(0,a.jsx)(n.code,{children:"proxied_agents"}),": A list of external agents to proxy. Each agent can have its own URL, authentication, and timeout settings (see Authentication Types below).","\n",(0,a.jsxs)(n.ul,{children:["\n",(0,a.jsxs)(n.li,{children:[(0,a.jsx)(n.code,{children:"use_auth_for_agent_card"}),": If true, applies the configured authentication when fetching agent cards. If false (default), agent card requests are made without authentication."]}),"\n",(0,a.jsxs)(n.li,{children:[(0,a.jsx)(n.code,{children:"use_agent_card_url"}),": If true (default), uses the URL from the agent card for task invocations. If false, uses the configured URL directly for all task invocations. Note: The configured URL is always used to fetch the agent card itself."]}),"\n",(0,a.jsxs)(n.li,{children:[(0,a.jsx)(n.code,{children:"agent_card_headers"}),": Custom HTTP headers to include when fetching the agent card. These headers are added alongside authentication headers."]}),"\n",(0,a.jsxs)(n.li,{children:[(0,a.jsx)(n.code,{children:"task_headers"}),": Custom HTTP headers to include when invoking A2A tasks. These headers are added alongside authentication headers."]}),"\n",(0,a.jsxs)(n.li,{children:[(0,a.jsx)(n.code,{children:"convert_progress_updates"}),": If true (default), converts TextParts in status updates to AgentProgressUpdateData DataParts for consistent UI behavior. If false, preserves original text parts."]}),"\n"]}),"\n"]}),"\n",(0,a.jsxs)(n.li,{children:[(0,a.jsx)(n.code,{children:"artifact_service"}),": Configuration for storing artifacts. This is shared across all proxied agents. This is configured in the same manner as agents and gateways"]}),"\n",(0,a.jsxs)(n.li,{children:[(0,a.jsx)(n.code,{children:"discovery_interval_seconds"}),": How often to refresh agent cards from all external agents (default: 60)."]}),"\n",(0,a.jsxs)(n.li,{children:[(0,a.jsx)(n.code,{children:"default_request_timeout_seconds"}),": Default timeout for requests to external agents. Individual agents can override this (default: 300)."]}),"\n"]}),"\n",(0,a.jsx)(n.h2,{id:"authentication-types",children:"Authentication Types"}),"\n",(0,a.jsxs)(n.p,{children:["The proxy supports three authentication schemes for connecting to downstream agents. Each agent in the ",(0,a.jsx)(n.code,{children:"proxied_agents"})," list can use a different authentication type, allowing you to integrate agents with varying security requirements in a single proxy instance."]}),"\n",(0,a.jsxs)(n.p,{children:["By default, authentication is only applied to A2A task invocations, not to agent card fetching. You can enable authentication for agent card fetching by setting ",(0,a.jsx)(n.code,{children:"use_auth_for_agent_card: true"})," in the agent configuration."]}),"\n",(0,a.jsx)(n.h3,{id:"static-bearer-token",children:"Static Bearer Token"}),"\n",(0,a.jsx)(n.p,{children:"Use static bearer tokens for agents that require a fixed authentication token."}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-yaml",children:'proxied_agents:\n  - name: "secure-agent"\n    url: "https://api.example.com/agent"\n    authentication:\n      type: "static_bearer"\n      token: "${AGENT_BEARER_TOKEN}"  # Use environment variable\n    # use_auth_for_agent_card: true  # Optional: Apply auth to agent card fetching\n'})}),"\n",(0,a.jsx)(n.h3,{id:"static-api-key",children:"Static API Key"}),"\n",(0,a.jsx)(n.p,{children:"Use static API keys for agents that require API key authentication."}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-yaml",children:'proxied_agents:\n  - name: "api-key-agent"\n    url: "https://api.example.com/agent"\n    authentication:\n      type: "static_apikey"\n      token: "${AGENT_API_KEY}"\n    # use_auth_for_agent_card: true  # Optional: Apply auth to agent card fetching\n'})}),"\n",(0,a.jsx)(n.h3,{id:"oauth-20-client-credentials",children:"OAuth 2.0 Client Credentials"}),"\n",(0,a.jsx)(n.p,{children:"Use OAuth 2.0 client credentials flow for agents that require dynamic token acquisition. The proxy automatically handles token refresh and retry logic."}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-yaml",children:'proxied_agents:\n  - name: "oauth-agent"\n    url: "https://api.example.com/agent"\n    authentication:\n      type: "oauth2_client_credentials"\n      token_url: "https://auth.example.com/oauth/token"\n      client_id: "${OAUTH_CLIENT_ID}"\n      client_secret: "${OAUTH_CLIENT_SECRET}"\n      scope: "agent.read agent.write"  # Optional\n      token_cache_duration_seconds: 3300  # Optional, default: 3300 (55 minutes)\n    # use_auth_for_agent_card: true  # Optional: Apply auth to agent card fetching\n'})}),"\n",(0,a.jsx)(n.p,{children:"The proxy caches OAuth tokens and automatically refreshes them when they expire. If a request receives a 401 Unauthorized response, the proxy invalidates the cached token and retries the request once with a fresh token."}),"\n",(0,a.jsx)(n.admonition,{title:"Security Best Practice",type:"note",children:(0,a.jsx)(n.p,{children:"Always use environment variables for sensitive credentials. Never commit tokens or secrets directly in configuration files."})}),"\n",(0,a.jsx)(n.h2,{id:"custom-http-headers",children:"Custom HTTP Headers"}),"\n",(0,a.jsx)(n.p,{children:"The proxy supports custom HTTP headers for both agent card fetching and A2A task invocations. This is useful for scenarios like API versioning, tenant identification, custom authentication schemes, or any other header-based requirements."}),"\n",(0,a.jsx)(n.h3,{id:"header-configuration",children:"Header Configuration"}),"\n",(0,a.jsxs)(n.p,{children:["Custom headers are defined as name-value pairs and can be configured separately for agent card fetching (",(0,a.jsx)(n.code,{children:"agent_card_headers"}),") and task invocations (",(0,a.jsx)(n.code,{children:"task_headers"}),"):"]}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-yaml",children:'proxied_agents:\n  - name: "custom-header-agent"\n    url: "https://api.example.com/agent"\n    authentication:\n      type: "static_bearer"\n      token: "${AGENT_TOKEN}"\n    agent_card_headers:\n      - name: "X-API-Version"\n        value: "v2"\n      - name: "X-Tenant-ID"\n        value: "${TENANT_ID}"\n    task_headers:\n      - name: "X-API-Version"\n        value: "v2"\n      - name: "X-Request-Priority"\n        value: "high"\n'})}),"\n",(0,a.jsx)(n.h3,{id:"header-precedence-rules",children:"Header Precedence Rules"}),"\n",(0,a.jsx)(n.p,{children:"When both authentication and custom headers are configured:"}),"\n",(0,a.jsxs)(n.ol,{children:["\n",(0,a.jsxs)(n.li,{children:["\n",(0,a.jsxs)(n.p,{children:[(0,a.jsx)(n.strong,{children:"Authentication headers take precedence"}),": The proxy applies authentication headers (like ",(0,a.jsx)(n.code,{children:"Authorization"})," or ",(0,a.jsx)(n.code,{children:"X-API-Key"}),") based on the authentication type configured. These are applied by the A2A SDK's authentication layer after custom headers are set."]}),"\n"]}),"\n",(0,a.jsxs)(n.li,{children:["\n",(0,a.jsxs)(n.p,{children:[(0,a.jsx)(n.strong,{children:"Custom headers are for metadata, not authentication"}),": Custom headers should be used for non-authentication purposes such as API versioning, tenant identification, or request metadata. They cannot override authentication headers."]}),"\n"]}),"\n",(0,a.jsxs)(n.li,{children:["\n",(0,a.jsxs)(n.p,{children:[(0,a.jsx)(n.strong,{children:"For custom authentication"}),": If you need custom authentication logic, omit the ",(0,a.jsx)(n.code,{children:"authentication"})," configuration block and use ",(0,a.jsx)(n.code,{children:"task_headers"})," to set your custom authentication header directly."]}),"\n"]}),"\n"]}),"\n",(0,a.jsx)(n.h3,{id:"use-cases",children:"Use Cases"}),"\n",(0,a.jsxs)(n.p,{children:[(0,a.jsx)(n.strong,{children:"API Versioning"}),": Specify the API version your integration requires:"]}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-yaml",children:'agent_card_headers:\n  - name: "X-API-Version"\n    value: "v2"\ntask_headers:\n  - name: "X-API-Version"\n    value: "v2"\n'})}),"\n",(0,a.jsxs)(n.p,{children:[(0,a.jsx)(n.strong,{children:"Tenant Identification"}),": Pass tenant or organization identifiers:"]}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-yaml",children:'task_headers:\n  - name: "X-Tenant-ID"\n    value: "${TENANT_ID}"\n  - name: "X-Organization"\n    value: "acme-corp"\n'})}),"\n",(0,a.jsxs)(n.p,{children:[(0,a.jsx)(n.strong,{children:"Custom Authentication"}),": If you need custom authentication, omit the ",(0,a.jsx)(n.code,{children:"authentication"})," block and use headers directly:"]}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-yaml",children:'# Note: Do NOT configure the \'authentication\' block if using custom auth headers\ntask_headers:\n  - name: "Authorization"\n    value: "Bearer ${CUSTOM_AUTH_TOKEN}"\n  # Or use a custom auth scheme:\n  - name: "X-Custom-Auth"\n    value: "${CUSTOM_AUTH_TOKEN}"\n'})}),"\n",(0,a.jsxs)(n.p,{children:[(0,a.jsx)(n.strong,{children:"Request Metadata"}),": Add metadata for tracking or routing:"]}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-yaml",children:'task_headers:\n  - name: "X-Request-Source"\n    value: "agent-mesh"\n  - name: "X-Request-Priority"\n    value: "high"\n'})}),"\n",(0,a.jsx)(n.h2,{id:"artifact-handling",children:"Artifact Handling"}),"\n",(0,a.jsx)(n.p,{children:"The proxy manages artifact flow in both directions to ensure seamless integration between Agent Mesh and external agents."}),"\n",(0,a.jsx)(n.h3,{id:"request-flow-agent-mesh-to-external-agent",children:"Request Flow: Agent Mesh to External Agent"}),"\n",(0,a.jsx)(n.p,{children:"When it forwards requests to external agents, the proxy resolves artifact URIs to byte content using the following sequence of operations:"}),"\n",(0,a.jsxs)(n.ol,{children:["\n",(0,a.jsxs)(n.li,{children:["The proxy receives an A2A request containing artifact references (for example, ",(0,a.jsx)(n.code,{children:"artifact://app/user/session/data.csv?version=1"}),")."]}),"\n",(0,a.jsx)(n.li,{children:"The proxy loads the artifact content from Agent Mesh's artifact service."}),"\n",(0,a.jsx)(n.li,{children:"The proxy replaces the URI with the actual byte content in the request."}),"\n",(0,a.jsx)(n.li,{children:"The proxy forwards the modified request to the external agent."}),"\n"]}),"\n",(0,a.jsx)(n.p,{children:"This process ensures that external agents receive complete artifact data without needing access to Agent Mesh's artifact service."}),"\n",(0,a.jsx)(n.h3,{id:"response-flow-external-agent-to-agent-mesh",children:"Response Flow: External Agent to Agent Mesh"}),"\n",(0,a.jsx)(n.p,{children:"When it receives responses from external agents, the proxy saves artifacts to Agent Mesh as follows:"}),"\n",(0,a.jsxs)(n.ol,{children:["\n",(0,a.jsx)(n.li,{children:"The external agent returns artifacts with byte content in the response."}),"\n",(0,a.jsx)(n.li,{children:"The proxy saves each artifact to Agent Mesh's artifact service."}),"\n",(0,a.jsx)(n.li,{children:"The proxy replaces the byte content with an artifact URI."}),"\n",(0,a.jsx)(n.li,{children:"The proxy publishes the modified response to Agent Mesh."}),"\n"]}),"\n",(0,a.jsx)(n.p,{children:"This process ensures that artifacts are stored centrally and can be accessed by other agents in Agent Mesh."}),"\n",(0,a.jsx)(n.h3,{id:"artifact-metadata",children:"Artifact Metadata"}),"\n",(0,a.jsx)(n.p,{children:"The proxy automatically generates metadata for saved artifacts, including:"}),"\n",(0,a.jsxs)(n.ul,{children:["\n",(0,a.jsxs)(n.li,{children:[(0,a.jsx)(n.code,{children:"proxied_from_artifact_id"}),": The original artifact ID from the external agent"]}),"\n",(0,a.jsxs)(n.li,{children:[(0,a.jsx)(n.code,{children:"description"}),": Extracted from the artifact or generated from context"]}),"\n",(0,a.jsxs)(n.li,{children:[(0,a.jsx)(n.code,{children:"produced_artifacts"}),": A manifest of all artifacts created during task execution"]}),"\n"]}),"\n",(0,a.jsx)(n.h2,{id:"status-update-conversion",children:"Status Update Conversion"}),"\n",(0,a.jsx)(n.p,{children:"The proxy can automatically convert text-based status updates from external A2A agents to match the native SAM agent format, ensuring consistent UI behavior across all agents in your mesh."}),"\n",(0,a.jsx)(n.h3,{id:"conversion-scope",children:"Conversion Scope"}),"\n",(0,a.jsxs)(n.p,{children:["The ",(0,a.jsx)(n.code,{children:"convert_progress_updates"})," setting only affects intermediate status updates:"]}),"\n",(0,a.jsxs)(n.ul,{children:["\n",(0,a.jsxs)(n.li,{children:[(0,a.jsx)(n.strong,{children:"Applies to"}),": ",(0,a.jsx)(n.code,{children:"TaskStatusUpdateEvent"})," messages (streaming progress updates)"]}),"\n",(0,a.jsxs)(n.li,{children:[(0,a.jsx)(n.strong,{children:"Does not apply to"}),": Final ",(0,a.jsx)(n.code,{children:"Task"})," responses, artifact content, or other message types"]}),"\n"]}),"\n",(0,a.jsx)(n.p,{children:"This means that final responses from external agents remain as text parts, preserving the agent's intended final output format."}),"\n",(0,a.jsx)(n.h3,{id:"when-to-disable",children:"When to Disable"}),"\n",(0,a.jsxs)(n.p,{children:["Set ",(0,a.jsx)(n.code,{children:"convert_progress_updates: false"})," if:"]}),"\n",(0,a.jsxs)(n.ul,{children:["\n",(0,a.jsx)(n.li,{children:"The external agent sends structured status updates that should be preserved exactly as-is"}),"\n",(0,a.jsx)(n.li,{children:"You have custom UI handling for text-based status updates"}),"\n",(0,a.jsx)(n.li,{children:"You need to preserve original TextParts for debugging or custom processing"}),"\n",(0,a.jsx)(n.li,{children:"The external agent already sends progress updates as DataParts"}),"\n"]}),"\n",(0,a.jsx)(n.p,{children:"Example configuration with conversion disabled:"}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-yaml",children:'proxied_agents:\n  - name: "legacy-agent"\n    url: "https://legacy.example.com/agent"\n    convert_progress_updates: false  # Preserve original text parts\n'})}),"\n",(0,a.jsx)(n.p,{children:"When disabled, all status update content passes through unchanged, allowing you to implement custom handling in your gateway or UI layer."}),"\n",(0,a.jsx)(n.h2,{id:"discovery-and-health",children:"Discovery and Health"}),"\n",(0,a.jsx)(n.p,{children:"The proxy maintains agent discovery and health monitoring through periodic agent card fetching."}),"\n",(0,a.jsx)(n.h3,{id:"initial-discovery",children:"Initial Discovery"}),"\n",(0,a.jsx)(n.p,{children:"When the proxy starts, it performs synchronous discovery of all configured agents by:"}),"\n",(0,a.jsxs)(n.ol,{children:["\n",(0,a.jsxs)(n.li,{children:["Fetching agent cards from each external agent's ",(0,a.jsx)(n.code,{children:"/.well-known/agent-card.json"})," endpoint."]}),"\n",(0,a.jsx)(n.li,{children:"Updating the local agent registry with agent capabilities."}),"\n",(0,a.jsx)(n.li,{children:"Publishing agent cards to the Agent Mesh discovery topic."}),"\n"]}),"\n",(0,a.jsx)(n.p,{children:"This process ensures that external agents are immediately discoverable when the proxy starts."}),"\n",(0,a.jsx)(n.h3,{id:"periodic-refresh",children:"Periodic Refresh"}),"\n",(0,a.jsxs)(n.p,{children:["The proxy periodically refreshes agent cards based on the configured ",(0,a.jsx)(n.code,{children:"discovery_interval_seconds"}),". When the configured interval elapses, the proxy fetches updated agent cards from external agents, updates the local registry with any changes, and then publishes the updated cards to Agent Mesh. This process ensures that Agent Mesh has current information about external agent capabilities and availability."]}),"\n",(0,a.jsx)(n.h3,{id:"agent-card-transformation",children:"Agent Card Transformation"}),"\n",(0,a.jsx)(n.p,{children:"The proxy transforms agent cards to make external agents appear as native Agent Mesh agents:"}),"\n",(0,a.jsxs)(n.ul,{children:["\n",(0,a.jsxs)(n.li,{children:["The ",(0,a.jsx)(n.code,{children:"name"})," field is set to the configured alias (the name you specify in ",(0,a.jsx)(n.code,{children:"proxied_agents"}),")."]}),"\n",(0,a.jsxs)(n.li,{children:["The ",(0,a.jsx)(n.code,{children:"url"})," field is rewritten to use the Solace topic format (for example, ",(0,a.jsx)(n.code,{children:"solace:myorg/production/agent/external-data-agent"}),")."]}),"\n"]}),"\n",(0,a.jsx)(n.p,{children:"These agent cards allow other agents to interact with external agents using the standard A2A protocol over Solace event mesh, without knowing they are proxied."}),"\n",(0,a.jsx)(n.h3,{id:"url-behavior",children:"URL Behavior"}),"\n",(0,a.jsx)(n.p,{children:"The proxy handles URLs in two contexts:"}),"\n",(0,a.jsxs)(n.ol,{children:["\n",(0,a.jsxs)(n.li,{children:["\n",(0,a.jsxs)(n.p,{children:[(0,a.jsx)(n.strong,{children:"Agent Card Fetching"}),": Always uses the configured URL in the ",(0,a.jsx)(n.code,{children:"proxied_agents"})," list to fetch the agent card from the external agent's ",(0,a.jsx)(n.code,{children:"/.well-known/agent-card.json"})," endpoint."]}),"\n"]}),"\n",(0,a.jsxs)(n.li,{children:["\n",(0,a.jsxs)(n.p,{children:[(0,a.jsx)(n.strong,{children:"Task Invocations"}),": By default, uses the URL specified in the agent card returned by the external agent. This allows external agents to advertise their preferred endpoint (which may differ from the agent card endpoint). You can override this behavior by setting ",(0,a.jsx)(n.code,{children:"use_agent_card_url: false"})," to always use the configured URL for both agent card fetching and task invocations."]}),"\n"]}),"\n"]}),"\n",(0,a.jsx)(n.h2,{id:"task-lifecycle-management",children:"Task Lifecycle Management"}),"\n",(0,a.jsx)(n.p,{children:"The proxy tracks active tasks and manages their lifecycle from initiation to completion."}),"\n",(0,a.jsx)(n.h3,{id:"task-initiation",children:"Task Initiation"}),"\n",(0,a.jsx)(n.p,{children:"When a request arrives from Agent Mesh, the proxy:"}),"\n",(0,a.jsxs)(n.ol,{children:["\n",(0,a.jsx)(n.li,{children:"Creates a task context to track the task's state."}),"\n",(0,a.jsx)(n.li,{children:"Resolves inbound artifacts."}),"\n",(0,a.jsx)(n.li,{children:"Forwards the request to the external agent."}),"\n",(0,a.jsx)(n.li,{children:"Begins streaming responses back to Agent Mesh."}),"\n"]}),"\n",(0,a.jsx)(n.h3,{id:"task-cancellation",children:"Task Cancellation"}),"\n",(0,a.jsx)(n.p,{children:"When a cancellation request arrives, the proxy:"}),"\n",(0,a.jsxs)(n.ol,{children:["\n",(0,a.jsx)(n.li,{children:"Looks up the active task context."}),"\n",(0,a.jsx)(n.li,{children:"Forwards the cancellation request to the external agent."}),"\n",(0,a.jsx)(n.li,{children:"Publishes the cancellation response to Agent Mesh."}),"\n"]}),"\n",(0,a.jsx)(n.h3,{id:"task-completion",children:"Task Completion"}),"\n",(0,a.jsx)(n.p,{children:"When a task completes, the proxy:"}),"\n",(0,a.jsxs)(n.ol,{children:["\n",(0,a.jsx)(n.li,{children:"Processes any final artifacts."}),"\n",(0,a.jsx)(n.li,{children:"Publishes the final task response to Agent Mesh."}),"\n",(0,a.jsx)(n.li,{children:"Removes the task context from active tracking."}),"\n"]}),"\n",(0,a.jsx)(n.h2,{id:"error-handling-and-retry-logic",children:"Error Handling and Retry Logic"}),"\n",(0,a.jsx)(n.p,{children:"The proxy implements robust error handling and automatic retry logic for authentication failures."}),"\n",(0,a.jsx)(n.h3,{id:"oauth-20-automatic-retry",children:"OAuth 2.0 Automatic Retry"}),"\n",(0,a.jsx)(n.p,{children:"When using OAuth 2.0 authentication, the proxy automatically handles token expiration using the following sequence:"}),"\n",(0,a.jsxs)(n.ol,{children:["\n",(0,a.jsx)(n.li,{children:"A request receives a 401 Unauthorized response from the external agent."}),"\n",(0,a.jsx)(n.li,{children:"The proxy invalidates the cached token."}),"\n",(0,a.jsx)(n.li,{children:"The proxy removes all cached clients for the agent/session."}),"\n",(0,a.jsx)(n.li,{children:"The proxy fetches a fresh token from the OAuth provider."}),"\n",(0,a.jsx)(n.li,{children:"The proxy retries the request once with the new token."}),"\n"]}),"\n",(0,a.jsx)(n.p,{children:"This sequence ensures seamless operation even when tokens expire during long-running tasks."}),"\n",(0,a.jsx)(n.h3,{id:"connection-errors",children:"Connection Errors"}),"\n",(0,a.jsx)(n.p,{children:"The proxy provides clear error messages for connection failures:"}),"\n",(0,a.jsxs)(n.ul,{children:["\n",(0,a.jsx)(n.li,{children:"Connection refused or agent unreachable"}),"\n",(0,a.jsx)(n.li,{children:"Timeout errors with configurable timeout values"}),"\n",(0,a.jsx)(n.li,{children:"JSON-RPC protocol errors from external agents"}),"\n"]}),"\n",(0,a.jsx)(n.h3,{id:"error-responses",children:"Error Responses"}),"\n",(0,a.jsx)(n.p,{children:"When errors occur, the proxy publishes standard A2A error responses to Agent Mesh, including:"}),"\n",(0,a.jsxs)(n.ul,{children:["\n",(0,a.jsxs)(n.li,{children:[(0,a.jsx)(n.code,{children:"InternalError"}),": For unexpected proxy errors"]}),"\n",(0,a.jsxs)(n.li,{children:[(0,a.jsx)(n.code,{children:"InvalidRequestError"}),": For malformed requests"]}),"\n",(0,a.jsxs)(n.li,{children:[(0,a.jsx)(n.code,{children:"TaskNotFoundError"}),": For cancellation requests on unknown tasks"]}),"\n"]}),"\n",(0,a.jsx)(n.h2,{id:"creating-a-proxy",children:"Creating a Proxy"}),"\n",(0,a.jsx)(n.p,{children:"Proxies are configured using standard YAML configuration files, similar to agents and gateways."}),"\n",(0,a.jsx)(n.h3,{id:"creating-the-configuration-file",children:"Creating the Configuration File"}),"\n",(0,a.jsxs)(n.p,{children:["Create a new YAML file in your ",(0,a.jsx)(n.code,{children:"configs"})," directory (for example, ",(0,a.jsx)(n.code,{children:"configs/my-proxy.yaml"}),"):"]}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-yaml",children:'log:\n  stdout_log_level: INFO\n  log_file_level: DEBUG\n  log_file: my-proxy.log\n\n# Include shared configuration (broker connection, etc.)\n!include shared_config.yaml\n\napps:\n  - name: my_a2a_proxy\n    app_module: solace_agent_mesh.agent.proxies.a2a.app\n    broker:\n      <<: *broker_connection\n\n    app_config:\n      namespace: "${NAMESPACE}"\n      \n      artifact_service:\n        type: "filesystem"\n        base_path: "/tmp/proxy-artifacts"\n        artifact_scope: "namespace"\n      \n      discovery_interval_seconds: 60\n      default_request_timeout_seconds: 300\n      \n      proxied_agents:\n        - name: "external-agent-1"\n          url: "https://api.example.com/agent"\n          request_timeout_seconds: 120\n          authentication:\n            type: "static_bearer"\n            token: "${AGENT_TOKEN}"\n'})}),"\n",(0,a.jsxs)(n.p,{children:["You can use the example file at ",(0,a.jsx)(n.code,{children:"examples/a2a_proxy.yaml"})," as a template."]}),"\n",(0,a.jsx)(n.h3,{id:"running-the-proxy",children:"Running the Proxy"}),"\n",(0,a.jsx)(n.p,{children:"Run the proxy along with your other Agent Mesh components:"}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-bash",children:"sam run\n"})}),"\n",(0,a.jsx)(n.p,{children:"The proxy automatically subscribes to the appropriate Solace topics and begins proxying requests to external agents."}),"\n",(0,a.jsx)(n.h3,{id:"multiple-proxy-configurations",children:"Multiple Proxy Configurations"}),"\n",(0,a.jsx)(n.p,{children:"While a single proxy can manage multiple external agents, you may want to create separate proxy configurations to:"}),"\n",(0,a.jsxs)(n.ul,{children:["\n",(0,a.jsx)(n.li,{children:"Organize agents by domain or team"}),"\n",(0,a.jsx)(n.li,{children:"Isolate agents with different security requirements"}),"\n",(0,a.jsx)(n.li,{children:"Distribute load across multiple proxy instances"}),"\n"]}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-bash",children:"configs/\n\u251c\u2500\u2500 data-agents-proxy.yaml      # Proxies 3 data-related agents\n\u251c\u2500\u2500 analytics-agents-proxy.yaml # Proxies 2 analytics agents\n\u2514\u2500\u2500 third-party-agents-proxy.yaml # Proxies external vendor agents\n"})}),"\n",(0,a.jsx)(n.p,{children:"Run all proxies together:"}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-bash",children:"sam run\n"})}),"\n",(0,a.jsx)(n.p,{children:"Or run specific proxy configurations:"}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-bash",children:"sam run configs/data-agents-proxy.yaml\n"})}),"\n",(0,a.jsx)(n.h2,{id:"advanced-configuration",children:"Advanced Configuration"}),"\n",(0,a.jsx)(n.h3,{id:"per-agent-timeout-override",children:"Per-Agent Timeout Override"}),"\n",(0,a.jsx)(n.p,{children:"You can override the default timeout for specific agents:"}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-yaml",children:'proxied_agents:\n  - name: "slow-agent"\n    url: "https://slow.example.com/agent"\n    request_timeout_seconds: 600  # 10 minutes\n'})}),"\n",(0,a.jsx)(n.h3,{id:"custom-headers-with-authentication",children:"Custom Headers with Authentication"}),"\n",(0,a.jsx)(n.p,{children:"Combine authentication with custom headers for complex integration requirements:"}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-yaml",children:'proxied_agents:\n  - name: "enterprise-agent"\n    url: "https://enterprise.example.com/agent"\n    authentication:\n      type: "oauth2_client_credentials"\n      token_url: "https://auth.example.com/oauth/token"\n      client_id: "${OAUTH_CLIENT_ID}"\n      client_secret: "${OAUTH_CLIENT_SECRET}"\n    use_auth_for_agent_card: true  # Apply OAuth to agent card fetching\n    agent_card_headers:\n      - name: "X-API-Version"\n        value: "v2"\n      - name: "X-Client-Type"\n        value: "agent-mesh"\n    task_headers:\n      - name: "X-API-Version"\n        value: "v2"\n      - name: "X-Tenant-ID"\n        value: "${TENANT_ID}"\n      - name: "X-Request-Priority"\n        value: "high"\n'})}),"\n",(0,a.jsx)(n.h3,{id:"url-override-for-task-invocations",children:"URL Override for Task Invocations"}),"\n",(0,a.jsxs)(n.p,{children:["By default, the proxy uses the URL from the agent card for task invocations. This allows external agents to specify their preferred endpoint. However, you can override this behavior by setting ",(0,a.jsx)(n.code,{children:"use_agent_card_url: false"}),":"]}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-yaml",children:'proxied_agents:\n  - name: "fixed-url-agent"\n    url: "https://api.example.com/agent"\n    use_agent_card_url: false  # Always use the configured URL\n    authentication:\n      type: "static_bearer"\n      token: "${AGENT_TOKEN}"\n'})}),"\n",(0,a.jsx)(n.p,{children:(0,a.jsx)(n.strong,{children:"Important notes:"})}),"\n",(0,a.jsxs)(n.ul,{children:["\n",(0,a.jsx)(n.li,{children:"The configured URL is always used to fetch the agent card, regardless of this setting"}),"\n",(0,a.jsxs)(n.li,{children:["When ",(0,a.jsx)(n.code,{children:"use_agent_card_url: false"}),", all task invocations use the configured URL"]}),"\n",(0,a.jsxs)(n.li,{children:["When ",(0,a.jsx)(n.code,{children:"use_agent_card_url: true"})," (default), the agent card's URL is used for tasks"]}),"\n"]}),"\n",(0,a.jsx)(n.h3,{id:"custom-artifact-service-scope",children:"Custom Artifact Service Scope"}),"\n",(0,a.jsx)(n.p,{children:"Configure artifact storage scope for the proxy:"}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-yaml",children:'artifact_service:\n  type: "filesystem"\n  base_path: "/data/proxy-artifacts"\n  artifact_scope: "namespace"  # Options: namespace, app, custom\n'})}),"\n",(0,a.jsx)(n.h3,{id:"multiple-proxies",children:"Multiple Proxies"}),"\n",(0,a.jsx)(n.p,{children:"You can run multiple proxy instances to distribute load or isolate different sets of external agents. Each proxy instance can manage multiple agents:"}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-yaml",children:'# data-agents-proxy.yaml\napp:\n  name: data-agents-proxy\n  app_config:\n    proxied_agents:\n      - name: "data-agent-1"\n        url: "https://data1.example.com/agent"\n      - name: "data-agent-2"\n        url: "https://data2.example.com/agent"\n      - name: "data-agent-3"\n        url: "https://data3.example.com/agent"\n\n# analytics-agents-proxy.yaml\napp:\n  name: analytics-agents-proxy\n  app_config:\n    proxied_agents:\n      - name: "analytics-agent-1"\n        url: "https://analytics1.example.com/agent"\n      - name: "analytics-agent-2"\n        url: "https://analytics2.example.com/agent"\n'})}),"\n",(0,a.jsx)(n.h2,{id:"troubleshooting",children:"Troubleshooting"}),"\n",(0,a.jsx)(n.h3,{id:"agent-not-discoverable",children:"Agent Not Discoverable"}),"\n",(0,a.jsx)(n.p,{children:"If an external agent does not appear in Agent Mesh:"}),"\n",(0,a.jsxs)(n.ol,{children:["\n",(0,a.jsx)(n.li,{children:"Check that the agent's URL is accessible from the proxy."}),"\n",(0,a.jsxs)(n.li,{children:["Verify that the agent exposes ",(0,a.jsx)(n.code,{children:"/.well-known/agent-card.json"}),"."]}),"\n",(0,a.jsx)(n.li,{children:"Check the proxy logs for discovery errors."}),"\n",(0,a.jsxs)(n.li,{children:["Ensure that ",(0,a.jsx)(n.code,{children:"discovery_interval_seconds"})," is set appropriately and is more frequent than the ",(0,a.jsx)(n.code,{children:"health_check_ttl_seconds"})," that is set on the calling agents and gateways."]}),"\n"]}),"\n",(0,a.jsx)(n.h3,{id:"authentication-failures",children:"Authentication Failures"}),"\n",(0,a.jsx)(n.p,{children:"If requests fail with 401 errors:"}),"\n",(0,a.jsxs)(n.ol,{children:["\n",(0,a.jsx)(n.li,{children:"Verify that the credentials are correctly set in environment variables."}),"\n",(0,a.jsxs)(n.li,{children:["For OAuth 2.0, check that ",(0,a.jsx)(n.code,{children:"token_url"}),", ",(0,a.jsx)(n.code,{children:"client_id"}),", and ",(0,a.jsx)(n.code,{children:"client_secret"})," are correct."]}),"\n",(0,a.jsx)(n.li,{children:"Ensure that the OAuth token URL uses HTTPS (required for security)."}),"\n",(0,a.jsx)(n.li,{children:"Check the proxy logs for token acquisition errors."}),"\n"]}),"\n",(0,a.jsx)(n.h3,{id:"timeout-errors",children:"Timeout Errors"}),"\n",(0,a.jsx)(n.p,{children:"If requests timeout:"}),"\n",(0,a.jsxs)(n.ol,{children:["\n",(0,a.jsxs)(n.li,{children:["Increase ",(0,a.jsx)(n.code,{children:"request_timeout_seconds"})," for slow agents."]}),"\n",(0,a.jsx)(n.li,{children:"Check the network connectivity between the proxy and the external agent."}),"\n",(0,a.jsx)(n.li,{children:"Verify that the external agent is responding within the timeout period."}),"\n"]}),"\n",(0,a.jsx)(n.h3,{id:"artifact-issues",children:"Artifact Issues"}),"\n",(0,a.jsx)(n.p,{children:"If artifacts are not flowing correctly:"}),"\n",(0,a.jsxs)(n.ol,{children:["\n",(0,a.jsx)(n.li,{children:"Verify that the artifact service is properly configured."}),"\n",(0,a.jsx)(n.li,{children:"Check that the proxy has write permissions to the artifact storage location."}),"\n",(0,a.jsx)(n.li,{children:"Ensure that the artifact URIs are correctly formatted."}),"\n",(0,a.jsx)(n.li,{children:"Check the proxy logs for artifact save/load errors."}),"\n"]}),"\n",(0,a.jsxs)(n.h3,{id:"issues-running-a2a-samples-with-containerfile",children:["Issues Running A2A Samples with ",(0,a.jsx)(n.code,{children:"Containerfile"})]}),"\n",(0,a.jsxs)(n.p,{children:["If you encounter a ",(0,a.jsx)(n.code,{children:"ValueError: Invalid context_id: ... is not a valid UUID."})," when running A2A samples using a ",(0,a.jsx)(n.code,{children:"Containerfile"}),", it may be due to outdated dependencies in the ",(0,a.jsx)(n.code,{children:"uv.lock"})," file. This can happen if the sample is pinned to an older version of the ",(0,a.jsx)(n.code,{children:"a2a-sdk"})," package. For more details, see ",(0,a.jsx)(n.a,{href:"https://github.com/a2aproject/a2a-samples/issues/399",children:"this GitHub issue"}),"."]}),"\n",(0,a.jsx)(n.p,{children:"To resolve this, navigate to the sample's directory and upgrade the dependencies:"}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-bash",children:"uv lock --upgrade\n"})}),"\n",(0,a.jsxs)(n.p,{children:["This will update the ",(0,a.jsx)(n.code,{children:"uv.lock"})," file to use the latest version of ",(0,a.jsx)(n.code,{children:"a2a-sdk"}),", which includes the necessary bug fixes."]})]})}function h(e={}){const{wrapper:n}={...(0,r.R)(),...e.components};return n?(0,a.jsx)(n,{...e,children:(0,a.jsx)(d,{...e})}):d(e)}},8453:(e,n,t)=>{t.d(n,{R:()=>i,x:()=>o});var s=t(6540);const a={},r=s.createContext(a);function i(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(a):e.components||a:i(e.components),s.createElement(r.Provider,{value:n},e.children)}}}]);

solace_agent_mesh/assets/docs/assets/js/94e8668d.16083b3f.js

@@ -0,0 +1 @@
+"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[8627],{5483:(e,n,i)=>{i.r(n),i.d(n,{assets:()=>c,contentTitle:()=>a,default:()=>h,frontMatter:()=>o,metadata:()=>s,toc:()=>l});const s=JSON.parse('{"id":"documentation/enterprise/rbac-setup-guide","title":"Setting Up RBAC","description":"Agent Mesh Enterprise now uses secure-by-default authorization. If you do not configure an authorization service, the system will deny all access by default. You must explicitly configure RBAC or another authorization type to grant access to users.","source":"@site/docs/documentation/enterprise/rbac-setup-guide.md","sourceDirName":"documentation/enterprise","slug":"/documentation/enterprise/rbac-setup-guide","permalink":"/solace-agent-mesh/docs/documentation/enterprise/rbac-setup-guide","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/enterprise/rbac-setup-guide.md","tags":[],"version":"current","sidebarPosition":10,"frontMatter":{"title":"Setting Up RBAC","sidebar_position":10},"sidebar":"docSidebar","previous":{"title":"Connectors","permalink":"/solace-agent-mesh/docs/documentation/enterprise/connectors/"},"next":{"title":"Enabling SSO","permalink":"/solace-agent-mesh/docs/documentation/enterprise/single-sign-on"}}');var r=i(4848),t=i(8453);const o={title:"Setting Up RBAC",sidebar_position:10},a=void 0,c={},l=[{value:"Table of Contents",id:"table-of-contents",level:2},{value:"Understanding RBAC in Agent Mesh Enterprise",id:"understanding-rbac-in-agent-mesh-enterprise",level:2},{value:"Authorization Types",id:"authorization-types",level:3},{value:"The Three Components",id:"the-three-components",level:3},{value:"How Authorization Works",id:"how-authorization-works",level:3},{value:"Planning Your RBAC Configuration",id:"planning-your-rbac-configuration",level:2},{value:"Identifying User Types",id:"identifying-user-types",level:3},{value:"Designing Roles",id:"designing-roles",level:3},{value:"Mapping Scopes to Features",id:"mapping-scopes-to-features",level:3},{value:"Setting Up RBAC in Docker",id:"setting-up-rbac-in-docker",level:2},{value:"Prerequisites",id:"prerequisites",level:3},{value:"Creating the Configuration Directory Structure",id:"creating-the-configuration-directory-structure",level:3},{value:"Defining Roles and Permissions",id:"defining-roles-and-permissions",level:3},{value:"Assigning Users to Roles",id:"assigning-users-to-roles",level:3},{value:"Creating the Enterprise Configuration",id:"creating-the-enterprise-configuration",level:3},{value:"Alternative: Development Mode (Permissive)",id:"alternative-development-mode-permissive",level:4},{value:"Default Behavior (No Configuration)",id:"default-behavior-no-configuration",level:4},{value:"Running the Docker Container",id:"running-the-docker-container",level:3},{value:"Verifying Your Configuration",id:"verifying-your-configuration",level:3},{value:"Understanding Configuration Files",id:"understanding-configuration-files",level:2},{value:"Role-to-Scope Definitions Structure",id:"role-to-scope-definitions-structure",level:3},{value:"User-to-Role Assignments Structure",id:"user-to-role-assignments-structure",level:3},{value:"Enterprise Configuration Structure",id:"enterprise-configuration-structure",level:3},{value:"Advanced Configuration Options",id:"advanced-configuration-options",level:2},{value:"Production-Ready Role Configuration",id:"production-ready-role-configuration",level:3},{value:"Integrating with Microsoft Graph",id:"integrating-with-microsoft-graph",level:3},{value:"Best Practices",id:"best-practices",level:2},{value:"Security Recommendations",id:"security-recommendations",level:3},{value:"Role Design Principles",id:"role-design-principles",level:3},{value:"Docker-Specific Recommendations",id:"docker-specific-recommendations",level:3},{value:"Troubleshooting",id:"troubleshooting",level:2},{value:"Authorization Denied for Valid User",id:"authorization-denied-for-valid-user",level:3},{value:"Configuration Files Not Found",id:"configuration-files-not-found",level:3},{value:"Microsoft Graph Integration Not Working",id:"microsoft-graph-integration-not-working",level:3},{value:"Debugging Authorization Issues",id:"debugging-authorization-issues",level:3},{value:"Getting Help",id:"getting-help",level:3},{value:"Conclusion",id:"conclusion",level:2}];function d(e){const n={a:"a",admonition:"admonition",code:"code",h2:"h2",h3:"h3",h4:"h4",li:"li",ol:"ol",p:"p",pre:"pre",strong:"strong",ul:"ul",...(0,t.R)(),...e.components};return(0,r.jsxs)(r.Fragment,{children:[(0,r.jsx)(n.admonition,{title:"Security Notice",type:"warning",children:(0,r.jsxs)(n.p,{children:[(0,r.jsx)(n.strong,{children:"Agent Mesh Enterprise now uses secure-by-default authorization."})," If you do not configure an authorization service, the system will ",(0,r.jsx)(n.strong,{children:"deny all access"})," by default. You must explicitly configure RBAC or another authorization type to grant access to users."]})}),"\n",(0,r.jsx)(n.p,{children:"This guide walks you through configuring Role-Based Access Control (RBAC) in a Docker installation for Agent Mesh. You will learn how to control access to Agent Mesh Enterprise features and resources based on user roles and permissions."}),"\n",(0,r.jsx)(n.h2,{id:"table-of-contents",children:"Table of Contents"}),"\n",(0,r.jsxs)(n.ul,{children:["\n",(0,r.jsx)(n.li,{children:(0,r.jsx)(n.a,{href:"#understanding-rbac-in-agent-mesh-enterprise",children:"Understanding RBAC in Agent Mesh Enterprise"})}),"\n",(0,r.jsx)(n.li,{children:(0,r.jsx)(n.a,{href:"#planning-your-rbac-configuration",children:"Planning Your RBAC Configuration"})}),"\n",(0,r.jsx)(n.li,{children:(0,r.jsx)(n.a,{href:"#setting-up-rbac-in-docker",children:"Setting Up RBAC in Docker"})}),"\n",(0,r.jsx)(n.li,{children:(0,r.jsx)(n.a,{href:"#understanding-configuration-files",children:"Understanding Configuration Files"})}),"\n",(0,r.jsx)(n.li,{children:(0,r.jsx)(n.a,{href:"#advanced-configuration-options",children:"Advanced Configuration Options"})}),"\n",(0,r.jsx)(n.li,{children:(0,r.jsx)(n.a,{href:"#best-practices",children:"Best Practices"})}),"\n",(0,r.jsx)(n.li,{children:(0,r.jsx)(n.a,{href:"#troubleshooting",children:"Troubleshooting"})}),"\n"]}),"\n",(0,r.jsx)(n.h2,{id:"understanding-rbac-in-agent-mesh-enterprise",children:"Understanding RBAC in Agent Mesh Enterprise"}),"\n",(0,r.jsx)(n.p,{children:"Before you configure RBAC, you need to understand how the system works. Agent Mesh Enterprise uses a three-tier authorization model that separates identity, roles, and permissions."}),"\n",(0,r.jsx)(n.h3,{id:"authorization-types",children:"Authorization Types"}),"\n",(0,r.jsx)(n.p,{children:"Agent Mesh Enterprise supports multiple authorization types, each suited for different use cases:"}),"\n",(0,r.jsxs)(n.p,{children:[(0,r.jsxs)(n.strong,{children:[(0,r.jsx)(n.code,{children:"deny_all"})," (Default)"]})," - The secure default that denies all access. This type is automatically used when:"]}),"\n",(0,r.jsxs)(n.ul,{children:["\n",(0,r.jsxs)(n.li,{children:["No ",(0,r.jsx)(n.code,{children:"authorization_service"})," configuration block is present"]}),"\n",(0,r.jsxs)(n.li,{children:["The ",(0,r.jsx)(n.code,{children:"authorization_service"})," block is empty"]}),"\n",(0,r.jsxs)(n.li,{children:["The ",(0,r.jsx)(n.code,{children:"type"})," field is explicitly set to ",(0,r.jsx)(n.code,{children:"deny_all"})]}),"\n"]}),"\n",(0,r.jsx)(n.p,{children:"When this type is active, all user requests are denied and logged with WARNING messages. This ensures maximum security by default."}),"\n",(0,r.jsxs)(n.p,{children:[(0,r.jsx)(n.strong,{children:(0,r.jsx)(n.code,{children:"default_rbac"})})," - Role-Based Access Control using configuration files. This type is the recommended type for production deployments where you need fine-grained control over user permissions. It requires both role definitions and user assignments files."]}),"\n",(0,r.jsxs)(n.p,{children:[(0,r.jsx)(n.strong,{children:(0,r.jsx)(n.code,{children:"custom"})})," - Custom authorization service implementation. Use this when you need to integrate with external authorization systems or implement custom authorization logic."]}),"\n",(0,r.jsxs)(n.p,{children:[(0,r.jsx)(n.strong,{children:(0,r.jsx)(n.code,{children:"none"})})," - Disables authorization entirely, granting wildcard ",(0,r.jsx)(n.code,{children:"*"})," scope to all users. This type must be explicitly configured and should ",(0,r.jsx)(n.strong,{children:"only be used in development environments"}),". The system logs prominent security warnings when this type is active."]}),"\n",(0,r.jsx)(n.admonition,{title:"Development Only",type:"danger",children:(0,r.jsxs)(n.p,{children:["The ",(0,r.jsx)(n.code,{children:"type: none"})," authorization configuration grants full access to all users and should ",(0,r.jsx)(n.strong,{children:"never"})," be used in production environments. It is intended only for local development and testing."]})}),"\n",(0,r.jsx)(n.h3,{id:"the-three-components",children:"The Three Components"}),"\n",(0,r.jsx)(n.p,{children:"RBAC in Agent Mesh Enterprise consists of three interconnected components:"}),"\n",(0,r.jsxs)(n.p,{children:[(0,r.jsx)(n.strong,{children:"Users"})," represent identities in your system. Each user has a unique identifier, typically an email address. When a user attempts to access a feature or resource, Agent Mesh Enterprise checks their assigned roles to determine what they can do."]}),"\n",(0,r.jsxs)(n.p,{children:[(0,r.jsx)(n.strong,{children:"Roles"}),' are collections of permissions that you assign to users. Instead of granting permissions directly to individual users, you create roles that represent job functions or responsibilities. For example, you might create a "data_analyst" role for users who need to work with data tools and artifacts. This approach simplifies administration because you can modify a role\'s permissions once and affect all users assigned to that role.']}),"\n",(0,r.jsxs)(n.p,{children:[(0,r.jsx)(n.strong,{children:"Scopes"})," are the actual permissions that grant access to specific features or resources. Each scope follows a pattern that identifies what it controls. For example, the scope ",(0,r.jsx)(n.code,{children:"tool:data:read"})," grants permission to read data tools, while ",(0,r.jsx)(n.code,{children:"artifact:create"})," allows creating artifacts. Scopes use wildcards to grant broader permissions. For example, the scope ",(0,r.jsx)(n.code,{children:"tool:data:*"})," grants all permissions for data tools."]}),"\n",(0,r.jsx)(n.h3,{id:"how-authorization-works",children:"How Authorization Works"}),"\n",(0,r.jsx)(n.p,{children:"When a user attempts an action in Agent Mesh Enterprise, the system follows this authorization flow:"}),"\n",(0,r.jsxs)(n.ol,{children:["\n",(0,r.jsx)(n.li,{children:"The system identifies the user based on their authentication credentials"}),"\n",(0,r.jsx)(n.li,{children:"It retrieves all roles assigned to that user"}),"\n",(0,r.jsx)(n.li,{children:"For each role, it collects all associated scopes (permissions)"}),"\n",(0,r.jsx)(n.li,{children:"It checks if any of the user's scopes match the permission required for the requested action"}),"\n",(0,r.jsx)(n.li,{children:"If a matching scope exists, the system allows the action; otherwise, it denies access"}),"\n"]}),"\n",(0,r.jsx)(n.p,{children:"This model implements the principle of least privilege: users receive only the permissions they need to perform their job functions."}),"\n",(0,r.jsx)(n.h2,{id:"planning-your-rbac-configuration",children:"Planning Your RBAC Configuration"}),"\n",(0,r.jsx)(n.p,{children:"Before you create configuration files, you should plan your RBAC structure. This planning phase helps you design a system that meets your organization's needs while remaining maintainable."}),"\n",(0,r.jsx)(n.h3,{id:"identifying-user-types",children:"Identifying User Types"}),"\n",(0,r.jsx)(n.p,{children:"Start by identifying the different types of users in your organization. Consider their job functions and what they need to accomplish with Agent Mesh Enterprise. Common user types include:"}),"\n",(0,r.jsx)(n.p,{children:"Administrators need full access to all features and resources. They manage the system, configure settings, and troubleshoot issues. You typically assign these users a role with wildcard permissions."}),"\n",(0,r.jsx)(n.p,{children:"Operators perform day-to-day tasks such as running tools, creating artifacts, and monitoring system activity. They need broad access to operational features but not administrative capabilities."}),"\n",(0,r.jsx)(n.p,{children:"Analysts work with data and reports. They need access to data tools, artifact creation, and monitoring capabilities, but they do not need access to system configuration or advanced tools."}),"\n",(0,r.jsx)(n.p,{children:"Viewers need read-only access to monitor system activity and view artifacts. They cannot create, modify, or delete resources."}),"\n",(0,r.jsx)(n.h3,{id:"designing-roles",children:"Designing Roles"}),"\n",(0,r.jsx)(n.p,{children:"Once you identify user types, design roles that match their needs. Each role should represent a specific job function and include only the scopes necessary for that function."}),"\n",(0,r.jsx)(n.p,{children:'Consider creating a role hierarchy where some roles inherit permissions from others. For example, an "operator" role might inherit all permissions from a "viewer" role and add additional capabilities. This approach reduces duplication and makes your configuration easier to maintain.'}),"\n",(0,r.jsx)(n.h3,{id:"mapping-scopes-to-features",children:"Mapping Scopes to Features"}),"\n",(0,r.jsx)(n.p,{children:"Understanding available scopes helps you design effective roles. Agent Mesh Enterprise uses a hierarchical scope naming convention:"}),"\n",(0,r.jsxs)(n.p,{children:["Tool scopes control access to tools and follow the pattern ",(0,r.jsx)(n.code,{children:"tool:<category>:<action>"}),". For example, ",(0,r.jsx)(n.code,{children:"tool:basic:read"})," grants permission to read basic tools, while ",(0,r.jsx)(n.code,{children:"tool:data:*"})," grants all permissions for data tools."]}),"\n",(0,r.jsxs)(n.p,{children:["Artifact scopes control access to artifacts (files and data created by the system) and use the pattern ",(0,r.jsx)(n.code,{children:"artifact:<action>"}),". Common artifact scopes include ",(0,r.jsx)(n.code,{children:"artifact:read"}),", ",(0,r.jsx)(n.code,{children:"artifact:create"}),", and ",(0,r.jsx)(n.code,{children:"artifact:delete"}),"."]}),"\n",(0,r.jsxs)(n.p,{children:["Monitoring scopes control access to system monitoring features and follow the pattern ",(0,r.jsx)(n.code,{children:"monitor/namespace/<namespace>:a2a_messages:subscribe"}),". These scopes allow users to observe message traffic in specific namespaces."]}),"\n",(0,r.jsxs)(n.p,{children:["The wildcard scope ",(0,r.jsx)(n.code,{children:"*"})," grants all permissions and should only be used for administrator roles."]}),"\n",(0,r.jsx)(n.h2,{id:"setting-up-rbac-in-docker",children:"Setting Up RBAC in Docker"}),"\n",(0,r.jsx)(n.p,{children:"Now that you understand RBAC concepts and have planned your configuration, you can set up RBAC in your Docker environment. This process involves creating configuration files, setting up the Docker container, and verifying that everything works correctly."}),"\n",(0,r.jsx)(n.h3,{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.jsx)(n.li,{children:"Docker installed and running on your system"}),"\n",(0,r.jsxs)(n.li,{children:["The Agent Mesh Enterprise Docker image (",(0,r.jsx)(n.code,{children:"solace-agent-mesh-enterprise"}),")"]}),"\n",(0,r.jsx)(n.li,{children:"A text editor for creating configuration files"}),"\n",(0,r.jsx)(n.li,{children:"Basic familiarity with YAML file format"}),"\n"]}),"\n",(0,r.jsx)(n.h3,{id:"creating-the-configuration-directory-structure",children:"Creating the Configuration Directory Structure"}),"\n",(0,r.jsx)(n.p,{children:"You need to create a directory structure on your host system to store RBAC configuration files. The Docker container will mount this directory to access your configurations."}),"\n",(0,r.jsx)(n.p,{children:"Create the directory structure as follows:"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-bash",children:"mkdir -p sam-enterprise/config/auth\n"})}),"\n",(0,r.jsxs)(n.p,{children:["This command creates a ",(0,r.jsx)(n.code,{children:"sam-enterprise"})," directory with a nested ",(0,r.jsx)(n.code,{children:"config/auth"})," subdirectory. The ",(0,r.jsx)(n.code,{children:"auth"})," subdirectory will contain your RBAC configuration files."]}),"\n",(0,r.jsx)(n.h3,{id:"defining-roles-and-permissions",children:"Defining Roles and Permissions"}),"\n",(0,r.jsxs)(n.p,{children:["Create a file named ",(0,r.jsx)(n.code,{children:"role-to-scope-definitions.yaml"})," in the ",(0,r.jsx)(n.code,{children:"sam-enterprise/config/auth"})," directory.\nThis file defines all roles in your system and the scopes (permissions) associated with each role."]}),"\n",(0,r.jsx)(n.p,{children:"Here is an example configuration that defines three roles:"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-yaml",children:'# role-to-scope-definitions.yaml\nroles:\n  enterprise_admin:\n    description: "Full access for enterprise administrators"\n    scopes:\n      - "*"  # Wildcard grants all permissions\n    \n  data_analyst:\n    description: "Data analysis and visualization specialist"\n    scopes:\n      - "tool:data:*"  # All data tools\n      - "artifact:read"\n      - "artifact:create"\n      - "monitor/namespace/*:a2a_messages:subscribe"  # Can monitor any namespace\n    \n  standard_user:\n    description: "Standard user with basic access"\n    scopes:\n      - "artifact:read"\n      - "tool:basic:read"\n      - "tool:basic:search"\n'})}),"\n",(0,r.jsx)(n.p,{children:"This configuration creates three distinct roles:"}),"\n",(0,r.jsxs)(n.p,{children:["The ",(0,r.jsx)(n.code,{children:"enterprise_admin"})," role receives the wildcard scope ",(0,r.jsx)(n.code,{children:"*"}),", which grants all permissions in the system. You should assign this role only to trusted administrators who need complete control over Agent Mesh Enterprise."]}),"\n",(0,r.jsxs)(n.p,{children:["The ",(0,r.jsx)(n.code,{children:"data_analyst"})," role receives permissions tailored for data analysis work. The scope ",(0,r.jsx)(n.code,{children:"tool:data:*"})," grants all permissions for data-related tools (read, write, execute). The ",(0,r.jsx)(n.code,{children:"artifact:read"})," and ",(0,r.jsx)(n.code,{children:"artifact:create"})," scopes allow analysts to view existing artifacts and create new ones. The monitoring scope ",(0,r.jsx)(n.code,{children:"monitor/namespace/*:a2a_messages:subscribe"})," enables analysts to observe message traffic across all namespaces, which helps them understand data flows."]}),"\n",(0,r.jsxs)(n.p,{children:["The ",(0,r.jsx)(n.code,{children:"standard_user"})," role provides minimal permissions for basic operations. Users with this role can read artifacts and perform basic tool operations but cannot create new artifacts or access advanced features."]}),"\n",(0,r.jsx)(n.h3,{id:"assigning-users-to-roles",children:"Assigning Users to Roles"}),"\n",(0,r.jsxs)(n.p,{children:["Create a file named ",(0,r.jsx)(n.code,{children:"user-to-role-assignments.yaml"})," in the ",(0,r.jsx)(n.code,{children:"sam-enterprise/config/auth"})," directory. This file maps user identities to roles."]}),"\n",(0,r.jsx)(n.p,{children:"Here is an example configuration:"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-yaml",children:'# user-to-role-assignments.yaml\nusers:\n  admin@example.com:\n    roles: ["enterprise_admin"]\n    description: "Enterprise Administrator Account"\n    \n  data.analyst@example.com:\n    roles: ["data_analyst"]\n    description: "Senior Data Analyst"\n    \n  user1@example.com:\n    roles: ["standard_user"]\n    description: "Standard Enterprise User"\n'})}),"\n",(0,r.jsx)(n.p,{children:"Each entry in this file maps a user identity (typically an email address) to one or more roles. The user identity must match exactly what your authentication system provides because Agent Mesh Enterprise performs case-sensitive matching."}),"\n",(0,r.jsxs)(n.p,{children:["You can assign multiple roles to a single user by listing them in the ",(0,r.jsx)(n.code,{children:"roles"})," array. When a user has multiple roles, they receive the combined permissions from all assigned roles. For example, if you assign both ",(0,r.jsx)(n.code,{children:"data_analyst"})," and ",(0,r.jsx)(n.code,{children:"standard_user"})," roles to a user, they receive all scopes from both roles."]}),"\n",(0,r.jsxs)(n.p,{children:["The ",(0,r.jsx)(n.code,{children:"description"})," field is optional but recommended. It helps you document the purpose of each user account, which is valuable when reviewing or auditing your RBAC configuration."]}),"\n",(0,r.jsx)(n.h3,{id:"creating-the-enterprise-configuration",children:"Creating the Enterprise Configuration"}),"\n",(0,r.jsxs)(n.p,{children:["Create a file named ",(0,r.jsx)(n.code,{children:"enterprise_config.yaml"})," in the ",(0,r.jsx)(n.code,{children:"sam-enterprise/config"})," directory (not in the ",(0,r.jsx)(n.code,{children:"auth"})," subdirectory). This file tells Agent Mesh Enterprise where to find your RBAC configuration files and how to use them."]}),"\n",(0,r.jsx)(n.admonition,{title:"Optional Configuration",type:"tip",children:(0,r.jsxs)(n.p,{children:["The ",(0,r.jsx)(n.code,{children:"authorization_service"})," configuration block is ",(0,r.jsx)(n.strong,{children:"optional"}),". If omitted, the system defaults to ",(0,r.jsx)(n.code,{children:"deny_all"})," (secure by default) and logs a WARNING message. You must explicitly configure authorization to grant access to users."]})}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-yaml",children:'# enterprise_config.yaml\nauthorization_service:\n  type: "default_rbac"\n  role_to_scope_definitions_path: "config/auth/role-to-scope-definitions.yaml"\n  user_to_role_assignments_path: "config/auth/user-to-role-assignments.yaml"\n\nnamespace: "enterprise_prod"\n'})}),"\n",(0,r.jsxs)(n.p,{children:["The ",(0,r.jsx)(n.code,{children:"authorization_service"})," section configures the RBAC system. The ",(0,r.jsx)(n.code,{children:"type"})," field specifies ",(0,r.jsx)(n.code,{children:"default_rbac"}),", which tells Agent Mesh Enterprise to use the file-based RBAC system. The two path fields point to your RBAC configuration files\u2014these paths are relative to the container's working directory, not your host system."]}),"\n",(0,r.jsxs)(n.p,{children:[(0,r.jsx)(n.strong,{children:"Important:"})," When using ",(0,r.jsx)(n.code,{children:"type: default_rbac"}),", ",(0,r.jsx)(n.code,{children:"role_to_scope_definitions_path"})," is ",(0,r.jsx)(n.strong,{children:"required"}),". The system fails to start if these files are missing or invalid."]}),"\n",(0,r.jsxs)(n.p,{children:["The ",(0,r.jsx)(n.code,{children:"namespace"})," field configures the Agent Mesh Enterprise instance. The namespace isolates this instance from others."]}),"\n",(0,r.jsx)(n.h4,{id:"alternative-development-mode-permissive",children:"Alternative: Development Mode (Permissive)"}),"\n",(0,r.jsx)(n.p,{children:"For local development and testing only, you can disable authorization:"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-yaml",children:'# enterprise_config.yaml - DEVELOPMENT ONLY\nauthorization_service:\n  type: "none"  # Grants full access to all users\n\nnamespace: "enterprise_dev"\n'})}),"\n",(0,r.jsx)(n.admonition,{title:"Security Warning",type:"danger",children:(0,r.jsxs)(n.p,{children:["Using ",(0,r.jsx)(n.code,{children:"type: none"})," disables all authorization checks and grants wildcard ",(0,r.jsx)(n.code,{children:"*"})," scope to every user. This configuration should ",(0,r.jsx)(n.strong,{children:"never"})," be used in production environments. The system logs prominent security warnings when this type is active."]})}),"\n",(0,r.jsx)(n.h4,{id:"default-behavior-no-configuration",children:"Default Behavior (No Configuration)"}),"\n",(0,r.jsxs)(n.p,{children:["If you omit the ",(0,r.jsx)(n.code,{children:"authorization_service"})," block entirely, the system uses secure defaults:"]}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-yaml",children:'# enterprise_config.yaml - Secure by default\n# No authorization_service block = deny_all\n\nnamespace: "enterprise_prod"\n'})}),"\n",(0,r.jsx)(n.p,{children:"When no authorization configuration is present, the system:"}),"\n",(0,r.jsxs)(n.ol,{children:["\n",(0,r.jsx)(n.li,{children:"Logs a WARNING message about missing configuration"}),"\n",(0,r.jsxs)(n.li,{children:["Defaults to ",(0,r.jsx)(n.code,{children:"deny_all"})," authorization type"]}),"\n",(0,r.jsx)(n.li,{children:"Denies all user requests with WARNING logs"}),"\n",(0,r.jsx)(n.li,{children:"Requires explicit RBAC configuration to grant access"}),"\n"]}),"\n",(0,r.jsx)(n.h3,{id:"running-the-docker-container",children:"Running the Docker Container"}),"\n",(0,r.jsxs)(n.p,{children:["Now you can start the Docker container with your RBAC configuration.\nNavigate to your ",(0,r.jsx)(n.code,{children:"sam-enterprise"})," directory and run:"]}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-bash",children:'cd sam-enterprise\n\ndocker run -d \\\n  --name sam-enterprise \\\n  -p 8001:8000 \\\n  -v "$(pwd):/app" \\\n  -e SAM_AUTHORIZATION_CONFIG="/app/config/enterprise_config.yaml" \\\n  -e NAMESPACE=enterprise_prod \\\n  -e ... list here all other necessary env vars ...\n  solace-agent-mesh-enterprise:<tagname>\n'})}),"\n",(0,r.jsx)(n.h3,{id:"verifying-your-configuration",children:"Verifying Your Configuration"}),"\n",(0,r.jsx)(n.p,{children:"After starting the container, you should verify that RBAC is working correctly. Follow these steps:"}),"\n",(0,r.jsxs)(n.ol,{children:["\n",(0,r.jsxs)(n.li,{children:["Open your web browser and navigate to ",(0,r.jsx)(n.code,{children:"http://localhost:8001"})]}),"\n",(0,r.jsxs)(n.li,{children:["Log in using one of the user identities defined in your ",(0,r.jsx)(n.code,{children:"user-to-role-assignments.yaml"})," file"]}),"\n",(0,r.jsx)(n.li,{children:"Attempt to access features that the user should have permission to use"}),"\n",(0,r.jsx)(n.li,{children:"Attempt to access features that the user should not have permission to use"}),"\n"]}),"\n",(0,r.jsx)(n.p,{children:"If RBAC is configured correctly, the user can access permitted features and receives authorization errors when attempting to access restricted features."}),"\n",(0,r.jsx)(n.p,{children:"You can also check the container logs to verify that Agent Mesh Enterprise loaded your configuration files:"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-bash",children:"docker logs sam-enterprise\n"})}),"\n",(0,r.jsx)(n.p,{children:"Look for log messages that indicate successful configuration loading. You should see messages similar to:"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{children:"INFO:solace_ai_connector:[ConfigurableRbacAuthSvc] Successfully loaded role-to-scope definitions from: /app/config/auth/role-to-scope-definitions.yaml\nDEBUG:solace_ai_connector:[ConfigurableRbacAuthSvc] Role 'enterprise_admin' loaded with 1 direct scopes, 1 resolved scopes.\nDEBUG:solace_ai_connector:[ConfigurableRbacAuthSvc] Role 'data_analyst' loaded with 4 direct scopes, 4 resolved scopes.\nDEBUG:solace_ai_connector:[ConfigurableRbacAuthSvc] Role 'standard_user' loaded with 3 direct scopes, 3 resolved scopes.\n"})}),"\n",(0,r.jsx)(n.p,{children:"These messages confirm that Agent Mesh Enterprise found and parsed your configuration files correctly."}),"\n",(0,r.jsx)(n.h2,{id:"understanding-configuration-files",children:"Understanding Configuration Files"}),"\n",(0,r.jsx)(n.p,{children:"Now that you have a working RBAC configuration, you should understand the full structure and capabilities of each configuration file. This knowledge helps you customize the configuration to meet your specific needs."}),"\n",(0,r.jsx)(n.h3,{id:"role-to-scope-definitions-structure",children:"Role-to-Scope Definitions Structure"}),"\n",(0,r.jsxs)(n.p,{children:["The ",(0,r.jsx)(n.code,{children:"role-to-scope-definitions.yaml"})," file supports several features beyond the basic examples shown earlier. Here is the complete structure:"]}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-yaml",children:'roles:\n  role_name:\n    description: "Role description"\n    scopes:\n      - "scope1"\n      - "scope2"\n    inherits:  # Optional - inherit scopes from other roles\n      - "parent_role1"\n      - "parent_role2"\n'})}),"\n",(0,r.jsxs)(n.p,{children:["The ",(0,r.jsx)(n.code,{children:"inherits"})," field allows you to create role hierarchies. When a role inherits from another role, it receives all scopes from the parent role in addition to its own scopes. This feature reduces duplication and makes your configuration easier to maintain."]}),"\n",(0,r.jsx)(n.p,{children:'For example, you might create a base "viewer" role with read-only permissions, then create an "operator" role that inherits from "viewer" and adds write permissions:'}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-yaml",children:'roles:\n  viewer:\n    description: "Read-only access"\n    scopes:\n      - "tool:basic:read"\n      - "artifact:read"\n  \n  operator:\n    description: "Operational access"\n    inherits:\n      - "viewer"\n    scopes:\n      - "tool:basic:*"\n      - "artifact:create"\n'})}),"\n",(0,r.jsxs)(n.p,{children:['In this example, the "operator" role receives all scopes from "viewer" (',(0,r.jsx)(n.code,{children:"tool:basic:read"})," and ",(0,r.jsx)(n.code,{children:"artifact:read"}),") plus its own scopes (",(0,r.jsx)(n.code,{children:"tool:basic:*"})," and ",(0,r.jsx)(n.code,{children:"artifact:create"}),"). Note that ",(0,r.jsx)(n.code,{children:"tool:basic:*"})," includes ",(0,r.jsx)(n.code,{children:"tool:basic:read"}),", so there is some overlap. Agent Mesh Enterprise handles this correctly by deduplicating scopes."]}),"\n",(0,r.jsx)(n.h3,{id:"user-to-role-assignments-structure",children:"User-to-Role Assignments Structure"}),"\n",(0,r.jsxs)(n.p,{children:["The ",(0,r.jsx)(n.code,{children:"user-to-role-assignments.yaml"})," file supports both global user identities and gateway-specific identities. Here is the complete structure:"]}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-yaml",children:'users:\n  user_identity:\n    roles: ["role1", "role2"]\n    description: "User description"\n\n# Optional: Gateway-specific user identities\ngateway_specific_identities:\n  gateway_id:user_identity:\n    roles: ["role1", "role2"]\n    description: "User with specific roles on this gateway"\n'})}),"\n",(0,r.jsxs)(n.p,{children:["The ",(0,r.jsx)(n.code,{children:"users"})," section defines global user identities that apply across all gateways. Most configurations only need this section."]}),"\n",(0,r.jsxs)(n.p,{children:["The ",(0,r.jsx)(n.code,{children:"gateway_specific_identities"})," section allows you to assign different roles to the same user identity on different gateways. This feature is useful in multi-gateway deployments where you want to grant different permissions based on which gateway a user accesses. The key format is ",(0,r.jsx)(n.code,{children:"gateway_id:user_identity"}),", where ",(0,r.jsx)(n.code,{children:"gateway_id"})," matches the gateway ID in your configuration. The default gateway ID is ",(0,r.jsx)(n.code,{children:"_default_enterprise_gateway"}),"."]}),"\n",(0,r.jsx)(n.h3,{id:"enterprise-configuration-structure",children:"Enterprise Configuration Structure"}),"\n",(0,r.jsx)(n.p,{children:"The enterprise configuration file supports multiple authorization service types. Here is the complete structure for the file-based RBAC system:"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-yaml",children:'authorization_service:\n  type: "default_rbac"\n  role_to_scope_definitions_path: "path/to/role-to-scope-definitions.yaml"\n  user_to_role_assignments_path: "path/to/user-to-role-assignments.yaml"\n'})}),"\n",(0,r.jsx)(n.h2,{id:"advanced-configuration-options",children:"Advanced Configuration Options"}),"\n",(0,r.jsx)(n.p,{children:"After you have a basic RBAC configuration working, you might want to explore advanced options that provide additional flexibility and integration capabilities."}),"\n",(0,r.jsx)(n.h3,{id:"production-ready-role-configuration",children:"Production-Ready Role Configuration"}),"\n",(0,r.jsx)(n.p,{children:"A production environment typically needs more sophisticated role definitions than the basic examples\n. Here is a comprehensive configuration that demonstrates best practices:"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-yaml",children:'# role-to-scope-definitions.yaml\nroles:\n  admin:\n    description: "Administrator with full access"\n    scopes:\n      - "*"\n  \n  operator:\n    description: "System operator"\n    scopes:\n      - "tool:basic:*"\n      - "tool:advanced:read"\n      - "artifact:read"\n      - "artifact:create"\n      - "monitor/namespace/*:a2a_messages:subscribe"\n  \n  viewer:\n    description: "Read-only access"\n    scopes:\n      - "tool:basic:read"\n      - "artifact:read"\n      - "monitor/namespace/*:a2a_messages:subscribe"\n'})}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-yaml",children:'# user-to-role-assignments.yaml\nusers:\n  admin@company.com:\n    roles: ["admin"]\n    description: "System Administrator"\n  \n  operator@company.com:\n    roles: ["operator"]\n    description: "System Operator"\n  \n  viewer@company.com:\n    roles: ["viewer"]\n    description: "Read-only User"\n'})}),"\n",(0,r.jsx)(n.p,{children:"This configuration creates a clear hierarchy of access levels. The admin role has unrestricted access, the operator role can perform most operational tasks, and the viewer role provides read-only access for monitoring and auditing purposes."}),"\n",(0,r.jsx)(n.h3,{id:"integrating-with-microsoft-graph",children:"Integrating with Microsoft Graph"}),"\n",(0,r.jsx)(n.p,{children:"For enterprise environments that use Microsoft Entra ID (formerly Azure AD) for user management, you can integrate Agent Mesh Enterprise with Microsoft Graph. This integration allows you to manage user role assignments through Microsoft Graph instead of maintaining a separate YAML file."}),"\n",(0,r.jsxs)(n.p,{children:["To configure Microsoft Graph integration, modify your ",(0,r.jsx)(n.code,{children:"enterprise_config.yaml"}),":"]}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-yaml",children:'# enterprise_config.yaml\nauthorization_service:\n  type: "default_rbac"\n  role_to_scope_definitions_path: "config/auth/role-to-scope-definitions.yaml"\n  user_to_role_provider: "ms_graph"\n  \n  ms_graph_config:\n    ms_graph_tenant_id: ${MS_GRAPH_TENANT_ID}\n    ms_graph_client_id: ${MS_GRAPH_CLIENT_ID}\n    ms_graph_client_secret: ${MS_GRAPH_CLIENT_SECRET}\n'})}),"\n",(0,r.jsxs)(n.p,{children:["This configuration tells Agent Mesh Enterprise to retrieve user role assignments from Microsoft Graph instead of reading them from a YAML file. The ",(0,r.jsx)(n.code,{children:"${...}"})," syntax indicates that these values come from environment variables, which keeps sensitive credentials out of your configuration files."]}),"\n",(0,r.jsxs)(n.p,{children:["When you use Microsoft Graph integration, you still define roles in the ",(0,r.jsx)(n.code,{children:"role-to-scope-definitions.yaml"})," file, but you manage user-to-role assignments through Microsoft Graph groups or attributes."]}),"\n",(0,r.jsx)(n.p,{children:"Run the Docker container with the Microsoft Graph credentials:"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-bash",children:'docker run -d \\\n  --name sam-enterprise \\\n  -p 8000:8001 \\\n  -v "$(pwd):/app" \\\n  -e MS_GRAPH_TENANT_ID=your-tenant-id \\\n  -e MS_GRAPH_CLIENT_ID=your-client-id \\\n  -e MS_GRAPH_CLIENT_SECRET=your-client-secret \\\n  -e NAMESPACE=enterprise_prod \\\n  solace-agent-mesh-enterprise:<tag>\n'})}),"\n",(0,r.jsx)(n.p,{children:"The Microsoft Graph integration requires that you configure an application registration in Microsoft Entra ID with appropriate permissions to read user and group information. The tenant ID identifies your Microsoft Entra ID tenant, the client ID identifies your application registration, and the client secret authenticates your application."}),"\n",(0,r.jsx)(n.h2,{id:"best-practices",children:"Best Practices"}),"\n",(0,r.jsx)(n.p,{children:"Following best practices helps you create a secure, maintainable RBAC configuration that scales with your organization's needs."}),"\n",(0,r.jsx)(n.h3,{id:"security-recommendations",children:"Security Recommendations"}),"\n",(0,r.jsx)(n.p,{children:"You should implement these security practices to protect your Agent Mesh Enterprise deployment:"}),"\n",(0,r.jsx)(n.p,{children:"Apply the principle of least privilege by assigning users only the minimum permissions necessary for their tasks. Start with restrictive permissions and add more as needed, rather than starting with broad permissions and removing them later. This approach reduces the risk of unauthorized access."}),"\n",(0,r.jsx)(n.p,{children:"Conduct regular audits of your role assignments and permissions. Review who has access to what features and verify that access levels remain appropriate as job responsibilities change. Remove access for users who no longer need it."}),"\n",(0,r.jsx)(n.p,{children:"Protect your RBAC configuration files with appropriate file permissions on your host system. These files control access to your entire Agent Mesh Enterprise deployment, so you should restrict read and write access to authorized administrators only."}),"\n",(0,r.jsx)(n.p,{children:"Store sensitive information like Microsoft Graph credentials as environment variables rather than hardcoding them in configuration files. Environment variables provide better security because they do not appear in version control systems or configuration backups."}),"\n",(0,r.jsx)(n.p,{children:"Never use development configurations in production environments. Development configurations often include test accounts with elevated permissions or relaxed security settings that are inappropriate for production use."}),"\n",(0,r.jsx)(n.h3,{id:"role-design-principles",children:"Role Design Principles"}),"\n",(0,r.jsx)(n.p,{children:"Well-designed roles make your RBAC configuration easier to understand and maintain:"}),"\n",(0,r.jsx)(n.p,{children:"Create roles that align with job functions in your organization. Each role should represent a specific type of work that users perform. This alignment makes it easier to determine which role to assign to new users."}),"\n",(0,r.jsx)(n.p,{children:"Use role inheritance to build a logical hierarchy. If one role needs all the permissions of another role plus additional permissions, use inheritance rather than duplicating scopes. This approach reduces configuration size and makes updates easier."}),"\n",(0,r.jsx)(n.p,{children:'Use clear, descriptive names for roles that indicate their purpose. Names like "data_analyst" or "system_operator" are more meaningful than generic names like "role1" or "user_type_a".'}),"\n",(0,r.jsx)(n.p,{children:"Document the purpose and scope of each role in the description field. This documentation helps other administrators understand your RBAC configuration and makes it easier to maintain over time."}),"\n",(0,r.jsxs)(n.p,{children:["Minimize wildcard usage in scope definitions. While wildcards like ",(0,r.jsx)(n.code,{children:"*"})," or ",(0,r.jsx)(n.code,{children:"tool:*:*"})," are convenient, they grant broad permissions that might include features you did not intend to allow. Use specific scopes whenever possible, and reserve wildcards for administrator roles."]}),"\n",(0,r.jsx)(n.h3,{id:"docker-specific-recommendations",children:"Docker-Specific Recommendations"}),"\n",(0,r.jsx)(n.p,{children:"When you run Agent Mesh Enterprise in Docker, follow these recommendations:"}),"\n",(0,r.jsx)(n.p,{children:"Use Docker volumes for persistent configuration storage. The volume mount approach shown in this guide ensures that your configuration persists even if you remove and recreate the container."}),"\n",(0,r.jsx)(n.p,{children:"Create separate configuration files for different environments (development, staging, production). This separation prevents accidental use of inappropriate configurations and makes it easier to maintain environment-specific settings."}),"\n",(0,r.jsx)(n.p,{children:"Implement health checks to verify that RBAC is functioning correctly. You can add a health check to your Docker run command that periodically tests whether the container is responding correctly."}),"\n",(0,r.jsx)(n.p,{children:"Regularly backup your RBAC configuration files. Store backups in a secure location separate from your Docker host. If you lose your configuration files, you lose control over who can access your Agent Mesh Enterprise deployment."}),"\n",(0,r.jsx)(n.p,{children:"Follow Docker security best practices such as running containers as non-root users and using read-only filesystems where possible. These practices reduce the impact of potential security vulnerabilities."}),"\n",(0,r.jsx)(n.h2,{id:"troubleshooting",children:"Troubleshooting"}),"\n",(0,r.jsx)(n.p,{children:"When you encounter issues with your RBAC configuration, systematic troubleshooting helps you identify and resolve problems quickly."}),"\n",(0,r.jsx)(n.h3,{id:"authorization-denied-for-valid-user",children:"Authorization Denied for Valid User"}),"\n",(0,r.jsx)(n.p,{children:"If a user cannot access features they should have permission to use, you might see authorization denied messages in the logs or user interface."}),"\n",(0,r.jsxs)(n.p,{children:["To resolve this issue, first verify that the user identity matches exactly what appears in your ",(0,r.jsx)(n.code,{children:"user-to-role-assignments.yaml"})," file. Agent Mesh Enterprise performs case-sensitive matching, so ",(0,r.jsx)(n.code,{children:"user@example.com"})," and ",(0,r.jsx)(n.code,{children:"User@example.com"})," are different identities."]}),"\n",(0,r.jsxs)(n.p,{children:["Next, check that the role assigned to the user has the necessary scopes. Review the ",(0,r.jsx)(n.code,{children:"role-to-scope-definitions.yaml"})," file and verify that the role includes scopes for the features the user is trying to access."]}),"\n",(0,r.jsx)(n.p,{children:"Ensure that your configuration files are correctly mounted in the Docker container. You can verify the mount by running:"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-bash",children:"docker exec -it sam-enterprise ls -la /app/config/auth\n"})}),"\n",(0,r.jsxs)(n.p,{children:["This command lists the files in the mounted directory. You should see your ",(0,r.jsx)(n.code,{children:"role-to-scope-definitions.yaml"})," and ",(0,r.jsx)(n.code,{children:"user-to-role-assignments.yaml"})," files."]}),"\n",(0,r.jsx)(n.p,{children:"Check the container logs for authorization service errors:"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-bash",children:"docker logs sam-enterprise\n"})}),"\n",(0,r.jsxs)(n.p,{children:["Look for messages with the ",(0,r.jsx)(n.code,{children:"[ConfigurableRbacAuthSvc]"})," prefix. These messages indicate whether Agent Mesh Enterprise successfully loaded your configuration files and how it resolved roles and scopes. You should see messages like:"]}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{children:"INFO:solace_ai_connector:[ConfigurableRbacAuthSvc] Successfully loaded role-to-scope definitions from: /app/config/auth/role-to-scope-definitions.yaml\nDEBUG:solace_ai_connector:[ConfigurableRbacAuthSvc] Role 'enterprise_admin' loaded with 1 direct scopes, 1 resolved scopes.\nDEBUG:solace_ai_connector:[ConfigurableRbacAuthSvc] Role 'data_analyst' loaded with 4 direct scopes, 4 resolved scopes.\nDEBUG:solace_ai_connector:[ConfigurableRbacAuthSvc] Role 'standard_user' loaded with 1 direct scopes, 1 resolved scopes.\n"})}),"\n",(0,r.jsx)(n.h3,{id:"configuration-files-not-found",children:"Configuration Files Not Found"}),"\n",(0,r.jsx)(n.p,{children:"If you see error messages about missing configuration files or the system uses default authorization behavior, the container cannot find your configuration files."}),"\n",(0,r.jsxs)(n.p,{children:["Check that the volume mount in your Docker run command is correct. The mount should map your host directory to ",(0,r.jsx)(n.code,{children:"/app"})," in the container. Verify that you are using the correct path on your host system."]}),"\n",(0,r.jsx)(n.p,{children:"Ensure that file permissions allow the container user to read the files. On Linux systems, you might need to adjust file permissions:"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-bash",children:"chmod 644 sam-enterprise/config/auth/*.yaml\n"})}),"\n",(0,r.jsx)(n.p,{children:"Check for typos in file names or paths. The file names are case-sensitive, and even small typos prevent Agent Mesh Enterprise from finding your configuration files."}),"\n",(0,r.jsx)(n.h3,{id:"microsoft-graph-integration-not-working",children:"Microsoft Graph Integration Not Working"}),"\n",(0,r.jsx)(n.p,{children:"If users cannot authenticate when you use Microsoft Graph integration, or you see error messages related to Microsoft Graph in the logs, several issues might be causing the problem."}),"\n",(0,r.jsx)(n.p,{children:"Verify that your Microsoft Graph credentials are correct. Double-check the tenant ID, client ID, and client secret against your Microsoft Entra ID application registration."}),"\n",(0,r.jsx)(n.p,{children:"Check that environment variables are properly set in your Docker run command. You can verify environment variables inside the container:"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-bash",children:"docker exec -it sam-enterprise env | grep MS_GRAPH\n"})}),"\n",(0,r.jsx)(n.p,{children:"Ensure that your Microsoft Graph application has the necessary permissions. The application needs permissions to read user and group information from Microsoft Entra ID."}),"\n",(0,r.jsxs)(n.p,{children:["Check network connectivity from the container to Microsoft Graph endpoints. The container must be able to reach ",(0,r.jsx)(n.code,{children:"graph.microsoft.com"})," over HTTPS. Firewall rules or network policies might block this connectivity."]}),"\n",(0,r.jsx)(n.h3,{id:"debugging-authorization-issues",children:"Debugging Authorization Issues"}),"\n",(0,r.jsx)(n.p,{children:"When you need to investigate authorization problems in detail, follow these debugging steps:"}),"\n",(0,r.jsxs)(n.p,{children:["Enable debug logging by adding a log level setting to your ",(0,r.jsx)(n.code,{children:"enterprise_config.yaml"}),":"]}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-yaml",children:'# Add to your enterprise_config.yaml\nlog_level: "DEBUG"\n'})}),"\n",(0,r.jsx)(n.p,{children:"Debug logging provides detailed information about authorization decisions, including which scopes the system checked and why it allowed or denied access."}),"\n",(0,r.jsx)(n.p,{children:"Check the container logs for detailed information:"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-bash",children:"docker logs sam-enterprise\n"})}),"\n",(0,r.jsxs)(n.p,{children:["Look for log messages with the ",(0,r.jsx)(n.code,{children:"[EnterpriseConfigResolverImpl]"})," or ",(0,r.jsx)(n.code,{children:"[ConfigurableRbacAuthSvc]"})," prefixes. These messages show how Agent Mesh Enterprise loaded and processed your configuration."]}),"\n",(0,r.jsx)(n.p,{children:"Temporarily assign the user to an administrator role to verify whether the issue is permission-related. If the user can access features when assigned to an admin role, the problem is with the scopes assigned to their original role."}),"\n",(0,r.jsx)(n.p,{children:"Inspect the mounted configuration files inside the container to verify that they contain the expected content:"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-bash",children:"docker exec -it sam-enterprise cat /app/config/auth/role-to-scope-definitions.yaml\ndocker exec -it sam-enterprise cat /app/config/auth/user-to-role-assignments.yaml\n"})}),"\n",(0,r.jsx)(n.p,{children:"This verification ensures that the files inside the container match your host files and that the volume mount is working correctly."}),"\n",(0,r.jsx)(n.h3,{id:"getting-help",children:"Getting Help"}),"\n",(0,r.jsx)(n.p,{children:"If you continue to experience issues after following these troubleshooting steps, you can get additional help:"}),"\n",(0,r.jsx)(n.p,{children:"Check the Agent Mesh Enterprise documentation for updates or additional information about RBAC configuration."}),"\n",(0,r.jsx)(n.p,{children:"Review the container logs for specific error messages. Error messages often include details about what went wrong and how to fix it."}),"\n",(0,r.jsx)(n.p,{children:"Contact Solace support with details of your configuration and the issues you are experiencing. Include relevant log excerpts and describe the steps you have already taken to troubleshoot the problem."}),"\n",(0,r.jsx)(n.h2,{id:"conclusion",children:"Conclusion"}),"\n",(0,r.jsx)(n.p,{children:"Setting up Role-Based Access Control in your Agent Mesh Enterprise Docker installation provides enhanced security and granular access control. This guide has walked you through understanding RBAC concepts, planning your configuration, creating configuration files, and troubleshooting common issues."}),"\n",(0,r.jsx)(n.p,{children:"You now have the knowledge to configure RBAC to meet your organization's specific requirements while maintaining a secure and manageable environment. Remember to regularly review and update your RBAC configuration as your organization's needs evolve, and always follow security best practices when managing access control."})]})}function h(e={}){const{wrapper:n}={...(0,t.R)(),...e.components};return n?(0,r.jsx)(n,{...e,children:(0,r.jsx)(d,{...e})}):d(e)}},8453:(e,n,i)=>{i.d(n,{R:()=>o,x:()=>a});var s=i(6540);const r={},t=s.createContext(r);function o(e){const n=s.useContext(t);return s.useMemo((function(){return"function"==typeof e?e(n):{...n,...e}}),[n,e])}function a(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(r):e.components||r:o(e.components),s.createElement(t.Provider,{value:n},e.children)}}}]);

solace_agent_mesh/assets/docs/assets/js/9bb13469.4523ae20.js

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

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/ad87452a.9d73dad6.js

@@ -0,0 +1 @@
+"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[1625],{2585:(e,n,s)=>{s.r(n),s.d(n,{assets:()=>l,contentTitle:()=>o,default:()=>h,frontMatter:()=>r,metadata:()=>i,toc:()=>c});const i=JSON.parse('{"id":"documentation/installing-and-configuring/session-storage","title":"Session Storage","description":"This guide explains how to configure session storage in Agent Mesh, enabling user conversations to persist across restarts and providing rich conversation history for both the WebUI Gateway and individual agents.","source":"@site/docs/documentation/installing-and-configuring/session-storage.md","sourceDirName":"documentation/installing-and-configuring","slug":"/documentation/installing-and-configuring/session-storage","permalink":"/solace-agent-mesh/docs/documentation/installing-and-configuring/session-storage","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/installing-and-configuring/session-storage.md","tags":[],"version":"current","sidebarPosition":350,"frontMatter":{"title":"Session Storage","sidebar_position":350},"sidebar":"docSidebar","previous":{"title":"User Feedback","permalink":"/solace-agent-mesh/docs/documentation/installing-and-configuring/user-feedback"},"next":{"title":"Artifact Storage","permalink":"/solace-agent-mesh/docs/documentation/installing-and-configuring/artifact-storage"}}');var a=s(4848),t=s(8453);const r={title:"Session Storage",sidebar_position:350},o="Configuring Session Storage",l={},c=[{value:"Understanding Session Storage Architecture",id:"understanding-session-storage-architecture",level:2},{value:"How Session Storage Works",id:"how-session-storage-works",level:3},{value:"Where Data Is Stored",id:"where-data-is-stored",level:3},{value:"Session Storage Scenarios",id:"session-storage-scenarios",level:2},{value:"Scenario A: Both WebUI Gateway and Agents Have Persistence (Recommended)",id:"scenario-a-both-webui-gateway-and-agents-have-persistence-recommended",level:3},{value:"Scenario B: Neither Has Persistence (Ephemeral Only)",id:"scenario-b-neither-has-persistence-ephemeral-only",level:3},{value:"Scenario C: Only Agents Have Persistence (Limited Experience)",id:"scenario-c-only-agents-have-persistence-limited-experience",level:3},{value:"Scenario D: Only WebUI Gateway Has Persistence (Broken Experience)",id:"scenario-d-only-webui-gateway-has-persistence-broken-experience",level:3},{value:"Configuring WebUI Gateway Session Storage",id:"configuring-webui-gateway-session-storage",level:2},{value:"Environment Variables",id:"environment-variables",level:3},{value:"Gateway Configuration File",id:"gateway-configuration-file",level:3},{value:"Database Backend Options",id:"database-backend-options",level:3},{value:"SQLite (Development)",id:"sqlite-development",level:4},{value:"PostgreSQL (Production)",id:"postgresql-production",level:4},{value:"MySQL/MariaDB (Production)",id:"mysqlmariadb-production",level:4},{value:"Configuring Agent Session Storage",id:"configuring-agent-session-storage",level:2},{value:"Agent Configuration File",id:"agent-configuration-file",level:3},{value:"Environment Variables",id:"environment-variables-1",level:3},{value:"Database Isolation Between Agents",id:"database-isolation-between-agents",level:3},{value:"Shared Configuration Pattern",id:"shared-configuration-pattern",level:3},{value:"Migrating from Ephemeral to Persistent",id:"migrating-from-ephemeral-to-persistent",level:2},{value:"Step 1: Configure WebUI Gateway Database",id:"step-1-configure-webui-gateway-database",level:3},{value:"Step 2: Configure Agent Databases",id:"step-2-configure-agent-databases",level:3},{value:"Step 3: Restart Application",id:"step-3-restart-application",level:3},{value:"Step 4: Verify Migration",id:"step-4-verify-migration",level:3},{value:"Migration Considerations",id:"migration-considerations",level:3},{value:"Next Steps",id:"next-steps",level:2}];function d(e){const n={a:"a",admonition:"admonition",code:"code",h1:"h1",h2:"h2",h3:"h3",h4:"h4",header:"header",li:"li",ol:"ol",p:"p",pre:"pre",ul:"ul",...(0,t.R)(),...e.components};return(0,a.jsxs)(a.Fragment,{children:[(0,a.jsx)(n.header,{children:(0,a.jsx)(n.h1,{id:"configuring-session-storage",children:"Configuring Session Storage"})}),"\n",(0,a.jsx)(n.p,{children:"This guide explains how to configure session storage in Agent Mesh, enabling user conversations to persist across restarts and providing rich conversation history for both the WebUI Gateway and individual agents."}),"\n",(0,a.jsx)(n.h2,{id:"understanding-session-storage-architecture",children:"Understanding Session Storage Architecture"}),"\n",(0,a.jsx)(n.p,{children:"Agent Mesh uses a distributed session architecture where the WebUI Gateway and agents maintain separate but coordinated session storage systems connected via session IDs."}),"\n",(0,a.jsx)(n.h3,{id:"how-session-storage-works",children:"How Session Storage Works"}),"\n",(0,a.jsx)(n.p,{children:"When a user starts a conversation:"}),"\n",(0,a.jsxs)(n.ol,{children:["\n",(0,a.jsxs)(n.li,{children:["The WebUI Gateway generates a session ID (",(0,a.jsx)(n.code,{children:"web-session-<UUID>"}),")"]}),"\n",(0,a.jsx)(n.li,{children:"The WebUI Gateway sends the session ID to the agent with each message"}),"\n",(0,a.jsx)(n.li,{children:"The agent receives the session ID and uses it to look up or store its own session context"}),"\n",(0,a.jsx)(n.li,{children:"The WebUI Gateway and agent store different data in their own databases"}),"\n"]}),"\n",(0,a.jsx)(n.p,{children:"This architecture allows:"}),"\n",(0,a.jsxs)(n.ul,{children:["\n",(0,a.jsx)(n.li,{children:"The WebUI Gateway to show conversation history in the user interface"}),"\n",(0,a.jsx)(n.li,{children:"Agents to maintain their own conversation context and memory"}),"\n",(0,a.jsx)(n.li,{children:"Multiple agents in a conversation to share the same session ID while maintaining isolated storage"}),"\n"]}),"\n",(0,a.jsx)(n.h3,{id:"where-data-is-stored",children:"Where Data Is Stored"}),"\n",(0,a.jsx)(n.p,{children:"The WebUI Gateway database stores:"}),"\n",(0,a.jsxs)(n.ul,{children:["\n",(0,a.jsx)(n.li,{children:"Session metadata (session ID, user ID, timestamps)"}),"\n",(0,a.jsx)(n.li,{children:"Chat history displayed in the UI"}),"\n",(0,a.jsx)(n.li,{children:"Message bubbles and formatted responses"}),"\n",(0,a.jsx)(n.li,{children:"Task metadata (agent names, status, feedback)"}),"\n"]}),"\n",(0,a.jsx)(n.p,{children:"Each agent database stores:"}),"\n",(0,a.jsxs)(n.ul,{children:["\n",(0,a.jsx)(n.li,{children:"Agent's conversation context and memory"}),"\n",(0,a.jsx)(n.li,{children:"Message history from the agent's perspective"}),"\n",(0,a.jsx)(n.li,{children:"Agent internal state and tool execution history"}),"\n",(0,a.jsx)(n.li,{children:"Session events and actions"}),"\n"]}),"\n",(0,a.jsx)(n.p,{children:"These are separate databases. Each agent has its own independent database (with separate credentials), and the WebUI Gateway has its own database. They coordinate via the session ID."}),"\n",(0,a.jsx)(n.h2,{id:"session-storage-scenarios",children:"Session Storage Scenarios"}),"\n",(0,a.jsx)(n.p,{children:"The behavior of your deployment depends on whether the WebUI Gateway and agents have persistent storage enabled. Understanding these scenarios helps you configure correctly for your needs."}),"\n",(0,a.jsx)(n.h3,{id:"scenario-a-both-webui-gateway-and-agents-have-persistence-recommended",children:"Scenario A: Both WebUI Gateway and Agents Have Persistence (Recommended)"}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-yaml",children:'# WebUI Gateway Configuration\nsession_service:\n  type: "sql"\n  database_url: "${WEB_UI_GATEWAY_DATABASE_URL}"\n'})}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-yaml",children:'# Agent Configuration\nsession_service:\n  type: "sql"\n  database_url: "${AGENT_DATABASE_URL, sqlite:///agent-session.db}"\n  default_behavior: "PERSISTENT"\n'})}),"\n",(0,a.jsx)(n.p,{children:"What happens:"}),"\n",(0,a.jsxs)(n.ul,{children:["\n",(0,a.jsx)(n.li,{children:"User sees full chat history in the UI after restarts"}),"\n",(0,a.jsx)(n.li,{children:"Agents remember full conversation context across restarts"}),"\n",(0,a.jsx)(n.li,{children:"Multi-turn conversations work perfectly"}),"\n",(0,a.jsx)(n.li,{children:"Browser refresh preserves everything"}),"\n"]}),"\n",(0,a.jsx)(n.p,{children:"Use this for:"}),"\n",(0,a.jsxs)(n.ul,{children:["\n",(0,a.jsx)(n.li,{children:"Production deployments"}),"\n",(0,a.jsx)(n.li,{children:"Multi-turn interactive experiences"}),"\n",(0,a.jsx)(n.li,{children:"Any deployment where users expect conversation continuity"}),"\n"]}),"\n",(0,a.jsx)(n.h3,{id:"scenario-b-neither-has-persistence-ephemeral-only",children:"Scenario B: Neither Has Persistence (Ephemeral Only)"}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-yaml",children:'# WebUI Gateway Configuration\nsession_service:\n  type: "memory"\n'})}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-yaml",children:'# Agent Configuration\nsession_service:\n  type: "memory"\n'})}),"\n",(0,a.jsx)(n.p,{children:"What happens:"}),"\n",(0,a.jsxs)(n.ul,{children:["\n",(0,a.jsx)(n.li,{children:"Sessions exist only in browser cookies"}),"\n",(0,a.jsx)(n.li,{children:"No conversation history after browser refresh"}),"\n",(0,a.jsx)(n.li,{children:"No persistence across restarts"}),"\n",(0,a.jsx)(n.li,{children:"Everything lost when cookies expire"}),"\n"]}),"\n",(0,a.jsx)(n.p,{children:"Use this for:"}),"\n",(0,a.jsxs)(n.ul,{children:["\n",(0,a.jsx)(n.li,{children:"Local development and testing only"}),"\n",(0,a.jsx)(n.li,{children:"Rapid prototyping"}),"\n",(0,a.jsx)(n.li,{children:"Scenarios where no persistence is needed"}),"\n"]}),"\n",(0,a.jsx)(n.p,{children:"Do not use for:"}),"\n",(0,a.jsxs)(n.ul,{children:["\n",(0,a.jsx)(n.li,{children:"Production deployments"}),"\n",(0,a.jsx)(n.li,{children:"Multi-turn conversations"}),"\n",(0,a.jsx)(n.li,{children:"Any scenario requiring conversation continuity"}),"\n"]}),"\n",(0,a.jsx)(n.h3,{id:"scenario-c-only-agents-have-persistence-limited-experience",children:"Scenario C: Only Agents Have Persistence (Limited Experience)"}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-yaml",children:'# WebUI Gateway Configuration\nsession_service:\n  type: "memory"  # No database\n'})}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-yaml",children:'# Agent Configuration\nsession_service:\n  type: "sql"\n  database_url: "${AGENT_DATABASE_URL}"\n  default_behavior: "PERSISTENT"\n'})}),"\n",(0,a.jsx)(n.p,{children:"What happens:"}),"\n",(0,a.jsxs)(n.ul,{children:["\n",(0,a.jsx)(n.li,{children:"User sees no chat history in the UI after browser refresh"}),"\n",(0,a.jsx)(n.li,{children:"Agents maintain conversation context internally"}),"\n",(0,a.jsx)(n.li,{children:"Conversation works but UI does not show history"}),"\n"]}),"\n",(0,a.jsx)(n.p,{children:"Use this for:"}),"\n",(0,a.jsxs)(n.ul,{children:["\n",(0,a.jsx)(n.li,{children:"Rare scenarios where UI history is not needed"}),"\n",(0,a.jsx)(n.li,{children:"Headless or API-only deployments without WebUI"}),"\n"]}),"\n",(0,a.jsx)(n.h3,{id:"scenario-d-only-webui-gateway-has-persistence-broken-experience",children:"Scenario D: Only WebUI Gateway Has Persistence (Broken Experience)"}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-yaml",children:'# WebUI Gateway Configuration\nsession_service:\n  type: "sql"\n  database_url: "${WEB_UI_GATEWAY_DATABASE_URL}"\n'})}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-yaml",children:'# Agent Configuration\nsession_service:\n  type: "memory"  # No database\n'})}),"\n",(0,a.jsxs)(n.admonition,{title:"Broken Experience",type:"warning",children:[(0,a.jsx)(n.p,{children:"What happens:"}),(0,a.jsxs)(n.ul,{children:["\n",(0,a.jsx)(n.li,{children:"User sees full chat history in the UI"}),"\n",(0,a.jsx)(n.li,{children:"Agent receives session ID but has no database to store context"}),"\n",(0,a.jsx)(n.li,{children:"Agent processes current message but forgets previous turns"}),"\n",(0,a.jsx)(n.li,{children:"The UI shows history, but the agent acts like every message is the first one"}),"\n"]}),(0,a.jsx)(n.p,{children:"The UI misleads the user by showing conversation history that the agent cannot actually use. Users get frustrated when the agent does not remember what they just said."}),(0,a.jsx)(n.p,{children:"Avoid this scenario because it creates a confusing and broken user experience."})]}),"\n",(0,a.jsx)(n.h2,{id:"configuring-webui-gateway-session-storage",children:"Configuring WebUI Gateway Session Storage"}),"\n",(0,a.jsx)(n.p,{children:"The WebUI Gateway requires two configuration elements to enable persistent session storage."}),"\n",(0,a.jsx)(n.h3,{id:"environment-variables",children:"Environment Variables"}),"\n",(0,a.jsxs)(n.p,{children:[(0,a.jsx)(n.code,{children:"SESSION_SECRET_KEY"})," (Required)"]}),"\n",(0,a.jsx)(n.p,{children:"A secret key used to sign session cookies. This must be the same across all instances if you run multiple pods or processes."}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-bash",children:'export SESSION_SECRET_KEY="your-secret-key-here"\n'})}),"\n",(0,a.jsxs)(n.p,{children:[(0,a.jsx)(n.code,{children:"WEB_UI_GATEWAY_DATABASE_URL"})," (Required for persistent mode)"]}),"\n",(0,a.jsx)(n.p,{children:"The database connection string specifying where to store session data."}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-bash",children:'export WEB_UI_GATEWAY_DATABASE_URL="postgresql://user:pass@host:5432/webui_db"\n'})}),"\n",(0,a.jsxs)(n.p,{children:[(0,a.jsx)(n.code,{children:"PLATFORM_DATABASE_URL"})," (Optional, required for enterprise features)"]}),"\n",(0,a.jsx)(n.p,{children:"The database connection string for platform features such as agents, connectors, and deployments. If not configured, platform endpoints return 501 (Not Implemented)."}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-bash",children:'export PLATFORM_DATABASE_URL="postgresql://user:pass@host:5432/platform_db"\n'})}),"\n",(0,a.jsx)(n.p,{children:"For development, you can use SQLite:"}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-bash",children:'export PLATFORM_DATABASE_URL="sqlite:///platform.db"\n'})}),"\n",(0,a.jsx)(n.h3,{id:"gateway-configuration-file",children:"Gateway Configuration File"}),"\n",(0,a.jsx)(n.p,{children:"Update your WebUI Gateway configuration to use the database:"}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-yaml",children:'session_service:\n  type: "sql"\n  database_url: "${WEB_UI_GATEWAY_DATABASE_URL}"\n\nplatform_service:\n  database_url: "${PLATFORM_DATABASE_URL, sqlite:///platform.db}"\n'})}),"\n",(0,a.jsx)(n.h3,{id:"database-backend-options",children:"Database Backend Options"}),"\n",(0,a.jsx)(n.h4,{id:"sqlite-development",children:"SQLite (Development)"}),"\n",(0,a.jsx)(n.p,{children:"SQLite stores session data in a local file, ideal for development without external infrastructure."}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-yaml",children:'session_service:\n  type: "sql"\n  database_url: "sqlite:///webui-gateway.db"\n'})}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-bash",children:'export WEB_UI_GATEWAY_DATABASE_URL="sqlite:///webui-gateway.db"\n'})}),"\n",(0,a.jsx)(n.p,{children:"Advantages:"}),"\n",(0,a.jsxs)(n.ul,{children:["\n",(0,a.jsx)(n.li,{children:"No external dependencies"}),"\n",(0,a.jsx)(n.li,{children:"Instant setup"}),"\n",(0,a.jsx)(n.li,{children:"Perfect for local development"}),"\n"]}),"\n",(0,a.jsx)(n.p,{children:"Limitations:"}),"\n",(0,a.jsxs)(n.ul,{children:["\n",(0,a.jsx)(n.li,{children:"Not suitable for production"}),"\n",(0,a.jsx)(n.li,{children:"Cannot be shared across multiple instances"}),"\n",(0,a.jsx)(n.li,{children:"No built-in replication or backup"}),"\n"]}),"\n",(0,a.jsx)(n.h4,{id:"postgresql-production",children:"PostgreSQL (Production)"}),"\n",(0,a.jsx)(n.p,{children:"PostgreSQL provides robust, scalable database suitable for production deployments."}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-yaml",children:'session_service:\n  type: "sql"\n  database_url: "postgresql://user:password@host:5432/webui_db"\n'})}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-bash",children:'export WEB_UI_GATEWAY_DATABASE_URL="postgresql://webui_user:secure_pass@db.example.com:5432/webui_db"\n'})}),"\n",(0,a.jsx)(n.p,{children:"Advantages:"}),"\n",(0,a.jsxs)(n.ul,{children:["\n",(0,a.jsx)(n.li,{children:"Production-grade reliability"}),"\n",(0,a.jsx)(n.li,{children:"Horizontal scalability (multiple instances share same database)"}),"\n",(0,a.jsx)(n.li,{children:"Cloud-managed options (AWS RDS, Google Cloud SQL, Azure Database)"}),"\n",(0,a.jsx)(n.li,{children:"Connection pooling support"}),"\n",(0,a.jsx)(n.li,{children:"ACID compliance"}),"\n"]}),"\n",(0,a.jsx)(n.p,{children:"Connection string format:"}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{children:"postgresql://[user[:password]@][host][:port]/[dbname][?param1=value1&...]\n"})}),"\n",(0,a.jsx)(n.h4,{id:"mysqlmariadb-production",children:"MySQL/MariaDB (Production)"}),"\n",(0,a.jsx)(n.p,{children:"MySQL and MariaDB are popular open-source databases suitable for production."}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-yaml",children:'session_service:\n  type: "sql"\n  database_url: "mysql+pymysql://user:password@host:3306/webui_db"\n'})}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-bash",children:'export WEB_UI_GATEWAY_DATABASE_URL="mysql+pymysql://webui_user:secure_pass@db.example.com:3306/webui_db"\n'})}),"\n",(0,a.jsx)(n.p,{children:"Advantages:"}),"\n",(0,a.jsxs)(n.ul,{children:["\n",(0,a.jsx)(n.li,{children:"Open-source and widely available"}),"\n",(0,a.jsx)(n.li,{children:"Strong community support"}),"\n",(0,a.jsx)(n.li,{children:"Cloud-managed options available"}),"\n",(0,a.jsx)(n.li,{children:"ACID compliance (with InnoDB)"}),"\n"]}),"\n",(0,a.jsx)(n.p,{children:"Connection string format:"}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{children:"mysql+pymysql://[user[:password]@][host][:port]/[database]\n"})}),"\n",(0,a.jsxs)(n.p,{children:["Agent Mesh uses ",(0,a.jsx)(n.code,{children:"pymysql"})," as the Python driver."]}),"\n",(0,a.jsx)(n.h2,{id:"configuring-agent-session-storage",children:"Configuring Agent Session Storage"}),"\n",(0,a.jsx)(n.p,{children:"Agents use the ADK (Agent Development Kit) session configuration system. Each agent can be configured independently with its own database."}),"\n",(0,a.jsx)(n.h3,{id:"agent-configuration-file",children:"Agent Configuration File"}),"\n",(0,a.jsxs)(n.p,{children:["Add the ",(0,a.jsx)(n.code,{children:"session_service"})," section to your agent's YAML configuration:"]}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-yaml",children:'session_service:\n  type: "sql"\n  database_url: "${AGENT_DATABASE_URL, sqlite:///agent-session.db}"\n  default_behavior: "PERSISTENT"\n'})}),"\n",(0,a.jsx)(n.p,{children:"Parameters:"}),"\n",(0,a.jsxs)(n.ul,{children:["\n",(0,a.jsxs)(n.li,{children:[(0,a.jsx)(n.code,{children:"type"}),": ",(0,a.jsx)(n.code,{children:'"memory"'})," (ephemeral) or ",(0,a.jsx)(n.code,{children:'"sql"'})," (persistent)"]}),"\n",(0,a.jsxs)(n.li,{children:[(0,a.jsx)(n.code,{children:"database_url"}),": Connection string for the agent's database"]}),"\n",(0,a.jsxs)(n.li,{children:[(0,a.jsx)(n.code,{children:"default_behavior"}),": ",(0,a.jsx)(n.code,{children:'"PERSISTENT"'})," (reuse sessions) or ",(0,a.jsx)(n.code,{children:'"RUN_BASED"'})," (new session per run)"]}),"\n"]}),"\n",(0,a.jsx)(n.h3,{id:"environment-variables-1",children:"Environment Variables"}),"\n",(0,a.jsx)(n.p,{children:"Each agent can have its own database credentials:"}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-bash",children:'export AGENT_DATABASE_URL="postgresql://agent_user:agent_pass@host:5432/agent_db"\n'})}),"\n",(0,a.jsx)(n.p,{children:"Or use a default with fallback in the YAML:"}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-yaml",children:'database_url: "${AGENT_DATABASE_URL, sqlite:///agent-session.db}"\n'})}),"\n",(0,a.jsx)(n.h3,{id:"database-isolation-between-agents",children:"Database Isolation Between Agents"}),"\n",(0,a.jsx)(n.p,{children:"Each agent should have:"}),"\n",(0,a.jsxs)(n.ul,{children:["\n",(0,a.jsx)(n.li,{children:"Its own separate database (not just a schema)"}),"\n",(0,a.jsx)(n.li,{children:"Its own separate credentials (username and password)"}),"\n",(0,a.jsx)(n.li,{children:"Complete isolation from other agents' data"}),"\n"]}),"\n",(0,a.jsx)(n.p,{children:"Example for two agents:"}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-yaml",children:'# Agent A Configuration\nsession_service:\n  type: "sql"\n  database_url: "${AGENT_A_DATABASE_URL, sqlite:///agent-a.db}"\n  default_behavior: "PERSISTENT"\n'})}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-yaml",children:'# Agent B Configuration\nsession_service:\n  type: "sql"\n  database_url: "${AGENT_B_DATABASE_URL, sqlite:///agent-b.db}"\n  default_behavior: "PERSISTENT"\n'})}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-bash",children:'# Environment variables for isolation\nexport AGENT_A_DATABASE_URL="postgresql://agent_a_user:pass@host:5432/agent_a_db"\nexport AGENT_B_DATABASE_URL="postgresql://agent_b_user:pass@host:5432/agent_b_db"\n'})}),"\n",(0,a.jsx)(n.h3,{id:"shared-configuration-pattern",children:"Shared Configuration Pattern"}),"\n",(0,a.jsx)(n.p,{children:"If all agents should use the same session storage configuration, use YAML anchors:"}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-yaml",children:'# Shared configuration\nsession_service: &default_session_service\n  type: "sql"\n  database_url: "${SESSION_DATABASE_URL, sqlite:///session.db}"\n  default_behavior: "PERSISTENT"\n\n# Agent references shared config\nagents:\n  - name: agent-a\n    session_service: *default_session_service\n\n  - name: agent-b\n    session_service: *default_session_service\n'})}),"\n",(0,a.jsx)(n.h2,{id:"migrating-from-ephemeral-to-persistent",children:"Migrating from Ephemeral to Persistent"}),"\n",(0,a.jsx)(n.p,{children:"Moving from ephemeral mode to persistent mode can be done without losing active sessions."}),"\n",(0,a.jsx)(n.h3,{id:"step-1-configure-webui-gateway-database",children:"Step 1: Configure WebUI Gateway Database"}),"\n",(0,a.jsx)(n.p,{children:"Set the environment variables:"}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-bash",children:'export SESSION_SECRET_KEY="your-secret-key"\nexport WEB_UI_GATEWAY_DATABASE_URL="postgresql://user:pass@host:5432/webui_db"\n'})}),"\n",(0,a.jsx)(n.p,{children:"Update your WebUI Gateway configuration:"}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-yaml",children:'session_service:\n  type: "sql"\n  database_url: "${WEB_UI_GATEWAY_DATABASE_URL}"\n'})}),"\n",(0,a.jsx)(n.h3,{id:"step-2-configure-agent-databases",children:"Step 2: Configure Agent Databases"}),"\n",(0,a.jsx)(n.p,{children:"For each agent, set the database URL:"}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-bash",children:'export AGENT_DATABASE_URL="postgresql://agent_user:pass@host:5432/agent_db"\n'})}),"\n",(0,a.jsx)(n.p,{children:"Update agent configuration:"}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-yaml",children:'session_service:\n  type: "sql"\n  database_url: "${AGENT_DATABASE_URL}"\n  default_behavior: "PERSISTENT"\n'})}),"\n",(0,a.jsx)(n.h3,{id:"step-3-restart-application",children:"Step 3: Restart Application"}),"\n",(0,a.jsx)(n.p,{children:"When the application restarts:"}),"\n",(0,a.jsxs)(n.ul,{children:["\n",(0,a.jsx)(n.li,{children:"Database migrations run automatically"}),"\n",(0,a.jsx)(n.li,{children:"Tables are created for session storage"}),"\n",(0,a.jsx)(n.li,{children:"No manual database setup required"}),"\n"]}),"\n",(0,a.jsx)(n.p,{children:"Tables created:"}),"\n",(0,a.jsxs)(n.ul,{children:["\n",(0,a.jsxs)(n.li,{children:[(0,a.jsx)(n.code,{children:"sessions"})," - Session metadata"]}),"\n",(0,a.jsxs)(n.li,{children:[(0,a.jsx)(n.code,{children:"chat_tasks"})," - Conversation messages"]}),"\n",(0,a.jsx)(n.li,{children:"Supporting indexes for performance"}),"\n"]}),"\n",(0,a.jsx)(n.h3,{id:"step-4-verify-migration",children:"Step 4: Verify Migration"}),"\n",(0,a.jsx)(n.p,{children:"Test that persistence is working:"}),"\n",(0,a.jsxs)(n.ol,{children:["\n",(0,a.jsx)(n.li,{children:"Start a conversation with an agent"}),"\n",(0,a.jsx)(n.li,{children:"Send a message"}),"\n",(0,a.jsx)(n.li,{children:"Restart the application"}),"\n",(0,a.jsx)(n.li,{children:"Refresh your browser"}),"\n",(0,a.jsx)(n.li,{children:"Verify conversation history is visible"}),"\n",(0,a.jsx)(n.li,{children:"Send another message to the same agent"}),"\n",(0,a.jsx)(n.li,{children:"Verify agent remembers previous conversation context"}),"\n"]}),"\n",(0,a.jsx)(n.h3,{id:"migration-considerations",children:"Migration Considerations"}),"\n",(0,a.jsx)(n.p,{children:"Existing cookies remain valid. Sessions stored only in cookies before migration continue to work until cookies expire."}),"\n",(0,a.jsx)(n.p,{children:"Database initialization happens once on first startup. Subsequent restarts connect to the existing database."}),"\n",(0,a.jsx)(n.p,{children:"Migration adds new storage without affecting existing sessions."}),"\n",(0,a.jsx)(n.h2,{id:"next-steps",children:"Next Steps"}),"\n",(0,a.jsx)(n.p,{children:"After configuring session storage, you may want to:"}),"\n",(0,a.jsxs)(n.ul,{children:["\n",(0,a.jsxs)(n.li,{children:["Configure ",(0,a.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/installing-and-configuring/artifact-storage",children:"Artifact Storage"})," for agent-generated files"]}),"\n",(0,a.jsxs)(n.li,{children:["Review ",(0,a.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/deploying/deployment-options",children:"deployment options"})," for production considerations"]}),"\n",(0,a.jsxs)(n.li,{children:["Set up ",(0,a.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/deploying/observability",children:"monitoring and observability"})," to track session activity"]}),"\n"]})]})}function h(e={}){const{wrapper:n}={...(0,t.R)(),...e.components};return n?(0,a.jsx)(n,{...e,children:(0,a.jsx)(d,{...e})}):d(e)}},8453:(e,n,s)=>{s.d(n,{R:()=>r,x:()=>o});var i=s(6540);const a={},t=i.createContext(a);function r(e){const n=i.useContext(t);return i.useMemo((function(){return"function"==typeof e?e(n):{...n,...e}}),[n,e])}function o(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(a):e.components||a:r(e.components),i.createElement(t.Provider,{value:n},e.children)}}}]);