solace-agent-mesh 1.7.0__py3-none-any.whl → 1.7.2__py3-none-any.whl

solace_agent_mesh/assets/docs/assets/js/15e40e79.36003774.js

@@ -1 +0,0 @@
-"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[6179],{5150:(e,n,s)=>{s.r(n),s.d(n,{assets:()=>a,contentTitle:()=>l,default:()=>h,frontMatter:()=>o,metadata:()=>i,toc:()=>c});const i=JSON.parse('{"id":"documentation/components/projects","title":"Projects","description":"Projects are a powerful organizational feature in Agent Mesh that enable users to group related chat sessions, manage artifacts and maintain context across multiple conversations. They provide a workspace-like environment for managing AI interactions around specific topics, tasks, or domains.","source":"@site/docs/documentation/components/projects.md","sourceDirName":"documentation/components","slug":"/documentation/components/projects","permalink":"/solace-agent-mesh/docs/documentation/components/projects","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/components/projects.md","tags":[],"version":"current","sidebarPosition":270,"frontMatter":{"title":"Projects","sidebar_position":270},"sidebar":"docSidebar","previous":{"title":"Plugins","permalink":"/solace-agent-mesh/docs/documentation/components/plugins"},"next":{"title":"Agent Mesh CLI","permalink":"/solace-agent-mesh/docs/documentation/components/cli"}}');var t=s(4848),r=s(8453);const o={title:"Projects",sidebar_position:270},l="Projects",a={},c=[{value:"Key Features",id:"key-features",level:2},{value:"How Projects Work",id:"how-projects-work",level:2},{value:"Project Components",id:"project-components",level:2},{value:"Project Metadata",id:"project-metadata",level:3},{value:"Chat Sessions",id:"chat-sessions",level:3},{value:"Knowledge (Artifacts)",id:"knowledge-artifacts",level:3},{value:"Configuration",id:"configuration",level:2},{value:"Disabling Projects",id:"disabling-projects",level:3},{value:"Feature Flag Control",id:"feature-flag-control",level:3},{value:"Soft Delete Pattern",id:"soft-delete-pattern",level:3},{value:"Best Practices",id:"best-practices",level:2},{value:"Project Organization",id:"project-organization",level:3},{value:"Knowledge Management",id:"knowledge-management",level:3},{value:"Session Management",id:"session-management",level:3},{value:"Troubleshooting",id:"troubleshooting",level:2},{value:"Projects Not Visible",id:"projects-not-visible",level:3},{value:"API Returns 501 Error",id:"api-returns-501-error",level:3},{value:"Search Not Working",id:"search-not-working",level:3},{value:"Performance Considerations",id:"performance-considerations",level:2},{value:"Database Optimization",id:"database-optimization",level:3},{value:"Artifact Storage",id:"artifact-storage",level:3},{value:"Search Performance",id:"search-performance",level:3},{value:"Security",id:"security",level:2},{value:"Authorization",id:"authorization",level:3},{value:"Data Privacy",id:"data-privacy",level:3},{value:"Related Documentation",id:"related-documentation",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,r.R)(),...e.components};return(0,t.jsxs)(t.Fragment,{children:[(0,t.jsx)(n.header,{children:(0,t.jsx)(n.h1,{id:"projects",children:"Projects"})}),"\n",(0,t.jsx)(n.p,{children:"Projects are a powerful organizational feature in Agent Mesh that enable users to group related chat sessions, manage artifacts and maintain context across multiple conversations. They provide a workspace-like environment for managing AI interactions around specific topics, tasks, or domains."}),"\n",(0,t.jsx)(n.admonition,{title:"In one sentence",type:"tip",children:(0,t.jsx)(n.p,{children:"Projects are organizational containers that group related chat sessions and knowledge artifacts together, enabling better context management and collaboration across multiple AI conversations."})}),"\n",(0,t.jsx)(n.h2,{id:"key-features",children:"Key Features"}),"\n",(0,t.jsxs)(n.ol,{children:["\n",(0,t.jsxs)(n.li,{children:["\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Session Organization"}),": Group related chat sessions under a single project for better organization and context management."]}),"\n"]}),"\n",(0,t.jsxs)(n.li,{children:["\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Knowledge Management"}),": Store and manage files, documents, and other artifacts that can be referenced across all sessions within a project."]}),"\n"]}),"\n",(0,t.jsxs)(n.li,{children:["\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Custom Instructions"}),": Define project-specific instructions (system prompt) that apply to all chat sessions within the project, ensuring consistent AI behavior."]}),"\n"]}),"\n",(0,t.jsxs)(n.li,{children:["\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Default Agent Configuration"}),": Set a default agent for the project, streamlining the chat creation process."]}),"\n"]}),"\n",(0,t.jsxs)(n.li,{children:["\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Soft Delete"}),": Projects and sessions can be safely deleted with the ability to recover them if needed (logical delete)."]}),"\n"]}),"\n",(0,t.jsxs)(n.li,{children:["\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Search Capabilities"}),": Search across all sessions within a project or across all projects to quickly find relevant conversations."]}),"\n"]}),"\n",(0,t.jsxs)(n.li,{children:["\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Session Mobility"}),": Move chat sessions between projects to reorganize your work as needs evolve."]}),"\n"]}),"\n"]}),"\n",(0,t.jsx)(n.h2,{id:"how-projects-work",children:"How Projects Work"}),"\n",(0,t.jsx)(n.p,{children:"Projects provide a hierarchical structure for organizing your AI interactions. Each project contains:"}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:"Project Metadata"}),": Name, description, system prompt, and default agent configuration"]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:"Chat Sessions"}),": Multiple conversation threads that inherit project settings"]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:"Project Knowledge"}),": Files and documents accessible across all sessions"]}),"\n"]}),"\n",(0,t.jsx)(n.h2,{id:"project-components",children:"Project Components"}),"\n",(0,t.jsx)(n.h3,{id:"project-metadata",children:"Project Metadata"}),"\n",(0,t.jsx)(n.p,{children:"Each project contains the following metadata:"}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:"Name"}),": A descriptive name for the project (required)"]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:"Description"}),": Optional detailed description of the project's purpose"]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:"System Prompt"}),": Custom instructions that apply to all chat sessions in the project"]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:"Default Agent"}),": The agent that will be used by default for new sessions in this project"]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:"Created/Updated Timestamps"}),": Automatic tracking of project creation and modification times"]}),"\n"]}),"\n",(0,t.jsx)(n.h3,{id:"chat-sessions",children:"Chat Sessions"}),"\n",(0,t.jsx)(n.p,{children:"Projects can contain multiple chat sessions, each representing a separate conversation thread. Sessions within a project:"}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsx)(n.li,{children:"Inherit the project's instructions (if defined)"}),"\n",(0,t.jsx)(n.li,{children:"Use the project's default agent (if specified)"}),"\n",(0,t.jsx)(n.li,{children:"Can access project-level artifacts"}),"\n",(0,t.jsx)(n.li,{children:"Can be moved between projects"}),"\n",(0,t.jsx)(n.li,{children:"Can be searched and filtered"}),"\n"]}),"\n",(0,t.jsx)(n.h3,{id:"knowledge-artifacts",children:"Knowledge (Artifacts)"}),"\n",(0,t.jsx)(n.p,{children:"Projects support two types of knowledge artifacts:"}),"\n",(0,t.jsxs)(n.ol,{children:["\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:"Project-Level Knowledge"}),': Files attached to the project itself (shown in the "Knowledge" section), accessible by all sessions']}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:"Session-Level Artifacts"}),": Files attached to specific chat sessions within the project"]}),"\n"]}),"\n",(0,t.jsx)(n.p,{children:"Knowledge artifacts can include:"}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsx)(n.li,{children:"Documents (PDF, DOCX, TXT, MD)"}),"\n",(0,t.jsx)(n.li,{children:"Images (PNG, JPG, GIF)"}),"\n",(0,t.jsx)(n.li,{children:"Code files"}),"\n",(0,t.jsx)(n.li,{children:"Data files (JSON, CSV, YAML)"}),"\n",(0,t.jsx)(n.li,{children:"Any other file type supported by the system"}),"\n"]}),"\n",(0,t.jsx)(n.h2,{id:"configuration",children:"Configuration"}),"\n",(0,t.jsx)(n.h3,{id:"disabling-projects",children:"Disabling Projects"}),"\n",(0,t.jsxs)(n.p,{children:["Projects require SQL database persistence to function. Configure persistence in your ",(0,t.jsx)(n.code,{children:"shared_config.yaml"}),":"]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-yaml",children:'session_service:\n  type: sql\n  database_url: "sqlite:///./data/sessions.db"\n'})}),"\n",(0,t.jsx)(n.p,{children:"Projects are enabled by default when persistence is configured. To disable the feature:"}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-yaml",children:"# Disable projects explicitly\nprojects:\n  enabled: false\n"})}),"\n",(0,t.jsx)(n.h3,{id:"feature-flag-control",children:"Feature Flag Control"}),"\n",(0,t.jsx)(n.p,{children:"You can also control projects via feature flags:"}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-yaml",children:"frontend_feature_enablement:\n  projects: false  # Disable projects\n  taskLogging: true\n"})}),"\n",(0,t.jsxs)(n.admonition,{title:"Configuration Priority",type:"note",children:[(0,t.jsx)(n.p,{children:"The feature flag resolution follows this priority:"}),(0,t.jsxs)(n.ol,{children:["\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:"Persistence Check"}),": If persistence is disabled, projects are disabled (non-negotiable)"]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:"Explicit Config"}),": ",(0,t.jsx)(n.code,{children:"projects.enabled"})," setting"]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:"Feature Flag"}),": ",(0,t.jsx)(n.code,{children:"frontend_feature_enablement.projects"})," setting"]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:"Default"}),": Enabled (if persistence is enabled and no explicit disable)"]}),"\n"]})]}),"\n",(0,t.jsx)(n.h3,{id:"soft-delete-pattern",children:"Soft Delete Pattern"}),"\n",(0,t.jsx)(n.p,{children:"Projects and sessions use a soft delete pattern for data preservation:"}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsxs)(n.li,{children:["Deleted items are marked with ",(0,t.jsx)(n.code,{children:"deleted_at"})," timestamp"]}),"\n",(0,t.jsx)(n.li,{children:"Deleted items are automatically filtered from queries"}),"\n",(0,t.jsx)(n.li,{children:"Data remains in database for audit trails"}),"\n",(0,t.jsx)(n.li,{children:"Can be recovered if needed"}),"\n"]}),"\n",(0,t.jsx)(n.h2,{id:"best-practices",children:"Best Practices"}),"\n",(0,t.jsx)(n.h3,{id:"project-organization",children:"Project Organization"}),"\n",(0,t.jsxs)(n.ol,{children:["\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:"Use Descriptive Names"}),": Give projects clear, descriptive names that reflect their purpose"]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:"Define Instructions"}),": Set project-specific instructions (system prompts) to ensure consistent AI behavior"]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:"Organize by Topic"}),": Group related conversations under the same project"]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:"Regular Cleanup"}),": Periodically review and delete unused projects"]}),"\n"]}),"\n",(0,t.jsx)(n.h3,{id:"knowledge-management",children:"Knowledge Management"}),"\n",(0,t.jsxs)(n.ol,{children:["\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:"Upload Relevant Files"}),": Only upload files that are relevant to the project in the Knowledge section"]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:"Use Metadata"}),": Add descriptions to knowledge artifacts for better organization"]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:"File Naming"}),": Use clear, descriptive filenames"]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:"Size Considerations"}),": Be mindful of file sizes for performance"]}),"\n"]}),"\n",(0,t.jsx)(n.h3,{id:"session-management",children:"Session Management"}),"\n",(0,t.jsxs)(n.ol,{children:["\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:"Move Sessions"}),": Reorganize sessions between projects as needs evolve"]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:"Use Search"}),": Leverage search to find relevant conversations quickly"]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:"Delete Unused Sessions"}),": Clean up old or irrelevant sessions"]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:"Consistent Naming"}),": Use clear session names for easier searching"]}),"\n"]}),"\n",(0,t.jsx)(n.h2,{id:"troubleshooting",children:"Troubleshooting"}),"\n",(0,t.jsx)(n.h3,{id:"projects-not-visible",children:"Projects Not Visible"}),"\n",(0,t.jsx)(n.p,{children:"If projects are not showing up in the UI:"}),"\n",(0,t.jsxs)(n.ol,{children:["\n",(0,t.jsxs)(n.li,{children:["\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Check Persistence Configuration"}),":"]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-yaml",children:"session_service:\n  type: sql  # Must be 'sql', not 'memory'\n"})}),"\n"]}),"\n",(0,t.jsxs)(n.li,{children:["\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Check if Projects are Explicitly Disabled"}),":"]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-yaml",children:"projects:\n  enabled: false  # Remove this line or set to true\n"})}),"\n"]}),"\n",(0,t.jsxs)(n.li,{children:["\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Check Feature Flags"}),":"]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-yaml",children:"frontend_feature_enablement:\n  projects: true  # Should be true or omitted\n"})}),"\n"]}),"\n",(0,t.jsxs)(n.li,{children:["\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Verify Config Endpoint"}),":"]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-bash",children:"curl http://localhost:8000/api/v1/config | jq '.frontend_feature_enablement.projects'\n"})}),"\n"]}),"\n"]}),"\n",(0,t.jsx)(n.h3,{id:"api-returns-501-error",children:"API Returns 501 Error"}),"\n",(0,t.jsx)(n.p,{children:"When project endpoints return 501 Not Implemented:"}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:"Persistence disabled"}),": Configure ",(0,t.jsx)(n.code,{children:"session_service.type: sql"})]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:"Explicitly disabled"}),": Remove ",(0,t.jsx)(n.code,{children:"projects.enabled: false"})," or set to ",(0,t.jsx)(n.code,{children:"true"})]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:"Feature flag disabled"}),": Set ",(0,t.jsx)(n.code,{children:"frontend_feature_enablement.projects: true"})]}),"\n"]}),"\n",(0,t.jsx)(n.h3,{id:"search-not-working",children:"Search Not Working"}),"\n",(0,t.jsx)(n.p,{children:"If session search is not returning results:"}),"\n",(0,t.jsxs)(n.ol,{children:["\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:"Check PostgreSQL Extension"}),": Ensure ",(0,t.jsx)(n.code,{children:"pg_trgm"})," extension is enabled"]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:"Verify Indexes"}),": Check that GIN indexes are created on search columns"]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:"Query Format"}),": Use simple search terms without special characters"]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:"Permissions"}),": Ensure user has access to the sessions being searched"]}),"\n"]}),"\n",(0,t.jsx)(n.h2,{id:"performance-considerations",children:"Performance Considerations"}),"\n",(0,t.jsx)(n.h3,{id:"database-optimization",children:"Database Optimization"}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:"Indexes"}),": Projects use indexes on ",(0,t.jsx)(n.code,{children:"user_id"}),", ",(0,t.jsx)(n.code,{children:"deleted_at"}),", and search columns"]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:"Eager Loading"}),": Related data is loaded efficiently to prevent N+1 queries"]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:"Pagination"}),": Search results are paginated to handle large datasets"]}),"\n"]}),"\n",(0,t.jsx)(n.h3,{id:"artifact-storage",children:"Artifact Storage"}),"\n",(0,t.jsxs)(n.p,{children:["Project artifacts use the configured artifact store. See ",(0,t.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/installing-and-configuring/configurations#artifact-service",children:"Configurations - Artifact Service"})," for more details."]}),"\n",(0,t.jsx)(n.h3,{id:"search-performance",children:"Search Performance"}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:"Full-Text Search"}),": Uses PostgreSQL ",(0,t.jsx)(n.code,{children:"pg_trgm"})," for efficient fuzzy matching"]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:"GIN Indexes"}),": Optimized indexes for fast text search"]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:"Query Optimization"}),": Subquery pattern avoids N+1 queries"]}),"\n"]}),"\n",(0,t.jsx)(n.h2,{id:"security",children:"Security"}),"\n",(0,t.jsx)(n.h3,{id:"authorization",children:"Authorization"}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsx)(n.li,{children:"All project operations validate user ownership"}),"\n",(0,t.jsx)(n.li,{children:"Sessions can only be moved to projects owned by the user"}),"\n",(0,t.jsx)(n.li,{children:"Knowledge artifacts are scoped to user and project/session context"}),"\n"]}),"\n",(0,t.jsx)(n.h3,{id:"data-privacy",children:"Data Privacy"}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsx)(n.li,{children:"Soft-deleted data remains in database (consider retention policies)"}),"\n",(0,t.jsx)(n.li,{children:"User ID tracked for all operations"}),"\n",(0,t.jsx)(n.li,{children:"Consider implementing hard delete for GDPR compliance"}),"\n"]}),"\n",(0,t.jsx)(n.h2,{id:"related-documentation",children:"Related Documentation"}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/components/gateways",children:"Gateways"})," - Learn about gateway configuration"]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/components/agents",children:"Agents"})," - Configure agents for your projects"]}),"\n"]})]})}function h(e={}){const{wrapper:n}={...(0,r.R)(),...e.components};return n?(0,t.jsx)(n,{...e,children:(0,t.jsx)(d,{...e})}):d(e)}},8453:(e,n,s)=>{s.d(n,{R:()=>o,x:()=>l});var i=s(6540);const t={},r=i.createContext(t);function o(e){const n=i.useContext(r);return i.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(t):e.components||t:o(e.components),i.createElement(r.Provider,{value:n},e.children)}}}]);

