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

solace_agent_mesh/agent/proxies/base/component.py

@@ -340,7 +340,7 @@ class BaseProxyComponent(ComponentBase, ABC):
                     continue
                 try:
                     # Use a synchronous client for this initial blocking call
-                    response = client.get(f"{agent_url}/.well-known/agent.json")
+                    response = client.get(f"{agent_url}/.well-known/agent-card.json")
                     response.raise_for_status()
                     agent_card = AgentCard.model_validate(response.json())
 
@@ -376,12 +376,13 @@ class BaseProxyComponent(ComponentBase, ABC):
                     continue
 
                 agent_alias = agent_config["name"]
-                card_for_proxy = modern_card.model_copy(deep=True)
-                card_for_proxy.name = agent_alias
-                self.agent_registry.add_or_update_agent(card_for_proxy)
+                # Create a copy for the registry to avoid modifying the original fetched card
+                card_for_registry = modern_card.model_copy(deep=True)
+                card_for_registry.name = agent_alias
+                self.agent_registry.add_or_update_agent(card_for_registry)
 
-                # Publish the modern card directly after updating its URL
-                card_to_publish = card_for_proxy.model_copy(deep=True)
+                # Create a separate copy for publishing
+                card_to_publish = card_for_registry.model_copy(deep=True)
                 card_to_publish.url = (
                     f"solace:{a2a.get_agent_request_topic(self.namespace, agent_alias)}"
                 )
@@ -557,10 +558,12 @@ class BaseProxyComponent(ComponentBase, ABC):
             "%s Publishing initially discovered agent cards...", self.log_identifier
         )
         for agent_alias in self.agent_registry.get_agent_names():
-            card_to_publish = self.agent_registry.get_agent(agent_alias)
-            if not card_to_publish:
+            original_card = self.agent_registry.get_agent(agent_alias)
+            if not original_card:
                 continue
 
+            # Create a copy for publishing to avoid modifying the card in the registry
+            card_to_publish = original_card.model_copy(deep=True)
             card_to_publish.url = (
                 f"solace:{a2a.get_agent_request_topic(self.namespace, agent_alias)}"
             )

solace_agent_mesh/agent/utils/artifact_helpers.py

