solace-agent-mesh 1.11.2__py3-none-any.whl → 1.12.0__py3-none-any.whl

solace_agent_mesh/assets/docs/assets/js/547e15cc.2f7790c1.js

@@ -1 +0,0 @@
-"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[9324],{305:(e,n,t)=>{t.r(n),t.d(n,{assets:()=>r,contentTitle:()=>o,default:()=>h,frontMatter:()=>a,metadata:()=>i,toc:()=>c});const i=JSON.parse('{"id":"documentation/components/plugins","title":"Plugins","description":"Plugins provide a mechanism to extend the functionality of Agent Mesh in a modular, shareable, and reusable way. The current plugin ecosystem includes agents, gateways, and specialized integrations.","source":"@site/docs/documentation/components/plugins.md","sourceDirName":"documentation/components","slug":"/documentation/components/plugins","permalink":"/solace-agent-mesh/docs/documentation/components/plugins","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/components/plugins.md","tags":[],"version":"current","sidebarPosition":270,"frontMatter":{"title":"Plugins","sidebar_position":270},"sidebar":"docSidebar","previous":{"title":"Gateways","permalink":"/solace-agent-mesh/docs/documentation/components/gateways"},"next":{"title":"Projects","permalink":"/solace-agent-mesh/docs/documentation/components/projects"}}');var s=t(4848),l=t(8453);const a={title:"Plugins",sidebar_position:270},o=void 0,r={},c=[{value:"Official Core Plugins",id:"official-core-plugins",level:3},{value:"Create a Plugin",id:"create-a-plugin",level:2},{value:"Build the Plugin",id:"build-the-plugin",level:3},{value:"Share the Plugin",id:"share-the-plugin",level:3},{value:"Use a Plugin",id:"use-a-plugin",level:2},{value:"Plugin Catalog Dashboard",id:"plugin-catalog-dashboard",level:2},{value:"Agent or Plugin: Which To Use?",id:"agent-or-plugin-which-to-use",level:2},{value:"When To Use a Standalone Agent",id:"when-to-use-a-standalone-agent",level:3},{value:"When To Use an Agent Plugin",id:"when-to-use-an-agent-plugin",level:3},{value:"Recommendation",id:"recommendation",level:3}];function d(e){const n={a:"a",admonition:"admonition",code:"code",h2:"h2",h3:"h3",li:"li",p:"p",pre:"pre",strong:"strong",table:"table",tbody:"tbody",td:"td",th:"th",thead:"thead",tr:"tr",ul:"ul",...(0,l.R)(),...e.components};return(0,s.jsxs)(s.Fragment,{children:[(0,s.jsx)(n.p,{children:"Plugins provide a mechanism to extend the functionality of Agent Mesh in a modular, shareable, and reusable way. The current plugin ecosystem includes agents, gateways, and specialized integrations."}),"\n",(0,s.jsx)(n.admonition,{title:"In one sentence",type:"tip",children:(0,s.jsx)(n.p,{children:"Plugins are modular Python packages that extend Solace the capabilities of Agent Mesh through agents, gateways, and specialized integrations."})}),"\n",(0,s.jsxs)(n.p,{children:["Plugins are packaged as Python modules that can be installed using various package managers (",(0,s.jsx)(n.code,{children:"pip"}),", ",(0,s.jsx)(n.code,{children:"uv"}),", ",(0,s.jsx)(n.code,{children:"poetry"}),", ",(0,s.jsx)(n.code,{children:"conda"}),"). They integrate seamlessly with the A2A protocol and can provide:"]}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Agent Plugins"}),": Specialized agents with domain-specific capabilities"]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Gateway Plugins"}),": New interface types for external system integration"]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Custom Plugins"}),": Custom integrations such as HR providers."]}),"\n"]}),"\n",(0,s.jsx)(n.p,{children:"All plugin interactions (create, build, add) are managed through the Agent Mesh CLI."}),"\n",(0,s.jsx)(n.admonition,{type:"info",children:(0,s.jsxs)(n.p,{children:["Run ",(0,s.jsx)(n.code,{children:"sam plugin --help"})," to see the list of available commands for plugins."]})}),"\n",(0,s.jsx)(n.h3,{id:"official-core-plugins",children:"Official Core Plugins"}),"\n",(0,s.jsxs)(n.p,{children:["Agent Mesh comes with a set of official core plugins that can be used to extend the functionality of the system. You can find the repository of the official core plugins ",(0,s.jsx)(n.a,{href:"https://github.com/SolaceLabs/solace-agent-mesh-core-plugins",children:"here \ud83d\udd17"}),"."]}),"\n",(0,s.jsxs)(n.p,{children:["For more information about how to use the official core plugins, see ",(0,s.jsx)(n.a,{href:"#use-a-plugin",children:"Use Plugins"}),"."]}),"\n",(0,s.jsx)(n.h2,{id:"create-a-plugin",children:"Create a Plugin"}),"\n",(0,s.jsxs)(n.p,{children:["To get started, ",(0,s.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/installing-and-configuring/installation",children:"install the Agent Mesh CLI"})," and run the following command:"]}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-bash",children:"solace-agent-mesh plugin create <plugin-name>\n"})}),"\n",(0,s.jsx)(n.p,{children:"Follow the prompts to create a new plugin. A plugin can be one of the following types:"}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Agent Plugin"}),": Contains custom agents that can be used in a Agent Mesh project."]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Gateway Plugin"}),": Contains custom gateways that can be used in a Agent Mesh project."]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Custom Plugin"}),": Contains custom integrations such as HR providers or other specialized functionality."]}),"\n"]}),"\n",(0,s.jsx)(n.p,{children:"The Agent Mesh CLI creates a directory with the provided name and the following structure:"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{children:"plugin-name/\n\u251c\u2500 config.yaml\n\u251c\u2500 src/\n\u2502  \u251c\u2500 __init__.py\n\u2502  \u251c\u2500 [...Other type specific python files]\n\u251c\u2500 .gitignore\n\u251c\u2500 pyproject.toml\n\u251c\u2500 README.md\n"})}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:["The ",(0,s.jsx)(n.code,{children:"src"})," directory contains the python source code."]}),"\n",(0,s.jsxs)(n.li,{children:["The ",(0,s.jsx)(n.code,{children:"config.yaml"})," file holds the configuration for the plugin, and how to be used in a Agent Mesh application."]}),"\n"]}),"\n",(0,s.jsx)(n.p,{children:"Once the plugin is created, you can start customizing the config.yaml or the python files."}),"\n",(0,s.jsx)(n.h3,{id:"build-the-plugin",children:"Build the Plugin"}),"\n",(0,s.jsxs)(n.p,{children:["Building the plugin creates a Python wheel package that can be installed using ",(0,s.jsx)(n.code,{children:"pip"})," or other package managers."]}),"\n",(0,s.jsxs)(n.p,{children:["Python ",(0,s.jsx)(n.code,{children:"build"})," package must be installed already since ",(0,s.jsx)(n.code,{children:"sam plugin build"})," command uses ",(0,s.jsx)(n.code,{children:"build"})," package, if not, run ",(0,s.jsx)(n.code,{children:"pip install build"}),"."]}),"\n",(0,s.jsx)(n.p,{children:"To build the plugin, run the following Agent Mesh CLI command:"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-bash",children:"solace-agent-mesh plugin build\n"})}),"\n",(0,s.jsxs)(n.p,{children:["The plugin uses the standard ",(0,s.jsx)(n.code,{children:"pyproject.toml"})," file to build the package."]}),"\n",(0,s.jsx)(n.h3,{id:"share-the-plugin",children:"Share the Plugin"}),"\n",(0,s.jsxs)(n.p,{children:["To share the plugin, you can upload the wheel package to a package repository or share the wheel package directly, or any other valid way to share a ",(0,s.jsx)(n.code,{children:"pyproject"})," project."]}),"\n",(0,s.jsx)(n.h2,{id:"use-a-plugin",children:"Use a Plugin"}),"\n",(0,s.jsxs)(n.p,{children:["To use a plugin in your project, use the ",(0,s.jsx)(n.code,{children:"plugin add"})," command, which performs two steps under-the-hood:"]}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:["Locates the plugin or installs the plugin package using a Python package manager (like ",(0,s.jsx)(n.code,{children:"pip"})," or ",(0,s.jsx)(n.code,{children:"uv"}),")"]}),"\n",(0,s.jsx)(n.li,{children:"Creates a component instance based on the plugin"}),"\n"]}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-bash",children:"solace-agent-mesh plugin add <COMPONENT_NAME> --plugin <PLUGIN_NAME>\n"})}),"\n",(0,s.jsx)(n.p,{children:"where:"}),"\n",(0,s.jsxs)(n.p,{children:[(0,s.jsx)(n.code,{children:"<COMPONENT_NAME>"})," is the name you choose for the component instance in your project."]}),"\n",(0,s.jsxs)(n.p,{children:[(0,s.jsx)(n.code,{children:"<PLUGIN_NAME>"}),", you can use:"]}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:["Name of the plugin as published to a package manager like ",(0,s.jsx)(n.code,{children:"pypi"}),", for example ",(0,s.jsx)(n.code,{children:"my-plugin"})]}),"\n",(0,s.jsx)(n.li,{children:"Name of the plugin that has been already installed into your Python environment."}),"\n",(0,s.jsxs)(n.li,{children:["A local path to the plugin directory, for example ",(0,s.jsx)(n.code,{children:"./my-plugin"})]}),"\n",(0,s.jsxs)(n.li,{children:["A path to a wheel package, for example ",(0,s.jsx)(n.code,{children:"./my-plugin/dist/my_plugin-0.1.0-py3-none-any.whl"})]}),"\n",(0,s.jsxs)(n.li,{children:["A URL to a git repository, for example ",(0,s.jsx)(n.code,{children:"git+https://github.com/<USERNAME>/<REPOSITORY>"}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:["If the plugin is in a subdirectory of the repository, you can specify the subdirectory using the ",(0,s.jsx)(n.code,{children:"git+https://github.com/<USERNAME>/<REPOSITORY>#subdirectory=<PLUGIN_NAME>"})," syntax."]}),"\n"]}),"\n"]}),"\n"]}),"\n",(0,s.jsx)(n.p,{children:"The CLI handles both steps automatically, or you can manage the plugin installation yourself using your preferred Python package manager."}),"\n",(0,s.jsxs)(n.admonition,{type:"tip",children:[(0,s.jsxs)(n.p,{children:["You can also customize the python package manager command used to install the plugin by setting the ",(0,s.jsx)(n.code,{children:"SAM_PLUGIN_INSTALL_COMMAND"})," environment variable or passing the ",(0,s.jsx)(n.code,{children:"--install-command"})," option to the ",(0,s.jsx)(n.code,{children:"plugin add"})," command.\nFor example, to use ",(0,s.jsx)(n.code,{children:"uv"})," as the package manager, you can run:"]}),(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-bash",children:'export SAM_PLUGIN_INSTALL_COMMAND="uv pip install {package}"\n'})}),(0,s.jsx)(n.p,{children:"or"}),(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-bash",children:'solace-agent-mesh plugin add <COMPONENT_NAME> --plugin <PLUGIN_NAME> --install-command "uv pip install {package}"\n'})})]}),"\n",(0,s.jsxs)(n.p,{children:["This command adds the plugin instance configuration to your ",(0,s.jsx)(n.code,{children:"configs"})," directory."]}),"\n",(0,s.jsx)(n.p,{children:"Depending on the plugin, you may need to update the newly added plugin configuration file. Follow the instructions provided by the plugin author for any specific configurations."}),"\n",(0,s.jsx)(n.h2,{id:"plugin-catalog-dashboard",children:"Plugin Catalog Dashboard"}),"\n",(0,s.jsxs)(n.p,{children:["You can manage available plugins with the ",(0,s.jsx)(n.code,{children:"plugin catalog"})," command, which launches a user-friendly interface."]}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-bash",children:"solace-agent-mesh plugin catalog\n"})}),"\n",(0,s.jsx)(n.h2,{id:"agent-or-plugin-which-to-use",children:"Agent or Plugin: Which To Use?"}),"\n",(0,s.jsx)(n.p,{children:"In simple terms, plugins of type agent are just packaged agents. However, there are distinct advantages to each approach, and choosing the right one depends on your use case."}),"\n",(0,s.jsx)(n.p,{children:"Here\u2019s a detailed comparison to help you decide."}),"\n",(0,s.jsxs)(n.table,{children:[(0,s.jsx)(n.thead,{children:(0,s.jsxs)(n.tr,{children:[(0,s.jsx)(n.th,{style:{textAlign:"left"},children:"Feature"}),(0,s.jsxs)(n.th,{style:{textAlign:"left"},children:["Standalone Agent (",(0,s.jsx)(n.code,{children:"sam add agent"}),")"]}),(0,s.jsxs)(n.th,{style:{textAlign:"left"},children:["Agent Plugin (",(0,s.jsx)(n.code,{children:"sam plugin create"}),")"]})]})}),(0,s.jsxs)(n.tbody,{children:[(0,s.jsxs)(n.tr,{children:[(0,s.jsx)(n.td,{style:{textAlign:"left"},children:(0,s.jsx)(n.strong,{children:"Creation"})}),(0,s.jsx)(n.td,{style:{textAlign:"left"},children:"A single command creates a configuration file in your project."}),(0,s.jsx)(n.td,{style:{textAlign:"left"},children:"Creates a complete, standard Python project structure."})]}),(0,s.jsxs)(n.tr,{children:[(0,s.jsx)(n.td,{style:{textAlign:"left"},children:(0,s.jsx)(n.strong,{children:"Structure"})}),(0,s.jsx)(n.td,{style:{textAlign:"left"},children:"Consists of a YAML configuration file and associated Python tool files within a Agent Mesh project."}),(0,s.jsxs)(n.td,{style:{textAlign:"left"},children:["A self-contained Python package with ",(0,s.jsx)(n.code,{children:"pyproject.toml"}),", a ",(0,s.jsx)(n.code,{children:"src"})," directory, and configuration templates."]})]}),(0,s.jsxs)(n.tr,{children:[(0,s.jsx)(n.td,{style:{textAlign:"left"},children:(0,s.jsx)(n.strong,{children:"Packaging"})}),(0,s.jsx)(n.td,{style:{textAlign:"left"},children:"Not packaged. It exists as a component within a larger Agent Mesh project."}),(0,s.jsxs)(n.td,{style:{textAlign:"left"},children:["Packaged into a standard Python wheel (",(0,s.jsx)(n.code,{children:".whl"}),") file using ",(0,s.jsx)(n.code,{children:"sam plugin build"}),"."]})]}),(0,s.jsxs)(n.tr,{children:[(0,s.jsx)(n.td,{style:{textAlign:"left"},children:(0,s.jsx)(n.strong,{children:"Distribution"})}),(0,s.jsx)(n.td,{style:{textAlign:"left"},children:"Shared by copying files or sharing the entire project."}),(0,s.jsx)(n.td,{style:{textAlign:"left"},children:"Easily distributed as a wheel file, via a Git repository, or published to a package index like PyPI."})]}),(0,s.jsxs)(n.tr,{children:[(0,s.jsx)(n.td,{style:{textAlign:"left"},children:(0,s.jsx)(n.strong,{children:"Reusability"})}),(0,s.jsx)(n.td,{style:{textAlign:"left"},children:"Primarily for use within the project where it was created."}),(0,s.jsx)(n.td,{style:{textAlign:"left"},children:"Designed for high reusability across different projects, teams, and communities."})]}),(0,s.jsxs)(n.tr,{children:[(0,s.jsx)(n.td,{style:{textAlign:"left"},children:(0,s.jsx)(n.strong,{children:"Installation"})}),(0,s.jsx)(n.td,{style:{textAlign:"left"},children:"No installation needed. The agent is configured and run as part of the main project."}),(0,s.jsxs)(n.td,{style:{textAlign:"left"},children:["Installed into the Python environment using ",(0,s.jsx)(n.code,{children:"sam plugin add"}),", which handles the package installation."]})]}),(0,s.jsxs)(n.tr,{children:[(0,s.jsx)(n.td,{style:{textAlign:"left"},children:(0,s.jsx)(n.strong,{children:"Versioning"})}),(0,s.jsx)(n.td,{style:{textAlign:"left"},children:"Versioned along with the main project."}),(0,s.jsxs)(n.td,{style:{textAlign:"left"},children:["Can be versioned independently according to Python packaging standards (e.g., ",(0,s.jsx)(n.code,{children:"v0.1.0"}),", ",(0,s.jsx)(n.code,{children:"v0.2.0"}),")."]})]}),(0,s.jsxs)(n.tr,{children:[(0,s.jsx)(n.td,{style:{textAlign:"left"},children:(0,s.jsx)(n.strong,{children:"Development"})}),(0,s.jsx)(n.td,{style:{textAlign:"left"},children:"Simple and direct. Edit files and run. Ideal for rapid prototyping."}),(0,s.jsx)(n.td,{style:{textAlign:"left"},children:"Involves a build/install cycle. Better for structured, long-term development."})]})]})]}),"\n",(0,s.jsx)(n.h3,{id:"when-to-use-a-standalone-agent",children:"When To Use a Standalone Agent"}),"\n",(0,s.jsx)(n.p,{children:"Create a standalone agent when:"}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsx)(n.li,{children:"You need to quickly test an idea or build a proof-of-concept."}),"\n",(0,s.jsx)(n.li,{children:"The agent is tightly coupled to a single project and is not intended for reuse."}),"\n",(0,s.jsx)(n.li,{children:"You want the most straightforward path to adding a simple agent without the overhead of a full package structure."}),"\n"]}),"\n",(0,s.jsx)(n.h3,{id:"when-to-use-an-agent-plugin",children:"When To Use an Agent Plugin"}),"\n",(0,s.jsx)(n.p,{children:"Create an agent as a plugin when:"}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsx)(n.li,{children:"You plan to use the same agent in multiple projects."}),"\n",(0,s.jsx)(n.li,{children:"You want to share your agent with other developers, teams, or the open-source community."}),"\n",(0,s.jsx)(n.li,{children:"You are building a robust, production-ready agent that benefits from a formal package structure, dependency management, and versioning."}),"\n",(0,s.jsx)(n.li,{children:"You are building a collection of standardized agents for your organization."}),"\n"]}),"\n",(0,s.jsx)(n.h3,{id:"recommendation",children:"Recommendation"}),"\n",(0,s.jsx)(n.p,{children:"The choice of how to build your agent depends on your goals and the requirements of your project:"}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:["\n",(0,s.jsxs)(n.p,{children:[(0,s.jsx)(n.strong,{children:"Standalone Agents"})," should be viewed as tactical tools for rapid, isolated prototyping. They serve immediate, project-specific needs but do not contribute to a scalable, long-term asset library."]}),"\n"]}),"\n",(0,s.jsxs)(n.li,{children:["\n",(0,s.jsxs)(n.p,{children:[(0,s.jsx)(n.strong,{children:"Agent Plugins"})," are the foundation for building a robust, governable, and reusable AI ecosystem. This model treats AI capabilities as enterprise assets, promoting standardization, reducing redundant development costs, and accelerating innovation across the organization. For any capability intended for broader use or long-term value, the plugin framework is the mandated path to maximize return on investment and ensure architectural integrity."]}),"\n"]}),"\n"]})]})}function h(e={}){const{wrapper:n}={...(0,l.R)(),...e.components};return n?(0,s.jsx)(n,{...e,children:(0,s.jsx)(d,{...e})}):d(e)}},8453:(e,n,t)=>{t.d(n,{R:()=>a,x:()=>o});var i=t(6540);const s={},l=i.createContext(s);function a(e){const n=i.useContext(l);return i.useMemo((function(){return"function"==typeof e?e(n):{...n,...e}}),[n,e])}function o(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(s):e.components||s:a(e.components),i.createElement(l.Provider,{value:n},e.children)}}}]);