solace_agent_mesh/assets/docs/assets/js/66d4869e.830d443f.js

@@ -1 +0,0 @@
-"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[3243],{6009:(e,n,o)=>{o.r(n),o.d(n,{assets:()=>a,contentTitle:()=>s,default:()=>c,frontMatter:()=>r,metadata:()=>i,toc:()=>g});const i=JSON.parse('{"id":"documentation/deploying/logging","title":"Logging","description":"Agent Mesh uses Python\'s built-in logging module to provide flexible and powerful logging capabilities.","source":"@site/docs/documentation/deploying/logging.md","sourceDirName":"documentation/deploying","slug":"/documentation/deploying/logging","permalink":"/solace-agent-mesh/docs/documentation/deploying/logging","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/deploying/logging.md","tags":[],"version":"current","sidebarPosition":35,"frontMatter":{"title":"Logging","sidebar_position":35},"sidebar":"docSidebar","previous":{"title":"Diagnosing and Resolving Problems","permalink":"/solace-agent-mesh/docs/documentation/deploying/debugging"},"next":{"title":"Migration Guide: Upgrading to the A2A SDK","permalink":"/solace-agent-mesh/docs/documentation/migrations/a2a-upgrade/a2a-gateway-upgrade-to-0.3.0"}}');var t=o(4848),l=o(8453);const r={title:"Logging",sidebar_position:35},s="Logging",a={},g=[{value:"Configuration",id:"configuration",level:2},{value:"Default Logging Configuration",id:"default-logging-configuration",level:2},{value:"Understanding the Default Configuration",id:"understanding-the-default-configuration",level:3},{value:"Loggers",id:"loggers",level:3},{value:"Handlers",id:"handlers",level:3},{value:"Formatters",id:"formatters",level:3},{value:"Understanding Effective Log Levels",id:"understanding-effective-log-levels",level:3},{value:"Environment Variable Substitution",id:"environment-variable-substitution",level:2},{value:"Enabling Structured Logging",id:"enabling-structured-logging",level:2},{value:"Common Configuration Scenarios",id:"common-configuration-scenarios",level:2},{value:"Customizing Log Levels",id:"customizing-log-levels",level:3}];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,l.R)(),...e.components};return(0,t.jsxs)(t.Fragment,{children:[(0,t.jsx)(n.header,{children:(0,t.jsx)(n.h1,{id:"logging",children:"Logging"})}),"\n",(0,t.jsxs)(n.p,{children:["Agent Mesh uses ",(0,t.jsx)(n.a,{href:"https://docs.python.org/3/library/logging.html",children:"Python's built-in logging module"})," to provide flexible and powerful logging capabilities."]}),"\n",(0,t.jsx)(n.p,{children:"Understanding logging configuration is essential for troubleshooting, monitoring system behavior, and maintaining production deployments. This guide covers everything you need to effectively configure and manage logging in your Agent Mesh applications."}),"\n",(0,t.jsx)(n.h2,{id:"configuration",children:"Configuration"}),"\n",(0,t.jsx)(n.p,{children:"The logging system is configured through an INI-based configuration file that gives you fine-grained control over log levels, output destinations, and formatting options."}),"\n",(0,t.jsx)(n.p,{children:"This approach provides several advantages:"}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:"Centralized Control"}),": Single configuration file manages logging for all components"]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:"Python Native"}),": Built on Python's standard ",(0,t.jsx)(n.code,{children:"logging"})," module"]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:"Flexible and Powerful"}),": Full access to Python's logging capabilities"]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:"Production-Ready"}),": Industry-standard approach used by many Python applications"]}),"\n"]}),"\n",(0,t.jsxs)(n.p,{children:["To provide a logging configuration, set the ",(0,t.jsx)(n.code,{children:"LOGGING_CONFIG_PATH=path/to/logging_config.ini"})," environment variable in your ",(0,t.jsx)(n.code,{children:".env"})," file or with the ",(0,t.jsx)(n.code,{children:"export"})," command."]}),"\n",(0,t.jsxs)(n.admonition,{title:"INI vs YAML Configuration",type:"info",children:[(0,t.jsxs)(n.p,{children:["While individual agent and gateway YAML files may contain a ",(0,t.jsx)(n.code,{children:"log:"})," section:"]}),(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{children:"log:\n  stdout_log_level: INFO\n  log_file_level: INFO\n  log_file: my-agent.log\n"})}),(0,t.jsx)(n.p,{children:"the INI-based configuration is the recommended and preferred approach. YAML configuration has lower precedence and will only be active when INI-based configuration is not enabled."})]}),"\n",(0,t.jsx)(n.h2,{id:"default-logging-configuration",children:"Default Logging Configuration"}),"\n",(0,t.jsxs)(n.p,{children:["When you run ",(0,t.jsx)(n.code,{children:"sam init"}),", Agent Mesh automatically generates a ",(0,t.jsx)(n.code,{children:"configs/logging_config.ini"})," file in your project directory. This file establishes sensible defaults while remaining easy to customize for your specific needs."]}),"\n",(0,t.jsx)(n.h3,{id:"understanding-the-default-configuration",children:"Understanding the Default Configuration"}),"\n",(0,t.jsxs)(n.p,{children:["Here's the default ",(0,t.jsx)(n.code,{children:"logging_config.ini"})," generated by ",(0,t.jsx)(n.code,{children:"sam init"}),", with annotations explaining each section:"]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-ini",children:"# Lists all configured loggers in this file\n[loggers]\nkeys=root,solace_ai_connector,solace_agent_mesh,sam_trace\n\n# Root logger - applies to all modules (including external libraries) that do not have a specific logger configured. \n# The root logger also specifies handlers for the application.\n[logger_root]\nlevel=${LOGGING_ROOT_LEVEL, WARNING}\nhandlers=streamHandler,rotatingFileHandler\nqualname=root\n\n# Main logger for the solace-ai-connector module\n[logger_solace_ai_connector]\nlevel=${LOGGING_SOLACE_AI_CONNECTOR_LEVEL, INFO}\nhandlers=\nqualname=solace_ai_connector\n\n# Main logger for the solace-agent-mesh module\n[logger_solace_agent_mesh]\nlevel=${LOGGING_SAM_LEVEL, INFO}\nhandlers=\nqualname=solace_agent_mesh\n\n# Special trace logger for detailed troubleshooting. Set to DEBUG to enable.\n[logger_sam_trace]\nlevel=${LOGGING_SAM_TRACE_LEVEL, INFO}\nhandlers=\nqualname=sam_trace\n\n# Lists all configured handlers in this file\n[handlers]\nkeys=streamHandler,rotatingFileHandler\n\n# Rotating file handler - writes to log files with automatic rotation\n[handler_rotatingFileHandler]\nclass=logging.handlers.RotatingFileHandler\nformatter=simpleFormatter\nargs=('sam.log', 'a', 52428800, 10)\n\n# Stream handler - outputs logs to console (stdout)\n[handler_streamHandler]\nclass=StreamHandler\nformatter=simpleFormatter\nargs=(sys.stdout,)\n\n# Lists all configured formatters in this file\n[formatters]\nkeys=simpleFormatter,jsonFormatter\n\n# Simple human-readable format\n[formatter_simpleFormatter]\nformat=%(asctime)s | %(levelname)-5s | %(threadName)s | %(name)s | %(message)s\n\n# JSON format for structured logging\n[formatter_jsonFormatter]\nclass=pythonjsonlogger.jsonlogger.JsonFormatter\nformat=%(asctime)s %(levelname)s %(threadName)s %(name)s %(message)s\n"})}),"\n",(0,t.jsx)(n.h3,{id:"loggers",children:"Loggers"}),"\n",(0,t.jsx)(n.p,{children:"Loggers are organized in a hierarchical namespace using dot-separated names, forming a tree structure where child loggers inherit configuration from their parents. When a logger is asked to handle a log record, it propagates the record up through the logger hierarchy until it reaches a logger with handlers configured or reaches the root logger."}),"\n",(0,t.jsx)(n.h3,{id:"handlers",children:"Handlers"}),"\n",(0,t.jsx)(n.p,{children:"Handlers determine where log messages go. The default configuration includes:"}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:(0,t.jsx)(n.code,{children:"streamHandler"})}),": Outputs logs to the console (stdout) for immediate visibility"]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:(0,t.jsx)(n.code,{children:"rotatingFileHandler"})}),": Writes logs to files with automatic rotation when size limits are reached. The rotating file handler is configured with these parameters (in the ",(0,t.jsx)(n.code,{children:"args"})," tuple):","\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:"Filename"}),": ",(0,t.jsx)(n.code,{children:"sam.log"})," - the base log file name"]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:"Mode"}),": ",(0,t.jsx)(n.code,{children:"'a'"})," - append mode (don't overwrite existing logs)"]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:"Max Size"}),": ",(0,t.jsx)(n.code,{children:"52428800"})," bytes (50 MB) - rotate when file reaches this size"]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:"Backup Count"}),": ",(0,t.jsx)(n.code,{children:"10"})," - keep up to 10 historical log files"]}),"\n"]}),"\n"]}),"\n"]}),"\n",(0,t.jsxs)(n.p,{children:["For complete details on handlers, see Python's ",(0,t.jsx)(n.a,{href:"https://docs.python.org/3/library/logging.handlers.html",children:"supported handlers documentation"})]}),"\n",(0,t.jsx)(n.h3,{id:"formatters",children:"Formatters"}),"\n",(0,t.jsx)(n.p,{children:"Formatters control the structure and appearance of log messages:"}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:(0,t.jsx)(n.code,{children:"simpleFormatter"})}),": Human-readable format including timestamp, level, thread, logger name, and message"]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:(0,t.jsx)(n.code,{children:"jsonFormatter"})}),": Structured JSON format for log aggregation and analysis tools"]}),"\n"]}),"\n",(0,t.jsxs)(n.p,{children:["For complete details on formatters and available fields, see Python's ",(0,t.jsx)(n.a,{href:"https://docs.python.org/3/library/logging.html#logrecord-attributes",children:"LogRecord attributes documentation"}),"."]}),"\n",(0,t.jsx)(n.h3,{id:"understanding-effective-log-levels",children:"Understanding Effective Log Levels"}),"\n",(0,t.jsx)(n.p,{children:"The effective log level for a logger is determined by the most specific configuration in the logger hierarchy. If a logger doesn't have a level explicitly set, it inherits from its parent. The root logger applies to all modules that do not have a logger defined."}),"\n",(0,t.jsx)(n.p,{children:"For example, if you set the root logger to DEBUG but create a more specific logger for solace_ai_connector at the INFO level, the effective log level for the solace_ai_connector module will be INFO. This means DEBUG level logs from solace_ai_connector will not be handled, as they fall below the effective log level."}),"\n",(0,t.jsx)(n.h2,{id:"environment-variable-substitution",children:"Environment Variable Substitution"}),"\n",(0,t.jsx)(n.p,{children:"The INI configuration supports environment variable substitution using the syntax:"}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-ini",children:"${VARIABLE_NAME, default_value}\n"})}),"\n",(0,t.jsx)(n.p,{children:"Users can use variable names of their choice; the application will look for these environment variables at runtime and substitute their values accordingly. If the environment variable is not set, the provided default value will be used."}),"\n",(0,t.jsx)(n.h2,{id:"enabling-structured-logging",children:"Enabling Structured Logging"}),"\n",(0,t.jsx)(n.p,{children:"Structured logging outputs log messages in JSON format, making them easier to parse, search, and analyze with log aggregation tools."}),"\n",(0,t.jsxs)(n.p,{children:["To enable JSON logging, modify the handler configurations to use ",(0,t.jsx)(n.code,{children:"jsonFormatter"})," instead of ",(0,t.jsx)(n.code,{children:"simpleFormatter"}),":"]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-ini",children:"[handler_rotatingFileHandler]\nclass=logging.handlers.RotatingFileHandler\nformatter=jsonFormatter  # Changed from simpleFormatter\nargs=('sam.log', 'a', 52428800, 10)\n\n[handler_streamHandler]\nclass=StreamHandler\nformatter=simpleFormatter  # Kept as simpleFormatter to show handlers can have different formatters\nargs=(sys.stdout,)\n"})}),"\n",(0,t.jsx)(n.h2,{id:"common-configuration-scenarios",children:"Common Configuration Scenarios"}),"\n",(0,t.jsx)(n.h3,{id:"customizing-log-levels",children:"Customizing Log Levels"}),"\n",(0,t.jsx)(n.p,{children:"You can add loggers to control the log level of specific modules or external libraries in your application. This allows you to increase verbosity for troubleshooting specific components while keeping other parts of the system quiet."}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-ini",children:"# Add to the loggers list\n[loggers]\nkeys=root,solace_ai_connector,solace_agent_mesh,sam_trace,my_logger,google_adk\n\n[logger_root]\nlevel=WARNING\nhandlers=streamHandler,rotatingFileHandler\nqualname=root\n\n[ some loggers were omitted ]\n\n# Increase verbosity of a specific package\n[logger_my_logger]\nlevel=DEBUG\nhandlers=\nqualname=solace_agent_mesh.gateway.http_sse\n\n# Increase verbosity of a specific external library\n[logger_google_adk]\nlevel=INFO\nhandlers=\nqualname=google_adk\n"})}),"\n",(0,t.jsxs)(n.admonition,{title:"Discovering Logger Names",type:"tip",children:[(0,t.jsxs)(n.p,{children:["To discover what logger names are available to control, temporarily set the root logger level to ",(0,t.jsx)(n.code,{children:"DEBUG"})," and run your application. The logger names will be visible in the actual log output (shown in the logger name field). This is particularly useful for identifying logger names from external libraries you want to control."]}),(0,t.jsx)(n.p,{children:"Once you've identified the logger names you need, you can:"}),(0,t.jsxs)(n.ol,{children:["\n",(0,t.jsxs)(n.li,{children:["Set the root logger level back to ",(0,t.jsx)(n.code,{children:"WARNING"})," to reduce overall verbosity"]}),"\n",(0,t.jsx)(n.li,{children:"Add specific logger configurations for the modules/library you want to monitor with increased verbosity"}),"\n"]}),(0,t.jsx)(n.p,{children:"This approach keeps your logs clean while giving you detailed visibility into the specific components you're troubleshooting."})]})]})}function c(e={}){const{wrapper:n}={...(0,l.R)(),...e.components};return n?(0,t.jsx)(n,{...e,children:(0,t.jsx)(d,{...e})}):d(e)}},8453:(e,n,o)=>{o.d(n,{R:()=>r,x:()=>s});var i=o(6540);const t={},l=i.createContext(t);function r(e){const n=i.useContext(l);return i.useMemo((function(){return"function"==typeof e?e(n):{...n,...e}}),[n,e])}function s(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(t):e.components||t:r(e.components),i.createElement(l.Provider,{value:n},e.children)}}}]);

solace_agent_mesh/assets/docs/assets/js/82fbfb93.139a1a1f.js

@@ -1 +0,0 @@
-"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[3257],{8556:(e,n,o)=>{o.r(n),o.d(n,{assets:()=>l,contentTitle:()=>r,default:()=>u,frontMatter:()=>a,metadata:()=>t,toc:()=>d});const t=JSON.parse('{"id":"documentation/deploying/deploying","title":"Deploying Agent Mesh","description":"Moving your Agent Mesh from development to production requires careful consideration of deployment strategies, monitoring capabilities, and troubleshooting approaches. Understanding your options and having robust observability tools ensures your agent mesh operates reliably at scale.","source":"@site/docs/documentation/deploying/deploying.md","sourceDirName":"documentation/deploying","slug":"/documentation/deploying/","permalink":"/solace-agent-mesh/docs/documentation/deploying/","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/deploying/deploying.md","tags":[],"version":"current","sidebarPosition":500,"frontMatter":{"title":"Deploying Agent Mesh","sidebar_position":500},"sidebar":"docSidebar","previous":{"title":"RAG Integration","permalink":"/solace-agent-mesh/docs/documentation/developing/tutorials/rag-integration"},"next":{"title":"Choosing Deployment Options","permalink":"/solace-agent-mesh/docs/documentation/deploying/deployment-options"}}');var i=o(4848),s=o(8453);const a={title:"Deploying Agent Mesh",sidebar_position:500},r="Deploying Agent Mesh",l={},d=[{value:"Selecting Your Deployment Strategy",id:"selecting-your-deployment-strategy",level:2},{value:"Observing Your Agent Mesh",id:"observing-your-agent-mesh",level:2},{value:"Troubleshooting and Debugging Issues",id:"troubleshooting-and-debugging-issues",level:2},{value:"Production Readiness Considerations",id:"production-readiness-considerations",level:2}];function c(e){const n={a:"a",h1:"h1",h2:"h2",header:"header",p:"p",...(0,s.R)(),...e.components};return(0,i.jsxs)(i.Fragment,{children:[(0,i.jsx)(n.header,{children:(0,i.jsx)(n.h1,{id:"deploying-agent-mesh",children:"Deploying Agent Mesh"})}),"\n",(0,i.jsx)(n.p,{children:"Moving your Agent Mesh from development to production requires careful consideration of deployment strategies, monitoring capabilities, and troubleshooting approaches. Understanding your options and having robust observability tools ensures your agent mesh operates reliably at scale."}),"\n",(0,i.jsx)(n.h2,{id:"selecting-your-deployment-strategy",children:"Selecting Your Deployment Strategy"}),"\n",(0,i.jsxs)(n.p,{children:["Production deployments require different considerations than development environments, particularly around scalability, reliability, and security. You can choose containerized deployments using Docker for single-node setups, Kubernetes orchestration for scalable architectures, or hybrid approaches that separate components for independent scaling. Each strategy offers distinct advantages depending on your operational requirements. For comprehensive guidance on evaluating and implementing these approaches, see ",(0,i.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/deploying/deployment-options",children:"Choosing Deployment Options"}),"."]}),"\n",(0,i.jsx)(n.h2,{id:"observing-your-agent-mesh",children:"Observing Your Agent Mesh"}),"\n",(0,i.jsxs)(n.p,{children:["Effective monitoring provides the visibility you need to understand system behavior and maintain optimal operation. The platform offers multiple observability layers that create a complete picture of your system's health. You can visualize request workflows through interactive diagrams, monitor real-time agent status, track message flows at the event broker level, and analyze detailed stimulus logs for forensic analysis. For detailed information on implementing these monitoring tools, see ",(0,i.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/deploying/observability",children:"Monitoring Your Agent Mesh"}),"."]}),"\n",(0,i.jsx)(n.h2,{id:"troubleshooting-and-debugging-issues",children:"Troubleshooting and Debugging Issues"}),"\n",(0,i.jsxs)(n.p,{children:["When issues arise in distributed systems, systematic debugging approaches help you quickly identify root causes. The debugging process leverages observability tools in focused ways to isolate problems and understand their causes. You can isolate specific components to reduce complexity, examine stimulus traces for detailed analysis, monitor real-time event broker activity, use interactive debugging tools for code investigation, and invoke agents directly for controlled testing. For step-by-step guidance on applying these strategies, see ",(0,i.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/deploying/debugging",children:"Diagnosing and Resolving Problems"}),"."]}),"\n",(0,i.jsx)(n.h2,{id:"production-readiness-considerations",children:"Production Readiness Considerations"}),"\n",(0,i.jsx)(n.p,{children:"Successful production deployments require attention to security, performance, and operational practices beyond basic functionality. Consider implementing robust secret management, establishing TLS encryption for all communication channels, configuring appropriate resource limits and scaling policies, setting up automated backup procedures, and creating runbooks for common scenarios. These practices ensure your agent mesh operates reliably and securely while providing the foundation for ongoing maintenance and optimization."})]})}function u(e={}){const{wrapper:n}={...(0,s.R)(),...e.components};return n?(0,i.jsx)(n,{...e,children:(0,i.jsx)(c,{...e})}):c(e)}},8453:(e,n,o)=>{o.d(n,{R:()=>a,x:()=>r});var t=o(6540);const i={},s=t.createContext(i);function a(e){const n=t.useContext(s);return t.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:a(e.components),t.createElement(s.Provider,{value:n},e.children)}}}]);