@@ -796,6 +796,51 @@ async def get_latest_artifact_version(
         return None
 
 
+async def get_artifact_counts_batch(
+    artifact_service: BaseArtifactService,
+    app_name: str,
+    user_id: str,
+    session_ids: List[str],
+) -> Dict[str, int]:
+    """
+    Get artifact counts for multiple sessions in a batch operation.
+    
+    Args:
+        artifact_service: The artifact service instance.
+        app_name: The application name.
+        user_id: The user ID.
+        session_ids: List of session IDs to get counts for.
+    
+    Returns:
+        Dict mapping session_id to artifact_count (excluding metadata files)
+    """
+    log_prefix = f"[ArtifactHelper:get_counts_batch] App={app_name}, User={user_id} -"
+    counts: Dict[str, int] = {}
+    
+    try:
+        list_keys_method = getattr(artifact_service, "list_artifact_keys")
+        
+        for session_id in session_ids:
+            try:
+                keys = await list_keys_method(
+                    app_name=app_name, user_id=user_id, session_id=session_id
+                )
+                # Count only non-metadata files
+                count = sum(1 for key in keys if not key.endswith(METADATA_SUFFIX))
+                counts[session_id] = count
+                log.debug("%s Session %s has %d artifacts", log_prefix, session_id, count)
+            except Exception as e:
+                log.warning("%s Failed to get count for session %s: %s", log_prefix, session_id, e)
+                counts[session_id] = 0
+                
+    except Exception as e:
+        log.exception("%s Error in batch count operation: %s", log_prefix, e)
+        # Return 0 for all sessions on error
+        return {session_id: 0 for session_id in session_ids}
+    
+    return counts
+
+
 async def get_artifact_info_list(
     artifact_service: BaseArtifactService,
     app_name: str,

solace_agent_mesh/assets/docs/404.html

@@ -4,13 +4,13 @@
 <meta charset="UTF-8">
 <meta name="generator" content="Docusaurus v3.8.1">
 <title data-rh="true">Page Not Found | Solace Agent Mesh</title><meta data-rh="true" name="viewport" content="width=device-width,initial-scale=1"><meta data-rh="true" name="twitter:card" content="summary_large_image"><meta data-rh="true" property="og:image" content="https://solacelabs.github.io/solace-agent-mesh/img/logo.png"><meta data-rh="true" name="twitter:image" content="https://solacelabs.github.io/solace-agent-mesh/img/logo.png"><meta data-rh="true" property="og:url" content="https://solacelabs.github.io/solace-agent-mesh/404.html"><meta data-rh="true" property="og:locale" content="en"><meta data-rh="true" name="docusaurus_locale" content="en"><meta data-rh="true" name="docusaurus_tag" content="default"><meta data-rh="true" name="docsearch:language" content="en"><meta data-rh="true" name="docsearch:docusaurus_tag" content="default"><meta data-rh="true" property="og:title" content="Page Not Found | Solace Agent Mesh"><link data-rh="true" rel="icon" href="/solace-agent-mesh/img/logo.png"><link data-rh="true" rel="canonical" href="https://solacelabs.github.io/solace-agent-mesh/404.html"><link data-rh="true" rel="alternate" href="https://solacelabs.github.io/solace-agent-mesh/404.html" hreflang="en"><link data-rh="true" rel="alternate" href="https://solacelabs.github.io/solace-agent-mesh/404.html" hreflang="x-default"><link rel="stylesheet" href="/solace-agent-mesh/assets/css/styles.906a1503.css">
-<script src="/solace-agent-mesh/assets/js/runtime~main.d9606d6a.js" defer="defer"></script>
-<script src="/solace-agent-mesh/assets/js/main.f213fe0c.js" defer="defer"></script>
+<script src="/solace-agent-mesh/assets/js/runtime~main.ec22999d.js" defer="defer"></script>
+<script src="/solace-agent-mesh/assets/js/main.60cfcf1b.js" defer="defer"></script>
 </head>
 <body class="navigation-with-keyboard">
 <svg xmlns="http://www.w3.org/2000/svg" style="display: none;"><defs>
 <symbol id="theme-svg-external-link" viewBox="0 0 24 24"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"/></symbol>
 </defs></svg>
-<script>!function(){var t=function(){try{return new URLSearchParams(window.location.search).get("docusaurus-theme")}catch(t){}}()||function(){try{return window.localStorage.getItem("theme")}catch(t){}}();document.documentElement.setAttribute("data-theme",t||(window.matchMedia("(prefers-color-scheme: dark)").matches?"dark":"light")),document.documentElement.setAttribute("data-theme-choice",t||"system")}(),function(){try{const c=new URLSearchParams(window.location.search).entries();for(var[t,e]of c)if(t.startsWith("docusaurus-data-")){var a=t.replace("docusaurus-data-","data-");document.documentElement.setAttribute(a,e)}}catch(t){}}()</script><div id="__docusaurus"><link rel="preload" as="image" href="/solace-agent-mesh/img/logo.png"><link rel="preload" as="image" href="/solace-agent-mesh/img/solace-logo.png"><div role="region" aria-label="Skip to main content"><a class="skipToContent_fXgn" href="#__docusaurus_skipToContent_fallback">Skip to main content</a></div><nav aria-label="Main" class="theme-layout-navbar navbar navbar--fixed-top"><div class="navbar__inner"><div class="theme-layout-navbar-left navbar__items"><button aria-label="Toggle navigation bar" aria-expanded="false" class="navbar__toggle clean-btn" type="button"><svg width="30" height="30" viewBox="0 0 30 30" aria-hidden="true"><path stroke="currentColor" stroke-linecap="round" stroke-miterlimit="10" stroke-width="2" d="M4 7h22M4 15h22M4 23h22"></path></svg></button><a class="navbar__brand" href="/solace-agent-mesh/docs/documentation/getting-started"><div class="navbar__logo"><img src="/solace-agent-mesh/img/logo.png" alt="Solace Agent Mesh Logo" class="themedComponent_mlkZ themedComponent--light_NVdE"><img src="/solace-agent-mesh/img/logo.png" alt="Solace Agent Mesh Logo" class="themedComponent_mlkZ themedComponent--dark_xIcU"></div><b class="navbar__title text--truncate">Solace Agent Mesh</b></a><a class="navbar__item navbar__link" href="/solace-agent-mesh/docs/documentation/getting-started/">Documentation</a></div><div class="theme-layout-navbar-right navbar__items navbar__items--right"><a href="https://github.com/SolaceLabs/solace-agent-mesh/" target="_blank" rel="noopener noreferrer" class="navbar__item navbar__link">GitHub<svg width="13.5" height="13.5" aria-hidden="true" class="iconExternalLink_nPIU"><use href="#theme-svg-external-link"></use></svg></a><div class="toggle_vylO colorModeToggle_DEke"><button class="clean-btn toggleButton_gllP toggleButtonDisabled_aARS" type="button" disabled="" title="system mode" aria-label="Switch between dark and light mode (currently system mode)"><svg viewBox="0 0 24 24" width="24" height="24" aria-hidden="true" class="toggleIcon_g3eP lightToggleIcon_pyhR"><path fill="currentColor" d="M12,9c1.65,0,3,1.35,3,3s-1.35,3-3,3s-3-1.35-3-3S10.35,9,12,9 M12,7c-2.76,0-5,2.24-5,5s2.24,5,5,5s5-2.24,5-5 S14.76,7,12,7L12,7z M2,13l2,0c0.55,0,1-0.45,1-1s-0.45-1-1-1l-2,0c-0.55,0-1,0.45-1,1S1.45,13,2,13z M20,13l2,0c0.55,0,1-0.45,1-1 s-0.45-1-1-1l-2,0c-0.55,0-1,0.45-1,1S19.45,13,20,13z M11,2v2c0,0.55,0.45,1,1,1s1-0.45,1-1V2c0-0.55-0.45-1-1-1S11,1.45,11,2z M11,20v2c0,0.55,0.45,1,1,1s1-0.45,1-1v-2c0-0.55-0.45-1-1-1C11.45,19,11,19.45,11,20z M5.99,4.58c-0.39-0.39-1.03-0.39-1.41,0 c-0.39,0.39-0.39,1.03,0,1.41l1.06,1.06c0.39,0.39,1.03,0.39,1.41,0s0.39-1.03,0-1.41L5.99,4.58z M18.36,16.95 c-0.39-0.39-1.03-0.39-1.41,0c-0.39,0.39-0.39,1.03,0,1.41l1.06,1.06c0.39,0.39,1.03,0.39,1.41,0c0.39-0.39,0.39-1.03,0-1.41 L18.36,16.95z M19.42,5.99c0.39-0.39,0.39-1.03,0-1.41c-0.39-0.39-1.03-0.39-1.41,0l-1.06,1.06c-0.39,0.39-0.39,1.03,0,1.41 s1.03,0.39,1.41,0L19.42,5.99z M7.05,18.36c0.39-0.39,0.39-1.03,0-1.41c-0.39-0.39-1.03-0.39-1.41,0l-1.06,1.06 c-0.39,0.39-0.39,1.03,0,1.41s1.03,0.39,1.41,0L7.05,18.36z"></path></svg><svg viewBox="0 0 24 24" width="24" height="24" aria-hidden="true" class="toggleIcon_g3eP darkToggleIcon_wfgR"><path fill="currentColor" d="M9.37,5.51C9.19,6.15,9.1,6.82,9.1,7.5c0,4.08,3.32,7.4,7.4,7.4c0.68,0,1.35-0.09,1.99-0.27C17.45,17.19,14.93,19,12,19 c-3.86,0-7-3.14-7-7C5,9.07,6.81,6.55,9.37,5.51z M12,3c-4.97,0-9,4.03-9,9s4.03,9,9,9s9-4.03,9-9c0-0.46-0.04-0.92-0.1-1.36 c-0.98,1.37-2.58,2.26-4.4,2.26c-2.98,0-5.4-2.42-5.4-5.4c0-1.81,0.89-3.42,2.26-4.4C12.92,3.04,12.46,3,12,3L12,3z"></path></svg><svg viewBox="0 0 24 24" width="24" height="24" aria-hidden="true" class="toggleIcon_g3eP systemToggleIcon_QzmC"><path fill="currentColor" d="m12 21c4.971 0 9-4.029 9-9s-4.029-9-9-9-9 4.029-9 9 4.029 9 9 9zm4.95-13.95c1.313 1.313 2.05 3.093 2.05 4.95s-0.738 3.637-2.05 4.95c-1.313 1.313-3.093 2.05-4.95 2.05v-14c1.857 0 3.637 0.737 4.95 2.05z"></path></svg></button></div><div class="navbarSearchContainer_Bca1"><div class="navbar__search"><span aria-label="expand searchbar" role="button" class="search-icon" tabindex="0"></span><input id="search_input_react" type="search" placeholder="Loading..." aria-label="Search" class="navbar__search-input search-bar" disabled=""></div></div></div></div><div role="presentation" class="navbar-sidebar__backdrop"></div></nav><div id="__docusaurus_skipToContent_fallback" class="theme-layout-main main-wrapper mainWrapper_z2l0"><main class="container margin-vert--xl"><div class="row"><div class="col col--6 col--offset-3"><h1 class="hero__title">Page Not Found</h1><p>We could not find what you were looking for.</p><p>Please contact the owner of the site that linked you to the original URL and let them know their link is broken.</p></div></div></main></div><footer class="theme-layout-footer footer footer--dark"><div class="container container-fluid"><div class="row footer__links"><div class="theme-layout-footer-column col footer__col"><div class="footer__title">Solace Agent Mesh</div><ul class="footer__items clean-list"><li class="footer__item"><a class="footer__link-item" href="/solace-agent-mesh/docs/documentation/getting-started">Documentation</a></li><li class="footer__item"><a href="https://github.com/SolaceLabs/solace-agent-mesh/" target="_blank" rel="noopener noreferrer" class="footer__link-item">GitHub<svg width="13.5" height="13.5" aria-hidden="true" class="iconExternalLink_nPIU"><use href="#theme-svg-external-link"></use></svg></a></li><li class="footer__item"><a href="https://github.com/SolaceLabs/solace-agent-mesh-core-plugins/" target="_blank" rel="noopener noreferrer" class="footer__link-item">Official Plugins<svg width="13.5" height="13.5" aria-hidden="true" class="iconExternalLink_nPIU"><use href="#theme-svg-external-link"></use></svg></a></li></ul></div><div class="theme-layout-footer-column col footer__col"><div class="footer__title">Company</div><ul class="footer__items clean-list"><li class="footer__item"><a href="https://solace.com/products/" target="_blank" rel="noopener noreferrer" class="footer__link-item">Products<svg width="13.5" height="13.5" aria-hidden="true" class="iconExternalLink_nPIU"><use href="#theme-svg-external-link"></use></svg></a></li><li class="footer__item"><a href="https://solace.com/contact/" target="_blank" rel="noopener noreferrer" class="footer__link-item">Contact<svg width="13.5" height="13.5" aria-hidden="true" class="iconExternalLink_nPIU"><use href="#theme-svg-external-link"></use></svg></a></li><li class="footer__item"><a href="https://solace.com/support/" target="_blank" rel="noopener noreferrer" class="footer__link-item">Support<svg width="13.5" height="13.5" aria-hidden="true" class="iconExternalLink_nPIU"><use href="#theme-svg-external-link"></use></svg></a></li><li class="footer__item"><a href="https://solace.com/legal/" target="_blank" rel="noopener noreferrer" class="footer__link-item">Privacy and Legal<svg width="13.5" height="13.5" aria-hidden="true" class="iconExternalLink_nPIU"><use href="#theme-svg-external-link"></use></svg></a></li></ul></div><div class="theme-layout-footer-column col footer__col"><div class="footer__title">Community</div><ul class="footer__items clean-list"><li class="footer__item"><a href="https://www.linkedin.com/company/solacedotcom/" target="_blank" rel="noopener noreferrer" class="footer__link-item">LinkedIn<svg width="13.5" height="13.5" aria-hidden="true" class="iconExternalLink_nPIU"><use href="#theme-svg-external-link"></use></svg></a></li><li class="footer__item"><a href="https://github.com/SolaceLabs" target="_blank" rel="noopener noreferrer" class="footer__link-item">GitHub<svg width="13.5" height="13.5" aria-hidden="true" class="iconExternalLink_nPIU"><use href="#theme-svg-external-link"></use></svg></a></li><li class="footer__item"><a href="https://www.youtube.com/SolaceSystems" target="_blank" rel="noopener noreferrer" class="footer__link-item">YouTube<svg width="13.5" height="13.5" aria-hidden="true" class="iconExternalLink_nPIU"><use href="#theme-svg-external-link"></use></svg></a></li><li class="footer__item"><a href="https://twitter.com/solacedotcom" target="_blank" rel="noopener noreferrer" class="footer__link-item">X<svg width="13.5" height="13.5" aria-hidden="true" class="iconExternalLink_nPIU"><use href="#theme-svg-external-link"></use></svg></a></li></ul></div></div><div class="footer__bottom text--center"><div class="margin-bottom--sm"><img src="/solace-agent-mesh/img/solace-logo.png" alt="Solace Logo" class="footer__logo themedComponent_mlkZ themedComponent--light_NVdE" width="10%" height="10%"><img src="/solace-agent-mesh/img/solace-logo.png" alt="Solace Logo" class="footer__logo themedComponent_mlkZ themedComponent--dark_xIcU" width="10%" height="10%"></div><div class="footer__copyright">Solace Agent Mesh. Copyright © 2025 Solace. Version: 1.7.1</div></div></div></footer></div>
+<script>!function(){var t=function(){try{return new URLSearchParams(window.location.search).get("docusaurus-theme")}catch(t){}}()||function(){try{return window.localStorage.getItem("theme")}catch(t){}}();document.documentElement.setAttribute("data-theme",t||(window.matchMedia("(prefers-color-scheme: dark)").matches?"dark":"light")),document.documentElement.setAttribute("data-theme-choice",t||"system")}(),function(){try{const c=new URLSearchParams(window.location.search).entries();for(var[t,e]of c)if(t.startsWith("docusaurus-data-")){var a=t.replace("docusaurus-data-","data-");document.documentElement.setAttribute(a,e)}}catch(t){}}()</script><div id="__docusaurus"><link rel="preload" as="image" href="/solace-agent-mesh/img/logo.png"><link rel="preload" as="image" href="/solace-agent-mesh/img/solace-logo.png"><div role="region" aria-label="Skip to main content"><a class="skipToContent_fXgn" href="#__docusaurus_skipToContent_fallback">Skip to main content</a></div><nav aria-label="Main" class="theme-layout-navbar navbar navbar--fixed-top"><div class="navbar__inner"><div class="theme-layout-navbar-left navbar__items"><button aria-label="Toggle navigation bar" aria-expanded="false" class="navbar__toggle clean-btn" type="button"><svg width="30" height="30" viewBox="0 0 30 30" aria-hidden="true"><path stroke="currentColor" stroke-linecap="round" stroke-miterlimit="10" stroke-width="2" d="M4 7h22M4 15h22M4 23h22"></path></svg></button><a class="navbar__brand" href="/solace-agent-mesh/docs/documentation/getting-started"><div class="navbar__logo"><img src="/solace-agent-mesh/img/logo.png" alt="Solace Agent Mesh Logo" class="themedComponent_mlkZ themedComponent--light_NVdE"><img src="/solace-agent-mesh/img/logo.png" alt="Solace Agent Mesh Logo" class="themedComponent_mlkZ themedComponent--dark_xIcU"></div><b class="navbar__title text--truncate">Solace Agent Mesh</b></a><a class="navbar__item navbar__link" href="/solace-agent-mesh/docs/documentation/getting-started/">Documentation</a></div><div class="theme-layout-navbar-right navbar__items navbar__items--right"><a href="https://github.com/SolaceLabs/solace-agent-mesh/" target="_blank" rel="noopener noreferrer" class="navbar__item navbar__link">GitHub<svg width="13.5" height="13.5" aria-hidden="true" class="iconExternalLink_nPIU"><use href="#theme-svg-external-link"></use></svg></a><div class="toggle_vylO colorModeToggle_DEke"><button class="clean-btn toggleButton_gllP toggleButtonDisabled_aARS" type="button" disabled="" title="system mode" aria-label="Switch between dark and light mode (currently system mode)"><svg viewBox="0 0 24 24" width="24" height="24" aria-hidden="true" class="toggleIcon_g3eP lightToggleIcon_pyhR"><path fill="currentColor" d="M12,9c1.65,0,3,1.35,3,3s-1.35,3-3,3s-3-1.35-3-3S10.35,9,12,9 M12,7c-2.76,0-5,2.24-5,5s2.24,5,5,5s5-2.24,5-5 S14.76,7,12,7L12,7z M2,13l2,0c0.55,0,1-0.45,1-1s-0.45-1-1-1l-2,0c-0.55,0-1,0.45-1,1S1.45,13,2,13z M20,13l2,0c0.55,0,1-0.45,1-1 s-0.45-1-1-1l-2,0c-0.55,0-1,0.45-1,1S19.45,13,20,13z M11,2v2c0,0.55,0.45,1,1,1s1-0.45,1-1V2c0-0.55-0.45-1-1-1S11,1.45,11,2z M11,20v2c0,0.55,0.45,1,1,1s1-0.45,1-1v-2c0-0.55-0.45-1-1-1C11.45,19,11,19.45,11,20z M5.99,4.58c-0.39-0.39-1.03-0.39-1.41,0 c-0.39,0.39-0.39,1.03,0,1.41l1.06,1.06c0.39,0.39,1.03,0.39,1.41,0s0.39-1.03,0-1.41L5.99,4.58z M18.36,16.95 c-0.39-0.39-1.03-0.39-1.41,0c-0.39,0.39-0.39,1.03,0,1.41l1.06,1.06c0.39,0.39,1.03,0.39,1.41,0c0.39-0.39,0.39-1.03,0-1.41 L18.36,16.95z M19.42,5.99c0.39-0.39,0.39-1.03,0-1.41c-0.39-0.39-1.03-0.39-1.41,0l-1.06,1.06c-0.39,0.39-0.39,1.03,0,1.41 s1.03,0.39,1.41,0L19.42,5.99z M7.05,18.36c0.39-0.39,0.39-1.03,0-1.41c-0.39-0.39-1.03-0.39-1.41,0l-1.06,1.06 c-0.39,0.39-0.39,1.03,0,1.41s1.03,0.39,1.41,0L7.05,18.36z"></path></svg><svg viewBox="0 0 24 24" width="24" height="24" aria-hidden="true" class="toggleIcon_g3eP darkToggleIcon_wfgR"><path fill="currentColor" d="M9.37,5.51C9.19,6.15,9.1,6.82,9.1,7.5c0,4.08,3.32,7.4,7.4,7.4c0.68,0,1.35-0.09,1.99-0.27C17.45,17.19,14.93,19,12,19 c-3.86,0-7-3.14-7-7C5,9.07,6.81,6.55,9.37,5.51z M12,3c-4.97,0-9,4.03-9,9s4.03,9,9,9s9-4.03,9-9c0-0.46-0.04-0.92-0.1-1.36 c-0.98,1.37-2.58,2.26-4.4,2.26c-2.98,0-5.4-2.42-5.4-5.4c0-1.81,0.89-3.42,2.26-4.4C12.92,3.04,12.46,3,12,3L12,3z"></path></svg><svg viewBox="0 0 24 24" width="24" height="24" aria-hidden="true" class="toggleIcon_g3eP systemToggleIcon_QzmC"><path fill="currentColor" d="m12 21c4.971 0 9-4.029 9-9s-4.029-9-9-9-9 4.029-9 9 4.029 9 9 9zm4.95-13.95c1.313 1.313 2.05 3.093 2.05 4.95s-0.738 3.637-2.05 4.95c-1.313 1.313-3.093 2.05-4.95 2.05v-14c1.857 0 3.637 0.737 4.95 2.05z"></path></svg></button></div><div class="navbarSearchContainer_Bca1"><div class="navbar__search"><span aria-label="expand searchbar" role="button" class="search-icon" tabindex="0"></span><input id="search_input_react" type="search" placeholder="Loading..." aria-label="Search" class="navbar__search-input search-bar" disabled=""></div></div></div></div><div role="presentation" class="navbar-sidebar__backdrop"></div></nav><div id="__docusaurus_skipToContent_fallback" class="theme-layout-main main-wrapper mainWrapper_z2l0"><main class="container margin-vert--xl"><div class="row"><div class="col col--6 col--offset-3"><h1 class="hero__title">Page Not Found</h1><p>We could not find what you were looking for.</p><p>Please contact the owner of the site that linked you to the original URL and let them know their link is broken.</p></div></div></main></div><footer class="theme-layout-footer footer footer--dark"><div class="container container-fluid"><div class="row footer__links"><div class="theme-layout-footer-column col footer__col"><div class="footer__title">Solace Agent Mesh</div><ul class="footer__items clean-list"><li class="footer__item"><a class="footer__link-item" href="/solace-agent-mesh/docs/documentation/getting-started">Documentation</a></li><li class="footer__item"><a href="https://github.com/SolaceLabs/solace-agent-mesh/" target="_blank" rel="noopener noreferrer" class="footer__link-item">GitHub<svg width="13.5" height="13.5" aria-hidden="true" class="iconExternalLink_nPIU"><use href="#theme-svg-external-link"></use></svg></a></li><li class="footer__item"><a href="https://github.com/SolaceLabs/solace-agent-mesh-core-plugins/" target="_blank" rel="noopener noreferrer" class="footer__link-item">Official Plugins<svg width="13.5" height="13.5" aria-hidden="true" class="iconExternalLink_nPIU"><use href="#theme-svg-external-link"></use></svg></a></li></ul></div><div class="theme-layout-footer-column col footer__col"><div class="footer__title">Company</div><ul class="footer__items clean-list"><li class="footer__item"><a href="https://solace.com/products/" target="_blank" rel="noopener noreferrer" class="footer__link-item">Products<svg width="13.5" height="13.5" aria-hidden="true" class="iconExternalLink_nPIU"><use href="#theme-svg-external-link"></use></svg></a></li><li class="footer__item"><a href="https://solace.com/contact/" target="_blank" rel="noopener noreferrer" class="footer__link-item">Contact<svg width="13.5" height="13.5" aria-hidden="true" class="iconExternalLink_nPIU"><use href="#theme-svg-external-link"></use></svg></a></li><li class="footer__item"><a href="https://solace.com/support/" target="_blank" rel="noopener noreferrer" class="footer__link-item">Support<svg width="13.5" height="13.5" aria-hidden="true" class="iconExternalLink_nPIU"><use href="#theme-svg-external-link"></use></svg></a></li><li class="footer__item"><a href="https://solace.com/legal/" target="_blank" rel="noopener noreferrer" class="footer__link-item">Privacy and Legal<svg width="13.5" height="13.5" aria-hidden="true" class="iconExternalLink_nPIU"><use href="#theme-svg-external-link"></use></svg></a></li></ul></div><div class="theme-layout-footer-column col footer__col"><div class="footer__title">Community</div><ul class="footer__items clean-list"><li class="footer__item"><a href="https://www.linkedin.com/company/solacedotcom/" target="_blank" rel="noopener noreferrer" class="footer__link-item">LinkedIn<svg width="13.5" height="13.5" aria-hidden="true" class="iconExternalLink_nPIU"><use href="#theme-svg-external-link"></use></svg></a></li><li class="footer__item"><a href="https://github.com/SolaceLabs" target="_blank" rel="noopener noreferrer" class="footer__link-item">GitHub<svg width="13.5" height="13.5" aria-hidden="true" class="iconExternalLink_nPIU"><use href="#theme-svg-external-link"></use></svg></a></li><li class="footer__item"><a href="https://www.youtube.com/SolaceSystems" target="_blank" rel="noopener noreferrer" class="footer__link-item">YouTube<svg width="13.5" height="13.5" aria-hidden="true" class="iconExternalLink_nPIU"><use href="#theme-svg-external-link"></use></svg></a></li><li class="footer__item"><a href="https://twitter.com/solacedotcom" target="_blank" rel="noopener noreferrer" class="footer__link-item">X<svg width="13.5" height="13.5" aria-hidden="true" class="iconExternalLink_nPIU"><use href="#theme-svg-external-link"></use></svg></a></li></ul></div></div><div class="footer__bottom text--center"><div class="margin-bottom--sm"><img src="/solace-agent-mesh/img/solace-logo.png" alt="Solace Logo" class="footer__logo themedComponent_mlkZ themedComponent--light_NVdE" width="10%" height="10%"><img src="/solace-agent-mesh/img/solace-logo.png" alt="Solace Logo" class="footer__logo themedComponent_mlkZ themedComponent--dark_xIcU" width="10%" height="10%"></div><div class="footer__copyright">Solace Agent Mesh. Copyright © 2025 Solace. Version: 1.7.2</div></div></div></footer></div>
 </body>
 </html>

solace_agent_mesh/assets/docs/assets/js/15e40e79.434bb30f.js

@@ -0,0 +1 @@
+"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:()=>l,contentTitle:()=>a,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},a="Projects",l={},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:"Performance Considerations",id:"performance-considerations",level:2},{value:"Database Optimization",id:"database-optimization",level:3},{value:"Artifact Storage",id:"artifact-storage",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 chat titles 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.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.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:()=>a});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 a(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/60702c0e.f9a9923a.js

@@ -0,0 +1 @@
+"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[1428],{1263:(e,n,t)=>{t.r(n),t.d(n,{assets:()=>c,contentTitle:()=>a,default:()=>p,frontMatter:()=>o,metadata:()=>s,toc:()=>l});const s=JSON.parse('{"id":"documentation/developing/tutorials/teams-integration","title":"Microsoft Teams Integration (Enterprise)","description":"This tutorial shows you how to integrate Microsoft Teams with Agent Mesh Enterprise, allowing users to interact with the system directly from Teams workspaces and channels.","source":"@site/docs/documentation/developing/tutorials/teams-integration.md","sourceDirName":"documentation/developing/tutorials","slug":"/documentation/developing/tutorials/teams-integration","permalink":"/solace-agent-mesh/docs/documentation/developing/tutorials/teams-integration","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/developing/tutorials/teams-integration.md","tags":[],"version":"current","sidebarPosition":70,"frontMatter":{"title":"Microsoft Teams Integration (Enterprise)","sidebar_position":70},"sidebar":"docSidebar","previous":{"title":"RAG Integration","permalink":"/solace-agent-mesh/docs/documentation/developing/tutorials/rag-integration"},"next":{"title":"Deploying Agent Mesh","permalink":"/solace-agent-mesh/docs/documentation/deploying/"}}');var i=t(4848),r=t(8453);const o={title:"Microsoft Teams Integration (Enterprise)",sidebar_position:70},a="Microsoft Teams Integration (Enterprise)",c={},l=[{value:"Prerequisites",id:"prerequisites",level:2},{value:"Overview",id:"overview",level:2},{value:"Azure Setup",id:"azure-setup",level:2},{value:"Step 1: Create Azure App Registration",id:"step-1-create-azure-app-registration",level:3},{value:"Step 2: Create Azure Bot Service",id:"step-2-create-azure-bot-service",level:3},{value:"Step 3: Add Teams Channel",id:"step-3-add-teams-channel",level:3},{value:"Step 4: Create Teams App Package",id:"step-4-create-teams-app-package",level:3},{value:"Step 5: Upload Teams App",id:"step-5-upload-teams-app",level:3},{value:"Configuring the Gateway",id:"configuring-the-gateway",level:2},{value:"Environment Variables",id:"environment-variables",level:3},{value:"Docker Compose Example",id:"docker-compose-example",level:3},{value:"Kubernetes ConfigMap/Secret",id:"kubernetes-configmapsecret",level:3},{value:"Gateway Configuration Options",id:"gateway-configuration-options",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",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:"microsoft-teams-integration-enterprise",children:"Microsoft Teams Integration (Enterprise)"})}),"\n",(0,i.jsx)(n.p,{children:"This tutorial shows you how to integrate Microsoft Teams with Agent Mesh Enterprise, allowing users to interact with the system directly from Teams workspaces and channels."}),"\n",(0,i.jsxs)(n.admonition,{title:"Enterprise Feature - Docker Deployment Only",type:"warning",children:[(0,i.jsx)(n.p,{children:"The Microsoft Teams Gateway is an Enterprise feature included in the Docker image. It is not available when installing via PyPI or wheel files. This feature requires:"}),(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsx)(n.li,{children:"Agent Mesh Enterprise Docker deployment"}),"\n",(0,i.jsx)(n.li,{children:"Azure Active Directory tenant access"}),"\n",(0,i.jsx)(n.li,{children:"Azure Bot Service setup"}),"\n"]})]}),"\n",(0,i.jsx)(n.admonition,{title:"Learn about gateways",type:"info",children:(0,i.jsxs)(n.p,{children:["For an introduction to gateways and how they work, see ",(0,i.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/components/gateways",children:"Gateways"}),"."]})}),"\n",(0,i.jsx)(n.h2,{id:"prerequisites",children:"Prerequisites"}),"\n",(0,i.jsx)(n.p,{children:"Before you begin, make sure you have the following:"}),"\n",(0,i.jsxs)(n.ol,{children:["\n",(0,i.jsx)(n.li,{children:"Agent Mesh Enterprise deployed via Docker or Kubernetes"}),"\n",(0,i.jsx)(n.li,{children:"Access to an Azure Active Directory tenant"}),"\n",(0,i.jsx)(n.li,{children:"An Azure subscription for creating Bot Service resources"}),"\n",(0,i.jsx)(n.li,{children:"A public HTTPS endpoint for production, or ngrok for development and testing"}),"\n"]}),"\n",(0,i.jsx)(n.h2,{id:"overview",children:"Overview"}),"\n",(0,i.jsx)(n.p,{children:"The Microsoft Teams Gateway connects your Agent Mesh deployment to Microsoft Teams, enabling several interaction modes. Users can chat directly with the bot in personal conversations, collaborate with the bot in group chats when they mention it, and interact with it in team channels. The gateway handles file uploads in formats including CSV, JSON, PDF, YAML, XML, and images. It also manages file downloads through Microsoft Teams' FileConsentCard approval flow."}),"\n",(0,i.jsx)(n.p,{children:"When users send messages, the gateway streams responses back in real time, updating messages as the agent processes the request. The system automatically extracts user identities through Azure AD authentication, ensuring secure access control. To maintain performance and clarity, sessions reset automatically at midnight UTC each day."}),"\n",(0,i.jsx)(n.p,{children:"The gateway operates in single-tenant mode, meaning it works within your organization's Azure AD tenant. This approach provides better security and simpler management for enterprise deployments."}),"\n",(0,i.jsx)(n.h2,{id:"azure-setup",children:"Azure Setup"}),"\n",(0,i.jsx)(n.p,{children:"Setting up the Teams integration requires creating several Azure resources. You configure these resources in a specific order because each one depends on information from the previous step."}),"\n",(0,i.jsx)(n.h3,{id:"step-1-create-azure-app-registration",children:"Step 1: Create Azure App Registration"}),"\n",(0,i.jsxs)(n.p,{children:["The App Registration establishes your bot's identity within Azure Active Directory. Go to ",(0,i.jsx)(n.a,{href:"https://portal.azure.com",children:"https://portal.azure.com"}),", then navigate to Azure Active Directory and select ",(0,i.jsx)(n.code,{children:"App registrations"}),". Click ",(0,i.jsx)(n.code,{children:"New registration"}),"."]}),"\n",(0,i.jsxs)(n.p,{children:['Enter a descriptive name like "SAM Teams Bot". Under ',(0,i.jsx)(n.code,{children:"Supported account types"}),", select ",(0,i.jsx)(n.code,{children:"Accounts in this organizational directory only (Single tenant)"}),". Leave the ",(0,i.jsx)(n.code,{children:"Redirect URI"})," blank and click ",(0,i.jsx)(n.code,{children:"Register"}),"."]}),"\n",(0,i.jsxs)(n.p,{children:["Copy both the ",(0,i.jsx)(n.code,{children:"Application (client) ID"})," and ",(0,i.jsx)(n.code,{children:"Directory (tenant) ID"})," from the details page\u2014you need both for later steps."]}),"\n",(0,i.jsxs)(n.p,{children:["Next, go to ",(0,i.jsx)(n.code,{children:"Certificates & secrets"})," and click ",(0,i.jsx)(n.code,{children:"New client secret"}),'. Enter a description like "SAM Bot Secret" and choose an expiration period. Click ',(0,i.jsx)(n.code,{children:"Add"}),"."]}),"\n",(0,i.jsx)(n.admonition,{title:"Save Your Secret",type:"danger",children:(0,i.jsxs)(n.p,{children:["The client secret value appears only once. Copy it immediately and store it securely. This becomes your ",(0,i.jsx)(n.code,{children:"TEAMS_BOT_PASSWORD"})," environment variable."]})}),"\n",(0,i.jsx)(n.h3,{id:"step-2-create-azure-bot-service",children:"Step 2: Create Azure Bot Service"}),"\n",(0,i.jsxs)(n.p,{children:["In the Azure Portal, search for ",(0,i.jsx)(n.code,{children:"Azure Bot"})," and click ",(0,i.jsx)(n.code,{children:"Create"}),". Enter a unique name like ",(0,i.jsx)(n.code,{children:"sam-teams-bot"}),", select your subscription and resource group, and choose a pricing tier (F0 for development, S1 for production)."]}),"\n",(0,i.jsxs)(n.p,{children:["Under ",(0,i.jsx)(n.code,{children:"Microsoft App ID"}),", select ",(0,i.jsx)(n.code,{children:"Use existing app registration"}),". Paste the ",(0,i.jsx)(n.code,{children:"Application (client) ID"})," from Step 1 into the ",(0,i.jsx)(n.code,{children:"App ID"})," field and enter your Azure AD tenant ID in the ",(0,i.jsx)(n.code,{children:"Tenant ID"})," field. Click ",(0,i.jsx)(n.code,{children:"Review + create"}),", then ",(0,i.jsx)(n.code,{children:"Create"}),"."]}),"\n",(0,i.jsxs)(n.p,{children:["After deployment, navigate to the bot resource and go to the ",(0,i.jsx)(n.code,{children:"Configuration"})," section. Set the ",(0,i.jsx)(n.code,{children:"Messaging endpoint"})," to your public HTTPS URL with ",(0,i.jsx)(n.code,{children:"/api/messages"})," appended (e.g., ",(0,i.jsx)(n.code,{children:"https://your-domain.com/api/messages"}),"). This endpoint must be publicly accessible from the internet. Click ",(0,i.jsx)(n.code,{children:"Apply"}),"."]}),"\n",(0,i.jsxs)(n.admonition,{title:"Development Setup",type:"tip",children:[(0,i.jsxs)(n.p,{children:["For local testing, use ",(0,i.jsx)(n.a,{href:"https://ngrok.com/",children:"ngrok"})," to expose your local port:"]}),(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:"ngrok http 8080\n"})}),(0,i.jsxs)(n.p,{children:["Then use the ngrok HTTPS URL as your messaging endpoint (e.g., ",(0,i.jsx)(n.code,{children:"https://abc123.ngrok.io/api/messages"}),")"]})]}),"\n",(0,i.jsx)(n.h3,{id:"step-3-add-teams-channel",children:"Step 3: Add Teams Channel"}),"\n",(0,i.jsxs)(n.p,{children:["In your Azure Bot resource, navigate to ",(0,i.jsx)(n.code,{children:"Channels"})," and click the ",(0,i.jsx)(n.code,{children:"Microsoft Teams"})," icon. Leave ",(0,i.jsx)(n.code,{children:"Calling"})," disabled and ensure ",(0,i.jsx)(n.code,{children:"Messaging"})," is enabled. Click ",(0,i.jsx)(n.code,{children:"Apply"})," to activate the channel."]}),"\n",(0,i.jsx)(n.h3,{id:"step-4-create-teams-app-package",children:"Step 4: Create Teams App Package"}),"\n",(0,i.jsxs)(n.p,{children:["Create a new directory with a file named ",(0,i.jsx)(n.code,{children:"manifest.json"})," containing the following:"]}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-json",children:'{\n  "$schema": "https://developer.microsoft.com/json-schemas/teams/v1.16/MicrosoftTeams.schema.json",\n  "manifestVersion": "1.16",\n  "version": "1.0.0",\n  "id": "YOUR-APP-ID-HERE",\n  "packageName": "com.solace.agentmesh.teams",\n  "developer": {\n    "name": "Your Organization",\n    "websiteUrl": "https://your-company.com",\n    "privacyUrl": "https://your-company.com/privacy",\n    "termsOfUseUrl": "https://your-company.com/terms"\n  },\n  "name": {\n    "short": "Agent Mesh Bot",\n    "full": "Solace Agent Mesh Bot"\n  },\n  "description": {\n    "short": "AI-powered assistant for your organization",\n    "full": "Solace Agent Mesh provides intelligent assistance through Microsoft Teams"\n  },\n  "icons": {\n    "outline": "outline.png",\n    "color": "color.png"\n  },\n  "accentColor": "#00C895",\n  "bots": [\n    {\n      "botId": "YOUR-BOT-ID-HERE",\n      "scopes": ["personal", "team", "groupchat"],\n      "supportsFiles": true,\n      "isNotificationOnly": false\n    }\n  ],\n  "permissions": [\n    "identity",\n    "messageTeamMembers"\n  ],\n  "validDomains": []\n}\n'})}),"\n",(0,i.jsxs)(n.p,{children:["Replace ",(0,i.jsx)(n.code,{children:"YOUR-APP-ID-HERE"})," with your ",(0,i.jsx)(n.code,{children:"Application (client) ID"})," from Step 1 and ",(0,i.jsx)(n.code,{children:"YOUR-BOT-ID-HERE"})," with your Azure Bot ID (usually the same as your App ID). Update the ",(0,i.jsx)(n.code,{children:"developer"})," fields with your organization's information and URLs."]}),"\n",(0,i.jsxs)(n.p,{children:["The ",(0,i.jsx)(n.code,{children:"supportsFiles"})," property enables file uploads and downloads. The ",(0,i.jsx)(n.code,{children:"scopes"})," array specifies where users interact with the bot (personal, team, or group chat). The ",(0,i.jsx)(n.code,{children:"permissions"})," array grants access to user identity and team messaging."]}),"\n",(0,i.jsx)(n.p,{children:"Create two icon files:"}),"\n",(0,i.jsx)(n.admonition,{title:"Icon Requirements",type:"tip",children:(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.code,{children:"color.png"}),": 192x192 pixels, full color"]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.code,{children:"outline.png"}),": 32x32 pixels, white icon on transparent background"]}),"\n"]})}),"\n",(0,i.jsxs)(n.p,{children:["Create a ZIP file containing ",(0,i.jsx)(n.code,{children:"manifest.json"}),", ",(0,i.jsx)(n.code,{children:"color.png"}),", and ",(0,i.jsx)(n.code,{children:"outline.png"}),". Name it ",(0,i.jsx)(n.code,{children:"teams-app.zip"}),"."]}),"\n",(0,i.jsx)(n.h3,{id:"step-5-upload-teams-app",children:"Step 5: Upload Teams App"}),"\n",(0,i.jsxs)(n.p,{children:["Open Microsoft Teams and click ",(0,i.jsx)(n.code,{children:"Apps"})," in the left sidebar. Click ",(0,i.jsx)(n.code,{children:"Manage your apps"}),", then ",(0,i.jsx)(n.code,{children:"Upload an app"}),". Select ",(0,i.jsx)(n.code,{children:"Upload a custom app"})," and choose your ",(0,i.jsx)(n.code,{children:"teams-app.zip"})," file."]}),"\n",(0,i.jsxs)(n.p,{children:["Click ",(0,i.jsx)(n.code,{children:"Add"})," to install the bot in your Teams workspace."]}),"\n",(0,i.jsx)(n.h2,{id:"configuring-the-gateway",children:"Configuring the Gateway"}),"\n",(0,i.jsx)(n.p,{children:"After you set up the Azure resources, you need to configure Agent Mesh Enterprise to connect to Teams. This configuration requires setting environment variables and updating your deployment configuration."}),"\n",(0,i.jsx)(n.h3,{id:"environment-variables",children:"Environment Variables"}),"\n",(0,i.jsx)(n.p,{children:"Set three environment variables for Teams authentication:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:'TEAMS_BOT_ID="your-azure-bot-id"\nTEAMS_BOT_PASSWORD="your-client-secret-value"\nAZURE_TENANT_ID="your-azure-tenant-id"\n'})}),"\n",(0,i.jsx)(n.admonition,{title:"Tenant ID",type:"info",children:(0,i.jsxs)(n.p,{children:["Find the tenant ID in Azure Portal \u2192 Azure Active Directory \u2192 Overview \u2192 ",(0,i.jsx)(n.code,{children:"Tenant ID"}),". It enables single-tenant authentication, restricting bot access to your organization's Azure AD users."]})}),"\n",(0,i.jsx)(n.h3,{id:"docker-compose-example",children:"Docker Compose Example"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-yaml",children:"version: '3.8'\nservices:\n  agent-mesh-enterprise:\n    image: solace-agent-mesh-enterprise:latest\n    ports:\n      - \"8080:8080\"\n    environment:\n      - TEAMS_BOT_ID=${TEAMS_BOT_ID}\n      - TEAMS_BOT_PASSWORD=${TEAMS_BOT_PASSWORD}\n      - AZURE_TENANT_ID=${AZURE_TENANT_ID}\n      - NAMESPACE=your-namespace\n      - SOLACE_BROKER_URL=ws://broker:8080\n"})}),"\n",(0,i.jsxs)(n.p,{children:["Set ",(0,i.jsx)(n.code,{children:"NAMESPACE"})," to your message broker topic namespace and ",(0,i.jsx)(n.code,{children:"SOLACE_BROKER_URL"})," to your Solace broker instance."]}),"\n",(0,i.jsx)(n.h3,{id:"kubernetes-configmapsecret",children:"Kubernetes ConfigMap/Secret"}),"\n",(0,i.jsxs)(n.p,{children:["Create ",(0,i.jsx)(n.code,{children:"Secret"})," and ",(0,i.jsx)(n.code,{children:"ConfigMap"})," resources in your deployment namespace:"]}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-yaml",children:'apiVersion: v1\nkind: Secret\nmetadata:\n  name: teams-gateway-credentials\ntype: Opaque\nstringData:\n  bot-id: "your-azure-bot-id"\n  bot-password: "your-client-secret-value"\n  tenant-id: "your-azure-tenant-id"\n---\napiVersion: v1\nkind: ConfigMap\nmetadata:\n  name: teams-gateway-config\ndata:\n  default-agent: "orchestrator-agent"\n  http-port: "8080"\n'})}),"\n",(0,i.jsx)(n.p,{children:"Reference these resources in your deployment to inject values as environment variables."}),"\n",(0,i.jsx)(n.h3,{id:"gateway-configuration-options",children:"Gateway Configuration Options"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-yaml",children:'component_name: teams-gateway\ncomponent_module: sam_teams_gateway\ncomponent_config:\n  microsoft_app_id: ${TEAMS_BOT_ID}\n  microsoft_app_password: ${TEAMS_BOT_PASSWORD}\n  microsoft_app_tenant_id: ${AZURE_TENANT_ID}  # Required for single-tenant auth\n  default_agent_name: orchestrator-agent\n  http_port: 8080\n  enable_typing_indicator: true\n  buffer_update_interval_seconds: 2\n  initial_status_message: "Processing your request..."\n  system_purpose: |\n    You are an AI assistant helping users through Microsoft Teams.\n  response_format: |\n    Provide clear, concise responses. Use markdown formatting when appropriate.\n'})}),"\n",(0,i.jsx)(n.p,{children:"Key parameters:"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.code,{children:"microsoft_app_tenant_id"}),": Required for single-tenant authentication; must match your Azure AD tenant ID"]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.code,{children:"default_agent_name"}),": Agent that handles incoming messages"]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.code,{children:"http_port"}),": Must match your container's exposed port"]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.code,{children:"enable_typing_indicator"}),": Shows typing indicator while processing requests"]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.code,{children:"buffer_update_interval_seconds"}),": Controls streaming response update frequency (lower = more real-time, higher = fewer API calls)"]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.code,{children:"initial_status_message"}),": Feedback shown when users first send a message"]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.code,{children:"system_purpose"}),": Defines the bot's role and behavior"]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.code,{children:"response_format"}),": Instructions for response formatting (e.g., markdown)"]}),"\n"]})]})}function p(e={}){const{wrapper:n}={...(0,r.R)(),...e.components};return n?(0,i.jsx)(n,{...e,children:(0,i.jsx)(d,{...e})}):d(e)}},8453:(e,n,t)=>{t.d(n,{R:()=>o,x:()=>a});var s=t(6540);const i={},r=s.createContext(i);function o(e){const n=s.useContext(r);return s.useMemo((function(){return"function"==typeof e?e(n):{...n,...e}}),[n,e])}function a(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(i):e.components||i:o(e.components),s.createElement(r.Provider,{value:n},e.children)}}}]);