solace_agent_mesh/assets/docs/assets/js/5c2bd65f.90a87880.js

@@ -1 +0,0 @@
-"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[5236],{4473:(e,n,t)=>{t.r(n),t.d(n,{assets:()=>l,contentTitle:()=>a,default:()=>u,frontMatter:()=>r,metadata:()=>i,toc:()=>c});const i=JSON.parse('{"id":"documentation/deploying/deployment-options","title":"Choosing Deployment Options","description":"Agent Mesh offers flexible deployment options designed to meet different operational requirements. Understanding these options helps you choose the right approach for your specific environment and scale needs.","source":"@site/docs/documentation/deploying/deployment-options.md","sourceDirName":"documentation/deploying","slug":"/documentation/deploying/deployment-options","permalink":"/solace-agent-mesh/docs/documentation/deploying/deployment-options","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/deploying/deployment-options.md","tags":[],"version":"current","sidebarPosition":10,"frontMatter":{"title":"Choosing Deployment Options","sidebar_position":10},"sidebar":"docSidebar","previous":{"title":"Deploying Agent Mesh","permalink":"/solace-agent-mesh/docs/documentation/deploying/"},"next":{"title":"Kubernetes","permalink":"/solace-agent-mesh/docs/documentation/deploying/kubernetes-deployment"}}');var s=t(4848),o=t(8453);const r={title:"Choosing Deployment Options",sidebar_position:10},a="Choosing Deployment Options",l={},c=[{value:"Development Environment",id:"development-environment",level:2},{value:"Production Environment",id:"production-environment",level:2},{value:"Deploying with Docker",id:"deploying-with-docker",level:3},{value:"Deploying with Kubernetes",id:"deploying-with-kubernetes",level:3},{value:"Separating and Scaling Components",id:"separating-and-scaling-components",level:3},{value:"Managing Storage Requirements",id:"managing-storage-requirements",level:3},{value:"Implementing Security Best Practices",id:"implementing-security-best-practices",level:3},{value:"Configuring Solace Event Broker",id:"configuring-solace-event-broker",level:3},{value:"Setting up Queue Templates",id:"setting-up-queue-templates",level:3}];function d(e){const n={a:"a",admonition:"admonition",br:"br",code:"code",em:"em",h1:"h1",h2:"h2",h3:"h3",header:"header",li:"li",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:"choosing-deployment-options",children:"Choosing Deployment Options"})}),"\n",(0,s.jsx)(n.p,{children:"Agent Mesh offers flexible deployment options designed to meet different operational requirements. Understanding these options helps you choose the right approach for your specific environment and scale needs."}),"\n",(0,s.jsx)(n.h2,{id:"development-environment",children:"Development Environment"}),"\n",(0,s.jsx)(n.p,{children:"During development, simplicity and rapid iteration are key priorities. The Agent Mesh CLI provides a streamlined way to run your entire project as a single application, making it easy to test changes and debug issues locally."}),"\n",(0,s.jsxs)(n.p,{children:["The development setup automatically loads environment variables from your configuration file (typically a ",(0,s.jsx)(n.code,{children:".env"})," file at the project root), eliminating the need for complex environment management:"]}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-bash",children:"sam run\n"})}),"\n",(0,s.jsx)(n.p,{children:"This command starts all configured components together, providing immediate feedback and allowing you to see how different agents interact within your mesh."}),"\n",(0,s.jsx)(n.h2,{id:"production-environment",children:"Production Environment"}),"\n",(0,s.jsx)(n.p,{children:"Production deployments require different considerations than development environments. You need reproducible builds, scalable infrastructure, and robust monitoring capabilities. Containerization addresses these requirements by providing consistent runtime environments and enabling modern orchestration platforms."}),"\n",(0,s.jsx)(n.p,{children:"We recommend using Docker for single-node deployments or Kubernetes for multi-node, scalable deployments. These technologies ensure your application runs consistently across different environments and can scale to meet demand."}),"\n",(0,s.jsx)(n.admonition,{title:"Platform Compatibility",type:"note",children:(0,s.jsxs)(n.p,{children:["If your host system architecture is not ",(0,s.jsx)(n.code,{children:"linux/amd64"}),", add the ",(0,s.jsx)(n.code,{children:"--platform linux/amd64"})," flag when you run the container to ensure compatibility with the pre-built images."]})}),"\n",(0,s.jsx)(n.h3,{id:"deploying-with-docker",children:"Deploying with Docker"}),"\n",(0,s.jsx)(n.p,{children:"Docker provides an excellent foundation for production deployments because it packages your application with all its dependencies into a portable container. This approach ensures consistent behavior across different environments and simplifies deployment processes."}),"\n",(0,s.jsx)(n.p,{children:"The following Dockerfile demonstrates how to containerize an Agent Mesh project:"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-Dockerfile",children:'FROM solace/solace-agent-mesh:latest\nWORKDIR /app\n\n# Install Python dependencies\nCOPY ./requirements.txt /app/requirements.txt\nRUN python3.11 -m pip install --no-cache-dir -r /app/requirements.txt\n\n# Copy project files\nCOPY . /app\n\nCMD ["run", "--system-env"]\n\n# To run one specific component, use:\n# CMD ["run", "--system-env", "configs/agents/main_orchestrator.yaml"]\n\n'})}),"\n",(0,s.jsxs)(n.p,{children:["To optimize build performance and security, create a ",(0,s.jsx)(n.code,{children:".dockerignore"})," file that excludes unnecessary files from the Docker build context:"]}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{children:".env\n*.log\ndist\n.git\n.vscode\n.DS_Store\n"})}),"\n",(0,s.jsx)(n.h3,{id:"deploying-with-kubernetes",children:"Deploying with Kubernetes"}),"\n",(0,s.jsx)(n.p,{children:"Kubernetes excels at managing containerized applications at scale, providing features like automatic scaling, rolling updates, and self-healing capabilities. When your Agent Mesh deployment needs to handle varying loads or requires high availability, Kubernetes becomes the preferred orchestration platform."}),"\n",(0,s.jsxs)(n.p,{children:["Agent Mesh provides Helm charts for Kubernetes deployments that handle resource management, scaling, and configuration. For prerequisites, Helm setup, and production configurations, see ",(0,s.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/deploying/kubernetes-deployment",children:"Kubernetes"}),"."]}),"\n",(0,s.jsx)(n.h3,{id:"separating-and-scaling-components",children:"Separating and Scaling Components"}),"\n",(0,s.jsx)(n.p,{children:"A microservices approach to deployment offers significant advantages for production systems. By splitting your Agent Mesh components into separate containers, you achieve better fault isolation, independent scaling, and more granular resource management."}),"\n",(0,s.jsx)(n.p,{children:"This architectural pattern ensures that if one component experiences issues, the rest of your system continues operating normally. When the failed component restarts, it automatically rejoins the mesh through the Solace event broker, maintaining system resilience."}),"\n",(0,s.jsx)(n.p,{children:"To implement component separation:"}),"\n",(0,s.jsxs)(n.p,{children:[(0,s.jsx)(n.strong,{children:"Reuse the same Docker image"}),": Your base container image remains consistent across all components, simplifying maintenance and ensuring compatibility."]}),"\n",(0,s.jsxs)(n.p,{children:[(0,s.jsx)(n.strong,{children:"Customize startup commands"}),": Each container runs only the components it needs by specifying different configuration files in the startup command."]}),"\n",(0,s.jsxs)(n.p,{children:[(0,s.jsx)(n.strong,{children:"Scale independently"}),": Components with higher resource demands or traffic can be scaled separately, optimizing resource utilization and cost."]}),"\n",(0,s.jsx)(n.p,{children:"For example, you might run your main orchestrator in one deployment while scaling your specialized tool agents in separate deployments based on demand."}),"\n",(0,s.jsx)(n.h3,{id:"managing-storage-requirements",children:"Managing Storage Requirements"}),"\n",(0,s.jsx)(n.p,{children:"When deploying multiple containers, shared storage becomes critical for maintaining consistency across your Agent Mesh deployment. All container instances must access the same storage location with identical configurations to ensure proper operation."}),"\n",(0,s.jsx)(n.admonition,{title:"Shared Storage Requirement",type:"warning",children:(0,s.jsx)(n.p,{children:"If using multiple containers, ensure all instances access the same storage with identical configurations. Inconsistent storage configurations can lead to data synchronization issues and unpredictable behavior."})}),"\n",(0,s.jsx)(n.p,{children:"Consider using persistent volumes in Kubernetes or shared file systems in Docker deployments to meet this requirement."}),"\n",(0,s.jsx)(n.h3,{id:"implementing-security-best-practices",children:"Implementing Security Best Practices"}),"\n",(0,s.jsx)(n.p,{children:"Production deployments require robust security measures to protect sensitive data and ensure system integrity. Implementing these practices helps safeguard your Agent Mesh deployment against common security threats."}),"\n",(0,s.jsxs)(n.p,{children:[(0,s.jsx)(n.strong,{children:"Environment Variables and Secrets Management"}),": Never store sensitive information like API keys, passwords, or certificates in ",(0,s.jsx)(n.code,{children:".env"})," files or container images. Instead, use dedicated secret management solutions such as AWS Secrets Manager, HashiCorp Vault, or Kubernetes Secrets. These tools provide encryption at rest, access controls, and audit trails for sensitive data."]}),"\n",(0,s.jsxs)(n.p,{children:[(0,s.jsx)(n.strong,{children:"TLS Encryption"}),": All communication channels should use TLS encryption to protect data in transit. This includes communication between Agent Mesh components and connections to the Solace event broker. TLS prevents eavesdropping and ensures data integrity during transmission."]}),"\n",(0,s.jsxs)(n.p,{children:[(0,s.jsx)(n.strong,{children:"Container Security"}),": Maintain security throughout your container lifecycle by regularly updating base images to include the latest security patches. Implement security scanning tools like Trivy or Clair in your CI/CD pipeline to identify vulnerabilities before deployment. Additionally, run containers with minimal privileges and avoid running processes as root when possible."]}),"\n",(0,s.jsx)(n.h3,{id:"configuring-solace-event-broker",children:"Configuring Solace Event Broker"}),"\n",(0,s.jsx)(n.p,{children:"The Solace event broker serves as the communication backbone for your agent mesh, handling all message routing and delivery between components. For production environments, using a Solace Cloud-managed event broker provides significant advantages over self-managed installations."}),"\n",(0,s.jsx)(n.p,{children:"Solace Cloud-managed event brokers offer built-in high availability, automatic scaling, security updates, and professional support. These managed services eliminate the operational overhead of maintaining event broker infrastructure while providing enterprise-grade reliability and performance."}),"\n",(0,s.jsxs)(n.p,{children:["For more information about cloud-managed options, see ",(0,s.jsx)(n.a,{href:"https://solace.com/products/event-broker/",children:"Solace Cloud"}),". For detailed configuration instructions, see ",(0,s.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/installing-and-configuring/configurations#event-broker-connection",children:"Configuring the Event Broker Connection"}),"."]}),"\n",(0,s.jsx)(n.h3,{id:"setting-up-queue-templates",children:"Setting up Queue Templates"}),"\n",(0,s.jsxs)(n.p,{children:["When the ",(0,s.jsx)(n.code,{children:"app.broker.temporary_queue"})," parameter is set to ",(0,s.jsx)(n.code,{children:"true"})," (default), the system uses ",(0,s.jsx)(n.a,{href:"https://docs.solace.com/Messaging/Guaranteed-Msg/Endpoints.htm#temporary-endpoints",children:"temporary endpoints"})," for A2A communication. Temporary queues are automatically created and deleted by the broker, which simplifies management and removes the need for manual cleanup. However, temporary queues do not support multiple client connections to the same queue, which may be limiting in scenarios where you run multiple instances of the same agent or need to start a new instance while an old one is still running."]}),"\n",(0,s.jsxs)(n.p,{children:["If you set ",(0,s.jsx)(n.code,{children:"temporary_queue"})," to ",(0,s.jsx)(n.code,{children:"false"}),", the system will create a durable queue for the client. Durable queues persist beyond the lifetime of a client connection, allowing multiple clients to connect to the same queue and ensuring messages are not lost if the client disconnects. However, this requires manual management of queues, including cleanup of unused ones."]}),"\n",(0,s.jsx)(n.admonition,{type:"tip",children:(0,s.jsxs)(n.p,{children:["For production environments that are container-managed (for example, Kubernetes), we recommend setting ",(0,s.jsx)(n.code,{children:"temporary_queue"})," to ",(0,s.jsx)(n.code,{children:"false"})," by setting the environment variable ",(0,s.jsx)(n.code,{children:"USE_TEMPORARY_QUEUES=false"}),".",(0,s.jsx)(n.br,{}),"\n","Using temporary queues in these environments can cause startup issues, since a new container may fail to connect if the previous instance is still running and holding the queue. Durable queues avoid this by allowing multiple agent instances to share the same queue."]})}),"\n",(0,s.jsxs)(n.p,{children:["To prevent messages from piling up in a durable queue when an agent is not running, the queue should be configured with a message TTL (time-to-live) and the ",(0,s.jsx)(n.strong,{children:"Respect Message TTL"})," option enabled. To apply these settings automatically for all new queues, you can create a ",(0,s.jsx)(n.a,{href:"https://docs.solace.com/Messaging/Guaranteed-Msg/Configuring-Endpoint-Templates.htm",children:"Queue Template"})," for your Solace Agent Mesh clients."]}),"\n",(0,s.jsx)(n.p,{children:"To create a queue template in the Solace Cloud Console:"}),"\n",(0,s.jsxs)(n.ol,{children:["\n",(0,s.jsxs)(n.li,{children:["Navigate to ",(0,s.jsx)(n.strong,{children:"Message VPNs"})," and select your VPN."]}),"\n",(0,s.jsxs)(n.li,{children:["Go to the ",(0,s.jsx)(n.strong,{children:"Queues"})," page."]}),"\n",(0,s.jsxs)(n.li,{children:["Open the ",(0,s.jsx)(n.strong,{children:"Templates"})," tab."]}),"\n",(0,s.jsxs)(n.li,{children:["Click ",(0,s.jsx)(n.strong,{children:"+ Queue Template"}),"."]}),"\n"]}),"\n",(0,s.jsx)(n.p,{children:"Use the following settings for the template:"}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Queue Name Filter"})," = ",(0,s.jsx)(n.code,{children:"{NAMESPACE}/>"}),(0,s.jsx)(n.br,{}),"\n","(Replace ",(0,s.jsx)(n.code,{children:"{NAMESPACE}"})," with the namespace defined in your configuration, for example, ",(0,s.jsx)(n.code,{children:"sam/"}),")"]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Respect TTL"})," = ",(0,s.jsx)(n.code,{children:"true"}),(0,s.jsx)(n.br,{}),"\n",(0,s.jsx)(n.em,{children:"(Under: Advanced Settings > Message Expiry)"})]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Maximum TTL (sec)"})," = ",(0,s.jsx)(n.code,{children:"18000"}),(0,s.jsx)(n.br,{}),"\n",(0,s.jsx)(n.em,{children:"(Under: Advanced Settings > Message Expiry)"})]}),"\n"]}),"\n",(0,s.jsxs)(n.admonition,{type:"info",children:[(0,s.jsxs)(n.p,{children:["Queue templates are only applied when a new queue is created from the messaging client.",(0,s.jsx)(n.br,{}),"\n","If you have already been running SAM with ",(0,s.jsx)(n.code,{children:"temporary_queue"})," set to ",(0,s.jsx)(n.code,{children:"false"}),", your durable queues were created before the template existed.",(0,s.jsx)(n.br,{}),"\n","To apply TTL settings to those queues, either:"]}),(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:["Enable ",(0,s.jsx)(n.strong,{children:"TTL"})," and ",(0,s.jsx)(n.strong,{children:"Respect TTL"})," manually in the Solace console on each queue, or"]}),"\n",(0,s.jsx)(n.li,{children:"Delete the existing queues and restart SAM to have them recreated automatically using the new template."}),"\n"]})]})]})}function u(e={}){const{wrapper:n}={...(0,o.R)(),...e.components};return n?(0,s.jsx)(n,{...e,children:(0,s.jsx)(d,{...e})}):d(e)}},8453:(e,n,t)=>{t.d(n,{R:()=>r,x:()=>a});var i=t(6540);const s={},o=i.createContext(s);function r(e){const n=i.useContext(o);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(s):e.components||s:r(e.components),i.createElement(o.Provider,{value:n},e.children)}}}]);

solace_agent_mesh/assets/docs/assets/js/64195356.c498c4d0.js

@@ -1 +0,0 @@
-"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[3870],{6247:(e,n,s)=>{s.r(n),s.d(n,{assets:()=>o,contentTitle:()=>c,default:()=>h,frontMatter:()=>a,metadata:()=>i,toc:()=>l});const i=JSON.parse('{"id":"documentation/installing-and-configuring/artifact-storage","title":"Artifact Storage","description":"This guide explains how to configure storage for artifacts\u2014files and data created by your agents\u2014from development to production deployments.","source":"@site/docs/documentation/installing-and-configuring/artifact-storage.md","sourceDirName":"documentation/installing-and-configuring","slug":"/documentation/installing-and-configuring/artifact-storage","permalink":"/solace-agent-mesh/docs/documentation/installing-and-configuring/artifact-storage","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/installing-and-configuring/artifact-storage.md","tags":[],"version":"current","sidebarPosition":360,"frontMatter":{"title":"Artifact Storage","sidebar_position":360},"sidebar":"docSidebar","previous":{"title":"Session Storage","permalink":"/solace-agent-mesh/docs/documentation/installing-and-configuring/session-storage"},"next":{"title":"Developing with Agent Mesh","permalink":"/solace-agent-mesh/docs/documentation/developing/"}}');var t=s(4848),r=s(8453);const a={title:"Artifact Storage",sidebar_position:360},c="Configuring Artifact Storage",o={},l=[{value:"Understanding Artifacts",id:"understanding-artifacts",level:2},{value:"Artifact Storage vs Session Storage",id:"artifact-storage-vs-session-storage",level:3},{value:"Artifact Storage Backends",id:"artifact-storage-backends",level:2},{value:"Filesystem Storage (Default)",id:"filesystem-storage-default",level:3},{value:"S3 (AWS)",id:"s3-aws",level:3},{value:"S3-Compatible API Endpoint",id:"s3-compatible-api-endpoint",level:3},{value:"Google Cloud Storage (GCS)",id:"google-cloud-storage-gcs",level:3},{value:"Understanding Artifact Versioning",id:"understanding-artifact-versioning",level:2},{value:"Configuring Artifact Storage",id:"configuring-artifact-storage-1",level:2},{value:"Development Setup",id:"development-setup",level:3},{value:"AWS Production Deployment",id:"aws-production-deployment",level:3},{value:"On-Premises or Private Cloud",id:"on-premises-or-private-cloud",level:3},{value:"Google Cloud Deployment",id:"google-cloud-deployment",level:3},{value:"Migrating Artifact Storage Backends",id:"migrating-artifact-storage-backends",level:2},{value:"Before Migration",id:"before-migration",level:3},{value:"Migration Steps",id:"migration-steps",level:3},{value:"Data Retention for Artifacts",id:"data-retention-for-artifacts",level:2},{value:"Troubleshooting",id:"troubleshooting",level:2},{value:"Backend Connectivity Issues",id:"backend-connectivity-issues",level:3},{value:"Authentication Errors",id:"authentication-errors",level:3},{value:"Artifact Not Found",id:"artifact-not-found",level:3},{value:"Performance Issues",id:"performance-issues",level:3},{value:"Next Steps",id:"next-steps",level:2}];function d(e){const n={a:"a",code:"code",h1:"h1",h2:"h2",h3:"h3",header:"header",li:"li",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,t.jsxs)(t.Fragment,{children:[(0,t.jsx)(n.header,{children:(0,t.jsx)(n.h1,{id:"configuring-artifact-storage",children:"Configuring Artifact Storage"})}),"\n",(0,t.jsx)(n.p,{children:"This guide explains how to configure storage for artifacts\u2014files and data created by your agents\u2014from development to production deployments."}),"\n",(0,t.jsx)(n.h2,{id:"understanding-artifacts",children:"Understanding Artifacts"}),"\n",(0,t.jsx)(n.p,{children:"Artifacts are files and data created by agents during task execution. Examples include generated reports, analysis results, processed documents, or any files that agents produce for users. Agent Mesh provides built-in tools for agents to create, manage, and reference artifacts."}),"\n",(0,t.jsx)(n.p,{children:"Key characteristics:"}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsx)(n.li,{children:"Automatic versioning: Each time an artifact is updated, a new version is created (v0, v1, v2, etc.)"}),"\n",(0,t.jsx)(n.li,{children:"User-scoped: Artifacts belong to specific users and sessions"}),"\n",(0,t.jsx)(n.li,{children:"Retrievable: Users can access, download, and view artifact history"}),"\n",(0,t.jsx)(n.li,{children:"Tool-driven: Agents use built-in tools to create and manage artifacts"}),"\n"]}),"\n",(0,t.jsx)(n.h3,{id:"artifact-storage-vs-session-storage",children:"Artifact Storage vs Session Storage"}),"\n",(0,t.jsx)(n.p,{children:"Unlike session storage (which is separate for WebUI Gateway and each agent), artifact storage is shared across all agents and gateways in your deployment."}),"\n",(0,t.jsx)(n.p,{children:"How it works:"}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsx)(n.li,{children:"All agents and gateways connect to the same artifact storage backend"}),"\n",(0,t.jsxs)(n.li,{children:["Artifacts are scoped by ",(0,t.jsx)(n.code,{children:"(user_id, session_id, app_name)"})," to maintain isolation"]}),"\n",(0,t.jsx)(n.li,{children:"Any agent or gateway can access artifacts within their scope"}),"\n",(0,t.jsx)(n.li,{children:"This allows agents to share files and data within a conversation"}),"\n"]}),"\n",(0,t.jsx)(n.p,{children:"Example:"}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-yaml",children:'# WebUI Gateway and all agents share this artifact storage\nartifact_service:\n  type: "s3"\n  bucket_name: "shared-artifacts-bucket"\n  region: "us-west-2"\n'})}),"\n",(0,t.jsx)(n.p,{children:"Contrast with session storage:"}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsx)(n.li,{children:"Session storage: Each agent has its own separate database"}),"\n",(0,t.jsx)(n.li,{children:"Artifact storage: All agents and gateways share the same storage backend"}),"\n"]}),"\n",(0,t.jsxs)(n.p,{children:["For session storage configuration, see ",(0,t.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/installing-and-configuring/session-storage",children:"Session Storage"}),"."]}),"\n",(0,t.jsx)(n.h2,{id:"artifact-storage-backends",children:"Artifact Storage Backends"}),"\n",(0,t.jsx)(n.p,{children:"Agent Mesh supports multiple storage backends for artifacts. Choose based on your deployment environment and requirements."}),"\n",(0,t.jsxs)(n.table,{children:[(0,t.jsx)(n.thead,{children:(0,t.jsxs)(n.tr,{children:[(0,t.jsx)(n.th,{children:"Backend"}),(0,t.jsx)(n.th,{children:"Best For"}),(0,t.jsx)(n.th,{children:"Production Ready"}),(0,t.jsx)(n.th,{children:"Setup Complexity"})]})}),(0,t.jsxs)(n.tbody,{children:[(0,t.jsxs)(n.tr,{children:[(0,t.jsx)(n.td,{children:"Filesystem"}),(0,t.jsx)(n.td,{children:"Local development"}),(0,t.jsx)(n.td,{children:"\u274c"}),(0,t.jsx)(n.td,{children:"Simple"})]}),(0,t.jsxs)(n.tr,{children:[(0,t.jsx)(n.td,{children:"S3 (AWS)"}),(0,t.jsx)(n.td,{children:"AWS deployments"}),(0,t.jsx)(n.td,{children:"\u2705"}),(0,t.jsx)(n.td,{children:"Medium"})]}),(0,t.jsxs)(n.tr,{children:[(0,t.jsx)(n.td,{children:"S3-Compatible API"}),(0,t.jsx)(n.td,{children:"On-premises, private cloud"}),(0,t.jsx)(n.td,{children:"\u2705"}),(0,t.jsx)(n.td,{children:"Medium"})]}),(0,t.jsxs)(n.tr,{children:[(0,t.jsx)(n.td,{children:"GCS"}),(0,t.jsx)(n.td,{children:"Google Cloud deployments"}),(0,t.jsx)(n.td,{children:"\u2705"}),(0,t.jsx)(n.td,{children:"Medium"})]})]})]}),"\n",(0,t.jsx)(n.h3,{id:"filesystem-storage-default",children:"Filesystem Storage (Default)"}),"\n",(0,t.jsx)(n.p,{children:"Filesystem storage saves artifacts to local disk directories. This is the default configuration and is suitable for development and local testing."}),"\n",(0,t.jsx)(n.p,{children:"Characteristics:"}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsx)(n.li,{children:"Artifacts stored in transparent directory structure"}),"\n",(0,t.jsx)(n.li,{children:"Data persists across restarts"}),"\n",(0,t.jsx)(n.li,{children:"Single instance only (not shared across pods)"}),"\n",(0,t.jsx)(n.li,{children:"Simple backup (copy directories)"}),"\n"]}),"\n",(0,t.jsx)(n.p,{children:"Use only for local development and single-machine deployments."}),"\n",(0,t.jsx)(n.p,{children:"Configuration:"}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-yaml",children:'artifact_service:\n  type: "filesystem"\n  base_path: "/tmp/sam-artifacts"\n'})}),"\n",(0,t.jsx)(n.p,{children:"Storage structure:"}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{children:"/tmp/sam-artifacts/\n\u251c\u2500\u2500 app-name/\n\u2502   \u2514\u2500\u2500 user-id/\n\u2502       \u251c\u2500\u2500 session-id/\n\u2502       \u2502   \u251c\u2500\u2500 report.pdf/\n\u2502       \u2502   \u2502   \u251c\u2500\u2500 0          (version 0 data)\n\u2502       \u2502   \u2502   \u251c\u2500\u2500 0.metadata (version 0 metadata)\n\u2502       \u2502   \u2502   \u251c\u2500\u2500 1          (version 1 data)\n\u2502       \u2502   \u2502   \u2514\u2500\u2500 1.metadata\n\u2502       \u2502   \u2514\u2500\u2500 data.csv/\n\u2502       \u2502       \u251c\u2500\u2500 0\n\u2502       \u2502       \u2514\u2500\u2500 0.metadata\n\u2502       \u2514\u2500\u2500 user/              (user-scoped artifacts)\n\u2502           \u2514\u2500\u2500 config.json/\n\u2502               \u251c\u2500\u2500 0\n\u2502               \u2514\u2500\u2500 0.metadata\n"})}),"\n",(0,t.jsx)(n.h3,{id:"s3-aws",children:"S3 (AWS)"}),"\n",(0,t.jsx)(n.p,{children:"S3 storage uses Amazon S3 for artifact persistence. This is the recommended production backend for AWS deployments."}),"\n",(0,t.jsx)(n.p,{children:"Characteristics:"}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsx)(n.li,{children:"Highly durable"}),"\n",(0,t.jsx)(n.li,{children:"Scalable to any size"}),"\n",(0,t.jsx)(n.li,{children:"Access from any location"}),"\n",(0,t.jsx)(n.li,{children:"Automatic backups and redundancy"}),"\n",(0,t.jsx)(n.li,{children:"IAM-based security"}),"\n"]}),"\n",(0,t.jsx)(n.p,{children:"Configuration:"}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-yaml",children:'artifact_service:\n  type: "s3"\n  bucket_name: "my-artifacts-bucket"\n  region: "us-west-2"\n'})}),"\n",(0,t.jsx)(n.p,{children:"Environment variables:"}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-bash",children:'export AWS_ACCESS_KEY_ID="your-access-key"\nexport AWS_SECRET_ACCESS_KEY="your-secret-key"\nexport AWS_REGION="us-west-2"\n'})}),"\n",(0,t.jsx)(n.p,{children:"IAM permissions required:"}),"\n",(0,t.jsx)(n.p,{children:"The credentials must have these permissions for the bucket:"}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsx)(n.li,{children:(0,t.jsx)(n.code,{children:"s3:GetObject"})}),"\n",(0,t.jsx)(n.li,{children:(0,t.jsx)(n.code,{children:"s3:PutObject"})}),"\n",(0,t.jsx)(n.li,{children:(0,t.jsx)(n.code,{children:"s3:DeleteObject"})}),"\n",(0,t.jsx)(n.li,{children:(0,t.jsx)(n.code,{children:"s3:ListBucket"})}),"\n"]}),"\n",(0,t.jsx)(n.p,{children:"Example IAM policy:"}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-json",children:'{\n  "Version": "2012-10-17",\n  "Statement": [\n    {\n      "Effect": "Allow",\n      "Action": [\n        "s3:GetObject",\n        "s3:PutObject",\n        "s3:DeleteObject",\n        "s3:ListBucket"\n      ],\n      "Resource": [\n        "arn:aws:s3:::my-artifacts-bucket",\n        "arn:aws:s3:::my-artifacts-bucket/*"\n      ]\n    }\n  ]\n}\n'})}),"\n",(0,t.jsx)(n.h3,{id:"s3-compatible-api-endpoint",children:"S3-Compatible API Endpoint"}),"\n",(0,t.jsx)(n.p,{children:"S3-compatible storage allows any storage service that implements the S3 API to work with Agent Mesh. This includes on-premises solutions and services from cloud providers other than AWS."}),"\n",(0,t.jsx)(n.p,{children:"Characteristics:"}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsx)(n.li,{children:"Works with any S3-compatible API implementation"}),"\n",(0,t.jsx)(n.li,{children:"Custom endpoints for private or on-premises storage"}),"\n",(0,t.jsx)(n.li,{children:"Same versioning and management as AWS S3"}),"\n",(0,t.jsx)(n.li,{children:"Requires compatible storage service"}),"\n"]}),"\n",(0,t.jsx)(n.p,{children:"Configuration:"}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-yaml",children:'artifact_service:\n  type: "s3"\n  bucket_name: "my-artifacts-bucket"\n  endpoint_url: "${S3_ENDPOINT_URL}"\n'})}),"\n",(0,t.jsx)(n.p,{children:"Environment variables:"}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-bash",children:'export S3_ENDPOINT_URL="https://storage.example.com"\nexport S3_ACCESS_KEY_ID="your-access-key"\nexport S3_SECRET_ACCESS_KEY="your-secret-key"\nexport AWS_REGION="us-east-1"  # Required but can be arbitrary for S3-compatible endpoints\n'})}),"\n",(0,t.jsx)(n.p,{children:"Supported services:"}),"\n",(0,t.jsx)(n.p,{children:"This configuration works with any S3-compatible storage service, including self-hosted and cloud-provider solutions. Examples include storage services from various cloud providers and on-premises object storage systems."}),"\n",(0,t.jsx)(n.h3,{id:"google-cloud-storage-gcs",children:"Google Cloud Storage (GCS)"}),"\n",(0,t.jsx)(n.p,{children:"GCS storage uses Google Cloud Storage for artifact persistence. This is the recommended backend for Google Cloud deployments."}),"\n",(0,t.jsx)(n.p,{children:"Characteristics:"}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsx)(n.li,{children:"High availability and durability"}),"\n",(0,t.jsx)(n.li,{children:"Integration with Google Cloud ecosystem"}),"\n",(0,t.jsx)(n.li,{children:"Scalable and managed by Google"}),"\n",(0,t.jsx)(n.li,{children:"Fine-grained IAM controls"}),"\n"]}),"\n",(0,t.jsx)(n.p,{children:"Configuration:"}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-yaml",children:'artifact_service:\n  type: "gcs"\n  bucket_name: "my-artifacts-bucket"\n'})}),"\n",(0,t.jsx)(n.p,{children:"Authentication:"}),"\n",(0,t.jsx)(n.p,{children:"GCS authentication uses Google Cloud Application Default Credentials. Set up via:"}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-bash",children:'export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account.json"\n'})}),"\n",(0,t.jsx)(n.p,{children:"Or configure via environment variables if you use workload identity in Kubernetes."}),"\n",(0,t.jsx)(n.p,{children:"Permissions required:"}),"\n",(0,t.jsx)(n.p,{children:"The service account must have these roles on the bucket:"}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsx)(n.li,{children:(0,t.jsx)(n.code,{children:"roles/storage.objectViewer"})}),"\n",(0,t.jsx)(n.li,{children:(0,t.jsx)(n.code,{children:"roles/storage.objectCreator"})}),"\n",(0,t.jsx)(n.li,{children:(0,t.jsx)(n.code,{children:"roles/storage.objectDeleter"})}),"\n"]}),"\n",(0,t.jsx)(n.h2,{id:"understanding-artifact-versioning",children:"Understanding Artifact Versioning"}),"\n",(0,t.jsx)(n.p,{children:"Agent Mesh automatically manages artifact versions, allowing users to access previous versions of files."}),"\n",(0,t.jsx)(n.p,{children:"How versioning works:"}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsx)(n.li,{children:"First artifact create: version 0"}),"\n",(0,t.jsx)(n.li,{children:"Append or update: version 1 (automatic increment)"}),"\n",(0,t.jsx)(n.li,{children:"Continue appending: version 2, 3, 4, etc."}),"\n",(0,t.jsx)(n.li,{children:"Versions persist independently"}),"\n"]}),"\n",(0,t.jsx)(n.p,{children:"Example lifecycle:"}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{children:"Agent creates report.pdf\n  \u2192 version 0 created\n\nAgent appends more data to report.pdf\n  \u2192 version 1 created (v0 still exists)\n\nAgent appends additional data\n  \u2192 version 2 created (v0 and v1 still exist)\n\nUser can access any version:\n- Latest version (automatic)\n- Specific version (v0, v1, v2)\n- Version history (list all versions)\n"})}),"\n",(0,t.jsx)(n.p,{children:"Metadata:"}),"\n",(0,t.jsx)(n.p,{children:"Each artifact version includes metadata:"}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-json",children:'{\n  "filename": "report.pdf",\n  "mime_type": "application/pdf",\n  "version": 0,\n  "size_bytes": 2048,\n  "timestamp": "2024-10-29T12:34:56Z"\n}\n'})}),"\n",(0,t.jsx)(n.h2,{id:"configuring-artifact-storage-1",children:"Configuring Artifact Storage"}),"\n",(0,t.jsx)(n.p,{children:"Choose your artifact storage backend based on your deployment environment."}),"\n",(0,t.jsx)(n.h3,{id:"development-setup",children:"Development Setup"}),"\n",(0,t.jsx)(n.p,{children:"For local development and testing, use filesystem storage:"}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-yaml",children:'artifact_service:\n  type: "filesystem"\n  base_path: "/tmp/sam-artifacts"\n'})}),"\n",(0,t.jsx)(n.p,{children:"Create the base directory if it doesn't exist:"}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-bash",children:"mkdir -p /tmp/sam-artifacts\n"})}),"\n",(0,t.jsx)(n.h3,{id:"aws-production-deployment",children:"AWS Production Deployment"}),"\n",(0,t.jsx)(n.p,{children:"For production deployments on AWS:"}),"\n",(0,t.jsxs)(n.ol,{children:["\n",(0,t.jsxs)(n.li,{children:["\n",(0,t.jsx)(n.p,{children:(0,t.jsx)(n.strong,{children:"Create S3 Bucket:"})}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-bash",children:"aws s3 mb s3://my-artifacts-bucket --region us-west-2\n"})}),"\n"]}),"\n",(0,t.jsxs)(n.li,{children:["\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Configure IAM User or Role"})," with required permissions (see IAM Policy above)"]}),"\n"]}),"\n",(0,t.jsxs)(n.li,{children:["\n",(0,t.jsx)(n.p,{children:(0,t.jsx)(n.strong,{children:"Configure Agent Mesh:"})}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-yaml",children:'artifact_service:\n  type: "s3"\n  bucket_name: "my-artifacts-bucket"\n  region: "us-west-2"\n'})}),"\n"]}),"\n",(0,t.jsxs)(n.li,{children:["\n",(0,t.jsx)(n.p,{children:(0,t.jsx)(n.strong,{children:"Set Environment Variables:"})}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-bash",children:'export AWS_ACCESS_KEY_ID="your-key"\nexport AWS_SECRET_ACCESS_KEY="your-secret"\nexport AWS_REGION="us-west-2"\n'})}),"\n"]}),"\n"]}),"\n",(0,t.jsx)(n.h3,{id:"on-premises-or-private-cloud",children:"On-Premises or Private Cloud"}),"\n",(0,t.jsx)(n.p,{children:"For on-premises deployments using S3-compatible storage:"}),"\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:"Set Up S3-Compatible Storage"})," (ensure it's running and accessible)"]}),"\n"]}),"\n",(0,t.jsxs)(n.li,{children:["\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Create Bucket:"})," Use your storage system's administration tools"]}),"\n"]}),"\n",(0,t.jsxs)(n.li,{children:["\n",(0,t.jsx)(n.p,{children:(0,t.jsx)(n.strong,{children:"Configure Agent Mesh:"})}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-yaml",children:'artifact_service:\n  type: "s3"\n  bucket_name: "my-bucket"\n  endpoint_url: "${S3_ENDPOINT_URL}"\n'})}),"\n"]}),"\n",(0,t.jsxs)(n.li,{children:["\n",(0,t.jsx)(n.p,{children:(0,t.jsx)(n.strong,{children:"Set Environment Variables:"})}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-bash",children:'export S3_ENDPOINT_URL="https://storage.example.com:9000"\nexport S3_ACCESS_KEY_ID="your-access-key"\nexport S3_SECRET_ACCESS_KEY="your-secret-key"\nexport AWS_REGION="us-east-1"\n'})}),"\n"]}),"\n"]}),"\n",(0,t.jsx)(n.h3,{id:"google-cloud-deployment",children:"Google Cloud Deployment"}),"\n",(0,t.jsx)(n.p,{children:"For production deployments on Google Cloud:"}),"\n",(0,t.jsxs)(n.ol,{children:["\n",(0,t.jsxs)(n.li,{children:["\n",(0,t.jsx)(n.p,{children:(0,t.jsx)(n.strong,{children:"Create GCS Bucket:"})}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-bash",children:"gsutil mb gs://my-artifacts-bucket\n"})}),"\n"]}),"\n",(0,t.jsxs)(n.li,{children:["\n",(0,t.jsx)(n.p,{children:(0,t.jsx)(n.strong,{children:"Set Up Service Account with required permissions"})}),"\n"]}),"\n",(0,t.jsxs)(n.li,{children:["\n",(0,t.jsx)(n.p,{children:(0,t.jsx)(n.strong,{children:"Configure Agent Mesh:"})}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-yaml",children:'artifact_service:\n  type: "gcs"\n  bucket_name: "my-artifacts-bucket"\n'})}),"\n"]}),"\n",(0,t.jsxs)(n.li,{children:["\n",(0,t.jsx)(n.p,{children:(0,t.jsx)(n.strong,{children:"Set Up Authentication:"})}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-bash",children:'export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account.json"\n'})}),"\n"]}),"\n"]}),"\n",(0,t.jsx)(n.h2,{id:"migrating-artifact-storage-backends",children:"Migrating Artifact Storage Backends"}),"\n",(0,t.jsx)(n.p,{children:"Moving from one artifact storage backend to another requires no special migration procedure\u2014the system starts fresh with the new backend."}),"\n",(0,t.jsx)(n.h3,{id:"before-migration",children:"Before Migration"}),"\n",(0,t.jsx)(n.p,{children:"Understand the implications:"}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsx)(n.li,{children:"Existing artifacts stored in the old backend will not be accessible after switching"}),"\n",(0,t.jsx)(n.li,{children:"New artifacts will be stored in the new backend"}),"\n",(0,t.jsx)(n.li,{children:"If you need to preserve existing artifacts, export them first from the old storage"}),"\n"]}),"\n",(0,t.jsx)(n.h3,{id:"migration-steps",children:"Migration Steps"}),"\n",(0,t.jsx)(n.p,{children:"Step 1: Set up new storage backend"}),"\n",(0,t.jsx)(n.p,{children:"Create the new storage location:"}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsxs)(n.li,{children:["For filesystem: ",(0,t.jsx)(n.code,{children:"mkdir -p /path/to/new/storage"})]}),"\n",(0,t.jsx)(n.li,{children:"For S3: Create bucket and set up credentials"}),"\n",(0,t.jsx)(n.li,{children:"For GCS: Create bucket and set up service account"}),"\n"]}),"\n",(0,t.jsx)(n.p,{children:"Step 2: Update configuration"}),"\n",(0,t.jsx)(n.p,{children:"Update your artifact service configuration:"}),"\n",(0,t.jsx)(n.p,{children:"From:"}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-yaml",children:'artifact_service:\n  type: "filesystem"\n  base_path: "/old/path"\n'})}),"\n",(0,t.jsx)(n.p,{children:"To:"}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-yaml",children:'artifact_service:\n  type: "s3"\n  bucket_name: "my-bucket"\n  region: "us-west-2"\n'})}),"\n",(0,t.jsx)(n.p,{children:"Step 3: Set environment variables"}),"\n",(0,t.jsx)(n.p,{children:"Configure credentials for the new backend:"}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-bash",children:'export AWS_ACCESS_KEY_ID="your-key"\nexport AWS_SECRET_ACCESS_KEY="your-secret"\nexport AWS_REGION="us-west-2"\n'})}),"\n",(0,t.jsx)(n.p,{children:"Step 4: Restart application"}),"\n",(0,t.jsx)(n.p,{children:"When the application restarts, it will use the new backend for all subsequent artifact operations."}),"\n",(0,t.jsx)(n.p,{children:"Step 5: Verify"}),"\n",(0,t.jsx)(n.p,{children:"Test artifact creation and retrieval:"}),"\n",(0,t.jsxs)(n.ol,{children:["\n",(0,t.jsx)(n.li,{children:"Create a new artifact"}),"\n",(0,t.jsx)(n.li,{children:"Verify it appears in the new storage backend"}),"\n",(0,t.jsx)(n.li,{children:"Retrieve it through the API or agent tools"}),"\n"]}),"\n",(0,t.jsx)(n.h2,{id:"data-retention-for-artifacts",children:"Data Retention for Artifacts"}),"\n",(0,t.jsx)(n.p,{children:"Like session data, artifact storage can be configured with automatic cleanup policies."}),"\n",(0,t.jsx)(n.p,{children:"Configuration:"}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-yaml",children:"data_retention:\n  enabled: true\n  task_retention_days: 90\n  cleanup_interval_hours: 24\n"})}),"\n",(0,t.jsx)(n.p,{children:"How it works:"}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsxs)(n.li,{children:["Artifacts older than ",(0,t.jsx)(n.code,{children:"task_retention_days"})," may be cleaned up"]}),"\n",(0,t.jsxs)(n.li,{children:["Cleanup runs every ",(0,t.jsx)(n.code,{children:"cleanup_interval_hours"})]}),"\n",(0,t.jsx)(n.li,{children:"Prevents unbounded storage growth"}),"\n"]}),"\n",(0,t.jsx)(n.p,{children:"Check your specific artifact storage backend documentation for retention policies and best practices."}),"\n",(0,t.jsx)(n.h2,{id:"troubleshooting",children:"Troubleshooting"}),"\n",(0,t.jsx)(n.h3,{id:"backend-connectivity-issues",children:"Backend Connectivity Issues"}),"\n",(0,t.jsxs)(n.p,{children:["Error: ",(0,t.jsx)(n.code,{children:"Failed to access storage"})," or ",(0,t.jsx)(n.code,{children:"Connection refused"})]}),"\n",(0,t.jsx)(n.p,{children:"Solutions:"}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsx)(n.li,{children:"Verify storage backend is running and accessible"}),"\n",(0,t.jsx)(n.li,{children:"Check network connectivity and firewall rules"}),"\n",(0,t.jsx)(n.li,{children:"Verify endpoint URL is correct (for S3-compatible)"}),"\n",(0,t.jsx)(n.li,{children:"Check credentials and permissions"}),"\n",(0,t.jsx)(n.li,{children:"Review application logs for detailed errors"}),"\n"]}),"\n",(0,t.jsx)(n.h3,{id:"authentication-errors",children:"Authentication Errors"}),"\n",(0,t.jsxs)(n.p,{children:["Error: ",(0,t.jsx)(n.code,{children:"Access Denied"})," or ",(0,t.jsx)(n.code,{children:"Unauthorized"})]}),"\n",(0,t.jsx)(n.p,{children:"Solutions:"}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsx)(n.li,{children:"Verify AWS/GCS credentials are correct"}),"\n",(0,t.jsx)(n.li,{children:"Confirm IAM/service account has required permissions"}),"\n",(0,t.jsx)(n.li,{children:"Check that credentials are set in environment variables"}),"\n",(0,t.jsx)(n.li,{children:"Verify bucket name is correct and matches configuration"}),"\n"]}),"\n",(0,t.jsx)(n.h3,{id:"artifact-not-found",children:"Artifact Not Found"}),"\n",(0,t.jsxs)(n.p,{children:["Error: ",(0,t.jsx)(n.code,{children:"404 Not Found"})," when retrieving artifact"]}),"\n",(0,t.jsx)(n.p,{children:"Solutions:"}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsx)(n.li,{children:"Verify artifact was successfully created"}),"\n",(0,t.jsx)(n.li,{children:"Check that session ID is correct"}),"\n",(0,t.jsx)(n.li,{children:"Confirm storage backend has the artifact"}),"\n",(0,t.jsx)(n.li,{children:"Verify you're accessing the correct version"}),"\n"]}),"\n",(0,t.jsx)(n.h3,{id:"performance-issues",children:"Performance Issues"}),"\n",(0,t.jsx)(n.p,{children:"Slow artifact creation or retrieval:"}),"\n",(0,t.jsx)(n.p,{children:"Solutions:"}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsx)(n.li,{children:"Check network latency to storage backend"}),"\n",(0,t.jsx)(n.li,{children:"Verify storage backend performance"}),"\n",(0,t.jsx)(n.li,{children:"Check for throttling or rate limiting"}),"\n",(0,t.jsx)(n.li,{children:"Consider object size and any upload/download limits"}),"\n"]}),"\n",(0,t.jsx)(n.h2,{id:"next-steps",children:"Next Steps"}),"\n",(0,t.jsx)(n.p,{children:"After configuring artifact storage, you may want to:"}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsxs)(n.li,{children:["Configure ",(0,t.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/installing-and-configuring/session-storage",children:"Session Storage"})," for conversation persistence"]}),"\n",(0,t.jsxs)(n.li,{children:["Explore ",(0,t.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/developing/create-agents",children:"agent tools"})," for working with artifacts"]}),"\n",(0,t.jsxs)(n.li,{children:["Review ",(0,t.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/deploying/deployment-options",children:"deployment options"})," for production considerations"]}),"\n",(0,t.jsxs)(n.li,{children:["Set up ",(0,t.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/deploying/observability",children:"monitoring and observability"})," to track artifact activity"]}),"\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:()=>a,x:()=>c});var i=s(6540);const t={},r=i.createContext(t);function a(e){const n=i.useContext(r);return i.useMemo((function(){return"function"==typeof e?e(n):{...n,...e}}),[n,e])}function c(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(t):e.components||t:a(e.components),i.createElement(r.Provider,{value:n},e.children)}}}]);

solace_agent_mesh/assets/docs/assets/js/66d4869e.b77431fc.js

@@ -1 +0,0 @@
-"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[3243],{6009:(e,n,o)=>{o.r(n),o.d(n,{assets:()=>a,contentTitle:()=>r,default:()=>d,frontMatter:()=>l,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":"Proxy Configuration","permalink":"/solace-agent-mesh/docs/documentation/deploying/proxy_configuration"}}');var t=o(4848),s=o(8453);const l={title:"Logging",sidebar_position:35},r="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},{value:"Agent-Specific Log File",id:"agent-specific-log-file",level:3}];function c(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 Python's ",(0,t.jsx)(n.code,{children:"fileConfig()"})," is still supported by Agent Mesh, it is not recommended due to ",(0,t.jsx)(n.a,{href:"https://docs.python.org/3/library/logging.config.html#configuration-file-format",children:"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.jsx)(n.p,{children:"While individual agent and gateway YAML files may contain a log section similar to the example below:"}),(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 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  # Colored simple human-readable format \n  coloredFormatter:\n    class: solace_ai_connector.logging.ColoredFormatter\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: "%(timestamp)s %(levelname)s %(threadName)s %(name)s %(message)s"\n    timestamp: "timestamp" # Generates ISO 8601-formatted timestamps for %(timestamp)s placeholder\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: coloredFormatter\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: ${LOGGING_FILE_NAME, 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 ",(0,t.jsx)(n.a,{href:"https://docs.python.org/3/library/logging.handlers.html",children:"Python's 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. 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:"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:"coloredFormatter"})}),": Similar to ",(0,t.jsx)(n.code,{children:"simpleFormatter"})," but with color coding for log levels and backend component logs to enhance readability in the console."]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:(0,t.jsx)(n.code,{children:"jsonFormatter"})}),": JSON format for log aggregation and analysis tools. See ",(0,t.jsx)(n.a,{href:"#structured-logging",children:"Structured Logging"})," for possible customizations."]}),"\n"]}),"\n",(0,t.jsxs)(n.p,{children:["Consult Python's documentation for complete details on ",(0,t.jsx)(n.a,{href:"https://docs.python.org/3/library/logging.html#formatter-objects",children:"formatters"})," and ",(0,t.jsx)(n.a,{href:"https://docs.python.org/3/library/logging.html#logrecord-attributes",children:"available fields"}),"."]}),"\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: ${LOGGING_FILE_NAME, 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.p,{children:"For instance, imagine you are troubleshooting an issue with the HTTP SSE gateway, and you also want to see more detailed logs coming from the google_adk external library, you can add the following loggers:"}),"\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 appear in each log entry, displayed as a dot-separated hierarchy. You can control verbosity at any level of the logger hierarchy."]}),(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."})]}),"\n",(0,t.jsx)(n.h3,{id:"agent-specific-log-file",children:"Agent-Specific Log File"}),"\n",(0,t.jsx)(n.p,{children:"For debugging a specific agent in isolation, you can run your SAM solution across multiple processes, with the agent you want to isolate running by itself with its own dedicated log file. This is particularly useful during development and troubleshooting."}),"\n",(0,t.jsx)(n.p,{children:"To isolate an agent's logs, run your SAM solution in two separate processes:"}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-bash",children:"# Process 1: Run your other components with default logging\nsam run configs/gateways/webui.yaml configs/agents/main_orchestrator.yaml configs/agents/some_other_agents.yaml # logs go to sam.log\n\n# Process 2: Run the isolated agent with its own log file\nexport LOGGING_FILE_NAME=my_isolated_agent.log && sam run configs/agents/my_agent_with_isolated_logs.yaml # logs go to my_isolated_agent.log\n"})}),"\n",(0,t.jsx)(n.p,{children:"This approach allows you to isolate and analyze a specific agent's behavior without interference from other components in your mesh. Each process writes to its own log file, making debugging much easier."})]})}function d(e={}){const{wrapper:n}={...(0,s.R)(),...e.components};return n?(0,t.jsx)(n,{...e,children:(0,t.jsx)(c,{...e})}):c(e)}},8453:(e,n,o)=>{o.d(n,{R:()=>l,x:()=>r});var i=o(6540);const t={},s=i.createContext(t);function l(e){const n=i.useContext(s);return i.useMemo((function(){return"function"==typeof e?e(n):{...n,...e}}),[n,e])}function r(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(t):e.components||t:l(e.components),i.createElement(s.Provider,{value:n},e.children)}}}]);

solace_agent_mesh/assets/docs/assets/js/8024126c.fa0e7186.js

@@ -1 +0,0 @@
-"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[3349],{3085:(e,n,o)=>{o.r(n),o.d(n,{assets:()=>r,contentTitle:()=>l,default:()=>h,frontMatter:()=>a,metadata:()=>t,toc:()=>c});const t=JSON.parse('{"id":"documentation/developing/creating-python-tools","title":"Creating Python Tools","description":"Agent Mesh provides a powerful and unified system for creating custom agent tools using Python. This is the primary way to extend an agent\'s capabilities with your own business logic, integrate with proprietary APIs, or perform specialized data processing.","source":"@site/docs/documentation/developing/creating-python-tools.md","sourceDirName":"documentation/developing","slug":"/documentation/developing/creating-python-tools","permalink":"/solace-agent-mesh/docs/documentation/developing/creating-python-tools","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/developing/creating-python-tools.md","tags":[],"version":"current","sidebarPosition":440,"frontMatter":{"title":"Creating Python Tools","sidebar_position":440},"sidebar":"docSidebar","previous":{"title":"Creating Custom Gateways","permalink":"/solace-agent-mesh/docs/documentation/developing/create-gateways"},"next":{"title":"Creating Service Providers","permalink":"/solace-agent-mesh/docs/documentation/developing/creating-service-providers"}}');var i=o(4848),s=o(8453);const a={title:"Creating Python Tools",sidebar_position:440},l="Creating Python Tools",r={},c=[{value:"Tool Creation Patterns",id:"tool-creation-patterns",level:2},{value:"Pattern 1: Simple Function-Based Tools",id:"pattern-1-simple-function-based-tools",level:2},{value:"Step 1: Write the Tool Function",id:"step-1-write-the-tool-function",level:3},{value:"Step 2: Configure the Tool",id:"step-2-configure-the-tool",level:3},{value:"Pattern 2: Advanced Single-Class Tools",id:"pattern-2-advanced-single-class-tools",level:2},{value:"Step 1: Create the <code>DynamicTool</code> Class",id:"step-1-create-the-dynamictool-class",level:3},{value:"Step 2: Configure the Tool",id:"step-2-configure-the-tool-1",level:3},{value:"Pattern 3: The Tool Provider Factory",id:"pattern-3-the-tool-provider-factory",level:2},{value:"Step 1: Create the Provider and Tools",id:"step-1-create-the-provider-and-tools",level:3},{value:"Step 2: Configure the Provider",id:"step-2-configure-the-provider",level:3},{value:"Managing Tool Lifecycles with <code>init</code> and <code>cleanup</code>",id:"managing-tool-lifecycles-with-init-and-cleanup",level:2},{value:"YAML-Based Lifecycle Hooks",id:"yaml-based-lifecycle-hooks",level:3},{value:"Step 1: Define the Tool and Hook Functions",id:"step-1-define-the-tool-and-hook-functions",level:4},{value:"Step 2: Configure the Hooks in YAML",id:"step-2-configure-the-hooks-in-yaml",level:4},{value:"Class-Based Lifecycle Methods (for <code>DynamicTool</code>)",id:"class-based-lifecycle-methods-for-dynamictool",level:3},{value:"Execution Order and Guarantees",id:"execution-order-and-guarantees",level:3},{value:"Adding Validated Configuration to Dynamic Tools",id:"adding-validated-configuration-to-dynamic-tools",level:2},{value:"Example 1: Using a Pydantic Model with a Single <code>DynamicTool</code>",id:"example-1-using-a-pydantic-model-with-a-single-dynamictool",level:3},{value:"Step 1: Define the Model and Tool Class",id:"step-1-define-the-model-and-tool-class",level:4},{value:"Step 2: Configure the Tool in YAML",id:"step-2-configure-the-tool-in-yaml",level:4},{value:"Example 2: Using a Pydantic Model with a <code>DynamicToolProvider</code>",id:"example-2-using-a-pydantic-model-with-a-dynamictoolprovider",level:3},{value:"Step 1: Define the Model and Provider Class",id:"step-1-define-the-model-and-provider-class",level:4},{value:"Step 2: Configure the Provider in YAML",id:"step-2-configure-the-provider-in-yaml",level:4}];function d(e){const n={code:"code",em:"em",h1:"h1",h2:"h2",h3:"h3",h4:"h4",header:"header",hr:"hr",li:"li",ol:"ol",p:"p",pre:"pre",strong:"strong",table:"table",tbody:"tbody",td:"td",th:"th",thead:"thead",tr:"tr",ul:"ul",...(0,s.R)(),...e.components};return(0,i.jsxs)(i.Fragment,{children:[(0,i.jsx)(n.header,{children:(0,i.jsx)(n.h1,{id:"creating-python-tools",children:"Creating Python Tools"})}),"\n",(0,i.jsx)(n.p,{children:"Agent Mesh provides a powerful and unified system for creating custom agent tools using Python. This is the primary way to extend an agent's capabilities with your own business logic, integrate with proprietary APIs, or perform specialized data processing."}),"\n",(0,i.jsxs)(n.p,{children:["This guide covers the different patterns for creating custom tools, all of which are configured using the versatile ",(0,i.jsx)(n.code,{children:"tool_type: python"}),"."]}),"\n",(0,i.jsx)(n.h2,{id:"tool-creation-patterns",children:"Tool Creation Patterns"}),"\n",(0,i.jsx)(n.p,{children:"There are three primary patterns for creating Python tools, ranging from simple to advanced. You can choose the best pattern for your needs, and even mix and match them within the same project."}),"\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:"Pattern"}),(0,i.jsx)(n.th,{children:"Best For"}),(0,i.jsx)(n.th,{children:"Key Feature"})]})}),(0,i.jsxs)(n.tbody,{children:[(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.td,{children:(0,i.jsx)(n.strong,{children:"Function-Based"})}),(0,i.jsx)(n.td,{children:"Simple, self-contained tools with static inputs."}),(0,i.jsx)(n.td,{children:"Quick and easy; uses function signature."})]}),(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.td,{children:(0,i.jsxs)(n.strong,{children:["Single ",(0,i.jsx)(n.code,{children:"DynamicTool"})," Class"]})}),(0,i.jsx)(n.td,{children:"Tools that require complex logic or a programmatically defined interface."}),(0,i.jsx)(n.td,{children:"Full control over the tool's definition."})]}),(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.td,{children:(0,i.jsxs)(n.strong,{children:[(0,i.jsx)(n.code,{children:"DynamicToolProvider"})," Class"]})}),(0,i.jsx)(n.td,{children:"Generating multiple related tools from a single, configurable source."}),(0,i.jsx)(n.td,{children:"Maximum scalability and code reuse."})]})]})]}),"\n",(0,i.jsxs)(n.p,{children:["All three patterns are configured in your agent's YAML file under the ",(0,i.jsx)(n.code,{children:"tools"})," list with ",(0,i.jsx)(n.code,{children:"tool_type: python"}),"."]}),"\n",(0,i.jsx)(n.hr,{}),"\n",(0,i.jsx)(n.h2,{id:"pattern-1-simple-function-based-tools",children:"Pattern 1: Simple Function-Based Tools"}),"\n",(0,i.jsxs)(n.p,{children:["This is the most straightforward way to create a custom tool. You define a standard Python ",(0,i.jsx)(n.code,{children:"async"})," function, and Agent Mesh automatically introspects its signature and docstring to create the tool definition for the LLM."]}),"\n",(0,i.jsx)(n.h3,{id:"step-1-write-the-tool-function",children:"Step 1: Write the Tool Function"}),"\n",(0,i.jsxs)(n.p,{children:["Create a Python file (e.g., ",(0,i.jsx)(n.code,{children:"src/my_agent/tools.py"}),") and define your tool."]}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-python",children:'# src/my_agent/tools.py\nfrom typing import Any, Dict, Optional\nfrom google.adk.tools import ToolContext\n\nasync def greet_user(\n    name: str,\n    tool_context: Optional[ToolContext] = None,\n    tool_config: Optional[Dict[str, Any]] = None\n) -> Dict[str, Any]:\n    """\n    Greets a user with a personalized message.\n\n    Args:\n        name: The name of the person to greet.\n\n    Returns:\n        A dictionary with the greeting message.\n    """\n    greeting_prefix = "Hello"\n    if tool_config:\n        greeting_prefix = tool_config.get("greeting_prefix", "Hello")\n\n    greeting_message = f"{greeting_prefix}, {name}! Welcome to Agent Mesh!"\n\n    return {\n        "status": "success",\n        "message": greeting_message\n    }\n'})}),"\n",(0,i.jsx)(n.p,{children:(0,i.jsx)(n.strong,{children:"Key Requirements:"})}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:["The function must be ",(0,i.jsx)(n.code,{children:"async def"}),"."]}),"\n",(0,i.jsxs)(n.li,{children:["The function's docstring is used as the tool's ",(0,i.jsx)(n.code,{children:"description"})," for the LLM."]}),"\n",(0,i.jsxs)(n.li,{children:["Type hints (",(0,i.jsx)(n.code,{children:"str"}),", ",(0,i.jsx)(n.code,{children:"int"}),", ",(0,i.jsx)(n.code,{children:"bool"}),") are used to generate the parameter schema."]}),"\n",(0,i.jsxs)(n.li,{children:["The function should accept ",(0,i.jsx)(n.code,{children:"tool_context"})," and ",(0,i.jsx)(n.code,{children:"tool_config"})," as optional keyword arguments to receive framework context and YAML configuration."]}),"\n"]}),"\n",(0,i.jsx)(n.h3,{id:"step-2-configure-the-tool",children:"Step 2: Configure the Tool"}),"\n",(0,i.jsxs)(n.p,{children:["In your agent's YAML configuration, add a ",(0,i.jsx)(n.code,{children:"tool_type: python"})," block and point it to your function."]}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-yaml",children:'# In your agent\'s app_config:\ntools:\n  - tool_type: python\n    component_module: "my_agent.tools"\n    function_name: "greet_user"\n    tool_config:\n      greeting_prefix: "Greetings"\n'})}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.code,{children:"component_module"}),": The Python module path to your tools file."]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.code,{children:"function_name"}),": The exact name of the function to load."]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.code,{children:"tool_config"}),": An optional dictionary passed to your tool at runtime."]}),"\n"]}),"\n",(0,i.jsx)(n.hr,{}),"\n",(0,i.jsx)(n.h2,{id:"pattern-2-advanced-single-class-tools",children:"Pattern 2: Advanced Single-Class Tools"}),"\n",(0,i.jsxs)(n.p,{children:["For tools that require more complex logic\u2014such as defining their interface programmatically based on configuration\u2014you can use a class that inherits from ",(0,i.jsx)(n.code,{children:"DynamicTool"}),"."]}),"\n",(0,i.jsxs)(n.h3,{id:"step-1-create-the-dynamictool-class",children:["Step 1: Create the ",(0,i.jsx)(n.code,{children:"DynamicTool"})," Class"]}),"\n",(0,i.jsxs)(n.p,{children:["Instead of a function, define a class that implements the ",(0,i.jsx)(n.code,{children:"DynamicTool"})," abstract base class."]}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-python",children:'# src/my_agent/tools.py\nfrom typing import Optional, Dict, Any\nfrom google.genai import types as adk_types\nfrom solace_agent_mesh.agent.tools.dynamic_tool import DynamicTool\n\nclass WeatherTool(DynamicTool):\n    """A dynamic tool that fetches current weather information."""\n\n    @property\n    def tool_name(self) -> str:\n        return "get_current_weather"\n\n    @property\n    def tool_description(self) -> str:\n        return "Get the current weather for a specified location."\n\n    @property\n    def parameters_schema(self) -> adk_types.Schema:\n        # Programmatically define the tool\'s parameters\n        return adk_types.Schema(\n            type=adk_types.Type.OBJECT,\n            properties={\n                "location": adk_types.Schema(type=adk_types.Type.STRING, description="The city and state/country."),\n                "units": adk_types.Schema(type=adk_types.Type.STRING, enum=["celsius", "fahrenheit"], nullable=True),\n            },\n            required=["location"],\n        )\n\n    async def _run_async_impl(self, args: Dict[str, Any], **kwargs) -> Dict[str, Any]:\n        location = args["location"]\n        # Access config via self.tool_config\n        api_key = self.tool_config.get("api_key")\n        if not api_key:\n            return {"status": "error", "message": "API key not configured"}\n        # ... implementation to call weather API ...\n        return {"status": "success", "weather": "Sunny"}\n'})}),"\n",(0,i.jsx)(n.h3,{id:"step-2-configure-the-tool-1",children:"Step 2: Configure the Tool"}),"\n",(0,i.jsxs)(n.p,{children:["The YAML configuration is very similar. You can either specify the ",(0,i.jsx)(n.code,{children:"class_name"})," or let Agent Mesh auto-discover it if it's the only ",(0,i.jsx)(n.code,{children:"DynamicTool"})," in the module."]}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-yaml",children:"# In your agent's app_config:\ntools:\n  - tool_type: python\n    component_module: \"my_agent.tools\"\n    # class_name: WeatherTool # Optional if it's the only one\n    tool_config:\n      api_key: ${WEATHER_API_KEY}\n"})}),"\n",(0,i.jsx)(n.hr,{}),"\n",(0,i.jsx)(n.h2,{id:"pattern-3-the-tool-provider-factory",children:"Pattern 3: The Tool Provider Factory"}),"\n",(0,i.jsx)(n.p,{children:"This is the most powerful pattern, designed for generating multiple, related tools from a single module and configuration block. It's perfect for creating toolsets based on external schemas, database tables, or other dynamic sources."}),"\n",(0,i.jsx)(n.h3,{id:"step-1-create-the-provider-and-tools",children:"Step 1: Create the Provider and Tools"}),"\n",(0,i.jsxs)(n.p,{children:["In your tools module, you define your ",(0,i.jsx)(n.code,{children:"DynamicTool"})," classes as before, but you also create a ",(0,i.jsx)(n.strong,{children:"provider"})," class that inherits from ",(0,i.jsx)(n.code,{children:"DynamicToolProvider"}),". This provider acts as a factory."]}),"\n",(0,i.jsxs)(n.p,{children:["You can also use the ",(0,i.jsx)(n.code,{children:"@register_tool"})," decorator on simple functions to have them automatically included by the provider."]}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-python",children:'# src/my_agent/database_tools.py\nfrom typing import Optional, Dict, Any, List\nfrom google.genai import types as adk_types\nfrom solace_agent_mesh.agent.tools.dynamic_tool import DynamicTool, DynamicToolProvider\n\n# --- Tool Implementations ---\nclass DatabaseQueryTool(DynamicTool):\n    # ... (implementation as in previous examples) ...\n    pass\n\nclass DatabaseSchemaTool(DynamicTool):\n    # ... (implementation as in previous examples) ...\n    pass\n\n# --- Tool Provider Implementation ---\nclass DatabaseToolProvider(DynamicToolProvider):\n    """A factory that creates all database-related tools."""\n\n    # Use a decorator for a simple, function-based tool\n\n    def create_tools(self, tool_config: Optional[dict] = None) -> List[DynamicTool]:\n        """\n        Generates a list of all database tools, passing the shared\n        configuration to each one.\n        """\n        # 1. Create tools from any decorated functions in this module\n        tools = self._create_tools_from_decorators(tool_config)\n\n        # 2. Programmatically create and add more complex tools\n        if tool_config and tool_config.get("connection_string"):\n            tools.append(DatabaseQueryTool(tool_config=tool_config))\n            tools.append(DatabaseSchemaTool(tool_config=tool_config))\n\n        return tools\n\n# NOTE that you must use the decorator outside of any class with the provider\'s class name.\n@DatabaseToolProvider.register_tool\nasync def get_database_server_version(tool_config: dict, **kwargs) -> dict:\n    """Returns the version of the connected PostgreSQL server."""\n    # ... implementation ...\n    return {"version": "PostgreSQL 15.3"}\n\n'})}),"\n",(0,i.jsx)(n.h3,{id:"step-2-configure-the-provider",children:"Step 2: Configure the Provider"}),"\n",(0,i.jsxs)(n.p,{children:["You only need a single YAML block. Agent Mesh will automatically detect the ",(0,i.jsx)(n.code,{children:"DynamicToolProvider"})," and use it to load all the tools it generates."]}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-yaml",children:'# In your agent\'s app_config:\ntools:\n  # This single block loads get_database_server_version,\n  # execute_database_query, and get_database_schema.\n  - tool_type: python\n    component_module: "my_agent.database_tools"\n    tool_config:\n      connection_string: ${DB_CONNECTION_STRING}\n      max_rows: 1000\n'})}),"\n",(0,i.jsx)(n.p,{children:"This approach is incredibly scalable, as one configuration entry can bootstrap an entire suite of dynamically generated tools."}),"\n",(0,i.jsx)(n.hr,{}),"\n",(0,i.jsxs)(n.h2,{id:"managing-tool-lifecycles-with-init-and-cleanup",children:["Managing Tool Lifecycles with ",(0,i.jsx)(n.code,{children:"init"})," and ",(0,i.jsx)(n.code,{children:"cleanup"})]}),"\n",(0,i.jsxs)(n.p,{children:["For tools that need to manage resources\u2014such as database connections, API clients, or temporary files\u2014Agent Mesh provides optional ",(0,i.jsx)(n.code,{children:"init"})," and ",(0,i.jsx)(n.code,{children:"cleanup"})," lifecycle hooks. These allow you to run code when the agent starts up and shuts down, ensuring that resources are acquired and released gracefully."]}),"\n",(0,i.jsx)(n.p,{children:"There are two ways to define these hooks:"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:[(0,i.jsxs)(n.strong,{children:["YAML-based (",(0,i.jsx)(n.code,{children:"init_function"}),", ",(0,i.jsx)(n.code,{children:"cleanup_function"}),"):"]})," A flexible method that works for ",(0,i.jsx)(n.em,{children:"any"})," Python tool, including simple function-based ones."]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsxs)(n.strong,{children:["Class-based (",(0,i.jsx)(n.code,{children:"init"}),", ",(0,i.jsx)(n.code,{children:"cleanup"})," methods):"]})," The idiomatic and recommended way for ",(0,i.jsx)(n.code,{children:"DynamicTool"})," and ",(0,i.jsx)(n.code,{children:"DynamicToolProvider"})," classes."]}),"\n"]}),"\n",(0,i.jsx)(n.h3,{id:"yaml-based-lifecycle-hooks",children:"YAML-Based Lifecycle Hooks"}),"\n",(0,i.jsxs)(n.p,{children:["You can add ",(0,i.jsx)(n.code,{children:"init_function"})," and ",(0,i.jsx)(n.code,{children:"cleanup_function"})," to any Python tool's configuration in your agent's YAML. The lifecycle functions must be defined in the same module as the tool itself."]}),"\n",(0,i.jsx)(n.h4,{id:"step-1-define-the-tool-and-hook-functions",children:"Step 1: Define the Tool and Hook Functions"}),"\n",(0,i.jsxs)(n.p,{children:["In your tool's Python file (e.g., ",(0,i.jsx)(n.code,{children:"src/my_agent/db_tools.py"}),"), define the tool function and its corresponding ",(0,i.jsx)(n.code,{children:"init"})," and ",(0,i.jsx)(n.code,{children:"cleanup"})," functions. These functions must be ",(0,i.jsx)(n.code,{children:"async"})," and will receive the agent component instance and the tool's configuration model object as arguments."]}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-python",children:'# src/my_agent/db_tools.py\nfrom solace_agent_mesh.agent.sac.component import SamAgentComponent\nfrom solace_agent_mesh.agent.tools.tool_config_types import AnyToolConfig\nfrom google.adk.tools import ToolContext\nfrom typing import Dict, Any\n\n# --- Lifecycle Hooks ---\n\nasync def initialize_db_connection(component: SamAgentComponent, tool_config_model: AnyToolConfig):\n    """Initializes a database connection and stores it for the agent to use."""\n    print("INFO: Initializing database connection...")\n    # In a real scenario, you would create a client instance\n    db_client = {"connection_string": tool_config_model.tool_config.get("connection_string")}\n    # Store the client in a shared state accessible by the component\n    component.set_agent_specific_state("db_client", db_client)\n    print("INFO: Database client initialized.")\n\nasync def close_db_connection(component: SamAgentComponent, tool_config_model: AnyToolConfig):\n    """Retrieves and closes the database connection."""\n    print("INFO: Closing database connection...")\n    db_client = component.get_agent_specific_state("db_client")\n    if db_client:\n        # In a real scenario, you would call db_client.close()\n        print("INFO: Database connection closed.")\n\n# --- Tool Function ---\n\nasync def query_database(query: str, tool_context: ToolContext, **kwargs) -> Dict[str, Any]:\n    """Queries the database using the initialized connection."""\n    host_component = tool_context._invocation_context.agent.host_component\n    db_client = host_component.get_agent_specific_state("db_client")\n    if not db_client:\n        return {"error": "Database connection not initialized."}\n    # ... use db_client to run query ...\n    return {"result": "some data"}\n'})}),"\n",(0,i.jsx)(n.h4,{id:"step-2-configure-the-hooks-in-yaml",children:"Step 2: Configure the Hooks in YAML"}),"\n",(0,i.jsxs)(n.p,{children:["In your YAML configuration, reference the lifecycle functions by name. The framework will automatically look for them in the ",(0,i.jsx)(n.code,{children:"component_module"}),"."]}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-yaml",children:'# In your agent\'s app_config:\ntools:\n  - tool_type: python\n    component_module: "my_agent.db_tools"\n    function_name: "query_database"\n    tool_config:\n      connection_string: "postgresql://user:pass@host/db"\n\n    # Initialize the tool on startup\n    init_function: "initialize_db_connection"\n\n    # Clean up the tool on shutdown\n    cleanup_function: "close_db_connection"\n'})}),"\n",(0,i.jsxs)(n.h3,{id:"class-based-lifecycle-methods-for-dynamictool",children:["Class-Based Lifecycle Methods (for ",(0,i.jsx)(n.code,{children:"DynamicTool"}),")"]}),"\n",(0,i.jsxs)(n.p,{children:["For tools built with ",(0,i.jsx)(n.code,{children:"DynamicTool"})," or ",(0,i.jsx)(n.code,{children:"DynamicToolProvider"}),", the recommended approach is to override the ",(0,i.jsx)(n.code,{children:"init"})," and ",(0,i.jsx)(n.code,{children:"cleanup"})," methods directly within the class. This co-locates the entire tool's logic and improves encapsulation."]}),"\n",(0,i.jsx)(n.p,{children:(0,i.jsxs)(n.strong,{children:["Example: Adding Lifecycle Methods to a ",(0,i.jsx)(n.code,{children:"DynamicTool"})]})}),"\n",(0,i.jsxs)(n.p,{children:["Here, we extend a ",(0,i.jsx)(n.code,{children:"DynamicTool"})," to manage its own API client."]}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-python",children:'# src/my_agent/api_tool.py\nfrom solace_agent_mesh.agent.sac.component import SamAgentComponent\nfrom solace_agent_mesh.agent.tools.dynamic_tool import DynamicTool\nfrom solace_agent_mesh.agent.tools.tool_config_types import AnyToolConfig\n# Assume WeatherApiClient is a custom class for an external service\nfrom my_agent.api_client import WeatherApiClient\n\nclass WeatherTool(DynamicTool):\n    """A dynamic tool that fetches weather and manages its own API client."""\n\n    async def init(self, component: "SamAgentComponent", tool_config: "AnyToolConfig") -> None:\n        """Initializes the API client when the agent starts."""\n        print("INFO: Initializing Weather API client...")\n        # self.tool_config is the validated Pydantic model or dict from YAML\n        api_key = self.tool_config.get("api_key")\n        self.api_client = WeatherApiClient(api_key=api_key)\n        print("INFO: Weather API client initialized.")\n\n    async def cleanup(self, component: "SamAgentComponent", tool_config: "AnyToolConfig") -> None:\n        """Closes the API client connection when the agent shuts down."""\n        print("INFO: Closing Weather API client...")\n        if hasattr(self, "api_client"):\n            await self.api_client.close()\n            print("INFO: Weather API client closed.")\n\n    # ... other required properties like tool_name, tool_description, etc. ...\n\n    async def _run_async_impl(self, args: dict, **kwargs) -> dict:\n        """Uses the initialized client to perform its task."""\n        location = args.get("location")\n        if not hasattr(self, "api_client"):\n            return {"error": "API client not initialized. Check lifecycle hooks."}\n        weather_data = await self.api_client.get_weather(location)\n        return {"weather": weather_data}\n'})}),"\n",(0,i.jsx)(n.p,{children:"The YAML configuration remains simple, as the lifecycle logic is now part of the tool's code."}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-yaml",children:'# In your agent\'s app_config:\ntools:\n  - tool_type: python\n    component_module: "my_agent.api_tool"\n    class_name: "WeatherTool"\n    tool_config:\n      api_key: ${WEATHER_API_KEY}\n'})}),"\n",(0,i.jsx)(n.h3,{id:"execution-order-and-guarantees",children:"Execution Order and Guarantees"}),"\n",(0,i.jsx)(n.p,{children:"It's important to understand the order in which lifecycle hooks are executed, especially if you mix both YAML-based and class-based methods for a single tool."}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:[(0,i.jsxs)(n.strong,{children:["Initialization (",(0,i.jsx)(n.code,{children:"init"}),"):"]})," All ",(0,i.jsx)(n.code,{children:"init"})," hooks are awaited during agent startup. A failure in any ",(0,i.jsx)(n.code,{children:"init"})," hook will prevent the agent from starting."]}),"\n",(0,i.jsxs)(n.ol,{children:["\n",(0,i.jsxs)(n.li,{children:["The YAML-based ",(0,i.jsx)(n.code,{children:"init_function"})," is executed first."]}),"\n",(0,i.jsxs)(n.li,{children:["The class-based ",(0,i.jsx)(n.code,{children:"init()"})," method is executed second."]}),"\n"]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:[(0,i.jsxs)(n.strong,{children:["Cleanup (",(0,i.jsx)(n.code,{children:"cleanup"}),"):"]})," All registered ",(0,i.jsx)(n.code,{children:"cleanup"})," hooks are executed during agent shutdown. They run in ",(0,i.jsx)(n.strong,{children:"LIFO (Last-In, First-Out)"})," order relative to initialization."]}),"\n",(0,i.jsxs)(n.ol,{children:["\n",(0,i.jsxs)(n.li,{children:["The class-based ",(0,i.jsx)(n.code,{children:"cleanup()"})," method is executed first."]}),"\n",(0,i.jsxs)(n.li,{children:["The YAML-based ",(0,i.jsx)(n.code,{children:"cleanup_function"})," is executed second."]}),"\n"]}),"\n"]}),"\n"]}),"\n",(0,i.jsx)(n.p,{children:"This LIFO order for cleanup is intuitive: the resource that was initialized last is the first one to be torn down."}),"\n",(0,i.jsx)(n.hr,{}),"\n",(0,i.jsx)(n.h2,{id:"adding-validated-configuration-to-dynamic-tools",children:"Adding Validated Configuration to Dynamic Tools"}),"\n",(0,i.jsxs)(n.p,{children:["For any class-based tool (",(0,i.jsx)(n.code,{children:"DynamicTool"})," or ",(0,i.jsx)(n.code,{children:"DynamicToolProvider"}),") that requires configuration, this is the recommended pattern. By linking a Pydantic model to your tool class, you can add automatic validation and type safety to your ",(0,i.jsx)(n.code,{children:"tool_config"}),". This provides several key benefits:"]}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.strong,{children:"Automatic Validation:"})," The agent will fail to start if the YAML configuration doesn't match your model, providing clear error messages."]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.strong,{children:"Type Safety:"})," Inside your tool, ",(0,i.jsx)(n.code,{children:"self.tool_config"})," is a fully typed Pydantic object, not a dictionary, enabling autocompletion and preventing common errors."]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.strong,{children:"Self-Documentation:"})," The Pydantic model itself serves as clear, machine-readable documentation for your tool's required configuration."]}),"\n"]}),"\n",(0,i.jsxs)(n.h3,{id:"example-1-using-a-pydantic-model-with-a-single-dynamictool",children:["Example 1: Using a Pydantic Model with a Single ",(0,i.jsx)(n.code,{children:"DynamicTool"})]}),"\n",(0,i.jsxs)(n.p,{children:["This example shows how to add a validated configuration to a standalone ",(0,i.jsx)(n.code,{children:"DynamicTool"})," class."]}),"\n",(0,i.jsx)(n.h4,{id:"step-1-define-the-model-and-tool-class",children:"Step 1: Define the Model and Tool Class"}),"\n",(0,i.jsxs)(n.p,{children:["In your tools file, define a ",(0,i.jsx)(n.code,{children:"pydantic.BaseModel"})," for your configuration. Then, in your ",(0,i.jsx)(n.code,{children:"DynamicTool"})," class, link to it using the ",(0,i.jsx)(n.code,{children:"config_model"})," class attribute."]}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-python",children:'# src/my_agent/weather_tools.py\nfrom typing import Dict, Any\nfrom pydantic import BaseModel, Field\nfrom google.genai import types as adk_types\nfrom solace_agent_mesh.agent.tools.dynamic_tool import DynamicTool\n\n# 1. Define the configuration model\nclass WeatherConfig(BaseModel):\n    api_key: str = Field(..., description="The API key for the weather service.")\n    default_unit: str = Field(default="celsius", description="The default temperature unit.")\n\n# 2. Create a tool and link the config model\nclass GetCurrentWeatherTool(DynamicTool):\n    config_model = WeatherConfig\n\n    def __init__(self, tool_config: WeatherConfig):\n        super().__init__(tool_config)\n        # self.tool_config is now a validated WeatherConfig instance\n        # You can safely access attributes with type safety\n        self.api_key = self.tool_config.api_key\n        self.unit = self.tool_config.default_unit\n\n    @property\n    def tool_name(self) -> str:\n        return "get_current_weather"\n\n    @property\n    def tool_description(self) -> str:\n        return f"Get the current weather. The default unit is {self.unit}."\n\n    @property\n    def parameters_schema(self) -> adk_types.Schema:\n        return adk_types.Schema(\n            type=adk_types.Type.OBJECT,\n            properties={\n                "location": adk_types.Schema(type=adk_types.Type.STRING, description="The city and state/country."),\n            },\n            required=["location"],\n        )\n\n    async def _run_async_impl(self, args: Dict[str, Any], **kwargs) -> Dict[str, Any]:\n        # ... implementation using self.api_key ...\n        return {"weather": f"Sunny in {args[\'location\']}"}\n'})}),"\n",(0,i.jsx)(n.h4,{id:"step-2-configure-the-tool-in-yaml",children:"Step 2: Configure the Tool in YAML"}),"\n",(0,i.jsx)(n.p,{children:"The YAML configuration remains simple. The framework handles the validation against your Pydantic model automatically."}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-yaml",children:'# In your agent\'s app_config:\ntools:\n  - tool_type: python\n    component_module: "my_agent.weather_tools"\n    # The framework will auto-discover the GetCurrentWeatherTool class\n    tool_config:\n      api_key: ${WEATHER_API_KEY}\n      default_unit: "fahrenheit" # Optional, overrides the model\'s default\n'})}),"\n",(0,i.jsxs)(n.p,{children:["If you were to forget ",(0,i.jsx)(n.code,{children:"api_key"})," in the YAML, the agent would fail to start and print a clear error message indicating that the ",(0,i.jsx)(n.code,{children:"api_key"})," field is required, making debugging configuration issues much easier."]}),"\n",(0,i.jsxs)(n.h3,{id:"example-2-using-a-pydantic-model-with-a-dynamictoolprovider",children:["Example 2: Using a Pydantic Model with a ",(0,i.jsx)(n.code,{children:"DynamicToolProvider"})]}),"\n",(0,i.jsx)(n.p,{children:"The same pattern applies to tool providers, allowing you to pass a validated, type-safe configuration object to your tool factory."}),"\n",(0,i.jsx)(n.h4,{id:"step-1-define-the-model-and-provider-class",children:"Step 1: Define the Model and Provider Class"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-python",children:'# src/my_agent/weather_tools_provider.py\nfrom typing import List\nfrom pydantic import BaseModel, Field\nfrom solace_agent_mesh.agent.tools.dynamic_tool import DynamicTool, DynamicToolProvider\n# ... assume GetCurrentWeatherTool is defined in this file or imported ...\n\n# 1. Define the configuration model\nclass WeatherProviderConfig(BaseModel):\n    api_key: str = Field(..., description="The API key for the weather service.")\n    default_unit: str = Field(default="celsius", description="The default temperature unit.")\n\n# 2. Create a provider and link the config model\nclass WeatherToolProvider(DynamicToolProvider):\n    config_model = WeatherProviderConfig\n\n    def create_tools(self, tool_config: WeatherProviderConfig) -> List[DynamicTool]:\n        # The framework passes a validated WeatherProviderConfig instance here\n        return [\n            GetCurrentWeatherTool(tool_config=tool_config)\n            # You could create other tools here that also use the config\n        ]\n'})}),"\n",(0,i.jsx)(n.h4,{id:"step-2-configure-the-provider-in-yaml",children:"Step 2: Configure the Provider in YAML"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-yaml",children:'# In your agent\'s app_config:\ntools:\n  - tool_type: python\n    component_module: "my_agent.weather_tools_provider"\n    # The framework will auto-discover the WeatherToolProvider\n    tool_config:\n      api_key: ${WEATHER_API_KEY}\n      default_unit: "fahrenheit" # Optional, overrides the model\'s default\n'})})]})}function h(e={}){const{wrapper:n}={...(0,s.R)(),...e.components};return n?(0,i.jsx)(n,{...e,children:(0,i.jsx)(d,{...e})}):d(e)}},8453:(e,n,o)=>{o.d(n,{R:()=>a,x:()=>l});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 l(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/81a99df0.2484b8d9.js

@@ -1 +0,0 @@
-"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[1193],{8873:(n,e,i)=>{i.r(e),i.d(e,{assets:()=>r,contentTitle:()=>a,default:()=>h,frontMatter:()=>s,metadata:()=>o,toc:()=>d});const o=JSON.parse('{"id":"documentation/components/builtin-tools/builtin-tools","title":"Configuring Built-in Tools","description":"This guide provides instructions for enabling and configuring the built-in tools provided by Agent Mesh framework.","source":"@site/docs/documentation/components/builtin-tools/builtin-tools.md","sourceDirName":"documentation/components/builtin-tools","slug":"/documentation/components/builtin-tools/","permalink":"/solace-agent-mesh/docs/documentation/components/builtin-tools/","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/components/builtin-tools/builtin-tools.md","tags":[],"version":"current","sidebarPosition":60,"frontMatter":{"title":"Configuring Built-in Tools","sidebar_position":60},"sidebar":"docSidebar","previous":{"title":"Agent Mesh CLI","permalink":"/solace-agent-mesh/docs/documentation/components/cli"},"next":{"title":"Artifact Management Tools","permalink":"/solace-agent-mesh/docs/documentation/components/builtin-tools/artifact-management"}}');var t=i(4848),l=i(8453);const s={title:"Configuring Built-in Tools",sidebar_position:60},a="Configuring Built-in Tools",r={},d=[{value:"Overview",id:"overview",level:2},{value:"Configuration Methods",id:"configuration-methods",level:2},{value:"Method 1: Enabling Tool Groups (Recommended)",id:"method-1-enabling-tool-groups-recommended",level:3},{value:"Method 2: Enabling Individual Tools",id:"method-2-enabling-individual-tools",level:3},{value:"Available Tool Groups and Tools",id:"available-tool-groups-and-tools",level:2},{value:"Artifact Management",id:"artifact-management",level:3},{value:"Data Analysis",id:"data-analysis",level:3},{value:"Web",id:"web",level:3},{value:"Audio",id:"audio",level:3},{value:"Image",id:"image",level:3},{value:"General",id:"general",level:3},{value:"Complete Configuration Example",id:"complete-configuration-example",level:2}];function c(n){const e={a:"a",admonition:"admonition",code:"code",h1:"h1",h2:"h2",h3:"h3",header:"header",li:"li",p:"p",pre:"pre",strong:"strong",ul:"ul",...(0,l.R)(),...n.components};return(0,t.jsxs)(t.Fragment,{children:[(0,t.jsx)(e.header,{children:(0,t.jsx)(e.h1,{id:"configuring-built-in-tools",children:"Configuring Built-in Tools"})}),"\n",(0,t.jsx)(e.p,{children:"This guide provides instructions for enabling and configuring the built-in tools provided by Agent Mesh framework."}),"\n",(0,t.jsx)(e.h2,{id:"overview",children:"Overview"}),"\n",(0,t.jsx)(e.p,{children:"Built-in tools are pre-packaged functionalities that can be granted to agents without requiring custom Python code. These tools address common operations such as file management, data analysis, web requests, and multi-modal generation."}),"\n",(0,t.jsxs)(e.p,{children:["The Agent Mesh framework manages these tools through a central ",(0,t.jsx)(e.code,{children:"tool_registry"}),", which is responsible for loading the tools, generating instructional prompts for the Large Language Model (LLM), and handling their execution in a consistent manner."]}),"\n",(0,t.jsx)(e.h2,{id:"configuration-methods",children:"Configuration Methods"}),"\n",(0,t.jsxs)(e.p,{children:["Tool configuration is managed within the ",(0,t.jsx)(e.code,{children:"tools"})," list in an agent's ",(0,t.jsx)(e.code,{children:"app_config"})," block in the corresponding YAML configuration file."]}),"\n",(0,t.jsx)(e.h3,{id:"method-1-enabling-tool-groups-recommended",children:"Method 1: Enabling Tool Groups (Recommended)"}),"\n",(0,t.jsx)(e.p,{children:"For efficient configuration, built-in tools are organized into logical groups. An entire group of related tools can be enabled with a single entry. This is the recommended approach for standard functionalities."}),"\n",(0,t.jsxs)(e.ul,{children:["\n",(0,t.jsxs)(e.li,{children:[(0,t.jsx)(e.strong,{children:(0,t.jsx)(e.code,{children:"tool_type"})}),": ",(0,t.jsx)(e.code,{children:"builtin-group"})]}),"\n",(0,t.jsxs)(e.li,{children:[(0,t.jsx)(e.strong,{children:(0,t.jsx)(e.code,{children:"group_name"})}),": The unique identifier for the tool category."]}),"\n"]}),"\n",(0,t.jsx)(e.p,{children:(0,t.jsx)(e.strong,{children:"Example:"})}),"\n",(0,t.jsx)(e.pre,{children:(0,t.jsx)(e.code,{className:"language-yaml",children:'# In your agent\'s app_config:\ntools:\n  - tool_type: builtin-group\n    group_name: "artifact_management"\n  - tool_type: builtin-group\n    group_name: "data_analysis"\n'})}),"\n",(0,t.jsx)(e.h3,{id:"method-2-enabling-individual-tools",children:"Method 2: Enabling Individual Tools"}),"\n",(0,t.jsx)(e.p,{children:"For more granular control over an agent's capabilities, specific tools can be enabled individually."}),"\n",(0,t.jsxs)(e.ul,{children:["\n",(0,t.jsxs)(e.li,{children:[(0,t.jsx)(e.strong,{children:(0,t.jsx)(e.code,{children:"tool_type"})}),": ",(0,t.jsx)(e.code,{children:"builtin"})]}),"\n",(0,t.jsxs)(e.li,{children:[(0,t.jsx)(e.strong,{children:(0,t.jsx)(e.code,{children:"tool_name"})}),": The unique, registered name of the tool."]}),"\n"]}),"\n",(0,t.jsx)(e.p,{children:(0,t.jsx)(e.strong,{children:"Example:"})}),"\n",(0,t.jsx)(e.pre,{children:(0,t.jsx)(e.code,{className:"language-yaml",children:'# In your agent\'s app_config:\ntools:\n  - tool_type: builtin\n    tool_name: "web_request"\n  - tool_type: builtin\n    tool_name: "time_delay"\n'})}),"\n",(0,t.jsx)(e.admonition,{title:"Note",type:"info",children:(0,t.jsx)(e.p,{children:"The Agent Mesh framework automatically handles duplicate tool registrations. If a tool group is enabled and a tool from that group is also listed individually, the tool is only loaded once."})}),"\n",(0,t.jsx)(e.h2,{id:"available-tool-groups-and-tools",children:"Available Tool Groups and Tools"}),"\n",(0,t.jsx)(e.p,{children:"The following sections detail the available tool groups and the individual tools they contain."}),"\n",(0,t.jsx)(e.h3,{id:"artifact-management",children:"Artifact Management"}),"\n",(0,t.jsxs)(e.p,{children:[(0,t.jsx)(e.strong,{children:"Group Name"}),": ",(0,t.jsx)(e.code,{children:"artifact_management"})]}),"\n",(0,t.jsxs)(e.p,{children:[(0,t.jsx)(e.strong,{children:"Description"}),": Tools for creating, loading, and managing file artifacts."]}),"\n",(0,t.jsxs)(e.p,{children:[(0,t.jsx)(e.strong,{children:"Individual Tools"}),":"]}),"\n",(0,t.jsxs)(e.ul,{children:["\n",(0,t.jsx)(e.li,{children:(0,t.jsx)(e.code,{children:"append_to_artifact"})}),"\n",(0,t.jsx)(e.li,{children:(0,t.jsx)(e.code,{children:"list_artifacts"})}),"\n",(0,t.jsx)(e.li,{children:(0,t.jsx)(e.code,{children:"load_artifact"})}),"\n",(0,t.jsx)(e.li,{children:(0,t.jsx)(e.code,{children:"apply_embed_and_create_artifact"})}),"\n",(0,t.jsx)(e.li,{children:(0,t.jsx)(e.code,{children:"extract_content_from_artifact"})}),"\n"]}),"\n",(0,t.jsx)(e.admonition,{type:"info",children:(0,t.jsxs)(e.p,{children:["For a more in-depth guide on using artifact management tools, refer to the ",(0,t.jsx)(e.a,{href:"/solace-agent-mesh/docs/documentation/components/builtin-tools/artifact-management",children:"Artifact Management"})," documentation."]})}),"\n",(0,t.jsx)(e.h3,{id:"data-analysis",children:"Data Analysis"}),"\n",(0,t.jsxs)(e.p,{children:[(0,t.jsx)(e.strong,{children:"Group Name"}),": ",(0,t.jsx)(e.code,{children:"data_analysis"})]}),"\n",(0,t.jsxs)(e.p,{children:[(0,t.jsx)(e.strong,{children:"Description"}),": Tools for querying, transforming, and visualizing data."]}),"\n",(0,t.jsxs)(e.p,{children:[(0,t.jsx)(e.strong,{children:"Individual Tools"}),":"]}),"\n",(0,t.jsxs)(e.ul,{children:["\n",(0,t.jsx)(e.li,{children:(0,t.jsx)(e.code,{children:"query_data_with_sql"})}),"\n",(0,t.jsx)(e.li,{children:(0,t.jsx)(e.code,{children:"create_sqlite_db"})}),"\n",(0,t.jsx)(e.li,{children:(0,t.jsx)(e.code,{children:"transform_data_with_jq"})}),"\n",(0,t.jsx)(e.li,{children:(0,t.jsx)(e.code,{children:"create_chart_from_plotly_config"})}),"\n"]}),"\n",(0,t.jsx)(e.admonition,{type:"info",children:(0,t.jsxs)(e.p,{children:["For a more in-depth guide on using Data Analysis tools, refer to the ",(0,t.jsx)(e.a,{href:"/solace-agent-mesh/docs/documentation/components/builtin-tools/data-analysis-tools",children:"Data Analysis Tools"})," documentation."]})}),"\n",(0,t.jsx)(e.h3,{id:"web",children:"Web"}),"\n",(0,t.jsxs)(e.p,{children:[(0,t.jsx)(e.strong,{children:"Group Name"}),": ",(0,t.jsx)(e.code,{children:"web"})]}),"\n",(0,t.jsxs)(e.p,{children:[(0,t.jsx)(e.strong,{children:"Description"}),": Tools for interacting with web resources."]}),"\n",(0,t.jsxs)(e.p,{children:[(0,t.jsx)(e.strong,{children:"Individual Tools"}),":"]}),"\n",(0,t.jsxs)(e.ul,{children:["\n",(0,t.jsx)(e.li,{children:(0,t.jsx)(e.code,{children:"web_request"})}),"\n"]}),"\n",(0,t.jsx)(e.h3,{id:"audio",children:"Audio"}),"\n",(0,t.jsxs)(e.p,{children:[(0,t.jsx)(e.strong,{children:"Group Name"}),": ",(0,t.jsx)(e.code,{children:"audio"})]}),"\n",(0,t.jsxs)(e.p,{children:[(0,t.jsx)(e.strong,{children:"Description"}),": Tools for generating and transcribing audio content."]}),"\n",(0,t.jsxs)(e.p,{children:[(0,t.jsx)(e.strong,{children:"Individual Tools"}),":"]}),"\n",(0,t.jsxs)(e.ul,{children:["\n",(0,t.jsx)(e.li,{children:(0,t.jsx)(e.code,{children:"text_to_speech"})}),"\n",(0,t.jsx)(e.li,{children:(0,t.jsx)(e.code,{children:"multi_speaker_text_to_speech"})}),"\n",(0,t.jsx)(e.li,{children:(0,t.jsx)(e.code,{children:"transcribe_audio"})}),"\n"]}),"\n",(0,t.jsx)(e.h3,{id:"image",children:"Image"}),"\n",(0,t.jsxs)(e.p,{children:[(0,t.jsx)(e.strong,{children:"Group Name"}),": ",(0,t.jsx)(e.code,{children:"image"})]}),"\n",(0,t.jsxs)(e.p,{children:[(0,t.jsx)(e.strong,{children:"Description"}),": Tools for generating and analyzing images."]}),"\n",(0,t.jsxs)(e.p,{children:[(0,t.jsx)(e.strong,{children:"Individual Tools"}),":"]}),"\n",(0,t.jsxs)(e.ul,{children:["\n",(0,t.jsx)(e.li,{children:(0,t.jsx)(e.code,{children:"create_image_from_description"})}),"\n",(0,t.jsx)(e.li,{children:(0,t.jsx)(e.code,{children:"describe_image"})}),"\n",(0,t.jsx)(e.li,{children:(0,t.jsx)(e.code,{children:"edit_image_with_gemini"})}),"\n",(0,t.jsx)(e.li,{children:(0,t.jsx)(e.code,{children:"describe_audio"})}),"\n"]}),"\n",(0,t.jsx)(e.h3,{id:"general",children:"General"}),"\n",(0,t.jsxs)(e.p,{children:[(0,t.jsx)(e.strong,{children:"Group Name"}),": ",(0,t.jsx)(e.code,{children:"general"})]}),"\n",(0,t.jsxs)(e.p,{children:[(0,t.jsx)(e.strong,{children:"Description"}),": General-purpose utility tools."]}),"\n",(0,t.jsxs)(e.p,{children:[(0,t.jsx)(e.strong,{children:"Individual Tools"}),":"]}),"\n",(0,t.jsxs)(e.ul,{children:["\n",(0,t.jsx)(e.li,{children:(0,t.jsx)(e.code,{children:"convert_file_to_markdown"})}),"\n",(0,t.jsx)(e.li,{children:(0,t.jsx)(e.code,{children:"mermaid_diagram_generator"})}),"\n"]}),"\n",(0,t.jsx)(e.h2,{id:"complete-configuration-example",children:"Complete Configuration Example"}),"\n",(0,t.jsxs)(e.p,{children:["Below is a comprehensive example of a well-formed ",(0,t.jsx)(e.code,{children:"app_config"})," that uses the unified method to enable a mix of tool groups and individual tools."]}),"\n",(0,t.jsx)(e.pre,{children:(0,t.jsx)(e.code,{className:"language-yaml",children:'# In your agent\'s YAML file:\napp_config:\n  namespace: "myorg/dev"\n  agent_name: "DataAndWebAgent"\n  model: "gemini-1.5-pro"\n  instruction: "You are an agent that can analyze data and browse the web."\n\n  # --- Unified Tool Configuration ---\n  tools:\n    # Enable a group of tools\n    - tool_type: builtin-group\n      group_name: "data_analysis"\n\n    # Enable another group\n    - tool_type: builtin-group\n      group_name: "artifact_management"\n\n    # Enable a single, specific tool\n    - tool_type: builtin\n      tool_name: "web_request"\n\n    # Enable a custom Python tool\n    - tool_type: python\n      component_module: "my_company.tools.custom_calculators"\n      function_name: "calculate_roi"\n\n  # ... other service configurations (session_service, artifact_service, etc.)\n'})})]})}function h(n={}){const{wrapper:e}={...(0,l.R)(),...n.components};return e?(0,t.jsx)(e,{...n,children:(0,t.jsx)(c,{...n})}):c(n)}},8453:(n,e,i)=>{i.d(e,{R:()=>s,x:()=>a});var o=i(6540);const t={},l=o.createContext(t);function s(n){const e=o.useContext(l);return o.useMemo((function(){return"function"==typeof n?n(e):{...e,...n}}),[e,n])}function a(n){let e;return e=n.disableParentContext?"function"==typeof n.components?n.components(t):n.components||t:s(n.components),o.createElement(l.Provider,{value:e},n.children)}}}]);

solace_agent_mesh/assets/docs/assets/js/9bb13469.b2333011.js

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

solace_agent_mesh/assets/docs/assets/js/ab9708a8.245ae0ef.js

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

solace_agent_mesh/assets/docs/assets/js/db5d6442.3daf1696.js

@@ -1 +0,0 @@
-"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[4262],{1148:(e,n,t)=>{t.r(n),t.d(n,{assets:()=>l,contentTitle:()=>a,default:()=>d,frontMatter:()=>r,metadata:()=>s,toc:()=>c});const s=JSON.parse('{"id":"documentation/deploying/kubernetes-deployment","title":"Kubernetes","description":"You can deploy Agent Mesh to Kubernetes using Helm charts, which handle the complexity of creating and configuring Kubernetes resources such as deployments, services, persistent volumes, and configuration management.","source":"@site/docs/documentation/deploying/kubernetes-deployment.md","sourceDirName":"documentation/deploying","slug":"/documentation/deploying/kubernetes-deployment","permalink":"/solace-agent-mesh/docs/documentation/deploying/kubernetes-deployment","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/deploying/kubernetes-deployment.md","tags":[],"version":"current","sidebarPosition":11,"frontMatter":{"title":"Kubernetes","sidebar_position":11},"sidebar":"docSidebar","previous":{"title":"Choosing Deployment Options","permalink":"/solace-agent-mesh/docs/documentation/deploying/deployment-options"},"next":{"title":"Monitoring Your Agent Mesh","permalink":"/solace-agent-mesh/docs/documentation/deploying/observability"}}');var o=t(4848),i=t(8453);const r={title:"Kubernetes",sidebar_position:11},a="Deploying Agent Mesh to Kubernetes",l={},c=[{value:"Prerequisites",id:"prerequisites",level:2},{value:"Understanding Kubernetes Deployment",id:"understanding-kubernetes-deployment",level:2},{value:"Using the Helm Quickstart",id:"using-the-helm-quickstart",level:2},{value:"Kubernetes Deployment Architecture",id:"kubernetes-deployment-architecture",level:2},{value:"Configuring for Kubernetes",id:"configuring-for-kubernetes",level:2},{value:"Queue Configuration",id:"queue-configuration",level:3},{value:"Secrets Management",id:"secrets-management",level:3},{value:"Storage",id:"storage",level:3},{value:"Resource Limits",id:"resource-limits",level:3}];function u(e){const n={a:"a",code:"code",h1:"h1",h2:"h2",h3:"h3",header:"header",li:"li",p:"p",pre:"pre",ul:"ul",...(0,i.R)(),...e.components};return(0,o.jsxs)(o.Fragment,{children:[(0,o.jsx)(n.header,{children:(0,o.jsx)(n.h1,{id:"deploying-agent-mesh-to-kubernetes",children:"Deploying Agent Mesh to Kubernetes"})}),"\n",(0,o.jsx)(n.p,{children:"You can deploy Agent Mesh to Kubernetes using Helm charts, which handle the complexity of creating and configuring Kubernetes resources such as deployments, services, persistent volumes, and configuration management."}),"\n",(0,o.jsx)(n.h2,{id:"prerequisites",children:"Prerequisites"}),"\n",(0,o.jsx)(n.p,{children:"To deploy Agent Mesh to Kubernetes, you need:"}),"\n",(0,o.jsxs)(n.ul,{children:["\n",(0,o.jsx)(n.li,{children:"A running Kubernetes cluster (version 1.20 or later)"}),"\n",(0,o.jsxs)(n.li,{children:["The ",(0,o.jsx)(n.code,{children:"kubectl"})," command-line tool configured to access your cluster"]}),"\n",(0,o.jsx)(n.li,{children:"Helm installed on your system (version 3.0 or later)"}),"\n",(0,o.jsx)(n.li,{children:"Container registry credentials (if you use private registries)"}),"\n",(0,o.jsx)(n.li,{children:"Solace broker credentials or Solace Cloud connection details"}),"\n"]}),"\n",(0,o.jsx)(n.h2,{id:"understanding-kubernetes-deployment",children:"Understanding Kubernetes Deployment"}),"\n",(0,o.jsx)(n.p,{children:"The deployment process involves adding the Helm chart repository, customizing values for your environment, and deploying Agent Mesh to your cluster. The Helm charts simplify this process compared to manually managing individual YAML manifests."}),"\n",(0,o.jsx)(n.h2,{id:"using-the-helm-quickstart",children:"Using the Helm Quickstart"}),"\n",(0,o.jsx)(n.p,{children:"The Solace Agent Mesh Helm quickstart includes pre-configured Helm values, deployment examples, and detailed documentation for common deployment scenarios."}),"\n",(0,o.jsxs)(n.p,{children:["For the quickstart repository and installation files, see ",(0,o.jsx)(n.a,{href:"https://github.com/SolaceProducts/solace-agent-mesh-helm-quickstart",children:"solace-agent-mesh-helm-quickstart"}),"."]}),"\n",(0,o.jsxs)(n.p,{children:["For step-by-step deployment instructions, see the ",(0,o.jsx)(n.a,{href:"https://solaceproducts.github.io/solace-agent-mesh-helm-quickstart/docs-site/",children:"Helm Deployment Guide"}),"."]}),"\n",(0,o.jsx)(n.h2,{id:"kubernetes-deployment-architecture",children:"Kubernetes Deployment Architecture"}),"\n",(0,o.jsx)(n.p,{children:"You can deploy Agent Mesh as a single monolithic deployment or as multiple specialized deployments that scale independently. The Helm charts support both patterns based on your scale requirements and operational preferences."}),"\n",(0,o.jsx)(n.p,{children:"When you deploy multiple components as separate deployments, each component runs independently and communicates through the Solace event broker. This approach provides better fault isolation and allows you to scale specific components based on demand. All components must connect to the same Solace broker and use consistent storage configurations to maintain system coherence."}),"\n",(0,o.jsx)(n.h2,{id:"configuring-for-kubernetes",children:"Configuring for Kubernetes"}),"\n",(0,o.jsx)(n.p,{children:"Several configuration considerations apply specifically to Kubernetes deployments."}),"\n",(0,o.jsx)(n.h3,{id:"queue-configuration",children:"Queue Configuration"}),"\n",(0,o.jsx)(n.p,{children:"For Kubernetes environments with container restarts, you should configure Agent Mesh to use durable queues instead of temporary queues. Set the environment variable:"}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-bash",children:"USE_TEMPORARY_QUEUES=false\n"})}),"\n",(0,o.jsxs)(n.p,{children:["This configuration ensures that messages persist even when pods restart and allows multiple instances to connect to the same queue. For detailed queue configuration guidance, including Queue Template setup in Solace Cloud, see ",(0,o.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/deploying/deployment-options#setting-up-queue-templates",children:"Choosing Deployment Options"}),"."]}),"\n",(0,o.jsx)(n.h3,{id:"secrets-management",children:"Secrets Management"}),"\n",(0,o.jsx)(n.p,{children:"You should use Kubernetes Secrets to store sensitive information such as API keys, broker credentials, and authentication tokens. Never embed these values in container images or configuration files."}),"\n",(0,o.jsx)(n.h3,{id:"storage",children:"Storage"}),"\n",(0,o.jsx)(n.p,{children:"If you run multiple pod replicas, ensure all instances access the same persistent storage with identical configurations. Inconsistent storage across instances can cause data synchronization issues."}),"\n",(0,o.jsx)(n.h3,{id:"resource-limits",children:"Resource Limits"}),"\n",(0,o.jsx)(n.p,{children:"You should define resource requests and limits for your containers to ensure stable operation and enable effective autoscaling. The Helm quickstart includes recommended resource configurations."})]})}function d(e={}){const{wrapper:n}={...(0,i.R)(),...e.components};return n?(0,o.jsx)(n,{...e,children:(0,o.jsx)(u,{...e})}):u(e)}},8453:(e,n,t)=>{t.d(n,{R:()=>r,x:()=>a});var s=t(6540);const o={},i=s.createContext(o);function r(e){const n=s.useContext(i);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(o):e.components||o:r(e.components),s.createElement(i.Provider,{value:n},e.children)}}}]);

solace_agent_mesh/assets/docs/assets/js/e04b235d.52cb25ed.js

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

solace_agent_mesh/assets/docs/assets/js/e1b6eeb4.b1068f9b.js

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