solace_agent_mesh/assets/docs/assets/js/924ffdeb.8095e148.js

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

solace_agent_mesh/assets/docs/assets/js/c93cbaa0.eaff365e.js

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

solace_agent_mesh/assets/docs/assets/js/f284c35a.5099c51e.js

@@ -1 +0,0 @@
-"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[3011],{8549:e=>{e.exports=JSON.parse('{"version":{"pluginId":"default","version":"current","label":"Next","banner":null,"badge":false,"noIndex":false,"className":"docs-version-current","isLast":true,"docsSidebars":{"docSidebar":[{"type":"category","label":"Getting Started","collapsible":true,"collapsed":false,"items":[{"type":"link","label":"What is Agent Mesh?","href":"/solace-agent-mesh/docs/documentation/getting-started/introduction","docId":"documentation/getting-started/introduction","unlisted":false},{"type":"link","label":"Try Agent Mesh","href":"/solace-agent-mesh/docs/documentation/getting-started/try-agent-mesh","docId":"documentation/getting-started/try-agent-mesh","unlisted":false},{"type":"link","label":"Architecture Overview","href":"/solace-agent-mesh/docs/documentation/getting-started/architecture","docId":"documentation/getting-started/architecture","unlisted":false}],"href":"/solace-agent-mesh/docs/documentation/getting-started/"},{"type":"category","label":"Components","collapsible":true,"collapsed":true,"items":[{"type":"link","label":"Agents","href":"/solace-agent-mesh/docs/documentation/components/agents","docId":"documentation/components/agents","unlisted":false},{"type":"link","label":"Orchestrator","href":"/solace-agent-mesh/docs/documentation/components/orchestrator","docId":"documentation/components/orchestrator","unlisted":false},{"type":"link","label":"Proxies","href":"/solace-agent-mesh/docs/documentation/components/proxies","docId":"documentation/components/proxies","unlisted":false},{"type":"link","label":"Gateways","href":"/solace-agent-mesh/docs/documentation/components/gateways","docId":"documentation/components/gateways","unlisted":false},{"type":"link","label":"Plugins","href":"/solace-agent-mesh/docs/documentation/components/plugins","docId":"documentation/components/plugins","unlisted":false},{"type":"link","label":"Projects","href":"/solace-agent-mesh/docs/documentation/components/projects","docId":"documentation/components/projects","unlisted":false},{"type":"link","label":"Agent Mesh CLI","href":"/solace-agent-mesh/docs/documentation/components/cli","docId":"documentation/components/cli","unlisted":false},{"type":"category","label":"Built-in Tools","collapsible":true,"collapsed":true,"items":[{"type":"link","label":"Artifact Management Tools","href":"/solace-agent-mesh/docs/documentation/components/builtin-tools/artifact-management","docId":"documentation/components/builtin-tools/artifact-management","unlisted":false},{"type":"link","label":"Data Analysis Tools","href":"/solace-agent-mesh/docs/documentation/components/builtin-tools/data-analysis-tools","docId":"documentation/components/builtin-tools/data-analysis-tools","unlisted":false},{"type":"link","label":"Audio Tools","href":"/solace-agent-mesh/docs/documentation/components/builtin-tools/audio-tools","docId":"documentation/components/builtin-tools/audio-tools","unlisted":false},{"type":"link","label":"Dynamic Embeds","href":"/solace-agent-mesh/docs/documentation/components/builtin-tools/embeds","docId":"documentation/components/builtin-tools/embeds","unlisted":false}],"href":"/solace-agent-mesh/docs/documentation/components/builtin-tools/"}],"href":"/solace-agent-mesh/docs/documentation/components/"},{"type":"category","label":"Installing and Configuring Agent Mesh","collapsible":true,"collapsed":true,"items":[{"type":"link","label":"Installing Agent Mesh","href":"/solace-agent-mesh/docs/documentation/installing-and-configuring/installation","docId":"documentation/installing-and-configuring/installation","unlisted":false},{"type":"link","label":"Creating and Running an Agent Mesh Project","href":"/solace-agent-mesh/docs/documentation/installing-and-configuring/run-project","docId":"documentation/installing-and-configuring/run-project","unlisted":false},{"type":"link","label":"Configuring Agent Mesh","href":"/solace-agent-mesh/docs/documentation/installing-and-configuring/configurations","docId":"documentation/installing-and-configuring/configurations","unlisted":false},{"type":"link","label":"Configuring LLMs","href":"/solace-agent-mesh/docs/documentation/installing-and-configuring/large_language_models","docId":"documentation/installing-and-configuring/large_language_models","unlisted":false},{"type":"link","label":"User Feedback","href":"/solace-agent-mesh/docs/documentation/installing-and-configuring/user-feedback","docId":"documentation/installing-and-configuring/user-feedback","unlisted":false},{"type":"link","label":"Session Storage","href":"/solace-agent-mesh/docs/documentation/installing-and-configuring/session-storage","docId":"documentation/installing-and-configuring/session-storage","unlisted":false},{"type":"link","label":"Artifact Storage","href":"/solace-agent-mesh/docs/documentation/installing-and-configuring/artifact-storage","docId":"documentation/installing-and-configuring/artifact-storage","unlisted":false}],"href":"/solace-agent-mesh/docs/documentation/installing-and-configuring/"},{"type":"category","label":"Developing with Agent Mesh","collapsible":true,"collapsed":true,"items":[{"type":"link","label":"Project Structure","href":"/solace-agent-mesh/docs/documentation/developing/structure","docId":"documentation/developing/structure","unlisted":false},{"type":"link","label":"Creating Agents","href":"/solace-agent-mesh/docs/documentation/developing/create-agents","docId":"documentation/developing/create-agents","unlisted":false},{"type":"link","label":"Creating Custom Gateways","href":"/solace-agent-mesh/docs/documentation/developing/create-gateways","docId":"documentation/developing/create-gateways","unlisted":false},{"type":"link","label":"Creating Python Tools","href":"/solace-agent-mesh/docs/documentation/developing/creating-python-tools","docId":"documentation/developing/creating-python-tools","unlisted":false},{"type":"link","label":"Creating Service Providers","href":"/solace-agent-mesh/docs/documentation/developing/creating-service-providers","docId":"documentation/developing/creating-service-providers","unlisted":false},{"type":"link","label":"Evaluating Agents","href":"/solace-agent-mesh/docs/documentation/developing/evaluations","docId":"documentation/developing/evaluations","unlisted":false},{"type":"category","label":"Tutorials","collapsible":true,"collapsed":true,"items":[{"type":"link","label":"Build Your Own Agent","href":"/solace-agent-mesh/docs/documentation/developing/tutorials/custom-agent","docId":"documentation/developing/tutorials/custom-agent","unlisted":false},{"type":"link","label":"MCP Integration","href":"/solace-agent-mesh/docs/documentation/developing/tutorials/mcp-integration","docId":"documentation/developing/tutorials/mcp-integration","unlisted":false},{"type":"link","label":"REST Gateway","href":"/solace-agent-mesh/docs/documentation/developing/tutorials/rest-gateway","docId":"documentation/developing/tutorials/rest-gateway","unlisted":false},{"type":"link","label":"Event Mesh Gateway","href":"/solace-agent-mesh/docs/documentation/developing/tutorials/event-mesh-gateway","docId":"documentation/developing/tutorials/event-mesh-gateway","unlisted":false},{"type":"link","label":"Amazon Bedrock Agents","href":"/solace-agent-mesh/docs/documentation/developing/tutorials/bedrock-agents","docId":"documentation/developing/tutorials/bedrock-agents","unlisted":false},{"type":"link","label":"SQL Database Integration","href":"/solace-agent-mesh/docs/documentation/developing/tutorials/sql-database","docId":"documentation/developing/tutorials/sql-database","unlisted":false},{"type":"link","label":"MongoDB Integration","href":"/solace-agent-mesh/docs/documentation/developing/tutorials/mongodb-integration","docId":"documentation/developing/tutorials/mongodb-integration","unlisted":false},{"type":"link","label":"Slack Integration","href":"/solace-agent-mesh/docs/documentation/developing/tutorials/slack-integration","docId":"documentation/developing/tutorials/slack-integration","unlisted":false},{"type":"link","label":"RAG Integration","href":"/solace-agent-mesh/docs/documentation/developing/tutorials/rag-integration","docId":"documentation/developing/tutorials/rag-integration","unlisted":false}]}],"href":"/solace-agent-mesh/docs/documentation/developing/"},{"type":"category","label":"Deploying Agent Mesh","collapsible":true,"collapsed":true,"items":[{"type":"link","label":"Choosing Deployment Options","href":"/solace-agent-mesh/docs/documentation/deploying/deployment-options","docId":"documentation/deploying/deployment-options","unlisted":false},{"type":"link","label":"Kubernetes","href":"/solace-agent-mesh/docs/documentation/deploying/kubernetes-deployment","docId":"documentation/deploying/kubernetes-deployment","unlisted":false},{"type":"link","label":"Monitoring Your Agent Mesh","href":"/solace-agent-mesh/docs/documentation/deploying/observability","docId":"documentation/deploying/observability","unlisted":false},{"type":"link","label":"Diagnosing and Resolving Problems","href":"/solace-agent-mesh/docs/documentation/deploying/debugging","docId":"documentation/deploying/debugging","unlisted":false},{"type":"link","label":"Logging","href":"/solace-agent-mesh/docs/documentation/deploying/logging","docId":"documentation/deploying/logging","unlisted":false}],"href":"/solace-agent-mesh/docs/documentation/deploying/"},{"type":"category","label":"Migrations","collapsible":true,"collapsed":true,"items":[{"type":"category","label":"A2A Upgrade to 0.3.0","collapsible":true,"collapsed":true,"items":[{"type":"link","label":"Migration Guide: Upgrading to the A2A SDK","href":"/solace-agent-mesh/docs/documentation/migrations/a2a-upgrade/a2a-gateway-upgrade-to-0.3.0","docId":"documentation/migrations/a2a-upgrade/a2a-gateway-upgrade-to-0.3.0","unlisted":false},{"type":"link","label":"A2A Technical Migration Map","href":"/solace-agent-mesh/docs/documentation/migrations/a2a-upgrade/a2a-technical-migration-map","docId":"documentation/migrations/a2a-upgrade/a2a-technical-migration-map","unlisted":false}]}]},{"type":"category","label":"Agent Mesh Enterprise","collapsible":true,"collapsed":true,"items":[{"type":"link","label":"Installing Agent Mesh Enterprise","href":"/solace-agent-mesh/docs/documentation/enterprise/installation","docId":"documentation/enterprise/installation","unlisted":false},{"type":"link","label":"Running from Wheel File","href":"/solace-agent-mesh/docs/documentation/enterprise/wheel-installation","docId":"documentation/enterprise/wheel-installation","unlisted":false},{"type":"link","label":"Agent Builder","href":"/solace-agent-mesh/docs/documentation/enterprise/agent-builder","docId":"documentation/enterprise/agent-builder","unlisted":false},{"type":"link","label":"Connectors","href":"/solace-agent-mesh/docs/documentation/enterprise/connectors/","docId":"documentation/enterprise/connectors/connectors","unlisted":false},{"type":"link","label":"Setting Up RBAC","href":"/solace-agent-mesh/docs/documentation/enterprise/rbac-setup-guide","docId":"documentation/enterprise/rbac-setup-guide","unlisted":false},{"type":"link","label":"Enabling SSO","href":"/solace-agent-mesh/docs/documentation/enterprise/single-sign-on","docId":"documentation/enterprise/single-sign-on","unlisted":false},{"type":"link","label":"Secure User Delegated Access","href":"/solace-agent-mesh/docs/documentation/enterprise/secure-user-delegated-access","docId":"documentation/enterprise/secure-user-delegated-access","unlisted":false}],"href":"/solace-agent-mesh/docs/documentation/enterprise/"}]},"docs":{"documentation/components/agents":{"id":"documentation/components/agents","title":"Agents","description":"Agents are specialized processing units within the Agent Mesh framework that are built around the Google Agent Development Kit (ADK) and provide the core intelligence layer. They:","sidebar":"docSidebar"},"documentation/components/builtin-tools/artifact-management":{"id":"documentation/components/builtin-tools/artifact-management","title":"Artifact Management Tools","description":"This guide details how agents utilize built-in tools to manage file artifacts and their associated metadata. The system employs an explicit, metadata-aware methodology wherein the agent maintains full control over the lifecycle of artifacts, including their creation, listing, loading, and return.","sidebar":"docSidebar"},"documentation/components/builtin-tools/audio-tools":{"id":"documentation/components/builtin-tools/audio-tools","title":"Audio Tools","description":"This guide provides technical documentation for the text-to-speech (TTS) tools available in Agent Mesh.","sidebar":"docSidebar"},"documentation/components/builtin-tools/builtin-tools":{"id":"documentation/components/builtin-tools/builtin-tools","title":"Configuring Built-in Tools","description":"This guide provides instructions for enabling and configuring the built-in tools provided by Agent Mesh framework.","sidebar":"docSidebar"},"documentation/components/builtin-tools/data-analysis-tools":{"id":"documentation/components/builtin-tools/data-analysis-tools","title":"Data Analysis Tools","description":"Agent Mesh includes a suite of optional built-in tools that enable agents to perform data analysis tasks directly on artifacts. These tools provide functionality for SQL querying, JQ transformations, and Plotly chart generation.","sidebar":"docSidebar"},"documentation/components/builtin-tools/embeds":{"id":"documentation/components/builtin-tools/embeds","title":"Dynamic Embeds","description":"Dynamic Embeds","sidebar":"docSidebar"},"documentation/components/cli":{"id":"documentation/components/cli","title":"Agent Mesh CLI","description":"Agent Mesh comes with a comprehensive CLI tool that you can use to create, and run an instance of Agent Mesh, which is referred to as an Agent Mesh application. Agent Mesh CLI also allows you to add agents and gateways, manage plugins, help you debug, and much more.","sidebar":"docSidebar"},"documentation/components/components":{"id":"documentation/components/components","title":"Components","description":"Agent Mesh provides a comprehensive set of components that work together to create a distributed AI agent ecosystem. Each component serves a specific purpose, from managing the command-line interface to orchestrating complex multi-agent workflows.","sidebar":"docSidebar"},"documentation/components/gateways":{"id":"documentation/components/gateways","title":"Gateways","description":"Gateways are a crucial component of the Agent Mesh framework that expose the agent mesh to external systems through various protocols. Built on a common base gateway architecture, they provide the following functions:","sidebar":"docSidebar"},"documentation/components/orchestrator":{"id":"documentation/components/orchestrator","title":"Orchestrator","description":"The A2A (Agent-to-Agent) protocol is the communication backbone of Agent Mesh that enables distributed agent coordination and workflow management. Unlike traditional centralized orchestration, the A2A protocol enables agents to discover each other, delegate tasks, and collaborate directly through standardized message patterns.","sidebar":"docSidebar"},"documentation/components/plugins":{"id":"documentation/components/plugins","title":"Plugins","description":"Plugins provide a mechanism to extend the functionality of Agent Mesh in a modular, shareable, and reusable way. The current plugin ecosystem includes agents, gateways, and specialized integrations.","sidebar":"docSidebar"},"documentation/components/projects":{"id":"documentation/components/projects","title":"Projects","description":"Projects are a powerful organizational feature in Agent Mesh that enable users to group related chat sessions, manage artifacts and maintain context across multiple conversations. They provide a workspace-like environment for managing AI interactions around specific topics, tasks, or domains.","sidebar":"docSidebar"},"documentation/components/proxies":{"id":"documentation/components/proxies","title":"Proxies","description":"Proxies act as protocol bridges that connect Agent Mesh to external A2A agents. By translating between A2A over Solace event mesh and A2A over HTTPS protocols, proxies enable agents within the mesh to delegate tasks to external agents and include them in collaborative workflows.","sidebar":"docSidebar"},"documentation/deploying/debugging":{"id":"documentation/deploying/debugging","title":"Diagnosing and Resolving Problems","description":"Effective debugging in Agent Mesh requires a systematic approach that leverages the platform\'s distributed architecture. Because your system consists of multiple agents communicating through a Solace event broker, issues can arise at various levels\u2014from individual agent logic to inter-component communication patterns.","sidebar":"docSidebar"},"documentation/deploying/deploying":{"id":"documentation/deploying/deploying","title":"Deploying Agent Mesh","description":"Moving your Agent Mesh from development to production requires careful consideration of deployment strategies, monitoring capabilities, and troubleshooting approaches. Understanding your options and having robust observability tools ensures your agent mesh operates reliably at scale.","sidebar":"docSidebar"},"documentation/deploying/deployment-options":{"id":"documentation/deploying/deployment-options","title":"Choosing Deployment Options","description":"Agent Mesh offers flexible deployment options designed to meet different operational requirements. Understanding these options helps you choose the right approach for your specific environment and scale needs.","sidebar":"docSidebar"},"documentation/deploying/kubernetes-deployment":{"id":"documentation/deploying/kubernetes-deployment","title":"Kubernetes","description":"You can deploy Agent Mesh to Kubernetes using Helm charts, which handle the complexity of creating and configuring Kubernetes resources such as deployments, services, persistent volumes, and configuration management.","sidebar":"docSidebar"},"documentation/deploying/logging":{"id":"documentation/deploying/logging","title":"Logging","description":"Agent Mesh uses Python\'s built-in logging module to provide flexible and powerful logging capabilities.","sidebar":"docSidebar"},"documentation/deploying/observability":{"id":"documentation/deploying/observability","title":"Monitoring Your Agent Mesh","description":"Understanding how your Agent Mesh system operates in real-time is crucial for maintaining optimal performance and quickly identifying issues. The platform provides a comprehensive observability suite that gives you deep insights into system behavior, message flows, and agent interactions.","sidebar":"docSidebar"},"documentation/developing/create-agents":{"id":"documentation/developing/create-agents","title":"Creating Agents","description":"For a more comprehensive tutorial example, see the Build Your Own Agent guide.","sidebar":"docSidebar"},"documentation/developing/create-gateways":{"id":"documentation/developing/create-gateways","title":"Creating Custom Gateways","description":"Gateway adapters connect external systems to the Agent Mesh through custom interfaces. They translate between platform-specific formats (Slack messages, HTTP requests, webhook payloads) and the standardized A2A protocol that agents understand. Gateway adapters handle platform events, extract user identity, and deliver agent responses back to users in the appropriate format.","sidebar":"docSidebar"},"documentation/developing/creating-python-tools":{"id":"documentation/developing/creating-python-tools","title":"Creating Python Tools","description":"Agent Mesh provides a powerful and unified system for creating custom agent tools using Python. This is the primary way to extend an agent\'s capabilities with your own business logic, integrate with proprietary APIs, or perform specialized data processing.","sidebar":"docSidebar"},"documentation/developing/creating-service-providers":{"id":"documentation/developing/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 Agent Mesh.","sidebar":"docSidebar"},"documentation/developing/developing":{"id":"documentation/developing/developing","title":"Developing with Agent Mesh","description":"Agent Mesh provides a framework for creating distributed AI applications using an event-driven architecture. You can build agents that communicate through the A2A (Agent-to-Agent) protocol, extend them with custom tools, integrate external systems through gateways, and create reusable components as plugins.","sidebar":"docSidebar"},"documentation/developing/evaluations":{"id":"documentation/developing/evaluations","title":"Evaluating Agents","description":"The framework includes an evaluation system that helps you test your agents\' behavior in a structured way. You can define test suites, run them against your agents, and generate detailed reports to analyze the results. When running evaluations locally, you can also benchmark different language models to see how they affect your agents\' responses.","sidebar":"docSidebar"},"documentation/developing/structure":{"id":"documentation/developing/structure","title":"Project Structure","description":"Agent Mesh is built on the A2A (Agent-to-Agent) protocol architecture, powered by Solace AI Connector, and uses the Solace event broker as the communication backbone. The framework is controlled by YAML configuration files that define agents, gateways, and plugins, enabling distributed AI agent communication through event-driven messaging.","sidebar":"docSidebar"},"documentation/developing/tutorials/bedrock-agents":{"id":"documentation/developing/tutorials/bedrock-agents","title":"Amazon Bedrock Agents","description":"This tutorial walks you through the process of integrating Amazon Bedrock Agents and Flows into Agent Mesh. This integration allows you to create agents that can interact with one or multiple Bedrock Agents or Flows, extending your Agent Mesh project with powerful AI capabilities from AWS.","sidebar":"docSidebar"},"documentation/developing/tutorials/custom-agent":{"id":"documentation/developing/tutorials/custom-agent","title":"Build Your Own Agent","description":"This tutorial shows you how to build a sophisticated weather agent using the Agent Mesh framework. Learn how to integrate with external APIs, manage resources properly, and create production-ready agents.","sidebar":"docSidebar"},"documentation/developing/tutorials/event-mesh-gateway":{"id":"documentation/developing/tutorials/event-mesh-gateway","title":"Event Mesh Gateway","description":"If you already have an event mesh in place, you can integrate Agent Mesh into it. This allows you to leverage existing infrastructure while introducing intelligence and automation through Agent Mesh.","sidebar":"docSidebar"},"documentation/developing/tutorials/mcp-integration":{"id":"documentation/developing/tutorials/mcp-integration","title":"MCP Integration","description":"This tutorial walks you through the process of integrating a Model Context Protocol (MCP) Server into Agent Mesh.","sidebar":"docSidebar"},"documentation/developing/tutorials/mongodb-integration":{"id":"documentation/developing/tutorials/mongodb-integration","title":"MongoDB Integration","description":"This tutorial sets up a MongoDB agent in Agent Mesh, which allows the Agent Mesh agent to answer natural language queries about a Mongo database. The agent translates user questions into MongoDB aggregation pipelines and executes them against your database.","sidebar":"docSidebar"},"documentation/developing/tutorials/rag-integration":{"id":"documentation/developing/tutorials/rag-integration","title":"RAG Integration","description":"This tutorial guides you through setting up and configuring Agent Mesh Retrieval Augmented Generation (RAG) plugin. The RAG plugin enables your agents to answer questions by retrieving information from a knowledge base of your documents.","sidebar":"docSidebar"},"documentation/developing/tutorials/rest-gateway":{"id":"documentation/developing/tutorials/rest-gateway","title":"REST Gateway","description":"Agent Mesh REST API Gateway provides a standard, robust, and secure HTTP-based entry point for programmatic and system-to-system integrations. It allows external clients to submit tasks to Agent Mesh agents, manage files, and discover agent capabilities using a familiar RESTful interface.","sidebar":"docSidebar"},"documentation/developing/tutorials/slack-integration":{"id":"documentation/developing/tutorials/slack-integration","title":"Slack Integration","description":"This tutorial integrates a Slack interface into Agent Mesh, enabling interaction with the system directly from your Slack workspace and channels.","sidebar":"docSidebar"},"documentation/developing/tutorials/sql-database":{"id":"documentation/developing/tutorials/sql-database","title":"SQL Database Integration","description":"This tutorial sets up a SQL database agent in Agent Mesh, which allows the Agent Mesh agent to answer natural language queries about a sample coffee company database. This tutorial provides some sample data to set up an SQLite database, but you can use the same approach to connect to other database types, such as MySQL or PostgreSQL.","sidebar":"docSidebar"},"documentation/enterprise/agent-builder":{"id":"documentation/enterprise/agent-builder","title":"Agent Builder","description":"Agent Builder provides a visual, form-based interface for creating and managing agents without writing configuration files. This tool offers optional AI assistance that suggests initial configuration values based on a description of the agent you want to build.","sidebar":"docSidebar"},"documentation/enterprise/connectors/connectors":{"id":"documentation/enterprise/connectors/connectors","title":"Connectors","description":"Connectors link agents to external data sources and services. Each connector type provides access to different systems using configured credentials and connection details. Agents use connectors to retrieve information, execute queries, and interact with external platforms through natural language conversations.","sidebar":"docSidebar"},"documentation/enterprise/enterprise":{"id":"documentation/enterprise/enterprise","title":"Agent Mesh Enterprise","description":"Agent Mesh Enterprise extends the open-source framework with production-ready features that enterprise environments require. This version provides enhanced security through single sign-on integration, granular access control through role-based permissions, intelligent data management for cost optimization, and comprehensive observability tools for monitoring agent workflows and system performance.","sidebar":"docSidebar"},"documentation/enterprise/installation":{"id":"documentation/enterprise/installation","title":"Installing Agent Mesh Enterprise","description":"This guide walks you through installing and running Agent Mesh Enterprise using Docker. You will download the enterprise image, load it into Docker, and launch a container configured for either development or production use.","sidebar":"docSidebar"},"documentation/enterprise/rbac-setup-guide":{"id":"documentation/enterprise/rbac-setup-guide","title":"Setting Up RBAC","description":"This guide walks you through configuring Role-Based Access Control (RBAC) in a Docker installation for Agent Mesh. You will learn how to control access to Agent Mesh Enterprise features and resources based on user roles and permissions.","sidebar":"docSidebar"},"documentation/enterprise/secure-user-delegated-access":{"id":"documentation/enterprise/secure-user-delegated-access","title":"Secure User Delegated Access","description":"This guide walks you through configuring Secure User Delegated Access for Agent Mesh Enterprise. You will learn how to enable users to authenticate with remote MCP tools using their own credentials through OAuth2, providing enhanced security and user-specific access control.","sidebar":"docSidebar"},"documentation/enterprise/single-sign-on":{"id":"documentation/enterprise/single-sign-on","title":"Enabling SSO","description":"Overview","sidebar":"docSidebar"},"documentation/enterprise/wheel-installation":{"id":"documentation/enterprise/wheel-installation","title":"Running from Wheel File","description":"You can run Agent Mesh Enterprise directly from a Python wheel file without using Docker containers. This approach gives you direct control over your Python environment and integrates with existing Python-based deployments.","sidebar":"docSidebar"},"documentation/getting-started/architecture":{"id":"documentation/getting-started/architecture","title":"Architecture Overview","description":"Agent Mesh is an event-driven framework that creates a distributed ecosystem of collaborative AI agents. The architecture decouples agent logic from communication and orchestration, enabling you to build scalable, resilient, and modular AI systems.","sidebar":"docSidebar"},"documentation/getting-started/getting-started":{"id":"documentation/getting-started/getting-started","title":"Getting Started","description":"Agent Mesh is an open-source framework for building event-driven multi-agent AI systems that solve complex problems through intelligent collaboration. You can use it to create teams of specialized AI agents that work together seamlessly, each bringing unique capabilities while communicating through Solace\'s proven event-driven architecture.","sidebar":"docSidebar"},"documentation/getting-started/introduction":{"id":"documentation/getting-started/introduction","title":"What is Agent Mesh?","description":"Modern AI development faces a fundamental challenge: powerful AI models are readily available, but it\'s complicated to connect them to the data and systems where they can provide value. Because the data that drives these AI models often exists in isolated silos (databases, SaaS platforms, APIs, and legacy systems), it can be difficult to build AI applications that work across these boundaries.","sidebar":"docSidebar"},"documentation/getting-started/try-agent-mesh":{"id":"documentation/getting-started/try-agent-mesh","title":"Try Agent Mesh","description":"Get started quickly with Agent Mesh using our pre-configured Docker image. This approach lets you explore the capabilities of Agent Mesh without setting up a complete project.","sidebar":"docSidebar"},"documentation/installing-and-configuring/artifact-storage":{"id":"documentation/installing-and-configuring/artifact-storage","title":"Artifact Storage","description":"This guide explains how to configure storage for artifacts\u2014files and data created by your agents\u2014from development to production deployments.","sidebar":"docSidebar"},"documentation/installing-and-configuring/configurations":{"id":"documentation/installing-and-configuring/configurations","title":"Configuring Agent Mesh","description":"The shared_config.yaml file is used to define configurations that can be shared across multiple agents or components in Agent Mesh. This centralized approach simplifies management of common configurations such as Solace event broker connections, language model settings, and service definitions.","sidebar":"docSidebar"},"documentation/installing-and-configuring/installation":{"id":"documentation/installing-and-configuring/installation","title":"Installing Agent Mesh","description":"Before you begin, ensure you have the following:","sidebar":"docSidebar"},"documentation/installing-and-configuring/installing-and-configuring":{"id":"documentation/installing-and-configuring/installing-and-configuring","title":"Installing and Configuring Agent Mesh","description":"Getting Agent Mesh up and running involves several key steps that prepare your development environment and configure the system for your specific needs. You\'ll install the framework, create your first project, configure essential settings, and connect to the language models that power your intelligent agents.","sidebar":"docSidebar"},"documentation/installing-and-configuring/large_language_models":{"id":"documentation/installing-and-configuring/large_language_models","title":"Configuring LLMs","description":"Large Language Models (LLMs) serve as the intelligence foundation for Agent Mesh, powering everything from natural language understanding to complex reasoning and decision-making. The system provides flexible configuration options that allow you to connect with various LLM providers through a unified interface, making it easy to switch between providers or use multiple models for different purposes.","sidebar":"docSidebar"},"documentation/installing-and-configuring/run-project":{"id":"documentation/installing-and-configuring/run-project","title":"Creating and Running an Agent Mesh Project","description":"This guide walks you through creating and running a complete Agent Mesh project. This approach provides full control over your configuration and is suitable for development, testing, and production environments.","sidebar":"docSidebar"},"documentation/installing-and-configuring/session-storage":{"id":"documentation/installing-and-configuring/session-storage","title":"Session Storage","description":"This guide explains how to configure session storage in Agent Mesh, enabling user conversations to persist across restarts and providing rich conversation history for both the WebUI Gateway and individual agents.","sidebar":"docSidebar"},"documentation/installing-and-configuring/user-feedback":{"id":"documentation/installing-and-configuring/user-feedback","title":"User Feedback","description":"User Feedback allows users to provide ratings and comments on AI agent responses through the Web UI. This feature enables quality monitoring, model improvement through evaluation datasets, and user satisfaction tracking. Feedback can be stored in a database for analytics and optionally published to Solace message broker topics for integration with external systems.","sidebar":"docSidebar"},"documentation/migrations/a2a-upgrade/a2a-gateway-upgrade-to-0.3.0":{"id":"documentation/migrations/a2a-upgrade/a2a-gateway-upgrade-to-0.3.0","title":"Migration Guide: Upgrading to the A2A SDK","description":"This guide is for developers who have built or are maintaining a custom Agent Mesh gateway. A recent architectural update has aligned Agent Mesh with the official Agent-to-Agent (A2A) protocol specification by adopting the a2a-sdk. This migration requires some changes to your gateway code to ensure compatibility.","sidebar":"docSidebar"},"documentation/migrations/a2a-upgrade/a2a-technical-migration-map":{"id":"documentation/migrations/a2a-upgrade/a2a-technical-migration-map","title":"A2A Technical Migration Map","description":"This document provides a comprehensive, technical mapping for migrating Agent Mesh components from the legacy A2A implementation to the new a2a-sdk-based protocol. It is designed to be used as a reference for automated or semi-automated code refactoring.","sidebar":"docSidebar"}}}}')}}]);