solace_agent_mesh/assets/docs/assets/js/66d4869e.5d2e116a.js

@@ -0,0 +1 @@
+"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:()=>l,default:()=>c,frontMatter:()=>r,metadata:()=>i,toc:()=>g});const i=JSON.parse('{"id":"documentation/deploying/logging","title":"Logging","description":"This guide covers the essential information you need to effectively configure and manage logging in your Agent Mesh applications. Proper logging configuration is critical for troubleshooting issues, monitoring system behavior, and maintaining reliable production deployments.","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),s=o(8453);const r={title:"Logging",sidebar_position:35},l="Logging",a={},g=[{value:"Configuration",id:"configuration",level:2},{value:"Default Logging Configuration",id:"default-logging-configuration",level:2},{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:"env-var-substitution",level:2},{value:"Common Configuration Scenarios",id:"common-configuration-scenarios",level:2},{value:"Structured Logging",id:"structured-logging",level:3},{value:"1- Enable JSON Formatter",id:"1--enable-json-formatter",level:4},{value:"2- Configure Contextual Info (Optional)",id:"2--configure-contextual-info-optional",level:4},{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",h4:"h4",header:"header",li:"li",mdxAdmonitionTitle:"mdxAdmonitionTitle",ol:"ol",p:"p",pre:"pre",strong:"strong",ul:"ul",...(0,s.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.jsx)(n.p,{children:"This guide covers the essential information you need to effectively configure and manage logging in your Agent Mesh applications. Proper logging configuration is critical for troubleshooting issues, monitoring system behavior, and maintaining reliable production deployments."}),"\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:"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.jsx)(n.h2,{id:"configuration",children:"Configuration"}),"\n",(0,t.jsxs)(n.p,{children:["Agent Mesh supports logging configuration as either a YAML or JSON file. Both formats leverage Python's ",(0,t.jsx)(n.a,{href:"https://docs.python.org/3/library/logging.config.html#logging.config.dictConfig",children:"dictConfig"})," method for advanced logging features."]}),"\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.yaml"})," 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.jsx)(n.admonition,{type:"info",children:(0,t.jsxs)(n.p,{children:["While the INI format using ",(0,t.jsx)(n.a,{href:"https://docs.python.org/3/library/logging.config.html#configuration-file-format",children:"Python's fileConfig()"})," is still supported by Agent Mesh, it is not recommended due to its limitations compared to YAML and JSON formats."]})}),"\n",(0,t.jsxs)(n.admonition,{title:"Agent/Gateway Specific Logging 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.jsxs)(n.p,{children:["using a dedicated logging configuration file (YAML, JSON) is the recommended and preferred approach. The simple ",(0,t.jsx)(n.code,{children:"log:"})," section configuration has lower precedence and will only be active when a dedicated logging configuration file is not provided."]})]}),"\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.yaml"})," file in your project directory. This file establishes sensible defaults while remaining easy to customize for your specific needs."]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-yaml",children:'# Python logging configuration version (always 1)\nversion: 1\n\n# Don\'t disable existing loggers when this config is loaded\ndisable_existing_loggers: false\n\n# Formatters control the structure and appearance of log messages\nformatters:\n  # Simple human-readable format\n  simpleFormatter:\n    format: "%(asctime)s | %(levelname)-5s | %(threadName)s | %(name)s | %(message)s"\n  \n  # JSON format for structured logging\n  jsonFormatter:\n    "()": pythonjsonlogger.json.JsonFormatter # The python-json-logger package is used for JSON formatting\n    format: "%(asctime)s %(levelname)s %(threadName)s %(name)s %(message)s"\n\n# Handlers determine where log messages go\nhandlers:\n  # Stream handler - outputs logs to console (stdout)\n  streamHandler:\n    class: logging.StreamHandler\n    formatter: simpleFormatter\n    stream: "ext://sys.stdout"\n  \n  # Rotating file handler - writes to log files with automatic rotation\n  rotatingFileHandler:\n    class: logging.handlers.RotatingFileHandler\n    formatter: simpleFormatter\n    filename: sam.log\n    mode: a             # Append mode - don\'t overwrite existing logs\n    maxBytes: 52428800  # 50 MB - rotate when file reaches this size\n    backupCount: 10     # Keep up to 10 historical log files\n\n# Loggers \nloggers:\n  # Keys are logger names used in the application code\n  solace_ai_connector:\n    level: ${LOGGING_SAC_LEVEL, INFO}\n    handlers: []\n  \n  solace_agent_mesh:\n    level: ${LOGGING_SAM_LEVEL, INFO}\n    handlers: []\n  \n  # Special trace logger for detailed troubleshooting. Set to DEBUG to enable.\n  sam_trace:\n    level: ${LOGGING_SAM_TRACE_LEVEL, INFO}\n    handlers: []\n\n# Root logger - applies to all log statements (including those from external libraries) that propagate up to root\n# The root logger also specifies handlers for the application\nroot:\n  level: ${LOGGING_ROOT_LEVEL, WARNING}\n  handlers:\n    - streamHandler\n    - rotatingFileHandler\n'})}),"\n",(0,t.jsxs)(n.admonition,{type:"note",children:[(0,t.jsx)(n.mdxAdmonitionTitle,{}),(0,t.jsx)(n.p,{children:"The examples in this documentation use YAML format, but examples can be easily converted to JSON if preferred."})]}),"\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."]}),"\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:"env-var-substitution",children:"Environment Variable Substitution"}),"\n",(0,t.jsx)(n.p,{children:"All configuration formats (YAML, JSON, and INI) support environment variable substitution using the syntax:"}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-yaml",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:"common-configuration-scenarios",children:"Common Configuration Scenarios"}),"\n",(0,t.jsx)(n.h3,{id:"structured-logging",children:"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 in log aggregation systems like Datadog, Splunk, Elasticsearch, and others."}),"\n",(0,t.jsx)(n.p,{children:"Enabling structured logging includes two steps."}),"\n",(0,t.jsx)(n.h4,{id:"1--enable-json-formatter",children:"1- Enable JSON Formatter"}),"\n",(0,t.jsxs)(n.p,{children:["Structured logging is enabled by assigning the ",(0,t.jsx)(n.code,{children:"jsonFormatter"}),", which is provided in the default logging configuration, to one or more logging handlers in your configuration. This means log messages handled by those specific handlers will be output in structured JSON format."]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-yaml",children:'handlers:\n  rotatingFileHandler:\n    class: logging.handlers.RotatingFileHandler\n    formatter: jsonFormatter  # Changed from simpleFormatter\n    filename: sam.log\n    mode: a\n    maxBytes: 52428800\n    backupCount: 10\n  \n  streamHandler:\n    class: logging.StreamHandler\n    formatter: simpleFormatter  # Kept as simpleFormatter to show handlers can have different formatters\n    stream: "ext://sys.stdout"\n'})}),"\n",(0,t.jsx)(n.h4,{id:"2--configure-contextual-info-optional",children:"2- Configure Contextual Info (Optional)"}),"\n",(0,t.jsxs)(n.p,{children:["Log aggregation systems often expect contextual fields to be included in log records for better filtering, grouping, and analysis. For example, contextual fields like ",(0,t.jsx)(n.code,{children:"service"})," and ",(0,t.jsx)(n.code,{children:"env"})," can be added to each log record to indicate which service generated the log and the environment it ran in."]}),"\n",(0,t.jsxs)(n.p,{children:["To add contextual info to every log record, use ",(0,t.jsx)(n.a,{href:"https://nhairs.github.io/python-json-logger/latest/quickstart/#static-fields",children:"python-json-logger's static_fields feature"})," as shown below:"]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-yaml",children:'  jsonFormatter:\n    "()": pythonjsonlogger.json.JsonFormatter\n    format: "%(asctime)s %(levelname)s %(threadName)s %(name)s %(message)s"\n    static_fields:\n      service: ${SERVICE_NAME, payment-service}\n      env: ${ENV, production}\n'})}),"\n",(0,t.jsxs)(n.p,{children:["With this ",(0,t.jsx)(n.code,{children:"jsonFormatter"})," configuration, all JSON log records will automatically include the specified static fields:"]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-json",children:'{\n   "asctime":"2025-10-30 22:25:56,960",\n   "levelname":"INFO",\n   "threadName":"MainThread",\n   "name":"solace_ai_connector.flow",\n   "message":"Processing message",\n   "service": "payment-service",\n   "env": "production"\n}\n'})}),"\n",(0,t.jsxs)(n.p,{children:["Notice that ",(0,t.jsx)(n.a,{href:"#env-var-substitution",children:"environment variable substitution"})," can be used for increased flexibility."]}),"\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-yaml",children:"loggers:\n  solace_ai_connector:\n    level: INFO\n    handlers: []\n  \n  solace_agent_mesh:\n    level: INFO\n    handlers: []\n  \n  sam_trace:\n    level: INFO\n    handlers: []\n  \n  # Increase verbosity of a specific package\n  solace_agent_mesh.gateway.http_sse:\n    level: DEBUG\n    handlers: []\n  \n  # Increase verbosity of a specific external library\n  google_adk:\n    level: INFO\n    handlers: []\n\nroot:\n  level: WARNING\n  handlers:\n    - streamHandler\n    - rotatingFileHandler\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,s.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:()=>l});var i=o(6540);const t={},s=i.createContext(t);function r(e){const n=i.useContext(s);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:r(e.components),i.createElement(s.Provider,{value:n},e.children)}}}]);

