solace-agent-mesh 1.4.12__py3-none-any.whl → 1.5.1__py3-none-any.whl

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

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

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

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

solace_agent_mesh/assets/docs/assets/js/aba87c2f.4ddf32f2.js

@@ -1 +0,0 @@
-"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[4651],{5923:(e,n,t)=>{t.r(n),t.d(n,{assets:()=>l,contentTitle:()=>r,default:()=>h,frontMatter:()=>o,metadata:()=>s,toc:()=>c});const s=JSON.parse('{"id":"documentation/concepts/agents","title":"Agents","description":"Agents are specialized processing units within the Solace Agent Mesh framework that are built around the Google Agent Development Kit (ADK) and provide the core intelligence layer. They:","source":"@site/docs/documentation/concepts/agents.md","sourceDirName":"documentation/concepts","slug":"/documentation/concepts/agents","permalink":"/solace-agent-mesh/docs/documentation/concepts/agents","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/concepts/agents.md","tags":[],"version":"current","sidebarPosition":20,"frontMatter":{"title":"Agents","sidebar_position":20},"sidebar":"docSidebar","previous":{"title":"Gateways","permalink":"/solace-agent-mesh/docs/documentation/concepts/gateways"},"next":{"title":"Orchestrator","permalink":"/solace-agent-mesh/docs/documentation/concepts/orchestrator"}}');var i=t(4848),a=t(8453);const o={title:"Agents",sidebar_position:20},r="Agents",l={},c=[{value:"Key Functions",id:"key-functions",level:2},{value:"Agent Design",id:"agent-design",level:2},{value:"The Agent Lifecycle",id:"the-agent-lifecycle",level:3},{value:"Potential Agent Examples",id:"potential-agent-examples",level:3},{value:"Tool Ecosystem",id:"tool-ecosystem",level:2},{value:"1. Built-in Tools",id:"1-built-in-tools",level:3},{value:"2. Custom Python Tools",id:"2-custom-python-tools",level:3},{value:"3. MCP (Model Context Protocol) Tools",id:"3-mcp-model-context-protocol-tools",level:3},{value:"Agent Card",id:"agent-card",level:2},{value:"Key Fields",id:"key-fields",level:3},{value:"Skills",id:"skills",level:3},{value:"Example Configuration",id:"example-configuration",level:3},{value:"User-Defined Agents",id:"user-defined-agents",level:2},{value:"Agent Plugins",id:"agent-plugins",level:2}];function d(e){const n={a:"a",admonition:"admonition",code:"code",h1:"h1",h2:"h2",h3:"h3",header:"header",li:"li",ol:"ol",p:"p",pre:"pre",strong:"strong",ul:"ul",...(0,a.R)(),...e.components};return(0,i.jsxs)(i.Fragment,{children:[(0,i.jsx)(n.header,{children:(0,i.jsx)(n.h1,{id:"agents",children:"Agents"})}),"\n",(0,i.jsx)(n.p,{children:"Agents are specialized processing units within the Solace Agent Mesh framework that are built around the Google Agent Development Kit (ADK) and provide the core intelligence layer. They:"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsx)(n.li,{children:"perform specific tasks or provide domain-specific knowledge or capabilities"}),"\n",(0,i.jsx)(n.li,{children:"integrate with the ADK runtime for advanced AI capabilities including tool usage, memory management, and session handling"}),"\n",(0,i.jsx)(n.li,{children:"play a crucial role in the system's ability to handle a wide range of tasks and adapt to various domains"}),"\n"]}),"\n",(0,i.jsx)(n.admonition,{title:"In one sentence",type:"tip",children:(0,i.jsx)(n.p,{children:"Agents are intelligence units that communicate through the A2A protocol to provide system capabilities beyond basic orchestrator capabilities."})}),"\n",(0,i.jsx)(n.h2,{id:"key-functions",children:"Key Functions"}),"\n",(0,i.jsxs)(n.ol,{children:["\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.strong,{children:"ADK Integration"}),": Agents are built using the Google Agent Development Kit, providing advanced AI capabilities including tool usage, memory management, and artifact handling."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.strong,{children:"AI-Enabled"}),": Agents come packaged with access to large language models (LLMs) and can utilize various tools."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.strong,{children:"Dynamic Discovery"}),": New agents can self-register/deregister and be discovered dynamically through broadcast messages without requiring changes to the running system."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.strong,{children:"Tool Ecosystem"}),": Agents have access to built-in tools for artifact management, data analysis, web scraping, and peer-to-peer delegation."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.strong,{children:"Session Management"}),": Agents support conversation continuity through ADK's session management capabilities."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.strong,{children:"Independence"}),": Agents are modularized and can be updated or replaced independently of other components."]}),"\n"]}),"\n"]}),"\n",(0,i.jsx)(n.h2,{id:"agent-design",children:"Agent Design"}),"\n",(0,i.jsx)(n.p,{children:"Agents in Solace Agent Mesh are built around the Solace AI Connector (SAC) component with ADK. Agent Mesh agents are complete self-contained units that can carry out specific tasks or provide domain-specific knowledge or capabilities. Each agent is defined by a YAML configuration file."}),"\n",(0,i.jsx)(n.p,{children:"Each agent integrates with:"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.strong,{children:"ADK Runtime"}),": For AI model access, tool execution, and session management"]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.strong,{children:"A2A Protocol"}),": For standardized agent-to-agent communication"]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.strong,{children:"Tool Registry"}),": Access to built-in and custom tools"]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.strong,{children:"Artifact Service"}),": For file handling and management"]}),"\n"]}),"\n",(0,i.jsx)(n.p,{children:"For example, an agent configured with SQL database tools can execute queries, perform data analysis, and generate visualizations through the integrated tool ecosystem, all while maintaining conversation context through its session management."}),"\n",(0,i.jsx)(n.h3,{id:"the-agent-lifecycle",children:"The Agent Lifecycle"}),"\n",(0,i.jsx)(n.p,{children:"Agents in Solace Agent Mesh follow the A2A protocol lifecycle and interact with the agent registry:"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.strong,{children:"Discovery"}),": Agents start broadcasting discovery messages on startup to announce their availability and capabilities to the agent mesh."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.strong,{children:"Active"}),": The agent listens for A2A protocol messages on its designated topics and processes incoming tasks through the ADK runtime."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.strong,{children:"Execution"}),": The agent works on a task. They can also delegate tasks to other agents through the peer-to-peer A2A communication protocol."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.strong,{children:"Cleanup"}),": When shutting down, agents perform session cleanup and deregister from the agent mesh."]}),"\n"]}),"\n"]}),"\n",(0,i.jsx)(n.h3,{id:"potential-agent-examples",children:"Potential Agent Examples"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.strong,{children:"RAG (Retrieval Augmented Generation) Agent"}),": An agent that can retrieve information based on a natural language query using an embedding model and vector database, and then generate a response using a language model."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.strong,{children:"External API Bridge"}),": An agent that acts as a bridge to external APIs, retrieving information from third-party services such as weather APIs or product information databases."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.strong,{children:"Internal System Lookup"}),": An agent that performs lookups in internal systems, such as a ticket management system or a customer relationship management (CRM) database."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.strong,{children:"Natural Language Processing Agent"}),": An agent that can perform tasks like sentiment analysis, named entity recognition, or language translation."]}),"\n"]}),"\n"]}),"\n",(0,i.jsx)(n.h2,{id:"tool-ecosystem",children:"Tool Ecosystem"}),"\n",(0,i.jsxs)(n.p,{children:["Agents perform tasks by using ",(0,i.jsx)(n.strong,{children:"tools"}),". A tool is a specific capability, like querying a database, calling an external API, or generating an image. The Solace Agent Mesh framework provides a flexible and powerful tool ecosystem, allowing you to equip your agents with the right capabilities for any job."]}),"\n",(0,i.jsx)(n.p,{children:"There are three primary ways to add tools to an agent:"}),"\n",(0,i.jsx)(n.h3,{id:"1-built-in-tools",children:"1. Built-in Tools"}),"\n",(0,i.jsx)(n.p,{children:"Solace Agent Mesh includes a rich library of pre-packaged tools for common tasks like data analysis, file management, and web requests. These are the easiest to use and can be enabled with just a few lines of configuration."}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.strong,{children:"Use Case"}),": For standard, out-of-the-box functionality."]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.strong,{children:"Learn More"}),": See the ",(0,i.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/user-guide/builtin-tools/",children:"Built-in Tools Reference"})," for a complete list and configuration details."]}),"\n"]}),"\n",(0,i.jsx)(n.h3,{id:"2-custom-python-tools",children:"2. Custom Python Tools"}),"\n",(0,i.jsx)(n.p,{children:"For unique business logic or specialized tasks, you can create your own tools using Python. This is the most powerful and flexible method, supporting everything from simple functions to advanced, class-based tool factories that can generate multiple tools programmatically."}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.strong,{children:"Use Case"}),": For implementing custom logic, integrating with proprietary systems, or creating dynamically configured tools."]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.strong,{children:"Learn More"}),": See the ",(0,i.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/user-guide/creating-python-tools",children:"Creating Python Tools"})," guide for a complete walkthrough."]}),"\n"]}),"\n",(0,i.jsx)(n.h3,{id:"3-mcp-model-context-protocol-tools",children:"3. MCP (Model Context Protocol) Tools"}),"\n",(0,i.jsx)(n.p,{children:"For integrating with external, standalone tool servers that conform to the Model Context Protocol, you can configure an MCP tool. This allows agents to communicate with tools running in separate processes or on different machines."}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.strong,{children:"Use Case"}),": For integrating with existing MCP-compliant tool servers or language-agnostic tool development."]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.strong,{children:"Learn More"}),": See the ",(0,i.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/tutorials/mcp-integration",children:"MCP Integration Tutorial"}),"."]}),"\n"]}),"\n",(0,i.jsx)(n.h2,{id:"agent-card",children:"Agent Card"}),"\n",(0,i.jsx)(n.p,{children:"The Agent Card is a public-facing profile that describes an agent's identity, capabilities, and how to interact with it. It functions like a digital business card, allowing other agents and clients within Solace Agent Mesh to discover what an agent can do. This information is published by the agent and is crucial for dynamic discovery and interoperability."}),"\n",(0,i.jsxs)(n.p,{children:["The Agent Card is defined in the agent's YAML configuration file under the ",(0,i.jsx)(n.code,{children:"agent_card"})," section."]}),"\n",(0,i.jsx)(n.h3,{id:"key-fields",children:"Key Fields"}),"\n",(0,i.jsxs)(n.p,{children:["You can configure the following fields in the ",(0,i.jsx)(n.code,{children:"agent card"}),":"]}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.strong,{children:(0,i.jsx)(n.code,{children:"description"})}),": A summary of the agent's purpose and capabilities."]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.strong,{children:(0,i.jsx)(n.code,{children:"defaultInputModes"})}),": A list of supported MIME types for input (e.g., ",(0,i.jsx)(n.code,{children:'["text/plain", "application/json", "file"]'}),")."]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.strong,{children:(0,i.jsx)(n.code,{children:"defaultOutputModes"})}),": A list of supported MIME types for output."]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.strong,{children:(0,i.jsx)(n.code,{children:"skills"})}),": A list of specific skills the agent possesses. Each skill corresponds to a capability, often backed by a tool."]}),"\n"]}),"\n",(0,i.jsx)(n.h3,{id:"skills",children:"Skills"}),"\n",(0,i.jsx)(n.p,{children:"A skill describes a specific function the agent can perform. It provides granular detail about the agent's abilities."}),"\n",(0,i.jsx)(n.p,{children:"Key attributes of a skill include:"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.strong,{children:(0,i.jsx)(n.code,{children:"id"})}),": A unique identifier for the skill, which should match the ",(0,i.jsx)(n.code,{children:"tool_name"})," if the skill is directly mapped to a tool."]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.strong,{children:(0,i.jsx)(n.code,{children:"name"})}),": A human-readable name for the skill."]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.strong,{children:(0,i.jsx)(n.code,{children:"description"})}),": A clear explanation of what the skill does, which helps the LLM (and other agents) decide when to use it."]}),"\n"]}),"\n",(0,i.jsx)(n.h3,{id:"example-configuration",children:"Example Configuration"}),"\n",(0,i.jsxs)(n.p,{children:["Here is an example of an ",(0,i.jsx)(n.code,{children:"agent_card"}),' configuration for a "Mermaid Diagram Generator" agent:']}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-yaml",children:'# ... inside app_config ...\nagent_card:\n  description: "An agent that generates PNG images from Mermaid diagram syntax."\n  defaultInputModes: ["text"] # Expects Mermaid syntax as text\n  defaultOutputModes: ["text", "file"] # Confirms with text, outputs file artifact\n  skills:\n  - id: "mermaid_diagram_generator"\n    name: "Mermaid Diagram Generator"\n    description: "Generates a PNG image from Mermaid diagram syntax. Input: mermaid_syntax (string), output_filename (string, optional)."\n'})}),"\n",(0,i.jsxs)(n.p,{children:['This card clearly communicates that the agent can take text (the Mermaid syntax) and produce a file (the PNG image), and it details the specific "mermaid_diagram_generator" skill it offers. For more details on creating agents and configuring their cards, see ',(0,i.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/user-guide/create-agents",children:"Creating Custom Agents"}),"."]}),"\n",(0,i.jsx)(n.h2,{id:"user-defined-agents",children:"User-Defined Agents"}),"\n",(0,i.jsx)(n.p,{children:"Using Solace Agent Mesh and the Solace Agent Mesh CLI, you can create your own agents. Agents are configured through YAML files that specify:"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsx)(n.li,{children:"Agent name and instructions"}),"\n",(0,i.jsx)(n.li,{children:"LLM model configuration"}),"\n",(0,i.jsx)(n.li,{children:"Available tools and capabilities"}),"\n",(0,i.jsx)(n.li,{children:"Artifact and session management settings"}),"\n",(0,i.jsx)(n.li,{children:"Discovery settings"}),"\n"]}),"\n",(0,i.jsx)(n.p,{children:"The following Solace Agent Mesh CLI command creates an agent configuration:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-sh",children:"sam add agent my-agent [--gui]\n"})}),"\n",(0,i.jsxs)(n.p,{children:["For more information, see ",(0,i.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/user-guide/create-agents",children:"Creating Custom Agents"}),"."]}),"\n",(0,i.jsx)(n.h2,{id:"agent-plugins",children:"Agent Plugins"}),"\n",(0,i.jsx)(n.p,{children:"You can also use agents built by the community or Solace directly in your app with little to no configuration."}),"\n",(0,i.jsxs)(n.p,{children:["For more information, see ",(0,i.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/concepts/plugins#use-a-plugin",children:"Use a Plugin"}),"."]})]})}function h(e={}){const{wrapper:n}={...(0,a.R)(),...e.components};return n?(0,i.jsx)(n,{...e,children:(0,i.jsx)(d,{...e})}):d(e)}},8453:(e,n,t)=>{t.d(n,{R:()=>o,x:()=>r});var s=t(6540);const i={},a=s.createContext(i);function o(e){const n=s.useContext(a);return s.useMemo((function(){return"function"==typeof e?e(n):{...n,...e}}),[n,e])}function r(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(i):e.components||i:o(e.components),s.createElement(a.Provider,{value:n},e.children)}}}]);

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

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

solace_agent_mesh/assets/docs/assets/js/ae4415af.16cc58d3.js

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

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

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

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

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

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

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

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

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

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

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