solace-agent-mesh 1.3.1__py3-none-any.whl → 1.3.3__py3-none-any.whl

solace_agent_mesh/assets/docs/assets/js/75384d09.abdf9cf9.js

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

solace_agent_mesh/assets/docs/assets/js/768e31b0.9abcdc48.js

@@ -0,0 +1 @@
+"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[1095],{6871:(e,n,i)=>{i.r(n),i.d(n,{assets:()=>a,contentTitle:()=>r,default:()=>h,frontMatter:()=>s,metadata:()=>o,toc:()=>d});const o=JSON.parse('{"id":"documentation/user-guide/builtin-tools/builtin-tools","title":"Configuring Built-in Tools","description":"This guide provides instructions for enabling and configuring the built-in tools provided by Solace Agent Mesh framework.","source":"@site/docs/documentation/user-guide/builtin-tools/builtin-tools.md","sourceDirName":"documentation/user-guide/builtin-tools","slug":"/documentation/user-guide/builtin-tools/","permalink":"/solace-agent-mesh/docs/documentation/user-guide/builtin-tools/","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/user-guide/builtin-tools/builtin-tools.md","tags":[],"version":"current","sidebarPosition":60,"frontMatter":{"title":"Configuring Built-in Tools","sidebar_position":60},"sidebar":"docSidebar","previous":{"title":"Creating Service Providers","permalink":"/solace-agent-mesh/docs/documentation/user-guide/creating-service-providers"},"next":{"title":"Artifact Management Tools","permalink":"/solace-agent-mesh/docs/documentation/user-guide/builtin-tools/artifact-management"}}');var l=i(4848),t=i(8453);const s={title:"Configuring Built-in Tools",sidebar_position:60},r="Configuring Built-in Tools",a={},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(e){const n={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,t.R)(),...e.components};return(0,l.jsxs)(l.Fragment,{children:[(0,l.jsx)(n.header,{children:(0,l.jsx)(n.h1,{id:"configuring-built-in-tools",children:"Configuring Built-in Tools"})}),"\n",(0,l.jsx)(n.p,{children:"This guide provides instructions for enabling and configuring the built-in tools provided by Solace Agent Mesh framework."}),"\n",(0,l.jsx)(n.h2,{id:"overview",children:"Overview"}),"\n",(0,l.jsx)(n.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,l.jsxs)(n.p,{children:["The Solace Agent Mesh framework manages these tools through a central ",(0,l.jsx)(n.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,l.jsx)(n.h2,{id:"configuration-methods",children:"Configuration Methods"}),"\n",(0,l.jsxs)(n.p,{children:["Tool configuration is managed within the ",(0,l.jsx)(n.code,{children:"tools"})," list in an agent's ",(0,l.jsx)(n.code,{children:"app_config"})," block in the corresponding YAML configuration file."]}),"\n",(0,l.jsx)(n.h3,{id:"method-1-enabling-tool-groups-recommended",children:"Method 1: Enabling Tool Groups (Recommended)"}),"\n",(0,l.jsx)(n.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,l.jsxs)(n.ul,{children:["\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.strong,{children:(0,l.jsx)(n.code,{children:"tool_type"})}),": ",(0,l.jsx)(n.code,{children:"builtin-group"})]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.strong,{children:(0,l.jsx)(n.code,{children:"group_name"})}),": The unique identifier for the tool category."]}),"\n"]}),"\n",(0,l.jsx)(n.p,{children:(0,l.jsx)(n.strong,{children:"Example:"})}),"\n",(0,l.jsx)(n.pre,{children:(0,l.jsx)(n.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,l.jsx)(n.h3,{id:"method-2-enabling-individual-tools",children:"Method 2: Enabling Individual Tools"}),"\n",(0,l.jsx)(n.p,{children:"For more granular control over an agent's capabilities, specific tools can be enabled individually."}),"\n",(0,l.jsxs)(n.ul,{children:["\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.strong,{children:(0,l.jsx)(n.code,{children:"tool_type"})}),": ",(0,l.jsx)(n.code,{children:"builtin"})]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.strong,{children:(0,l.jsx)(n.code,{children:"tool_name"})}),": The unique, registered name of the tool."]}),"\n"]}),"\n",(0,l.jsx)(n.p,{children:(0,l.jsx)(n.strong,{children:"Example:"})}),"\n",(0,l.jsx)(n.pre,{children:(0,l.jsx)(n.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,l.jsx)(n.admonition,{title:"Note",type:"info",children:(0,l.jsx)(n.p,{children:"The Solace 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,l.jsx)(n.h2,{id:"available-tool-groups-and-tools",children:"Available Tool Groups and Tools"}),"\n",(0,l.jsx)(n.p,{children:"The following sections detail the available tool groups and the individual tools they contain."}),"\n",(0,l.jsx)(n.h3,{id:"artifact-management",children:"Artifact Management"}),"\n",(0,l.jsxs)(n.p,{children:[(0,l.jsx)(n.strong,{children:"Group Name"}),": ",(0,l.jsx)(n.code,{children:"artifact_management"})]}),"\n",(0,l.jsxs)(n.p,{children:[(0,l.jsx)(n.strong,{children:"Description"}),": Tools for creating, loading, and managing file artifacts."]}),"\n",(0,l.jsxs)(n.p,{children:[(0,l.jsx)(n.strong,{children:"Individual Tools"}),":"]}),"\n",(0,l.jsxs)(n.ul,{children:["\n",(0,l.jsx)(n.li,{children:(0,l.jsx)(n.code,{children:"create_artifact"})}),"\n",(0,l.jsx)(n.li,{children:(0,l.jsx)(n.code,{children:"append_to_artifact"})}),"\n",(0,l.jsx)(n.li,{children:(0,l.jsx)(n.code,{children:"list_artifacts"})}),"\n",(0,l.jsx)(n.li,{children:(0,l.jsx)(n.code,{children:"load_artifact"})}),"\n",(0,l.jsx)(n.li,{children:(0,l.jsx)(n.code,{children:"signal_artifact_for_return"})}),"\n",(0,l.jsx)(n.li,{children:(0,l.jsx)(n.code,{children:"apply_embed_and_create_artifact"})}),"\n",(0,l.jsx)(n.li,{children:(0,l.jsx)(n.code,{children:"extract_content_from_artifact"})}),"\n"]}),"\n",(0,l.jsx)(n.admonition,{type:"info",children:(0,l.jsxs)(n.p,{children:["For a more in-depth guide on using artifact management tools, refer to the ",(0,l.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/user-guide/builtin-tools/artifact-management",children:"Artifact Management"})," documentation."]})}),"\n",(0,l.jsx)(n.h3,{id:"data-analysis",children:"Data Analysis"}),"\n",(0,l.jsxs)(n.p,{children:[(0,l.jsx)(n.strong,{children:"Group Name"}),": ",(0,l.jsx)(n.code,{children:"data_analysis"})]}),"\n",(0,l.jsxs)(n.p,{children:[(0,l.jsx)(n.strong,{children:"Description"}),": Tools for querying, transforming, and visualizing data."]}),"\n",(0,l.jsxs)(n.p,{children:[(0,l.jsx)(n.strong,{children:"Individual Tools"}),":"]}),"\n",(0,l.jsxs)(n.ul,{children:["\n",(0,l.jsx)(n.li,{children:(0,l.jsx)(n.code,{children:"query_data_with_sql"})}),"\n",(0,l.jsx)(n.li,{children:(0,l.jsx)(n.code,{children:"create_sqlite_db"})}),"\n",(0,l.jsx)(n.li,{children:(0,l.jsx)(n.code,{children:"transform_data_with_jq"})}),"\n",(0,l.jsx)(n.li,{children:(0,l.jsx)(n.code,{children:"create_chart_from_plotly_config"})}),"\n"]}),"\n",(0,l.jsx)(n.admonition,{type:"info",children:(0,l.jsxs)(n.p,{children:["For a more in-depth guide on using Data Analysis tools, refer to the ",(0,l.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/user-guide/builtin-tools/data-analysis-tools",children:"Data Analysis Tools"})," documentation."]})}),"\n",(0,l.jsx)(n.h3,{id:"web",children:"Web"}),"\n",(0,l.jsxs)(n.p,{children:[(0,l.jsx)(n.strong,{children:"Group Name"}),": ",(0,l.jsx)(n.code,{children:"web"})]}),"\n",(0,l.jsxs)(n.p,{children:[(0,l.jsx)(n.strong,{children:"Description"}),": Tools for interacting with web resources."]}),"\n",(0,l.jsxs)(n.p,{children:[(0,l.jsx)(n.strong,{children:"Individual Tools"}),":"]}),"\n",(0,l.jsxs)(n.ul,{children:["\n",(0,l.jsx)(n.li,{children:(0,l.jsx)(n.code,{children:"web_request"})}),"\n"]}),"\n",(0,l.jsx)(n.h3,{id:"audio",children:"Audio"}),"\n",(0,l.jsxs)(n.p,{children:[(0,l.jsx)(n.strong,{children:"Group Name"}),": ",(0,l.jsx)(n.code,{children:"audio"})]}),"\n",(0,l.jsxs)(n.p,{children:[(0,l.jsx)(n.strong,{children:"Description"}),": Tools for generating and transcribing audio content."]}),"\n",(0,l.jsxs)(n.p,{children:[(0,l.jsx)(n.strong,{children:"Individual Tools"}),":"]}),"\n",(0,l.jsxs)(n.ul,{children:["\n",(0,l.jsx)(n.li,{children:(0,l.jsx)(n.code,{children:"text_to_speech"})}),"\n",(0,l.jsx)(n.li,{children:(0,l.jsx)(n.code,{children:"multi_speaker_text_to_speech"})}),"\n",(0,l.jsx)(n.li,{children:(0,l.jsx)(n.code,{children:"transcribe_audio"})}),"\n"]}),"\n",(0,l.jsx)(n.h3,{id:"image",children:"Image"}),"\n",(0,l.jsxs)(n.p,{children:[(0,l.jsx)(n.strong,{children:"Group Name"}),": ",(0,l.jsx)(n.code,{children:"image"})]}),"\n",(0,l.jsxs)(n.p,{children:[(0,l.jsx)(n.strong,{children:"Description"}),": Tools for generating and analyzing images."]}),"\n",(0,l.jsxs)(n.p,{children:[(0,l.jsx)(n.strong,{children:"Individual Tools"}),":"]}),"\n",(0,l.jsxs)(n.ul,{children:["\n",(0,l.jsx)(n.li,{children:(0,l.jsx)(n.code,{children:"create_image_from_description"})}),"\n",(0,l.jsx)(n.li,{children:(0,l.jsx)(n.code,{children:"describe_image"})}),"\n",(0,l.jsx)(n.li,{children:(0,l.jsx)(n.code,{children:"edit_image_with_gemini"})}),"\n",(0,l.jsx)(n.li,{children:(0,l.jsx)(n.code,{children:"describe_audio"})}),"\n"]}),"\n",(0,l.jsx)(n.h3,{id:"general",children:"General"}),"\n",(0,l.jsxs)(n.p,{children:[(0,l.jsx)(n.strong,{children:"Group Name"}),": ",(0,l.jsx)(n.code,{children:"general"})]}),"\n",(0,l.jsxs)(n.p,{children:[(0,l.jsx)(n.strong,{children:"Description"}),": General-purpose utility tools."]}),"\n",(0,l.jsxs)(n.p,{children:[(0,l.jsx)(n.strong,{children:"Individual Tools"}),":"]}),"\n",(0,l.jsxs)(n.ul,{children:["\n",(0,l.jsx)(n.li,{children:(0,l.jsx)(n.code,{children:"convert_file_to_markdown"})}),"\n",(0,l.jsx)(n.li,{children:(0,l.jsx)(n.code,{children:"mermaid_diagram_generator"})}),"\n"]}),"\n",(0,l.jsx)(n.h2,{id:"complete-configuration-example",children:"Complete Configuration Example"}),"\n",(0,l.jsxs)(n.p,{children:["Below is a comprehensive example of a well-formed ",(0,l.jsx)(n.code,{children:"app_config"})," that uses the unified method to enable a mix of tool groups and individual tools."]}),"\n",(0,l.jsx)(n.pre,{children:(0,l.jsx)(n.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(e={}){const{wrapper:n}={...(0,t.R)(),...e.components};return n?(0,l.jsx)(n,{...e,children:(0,l.jsx)(c,{...e})}):c(e)}},8453:(e,n,i)=>{i.d(n,{R:()=>s,x:()=>r});var o=i(6540);const l={},t=o.createContext(l);function s(e){const n=o.useContext(t);return o.useMemo((function(){return"function"==typeof e?e(n):{...n,...e}}),[n,e])}function r(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(l):e.components||l:s(e.components),o.createElement(t.Provider,{value:n},e.children)}}}]);

solace_agent_mesh/assets/docs/assets/js/945fb41e.abf2be91.js

@@ -0,0 +1 @@
+"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[1721],{3878:(e,n,t)=>{t.r(n),t.d(n,{assets:()=>l,contentTitle:()=>o,default:()=>h,frontMatter:()=>a,metadata:()=>s,toc:()=>c});const s=JSON.parse('{"id":"documentation/getting-started/introduction","title":"Introduction","description":"Solace Agent Mesh","source":"@site/docs/documentation/getting-started/introduction.md","sourceDirName":"documentation/getting-started","slug":"/documentation/getting-started/introduction","permalink":"/solace-agent-mesh/docs/documentation/getting-started/introduction","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/getting-started/introduction.md","tags":[],"version":"current","sidebarPosition":10,"frontMatter":{"title":"Introduction","sidebar_position":10},"sidebar":"docSidebar","next":{"title":"Installation","permalink":"/solace-agent-mesh/docs/documentation/getting-started/installation"}}');var i=t(4848),r=t(8453);const a={title:"Introduction",sidebar_position:10},o=void 0,l={},c=[{value:"Solace Agent Mesh",id:"solace-agent-mesh",level:2},{value:"What Problems Does the Mesh Solve?",id:"what-problems-does-the-mesh-solve",level:3},{value:"Why Choose Solace Agent Mesh?",id:"why-choose-solace-agent-mesh",level:3},{value:"Real-World Applications",id:"real-world-applications",level:2},{value:"Evolution Through Usage",id:"evolution-through-usage",level:3},{value:"For Developers",id:"for-developers",level:2},{value:"Getting Started",id:"getting-started",level:2}];function d(e){const n={a:"a",br:"br",h2:"h2",h3:"h3",img:"img",li:"li",p:"p",strong:"strong",ul:"ul",...(0,r.R)(),...e.components};return(0,i.jsxs)(i.Fragment,{children:[(0,i.jsx)(n.h2,{id:"solace-agent-mesh",children:"Solace Agent Mesh"}),"\n",(0,i.jsx)(n.p,{children:"Modern AI development faces a fundamental challenge: while powerful AI models are readily available, the real complexity lies in connecting them to the data and systems where they can provide value. Data exists in isolated silos - spread across databases, SaaS platforms, APIs, and legacy systems - making it difficult to build AI applications that can work across these boundaries."}),"\n",(0,i.jsx)(n.p,{children:'Solace Agent Mesh is an open-source framework that tackles this challenge head-on by integrating the Google Agent Development Kit (ADK) with the Solace AI Connector (SAC) to provide a "Universal A2A Agent Host" that enables scalable, distributed AI agent communication through Solace PubSub+. Whether you\'re an AI enthusiast experimenting with new models, or an enterprise developer building production systems, Solace Agent Mesh gives you the tools to:'}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsx)(n.li,{children:"connect AI agents to real-world data sources and systems through a standardized A2A (Agent-to-Agent) protocol"}),"\n",(0,i.jsx)(n.li,{children:"add gateways to provide event-based integrations or interactive UI connections"}),"\n",(0,i.jsx)(n.li,{children:"monitor and debug AI interactions in real-time through comprehensive observability"}),"\n",(0,i.jsx)(n.li,{children:"deploy solutions that scale from prototype to production with enterprise-grade reliability"}),"\n"]}),"\n",(0,i.jsx)(n.p,{children:"Rather than trying to be a monolithic AI platform, Solace Agent Mesh focuses on being an excellent integration layer built on proven event-driven architecture. It brings together specialized agents - whether they're using local databases, accessing cloud APIs, or interfacing with enterprise systems - and helps them collaborate through standardized A2A communication to solve complex problems."}),"\n",(0,i.jsx)(n.p,{children:"Built on event-driven architecture technology from Solace with Google ADK integration, Solace Agent Mesh provides the robust foundation needed for both experimental and production deployments."}),"\n",(0,i.jsx)(n.p,{children:(0,i.jsx)(n.img,{alt:"Solace Agent Mesh Overview",src:t(1351).A+"",width:"2558",height:"1788"})}),"\n",(0,i.jsx)(n.h3,{id:"what-problems-does-the-mesh-solve",children:"What Problems Does the Mesh Solve?"}),"\n",(0,i.jsx)(n.p,{children:"Solace Agent Mesh tackles the hardest challenges in building collaborative AI systems: agent coordination, system integration, and extensibility at scale. This section reveals the key problems it solves and shows how organizations are using it today."}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.strong,{children:"Event-Driven Architecture at the Core:"}),(0,i.jsx)(n.br,{}),"\n","The beating heart of Solace Agent Mesh is its event mesh\u2014a neural network for your AI components. This architecture creates a fluid, asynchronous communication layer where messages flow naturally between agents, gateways, and external systems. By decoupling senders from receivers, the mesh dramatically simplifies agent interactions, ensures message delivery even during component failures, and lets you add, remove, or restart components on the fly without disrupting workflows."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.strong,{children:"Breaking Down AI Silos:"}),(0,i.jsx)(n.br,{}),"\n","Specialized agents operate independently yet collaborate effortlessly\u2014like expert teammates rather than isolated tools."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.strong,{children:"Orchestrating Complex Workflows:"}),(0,i.jsx)(n.br,{}),"\n","Create sophisticated multi-agent processes where tasks flow naturally between specialists, executing in sequence or parallel based on dynamic needs."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.strong,{children:"Speaking a Common Language:"}),(0,i.jsx)(n.br,{}),"\n","The A2A protocol creates a universal communication standard, ensuring all agents and gateways understand each other regardless of their internal implementation."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.strong,{children:"Unifying AI Capabilities:"}),(0,i.jsx)(n.br,{}),"\n","Blend diverse AI models, custom tools (Python functions, MCP tools), and enterprise data sources into a cohesive ecosystem."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.strong,{children:"Connecting to Your World:"}),(0,i.jsx)(n.br,{}),"\n","Purpose-built gateways bridge the gap between the agent mesh and your existing systems\u2014web interfaces, Slack workspaces, APIs, and event streams."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.strong,{children:"Handling the Unpredictable:"}),(0,i.jsx)(n.br,{}),"\n","The event-driven backbone gracefully manages long-running tasks and asynchronous patterns that are inherent in AI agent interactions."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.strong,{children:"Adding Agents to Increase Capabilities"}),":\nEach new agent adds more capabilities to the system. Adding a new agent is not additive\u2014it is exponential. With each agent being able to enhance all other agents as they collaborate for more and more complex tasks."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.strong,{children:"Adding Gateways to Increase the Supported Use Cases"}),":\nEach new gateway opens up new use cases for the system. A new gateway can provide a new interface to the system, with a different system purpose and response rules."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.strong,{children:"Enterprise-Ready"}),":\nEngineered from the ground up for production deployment, this solution leverages expertise from Solace in building mission-critical distributed systems."]}),"\n"]}),"\n"]}),"\n",(0,i.jsx)(n.h3,{id:"why-choose-solace-agent-mesh",children:"Why Choose Solace Agent Mesh?"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.strong,{children:"Enterprise-Grade Performance:"}),(0,i.jsx)(n.br,{}),"\n","Built on Solace PubSub+ Event Broker, the mesh delivers high-throughput, fault-tolerant messaging that scales with your needs."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.strong,{children:"Plug-and-Play Extensibility:"}),(0,i.jsx)(n.br,{}),"\n","The event-driven architecture makes adding new capabilities remarkably simple. Deploy a new agent, and it instantly publishes its capabilities to the mesh. Other components discover it automatically\u2014no manual configuration, no downtime, no integration headaches."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.strong,{children:"Modular by Design:"}),(0,i.jsx)(n.br,{}),"\n","Every component\u2014agents, gateways, tools\u2014is a self-contained module you can reuse, replace, or enhance independently."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.strong,{children:"Configuration-Driven:"}),(0,i.jsx)(n.br,{}),"\n","YAML-based configuration gives you precise control over agent behavior, service integrations, and security settings without code changes."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.strong,{children:"Security-First Approach:"}),(0,i.jsx)(n.br,{}),"\n","The built-in authorization framework provides fine-grained access control over agents and tools based on user roles and scopes."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.strong,{children:"Resilient by Nature:"}),(0,i.jsx)(n.br,{}),"\n","Event-driven design creates responsive, self-healing interactions that recover gracefully from disruptions."]}),"\n"]}),"\n"]}),"\n",(0,i.jsx)(n.h2,{id:"real-world-applications",children:"Real-World Applications"}),"\n",(0,i.jsx)(n.p,{children:"Organizations are using Solace Agent Mesh in diverse scenarios:"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:(0,i.jsx)(n.strong,{children:"Intelligent Enterprise Automation:"})}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsx)(n.li,{children:"Customer service systems that route inquiries to specialized agents based on intent and context."}),"\n",(0,i.jsx)(n.li,{children:"Data processing pipelines where specialized agents transform, analyze, and enrich information from multiple sources."}),"\n"]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:(0,i.jsx)(n.strong,{children:"AI Task Specialization:"})}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsx)(n.li,{children:"Image analysis workflows where one agent processes visual data and delegates text generation to a language specialist."}),"\n",(0,i.jsx)(n.li,{children:"Document processing systems that extract text, summarize content, and translate results\u2014each step handled by the perfect specialist."}),"\n"]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.strong,{children:"Human-AI Collaboration:"}),(0,i.jsx)(n.br,{}),"\n","Agents that perform complex tasks while keeping humans in the loop for approvals, clarifications, or expert guidance via web or chat interfaces."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.strong,{children:"Multi-Agent Research:"}),(0,i.jsx)(n.br,{}),"\n","A production-ready platform for exploring agent collaboration patterns, delegation strategies, and distributed AI problem-solving."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.strong,{children:"Data-Driven Intelligence:"}),(0,i.jsx)(n.br,{}),"\n","Agents that query databases, transform results, and generate visualizations based on natural language requests or system events."]}),"\n"]}),"\n"]}),"\n",(0,i.jsx)(n.h3,{id:"evolution-through-usage",children:"Evolution Through Usage"}),"\n",(0,i.jsx)(n.p,{children:"Solace Agent Mesh grows with your needs. For example, at Solace we started with basic agents and have continuously expanded the system's capabilities:"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsx)(n.li,{children:"Added specialized agents for JIRA and Confluence integration"}),"\n",(0,i.jsx)(n.li,{children:"Implemented multiple interface options including browser-based user interfaces and REST API gateways"}),"\n",(0,i.jsx)(n.li,{children:"Integrated with various AI models and data sources"}),"\n"]}),"\n",(0,i.jsx)(n.h2,{id:"for-developers",children:"For Developers"}),"\n",(0,i.jsx)(n.p,{children:"Solace Agent Mesh is an agentic framework that provides several key technical advantages:"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.strong,{children:"Complete Observability"}),": Because all communication flows through the event broker, you can monitor and debug the entire system in real-time"]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.strong,{children:"Flexible Integration"}),": Built-in support for common enterprise systems and AI frameworks"]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.strong,{children:"Plugin Architecture"}),": Easily extend the system with custom agents and gateways"]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.strong,{children:"Developer Tools"}),": Comprehensive CLI and debugging utilities"]}),"\n"]}),"\n",(0,i.jsx)(n.h2,{id:"getting-started",children:"Getting Started"}),"\n",(0,i.jsx)(n.p,{children:"Whether you're building a proof-of-concept or planning a production deployment, Solace Agent Mesh provides the foundation you need. For more information, see:"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/getting-started/installation",children:"Installation"}),": For installing and setting up Solace Agent Mesh."]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/getting-started/quick-start",children:"Quick Start"}),": For creating a project, build, and run Solace Agent Mesh."]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/getting-started/component-overview",children:"Components Overview"}),": Understand the parts of Solace Agent Mesh."]}),"\n"]})]})}function h(e={}){const{wrapper:n}={...(0,r.R)(),...e.components};return n?(0,i.jsx)(n,{...e,children:(0,i.jsx)(d,{...e})}):d(e)}},1351:(e,n,t)=>{t.d(n,{A:()=>s});const s=t.p+"assets/images/Solace_AI_Framework_With_Broker-85f0a306a9bcdd20b390b7a949f6d862.png"},8453:(e,n,t)=>{t.d(n,{R:()=>a,x:()=>o});var s=t(6540);const i={},r=s.createContext(i);function a(e){const n=s.useContext(r);return s.useMemo((function(){return"function"==typeof e?e(n):{...n,...e}}),[n,e])}function o(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(i):e.components||i:a(e.components),s.createElement(r.Provider,{value:n},e.children)}}}]);

solace_agent_mesh/assets/docs/assets/js/9a09e75d.5a319fd4.js

@@ -0,0 +1 @@
+"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[6719],{1786:(e,n,t)=>{t.r(n),t.d(n,{assets:()=>l,contentTitle:()=>a,default:()=>h,frontMatter:()=>i,metadata:()=>o,toc:()=>c});const o=JSON.parse('{"id":"documentation/user-guide/creating-python-tools","title":"Creating Python Tools","description":"Solace 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/user-guide/creating-python-tools.md","sourceDirName":"documentation/user-guide","slug":"/documentation/user-guide/creating-python-tools","permalink":"/solace-agent-mesh/docs/documentation/user-guide/creating-python-tools","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/user-guide/creating-python-tools.md","tags":[],"version":"current","sidebarPosition":35,"frontMatter":{"title":"Creating Python Tools","sidebar_position":35},"sidebar":"docSidebar","previous":{"title":"Create Agents","permalink":"/solace-agent-mesh/docs/documentation/user-guide/create-agents"},"next":{"title":"Create Gateways","permalink":"/solace-agent-mesh/docs/documentation/user-guide/create-gateways"}}');var s=t(4848),r=t(8453);const i={title:"Creating Python Tools",sidebar_position:35},a="Creating Python Tools",l={},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}];function d(e){const n={code:"code",h1:"h1",h2:"h2",h3:"h3",header:"header",hr:"hr",li:"li",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,s.jsxs)(s.Fragment,{children:[(0,s.jsx)(n.header,{children:(0,s.jsx)(n.h1,{id:"creating-python-tools",children:"Creating Python Tools"})}),"\n",(0,s.jsx)(n.p,{children:"Solace 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,s.jsxs)(n.p,{children:["This guide covers the different patterns for creating custom tools, all of which are configured using the versatile ",(0,s.jsx)(n.code,{children:"tool_type: python"}),"."]}),"\n",(0,s.jsx)(n.h2,{id:"tool-creation-patterns",children:"Tool Creation Patterns"}),"\n",(0,s.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,s.jsxs)(n.table,{children:[(0,s.jsx)(n.thead,{children:(0,s.jsxs)(n.tr,{children:[(0,s.jsx)(n.th,{children:"Pattern"}),(0,s.jsx)(n.th,{children:"Best For"}),(0,s.jsx)(n.th,{children:"Key Feature"})]})}),(0,s.jsxs)(n.tbody,{children:[(0,s.jsxs)(n.tr,{children:[(0,s.jsx)(n.td,{children:(0,s.jsx)(n.strong,{children:"Function-Based"})}),(0,s.jsx)(n.td,{children:"Simple, self-contained tools with static inputs."}),(0,s.jsx)(n.td,{children:"Quick and easy; uses function signature."})]}),(0,s.jsxs)(n.tr,{children:[(0,s.jsx)(n.td,{children:(0,s.jsxs)(n.strong,{children:["Single ",(0,s.jsx)(n.code,{children:"DynamicTool"})," Class"]})}),(0,s.jsx)(n.td,{children:"Tools that require complex logic or a programmatically defined interface."}),(0,s.jsx)(n.td,{children:"Full control over the tool's definition."})]}),(0,s.jsxs)(n.tr,{children:[(0,s.jsx)(n.td,{children:(0,s.jsxs)(n.strong,{children:[(0,s.jsx)(n.code,{children:"DynamicToolProvider"})," Class"]})}),(0,s.jsx)(n.td,{children:"Generating multiple related tools from a single, configurable source."}),(0,s.jsx)(n.td,{children:"Maximum scalability and code reuse."})]})]})]}),"\n",(0,s.jsxs)(n.p,{children:["All three patterns are configured in your agent's YAML file under the ",(0,s.jsx)(n.code,{children:"tools"})," list with ",(0,s.jsx)(n.code,{children:"tool_type: python"}),"."]}),"\n",(0,s.jsx)(n.hr,{}),"\n",(0,s.jsx)(n.h2,{id:"pattern-1-simple-function-based-tools",children:"Pattern 1: Simple Function-Based Tools"}),"\n",(0,s.jsxs)(n.p,{children:["This is the most straightforward way to create a custom tool. You define a standard Python ",(0,s.jsx)(n.code,{children:"async"})," function, and Solace Agent Mesh automatically introspects its signature and docstring to create the tool definition for the LLM."]}),"\n",(0,s.jsx)(n.h3,{id:"step-1-write-the-tool-function",children:"Step 1: Write the Tool Function"}),"\n",(0,s.jsxs)(n.p,{children:["Create a Python file (e.g., ",(0,s.jsx)(n.code,{children:"src/my_agent/tools.py"}),") and define your tool."]}),"\n",(0,s.jsx)(n.pre,{children:(0,s.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 Solace Agent Mesh!"\n\n    return {\n        "status": "success",\n        "message": greeting_message\n    }\n'})}),"\n",(0,s.jsx)(n.p,{children:(0,s.jsx)(n.strong,{children:"Key Requirements:"})}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:["The function must be ",(0,s.jsx)(n.code,{children:"async def"}),"."]}),"\n",(0,s.jsxs)(n.li,{children:["The function's docstring is used as the tool's ",(0,s.jsx)(n.code,{children:"description"})," for the LLM."]}),"\n",(0,s.jsxs)(n.li,{children:["Type hints (",(0,s.jsx)(n.code,{children:"str"}),", ",(0,s.jsx)(n.code,{children:"int"}),", ",(0,s.jsx)(n.code,{children:"bool"}),") are used to generate the parameter schema."]}),"\n",(0,s.jsxs)(n.li,{children:["The function should accept ",(0,s.jsx)(n.code,{children:"tool_context"})," and ",(0,s.jsx)(n.code,{children:"tool_config"})," as optional keyword arguments to receive framework context and YAML configuration."]}),"\n"]}),"\n",(0,s.jsx)(n.h3,{id:"step-2-configure-the-tool",children:"Step 2: Configure the Tool"}),"\n",(0,s.jsxs)(n.p,{children:["In your agent's YAML configuration, add a ",(0,s.jsx)(n.code,{children:"tool_type: python"})," block and point it to your function."]}),"\n",(0,s.jsx)(n.pre,{children:(0,s.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,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.code,{children:"component_module"}),": The Python module path to your tools file."]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.code,{children:"function_name"}),": The exact name of the function to load."]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.code,{children:"tool_config"}),": An optional dictionary passed to your tool at runtime."]}),"\n"]}),"\n",(0,s.jsx)(n.hr,{}),"\n",(0,s.jsx)(n.h2,{id:"pattern-2-advanced-single-class-tools",children:"Pattern 2: Advanced Single-Class Tools"}),"\n",(0,s.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,s.jsx)(n.code,{children:"DynamicTool"}),"."]}),"\n",(0,s.jsxs)(n.h3,{id:"step-1-create-the-dynamictool-class",children:["Step 1: Create the ",(0,s.jsx)(n.code,{children:"DynamicTool"})," Class"]}),"\n",(0,s.jsxs)(n.p,{children:["Instead of a function, define a class that implements the ",(0,s.jsx)(n.code,{children:"DynamicTool"})," abstract base class."]}),"\n",(0,s.jsx)(n.pre,{children:(0,s.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,s.jsx)(n.h3,{id:"step-2-configure-the-tool-1",children:"Step 2: Configure the Tool"}),"\n",(0,s.jsxs)(n.p,{children:["The YAML configuration is very similar. You can either specify the ",(0,s.jsx)(n.code,{children:"class_name"})," or let Solace Agent Mesh auto-discover it if it's the only ",(0,s.jsx)(n.code,{children:"DynamicTool"})," in the module."]}),"\n",(0,s.jsx)(n.pre,{children:(0,s.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,s.jsx)(n.hr,{}),"\n",(0,s.jsx)(n.h2,{id:"pattern-3-the-tool-provider-factory",children:"Pattern 3: The Tool Provider Factory"}),"\n",(0,s.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,s.jsx)(n.h3,{id:"step-1-create-the-provider-and-tools",children:"Step 1: Create the Provider and Tools"}),"\n",(0,s.jsxs)(n.p,{children:["In your tools module, you define your ",(0,s.jsx)(n.code,{children:"DynamicTool"})," classes as before, but you also create a ",(0,s.jsx)(n.strong,{children:"provider"})," class that inherits from ",(0,s.jsx)(n.code,{children:"DynamicToolProvider"}),". This provider acts as a factory."]}),"\n",(0,s.jsxs)(n.p,{children:["You can also use the ",(0,s.jsx)(n.code,{children:"@register_tool"})," decorator on simple functions to have them automatically included by the provider."]}),"\n",(0,s.jsx)(n.pre,{children:(0,s.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,s.jsx)(n.h3,{id:"step-2-configure-the-provider",children:"Step 2: Configure the Provider"}),"\n",(0,s.jsxs)(n.p,{children:["You only need a single YAML block. Solace Agent Mesh will automatically detect the ",(0,s.jsx)(n.code,{children:"DynamicToolProvider"})," and use it to load all the tools it generates."]}),"\n",(0,s.jsx)(n.pre,{children:(0,s.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,s.jsx)(n.p,{children:"This approach is incredibly scalable, as one configuration entry can bootstrap an entire suite of dynamically generated tools."})]})}function h(e={}){const{wrapper:n}={...(0,r.R)(),...e.components};return n?(0,s.jsx)(n,{...e,children:(0,s.jsx)(d,{...e})}):d(e)}},8453:(e,n,t)=>{t.d(n,{R:()=>i,x:()=>a});var o=t(6540);const s={},r=o.createContext(s);function i(e){const n=o.useContext(r);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:i(e.components),o.createElement(r.Provider,{value:n},e.children)}}}]);

solace_agent_mesh/assets/docs/assets/js/9eff14a2.d62aad71.js

@@ -0,0 +1 @@
+"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[9639],{2888:(e,n,t)=>{t.r(n),t.d(n,{assets:()=>r,contentTitle:()=>l,default:()=>h,frontMatter:()=>o,metadata:()=>a,toc:()=>c});const a=JSON.parse('{"id":"documentation/tutorials/slack-integration","title":"Slack Integration","description":"This tutorial integrates a Slack interface into Solace Agent Mesh, enabling interaction with the system directly from your Slack workspace and channels.","source":"@site/docs/documentation/tutorials/slack-integration.md","sourceDirName":"documentation/tutorials","slug":"/documentation/tutorials/slack-integration","permalink":"/solace-agent-mesh/docs/documentation/tutorials/slack-integration","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/tutorials/slack-integration.md","tags":[],"version":"current","sidebarPosition":60,"frontMatter":{"title":"Slack Integration","sidebar_position":60},"sidebar":"docSidebar","previous":{"title":"MongoDB Integration","permalink":"/solace-agent-mesh/docs/documentation/tutorials/mongodb-integration"},"next":{"title":"RAG Integration","permalink":"/solace-agent-mesh/docs/documentation/tutorials/rag-integration"}}');var s=t(4848),i=t(8453);const o={title:"Slack Integration",sidebar_position:60},l="Slack Integration",r={},c=[{value:"Setting Up the Environment",id:"setting-up-the-environment",level:2},{value:"Creating the Slack App",id:"creating-the-slack-app",level:2},{value:"App-Level Tokens",id:"app-level-tokens",level:3},{value:"Installing the App in Your Slack Workspace",id:"installing-the-app-in-your-slack-workspace",level:3},{value:"Installing the Slack Gateway",id:"installing-the-slack-gateway",level:2},{value:"Running the Slack Gateway",id:"running-the-slack-gateway",level:2},{value:"Testing the Installation",id:"testing-the-installation",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:"slack-integration",children:"Slack Integration"})}),"\n",(0,s.jsx)(n.p,{children:"This tutorial integrates a Slack interface into Solace Agent Mesh, enabling interaction with the system directly from your Slack workspace and channels."}),"\n",(0,s.jsx)(n.admonition,{title:"Learn about gateways",type:"info",children:(0,s.jsxs)(n.p,{children:["Read about ",(0,s.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/concepts/gateways",children:"Gateways"})," before you start this tutorial."]})}),"\n",(0,s.jsx)(n.h2,{id:"setting-up-the-environment",children:"Setting Up the Environment"}),"\n",(0,s.jsxs)(n.p,{children:["First, you need to ",(0,s.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/getting-started/installation",children:"install Solace Agent Mesh and Solace Mesh Agent CLI"}),", and then ",(0,s.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/getting-started/quick-start",children:"create a new Solace Agent Mesh project"})," or ",(0,s.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/concepts/plugins#create-a-plugin",children:"create a new gateway plugin"}),"."]}),"\n",(0,s.jsx)(n.h2,{id:"creating-the-slack-app",children:"Creating the Slack App"}),"\n",(0,s.jsxs)(n.p,{children:["Next, create a ",(0,s.jsx)(n.a,{href:"https://api.slack.com/apps",children:"Slack Application"})," in your workspace."]}),"\n",(0,s.jsxs)(n.ol,{children:["\n",(0,s.jsxs)(n.li,{children:["Go to the ",(0,s.jsx)(n.a,{href:"https://api.slack.com/apps",children:"Slack Application"})," website."]}),"\n",(0,s.jsxs)(n.li,{children:["Select ",(0,s.jsx)(n.strong,{children:"Your Apps"})," and click ",(0,s.jsx)(n.strong,{children:"Create New App"}),"."]}),"\n",(0,s.jsxs)(n.li,{children:["Choose ",(0,s.jsx)(n.strong,{children:"From a manifest"})," and apply the following configuration.","\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsx)(n.li,{children:"You can customize the name and description, but keep the rest of the configuration and settings unchanged."}),"\n"]}),"\n"]}),"\n"]}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-yaml",children:"display_information:\n  name: solace-agent-mesh-bot\n  description: An app to integrate with Solace Agent Mesh\nfeatures:\n  app_home:\n    home_tab_enabled: false\n    messages_tab_enabled: true\n    messages_tab_read_only_enabled: false\n  bot_user:\n    display_name: Solace Agent Mesh\n    always_online: false\noauth_config:\n  scopes:\n    bot:\n      - app_mentions:read\n      - bookmarks:read\n      - channels:history\n      - channels:join\n      - channels:manage\n      - channels:read\n      - chat:write\n      - chat:write.customize\n      - chat:write.public\n      - files:read\n      - files:write\n      - groups:history\n      - groups:read\n      - groups:write\n      - im:history\n      - im:read\n      - im:write\n      - links:read\n      - links:write\n      - mpim:history\n      - mpim:read\n      - mpim:write\n      - pins:read\n      - pins:write\n      - reactions:read\n      - reactions:write\n      - reminders:read\n      - reminders:write\n      - team:read\n      - usergroups:read\n      - usergroups:write\n      - users.profile:read\n      - users:read.email\n      - users:read\n      - users:write\n      - conversations.connect:read\n      - conversations.connect:write\n      - incoming-webhook\nsettings:\n  event_subscriptions:\n    bot_events:\n      - app_mention\n      - message.groups\n      - message.im\n  interactivity:\n    is_enabled: true\n  org_deploy_enabled: false\n  socket_mode_enabled: true\n  token_rotation_enabled: false\n"})}),"\n",(0,s.jsxs)(n.p,{children:["Then select ",(0,s.jsx)(n.code,{children:"Create"})," to create your new App."]}),"\n",(0,s.jsx)(n.h3,{id:"app-level-tokens",children:"App-Level Tokens"}),"\n",(0,s.jsxs)(n.p,{children:["In your created App, select ",(0,s.jsx)(n.code,{children:"Basic Information"})," under ",(0,s.jsx)(n.code,{children:"Settings"}),". Scroll down to ",(0,s.jsx)(n.code,{children:"App-Level Tokens"})," and click ",(0,s.jsx)(n.code,{children:"Generate Token and Scopes"}),"."]}),"\n",(0,s.jsxs)(n.p,{children:["Provide your token a name, add all available scopes, and then click ",(0,s.jsx)(n.code,{children:"Generate"}),"."]}),"\n",(0,s.jsxs)(n.p,{children:["Make note of the resulting application token (beginning with ",(0,s.jsx)(n.code,{children:"xapp-"}),") - you need it in a future step."]}),"\n",(0,s.jsx)(n.h3,{id:"installing-the-app-in-your-slack-workspace",children:"Installing the App in Your Slack Workspace"}),"\n",(0,s.jsxs)(n.p,{children:["Next, select ",(0,s.jsx)(n.strong,{children:"Install App"})," under ",(0,s.jsx)(n.strong,{children:"Settings"})," and follow the installation flow to install the App in your workspace."]}),"\n",(0,s.jsxs)(n.p,{children:["After installation, the bot token (beginning with ",(0,s.jsx)(n.code,{children:"xoxb-"}),") is visible. Make note of this token."]}),"\n",(0,s.jsx)(n.h2,{id:"installing-the-slack-gateway",children:"Installing the Slack Gateway"}),"\n",(0,s.jsx)(n.p,{children:"After configuring your Slack App, the next step is to add the Slack gateway to Solace Agent Mesh."}),"\n",(0,s.jsxs)(n.ol,{children:["\n",(0,s.jsxs)(n.li,{children:["\n",(0,s.jsx)(n.p,{children:"Add the gateway plugin using Solace Agent Mesh CLI:"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-sh",children:"sam plugin add slack-bot --plugin sam-slack\n"})}),"\n",(0,s.jsxs)(n.p,{children:["You can change ",(0,s.jsx)(n.code,{children:"slack-bot"})," to any name you prefer for your gateway."]}),"\n"]}),"\n",(0,s.jsxs)(n.li,{children:["\n",(0,s.jsx)(n.p,{children:"Configure the required environment variables:"}),"\n",(0,s.jsxs)(n.p,{children:["The Slack interface requires two authentication tokens. Add these to your ",(0,s.jsx)(n.code,{children:".env"})," file in the project root directory using the tokens generated during Slack App setup:"]}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-env",children:"SLACK_BOT_TOKEN=xoxb-xxxxxxxxxx\nSLACK_APP_TOKEN=xapp-xxxxxxxxxx\n"})}),"\n"]}),"\n"]}),"\n",(0,s.jsx)(n.admonition,{type:"tip",children:(0,s.jsxs)(n.p,{children:["You can further customize the Slack gateway by updating the ",(0,s.jsx)(n.code,{children:"configs/gateways/slack-bot.yaml"})," file. This file contains the configuration for the Slack gateway, including the initial status message, the gateway system purpose, and response format."]})}),"\n",(0,s.jsx)(n.h2,{id:"running-the-slack-gateway",children:"Running the Slack Gateway"}),"\n",(0,s.jsx)(n.p,{children:"Launch the Slack gateway with:"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-sh",children:"sam run configs/gateways/slack-bot.yaml\n"})}),"\n",(0,s.jsxs)(n.p,{children:["For detailed information about available Solace Agent Mesh CLI commands, see ",(0,s.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/concepts/cli",children:"the Solace Agent Mesh CLI"}),"."]}),"\n",(0,s.jsx)(n.h2,{id:"testing-the-installation",children:"Testing the Installation"}),"\n",(0,s.jsx)(n.p,{children:"To test your installation:"}),"\n",(0,s.jsxs)(n.ol,{children:["\n",(0,s.jsx)(n.li,{children:"Open your Slack workspace in the desktop app or browser."}),"\n",(0,s.jsxs)(n.li,{children:["Find and click on the ",(0,s.jsx)(n.strong,{children:"Solace Agent Mesh"})," app under the ",(0,s.jsx)(n.strong,{children:"Apps"})," section."]}),"\n",(0,s.jsxs)(n.li,{children:["Send a test message by typing ",(0,s.jsx)(n.code,{children:"hello"})," and click ",(0,s.jsx)(n.strong,{children:"Enter"}),"."]}),"\n",(0,s.jsxs)(n.li,{children:["You should see:","\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsx)(n.li,{children:'A "Chatbot is thinking..." status message'}),"\n",(0,s.jsx)(n.li,{children:"A response from the chatbot within a few seconds"}),"\n"]}),"\n"]}),"\n"]})]})}function h(e={}){const{wrapper:n}={...(0,i.R)(),...e.components};return n?(0,s.jsx)(n,{...e,children:(0,s.jsx)(d,{...e})}):d(e)}},8453:(e,n,t)=>{t.d(n,{R:()=>o,x:()=>l});var a=t(6540);const s={},i=a.createContext(s);function o(e){const n=a.useContext(i);return a.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(s):e.components||s:o(e.components),a.createElement(i.Provider,{value:n},e.children)}}}]);

solace_agent_mesh/assets/docs/assets/js/a3a92b25.1d029b81.js

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

solace_agent_mesh/assets/docs/assets/js/{aba87c2f.071e2d94.js → aba87c2f.4ddf32f2.js}

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

solace_agent_mesh/assets/docs/assets/js/ae0e903d.abca774a.js

@@ -0,0 +1 @@
+"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[3486],{3782:(e,n,t)=>{t.r(n),t.d(n,{assets:()=>c,contentTitle:()=>r,default:()=>E,frontMatter:()=>i,metadata:()=>s,toc:()=>l});const s=JSON.parse('{"id":"documentation/Enterprise/installation","title":"Installation","description":"Prepare the Enterprise Image","source":"@site/docs/documentation/Enterprise/installation.md","sourceDirName":"documentation/Enterprise","slug":"/documentation/Enterprise/installation","permalink":"/solace-agent-mesh/docs/documentation/Enterprise/installation","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/Enterprise/installation.md","tags":[],"version":"current","sidebarPosition":5,"frontMatter":{"title":"Installation","sidebar_position":5},"sidebar":"docSidebar","previous":{"title":"A2A Technical Migration Map","permalink":"/solace-agent-mesh/docs/documentation/Migrations/A2A Upgrade To 0.3.0/a2a-technical-migration-map"},"next":{"title":"SSO","permalink":"/solace-agent-mesh/docs/documentation/Enterprise/single-sign-on"}}');var a=t(4848),o=t(8453);const i={title:"Installation",sidebar_position:5},r=void 0,c={},l=[{value:"Prepare the Enterprise Image",id:"prepare-the-enterprise-image",level:2},{value:"Running Solace Agent Mesh Enterprise",id:"running-solace-agent-mesh-enterprise",level:2},{value:"Development Use Case",id:"development-use-case",level:3},{value:"Production Use Case",id:"production-use-case",level:3}];function d(e){const n={a:"a",admonition:"admonition",code:"code",h2:"h2",h3:"h3",p:"p",pre:"pre",...(0,o.R)(),...e.components};return(0,a.jsxs)(a.Fragment,{children:[(0,a.jsx)(n.h2,{id:"prepare-the-enterprise-image",children:"Prepare the Enterprise Image"}),"\n",(0,a.jsxs)(n.p,{children:["Download the latest enterprise docker image tarball from the ",(0,a.jsx)(n.a,{href:"https://products.solace.com/",children:"Solace Product Portal"}),"."]}),"\n",(0,a.jsx)(n.p,{children:"Load the image using Docker with the following command."}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-bash",children:"docker load -i solace-agent-mesh-enterprise-<tag>.tar\n"})}),"\n",(0,a.jsx)(n.p,{children:"Once loaded, you can verify the image locally using the following command:"}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-bash",children:"docker images\n"})}),"\n",(0,a.jsx)(n.h2,{id:"running-solace-agent-mesh-enterprise",children:"Running Solace Agent Mesh Enterprise"}),"\n",(0,a.jsx)(n.p,{children:"Here are two examples of Docker run commands for both a development use case as well as a production use case:"}),"\n",(0,a.jsx)(n.admonition,{type:"tip",children:(0,a.jsxs)(n.p,{children:["You may need to include ",(0,a.jsx)(n.code,{children:"--platform linux/amd64"})," depending on the host machine you\u2019re using."]})}),"\n",(0,a.jsx)(n.h3,{id:"development-use-case",children:"Development Use Case"}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-bash",children:'docker run -itd -p 8000:8000 \\\n  -e LLM_SERVICE_API_KEY="<YOUR_LLM_TOKEN>" \\\n  -e LLM_SERVICE_ENDPOINT="<YOUR_LLM_SERVICE_ENDPOINT>" \\\n  -e LLM_SERVICE_PLANNING_MODEL_NAME="<YOUR_MODEL_NAME>" \\\n  -e LLM_SERVICE_GENERAL_MODEL_NAME="<YOUR_MODEL_NAME>" \\\n  -e NAMESPACE="<YOUR_NAMESPACE>" \\\n  -e SOLACE_DEV_MODE="true" \\\n  --name sam-ent-dev \\\nsolace-agent-mesh-enterprise:<tag>\n'})}),"\n",(0,a.jsx)(n.h3,{id:"production-use-case",children:"Production Use Case"}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-bash",children:'docker run -itd -p 8000:8000 \\\n  -e LLM_SERVICE_API_KEY="<YOUR_LLM_TOKEN>" \\\n  -e LLM_SERVICE_ENDPOINT="<YOUR_LLM_SERVICE_ENDPOINT>" \\\n  -e LLM_SERVICE_PLANNING_MODEL_NAME="<YOUR_MODEL_NAME>" \\\n  -e LLM_SERVICE_GENERAL_MODEL_NAME="<YOUR_MODEL_NAME>" \\\n  -e NAMESPACE="<YOUR_NAMESPACE>" \\\n  -e SOLACE_DEV_MODE="false" \\\n  -e SOLACE_BROKER_URL="<YOUR_BROKER_URL>" \\\n  -e SOLACE_BROKER_VPN="<YOUR_BROKER_VPN>" \\\n  -e SOLACE_BROKER_USERNAME="<YOUR_BROKER_USERNAME>" \\\n  -e SOLACE_BROKER_PASSWORD="<YOUR_BROKER_PASSWORD>" \\\n  --name sam-ent-prod \\\nsolace-agent-mesh-enterprise:<tag>\n'})}),"\n",(0,a.jsxs)(n.p,{children:["You can then access Solace Agent Mesh Enterprise UI through ",(0,a.jsx)(n.a,{href:"http://localhost:8000",children:"http://localhost:8000"})]})]})}function E(e={}){const{wrapper:n}={...(0,o.R)(),...e.components};return n?(0,a.jsx)(n,{...e,children:(0,a.jsx)(d,{...e})}):d(e)}},8453:(e,n,t)=>{t.d(n,{R:()=>i,x:()=>r});var s=t(6540);const a={},o=s.createContext(a);function i(e){const n=s.useContext(o);return s.useMemo((function(){return"function"==typeof e?e(n):{...n,...e}}),[n,e])}function r(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(a):e.components||a:i(e.components),s.createElement(o.Provider,{value:n},e.children)}}}]);

solace_agent_mesh/assets/docs/assets/js/ae4415af.24cdc514.js

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

solace_agent_mesh/assets/docs/assets/js/bac0be12.27ee2c26.js

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

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

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