solace_agent_mesh/assets/docs/assets/js/82fbfb93.d98a6526.js

@@ -0,0 +1 @@
+"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":"Microsoft Teams Integration (Enterprise)","permalink":"/solace-agent-mesh/docs/documentation/developing/tutorials/teams-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.cc09c4ff.js

@@ -0,0 +1 @@
+"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[8907],{3780:(e,n,t)=>{t.r(n),t.d(n,{assets:()=>l,contentTitle:()=>o,default:()=>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},{value:"Issues Running A2A Samples with <code>Containerfile</code>",id:"issues-running-a2a-samples-with-containerfile",level:3}];function h(e){const n={a:"a",admonition:"admonition",code:"code",h1:"h1",h2:"h2",h3:"h3",header:"header",li:"li",mermaid:"mermaid",ol:"ol",p:"p",pre:"pre",strong:"strong",table:"table",tbody:"tbody",td:"td",th:"th",thead:"thead",tr:"tr",ul:"ul",...(0,r.R)(),...e.components};return(0,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-card.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-card.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"]}),"\n",(0,i.jsxs)(n.h3,{id:"issues-running-a2a-samples-with-containerfile",children:["Issues Running A2A Samples with ",(0,i.jsx)(n.code,{children:"Containerfile"})]}),"\n",(0,i.jsxs)(n.p,{children:["If you encounter a ",(0,i.jsx)(n.code,{children:"ValueError: Invalid context_id: ... is not a valid UUID."})," when running A2A samples using a ",(0,i.jsx)(n.code,{children:"Containerfile"}),", it may be due to outdated dependencies in the ",(0,i.jsx)(n.code,{children:"uv.lock"})," file. This can happen if the sample is pinned to an older version of the ",(0,i.jsx)(n.code,{children:"a2a-sdk"})," package. For more details, see ",(0,i.jsx)(n.a,{href:"https://github.com/a2aproject/a2a-samples/issues/399",children:"this GitHub issue"}),"."]}),"\n",(0,i.jsx)(n.p,{children:"To resolve this, navigate to the sample's directory and upgrade the dependencies:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:"uv lock --upgrade\n"})}),"\n",(0,i.jsxs)(n.p,{children:["This will update the ",(0,i.jsx)(n.code,{children:"uv.lock"})," file to use the latest version of ",(0,i.jsx)(n.code,{children:"a2a-sdk"}),", which includes the necessary bug fixes."]})]})}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.9232f4b5.js

@@ -0,0 +1 @@
+"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[1537],{9377:(e,n,t)=>{t.r(n),t.d(n,{assets:()=>l,contentTitle:()=>s,default:()=>h,frontMatter:()=>o,metadata:()=>i,toc:()=>c});const i=JSON.parse('{"id":"documentation/developing/tutorials/rag-integration","title":"RAG Integration","description":"This tutorial guides you through setting up and configuring Agent Mesh Retrieval Augmented Generation (RAG) plugin. The RAG plugin enables your agents to answer questions by retrieving information from a knowledge base of your documents.","source":"@site/docs/documentation/developing/tutorials/rag-integration.md","sourceDirName":"documentation/developing/tutorials","slug":"/documentation/developing/tutorials/rag-integration","permalink":"/solace-agent-mesh/docs/documentation/developing/tutorials/rag-integration","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/developing/tutorials/rag-integration.md","tags":[],"version":"current","sidebarPosition":70,"frontMatter":{"title":"RAG Integration","sidebar_position":70,"toc_max_heading_level":4},"sidebar":"docSidebar","previous":{"title":"Slack Integration","permalink":"/solace-agent-mesh/docs/documentation/developing/tutorials/slack-integration"},"next":{"title":"Microsoft Teams Integration (Enterprise)","permalink":"/solace-agent-mesh/docs/documentation/developing/tutorials/teams-integration"}}');var r=t(4848),a=t(8453);const o={title:"RAG Integration",sidebar_position:70,toc_max_heading_level:4},s="RAG Integration",l={},c=[{value:"What is Agent Mesh RAG?",id:"what-is-agent-mesh-rag",level:2},{value:"Prerequisites",id:"prerequisites",level:2},{value:"Adding the RAG Plugin",id:"adding-the-rag-plugin",level:2},{value:"Configuring the RAG Agent",id:"configuring-the-rag-agent",level:2},{value:"Shared Configuration",id:"shared-configuration",level:3},{value:"RAG Pipeline Configuration",id:"rag-pipeline-configuration",level:3},{value:"1. Scanner Configuration",id:"1-scanner-configuration",level:4},{value:"2. Preprocessor Configuration",id:"2-preprocessor-configuration",level:4},{value:"3. Splitter Configuration",id:"3-splitter-configuration",level:4},{value:"4. Embedding Configuration",id:"4-embedding-configuration",level:4},{value:"5. Vector Database Configuration",id:"5-vector-database-configuration",level:4},{value:"6. LLM Configuration",id:"6-llm-configuration",level:4},{value:"7. Retrieval Configuration",id:"7-retrieval-configuration",level:4},{value:"Environment Variables",id:"environment-variables",level:3},{value:"Running the RAG Agent",id:"running-the-rag-agent",level:2},{value:"Testing the RAG Agent",id:"testing-the-rag-agent",level:2},{value:"Ingesting Documents",id:"ingesting-documents",level:3},{value:"Option 1: Automatic Scanning (Batch Ingestion)",id:"option-1-automatic-scanning-batch-ingestion",level:4},{value:"Option 2: Manual Upload via Gateway",id:"option-2-manual-upload-via-gateway",level:4},{value:"Querying the Knowledge Base",id:"querying-the-knowledge-base",level:3},{value:"Troubleshooting",id:"troubleshooting",level:2}];function d(e){const n={a:"a",blockquote:"blockquote",code:"code",h1:"h1",h2:"h2",h3:"h3",h4:"h4",header:"header",li:"li",ol:"ol",p:"p",pre:"pre",strong:"strong",ul:"ul",...(0,a.R)(),...e.components};return(0,r.jsxs)(r.Fragment,{children:[(0,r.jsx)(n.header,{children:(0,r.jsx)(n.h1,{id:"rag-integration",children:"RAG Integration"})}),"\n",(0,r.jsx)(n.p,{children:"This tutorial guides you through setting up and configuring Agent Mesh Retrieval Augmented Generation (RAG) plugin. The RAG plugin enables your agents to answer questions by retrieving information from a knowledge base of your documents."}),"\n",(0,r.jsx)(n.h2,{id:"what-is-agent-mesh-rag",children:"What is Agent Mesh RAG?"}),"\n",(0,r.jsx)(n.p,{children:"The Agent Mesh RAG plugin enhances your agents with the ability to perform retrieval-augmented generation. This means the agent can:"}),"\n",(0,r.jsxs)(n.ul,{children:["\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"Scan"})," documents from various sources (local filesystem, Google Drive, etc.)."]}),"\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"Preprocess"})," and ",(0,r.jsx)(n.strong,{children:"split"})," the text into manageable chunks."]}),"\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"Embed"})," these chunks into vectors and store them in a vector database."]}),"\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"Retrieve"})," relevant chunks of text based on a user's query."]}),"\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"Generate"})," an answer using a large language model (LLM) augmented with the retrieved information."]}),"\n"]}),"\n",(0,r.jsx)(n.p,{children:"This allows you to build agents that can answer questions about your own private data."}),"\n",(0,r.jsx)(n.h2,{id:"prerequisites",children:"Prerequisites"}),"\n",(0,r.jsx)(n.p,{children:"Before you begin, ensure you have:"}),"\n",(0,r.jsxs)(n.ul,{children:["\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/installing-and-configuring/installation",children:"Installed Agent Mesh and the Agent Mesh CLI"}),"."]}),"\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/installing-and-configuring/run-project",children:"Created a new Agent Mesh project"}),"."]}),"\n",(0,r.jsx)(n.li,{children:"Access to a vector database (for example, Qdrant, Chroma, and Pinecone)."}),"\n",(0,r.jsx)(n.li,{children:"Access to an LLM for generation and an embedding model."}),"\n",(0,r.jsx)(n.li,{children:"A directory with some documents for the agent to ingest."}),"\n"]}),"\n",(0,r.jsx)(n.h2,{id:"adding-the-rag-plugin",children:"Adding the RAG Plugin"}),"\n",(0,r.jsx)(n.p,{children:"To add the RAG plugin to your Agent Mesh project, run the following command:"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-sh",children:"sam plugin add my-rag-agent --plugin sam-rag\n"})}),"\n",(0,r.jsxs)(n.p,{children:["Replace ",(0,r.jsx)(n.code,{children:"my-rag-agent"})," with your preferred agent name. This command:"]}),"\n",(0,r.jsxs)(n.ul,{children:["\n",(0,r.jsxs)(n.li,{children:["Installs the ",(0,r.jsx)(n.code,{children:"sam-rag"})," plugin."]}),"\n",(0,r.jsxs)(n.li,{children:["Creates a new agent configuration file at ",(0,r.jsx)(n.code,{children:"configs/agents/my-rag-agent.yaml"}),"."]}),"\n"]}),"\n",(0,r.jsx)(n.h2,{id:"configuring-the-rag-agent",children:"Configuring the RAG Agent"}),"\n",(0,r.jsxs)(n.p,{children:["The RAG agent requires a detailed configuration. Open ",(0,r.jsx)(n.code,{children:"configs/agents/my-rag-agent.yaml"})," to configure the following sections:"]}),"\n",(0,r.jsx)(n.h3,{id:"shared-configuration",children:"Shared Configuration"}),"\n",(0,r.jsxs)(n.p,{children:["Like other agents, the RAG agent needs a connection to the Solace broker and a configured LLM. This is typically done in a ",(0,r.jsx)(n.code,{children:"shared_config.yaml"})," file."]}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-yaml",children:"# configs/shared_config.yaml\nshared_config:\n  - broker_connection: &broker_connection\n      dev_mode: ${SOLACE_DEV_MODE, false}\n      broker_url: ${SOLACE_BROKER_URL, ws://localhost:8008}\n      broker_username: ${SOLACE_BROKER_USERNAME, default}\n      broker_password: ${SOLACE_BROKER_PASSWORD, default}\n      broker_vpn: ${SOLACE_BROKER_VPN, default}\n      temporary_queue: ${USE_TEMPORARY_QUEUES, true}\n\n  - models:\n    general: &general_model\n      model: ${LLM_SERVICE_GENERAL_MODEL_NAME}\n      api_base: ${LLM_SERVICE_ENDPOINT}\n      api_key: ${LLM_SERVICE_API_KEY}\n"})}),"\n",(0,r.jsx)(n.h3,{id:"rag-pipeline-configuration",children:"RAG Pipeline Configuration"}),"\n",(0,r.jsxs)(n.p,{children:["The RAG pipeline has several stages, each with its own configuration block within the ",(0,r.jsx)(n.code,{children:"app_config"})," section of your ",(0,r.jsx)(n.code,{children:"my-rag-agent.yaml"})," file."]}),"\n",(0,r.jsx)(n.h4,{id:"1-scanner-configuration",children:"1. Scanner Configuration"}),"\n",(0,r.jsx)(n.p,{children:"The scanner discovers documents to be ingested. You can configure it to scan a local filesystem or cloud sources."}),"\n",(0,r.jsx)(n.p,{children:(0,r.jsx)(n.strong,{children:"Local Filesystem Example:"})}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-yaml",children:'scanner:\n  batch: true\n  use_memory_storage: true\n  source:\n    type: filesystem\n    directories:\n      - "/path/to/your/documents" # Important: Replace with your actual document directory path\n    filters:\n      file_formats:\n        - ".txt"\n        - ".pdf"\n        - ".md"\n'})}),"\n",(0,r.jsxs)(n.p,{children:[(0,r.jsx)(n.strong,{children:"Multi-Cloud Source Example:"}),"\nYou can also configure multiple sources, including Google Drive, OneDrive, and S3."]}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-yaml",children:'scanner:\n  batch: true\n  use_memory_storage: true\n  sources:\n    - type: filesystem\n      directories: ["${LOCAL_DOCUMENTS_PATH}"]\n    - type: google_drive\n      credentials_path: "${GOOGLE_DRIVE_CREDENTIALS_PATH}"\n      folders:\n        - folder_id: "${GOOGLE_DRIVE_FOLDER_ID_1}"\n          name: "Documents"\n          recursive: true\n'})}),"\n",(0,r.jsx)(n.h4,{id:"2-preprocessor-configuration",children:"2. Preprocessor Configuration"}),"\n",(0,r.jsx)(n.p,{children:"The preprocessor cleans the text extracted from documents."}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-yaml",children:"preprocessor:\n  default_preprocessor:\n    type: enhanced\n    params:\n      lowercase: true\n      normalize_whitespace: true\n      remove_urls: true\n  preprocessors:\n    pdf: \n      type: document\n      params:\n        lowercase: true\n        normalize_whitespace: true\n        remove_non_ascii: true\n        remove_urls: true\n"})}),"\n",(0,r.jsx)(n.h4,{id:"3-splitter-configuration",children:"3. Splitter Configuration"}),"\n",(0,r.jsx)(n.p,{children:"The splitter breaks down large documents into smaller chunks. Different splitters are available for different file types."}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-yaml",children:"splitter:\n  default_splitter:\n    type: recursive_character\n    params:\n      chunk_size: 2048\n      chunk_overlap: 400\n  splitters:\n    markdown:\n      type: markdown\n      params:\n        chunk_size: 2048\n        chunk_overlap: 400\n    pdf:\n      type: token\n      params:\n        chunk_size: 500\n        chunk_overlap: 100\n"})}),"\n",(0,r.jsx)(n.h4,{id:"4-embedding-configuration",children:"4. Embedding Configuration"}),"\n",(0,r.jsx)(n.p,{children:"This section defines the model used to create vector embeddings from the text chunks."}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-yaml",children:'embedding:\n  embedder_type: "openai"\n  embedder_params:\n    model: "${OPENAI_EMBEDDING_MODEL}"\n    api_key: "${OPENAI_API_KEY}"\n    api_base: "${OPENAI_API_ENDPOINT}"\n  normalize_embeddings: true\n'})}),"\n",(0,r.jsx)(n.h4,{id:"5-vector-database-configuration",children:"5. Vector Database Configuration"}),"\n",(0,r.jsx)(n.p,{children:"Configure the connection to your vector database where the embeddings are stored."}),"\n",(0,r.jsx)(n.p,{children:(0,r.jsx)(n.strong,{children:"Qdrant Example:"})}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-yaml",children:'vector_db:\n  db_type: "qdrant"\n  db_params:\n    url: "${QDRANT_URL}"\n    api_key: "${QDRANT_API_KEY}"\n    collection_name: "${QDRANT_COLLECTION}"\n    embedding_dimension: ${QDRANT_EMBEDDING_DIMENSION}\n'})}),"\n",(0,r.jsx)(n.p,{children:(0,r.jsx)(n.strong,{children:"Chroma Example:"})}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-yaml",children:'vector_db:\n  db_type: "chroma"\n  db_params:\n    host: "${CHROMA_HOST}"\n    port: "${CHROMA_PORT}"\n    collection_name: "${CHROMA_COLLECTION}"\n'})}),"\n",(0,r.jsx)(n.h4,{id:"6-llm-configuration",children:"6. LLM Configuration"}),"\n",(0,r.jsx)(n.p,{children:"Configure the LLM that is used to generate answers based on the retrieved context."}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-yaml",children:'llm:\n  load_balancer:\n    - model_name: "gpt-4o"\n      litellm_params:\n        model: "openai/${OPENAI_MODEL_NAME}"\n        api_key: "${OPENAI_API_KEY}"\n        api_base: "${OPENAI_API_ENDPOINT}"\n'})}),"\n",(0,r.jsx)(n.h4,{id:"7-retrieval-configuration",children:"7. Retrieval Configuration"}),"\n",(0,r.jsx)(n.p,{children:"This defines how many document chunks are retrieved to answer a query."}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-yaml",children:"retrieval:\n  top_k: 7\n"})}),"\n",(0,r.jsx)(n.h3,{id:"environment-variables",children:"Environment Variables"}),"\n",(0,r.jsxs)(n.p,{children:["The RAG agent relies heavily on environment variables. Here are some of the most important ones you'll need to set in your ",(0,r.jsx)(n.code,{children:".env"})," file:"]}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-bash",children:'# Solace Connection\nSOLACE_BROKER_URL=ws://localhost:8008\nSOLACE_BROKER_VPN=default\nSOLACE_BROKER_USERNAME=default\nSOLACE_BROKER_PASSWORD=default\nNAMESPACE=my-org/dev\n\n# LLM and Embedding Models\nOPENAI_API_KEY="your-openai-api-key"\nOPENAI_API_ENDPOINT="your-openai-api-endpoint"\nOPENAI_MODEL_NAME="model name. E.g., gpt-4o"\nOPENAI_EMBEDDING_MODEL="embedding model name. E.g., text-embedding-3-small"\n\n# Vector Database (Qdrant example)\nQDRANT_URL="Qdrant url"\nQDRANT_API_KEY="API key"\nQDRANT_COLLECTION="my-rag-collection"\nQDRANT_EMBEDDING_DIMENSION=1536 # Depends on your embedding model\n\n# Scanner\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/{e6f9706b.045d0fa1.js → e6f9706b.4488e34c.js}

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