solace-agent-mesh 1.6.1__py3-none-any.whl → 1.13.2__py3-none-any.whl

solace_agent_mesh/assets/docs/assets/js/6aaedf65.7253541d.js

@@ -0,0 +1 @@
+"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[4795],{289:(e,n,t)=>{t.r(n),t.d(n,{assets:()=>c,contentTitle:()=>a,default:()=>l,frontMatter:()=>o,metadata:()=>s,toc:()=>h});const s=JSON.parse('{"id":"documentation/components/speech","title":"Speech Integration","description":"Agent Mesh provides speech capabilities through integrated Speech-to-Text (STT) and Text-to-Speech (TTS) services. You can enable users to interact with agents through voice input and receive spoken responses, creating more natural and accessible conversational experiences.","source":"@site/docs/documentation/components/speech.md","sourceDirName":"documentation/components","slug":"/documentation/components/speech","permalink":"/solace-agent-mesh/docs/documentation/components/speech","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/components/speech.md","tags":[],"version":"current","frontMatter":{},"sidebar":"docSidebar","previous":{"title":"Prompt Library","permalink":"/solace-agent-mesh/docs/documentation/components/prompts"},"next":{"title":"Installing and Configuring Agent Mesh","permalink":"/solace-agent-mesh/docs/documentation/installing-and-configuring/"}}');var i=t(4848),r=t(8453);const o={},a="Speech Integration",c={},h=[{value:"Understanding Speech Integration",id:"understanding-speech-integration",level:2},{value:"Configuring Speech Services",id:"configuring-speech-services",level:2},{value:"Speech-to-Text Configuration",id:"speech-to-text-configuration",level:3},{value:"Text-to-Speech Configuration",id:"text-to-speech-configuration",level:3},{value:"Enabling Speech Features",id:"enabling-speech-features",level:2},{value:"Managing User Settings",id:"managing-user-settings",level:2},{value:"Monitoring Speech Usage",id:"monitoring-speech-usage",level:2},{value:"Troubleshooting Speech Issues",id:"troubleshooting-speech-issues",level:2},{value:"Security Considerations",id:"security-considerations",level:2},{value:"Integration Examples",id:"integration-examples",level:2}];function p(e){const n={code:"code",h1:"h1",h2:"h2",h3:"h3",header:"header",p:"p",pre:"pre",...(0,r.R)(),...e.components};return(0,i.jsxs)(i.Fragment,{children:[(0,i.jsx)(n.header,{children:(0,i.jsx)(n.h1,{id:"speech-integration",children:"Speech Integration"})}),"\n",(0,i.jsx)(n.p,{children:"Agent Mesh provides speech capabilities through integrated Speech-to-Text (STT) and Text-to-Speech (TTS) services. You can enable users to interact with agents through voice input and receive spoken responses, creating more natural and accessible conversational experiences."}),"\n",(0,i.jsx)(n.h2,{id:"understanding-speech-integration",children:"Understanding Speech Integration"}),"\n",(0,i.jsx)(n.p,{children:"The speech system consists of two complementary services that work together to enable voice interactions. The STT service converts spoken audio into text that agents can process, while the TTS service transforms agent responses into natural-sounding speech. Both services support multiple providers and can be configured independently based on your requirements."}),"\n",(0,i.jsx)(n.p,{children:"The system integrates with the WebUI gateway to provide seamless voice interactions in chat interfaces. When you enable speech features, users see microphone and speaker controls that allow them to speak their questions and hear agent responses without typing."}),"\n",(0,i.jsx)(n.h2,{id:"configuring-speech-services",children:"Configuring Speech Services"}),"\n",(0,i.jsxs)(n.p,{children:["You configure speech services in your gateway YAML file under the ",(0,i.jsx)(n.code,{children:"app_config.speech"})," section. The configuration defines which providers to use, authentication credentials, and service-specific settings that control behavior and quality."]}),"\n",(0,i.jsx)(n.h3,{id:"speech-to-text-configuration",children:"Speech-to-Text Configuration"}),"\n",(0,i.jsx)(n.p,{children:"The STT service transcribes audio input into text using either OpenAI's Whisper API or Azure Speech Services. You specify the provider and its credentials in your configuration:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-yaml",children:'app_config:\n  speech:\n    stt:\n      provider: openai  # or "azure"\n      openai:\n        api_key: ${OPENAI_API_KEY}\n        url: https://api.openai.com/v1/audio/transcriptions\n        model: whisper-1\n'})}),"\n",(0,i.jsx)(n.p,{children:"When using Azure Speech Services, you provide your subscription key and region:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-yaml",children:"app_config:\n  speech:\n    stt:\n      provider: azure\n      azure:\n        api_key: ${AZURE_SPEECH_KEY}\n        region: eastus\n        language: en-US\n"})}),"\n",(0,i.jsx)(n.p,{children:"The system validates audio files before transcription, rejecting files larger than 25MB or with unsupported formats. Supported formats include WAV, MP3, WebM, and OGG."}),"\n",(0,i.jsx)(n.h3,{id:"text-to-speech-configuration",children:"Text-to-Speech Configuration"}),"\n",(0,i.jsx)(n.p,{children:"The TTS service generates natural-sounding speech from text using either Google's Gemini or Azure Neural Voices. You configure the provider, voice selection, and quality settings:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-yaml",children:'app_config:\n  speech:\n    tts:\n      provider: gemini  # or "azure"\n      gemini:\n        api_key: ${GEMINI_API_KEY}\n        model: gemini-2.5-flash-preview-tts\n        default_voice: Kore\n        voices:\n          - Kore\n          - Puck\n          - Charon\n          - Kore\n          - Fenrir\n          - Aoede\n'})}),"\n",(0,i.jsx)(n.p,{children:"Azure Neural Voices offer high-definition voices with natural prosody:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-yaml",children:"app_config:\n  speech:\n    tts:\n      provider: azure\n      azure:\n        api_key: ${AZURE_SPEECH_KEY}\n        region: eastus\n        default_voice: en-US-Ava:DragonHDLatestNeural\n        voices:\n          - en-US-Ava:DragonHDLatestNeural\n          - en-US-Andrew:DragonHDLatestNeural\n          - en-US-Emma:DragonHDLatestNeural\n          - en-US-Brian:DragonHDLatestNeural\n"})}),"\n",(0,i.jsx)(n.p,{children:"The system automatically chunks long text into manageable segments for streaming playback, reducing latency and improving the user experience."}),"\n",(0,i.jsx)(n.h2,{id:"enabling-speech-features",children:"Enabling Speech Features"}),"\n",(0,i.jsxs)(n.p,{children:["Speech features are disabled by default and require explicit configuration to appear in the user interface. You control feature visibility through the ",(0,i.jsx)(n.code,{children:"frontend_feature_enablement"})," section:"]}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-yaml",children:"app_config:\n  frontend_feature_enablement:\n    speechToText: true\n    textToSpeech: true\n"})}),"\n",(0,i.jsx)(n.p,{children:"When you enable these flags, the WebUI displays microphone and speaker controls in the chat interface. Users can click the microphone to record voice input or the speaker icon to hear agent responses."}),"\n",(0,i.jsx)(n.h2,{id:"managing-user-settings",children:"Managing User Settings"}),"\n",(0,i.jsx)(n.p,{children:"Users can customize their speech experience through the settings panel. The system provides controls for voice selection, playback speed, and automatic playback behavior. You can set default values that users can override:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-yaml",children:"app_config:\n  speech:\n    speechTab:\n      speechToText:\n        speechToText: true\n        engineSTT: external\n        languageSTT: en-US\n      textToSpeech:\n        textToSpeech: true\n        engineTTS: external\n        voice: Kore\n        playbackRate: 1.0\n"})}),"\n",(0,i.jsx)(n.h2,{id:"monitoring-speech-usage",children:"Monitoring Speech Usage"}),"\n",(0,i.jsx)(n.p,{children:"Speech services consume API credits based on audio duration and text length. OpenAI charges per minute of audio transcribed, while Gemini and Azure charge per character of text synthesized. You should monitor usage through your provider's dashboard and set appropriate rate limits to control costs."}),"\n",(0,i.jsx)(n.p,{children:"The system logs all speech operations, including transcription requests, TTS generation, and any errors encountered. You can use these logs to track usage patterns, identify issues, and optimize your configuration for better performance and cost efficiency."}),"\n",(0,i.jsx)(n.h2,{id:"troubleshooting-speech-issues",children:"Troubleshooting Speech Issues"}),"\n",(0,i.jsx)(n.p,{children:"When speech features do not appear in the interface, verify that you have enabled the feature flags in your configuration and that the gateway has restarted to load the new settings. Check the browser console for any JavaScript errors that might prevent the speech controls from rendering."}),"\n",(0,i.jsx)(n.p,{children:"If transcription fails, confirm that your API keys are valid and that you have sufficient credits with your provider. The system returns specific error messages for common issues like unsupported audio formats, files that are too large, or API authentication failures."}),"\n",(0,i.jsx)(n.p,{children:"For TTS problems, verify that your selected voice is available for your provider and region. Some voices require specific API versions or subscription tiers. The system falls back to default voices when requested voices are unavailable, but you should configure appropriate defaults to ensure consistent behavior."}),"\n",(0,i.jsx)(n.h2,{id:"security-considerations",children:"Security Considerations"}),"\n",(0,i.jsx)(n.p,{children:"Audio data passes through your gateway to external speech providers. The system does not store audio recordings by default, but transcribed text becomes part of the conversation history. You should inform users about data handling practices and comply with relevant privacy regulations when processing voice data."}),"\n",(0,i.jsx)(n.h2,{id:"integration-examples",children:"Integration Examples"}),"\n",(0,i.jsxs)(n.p,{children:["For a complete working example, see the WebUI gateway configuration in ",(0,i.jsx)(n.code,{children:"templates/webui.yaml"}),". This configuration demonstrates all speech settings with appropriate defaults and shows how to structure your YAML for production use."]})]})}function l(e={}){const{wrapper:n}={...(0,r.R)(),...e.components};return n?(0,i.jsx)(n,{...e,children:(0,i.jsx)(p,{...e})}):p(e)}},8453:(e,n,t)=>{t.d(n,{R:()=>o,x:()=>a});var s=t(6540);const i={},r=s.createContext(i);function o(e){const n=s.useContext(r);return s.useMemo((function(){return"function"==typeof e?e(n):{...n,...e}}),[n,e])}function a(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(i):e.components||i:o(e.components),s.createElement(r.Provider,{value:n},e.children)}}}]);

solace_agent_mesh/assets/docs/assets/js/6ad8f0bd.a5b36a60.js

@@ -0,0 +1 @@
+"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[6084],{4795:(e,n,t)=>{t.r(n),t.d(n,{assets:()=>c,contentTitle:()=>s,default:()=>h,frontMatter:()=>i,metadata:()=>a,toc:()=>l});const a=JSON.parse('{"id":"documentation/developing/tutorials/custom-agent","title":"Build Your Own Agent","description":"This tutorial shows you how to build a sophisticated weather agent using the Agent Mesh framework. Learn how to integrate with external APIs, manage resources properly, and create production-ready agents.","source":"@site/docs/documentation/developing/tutorials/custom-agent.md","sourceDirName":"documentation/developing/tutorials","slug":"/documentation/developing/tutorials/custom-agent","permalink":"/solace-agent-mesh/docs/documentation/developing/tutorials/custom-agent","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/developing/tutorials/custom-agent.md","tags":[],"version":"current","sidebarPosition":5,"frontMatter":{"title":"Build Your Own Agent","sidebar_position":5},"sidebar":"docSidebar","previous":{"title":"Evaluating Agents","permalink":"/solace-agent-mesh/docs/documentation/developing/evaluations"},"next":{"title":"MCP Integration","permalink":"/solace-agent-mesh/docs/documentation/developing/tutorials/mcp-integration"}}');var r=t(4848),o=t(8453);const i={title:"Build Your Own Agent",sidebar_position:5},s="Build Your Own Agent",c={},l=[{value:"Overview",id:"overview",level:2},{value:"Prerequisites",id:"prerequisites",level:2},{value:"Planning the Weather Agent",id:"planning-the-weather-agent",level:2},{value:"Step 1: Project Structure",id:"step-1-project-structure",level:2},{value:"Step 2: Weather Service Implementation",id:"step-2-weather-service-implementation",level:2},{value:"Step 3: Weather Tools Implementation",id:"step-3-weather-tools-implementation",level:2},{value:"Step 4: Lifecycle Functions",id:"step-4-lifecycle-functions",level:2},{value:"Step 5: Agent Configuration",id:"step-5-agent-configuration",level:2},{value:"Step 6: Environment Setup",id:"step-6-environment-setup",level:2},{value:"Step 7: Running the Agent",id:"step-7-running-the-agent",level:2},{value:"Step 8: Testing the Weather Agent",id:"step-8-testing-the-weather-agent",level:2},{value:"Key Features Demonstrated",id:"key-features-demonstrated",level:2},{value:"1. External API Integration",id:"1-external-api-integration",level:3},{value:"2. Resource Management",id:"2-resource-management",level:3},{value:"3. Configuration Management",id:"3-configuration-management",level:3},{value:"4. Error Handling",id:"4-error-handling",level:3},{value:"5. Artifact Management",id:"5-artifact-management",level:3}];function d(e){const n={a:"a",admonition:"admonition",blockquote:"blockquote",code:"code",h1:"h1",h2:"h2",h3:"h3",header:"header",li:"li",ol:"ol",p:"p",pre:"pre",strong:"strong",ul:"ul",...(0,o.R)(),...e.components},{Details:t}=n;return t||function(e,n){throw new Error("Expected "+(n?"component":"object")+" `"+e+"` to be defined: you likely forgot to import, pass, or provide it.")}("Details",!0),(0,r.jsxs)(r.Fragment,{children:[(0,r.jsx)(n.header,{children:(0,r.jsx)(n.h1,{id:"build-your-own-agent",children:"Build Your Own Agent"})}),"\n",(0,r.jsx)(n.p,{children:"This tutorial shows you how to build a sophisticated weather agent using the Agent Mesh framework. Learn how to integrate with external APIs, manage resources properly, and create production-ready agents."}),"\n",(0,r.jsx)(n.h2,{id:"overview",children:"Overview"}),"\n",(0,r.jsx)(n.p,{children:"Our weather agent will demonstrate:"}),"\n",(0,r.jsxs)(n.ul,{children:["\n",(0,r.jsx)(n.li,{children:"External API integration (OpenWeatherMap)"}),"\n",(0,r.jsx)(n.li,{children:"Professional service layer architecture"}),"\n",(0,r.jsx)(n.li,{children:"Multiple sophisticated tools"}),"\n",(0,r.jsx)(n.li,{children:"Proper lifecycle management"}),"\n",(0,r.jsx)(n.li,{children:"Error handling and validation"}),"\n",(0,r.jsx)(n.li,{children:"Artifact creation and management"}),"\n"]}),"\n",(0,r.jsx)(n.h2,{id:"prerequisites",children:"Prerequisites"}),"\n",(0,r.jsx)(n.p,{children:"Before starting this tutorial, make sure you have:"}),"\n",(0,r.jsxs)(n.ul,{children:["\n",(0,r.jsxs)(n.li,{children:["Read the ",(0,r.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/developing/create-agents",children:"Create Agent"})," tutorial"]}),"\n",(0,r.jsxs)(n.li,{children:["An OpenWeatherMap API key (free at ",(0,r.jsx)(n.a,{href:"https://openweathermap.org/api",children:"openweathermap.org"}),")"]}),"\n",(0,r.jsx)(n.li,{children:"Basic understanding of Python async/await"}),"\n",(0,r.jsx)(n.li,{children:"Familiarity with HTTP APIs"}),"\n"]}),"\n",(0,r.jsx)(n.h2,{id:"planning-the-weather-agent",children:"Planning the Weather Agent"}),"\n",(0,r.jsx)(n.p,{children:"Our weather agent will have the following capabilities:"}),"\n",(0,r.jsxs)(n.ol,{children:["\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"Get Current Weather"}),": Fetch current weather conditions for a specified location"]}),"\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"Get Weather Forecast"}),": Retrieve a multi-day weather forecast"]}),"\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"Save Weather Reports"}),": Store weather data as artifacts"]}),"\n"]}),"\n",(0,r.jsx)(n.p,{children:"The agent will demonstrate:"}),"\n",(0,r.jsxs)(n.ul,{children:["\n",(0,r.jsx)(n.li,{children:"External API integration"}),"\n",(0,r.jsx)(n.li,{children:"Error handling and validation"}),"\n",(0,r.jsx)(n.li,{children:"Configuration management"}),"\n",(0,r.jsx)(n.li,{children:"Artifact creation"}),"\n",(0,r.jsx)(n.li,{children:"Resource lifecycle management"}),"\n"]}),"\n",(0,r.jsx)(n.h2,{id:"step-1-project-structure",children:"Step 1: Project Structure"}),"\n",(0,r.jsx)(n.p,{children:"Run the following command to create a new custom agent:"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-bash",children:"sam add agent --gui\n"})}),"\n",(0,r.jsxs)(n.admonition,{type:"tip",children:[(0,r.jsxs)(n.p,{children:["You can create an agent either by using the ",(0,r.jsx)(n.code,{children:"sam add agent"})," command or by creating a new plugin of type agent, ",(0,r.jsx)(n.code,{children:"sam plugin create my-hello-agent --type agent"}),"."]}),(0,r.jsxs)(n.p,{children:["For information and recommendations about these options, see ",(0,r.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/components/plugins#agent-or-plugin-which-to-use",children:(0,r.jsx)(n.code,{children:"Agent or Plugin: Which To use?"})}),"."]}),(0,r.jsxs)(n.p,{children:["For an example of plugin agents, see the ",(0,r.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/developing/create-agents#creating-your-first-agent-step-by-step",children:"Create Agents"})," guide."]})]}),"\n",(0,r.jsx)(n.p,{children:'Follow the steps on the GUI to create a new agent named "Weather Agent". We can update the tools/skills section directly in the configuration file later.'}),"\n",(0,r.jsxs)(n.admonition,{title:"Important Notice",type:"warning",children:[(0,r.jsx)(n.p,{children:"This tutorial is intentionally comprehensive to demonstrate the full flexibility and advanced features available in Agent Mesh agents. For most straightforward use cases, you only need a simple Python function and a corresponding reference in your YAML configuration file."}),(0,r.jsxs)(t,{children:[(0,r.jsx)("summary",{children:"Simple Weather Agent Example"}),(0,r.jsxs)(n.p,{children:["After going through the add agent wizard from ",(0,r.jsx)(n.code,{children:"sam add agent --gui"}),", create the following file under ",(0,r.jsx)(n.code,{children:"src/weather_agent/tools.py"})," directory:"]}),(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-py",children:'# src/weather_agent/tools.py\nimport httpx\nfrom typing import Any, Dict, Optional\nfrom google.adk.tools import ToolContext\nfrom solace_ai_connector.common.log import log\n\n\nasync def get_current_weather(\n    location: str,\n    units: str = "metric",\n    tool_context: Optional[ToolContext] = None,\n    tool_config: Optional[Dict[str, Any]] = None\n) -> Dict[str, Any]:\n    """\n    Get current weather conditions for a specified location.\n    \n    Args:\n        location: City name, state, and country (for example, "New York, NY, US")\n        units: Temperature units - "metric" (Celsius), "imperial" (Fahrenheit), or "kelvin"\n    """\n    log.info("[GetCurrentWeather] Getting current weather for: %s", location)\n    base_url = "https://api.openweathermap.org/data/2.5"\n    api_key = tool_config.get("api_key") if tool_config else None\n\n    url = f"{base_url}/weather"\n    params = {\n        "q": location,\n        "appid": api_key,\n        "units": units\n    }\n\n    try:\n        # Fetch weather data\n        async with httpx.AsyncClient() as client:\n            response = await client.get(url, params=params)\n            response.raise_for_status()\n            weather_data = response.json()\n        \n        result = {\n            "status": "success",\n            "location": location,\n            "units": units,\n            "data": weather_data\n        }\n        return result\n    \n    except Exception as e:\n        log.error(f"[GetCurrentWeather] Error getting weather: {e}")\n        return {\n            "status": "error",\n            "message": f"Weather service error: {str(e)}"\n        }\n\n\nasync def get_weather_forecast(\n    location: str,\n    days: int = 5,\n    units: str = "metric",\n    tool_context: Optional[ToolContext] = None,\n    tool_config: Optional[Dict[str, Any]] = None\n) -> Dict[str, Any]:\n    """\n    Get weather forecast for a specified location.\n    \n    Args:\n        location: City name, state, and country\n        days: Number of days for forecast (1-5)\n        units: Temperature units\n    """\n    log.info("[GetWeatherForecast] Getting %d-day forecast for: %s", days, location)\n    base_url = "https://api.openweathermap.org/data/2.5"\n    api_key = tool_config.get("api_key") if tool_config else None\n\n    url = f"{base_url}/forecast"\n    params = {\n        "q": location,\n        "appid": api_key,\n        "units": units,\n        "cnt": min(days * 8, 40) \n    }\n\n    try:\n        # Fetch forecast data\n        async with httpx.AsyncClient() as client:\n            response = await client.get(url, params=params)\n            response.raise_for_status()\n            forecast_data = response.json()\n\n        result = {\n            "status": "success",\n            "location": forecast_data["location"],\n            "days": days,\n            "units": units,\n            "data": forecast_data\n        }\n        return result\n    except Exception as e:\n        log.error(f"[GetWeatherForecast] Error getting forecast: {e}")\n        return {\n            "status": "error",\n            "message": f"Weather service error: {str(e)}"\n        }\n\n'})}),(0,r.jsxs)(n.p,{children:["And update the weather agent config file's tool section under ",(0,r.jsx)(n.code,{children:"configs/agent/weather-agent.yaml"})," as follows:"]}),(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-yaml",children:'      # Tools configuration\n      tools:\n        # Current weather tool\n        - tool_type: python\n          component_module: "src.weather_agent.tools"\n          component_base_path: .\n          function_name: "get_current_weather"\n          tool_description: "Get current weather conditions for a specified location"\n          tool_config:\n            api_key: ${OPENWEATHER_API_KEY}\n\n        # Weather forecast tool\n        - tool_type: python\n          component_module: "src.weather_agent.tools"\n          function_name: "get_weather_forecast"\n          component_base_path: .\n          tool_description: "Get weather forecast for up to 5 days for a specified location"\n          tool_config:\n            api_key: ${OPENWEATHER_API_KEY}\n\n'})}),(0,r.jsxs)(n.p,{children:["For better discoverability, update the ",(0,r.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/components/agents#agent-card",children:"agent card"})," section in the same YAML file as follows:"]}),(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-yaml",children:'      # Agent card\n      agent_card:\n        description: "Professional weather agent providing current conditions, forecasts, and weather comparisons"\n        defaultInputModes: ["text"]\n        defaultOutputModes: ["text"]\n        skills:\n          - id: "get_current_weather"\n            name: "Get Current Weather"\n            description: "Retrieve current weather conditions for any location worldwide"\n          - id: "get_weather_forecast"\n            name: "Get Weather Forecast"\n            description: "Provide detailed weather forecasts up to 5 days ahead"\n'})}),(0,r.jsxs)(n.p,{children:["To run the agent, you can continue following documentation from ",(0,r.jsx)(n.a,{href:"#step-6-environment-setup",children:"Step 6"})," of this tutorial."]})]}),(0,r.jsx)(n.p,{children:"Other concepts mentioned in this page such as lifecycle, services, artifacts are just to showcase more advanced patterns."})]}),"\n",(0,r.jsx)(n.p,{children:"Create the directory structure for the weather agent:"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{children:"sam-project/\n\u251c\u2500\u2500 src/\n\u2502   \u2514\u2500\u2500 weather_agent/\n\u2502       \u251c\u2500\u2500 __init__.py\n\u2502       \u251c\u2500\u2500 tools.py\n\u2502       \u251c\u2500\u2500 lifecycle.py\n\u2502       \u2514\u2500\u2500 services/\n\u2502           \u251c\u2500\u2500 __init__.py\n\u2502           \u2514\u2500\u2500 weather_service.py\n\u251c\u2500\u2500 configs\n\u2502   \u2514\u2500\u2500 shared_config.yaml\n\u2502   \u2514\u2500\u2500 agents/\n\u2502       \u2514\u2500\u2500 weather_agent.yaml\n...\n"})}),"\n",(0,r.jsxs)(n.admonition,{type:"tip",children:[(0,r.jsxs)(n.p,{children:["In Agent Mesh, you can create an agent either by using the ",(0,r.jsx)(n.code,{children:"sam add agent"})," command or by creating a new plugin of type agent, ",(0,r.jsx)(n.code,{children:"sam plugin create your-agent --type agent"}),"."]}),(0,r.jsxs)(n.p,{children:["This tutorial uses the ",(0,r.jsx)(n.code,{children:"sam add agent"}),' command to create a new agent named "Weather Agent", for an example of creating a custom agent plugin, see the ',(0,r.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/developing/create-agents",children:"Create Agents"})," tutorial."]})]}),"\n",(0,r.jsx)(n.h2,{id:"step-2-weather-service-implementation",children:"Step 2: Weather Service Implementation"}),"\n",(0,r.jsx)(n.p,{children:"First, create a service class to handle weather API interactions:"}),"\n",(0,r.jsx)(n.p,{children:(0,r.jsxs)(n.strong,{children:[(0,r.jsx)(n.code,{children:"src/weather_agent/services/weather_service.py"}),":"]})}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-python",children:'"""\nWeather service for interacting with external weather APIs.\n"""\n\nimport aiohttp\nfrom typing import Dict, Any, Optional, List\nfrom datetime import datetime, timezone\nfrom solace_ai_connector.common.log import log\n\n\nclass WeatherService:\n    """Service for fetching weather data from external APIs."""\n    \n    def __init__(self, api_key: str, base_url: str = "https://api.openweathermap.org/data/2.5"):\n        self.api_key = api_key\n        self.base_url = base_url\n        self.session: Optional[aiohttp.ClientSession] = None\n        self.log_identifier = "[WeatherService]"\n    \n    async def _get_session(self) -> aiohttp.ClientSession:\n        """Get or create an HTTP session."""\n        if self.session is None or self.session.closed:\n            self.session = aiohttp.ClientSession()\n        return self.session\n    \n    async def close(self):\n        """Close the HTTP session."""\n        if self.session and not self.session.closed:\n            await self.session.close()\n            log.info(f"{self.log_identifier} HTTP session closed")\n    \n    async def get_current_weather(self, location: str, units: str = "metric") -> Dict[str, Any]:\n        """\n        Get current weather for a location.\n        \n        Args:\n            location: City name, state code, and country code (for example, "London,UK")\n            units: Temperature units (metric, imperial, kelvin)\n        \n        Returns:\n            Dictionary containing current weather data\n        """\n        log.info(f"{self.log_identifier} Fetching current weather for: {location}")\n        \n        session = await self._get_session()\n        url = f"{self.base_url}/weather"\n        params = {\n            "q": location,\n            "appid": self.api_key,\n            "units": units\n        }\n        \n        try:\n            async with session.get(url, params=params) as response:\n                if response.status == 200:\n                    data = await response.json()\n                    log.info(f"{self.log_identifier} Successfully fetched weather for {location}")\n                    return self._format_current_weather(data)\n                elif response.status == 404:\n                    raise ValueError(f"Location \'{location}\' not found")\n                else:\n                    error_data = await response.json()\n                    raise Exception(f"Weather API error: {error_data.get(\'message\', \'Unknown error\')}")\n        \n        except aiohttp.ClientError as e:\n            log.error(f"{self.log_identifier} Network error fetching weather: {e}")\n            raise Exception(f"Network error: {str(e)}")\n    \n    async def get_weather_forecast(self, location: str, days: int = 5, units: str = "metric") -> Dict[str, Any]:\n        """\n        Get weather forecast for a location.\n        \n        Args:\n            location: City name, state code, and country code\n            days: Number of days for forecast (1-5)\n            units: Temperature units\n        \n        Returns:\n            Dictionary containing forecast data\n        """\n        log.info(f"{self.log_identifier} Fetching {days}-day forecast for: {location}")\n        \n        session = await self._get_session()\n        url = f"{self.base_url}/forecast"\n        params = {\n            "q": location,\n            "appid": self.api_key,\n            "units": units,\n            "cnt": min(days * 8, 40)  # API returns 3-hour intervals, max 40 entries\n        }\n        \n        try:\n            async with session.get(url, params=params) as response:\n                if response.status == 200:\n                    data = await response.json()\n                    log.info(f"{self.log_identifier} Successfully fetched forecast for {location}")\n                    return self._format_forecast_data(data, days)\n                elif response.status == 404:\n                    raise ValueError(f"Location \'{location}\' not found")\n                else:\n                    error_data = await response.json()\n                    raise Exception(f"Weather API error: {error_data.get(\'message\', \'Unknown error\')}")\n        \n        except aiohttp.ClientError as e:\n            log.error(f"{self.log_identifier} Network error fetching forecast: {e}")\n            raise Exception(f"Network error: {str(e)}")\n    \n    def _format_current_weather(self, data: Dict) -> Dict[str, Any]:\n        """Format current weather data for consistent output."""\n        return {\n            "location": f"{data[\'name\']}, {data[\'sys\'][\'country\']}",\n            "temperature": data[\'main\'][\'temp\'],\n            "feels_like": data[\'main\'][\'feels_like\'],\n            "humidity": data[\'main\'][\'humidity\'],\n            "pressure": data[\'main\'][\'pressure\'],\n            "description": data[\'weather\'][0][\'description\'].title(),\n            "wind_speed": data.get(\'wind\', {}).get(\'speed\', 0),\n            "wind_direction": data.get(\'wind\', {}).get(\'deg\', 0),\n            "visibility": data.get(\'visibility\', 0) / 1000,  # Convert to km\n            "timestamp": datetime.fromtimestamp(data[\'dt\']).isoformat(),\n            "sunrise": datetime.fromtimestamp(data[\'sys\'][\'sunrise\']).isoformat(),\n            "sunset": datetime.fromtimestamp(data[\'sys\'][\'sunset\']).isoformat()\n        }\n    \n    def _format_forecast_data(self, data: Dict, days: int) -> Dict[str, Any]:\n        """Format forecast data for consistent output."""\n        forecasts = []\n        current_date = None\n        daily_data = []\n        \n        for item in data[\'list\'][:days * 8]:\n            forecast_date = datetime.fromtimestamp(item[\'dt\']).date()\n            \n            if current_date != forecast_date:\n                if daily_data:\n                    forecasts.append(self._aggregate_daily_forecast(daily_data))\n                current_date = forecast_date\n                daily_data = []\n            \n            daily_data.append(item)\n        \n        # Add the last day\'s data\n        if daily_data:\n            forecasts.append(self._aggregate_daily_forecast(daily_data))\n        \n        return {\n            "location": f"{data[\'city\'][\'name\']}, {data[\'city\'][\'country\']}",\n            "forecasts": forecasts[:days]\n        }\n    \n    def _aggregate_daily_forecast(self, daily_data: List[Dict]) -> Dict[str, Any]:\n        """Aggregate 3-hour forecasts into daily summary."""\n        if not daily_data:\n            return {}\n        \n        # Get temperatures for min/max calculation\n        temps = [item[\'main\'][\'temp\'] for item in daily_data]\n        \n        # Use the forecast closest to noon for general conditions\n        noon_forecast = min(daily_data, key=lambda x: abs(\n            datetime.fromtimestamp(x[\'dt\']).hour - 12\n        ))\n        \n        return {\n            "date": datetime.fromtimestamp(daily_data[0][\'dt\']).date().isoformat(),\n            "temperature_min": min(temps),\n            "temperature_max": max(temps),\n            "description": noon_forecast[\'weather\'][0][\'description\'].title(),\n            "humidity": noon_forecast[\'main\'][\'humidity\'],\n            "wind_speed": noon_forecast.get(\'wind\', {}).get(\'speed\', 0),\n            "precipitation_probability": noon_forecast.get(\'pop\', 0) * 100\n        }\n'})}),"\n",(0,r.jsx)(n.h2,{id:"step-3-weather-tools-implementation",children:"Step 3: Weather Tools Implementation"}),"\n",(0,r.jsx)(n.p,{children:"Now create the tool functions:"}),"\n",(0,r.jsx)(n.p,{children:(0,r.jsxs)(n.strong,{children:[(0,r.jsx)(n.code,{children:"src/weather_agent/tools.py"}),":"]})}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-python",children:'"""\nWeather agent tools for fetching and processing weather data.\n"""\n\nimport json\nfrom typing import Any, Dict, Optional\nfrom datetime import datetime, timezone\nfrom google.adk.tools import ToolContext\nfrom solace_ai_connector.common.log import log\nfrom solace_agent_mesh.agent.utils.artifact_helpers import save_artifact_with_metadata\n\nasync def get_current_weather(\n    location: str,\n    units: str = "metric",\n    save_to_file: bool = False,\n    tool_context: Optional[ToolContext] = None,\n    tool_config: Optional[Dict[str, Any]] = None\n) -> Dict[str, Any]:\n    """\n    Get current weather conditions for a specified location.\n    \n    Args:\n        location: City name, state, and country (for example, "New York, NY, US")\n        units: Temperature units - "metric" (Celsius), "imperial" (Fahrenheit), or "kelvin"\n        save_to_file: Whether to save the weather report as an artifact\n    \n    Returns:\n        Dictionary containing current weather information\n    """\n    log_identifier = "[GetCurrentWeather]"\n    log.info(f"{log_identifier} Getting current weather for: {location}")\n    \n    if not tool_context:\n        return {\n            "status": "error",\n            "message": "Tool context is required for weather operations"\n        }\n    \n    try:\n        # Get weather service from agent state\n        host_component = getattr(tool_context._invocation_context, "agent", None)\n        if host_component:\n            host_component = getattr(host_component, "host_component", None)\n        \n        if not host_component:\n            return {\n                "status": "error",\n                "message": "Could not access agent host component"\n            }\n        \n        weather_service = host_component.get_agent_specific_state("weather_service")\n        if not weather_service:\n            return {\n                "status": "error",\n                "message": "Weather service not initialized"\n            }\n        \n        # Fetch weather data\n        weather_data = await weather_service.get_current_weather(location, units)\n        \n        # Create human-readable summary\n        summary = _create_weather_summary(weather_data)\n        \n        result = {\n            "status": "success",\n            "location": weather_data["location"],\n            "summary": summary,\n            "data": weather_data\n        }\n        \n        # Save to artifact if requested\n        if save_to_file:\n            artifact_result = await _save_weather_artifact(\n                weather_data, f"current_weather_{location}", tool_context\n            )\n            result["artifact"] = artifact_result\n        \n        log.info(f"{log_identifier} Successfully retrieved weather for {location}")\n        return result\n    \n    except ValueError as e:\n        log.warning(f"{log_identifier} Invalid location: {e}")\n        return {\n            "status": "error",\n            "message": f"Location error: {str(e)}"\n        }\n    except Exception as e:\n        log.error(f"{log_identifier} Error getting weather: {e}")\n        return {\n            "status": "error",\n            "message": f"Weather service error: {str(e)}"\n        }\n\n\nasync def get_weather_forecast(\n    location: str,\n    days: int = 5,\n    units: str = "metric",\n    save_to_file: bool = False,\n    tool_context: Optional[ToolContext] = None,\n    tool_config: Optional[Dict[str, Any]] = None\n) -> Dict[str, Any]:\n    """\n    Get weather forecast for a specified location.\n    \n    Args:\n        location: City name, state, and country\n        days: Number of days for forecast (1-5)\n        units: Temperature units\n        save_to_file: Whether to save the forecast as an artifact\n    \n    Returns:\n        Dictionary containing weather forecast information\n    """\n    log_identifier = "[GetWeatherForecast]"\n    log.info(f"{log_identifier} Getting {days}-day forecast for: {location}")\n    \n    if not tool_context:\n        return {\n            "status": "error",\n            "message": "Tool context is required for weather operations"\n        }\n    \n    # Validate days parameter\n    if not 1 <= days <= 5:\n        return {\n            "status": "error",\n            "message": "Days must be between 1 and 5"\n        }\n    \n    try:\n        # Get weather service from agent state\n        host_component = getattr(tool_context._invocation_context, "agent", None)\n        if host_component:\n            host_component = getattr(host_component, "host_component", None)\n        \n        if not host_component:\n            return {\n                "status": "error",\n                "message": "Could not access agent host component"\n            }\n        \n        weather_service = host_component.get_agent_specific_state("weather_service")\n        if not weather_service:\n            return {\n                "status": "error",\n                "message": "Weather service not initialized"\n            }\n        \n        # Fetch forecast data\n        forecast_data = await weather_service.get_weather_forecast(location, days, units)\n        \n        # Create human-readable summary\n        summary = _create_forecast_summary(forecast_data)\n        \n        result = {\n            "status": "success",\n            "location": forecast_data["location"],\n            "summary": summary,\n            "data": forecast_data\n        }\n        \n        # Save to artifact if requested\n        if save_to_file:\n            artifact_result = await _save_weather_artifact(\n                forecast_data, f"forecast_{location}_{days}day", tool_context\n            )\n            result["artifact"] = artifact_result\n        \n        log.info(f"{log_identifier} Successfully retrieved forecast for {location}")\n        return result\n    \n    except ValueError as e:\n        log.warning(f"{log_identifier} Invalid location: {e}")\n        return {\n            "status": "error",\n            "message": f"Location error: {str(e)}"\n        }\n    except Exception as e:\n        log.error(f"{log_identifier} Error getting forecast: {e}")\n        return {\n            "status": "error",\n            "message": f"Weather service error: {str(e)}"\n        }\n\n\ndef _create_weather_summary(weather_data: Dict[str, Any]) -> str:\n    """Create a human-readable weather summary."""\n    temp_unit = "\xb0C"  # Assuming metric units for summary\n    \n    summary = f"Current weather in {weather_data[\'location\']}:\\n"\n    summary += f"\u2022 Temperature: {weather_data[\'temperature\']}{temp_unit} (feels like {weather_data[\'feels_like\']}{temp_unit})\\n"\n    summary += f"\u2022 Conditions: {weather_data[\'description\']}\\n"\n    summary += f"\u2022 Humidity: {weather_data[\'humidity\']}%\\n"\n    summary += f"\u2022 Wind: {weather_data[\'wind_speed\']} m/s\\n"\n    summary += f"\u2022 Visibility: {weather_data[\'visibility\']} km"\n    \n    return summary\n\n\ndef _create_forecast_summary(forecast_data: Dict[str, Any]) -> str:\n    """Create a human-readable forecast summary."""\n    summary = f"Weather forecast for {forecast_data[\'location\']}:\\n\\n"\n    \n    for forecast in forecast_data[\'forecasts\']:\n        date = datetime.fromisoformat(forecast[\'date\']).strftime(\'%A, %B %d\')\n        summary += f"\u2022 {date}: {forecast[\'description\']}\\n"\n        summary += f"  High: {forecast[\'temperature_max\']:.1f}\xb0C, Low: {forecast[\'temperature_min\']:.1f}\xb0C\\n"\n        if forecast[\'precipitation_probability\'] > 0:\n            summary += f"  Precipitation: {forecast[\'precipitation_probability\']:.0f}% chance\\n"\n        summary += "\\n"\n    \n    return summary.strip()\n\n\nasync def _save_weather_artifact(\n    weather_data: Dict[str, Any],\n    filename_base: str,\n    tool_context: ToolContext\n) -> Dict[str, Any]:\n    """Save weather data as an artifact."""\n    try:\n        # Prepare content\n        content = json.dumps(weather_data, indent=2, default=str)\n        timestamp = datetime.now(timezone.utc)\n        filename = f"{filename_base}_{timestamp.strftime(\'%Y%m%d_%H%M%S\')}.json"\n        \n        # Save artifact\n        artifact_service = tool_context._invocation_context.artifact_service\n        result = await save_artifact_with_metadata(\n            artifact_service=artifact_service,\n            app_name=tool_context._invocation_context.app_name,\n            user_id=tool_context._invocation_context.user_id,\n            session_id=tool_context._invocation_context.session.id,\n            filename=filename,\n            content_bytes=content.encode(\'utf-8\'),\n            mime_type="application/json",\n            metadata_dict={\n                "description": "Weather data report",\n                "source": "Weather Agent"\n            },\n            timestamp=timestamp\n        )\n        \n        return {\n            "filename": filename,\n            "status": result.get("status", "success")\n        }\n    \n    except Exception as e:\n        log.error(f"[WeatherArtifact] Error saving artifact: {e}")\n        return {\n            "status": "error",\n            "message": f"Failed to save artifact: {str(e)}"\n        }\n'})}),"\n",(0,r.jsx)(n.h2,{id:"step-4-lifecycle-functions",children:"Step 4: Lifecycle Functions"}),"\n",(0,r.jsx)(n.p,{children:"Create the lifecycle management:"}),"\n",(0,r.jsx)(n.p,{children:(0,r.jsxs)(n.strong,{children:[(0,r.jsx)(n.code,{children:"src/weather_agent/lifecycle.py"}),":"]})}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-python",children:'"""\nLifecycle functions for the Weather Agent.\n"""\n\nfrom typing import Any\nimport asyncio\nfrom pydantic import BaseModel, Field, SecretStr\nfrom solace_ai_connector.common.log import log\nfrom .services.weather_service import WeatherService\n\n\nclass WeatherAgentInitConfig(BaseModel):\n    """\n    Configuration model for Weather Agent initialization.\n    """\n    api_key: SecretStr = Field(description="OpenWeatherMap API key")\n    base_url: str = Field(\n        default="https://api.openweathermap.org/data/2.5",\n        description="Weather API base URL"\n    )\n    startup_message: str = Field(\n        default="Weather Agent is ready to provide weather information!",\n        description="Message to log on startup"\n    )\n\n\ndef initialize_weather_agent(host_component: Any, init_config: WeatherAgentInitConfig):\n    """\n    Initialize the Weather Agent with weather service.\n    \n    Args:\n        host_component: The agent host component\n        init_config: Validated initialization configuration\n    """\n    log_identifier = f"[{host_component.agent_name}:init]"\n    log.info(f"{log_identifier} Starting Weather Agent initialization...")\n    \n    try:\n        # Initialize weather service\n        weather_service = WeatherService(\n            api_key=init_config.api_key.get_secret_value(),\n            base_url=init_config.base_url\n        )\n        \n        # Store service in agent state\n        host_component.set_agent_specific_state("weather_service", weather_service)\n        \n        # Log startup message\n        log.info(f"{log_identifier} {init_config.startup_message}")\n        \n        # Store initialization metadata\n        host_component.set_agent_specific_state("initialized_at", "2024-01-01T00:00:00Z")\n        host_component.set_agent_specific_state("weather_requests_count", 0)\n        \n        log.info(f"{log_identifier} Weather Agent initialization completed successfully")\n    \n    except Exception as e:\n        log.error(f"{log_identifier} Failed to initialize Weather Agent: {e}")\n        raise\n\n\ndef cleanup_weather_agent(host_component: Any):\n    """\n    Clean up Weather Agent resources.\n    \n    Args:\n        host_component: The agent host component\n    """\n    log_identifier = f"[{host_component.agent_name}:cleanup]"\n    log.info(f"{log_identifier} Starting Weather Agent cleanup...")\n\n    async def cleanup_async(host_component: Any):\n        try:\n            # Get and close weather service\n            weather_service = host_component.get_agent_specific_state("weather_service")\n            if weather_service:\n                await weather_service.close()\n                log.info(f"{log_identifier} Weather service closed successfully")\n            \n            # Log final statistics\n            request_count = host_component.get_agent_specific_state("weather_requests_count", 0)\n            log.info(f"{log_identifier} Agent processed {request_count} weather requests during its lifetime")\n            \n            log.info(f"{log_identifier} Weather Agent cleanup completed")\n        \n        except Exception as e:\n            log.error(f"{log_identifier} Error during cleanup: {e}")\n    \n    # run cleanup in the event loop\n    loop = asyncio.get_event_loop()\n    loop.run_until_complete(cleanup_async(host_component))\n    log.info(f"{log_identifier} Weather Agent cleanup completed successfully")\n'})}),"\n",(0,r.jsx)(n.h2,{id:"step-5-agent-configuration",children:"Step 5: Agent Configuration"}),"\n",(0,r.jsx)(n.p,{children:"Create the comprehensive YAML configuration:"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-yaml",children:'# Weather Agent Configuration\nlog:\n  stdout_log_level: INFO\n  log_file_level: DEBUG\n  log_file: weather-agent.log\n\n!include ../shared_config.yaml\n\napps:\n  - name: weather-agent\n    # Broker configuration\n    app_module: solace_agent_mesh.agent.sac.app\n    broker:\n      <<: *broker_connection\n\n    app_config:\n      namespace: "${NAMESPACE}"\n      agent_name: "WeatherAgent"\n      display_name: "Weather Information Agent"\n      supports_streaming: true\n      \n      # LLM model configuration\n      model: *general_model\n      \n      # Agent instructions\n      instruction: |\n        You are a professional weather agent that provides accurate, up-to-date weather information.\n        \n        Your capabilities include:\n        1. Getting current weather conditions for any location worldwide\n        2. Providing detailed weather forecasts up to 5 days\n        3. Saving weather reports as files for future reference\n        \n        Guidelines:\n        - Always specify the location clearly when providing weather information\n        - Include relevant details like temperature, conditions, humidity, and wind\n        - Offer to save weather reports when providing detailed information\n        - Be helpful in suggesting appropriate clothing or activities based on weather\n        - If a location is ambiguous, ask for clarification (city, state/province, country)\n        \n        When users ask about weather, use the appropriate tools to fetch real-time data.\n        Present information in a clear, organized manner that\'s easy to understand.\n      \n      # Lifecycle functions\n      agent_init_function:\n        module: "src.weather_agent.lifecycle"\n        name: "initialize_weather_agent"\n        base_path: .\n        config:\n          api_key: ${OPENWEATHER_API_KEY}\n          base_url: "https://api.openweathermap.org/data/2.5"\n          startup_message: "Weather Agent is ready to provide weather information!"\n      \n      agent_cleanup_function:\n        module: "src.weather_agent.lifecycle"\n        base_path: .\n        name: "cleanup_weather_agent"\n      \n      # Tools configuration\n      tools:\n        # Current weather tool\n        - tool_type: python\n          component_module: "src.weather_agent.tools"\n          component_base_path: .\n          function_name: "get_current_weather"\n          tool_description: "Get current weather conditions for a specified location"\n        \n        # Weather forecast tool\n        - tool_type: python\n          component_module: "src.weather_agent.tools"\n          component_base_path: .\n          function_name: "get_weather_forecast"\n          tool_description: "Get weather forecast for up to 5 days for a specified location"\n        \n        # Built-in artifact tools for file operations\n        - tool_type: builtin-group\n          group_name: "artifact_management"\n    \n      session_service: *default_session_service\n      artifact_service: *default_artifact_service\n\n      artifact_handling_mode: "reference"\n      enable_embed_resolution: true\n      enable_artifact_content_instruction: true\n      # Agent card\n      agent_card:\n        description: "Professional weather agent providing current conditions, forecasts, and weather comparisons"\n        defaultInputModes: ["text"]\n        defaultOutputModes: ["text", "file"]\n        skills:\n          - id: "get_current_weather"\n            name: "Get Current Weather"\n            description: "Retrieve current weather conditions for any location worldwide"\n          - id: "get_weather_forecast"\n            name: "Get Weather Forecast"\n            description: "Provide detailed weather forecasts up to 5 days ahead"\n      \n      agent_card_publishing:\n        interval_seconds: 30\n\n      agent_discovery:\n        enabled: false\n\n      inter_agent_communication:\n        allow_list: []\n        request_timeout_seconds: 30\n'})}),"\n",(0,r.jsxs)(n.p,{children:["For more details on agent cards, see the ",(0,r.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/components/agents#agent-card",children:"Agent Card Concepts"})," documentation."]}),"\n",(0,r.jsx)(n.h2,{id:"step-6-environment-setup",children:"Step 6: Environment Setup"}),"\n",(0,r.jsx)(n.p,{children:"Before running your weather agent, you'll need to:"}),"\n",(0,r.jsxs)(n.ol,{children:["\n",(0,r.jsxs)(n.li,{children:["\n",(0,r.jsxs)(n.p,{children:[(0,r.jsx)(n.strong,{children:"Get an OpenWeatherMap API key"}),":"]}),"\n",(0,r.jsxs)(n.ul,{children:["\n",(0,r.jsxs)(n.li,{children:["Sign up at ",(0,r.jsx)(n.a,{href:"https://openweathermap.org/api",children:"OpenWeatherMap"})]}),"\n",(0,r.jsx)(n.li,{children:"Get your free API key"}),"\n"]}),"\n"]}),"\n",(0,r.jsxs)(n.li,{children:["\n",(0,r.jsxs)(n.p,{children:[(0,r.jsx)(n.strong,{children:"Set environment variables"}),":"]}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-bash",children:'export OPENWEATHER_API_KEY="your_api_key_here"\n# Other environment variables as needed\n'})}),"\n"]}),"\n"]}),"\n",(0,r.jsx)(n.h2,{id:"step-7-running-the-agent",children:"Step 7: Running the Agent"}),"\n",(0,r.jsxs)(n.p,{children:["To start the agent, it is preferred to build the plugin and then install it with your agent name. But for debugging or isolated development testing, you can run your agent from the ",(0,r.jsx)(n.code,{children:"src"})," directory directly using the Agent Mesh CLI."]}),"\n",(0,r.jsx)(n.p,{children:"Start your weather agent for development purposes run:"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-bash",children:"sam run\n"})}),"\n",(0,r.jsxs)(n.ul,{children:["\n",(0,r.jsxs)(n.li,{children:["To solely run the agent, use ",(0,r.jsx)(n.code,{children:"sam run configs/agents/weather_agent.yaml"})]}),"\n"]}),"\n",(0,r.jsx)(n.h2,{id:"step-8-testing-the-weather-agent",children:"Step 8: Testing the Weather Agent"}),"\n",(0,r.jsx)(n.p,{children:"You can test your weather agent with these example requests:"}),"\n",(0,r.jsx)(n.p,{children:(0,r.jsx)(n.strong,{children:"Current Weather:"})}),"\n",(0,r.jsxs)(n.blockquote,{children:["\n",(0,r.jsx)(n.p,{children:'"What\'s the current weather in New York City?"'}),"\n"]}),"\n",(0,r.jsx)(n.p,{children:(0,r.jsx)(n.strong,{children:"Weather Forecast:"})}),"\n",(0,r.jsxs)(n.blockquote,{children:["\n",(0,r.jsx)(n.p,{children:'"Can you give me a 5-day forecast for London, UK and save it to a file?"'}),"\n"]}),"\n",(0,r.jsx)(n.p,{children:(0,r.jsx)(n.strong,{children:"Weather with File Save:"})}),"\n",(0,r.jsxs)(n.blockquote,{children:["\n",(0,r.jsx)(n.p,{children:'"Get the current weather for Tokyo, Japan and save the report"'}),"\n"]}),"\n",(0,r.jsx)(n.h2,{id:"key-features-demonstrated",children:"Key Features Demonstrated"}),"\n",(0,r.jsx)(n.h3,{id:"1-external-api-integration",children:"1. External API Integration"}),"\n",(0,r.jsxs)(n.ul,{children:["\n",(0,r.jsx)(n.li,{children:"Proper HTTP session management"}),"\n",(0,r.jsx)(n.li,{children:"Error handling for network issues"}),"\n",(0,r.jsx)(n.li,{children:"API response transformation"}),"\n"]}),"\n",(0,r.jsx)(n.h3,{id:"2-resource-management",children:"2. Resource Management"}),"\n",(0,r.jsxs)(n.ul,{children:["\n",(0,r.jsx)(n.li,{children:"Lifecycle functions for initialization and cleanup"}),"\n",(0,r.jsx)(n.li,{children:"Shared service instances across tool calls"}),"\n",(0,r.jsx)(n.li,{children:"Proper resource disposal"}),"\n"]}),"\n",(0,r.jsx)(n.h3,{id:"3-configuration-management",children:"3. Configuration Management"}),"\n",(0,r.jsxs)(n.ul,{children:["\n",(0,r.jsx)(n.li,{children:"Pydantic models for type-safe configuration"}),"\n",(0,r.jsx)(n.li,{children:"Environment variable integration"}),"\n",(0,r.jsx)(n.li,{children:"Flexible tool configuration"}),"\n"]}),"\n",(0,r.jsx)(n.h3,{id:"4-error-handling",children:"4. Error Handling"}),"\n",(0,r.jsxs)(n.ul,{children:["\n",(0,r.jsx)(n.li,{children:"Comprehensive exception handling"}),"\n",(0,r.jsx)(n.li,{children:"User-friendly error messages"}),"\n",(0,r.jsx)(n.li,{children:"Logging for debugging"}),"\n"]}),"\n",(0,r.jsx)(n.h3,{id:"5-artifact-management",children:"5. Artifact Management"}),"\n",(0,r.jsxs)(n.ul,{children:["\n",(0,r.jsx)(n.li,{children:"Saving structured data as files"}),"\n",(0,r.jsx)(n.li,{children:"Metadata enrichment"}),"\n",(0,r.jsx)(n.li,{children:"File format handling"}),"\n"]})]})}function h(e={}){const{wrapper:n}={...(0,o.R)(),...e.components};return n?(0,r.jsx)(n,{...e,children:(0,r.jsx)(d,{...e})}):d(e)}},8453:(e,n,t)=>{t.d(n,{R:()=>i,x:()=>s});var a=t(6540);const r={},o=a.createContext(r);function i(e){const n=a.useContext(o);return a.useMemo((function(){return"function"==typeof e?e(n):{...n,...e}}),[n,e])}function s(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(r):e.components||r:i(e.components),a.createElement(o.Provider,{value:n},e.children)}}}]);

solace_agent_mesh/assets/docs/assets/js/6d84eae0.fd23ba4a.js

@@ -0,0 +1 @@
+"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[3404],{7711:(n,e,t)=>{t.r(e),t.d(e,{assets:()=>c,contentTitle:()=>r,default:()=>u,frontMatter:()=>a,metadata:()=>i,toc:()=>l});const i=JSON.parse('{"id":"documentation/installing-and-configuring/installing-and-configuring","title":"Installing and Configuring Agent Mesh","description":"Getting Agent Mesh up and running involves several key steps that prepare your development environment and configure the system for your specific needs. You\'ll install the framework, create your first project, configure essential settings, and connect to the language models that power your intelligent agents.","source":"@site/docs/documentation/installing-and-configuring/installing-and-configuring.md","sourceDirName":"documentation/installing-and-configuring","slug":"/documentation/installing-and-configuring/","permalink":"/solace-agent-mesh/docs/documentation/installing-and-configuring/","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/installing-and-configuring/installing-and-configuring.md","tags":[],"version":"current","sidebarPosition":300,"frontMatter":{"title":"Installing and Configuring Agent Mesh","sidebar_position":300},"sidebar":"docSidebar","previous":{"title":"Speech Integration","permalink":"/solace-agent-mesh/docs/documentation/components/speech"},"next":{"title":"Installing Agent Mesh","permalink":"/solace-agent-mesh/docs/documentation/installing-and-configuring/installation"}}');var o=t(4848),s=t(8453);const a={title:"Installing and Configuring Agent Mesh",sidebar_position:300},r="Installing and Configuring Agent Mesh",c={},l=[{value:"Setting Up Your Environment",id:"setting-up-your-environment",level:2},{value:"Creating Your First Project",id:"creating-your-first-project",level:2},{value:"Managing System Configuration",id:"managing-system-configuration",level:2},{value:"Connecting Language Models",id:"connecting-language-models",level:2}];function g(n){const e={a:"a",h1:"h1",h2:"h2",header:"header",p:"p",...(0,s.R)(),...n.components};return(0,o.jsxs)(o.Fragment,{children:[(0,o.jsx)(e.header,{children:(0,o.jsx)(e.h1,{id:"installing-and-configuring-agent-mesh",children:"Installing and Configuring Agent Mesh"})}),"\n",(0,o.jsx)(e.p,{children:"Getting Agent Mesh up and running involves several key steps that prepare your development environment and configure the system for your specific needs. You'll install the framework, create your first project, configure essential settings, and connect to the language models that power your intelligent agents."}),"\n",(0,o.jsx)(e.h2,{id:"setting-up-your-environment",children:"Setting Up Your Environment"}),"\n",(0,o.jsxs)(e.p,{children:["Before you can build and deploy agent meshes, you need to install the Agent Mesh framework and CLI tools on your system. The installation process includes setting up Python dependencies, configuring virtual environments, and verifying that all components work correctly. You can choose between local installation using pip or uv, or use the pre-built Docker image for containerized deployments. For complete installation instructions and system requirements, see ",(0,o.jsx)(e.a,{href:"/solace-agent-mesh/docs/documentation/installing-and-configuring/installation",children:"Installing Agent Mesh"}),"."]}),"\n",(0,o.jsx)(e.h2,{id:"creating-your-first-project",children:"Creating Your First Project"}),"\n",(0,o.jsxs)(e.p,{children:["Once you have Agent Mesh installed, you'll create and run your first project to establish a working agent mesh system. This process involves initializing a new project directory, configuring basic settings through either a web interface or command-line prompts, and starting your agent mesh with the built-in orchestrator and web gateway. The project creation process also handles essential setup tasks like environment variable configuration and component initialization. For step-by-step guidance on project creation and execution, see ",(0,o.jsx)(e.a,{href:"/solace-agent-mesh/docs/documentation/installing-and-configuring/run-project",children:"Creating and Running an Agent Mesh Project"}),"."]}),"\n",(0,o.jsx)(e.h2,{id:"managing-system-configuration",children:"Managing System Configuration"}),"\n",(0,o.jsxs)(e.p,{children:["Effective configuration management ensures consistent behavior across all components in your agent mesh deployment. The shared configuration system allows you to define common settings such as broker connections, service definitions, and environment-specific parameters in centralized files that multiple agents and gateways can reference. You'll learn how to structure configuration files, use YAML anchors for reusable settings, and manage multiple configuration environments for development, testing, and production scenarios. For comprehensive configuration guidance and best practices, see ",(0,o.jsx)(e.a,{href:"/solace-agent-mesh/docs/documentation/installing-and-configuring/configurations",children:"Configuring Agent Mesh"}),"."]}),"\n",(0,o.jsx)(e.h2,{id:"connecting-language-models",children:"Connecting Language Models"}),"\n",(0,o.jsxs)(e.p,{children:["Language models provide the intelligence that powers your agents' reasoning, decision-making, and natural language capabilities. The system supports numerous LLM providers through a unified configuration interface, allowing you to connect with OpenAI, Anthropic, Google, Amazon, and many other services. You'll configure model-specific settings, manage API credentials securely through environment variables, and optimize model behavior for different use cases such as planning, general tasks, and specialized functions like image generation or audio transcription. For detailed provider configurations and security settings, see ",(0,o.jsx)(e.a,{href:"/solace-agent-mesh/docs/documentation/installing-and-configuring/large_language_models",children:"Configuration Settings for LLMs"}),"."]})]})}function u(n={}){const{wrapper:e}={...(0,s.R)(),...n.components};return e?(0,o.jsx)(e,{...n,children:(0,o.jsx)(g,{...n})}):g(n)}},8453:(n,e,t)=>{t.d(e,{R:()=>a,x:()=>r});var i=t(6540);const o={},s=i.createContext(o);function a(n){const e=i.useContext(s);return i.useMemo((function(){return"function"==typeof n?n(e):{...e,...n}}),[e,n])}function r(n){let e;return e=n.disableParentContext?"function"==typeof n.components?n.components(o):n.components||o:a(n.components),i.createElement(s.Provider,{value:e},n.children)}}}]);

solace_agent_mesh/assets/docs/assets/js/71da7b71.374b9d54.js

@@ -0,0 +1 @@
+"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[5525],{5822:(e,t,n)=>{n.r(t),n.d(t,{assets:()=>d,contentTitle:()=>o,default:()=>h,frontMatter:()=>l,metadata:()=>i,toc:()=>c});const i=JSON.parse('{"id":"documentation/installing-and-configuring/configurations","title":"Configuring Agent Mesh","description":"The shared_config.yaml file is used to define configurations that can be shared across multiple agents or components in Agent Mesh. This centralized approach simplifies management of common configurations such as Solace event broker connections, language model settings, and service definitions.","source":"@site/docs/documentation/installing-and-configuring/configurations.md","sourceDirName":"documentation/installing-and-configuring","slug":"/documentation/installing-and-configuring/configurations","permalink":"/solace-agent-mesh/docs/documentation/installing-and-configuring/configurations","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/installing-and-configuring/configurations.md","tags":[],"version":"current","sidebarPosition":330,"frontMatter":{"title":"Configuring Agent Mesh","sidebar_position":330,"toc_max_heading_level":4},"sidebar":"docSidebar","previous":{"title":"Creating and Running an Agent Mesh Project","permalink":"/solace-agent-mesh/docs/documentation/installing-and-configuring/run-project"},"next":{"title":"Configuring LLMs","permalink":"/solace-agent-mesh/docs/documentation/installing-and-configuring/large_language_models"}}');var s=n(4848),r=n(8453);const l={title:"Configuring Agent Mesh",sidebar_position:330,toc_max_heading_level:4},o=void 0,d={},c=[{value:"Understanding Shared Configuration",id:"understanding-shared-configuration",level:2},{value:"Managing Multiple Shared Configuration Files",id:"managing-multiple-shared-configuration-files",level:3},{value:"Configuration Structure",id:"configuration-structure",level:2},{value:"Event Broker Connection",id:"event-broker-connection",level:2},{value:"LLM Configuration",id:"llm-configuration",level:2},{value:"Model Configuration Parameters",id:"model-configuration-parameters",level:3},{value:"Predefined Model Types",id:"predefined-model-types",level:3},{value:"Service Configuration",id:"service-configuration",level:2},{value:"Session Service",id:"session-service",level:3},{value:"Artifact Service",id:"artifact-service",level:3},{value:"Data Tools Configuration",id:"data-tools-configuration",level:3}];function a(e){const t={a:"a",admonition:"admonition",code:"code",h2:"h2",h3:"h3",li:"li",p:"p",pre:"pre",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.jsxs)(t.p,{children:["The ",(0,s.jsx)(t.code,{children:"shared_config.yaml"})," file is used to define configurations that can be shared across multiple agents or components in Agent Mesh. This centralized approach simplifies management of common configurations such as Solace event broker connections, language model settings, and service definitions."]}),"\n",(0,s.jsx)(t.h2,{id:"understanding-shared-configuration",children:"Understanding Shared Configuration"}),"\n",(0,s.jsxs)(t.p,{children:["All agents and gateways require access to a ",(0,s.jsx)(t.code,{children:"shared_config"})," object. You can provide configuration in the following ways:"]}),"\n",(0,s.jsxs)(t.ul,{children:["\n",(0,s.jsx)(t.li,{children:"hard-coding configuration values directly within your agent or gateway YAML files. This method works for simple setups or quick prototyping, but it becomes unwieldy as your deployment grows."}),"\n",(0,s.jsxs)(t.li,{children:["using the ",(0,s.jsx)(t.code,{children:"!include"})," directive to reference a centralized configuration file. This approach promotes consistency and simplifies maintenance across your entire project."]}),"\n"]}),"\n",(0,s.jsxs)(t.p,{children:["When a plugin is installed, it may come with hard-coded default values. It is a best practice to remove this section and use ",(0,s.jsx)(t.code,{children:"!include"})," to point to the centralized ",(0,s.jsx)(t.code,{children:"shared_config"})," file. This ensures that all components are using the same base configuration."]}),"\n",(0,s.jsx)(t.h3,{id:"managing-multiple-shared-configuration-files",children:"Managing Multiple Shared Configuration Files"}),"\n",(0,s.jsx)(t.p,{children:"You can use multiple shared configuration files to manage different environments or setups (e.g., for different cloud providers), as follows:"}),"\n",(0,s.jsxs)(t.ul,{children:["\n",(0,s.jsxs)(t.li,{children:["\n",(0,s.jsxs)(t.p,{children:["The filename must always begin with ",(0,s.jsx)(t.code,{children:"shared_config"}),", followed by any descriptive suffix that helps identify the configuration's purpose. Examples include ",(0,s.jsx)(t.code,{children:"shared_config_aws.yaml"})," for Amazon Web Services deployments or ",(0,s.jsx)(t.code,{children:"shared_config_production.yaml"})," for production environments. This naming convention ensures the system can locate and process these files correctly."]}),"\n"]}),"\n",(0,s.jsxs)(t.li,{children:["\n",(0,s.jsxs)(t.p,{children:["You can organize configuration files into subdirectories to further improve project structure. For instance, you might place files in ",(0,s.jsx)(t.code,{children:"configs/agents/shared_config.yaml"})," or ",(0,s.jsx)(t.code,{children:"environments/dev/shared_config_dev.yaml"}),". When you use subdirectories, you must update the ",(0,s.jsx)(t.code,{children:"!include"})," path in your agent or gateway configurations to reflect the correct file location."]}),"\n"]}),"\n"]}),"\n",(0,s.jsxs)(t.p,{children:["The configuration file uses YAML anchors (",(0,s.jsx)(t.code,{children:"&anchor_name"}),") to create reusable configuration blocks, which can then be referenced in agent configuration files."]}),"\n",(0,s.jsx)(t.h2,{id:"configuration-structure",children:"Configuration Structure"}),"\n",(0,s.jsxs)(t.p,{children:["The following example shows the structure of the ",(0,s.jsx)(t.code,{children:"shared_config.yaml"})," configuration file:"]}),"\n",(0,s.jsx)(t.pre,{children:(0,s.jsx)(t.code,{className:"language-yaml",children:"shared_config:\n  - broker_connection: &broker_connection\n      dev_mode: ${SOLACE_DEV_MODE, false}\n      broker_url: ${SOLACE_BROKER_URL, ws://localhost:8008}\n      broker_username: ${SOLACE_BROKER_USERNAME, default}\n      broker_password: ${SOLACE_BROKER_PASSWORD, default}\n      broker_vpn: ${SOLACE_BROKER_VPN, default}\n      temporary_queue: ${USE_TEMPORARY_QUEUES, true}\n      # Ensure high enough limits if many agents are running\n      # max_connection_retries: -1 # Retry forever\n\n  - models:\n    planning: &planning_model\n      # This dictionary structure tells ADK to use the LiteLlm wrapper.\n      # 'model' uses the specific model identifier your endpoint expects.\n      model: ${LLM_SERVICE_PLANNING_MODEL_NAME} # Use env var for model name\n      # 'api_base' tells LiteLLM where to send the request.\n      api_base: ${LLM_SERVICE_ENDPOINT} # Use env var for endpoint URL\n      # 'api_key' provides authentication.\n      api_key: ${LLM_SERVICE_API_KEY} # Use env var for API key\n      # Enable parallel tool calls for planning model\n      parallel_tool_calls: true\n      # Prompt Caching Strategy\n      cache_strategy: \"5m\" # none, 5m, 1h\n      # max_tokens: ${MAX_TOKENS, 16000} # Set a reasonable max token limit for planning\n      # temperature: 0.1 # Lower temperature for more deterministic planning\n    \n    general: &general_model\n      # This dictionary structure tells ADK to use the LiteLlm wrapper.\n      # 'model' uses the specific model identifier your endpoint expects.\n      model: ${LLM_SERVICE_GENERAL_MODEL_NAME} # Use env var for model name\n      # 'api_base' tells LiteLLM where to send the request.\n      api_base: ${LLM_SERVICE_ENDPOINT} # Use env var for endpoint URL\n      # 'api_key' provides authentication.\n      api_key: ${LLM_SERVICE_API_KEY} # Use env var for API key\n\n      # ... (similar structure)\n\n  - services:\n    # Default session service configuration\n    session_service: &default_session_service\n      type: \"sql\"\n      database_url: \"${DATABASE_URL, sqlite:///session.db}\"\n      default_behavior: \"PERSISTENT\"\n    \n    # Default artifact service configuration\n    artifact_service: &default_artifact_service\n      type: \"filesystem\"\n      base_path: \"/tmp/samv2\"\n      artifact_scope: namespace\n    \n    # Default data tools configuration\n    data_tools_config: &default_data_tools_config\n      sqlite_memory_threshold_mb: 100\n      max_result_preview_rows: 50\n      max_result_preview_bytes: 4096\n"})}),"\n",(0,s.jsx)(t.h2,{id:"event-broker-connection",children:"Event Broker Connection"}),"\n",(0,s.jsxs)(t.p,{children:["The ",(0,s.jsx)(t.code,{children:"broker_connection"})," section configures the connection to the Solace event broker. The connection parameters are described in the following table:"]}),"\n",(0,s.jsxs)(t.table,{children:[(0,s.jsx)(t.thead,{children:(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.th,{style:{textAlign:"left"},children:"Parameter"}),(0,s.jsx)(t.th,{style:{textAlign:"left"},children:"Environment Variable"}),(0,s.jsx)(t.th,{style:{textAlign:"left"},children:"Description"}),(0,s.jsx)(t.th,{style:{textAlign:"left"},children:"Default"})]})}),(0,s.jsxs)(t.tbody,{children:[(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.td,{style:{textAlign:"left"},children:(0,s.jsx)(t.code,{children:"dev_mode"})}),(0,s.jsx)(t.td,{style:{textAlign:"left"},children:(0,s.jsx)(t.code,{children:"SOLACE_DEV_MODE"})}),(0,s.jsxs)(t.td,{style:{textAlign:"left"},children:["When set to ",(0,s.jsx)(t.code,{children:"true"}),", uses an in-memory broker for testing."]}),(0,s.jsx)(t.td,{style:{textAlign:"left"},children:(0,s.jsx)(t.code,{children:"false"})})]}),(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.td,{style:{textAlign:"left"},children:(0,s.jsx)(t.code,{children:"broker_url"})}),(0,s.jsx)(t.td,{style:{textAlign:"left"},children:(0,s.jsx)(t.code,{children:"SOLACE_BROKER_URL"})}),(0,s.jsx)(t.td,{style:{textAlign:"left"},children:"The URL of the Solace event broker."}),(0,s.jsx)(t.td,{style:{textAlign:"left"},children:(0,s.jsx)(t.code,{children:"ws://localhost:8008"})})]}),(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.td,{style:{textAlign:"left"},children:(0,s.jsx)(t.code,{children:"broker_username"})}),(0,s.jsx)(t.td,{style:{textAlign:"left"},children:(0,s.jsx)(t.code,{children:"SOLACE_BROKER_USERNAME"})}),(0,s.jsx)(t.td,{style:{textAlign:"left"},children:"The username for authenticating with the event broker."}),(0,s.jsx)(t.td,{style:{textAlign:"left"},children:(0,s.jsx)(t.code,{children:"default"})})]}),(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.td,{style:{textAlign:"left"},children:(0,s.jsx)(t.code,{children:"broker_password"})}),(0,s.jsx)(t.td,{style:{textAlign:"left"},children:(0,s.jsx)(t.code,{children:"SOLACE_BROKER_PASSWORD"})}),(0,s.jsx)(t.td,{style:{textAlign:"left"},children:"The password for authenticating with the event broker."}),(0,s.jsx)(t.td,{style:{textAlign:"left"},children:(0,s.jsx)(t.code,{children:"default"})})]}),(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.td,{style:{textAlign:"left"},children:(0,s.jsx)(t.code,{children:"broker_vpn"})}),(0,s.jsx)(t.td,{style:{textAlign:"left"},children:(0,s.jsx)(t.code,{children:"SOLACE_BROKER_VPN"})}),(0,s.jsx)(t.td,{style:{textAlign:"left"},children:"The Message VPN to connect to on the event broker."}),(0,s.jsx)(t.td,{style:{textAlign:"left"},children:(0,s.jsx)(t.code,{children:"default"})})]}),(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.td,{style:{textAlign:"left"},children:(0,s.jsx)(t.code,{children:"temporary_queue"})}),(0,s.jsx)(t.td,{style:{textAlign:"left"},children:(0,s.jsx)(t.code,{children:"USE_TEMPORARY_QUEUES"})}),(0,s.jsxs)(t.td,{style:{textAlign:"left"},children:["Whether to use temporary queues for communication. If ",(0,s.jsx)(t.code,{children:"false"}),", a durable queue will be created."]}),(0,s.jsx)(t.td,{style:{textAlign:"left"},children:(0,s.jsx)(t.code,{children:"true"})})]}),(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.td,{style:{textAlign:"left"},children:(0,s.jsx)(t.code,{children:"max_connection_retries"})}),(0,s.jsx)(t.td,{style:{textAlign:"left"},children:(0,s.jsx)(t.code,{children:"MAX_CONNECTION_RETRIES"})}),(0,s.jsxs)(t.td,{style:{textAlign:"left"},children:["The maximum number of times to retry connecting to the event broker if the connection fails. A value of ",(0,s.jsx)(t.code,{children:"-1"})," means retry forever."]}),(0,s.jsx)(t.td,{style:{textAlign:"left"},children:(0,s.jsx)(t.code,{children:"-1"})})]})]})]}),"\n",(0,s.jsx)(t.admonition,{type:"tip",children:(0,s.jsxs)(t.p,{children:["If you need to configure multiple brokers, you can do so by adding additional entries under ",(0,s.jsx)(t.code,{children:"shared_config"})," with a unique name (For example,  ",(0,s.jsx)(t.code,{children:"broker_connection_eu: &broker_connection_eu"})," or ",(0,s.jsx)(t.code,{children:"broker_connection_us: &broker_connection_us"}),"). Reference these configurations in your agent files using the appropriate anchor, such as ",(0,s.jsx)(t.code,{children:"<<: *broker_connection_eu"}),"."]})}),"\n",(0,s.jsxs)(t.admonition,{type:"info",children:[(0,s.jsxs)(t.p,{children:["Setting the ",(0,s.jsx)(t.code,{children:"temporary_queue"})," parameter to ",(0,s.jsx)(t.code,{children:"true"})," (default) will use ",(0,s.jsx)(t.a,{href:"https://docs.solace.com/Messaging/Guaranteed-Msg/Endpoints.htm#temporary-endpoints",children:"temporary endpoints"})," for A2A communication. Temporary queues are automatically created and deleted by the broker, which simplifies management and reduces the need for manual cleanup. However, it does not allow for multiple client connections to the same queue, which may be a limitation in some scenarios where you're running multiple instances of the same agent or a new instance needs to be started while an old instance is still running."]}),(0,s.jsxs)(t.p,{children:["If you set ",(0,s.jsx)(t.code,{children:"temporary_queue"})," to ",(0,s.jsx)(t.code,{children:"false"}),", the system will create a durable queue for the client. Durable queues persist beyond the lifetime of the client connection, allowing multiple clients to connect to the same queue and ensuring that messages are not lost if the client disconnects. However, this requires manual management of the queues, including cleanup of unused queues."]}),(0,s.jsxs)(t.p,{children:["Check the ",(0,s.jsx)(t.a,{href:"/solace-agent-mesh/docs/documentation/deploying/deployment-options#setting-up-queue-templates",children:"Setting up Queue Templates"})," section for guidance on configuring queue templates to manage message TTL."]})]}),"\n",(0,s.jsx)(t.h2,{id:"llm-configuration",children:"LLM Configuration"}),"\n",(0,s.jsxs)(t.p,{children:["The models section configures the various Large Language Models and other generative models that power your agents' intelligence. This configuration leverages the ",(0,s.jsx)(t.a,{href:"https://litellm.ai/",children:"LiteLLM"})," library, which provides a standardized interface for interacting with ",(0,s.jsx)(t.a,{href:"https://docs.litellm.ai/docs/providers",children:"different model providers"}),", simplifying the process of switching between or combining multiple AI services."]}),"\n",(0,s.jsx)(t.h3,{id:"model-configuration-parameters",children:"Model Configuration Parameters"}),"\n",(0,s.jsxs)(t.p,{children:["Each model configuration requires specific parameters that tell the system how to communicate with the model provider. The model parameter specifies the exact model identifier in the format expected by your provider, such as ",(0,s.jsx)(t.code,{children:"openai/gpt-4"})," or ",(0,s.jsx)(t.code,{children:"anthropic/claude-3-opus-20240229"}),". The API base URL points to your provider's endpoint, but some providers use default endpoints that don't require explicit specification."]}),"\n",(0,s.jsx)(t.p,{children:"Authentication typically requires an API key, but some providers use alternative authentication mechanisms. Additional parameters control model behavior, such as enabling parallel tool calls for models that support this feature, setting maximum token limits to control response length and costs, and adjusting temperature values to influence response creativity versus determinism."}),"\n",(0,s.jsxs)(t.table,{children:[(0,s.jsx)(t.thead,{children:(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.th,{style:{textAlign:"left"},children:"Parameter"}),(0,s.jsx)(t.th,{style:{textAlign:"left"},children:"Environment Variable"}),(0,s.jsx)(t.th,{style:{textAlign:"left"},children:"Description"})]})}),(0,s.jsxs)(t.tbody,{children:[(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.td,{style:{textAlign:"left"},children:(0,s.jsx)(t.code,{children:"model"})}),(0,s.jsx)(t.td,{style:{textAlign:"left"},children:(0,s.jsx)(t.code,{children:"LLM_SERVICE_<MODEL_NAME>_MODEL_NAME"})}),(0,s.jsxs)(t.td,{style:{textAlign:"left"},children:["The specific model identifier that the endpoint expects in the format of ",(0,s.jsx)(t.code,{children:"provider/model"})," (e.g., ",(0,s.jsx)(t.code,{children:"openai/gpt-4"}),", ",(0,s.jsx)(t.code,{children:"anthropic/claude-3-opus-20240229"}),")."]})]}),(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.td,{style:{textAlign:"left"},children:(0,s.jsx)(t.code,{children:"api_base"})}),(0,s.jsx)(t.td,{style:{textAlign:"left"},children:(0,s.jsx)(t.code,{children:"LLM_SERVICE_ENDPOINT"})}),(0,s.jsx)(t.td,{style:{textAlign:"left"},children:"The base URL of the LLM provider's API endpoint."})]}),(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.td,{style:{textAlign:"left"},children:(0,s.jsx)(t.code,{children:"api_key"})}),(0,s.jsx)(t.td,{style:{textAlign:"left"},children:(0,s.jsx)(t.code,{children:"LLM_SERVICE_API_KEY"})}),(0,s.jsx)(t.td,{style:{textAlign:"left"},children:"The API key for authenticating with the service."})]}),(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.td,{style:{textAlign:"left"},children:(0,s.jsx)(t.code,{children:"parallel_tool_calls"})}),(0,s.jsx)(t.td,{style:{textAlign:"left"}}),(0,s.jsx)(t.td,{style:{textAlign:"left"},children:"Enable parallel tool calls for the model."})]}),(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.td,{style:{textAlign:"left"},children:(0,s.jsx)(t.code,{children:"cache_strategy"})}),(0,s.jsx)(t.td,{style:{textAlign:"left"}}),(0,s.jsxs)(t.td,{style:{textAlign:"left"},children:["Set the prompt caching strategy (one of: ",(0,s.jsx)(t.code,{children:"none"}),", ",(0,s.jsx)(t.code,{children:"5m"}),", ",(0,s.jsx)(t.code,{children:"1h"}),"). For more details check ",(0,s.jsx)(t.a,{href:"/solace-agent-mesh/docs/documentation/installing-and-configuring/large_language_models#prompt-caching",children:"LLM Configuration"})," page."]})]}),(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.td,{style:{textAlign:"left"},children:(0,s.jsx)(t.code,{children:"max_tokens"})}),(0,s.jsx)(t.td,{style:{textAlign:"left"},children:(0,s.jsx)(t.code,{children:"MAX_TOKENS"})}),(0,s.jsx)(t.td,{style:{textAlign:"left"},children:"Set a reasonable max token limit for the model."})]}),(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.td,{style:{textAlign:"left"},children:(0,s.jsx)(t.code,{children:"temperature"})}),(0,s.jsx)(t.td,{style:{textAlign:"left"},children:(0,s.jsx)(t.code,{children:"TEMPERATURE"})}),(0,s.jsx)(t.td,{style:{textAlign:"left"},children:"Lower temperature for more deterministic planning."})]})]})]}),"\n",(0,s.jsx)(t.p,{children:"For Google's Gemini models, you can use a simplified configuration approach that references the model directly:"}),"\n",(0,s.jsx)(t.pre,{children:(0,s.jsx)(t.code,{className:"language-yaml",children:"model: gemini-2.5-pro\n"})}),"\n",(0,s.jsxs)(t.p,{children:["For detailed information about configuring Gemini models and setting up the required environment variables, see the ",(0,s.jsx)(t.a,{href:"https://google.github.io/adk-docs/agents/models/#using-google-gemini-models",children:"Gemini model documentation"}),"."]}),"\n",(0,s.jsx)(t.h3,{id:"predefined-model-types",children:"Predefined Model Types"}),"\n",(0,s.jsxs)(t.p,{children:["The ",(0,s.jsx)(t.code,{children:"shared_config.yaml"})," configuration file defines predefined model types that serve as aliases for specific use cases. These aliases allow you to reference models by their intended purpose rather than their technical specifications, making your agent configurations more readable and maintainable. The model types are as follows:"]}),"\n",(0,s.jsxs)(t.ul,{children:["\n",(0,s.jsxs)(t.li,{children:[(0,s.jsx)(t.code,{children:"planning"}),": Used by agents for planning and decision-making. It's configured for deterministic outputs (",(0,s.jsx)(t.code,{children:"temperature: 0.1"}),") and can use tools in parallel."]}),"\n",(0,s.jsxs)(t.li,{children:[(0,s.jsx)(t.code,{children:"general"}),": A general-purpose model for various tasks."]}),"\n",(0,s.jsxs)(t.li,{children:[(0,s.jsx)(t.code,{children:"image_gen"}),": A model for generating images."]}),"\n",(0,s.jsxs)(t.li,{children:[(0,s.jsx)(t.code,{children:"image_describe"}),": A model for describing the content of images."]}),"\n",(0,s.jsxs)(t.li,{children:[(0,s.jsx)(t.code,{children:"audio_transcription"}),": A model for transcribing audio files."]}),"\n",(0,s.jsxs)(t.li,{children:[(0,s.jsx)(t.code,{children:"report_gen"}),": A model specialized for generating reports."]}),"\n",(0,s.jsxs)(t.li,{children:[(0,s.jsx)(t.code,{children:"multimodal"}),": A simple string reference to a multimodal model (e.g., ",(0,s.jsx)(t.code,{children:'"gemini-1.5-flash-latest"'}),")."]}),"\n"]}),"\n",(0,s.jsxs)(t.p,{children:["You can define any number of models in this section and reference them in your agent configurations. The system uses only the ",(0,s.jsx)(t.code,{children:"planning"})," and ",(0,s.jsx)(t.code,{children:"general"})," models by default; you don't need to configure the specialized models unless your agents specifically require those capabilities."]}),"\n",(0,s.jsxs)(t.p,{children:["For information about configuring different LLM providers and SSL/TLS security settings, see ",(0,s.jsx)(t.a,{href:"/solace-agent-mesh/docs/documentation/installing-and-configuring/large_language_models",children:"Configuring LLMs"}),"."]}),"\n",(0,s.jsx)(t.h2,{id:"service-configuration",children:"Service Configuration"}),"\n",(0,s.jsxs)(t.p,{children:["The ",(0,s.jsx)(t.code,{children:"services"})," section in ",(0,s.jsx)(t.code,{children:"shared_config.yaml"})," is used to configure various services that are available to agents. These services handle concerns such as session persistence, artifact storage, and data processing optimization."]}),"\n",(0,s.jsx)(t.h3,{id:"session-service",children:"Session Service"}),"\n",(0,s.jsxs)(t.p,{children:["The session service manages conversation history and context persistence across agent interactions. This service determines whether your agents remember previous conversations and how long that memory persists. The preset agent configurations default to SQL with SQLite for persistent sessions. For detailed information about session storage backends, architecture, and configuration examples, see ",(0,s.jsx)(t.a,{href:"/solace-agent-mesh/docs/documentation/installing-and-configuring/session-storage",children:"Session Storage"}),"."]}),"\n",(0,s.jsxs)(t.table,{children:[(0,s.jsx)(t.thead,{children:(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.th,{style:{textAlign:"left"},children:"Parameter"}),(0,s.jsx)(t.th,{style:{textAlign:"left"},children:"Options"}),(0,s.jsx)(t.th,{style:{textAlign:"left"},children:"Description"}),(0,s.jsx)(t.th,{style:{textAlign:"left"},children:"Default"})]})}),(0,s.jsxs)(t.tbody,{children:[(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.td,{style:{textAlign:"left"},children:(0,s.jsx)(t.code,{children:"type"})}),(0,s.jsxs)(t.td,{style:{textAlign:"left"},children:[(0,s.jsx)(t.code,{children:"memory"}),", ",(0,s.jsx)(t.code,{children:"sql"})]}),(0,s.jsxs)(t.td,{style:{textAlign:"left"},children:["The storage backend for session data. The ",(0,s.jsx)(t.code,{children:"memory"})," option stores sessions in application memory. The ",(0,s.jsx)(t.code,{children:"sql"})," option stores sessions in a database."]}),(0,s.jsx)(t.td,{style:{textAlign:"left"},children:(0,s.jsx)(t.code,{children:"sql"})})]}),(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.td,{style:{textAlign:"left"},children:(0,s.jsx)(t.code,{children:"database_url"})}),(0,s.jsx)(t.td,{style:{textAlign:"left"},children:"Database URL string"}),(0,s.jsxs)(t.td,{style:{textAlign:"left"},children:["The connection string for your database. Required when ",(0,s.jsx)(t.code,{children:"type"})," is ",(0,s.jsx)(t.code,{children:"sql"}),". Supports SQLite (",(0,s.jsx)(t.code,{children:"sqlite:///path/to/db.db"}),") and PostgreSQL (",(0,s.jsx)(t.code,{children:"postgresql://user:pass@host:port/dbname"}),")."]}),(0,s.jsx)(t.td,{style:{textAlign:"left"},children:"(none)"})]}),(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.td,{style:{textAlign:"left"},children:(0,s.jsx)(t.code,{children:"default_behavior"})}),(0,s.jsxs)(t.td,{style:{textAlign:"left"},children:[(0,s.jsx)(t.code,{children:"PERSISTENT"}),", ",(0,s.jsx)(t.code,{children:"RUN_BASED"})]}),(0,s.jsxs)(t.td,{style:{textAlign:"left"},children:["The retention policy for session history. The ",(0,s.jsx)(t.code,{children:"PERSISTENT"})," option keeps session history indefinitely, while ",(0,s.jsx)(t.code,{children:"RUN_BASED"})," clears history between runs."]}),(0,s.jsx)(t.td,{style:{textAlign:"left"},children:(0,s.jsx)(t.code,{children:"PERSISTENT"})})]})]})]}),"\n",(0,s.jsx)(t.admonition,{type:"tip",children:(0,s.jsxs)(t.p,{children:["The preset agent configurations default to SQL with SQLite databases. You can configure PostgreSQL by setting database URL environment variables as described in the ",(0,s.jsx)(t.a,{href:"/solace-agent-mesh/docs/documentation/installing-and-configuring/session-storage",children:"Session Storage"})," guide."]})}),"\n",(0,s.jsx)(t.h3,{id:"artifact-service",children:"Artifact Service"}),"\n",(0,s.jsxs)(t.p,{children:["The ",(0,s.jsx)(t.code,{children:"artifact_service"})," is responsible for managing artifacts, which are files or data generated by agents, such as generated documents, processed data files, and intermediate results. For detailed information about artifact storage backends, versioning, and production configurations, see ",(0,s.jsx)(t.a,{href:"/solace-agent-mesh/docs/documentation/installing-and-configuring/artifact-storage",children:"Artifact Storage"}),"."]}),"\n",(0,s.jsxs)(t.table,{children:[(0,s.jsx)(t.thead,{children:(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.th,{style:{textAlign:"left"},children:"Parameter"}),(0,s.jsx)(t.th,{style:{textAlign:"left"},children:"Options"}),(0,s.jsx)(t.th,{style:{textAlign:"left"},children:"Description"}),(0,s.jsx)(t.th,{style:{textAlign:"left"},children:"Default"})]})}),(0,s.jsxs)(t.tbody,{children:[(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.td,{style:{textAlign:"left"},children:(0,s.jsx)(t.code,{children:"type"})}),(0,s.jsxs)(t.td,{style:{textAlign:"left"},children:[(0,s.jsx)(t.code,{children:"memory"}),", ",(0,s.jsx)(t.code,{children:"gcs"}),", ",(0,s.jsx)(t.code,{children:"filesystem"})]}),(0,s.jsxs)(t.td,{style:{textAlign:"left"},children:["Service type for artifact storage. Use ",(0,s.jsx)(t.code,{children:"memory"})," for in-memory, ",(0,s.jsx)(t.code,{children:"gcs"})," for Google Cloud Storage, or ",(0,s.jsx)(t.code,{children:"filesystem"})," for local file storage."]}),(0,s.jsx)(t.td,{style:{textAlign:"left"},children:(0,s.jsx)(t.code,{children:"memory"})})]}),(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.td,{style:{textAlign:"left"},children:(0,s.jsx)(t.code,{children:"base_path"})}),(0,s.jsx)(t.td,{style:{textAlign:"left"},children:"local path"}),(0,s.jsxs)(t.td,{style:{textAlign:"left"},children:["Base directory path for storing artifacts. Required only if ",(0,s.jsx)(t.code,{children:"type"})," is ",(0,s.jsx)(t.code,{children:"filesystem"}),"."]}),(0,s.jsx)(t.td,{style:{textAlign:"left"},children:"(none)"})]}),(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.td,{style:{textAlign:"left"},children:(0,s.jsx)(t.code,{children:"bucket_name"})}),(0,s.jsx)(t.td,{style:{textAlign:"left"},children:"bucket name"}),(0,s.jsxs)(t.td,{style:{textAlign:"left"},children:["Google Cloud Storage bucket name. Required only if ",(0,s.jsx)(t.code,{children:"type"})," is ",(0,s.jsx)(t.code,{children:"gcs"}),"."]}),(0,s.jsx)(t.td,{style:{textAlign:"left"},children:"(none)"})]}),(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.td,{style:{textAlign:"left"},children:(0,s.jsx)(t.code,{children:"artifact_scope"})}),(0,s.jsxs)(t.td,{style:{textAlign:"left"},children:[(0,s.jsx)(t.code,{children:"namespace"}),", ",(0,s.jsx)(t.code,{children:"app"})]}),(0,s.jsxs)(t.td,{style:{textAlign:"left"},children:["Scope for artifact sharing. ",(0,s.jsx)(t.code,{children:"namespace"}),": shared by all components in the namespace. ",(0,s.jsx)(t.code,{children:"app"}),": isolated by agent/gateway name. Must be consistent for all components in the same process."]}),(0,s.jsx)(t.td,{style:{textAlign:"left"},children:(0,s.jsx)(t.code,{children:"namespace"})})]}),(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.td,{style:{textAlign:"left"},children:(0,s.jsx)(t.code,{children:"artifact_scope_value"})}),(0,s.jsx)(t.td,{style:{textAlign:"left"},children:"custom scope id"}),(0,s.jsxs)(t.td,{style:{textAlign:"left"},children:["Custom identifier for artifact scope. Required if ",(0,s.jsx)(t.code,{children:"artifact_scope"})," is set to a custom value."]}),(0,s.jsx)(t.td,{style:{textAlign:"left"},children:"(none)"})]})]})]}),"\n",(0,s.jsx)(t.h3,{id:"data-tools-configuration",children:"Data Tools Configuration"}),"\n",(0,s.jsx)(t.p,{children:"The data tools configuration optimizes how agents handle data analysis and processing tasks. These settings balance performance, memory usage, and user experience when agents work with databases and large datasets."}),"\n",(0,s.jsx)(t.p,{children:"The SQLite memory threshold determines when the system switches from disk-based to memory-based database operations. Lower thresholds favor memory usage for better performance although consume more system RAM. Higher thresholds reduce memory pressure although may slow database operations."}),"\n",(0,s.jsx)(t.p,{children:"Result preview settings control how much data agents display when showing query results or data samples. These limits prevent overwhelming users with massive datasets while ensuring they see enough information to understand the results."}),"\n",(0,s.jsxs)(t.table,{children:[(0,s.jsx)(t.thead,{children:(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.th,{style:{textAlign:"left"},children:"Parameter"}),(0,s.jsx)(t.th,{style:{textAlign:"left"},children:"Type"}),(0,s.jsx)(t.th,{style:{textAlign:"left"},children:"Description"}),(0,s.jsx)(t.th,{style:{textAlign:"left"},children:"Default"})]})}),(0,s.jsxs)(t.tbody,{children:[(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.td,{style:{textAlign:"left"},children:(0,s.jsx)(t.code,{children:"sqlite_memory_threshold_mb"})}),(0,s.jsx)(t.td,{style:{textAlign:"left"},children:(0,s.jsx)(t.code,{children:"integer"})}),(0,s.jsx)(t.td,{style:{textAlign:"left"},children:"The memory threshold in megabytes for using an in-memory SQLite database."}),(0,s.jsx)(t.td,{style:{textAlign:"left"},children:(0,s.jsx)(t.code,{children:"100"})})]}),(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.td,{style:{textAlign:"left"},children:(0,s.jsx)(t.code,{children:"max_result_preview_rows"})}),(0,s.jsx)(t.td,{style:{textAlign:"left"},children:(0,s.jsx)(t.code,{children:"integer"})}),(0,s.jsx)(t.td,{style:{textAlign:"left"},children:"The maximum number of rows to show in a result preview."}),(0,s.jsx)(t.td,{style:{textAlign:"left"},children:(0,s.jsx)(t.code,{children:"50"})})]}),(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.td,{style:{textAlign:"left"},children:(0,s.jsx)(t.code,{children:"max_result_preview_bytes"})}),(0,s.jsx)(t.td,{style:{textAlign:"left"},children:(0,s.jsx)(t.code,{children:"integer"})}),(0,s.jsx)(t.td,{style:{textAlign:"left"},children:"The maximum number of bytes to show in a result preview."}),(0,s.jsx)(t.td,{style:{textAlign:"left"},children:(0,s.jsx)(t.code,{children:"4096"})})]})]})]})]})}function h(e={}){const{wrapper:t}={...(0,r.R)(),...e.components};return t?(0,s.jsx)(t,{...e,children:(0,s.jsx)(a,{...e})}):a(e)}},8453:(e,t,n)=>{n.d(t,{R:()=>l,x:()=>o});var i=n(6540);const s={},r=i.createContext(s);function l(e){const t=i.useContext(r);return i.useMemo((function(){return"function"==typeof e?e(t):{...t,...e}}),[t,e])}function o(e){let t;return t=e.disableParentContext?"function"==typeof e.components?e.components(s):e.components||s:l(e.components),i.createElement(r.Provider,{value:t},e.children)}}}]);

solace_agent_mesh/assets/docs/assets/js/729898df.7249e9fd.js

@@ -0,0 +1 @@
+"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[6310],{7048:(e,i,n)=>{n.r(i),n.d(i,{assets:()=>a,contentTitle:()=>r,default:()=>h,frontMatter:()=>l,metadata:()=>o,toc:()=>d});const o=JSON.parse('{"id":"documentation/components/builtin-tools/image-tools","title":"Image Tools","description":"Overview","source":"@site/docs/documentation/components/builtin-tools/image-tools.md","sourceDirName":"documentation/components/builtin-tools","slug":"/documentation/components/builtin-tools/image-tools","permalink":"/solace-agent-mesh/docs/documentation/components/builtin-tools/image-tools","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/components/builtin-tools/image-tools.md","tags":[],"version":"current","sidebarPosition":35,"frontMatter":{"title":"Image Tools","sidebar_position":35},"sidebar":"docSidebar","previous":{"title":"Audio Tools","permalink":"/solace-agent-mesh/docs/documentation/components/builtin-tools/audio-tools"},"next":{"title":"Dynamic Embeds","permalink":"/solace-agent-mesh/docs/documentation/components/builtin-tools/embeds"}}');var t=n(4848),s=n(8453);const l={title:"Image Tools",sidebar_position:35},r="Image Tools",a={},d=[{value:"Overview",id:"overview",level:2},{value:"Available Tools",id:"available-tools",level:3},{value:"Tool Reference",id:"tool-reference",level:2},{value:"create_image_from_description",id:"create_image_from_description",level:3},{value:"Tool Configuration",id:"tool-configuration",level:4},{value:"Configuration Parameters",id:"configuration-parameters",level:4},{value:"Output Format",id:"output-format",level:4},{value:"Example Usage",id:"example-usage",level:4},{value:"describe_image",id:"describe_image",level:3},{value:"Tool Configuration",id:"tool-configuration-1",level:4},{value:"Supported Image Formats",id:"supported-image-formats",level:4},{value:"edit_image_with_gemini",id:"edit_image_with_gemini",level:3},{value:"Tool Configuration",id:"tool-configuration-2",level:4},{value:"Configuration Parameters",id:"configuration-parameters-1",level:4},{value:"Supported Input Formats",id:"supported-input-formats",level:4},{value:"Best Practices",id:"best-practices",level:4},{value:"Tool Group Configuration",id:"tool-group-configuration",level:3}];function c(e){const i={code:"code",h1:"h1",h2:"h2",h3:"h3",h4:"h4",header:"header",hr:"hr",li:"li",ol:"ol",p:"p",pre:"pre",strong:"strong",table:"table",tbody:"tbody",td:"td",th:"th",thead:"thead",tr:"tr",ul:"ul",...(0,s.R)(),...e.components};return(0,t.jsxs)(t.Fragment,{children:[(0,t.jsx)(i.header,{children:(0,t.jsx)(i.h1,{id:"image-tools",children:"Image Tools"})}),"\n",(0,t.jsx)(i.h2,{id:"overview",children:"Overview"}),"\n",(0,t.jsx)(i.p,{children:"The image tools provide agents with capabilities for generating, editing, and analyzing images. These tools enable multimodal workflows where agents can create visual content, enhance existing images, and extract information from visual data."}),"\n",(0,t.jsx)(i.h3,{id:"available-tools",children:"Available Tools"}),"\n",(0,t.jsxs)(i.ul,{children:["\n",(0,t.jsxs)(i.li,{children:[(0,t.jsx)(i.strong,{children:"create_image_from_description"}),": Generate images from text descriptions"]}),"\n",(0,t.jsxs)(i.li,{children:[(0,t.jsx)(i.strong,{children:"describe_image"}),": Analyze and describe image contents"]}),"\n",(0,t.jsxs)(i.li,{children:[(0,t.jsx)(i.strong,{children:"edit_image_with_gemini"}),": Edit existing images using AI"]}),"\n",(0,t.jsxs)(i.li,{children:[(0,t.jsx)(i.strong,{children:"describe_audio"}),": Analyze audio content (cross-listed with audio tools)"]}),"\n"]}),"\n",(0,t.jsx)(i.h2,{id:"tool-reference",children:"Tool Reference"}),"\n",(0,t.jsx)(i.h3,{id:"create_image_from_description",children:"create_image_from_description"}),"\n",(0,t.jsx)(i.p,{children:"Generate images from textual descriptions using AI image generation models."}),"\n",(0,t.jsx)(i.h4,{id:"tool-configuration",children:"Tool Configuration"}),"\n",(0,t.jsx)(i.p,{children:"Configure the image generation service in your agent's tool configuration:"}),"\n",(0,t.jsx)(i.pre,{children:(0,t.jsx)(i.code,{className:"language-yaml",children:'tools:\n  - tool_type: builtin\n    tool_name: "create_image_from_description"\n    tool_config:\n      model: "imagen-4-ultra"       # Image generation model\n      api_key: "${API_KEY}"         # API authentication\n      api_base: "https://ENDPOINT"   # API endpoint\n'})}),"\n",(0,t.jsx)(i.h4,{id:"configuration-parameters",children:"Configuration Parameters"}),"\n",(0,t.jsxs)(i.table,{children:[(0,t.jsx)(i.thead,{children:(0,t.jsxs)(i.tr,{children:[(0,t.jsx)(i.th,{children:"Parameter"}),(0,t.jsx)(i.th,{children:"Type"}),(0,t.jsx)(i.th,{children:"Description"})]})}),(0,t.jsxs)(i.tbody,{children:[(0,t.jsxs)(i.tr,{children:[(0,t.jsx)(i.td,{children:(0,t.jsx)(i.code,{children:"model"})}),(0,t.jsx)(i.td,{children:"string"}),(0,t.jsx)(i.td,{children:"Image generation model identifier"})]}),(0,t.jsxs)(i.tr,{children:[(0,t.jsx)(i.td,{children:(0,t.jsx)(i.code,{children:"api_key"})}),(0,t.jsx)(i.td,{children:"string"}),(0,t.jsx)(i.td,{children:"API authentication key (use environment variables)"})]}),(0,t.jsxs)(i.tr,{children:[(0,t.jsx)(i.td,{children:(0,t.jsx)(i.code,{children:"api_base"})}),(0,t.jsx)(i.td,{children:"string"}),(0,t.jsx)(i.td,{children:"Base URL for the API endpoint"})]})]})]}),"\n",(0,t.jsx)(i.h4,{id:"output-format",children:"Output Format"}),"\n",(0,t.jsxs)(i.ul,{children:["\n",(0,t.jsxs)(i.li,{children:[(0,t.jsx)(i.strong,{children:"File Type"}),": PNG"]}),"\n"]}),"\n",(0,t.jsx)(i.h4,{id:"example-usage",children:"Example Usage"}),"\n",(0,t.jsx)(i.pre,{children:(0,t.jsx)(i.code,{className:"language-yaml",children:'# Agent configuration\napp_config:\n  agent_name: "DesignAgent"\n  instruction: "You create visual content based on user descriptions."\n\n  tools:\n    - tool_type: builtin\n      tool_name: "create_image_from_description"\n      tool_config:\n        model: "imagen-4-ultra"\n        api_key: "${OPENAI_API_KEY}"\n        api_base: "https://api.openai.com"\n'})}),"\n",(0,t.jsx)(i.hr,{}),"\n",(0,t.jsx)(i.h3,{id:"describe_image",children:"describe_image"}),"\n",(0,t.jsx)(i.p,{children:"Analyze and describe the contents of an image using vision-capable AI models."}),"\n",(0,t.jsx)(i.h4,{id:"tool-configuration-1",children:"Tool Configuration"}),"\n",(0,t.jsx)(i.pre,{children:(0,t.jsx)(i.code,{className:"language-yaml",children:'tools:\n  - tool_type: builtin\n    tool_name: "describe_image"\n    tool_config:\n      model: "gemini-2.5-flash"       # Vision model\n      api_key: "${API_KEY}"\n      api_base: "https://ENDPOINT"\n'})}),"\n",(0,t.jsx)(i.h4,{id:"supported-image-formats",children:"Supported Image Formats"}),"\n",(0,t.jsxs)(i.ul,{children:["\n",(0,t.jsxs)(i.li,{children:["PNG (",(0,t.jsx)(i.code,{children:".png"}),")"]}),"\n",(0,t.jsxs)(i.li,{children:["JPEG (",(0,t.jsx)(i.code,{children:".jpg"}),", ",(0,t.jsx)(i.code,{children:".jpeg"}),")"]}),"\n",(0,t.jsxs)(i.li,{children:["WebP (",(0,t.jsx)(i.code,{children:".webp"}),")"]}),"\n",(0,t.jsxs)(i.li,{children:["GIF (",(0,t.jsx)(i.code,{children:".gif"}),")"]}),"\n"]}),"\n",(0,t.jsx)(i.h3,{id:"edit_image_with_gemini",children:"edit_image_with_gemini"}),"\n",(0,t.jsx)(i.p,{children:"Edit existing images using Google Gemini's AI-powered image editing capabilities."}),"\n",(0,t.jsx)(i.h4,{id:"tool-configuration-2",children:"Tool Configuration"}),"\n",(0,t.jsx)(i.pre,{children:(0,t.jsx)(i.code,{className:"language-yaml",children:'tools:\n  - tool_type: builtin\n    tool_name: "edit_image_with_gemini"\n    tool_config:\n      gemini_api_key: "${GOOGLE_API_KEY}"\n      model: "gemini-2.5-flash-image"\n'})}),"\n",(0,t.jsxs)(i.p,{children:[(0,t.jsx)(i.strong,{children:"Required"}),": Google Gemini API key"]}),"\n",(0,t.jsx)(i.h4,{id:"configuration-parameters-1",children:"Configuration Parameters"}),"\n",(0,t.jsxs)(i.table,{children:[(0,t.jsx)(i.thead,{children:(0,t.jsxs)(i.tr,{children:[(0,t.jsx)(i.th,{children:"Parameter"}),(0,t.jsx)(i.th,{children:"Type"}),(0,t.jsx)(i.th,{children:"Description"})]})}),(0,t.jsxs)(i.tbody,{children:[(0,t.jsxs)(i.tr,{children:[(0,t.jsx)(i.td,{children:(0,t.jsx)(i.code,{children:"gemini_api_key"})}),(0,t.jsx)(i.td,{children:"string"}),(0,t.jsx)(i.td,{children:"Google Gemini API authentication key"})]}),(0,t.jsxs)(i.tr,{children:[(0,t.jsx)(i.td,{children:(0,t.jsx)(i.code,{children:"model"})}),(0,t.jsx)(i.td,{children:"string"}),(0,t.jsxs)(i.td,{children:["Gemini model name (default: ",(0,t.jsx)(i.code,{children:"gemini-2.0-flash-preview-image-generation"}),")"]})]})]})]}),"\n",(0,t.jsx)(i.h4,{id:"supported-input-formats",children:"Supported Input Formats"}),"\n",(0,t.jsxs)(i.ul,{children:["\n",(0,t.jsxs)(i.li,{children:["PNG (",(0,t.jsx)(i.code,{children:".png"}),")"]}),"\n",(0,t.jsxs)(i.li,{children:["JPEG (",(0,t.jsx)(i.code,{children:".jpg"}),", ",(0,t.jsx)(i.code,{children:".jpeg"}),")"]}),"\n",(0,t.jsxs)(i.li,{children:["WebP (",(0,t.jsx)(i.code,{children:".webp"}),")"]}),"\n",(0,t.jsxs)(i.li,{children:["GIF (",(0,t.jsx)(i.code,{children:".gif"}),")"]}),"\n"]}),"\n",(0,t.jsx)(i.h4,{id:"best-practices",children:"Best Practices"}),"\n",(0,t.jsxs)(i.ol,{children:["\n",(0,t.jsxs)(i.li,{children:["\n",(0,t.jsxs)(i.p,{children:[(0,t.jsx)(i.strong,{children:"Be Specific"}),": Detailed edit prompts yield better results"]}),"\n",(0,t.jsx)(i.pre,{children:(0,t.jsx)(i.code,{className:"language-yaml",children:'# Good\nedit_prompt: "Remove the person in the red shirt on the left side, fill the space with matching background"\n\n# Poor\nedit_prompt: "Remove person"\n'})}),"\n"]}),"\n",(0,t.jsxs)(i.li,{children:["\n",(0,t.jsxs)(i.p,{children:[(0,t.jsx)(i.strong,{children:"Preserve Quality"}),": Start with high-resolution source images"]}),"\n"]}),"\n",(0,t.jsxs)(i.li,{children:["\n",(0,t.jsxs)(i.p,{children:[(0,t.jsx)(i.strong,{children:"Iterative Editing"}),": Make incremental changes rather than complex multi-step edits in one prompt"]}),"\n"]}),"\n"]}),"\n",(0,t.jsx)(i.h3,{id:"tool-group-configuration",children:"Tool Group Configuration"}),"\n",(0,t.jsx)(i.p,{children:"Enable all image tools at once:"}),"\n",(0,t.jsx)(i.pre,{children:(0,t.jsx)(i.code,{className:"language-yaml",children:'tools:\n  - tool_type: builtin-group\n    group_name: "image"\n'})})]})}function h(e={}){const{wrapper:i}={...(0,s.R)(),...e.components};return i?(0,t.jsx)(i,{...e,children:(0,t.jsx)(c,{...e})}):c(e)}},8453:(e,i,n)=>{n.d(i,{R:()=>l,x:()=>r});var o=n(6540);const t={},s=o.createContext(t);function l(e){const i=o.useContext(s);return o.useMemo((function(){return"function"==typeof e?e(i):{...i,...e}}),[i,e])}function r(e){let i;return i=e.disableParentContext?"function"==typeof e.components?e.components(t):e.components||t:l(e.components),o.createElement(s.Provider,{value:i},e.children)}}}]);

solace_agent_mesh/assets/docs/assets/js/7e294c01.7c5f6906.js

@@ -0,0 +1 @@
+"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[3758],{3494:(e,n,t)=>{t.r(n),t.d(n,{assets:()=>c,contentTitle:()=>a,default:()=>m,frontMatter:()=>i,metadata:()=>r,toc:()=>l});const r=JSON.parse('{"id":"documentation/components/platform-service","title":"Platform Service","description":"The Platform Service is a backend microservice responsible for management operations in Solace Agent Mesh. It operates independently from other components, allowing it to scale separately.","source":"@site/docs/documentation/components/platform-service.md","sourceDirName":"documentation/components","slug":"/documentation/components/platform-service","permalink":"/solace-agent-mesh/docs/documentation/components/platform-service","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/components/platform-service.md","tags":[],"version":"current","sidebarPosition":265,"frontMatter":{"title":"Platform Service","sidebar_position":265},"sidebar":"docSidebar","previous":{"title":"Gateways","permalink":"/solace-agent-mesh/docs/documentation/components/gateways"},"next":{"title":"Plugins","permalink":"/solace-agent-mesh/docs/documentation/components/plugins"}}');var o=t(4848),s=t(8453);const i={title:"Platform Service",sidebar_position:265},a="Platform Service",c={},l=[{value:"What Does It Provide?",id:"what-does-it-provide",level:2},{value:"Running the Platform Service",id:"running-the-platform-service",level:2}];function d(e){const n={admonition:"admonition",code:"code",em:"em",h1:"h1",h2:"h2",header:"header",li:"li",p:"p",pre:"pre",strong:"strong",ul:"ul",...(0,s.R)(),...e.components};return(0,o.jsxs)(o.Fragment,{children:[(0,o.jsx)(n.header,{children:(0,o.jsx)(n.h1,{id:"platform-service",children:"Platform Service"})}),"\n",(0,o.jsx)(n.p,{children:"The Platform Service is a backend microservice responsible for management operations in Solace Agent Mesh. It operates independently from other components, allowing it to scale separately."}),"\n",(0,o.jsx)(n.h2,{id:"what-does-it-provide",children:"What Does It Provide?"}),"\n",(0,o.jsx)(n.p,{children:"The Platform Service provides the backend infrastructure for:"}),"\n",(0,o.jsxs)(n.ul,{children:["\n",(0,o.jsxs)(n.li,{children:[(0,o.jsx)(n.strong,{children:"Agent Builder"})," ",(0,o.jsx)(n.em,{children:"(Enterprise)"})," - Create, read, update, and delete AI agents"]}),"\n",(0,o.jsxs)(n.li,{children:[(0,o.jsx)(n.strong,{children:"Connector Management"})," ",(0,o.jsx)(n.em,{children:"(Enterprise)"})," - Manage database connectors that enable agents to query SQL databases"]}),"\n",(0,o.jsxs)(n.li,{children:[(0,o.jsx)(n.strong,{children:"Deployment Orchestration"})," ",(0,o.jsx)(n.em,{children:"(Enterprise)"})," - Deploy agents to runtime environments"]}),"\n",(0,o.jsxs)(n.li,{children:[(0,o.jsx)(n.strong,{children:"Deployer Monitoring"})," ",(0,o.jsx)(n.em,{children:"(Enterprise)"})," - Track health and availability of deployer services"]}),"\n"]}),"\n",(0,o.jsx)(n.h2,{id:"running-the-platform-service",children:"Running the Platform Service"}),"\n",(0,o.jsx)(n.p,{children:"A sample Platform Service configuration is automatically generated when you run:"}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-bash",children:"sam init --gui\n"})}),"\n",(0,o.jsxs)(n.p,{children:["When prompted to enable the WebUI Gateway, select ",(0,o.jsx)(n.strong,{children:"Yes"}),". This will generate ",(0,o.jsx)(n.code,{children:"configs/services/platform.yaml"})," with all necessary configuration."]}),"\n",(0,o.jsx)(n.p,{children:"Start the Platform Service using the SAM CLI:"}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-bash",children:"sam run configs/services/platform.yaml\n"})}),"\n",(0,o.jsxs)(n.p,{children:["The service runs on ",(0,o.jsx)(n.strong,{children:"port 8001"})," by default."]}),"\n",(0,o.jsx)(n.admonition,{type:"note",children:(0,o.jsx)(n.p,{children:"A Platform Service instance is only required when running the WebUI Gateway in combination with Agent Mesh Enterprise."})})]})}function m(e={}){const{wrapper:n}={...(0,s.R)(),...e.components};return n?(0,o.jsx)(n,{...e,children:(0,o.jsx)(d,{...e})}):d(e)}},8453:(e,n,t)=>{t.d(n,{R:()=>i,x:()=>a});var r=t(6540);const o={},s=r.createContext(o);function i(e){const n=r.useContext(s);return r.useMemo((function(){return"function"==typeof e?e(n):{...n,...e}}),[n,e])}function a(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(o):e.components||o:i(e.components),r.createElement(s.Provider,{value:n},e.children)}}}]);

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

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

solace_agent_mesh/assets/docs/assets/js/81a99df0.7ed65d45.js

@@ -0,0 +1 @@
+"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[1193],{8873:(e,n,i)=>{i.r(n),i.d(n,{assets:()=>d,contentTitle:()=>r,default:()=>h,frontMatter:()=>l,metadata:()=>o,toc:()=>a});const o=JSON.parse('{"id":"documentation/components/builtin-tools/builtin-tools","title":"Configuring Built-in Tools","description":"This guide provides instructions for enabling and configuring the built-in tools provided by Agent Mesh framework.","source":"@site/docs/documentation/components/builtin-tools/builtin-tools.md","sourceDirName":"documentation/components/builtin-tools","slug":"/documentation/components/builtin-tools/","permalink":"/solace-agent-mesh/docs/documentation/components/builtin-tools/","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/components/builtin-tools/builtin-tools.md","tags":[],"version":"current","sidebarPosition":60,"frontMatter":{"title":"Configuring Built-in Tools","sidebar_position":60},"sidebar":"docSidebar","previous":{"title":"Agent Mesh CLI","permalink":"/solace-agent-mesh/docs/documentation/components/cli"},"next":{"title":"Artifact Management Tools","permalink":"/solace-agent-mesh/docs/documentation/components/builtin-tools/artifact-management"}}');var s=i(4848),t=i(8453);const l={title:"Configuring Built-in Tools",sidebar_position:60},r="Configuring Built-in Tools",d={},a=[{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 Search",id:"web-search",level:3},{value:"Research",id:"research",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},{value:"Additional Tool Types",id:"additional-tool-types",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",table:"table",tbody:"tbody",td:"td",th:"th",thead:"thead",tr:"tr",ul:"ul",...(0,t.R)(),...e.components};return(0,s.jsxs)(s.Fragment,{children:[(0,s.jsx)(n.header,{children:(0,s.jsx)(n.h1,{id:"configuring-built-in-tools",children:"Configuring Built-in Tools"})}),"\n",(0,s.jsx)(n.p,{children:"This guide provides instructions for enabling and configuring the built-in tools provided by Agent Mesh framework."}),"\n",(0,s.jsx)(n.h2,{id:"overview",children:"Overview"}),"\n",(0,s.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,s.jsxs)(n.p,{children:["The Agent Mesh framework manages these tools through a central ",(0,s.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,s.jsx)(n.h2,{id:"configuration-methods",children:"Configuration Methods"}),"\n",(0,s.jsxs)(n.p,{children:["Tool configuration is managed within the ",(0,s.jsx)(n.code,{children:"tools"})," list in an agent's ",(0,s.jsx)(n.code,{children:"app_config"})," block in the corresponding YAML configuration file."]}),"\n",(0,s.jsx)(n.h3,{id:"method-1-enabling-tool-groups-recommended",children:"Method 1: Enabling Tool Groups (Recommended)"}),"\n",(0,s.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,s.jsx)(n.p,{children:(0,s.jsx)(n.strong,{children:"Example:"})}),"\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: builtin-group\n    group_name: "artifact_management"\n  - tool_type: builtin-group\n    group_name: "data_analysis"\n'})}),"\n",(0,s.jsx)(n.p,{children:(0,s.jsx)(n.strong,{children:"Configuration:"})}),"\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:"Field"}),(0,s.jsx)(n.th,{children:"Type"}),(0,s.jsx)(n.th,{children:"Required"}),(0,s.jsx)(n.th,{children:"Description"})]})}),(0,s.jsxs)(n.tbody,{children:[(0,s.jsxs)(n.tr,{children:[(0,s.jsx)(n.td,{children:(0,s.jsx)(n.code,{children:"tool_type"})}),(0,s.jsx)(n.td,{children:"string"}),(0,s.jsx)(n.td,{children:"Yes"}),(0,s.jsxs)(n.td,{children:["Must be ",(0,s.jsx)(n.code,{children:"builtin-group"})]})]}),(0,s.jsxs)(n.tr,{children:[(0,s.jsx)(n.td,{children:(0,s.jsx)(n.code,{children:"group_name"})}),(0,s.jsx)(n.td,{children:"string"}),(0,s.jsx)(n.td,{children:"Yes"}),(0,s.jsxs)(n.td,{children:["Tool group identifier. Available groups: ",(0,s.jsx)(n.code,{children:"artifact_management"}),", ",(0,s.jsx)(n.code,{children:"data_analysis"}),", ",(0,s.jsx)(n.code,{children:"web"}),", ",(0,s.jsx)(n.code,{children:"audio"}),", ",(0,s.jsx)(n.code,{children:"image"}),", ",(0,s.jsx)(n.code,{children:"general"})]})]}),(0,s.jsxs)(n.tr,{children:[(0,s.jsx)(n.td,{children:(0,s.jsx)(n.code,{children:"tool_config"})}),(0,s.jsx)(n.td,{children:"object"}),(0,s.jsx)(n.td,{children:"No"}),(0,s.jsx)(n.td,{children:"Group-specific configuration parameters"})]})]})]}),"\n",(0,s.jsx)(n.h3,{id:"method-2-enabling-individual-tools",children:"Method 2: Enabling Individual Tools"}),"\n",(0,s.jsx)(n.p,{children:"For more granular control over an agent's capabilities, specific tools can be enabled individually."}),"\n",(0,s.jsx)(n.p,{children:(0,s.jsx)(n.strong,{children:"Example:"})}),"\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: builtin\n    tool_name: "web_request"\n  - tool_type: builtin\n    tool_name: "time_delay"\n'})}),"\n",(0,s.jsx)(n.p,{children:(0,s.jsx)(n.strong,{children:"Configuration:"})}),"\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:"Field"}),(0,s.jsx)(n.th,{children:"Type"}),(0,s.jsx)(n.th,{children:"Required"}),(0,s.jsx)(n.th,{children:"Description"})]})}),(0,s.jsxs)(n.tbody,{children:[(0,s.jsxs)(n.tr,{children:[(0,s.jsx)(n.td,{children:(0,s.jsx)(n.code,{children:"tool_type"})}),(0,s.jsx)(n.td,{children:"string"}),(0,s.jsx)(n.td,{children:"Yes"}),(0,s.jsxs)(n.td,{children:["Must be ",(0,s.jsx)(n.code,{children:"builtin"})]})]}),(0,s.jsxs)(n.tr,{children:[(0,s.jsx)(n.td,{children:(0,s.jsx)(n.code,{children:"tool_name"})}),(0,s.jsx)(n.td,{children:"string"}),(0,s.jsx)(n.td,{children:"Yes"}),(0,s.jsx)(n.td,{children:"Specific tool name to enable"})]}),(0,s.jsxs)(n.tr,{children:[(0,s.jsx)(n.td,{children:(0,s.jsx)(n.code,{children:"tool_config"})}),(0,s.jsx)(n.td,{children:"object"}),(0,s.jsx)(n.td,{children:"No"}),(0,s.jsx)(n.td,{children:"Tool-specific configuration parameters"})]})]})]}),"\n",(0,s.jsx)(n.admonition,{title:"Note",type:"info",children:(0,s.jsx)(n.p,{children:"The Agent Mesh framework automatically handles duplicate tool registrations. If a tool group is enabled and a tool from that group is also listed individually, the tool is only loaded once."})}),"\n",(0,s.jsx)(n.h2,{id:"available-tool-groups-and-tools",children:"Available Tool Groups and Tools"}),"\n",(0,s.jsx)(n.p,{children:"The following sections detail the available tool groups and the individual tools they contain."}),"\n",(0,s.jsx)(n.h3,{id:"artifact-management",children:"Artifact Management"}),"\n",(0,s.jsxs)(n.p,{children:[(0,s.jsx)(n.strong,{children:"Group Name"}),": ",(0,s.jsx)(n.code,{children:"artifact_management"})]}),"\n",(0,s.jsxs)(n.p,{children:[(0,s.jsx)(n.strong,{children:"Description"}),": Tools for creating, loading, and managing file artifacts."]}),"\n",(0,s.jsxs)(n.p,{children:[(0,s.jsx)(n.strong,{children:"Individual Tools"}),":"]}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsx)(n.li,{children:(0,s.jsx)(n.code,{children:"append_to_artifact"})}),"\n",(0,s.jsx)(n.li,{children:(0,s.jsx)(n.code,{children:"list_artifacts"})}),"\n",(0,s.jsx)(n.li,{children:(0,s.jsx)(n.code,{children:"load_artifact"})}),"\n",(0,s.jsx)(n.li,{children:(0,s.jsx)(n.code,{children:"apply_embed_and_create_artifact"})}),"\n",(0,s.jsx)(n.li,{children:(0,s.jsx)(n.code,{children:"extract_content_from_artifact"})}),"\n"]}),"\n",(0,s.jsx)(n.admonition,{type:"info",children:(0,s.jsxs)(n.p,{children:["For a more in-depth guide on using artifact management tools, refer to the ",(0,s.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/components/builtin-tools/artifact-management",children:"Artifact Management"})," documentation."]})}),"\n",(0,s.jsx)(n.h3,{id:"data-analysis",children:"Data Analysis"}),"\n",(0,s.jsxs)(n.p,{children:[(0,s.jsx)(n.strong,{children:"Group Name"}),": ",(0,s.jsx)(n.code,{children:"data_analysis"})]}),"\n",(0,s.jsxs)(n.p,{children:[(0,s.jsx)(n.strong,{children:"Description"}),": Tools for querying, transforming, and visualizing data."]}),"\n",(0,s.jsxs)(n.p,{children:[(0,s.jsx)(n.strong,{children:"Individual Tools"}),":"]}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsx)(n.li,{children:(0,s.jsx)(n.code,{children:"query_data_with_sql"})}),"\n",(0,s.jsx)(n.li,{children:(0,s.jsx)(n.code,{children:"create_sqlite_db"})}),"\n",(0,s.jsx)(n.li,{children:(0,s.jsx)(n.code,{children:"transform_data_with_jq"})}),"\n",(0,s.jsx)(n.li,{children:(0,s.jsx)(n.code,{children:"create_chart_from_plotly_config"})}),"\n"]}),"\n",(0,s.jsx)(n.admonition,{type:"info",children:(0,s.jsxs)(n.p,{children:["For a more in-depth guide on using Data Analysis tools, refer to the ",(0,s.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/components/builtin-tools/data-analysis-tools",children:"Data Analysis Tools"})," documentation."]})}),"\n",(0,s.jsx)(n.h3,{id:"web-search",children:"Web Search"}),"\n",(0,s.jsxs)(n.p,{children:[(0,s.jsx)(n.strong,{children:"Group Name"}),": ",(0,s.jsx)(n.code,{children:"web_search"})]}),"\n",(0,s.jsxs)(n.p,{children:[(0,s.jsx)(n.strong,{children:"Description"}),": Tools for searching the web and retrieving current information."]}),"\n",(0,s.jsxs)(n.p,{children:[(0,s.jsx)(n.strong,{children:"Individual Tools"}),":"]}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsx)(n.li,{children:(0,s.jsx)(n.code,{children:"web_search_google"})}),"\n"]}),"\n",(0,s.jsx)(n.admonition,{type:"info",children:(0,s.jsxs)(n.p,{children:["For a more in-depth guide on using web search tools, refer to the ",(0,s.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/components/builtin-tools/research-tools",children:"Research Tools"})," documentation."]})}),"\n",(0,s.jsx)(n.h3,{id:"research",children:"Research"}),"\n",(0,s.jsxs)(n.p,{children:[(0,s.jsx)(n.strong,{children:"Group Name"}),": ",(0,s.jsx)(n.code,{children:"research"})]}),"\n",(0,s.jsxs)(n.p,{children:[(0,s.jsx)(n.strong,{children:"Description"}),": Advanced research tools for comprehensive information gathering."]}),"\n",(0,s.jsxs)(n.p,{children:[(0,s.jsx)(n.strong,{children:"Individual Tools"}),":"]}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsx)(n.li,{children:(0,s.jsx)(n.code,{children:"deep_research"})}),"\n"]}),"\n",(0,s.jsx)(n.admonition,{type:"info",children:(0,s.jsxs)(n.p,{children:["For a more in-depth guide on using the deep research tool, refer to the ",(0,s.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/components/builtin-tools/research-tools",children:"Research Tools"})," documentation."]})}),"\n",(0,s.jsx)(n.h3,{id:"web",children:"Web"}),"\n",(0,s.jsxs)(n.p,{children:[(0,s.jsx)(n.strong,{children:"Group Name"}),": ",(0,s.jsx)(n.code,{children:"web"})]}),"\n",(0,s.jsxs)(n.p,{children:[(0,s.jsx)(n.strong,{children:"Description"}),": Tools for interacting with web resources."]}),"\n",(0,s.jsxs)(n.p,{children:[(0,s.jsx)(n.strong,{children:"Individual Tools"}),":"]}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsx)(n.li,{children:(0,s.jsx)(n.code,{children:"web_request"})}),"\n"]}),"\n",(0,s.jsx)(n.h3,{id:"audio",children:"Audio"}),"\n",(0,s.jsxs)(n.p,{children:[(0,s.jsx)(n.strong,{children:"Group Name"}),": ",(0,s.jsx)(n.code,{children:"audio"})]}),"\n",(0,s.jsxs)(n.p,{children:[(0,s.jsx)(n.strong,{children:"Description"}),": Tools for generating and transcribing audio content."]}),"\n",(0,s.jsxs)(n.p,{children:[(0,s.jsx)(n.strong,{children:"Individual Tools"}),":"]}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsx)(n.li,{children:(0,s.jsx)(n.code,{children:"text_to_speech"})}),"\n",(0,s.jsx)(n.li,{children:(0,s.jsx)(n.code,{children:"multi_speaker_text_to_speech"})}),"\n",(0,s.jsx)(n.li,{children:(0,s.jsx)(n.code,{children:"transcribe_audio"})}),"\n"]}),"\n",(0,s.jsx)(n.admonition,{type:"info",children:(0,s.jsxs)(n.p,{children:["For a more in-depth guide on using audio tools, refer to the ",(0,s.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/components/builtin-tools/audio-tools",children:"Audio Tools"})," documentation."]})}),"\n",(0,s.jsx)(n.h3,{id:"image",children:"Image"}),"\n",(0,s.jsxs)(n.p,{children:[(0,s.jsx)(n.strong,{children:"Group Name"}),": ",(0,s.jsx)(n.code,{children:"image"})]}),"\n",(0,s.jsxs)(n.p,{children:[(0,s.jsx)(n.strong,{children:"Description"}),": Tools for generating and analyzing images."]}),"\n",(0,s.jsxs)(n.p,{children:[(0,s.jsx)(n.strong,{children:"Individual Tools"}),":"]}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsx)(n.li,{children:(0,s.jsx)(n.code,{children:"create_image_from_description"})}),"\n",(0,s.jsx)(n.li,{children:(0,s.jsx)(n.code,{children:"describe_image"})}),"\n",(0,s.jsx)(n.li,{children:(0,s.jsx)(n.code,{children:"edit_image_with_gemini"})}),"\n",(0,s.jsx)(n.li,{children:(0,s.jsx)(n.code,{children:"describe_audio"})}),"\n"]}),"\n",(0,s.jsx)(n.h3,{id:"general",children:"General"}),"\n",(0,s.jsxs)(n.p,{children:[(0,s.jsx)(n.strong,{children:"Group Name"}),": ",(0,s.jsx)(n.code,{children:"general"})]}),"\n",(0,s.jsxs)(n.p,{children:[(0,s.jsx)(n.strong,{children:"Description"}),": General-purpose utility tools."]}),"\n",(0,s.jsxs)(n.p,{children:[(0,s.jsx)(n.strong,{children:"Individual Tools"}),":"]}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsx)(n.li,{children:(0,s.jsx)(n.code,{children:"convert_file_to_markdown"})}),"\n",(0,s.jsx)(n.li,{children:(0,s.jsx)(n.code,{children:"mermaid_diagram_generator"})}),"\n"]}),"\n",(0,s.jsx)(n.h2,{id:"complete-configuration-example",children:"Complete Configuration Example"}),"\n",(0,s.jsxs)(n.p,{children:["Below is a comprehensive example of a well-formed ",(0,s.jsx)(n.code,{children:"app_config"})," that uses the unified method to enable a mix of tool groups and individual tools."]}),"\n",(0,s.jsx)(n.pre,{children:(0,s.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  # ... other service configurations (session_service, artifact_service, etc.)\n'})}),"\n",(0,s.jsx)(n.h2,{id:"additional-tool-types",children:"Additional Tool Types"}),"\n",(0,s.jsx)(n.p,{children:"For extending agent capabilities beyond built-in tools:"}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Custom Python Tools"}),": See ",(0,s.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/developing/creating-python-tools",children:"Creating Python Tools"})," for creating custom tools with your own business logic"]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"MCP Integration"}),": See ",(0,s.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/developing/tutorials/mcp-integration",children:"MCP Integration Tutorial"})," for connecting to Model Context Protocol servers"]}),"\n"]})]})}function h(e={}){const{wrapper:n}={...(0,t.R)(),...e.components};return n?(0,s.jsx)(n,{...e,children:(0,s.jsx)(c,{...e})}):c(e)}},8453:(e,n,i)=>{i.d(n,{R:()=>l,x:()=>r});var o=i(6540);const s={},t=o.createContext(s);function l(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(s):e.components||s:l(e.components),o.createElement(t.Provider,{value:n},e.children)}}}]);

solace_agent_mesh/assets/docs/assets/js/82fbfb93.161823a5.js

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

solace_agent_mesh/assets/docs/assets/js/8b032486.91a91afc.js

@@ -0,0 +1 @@
+"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[8498],{47:(e,n,t)=>{t.r(n),t.d(n,{assets:()=>r,contentTitle:()=>d,default:()=>h,frontMatter:()=>l,metadata:()=>s,toc:()=>c});const s=JSON.parse('{"id":"documentation/installing-and-configuring/user-feedback","title":"User Feedback","description":"User Feedback allows users to provide ratings and comments on AI agent responses through the Web UI. This feature enables quality monitoring, model improvement through evaluation datasets, and user satisfaction tracking. Feedback can be stored in a database for analytics and optionally published to Solace message broker topics for integration with external systems.","source":"@site/docs/documentation/installing-and-configuring/user-feedback.md","sourceDirName":"documentation/installing-and-configuring","slug":"/documentation/installing-and-configuring/user-feedback","permalink":"/solace-agent-mesh/docs/documentation/installing-and-configuring/user-feedback","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/installing-and-configuring/user-feedback.md","tags":[],"version":"current","sidebarPosition":345,"frontMatter":{"title":"User Feedback","sidebar_position":345},"sidebar":"docSidebar","previous":{"title":"Configuring LLMs","permalink":"/solace-agent-mesh/docs/documentation/installing-and-configuring/large_language_models"},"next":{"title":"Session Storage","permalink":"/solace-agent-mesh/docs/documentation/installing-and-configuring/session-storage"}}');var i=t(4848),a=t(8453);const l={title:"User Feedback",sidebar_position:345},d=void 0,r={},c=[{value:"Prerequisites",id:"prerequisites",level:2},{value:"Enabling User Feedback",id:"enabling-user-feedback",level:2},{value:"Configuring Feedback Publishing",id:"configuring-feedback-publishing",level:2},{value:"Configuration Example",id:"configuration-example",level:3},{value:"Task Information Modes",id:"task-information-modes",level:3},{value:"Using User Feedback",id:"using-user-feedback",level:2},{value:"Retrieving Feedback",id:"retrieving-feedback",level:2},{value:"Query Parameters",id:"query-parameters",level:3},{value:"Security and Access Control",id:"security-and-access-control",level:3},{value:"Example API Calls",id:"example-api-calls",level:3},{value:"Publishing Feedback Events",id:"publishing-feedback-events",level:2},{value:"Event Payload Examples",id:"event-payload-examples",level:3},{value:"Integrating with External Systems",id:"integrating-with-external-systems",level:3},{value:"Data Retention",id:"data-retention",level:2}];function o(e){const n={a:"a",admonition:"admonition",code:"code",h2:"h2",h3:"h3",li:"li",p:"p",pre:"pre",strong:"strong",table:"table",tbody:"tbody",td:"td",th:"th",thead:"thead",tr:"tr",ul:"ul",...(0,a.R)(),...e.components};return(0,i.jsxs)(i.Fragment,{children:[(0,i.jsx)(n.p,{children:"User Feedback allows users to provide ratings and comments on AI agent responses through the Web UI. This feature enables quality monitoring, model improvement through evaluation datasets, and user satisfaction tracking. Feedback can be stored in a database for analytics and optionally published to Solace message broker topics for integration with external systems."}),"\n",(0,i.jsx)(n.h2,{id:"prerequisites",children:"Prerequisites"}),"\n",(0,i.jsx)(n.p,{children:"User Feedback requires session persistence to be enabled. Session persistence ensures that feedback submissions can be reliably stored and associated with specific user interactions and tasks."}),"\n",(0,i.jsxs)(n.p,{children:["To enable session persistence, configure the session service with a database backend in your ",(0,i.jsx)(n.code,{children:"shared_config.yaml"})," file:"]}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-yaml",children:'services:\n  session_service:\n    type: "sql"\n    database_url: "${WEB_UI_GATEWAY_DATABASE_URL, sqlite:///webui-gateway.db}"\n    default_behavior: "PERSISTENT"\n'})}),"\n",(0,i.jsxs)(n.p,{children:["For more information about session service configuration and database setup options, see ",(0,i.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/installing-and-configuring/configurations#session-service",children:"Session Service"}),"."]}),"\n",(0,i.jsx)(n.admonition,{type:"info",children:(0,i.jsx)(n.p,{children:"If session persistence is not enabled, the system automatically disables the feedback collection feature to prevent data loss. Feedback buttons will not appear in the Web UI when persistence is disabled."})}),"\n",(0,i.jsx)(n.h2,{id:"enabling-user-feedback",children:"Enabling User Feedback"}),"\n",(0,i.jsxs)(n.p,{children:["To enable feedback collection in the Web UI, set the ",(0,i.jsx)(n.code,{children:"frontend_collect_feedback"})," parameter to ",(0,i.jsx)(n.code,{children:"true"})," in your gateway configuration file:"]}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-yaml",children:'apps:\n  - name: webui_example_app\n    app_config:\n      # Enable feedback collection in the UI\n      frontend_collect_feedback: true\n\n      # Session persistence required (see Prerequisites)\n      session_service:\n        type: "sql"\n        database_url: "${WEB_UI_GATEWAY_DATABASE_URL, sqlite:///webui-gateway.db}"\n        default_behavior: "PERSISTENT"\n'})}),"\n",(0,i.jsx)(n.p,{children:"When enabled, thumbs up and thumbs down buttons appear after completed agent responses in the Web UI. Users can click these buttons to submit feedback, with an optional text comment providing additional context."}),"\n",(0,i.jsx)(n.h2,{id:"configuring-feedback-publishing",children:"Configuring Feedback Publishing"}),"\n",(0,i.jsx)(n.p,{children:"Feedback can be published to Solace message broker topics for integration with external analytics systems, evaluation pipelines, or monitoring dashboards. This publishing capability is optional and can be configured independently of basic feedback collection."}),"\n",(0,i.jsx)(n.p,{children:"The following table describes the feedback publishing configuration parameters:"}),"\n",(0,i.jsxs)(n.table,{children:[(0,i.jsx)(n.thead,{children:(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.th,{style:{textAlign:"left"},children:"Parameter"}),(0,i.jsx)(n.th,{style:{textAlign:"left"},children:"Type"}),(0,i.jsx)(n.th,{style:{textAlign:"left"},children:"Description"}),(0,i.jsx)(n.th,{style:{textAlign:"left"},children:"Default"})]})}),(0,i.jsxs)(n.tbody,{children:[(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.td,{style:{textAlign:"left"},children:(0,i.jsx)(n.code,{children:"enabled"})}),(0,i.jsx)(n.td,{style:{textAlign:"left"},children:(0,i.jsx)(n.code,{children:"boolean"})}),(0,i.jsx)(n.td,{style:{textAlign:"left"},children:"Enable or disable feedback event publishing."}),(0,i.jsx)(n.td,{style:{textAlign:"left"},children:(0,i.jsx)(n.code,{children:"false"})})]}),(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.td,{style:{textAlign:"left"},children:(0,i.jsx)(n.code,{children:"topic"})}),(0,i.jsx)(n.td,{style:{textAlign:"left"},children:(0,i.jsx)(n.code,{children:"string"})}),(0,i.jsx)(n.td,{style:{textAlign:"left"},children:"The topic name for publishing feedback events. Supports environment variable substitution."}),(0,i.jsx)(n.td,{style:{textAlign:"left"},children:(0,i.jsx)(n.code,{children:"sam/feedback/v1"})})]}),(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.td,{style:{textAlign:"left"},children:(0,i.jsx)(n.code,{children:"include_task_info"})}),(0,i.jsx)(n.td,{style:{textAlign:"left"},children:(0,i.jsx)(n.code,{children:"string"})}),(0,i.jsxs)(n.td,{style:{textAlign:"left"},children:["Controls what task information is included in published events. Options are ",(0,i.jsx)(n.code,{children:"none"}),", ",(0,i.jsx)(n.code,{children:"summary"}),", or ",(0,i.jsx)(n.code,{children:"stim"}),"."]}),(0,i.jsx)(n.td,{style:{textAlign:"left"},children:(0,i.jsx)(n.code,{children:"none"})})]}),(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.td,{style:{textAlign:"left"},children:(0,i.jsx)(n.code,{children:"max_payload_size_bytes"})}),(0,i.jsx)(n.td,{style:{textAlign:"left"},children:(0,i.jsx)(n.code,{children:"integer"})}),(0,i.jsxs)(n.td,{style:{textAlign:"left"},children:["Maximum payload size in bytes. If the payload exceeds this limit when using ",(0,i.jsx)(n.code,{children:"stim"})," mode, the system falls back to ",(0,i.jsx)(n.code,{children:"summary"})," mode."]}),(0,i.jsx)(n.td,{style:{textAlign:"left"},children:(0,i.jsx)(n.code,{children:"9000000"})})]})]})]}),"\n",(0,i.jsx)(n.h3,{id:"configuration-example",children:"Configuration Example"}),"\n",(0,i.jsx)(n.p,{children:"The following example shows how to configure feedback publishing in your gateway configuration file:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-yaml",children:'apps:\n  - name: webui_example_app\n    app_config:\n      frontend_collect_feedback: true\n\n      feedback_publishing:\n        enabled: true\n        topic: "${NAMESPACE}/sam/feedback/v1"\n        include_task_info: "summary"\n        max_payload_size_bytes: 9000000\n'})}),"\n",(0,i.jsx)(n.h3,{id:"task-information-modes",children:"Task Information Modes"}),"\n",(0,i.jsxs)(n.p,{children:["The ",(0,i.jsx)(n.code,{children:"include_task_info"})," parameter determines what task details are included with each feedback event:"]}),"\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.strong,{children:(0,i.jsx)(n.code,{children:"none"})})," - Only feedback data (task_id, session_id, rating, comment, user_id) is published. Use this mode when you want minimal payload size and don't need task context in the consuming system."]}),"\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.strong,{children:(0,i.jsx)(n.code,{children:"summary"})})," - Includes basic task information such as task_id, user_id, start_time, end_time, status, and initial_request_text. Use this mode for lightweight analytics and monitoring where you need basic task context without full execution details."]}),"\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.strong,{children:(0,i.jsx)(n.code,{children:"stim"})})," - Includes complete task execution history with all events, tool calls, and agent interactions. This mode provides full traceability for debugging and detailed analysis. If the payload exceeds ",(0,i.jsx)(n.code,{children:"max_payload_size_bytes"}),", the system automatically falls back to ",(0,i.jsx)(n.code,{children:"summary"})," mode and logs the fallback decision."]}),"\n",(0,i.jsx)(n.h2,{id:"using-user-feedback",children:"Using User Feedback"}),"\n",(0,i.jsx)(n.p,{children:"Users submit feedback through the Web UI by clicking thumbs up or thumbs down buttons that appear after completed agent responses. A modal dialog allows users to optionally add text comments explaining their rating. Each task can receive one feedback submission, and buttons are disabled after submission to prevent duplicate feedback."}),"\n",(0,i.jsxs)(n.p,{children:["Feedback is stored in the ",(0,i.jsx)(n.code,{children:"feedback"})," database table with the following information:"]}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsx)(n.li,{children:"Unique feedback ID"}),"\n",(0,i.jsx)(n.li,{children:"Associated task ID and session ID"}),"\n",(0,i.jsx)(n.li,{children:"User ID of the person who submitted the feedback"}),"\n",(0,i.jsx)(n.li,{children:"Rating type (up or down)"}),"\n",(0,i.jsx)(n.li,{children:"Optional text comment"}),"\n",(0,i.jsx)(n.li,{children:"Creation timestamp"}),"\n"]}),"\n",(0,i.jsx)(n.p,{children:"The feedback is also stored in the task metadata, allowing quick access to feedback status when retrieving task information through other APIs."}),"\n",(0,i.jsx)(n.h2,{id:"retrieving-feedback",children:"Retrieving Feedback"}),"\n",(0,i.jsxs)(n.p,{children:["You can retrieve feedback programmatically using the ",(0,i.jsx)(n.code,{children:"GET /api/v1/feedback"})," endpoint. This endpoint supports flexible filtering and pagination to help you analyze feedback data."]}),"\n",(0,i.jsx)(n.h3,{id:"query-parameters",children:"Query Parameters"}),"\n",(0,i.jsx)(n.p,{children:"The following table describes the available query parameters:"}),"\n",(0,i.jsxs)(n.table,{children:[(0,i.jsx)(n.thead,{children:(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.th,{style:{textAlign:"left"},children:"Parameter"}),(0,i.jsx)(n.th,{style:{textAlign:"left"},children:"Type"}),(0,i.jsx)(n.th,{style:{textAlign:"left"},children:"Description"}),(0,i.jsx)(n.th,{style:{textAlign:"left"},children:"Default"})]})}),(0,i.jsxs)(n.tbody,{children:[(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.td,{style:{textAlign:"left"},children:(0,i.jsx)(n.code,{children:"start_date"})}),(0,i.jsx)(n.td,{style:{textAlign:"left"},children:(0,i.jsx)(n.code,{children:"string"})}),(0,i.jsx)(n.td,{style:{textAlign:"left"},children:"Filter feedback created after this date (ISO 8601 format)."}),(0,i.jsx)(n.td,{style:{textAlign:"left"},children:"(none)"})]}),(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.td,{style:{textAlign:"left"},children:(0,i.jsx)(n.code,{children:"end_date"})}),(0,i.jsx)(n.td,{style:{textAlign:"left"},children:(0,i.jsx)(n.code,{children:"string"})}),(0,i.jsx)(n.td,{style:{textAlign:"left"},children:"Filter feedback created before this date (ISO 8601 format)."}),(0,i.jsx)(n.td,{style:{textAlign:"left"},children:"(none)"})]}),(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.td,{style:{textAlign:"left"},children:(0,i.jsx)(n.code,{children:"task_id"})}),(0,i.jsx)(n.td,{style:{textAlign:"left"},children:(0,i.jsx)(n.code,{children:"string"})}),(0,i.jsx)(n.td,{style:{textAlign:"left"},children:"Filter by specific task ID."}),(0,i.jsx)(n.td,{style:{textAlign:"left"},children:"(none)"})]}),(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.td,{style:{textAlign:"left"},children:(0,i.jsx)(n.code,{children:"session_id"})}),(0,i.jsx)(n.td,{style:{textAlign:"left"},children:(0,i.jsx)(n.code,{children:"string"})}),(0,i.jsx)(n.td,{style:{textAlign:"left"},children:"Filter by specific session ID."}),(0,i.jsx)(n.td,{style:{textAlign:"left"},children:"(none)"})]}),(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.td,{style:{textAlign:"left"},children:(0,i.jsx)(n.code,{children:"rating"})}),(0,i.jsx)(n.td,{style:{textAlign:"left"},children:(0,i.jsx)(n.code,{children:"string"})}),(0,i.jsxs)(n.td,{style:{textAlign:"left"},children:["Filter by rating type (",(0,i.jsx)(n.code,{children:"up"})," or ",(0,i.jsx)(n.code,{children:"down"}),")."]}),(0,i.jsx)(n.td,{style:{textAlign:"left"},children:"(none)"})]}),(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.td,{style:{textAlign:"left"},children:(0,i.jsx)(n.code,{children:"page"})}),(0,i.jsx)(n.td,{style:{textAlign:"left"},children:(0,i.jsx)(n.code,{children:"integer"})}),(0,i.jsx)(n.td,{style:{textAlign:"left"},children:"Page number for pagination."}),(0,i.jsx)(n.td,{style:{textAlign:"left"},children:(0,i.jsx)(n.code,{children:"1"})})]}),(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.td,{style:{textAlign:"left"},children:(0,i.jsx)(n.code,{children:"page_size"})}),(0,i.jsx)(n.td,{style:{textAlign:"left"},children:(0,i.jsx)(n.code,{children:"integer"})}),(0,i.jsx)(n.td,{style:{textAlign:"left"},children:"Number of results per page."}),(0,i.jsx)(n.td,{style:{textAlign:"left"},children:(0,i.jsx)(n.code,{children:"20"})})]}),(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.td,{style:{textAlign:"left"},children:(0,i.jsx)(n.code,{children:"query_user_id"})}),(0,i.jsx)(n.td,{style:{textAlign:"left"},children:(0,i.jsx)(n.code,{children:"string"})}),(0,i.jsxs)(n.td,{style:{textAlign:"left"},children:["(Admin only) Query feedback for a specific user. Requires ",(0,i.jsx)(n.code,{children:"feedback:read:all"})," scope."]}),(0,i.jsx)(n.td,{style:{textAlign:"left"},children:"(none)"})]})]})]}),"\n",(0,i.jsx)(n.p,{children:"All query parameters are optional and can be combined to create specific filters. Results are returned in descending order by creation time (most recent first)."}),"\n",(0,i.jsx)(n.h3,{id:"security-and-access-control",children:"Security and Access Control"}),"\n",(0,i.jsxs)(n.p,{children:["Regular users can only retrieve their own feedback. Users with the ",(0,i.jsx)(n.code,{children:"feedback:read:all"})," scope can retrieve feedback from any user or all users. When filtering by ",(0,i.jsx)(n.code,{children:"task_id"}),", the system verifies that the user owns the task or has admin permissions before returning results."]}),"\n",(0,i.jsx)(n.h3,{id:"example-api-calls",children:"Example API Calls"}),"\n",(0,i.jsx)(n.p,{children:"The following examples demonstrate common feedback retrieval scenarios:"}),"\n",(0,i.jsx)(n.p,{children:(0,i.jsx)(n.strong,{children:"Get your own feedback from the last week:"})}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:'curl "http://localhost:8000/api/v1/feedback?start_date=2025-10-22T00:00:00&end_date=2025-10-29T23:59:59"\n'})}),"\n",(0,i.jsx)(n.p,{children:(0,i.jsx)(n.strong,{children:"Get all negative feedback for a specific task:"})}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:'curl "http://localhost:8000/api/v1/feedback?task_id=task-abc123&rating=down"\n'})}),"\n",(0,i.jsx)(n.p,{children:(0,i.jsx)(n.strong,{children:"Get feedback from a specific session:"})}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:'curl "http://localhost:8000/api/v1/feedback?session_id=web-session-xyz"\n'})}),"\n",(0,i.jsx)(n.p,{children:(0,i.jsx)(n.strong,{children:"Admin: Get all users' feedback from October:"})}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:'curl "http://localhost:8000/api/v1/feedback?start_date=2025-10-01&end_date=2025-10-31"\n'})}),"\n",(0,i.jsx)(n.p,{children:(0,i.jsx)(n.strong,{children:"Get the first 50 results with pagination:"})}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:'curl "http://localhost:8000/api/v1/feedback?page=1&page_size=50"\n'})}),"\n",(0,i.jsx)(n.h2,{id:"publishing-feedback-events",children:"Publishing Feedback Events"}),"\n",(0,i.jsxs)(n.p,{children:["When feedback publishing is enabled, the system publishes feedback events to the configured Solace topic. The payload structure varies based on the ",(0,i.jsx)(n.code,{children:"include_task_info"})," setting."]}),"\n",(0,i.jsx)(n.h3,{id:"event-payload-examples",children:"Event Payload Examples"}),"\n",(0,i.jsx)(n.p,{children:(0,i.jsxs)(n.strong,{children:["Mode: ",(0,i.jsx)(n.code,{children:"none"})]})}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-json",children:'{\n  "feedback": {\n    "task_id": "task-abc123",\n    "session_id": "web-session-xyz",\n    "feedback_type": "up",\n    "feedback_text": "Great response!",\n    "user_id": "user123"\n  }\n}\n'})}),"\n",(0,i.jsx)(n.p,{children:(0,i.jsxs)(n.strong,{children:["Mode: ",(0,i.jsx)(n.code,{children:"summary"})]})}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-json",children:'{\n  "feedback": {\n    "task_id": "task-abc123",\n    "session_id": "web-session-xyz",\n    "feedback_type": "up",\n    "feedback_text": "Great response!",\n    "user_id": "user123"\n  },\n  "task_summary": {\n    "id": "task-abc123",\n    "user_id": "user123",\n    "start_time": 1730217600000,\n    "end_time": 1730217650000,\n    "status": "completed",\n    "initial_request_text": "Help me analyze this data"\n  }\n}\n'})}),"\n",(0,i.jsx)(n.p,{children:(0,i.jsxs)(n.strong,{children:["Mode: ",(0,i.jsx)(n.code,{children:"stim"})]})}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-json",children:'{\n  "feedback": {\n    "task_id": "task-abc123",\n    "session_id": "web-session-xyz",\n    "feedback_type": "up",\n    "feedback_text": "Great response!",\n    "user_id": "user123"\n  },\n  "task_stim_data": {\n    "invocation_details": {\n      "log_file_version": "2.0",\n      "task_id": "task-abc123",\n      "user_id": "user123",\n      "start_time": 1730217600000,\n      "end_time": 1730217650000,\n      "status": "completed",\n      "initial_request_text": "Help me analyze this data"\n    },\n    "invocation_flow": [\n      {\n        "id": "event-1",\n        "created_time": 1730217600000,\n        "topic": "namespace/agent/request",\n        "direction": "request",\n        "payload": { "message": "..." }\n      },\n      {\n        "id": "event-2",\n        "created_time": 1730217625000,\n        "topic": "namespace/agent/response",\n        "direction": "response",\n        "payload": { "result": "..." }\n      }\n    ]\n  }\n}\n'})}),"\n",(0,i.jsx)(n.h3,{id:"integrating-with-external-systems",children:"Integrating with External Systems"}),"\n",(0,i.jsx)(n.p,{children:"External systems can subscribe to the feedback topic to consume feedback events in real-time. This approach enables integration with various downstream systems such as analytics platforms, evaluation pipelines, and monitoring dashboards."}),"\n",(0,i.jsxs)(n.p,{children:["The topic naming pattern follows the format ",(0,i.jsx)(n.code,{children:"{namespace}/sam/feedback/v1"}),", where ",(0,i.jsx)(n.code,{children:"{namespace}"})," is your configured namespace. You can customize this pattern using the ",(0,i.jsx)(n.code,{children:"topic"})," configuration parameter and environment variable substitution."]}),"\n",(0,i.jsx)(n.admonition,{type:"tip",children:(0,i.jsxs)(n.p,{children:["Use ",(0,i.jsx)(n.code,{children:"summary"})," mode for most analytics and monitoring use cases, as it provides essential task context without the overhead of full execution traces. Reserve ",(0,i.jsx)(n.code,{children:"stim"})," mode for detailed debugging and analysis scenarios where complete execution history is required."]})}),"\n",(0,i.jsx)(n.h2,{id:"data-retention",children:"Data Retention"}),"\n",(0,i.jsx)(n.p,{children:"Feedback records are subject to the data retention policies configured in your gateway. The data retention service automatically cleans up old feedback records based on the configured retention period, preventing unbounded database growth."}),"\n",(0,i.jsxs)(n.p,{children:["To configure data retention for feedback, set the ",(0,i.jsx)(n.code,{children:"feedback_retention_days"})," parameter in your gateway configuration:"]}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-yaml",children:"apps:\n  - name: webui_example_app\n    app_config:\n      data_retention:\n        enabled: true\n        feedback_retention_days: 90\n        cleanup_interval_hours: 24\n        batch_size: 1000\n"})}),"\n",(0,i.jsxs)(n.p,{children:["For detailed information about data retention configuration and cleanup policies, see the ",(0,i.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/installing-and-configuring/configurations",children:"Data Retention documentation"}),"."]})]})}function h(e={}){const{wrapper:n}={...(0,a.R)(),...e.components};return n?(0,i.jsx)(n,{...e,children:(0,i.jsx)(o,{...e})}):o(e)}},8453:(e,n,t)=>{t.d(n,{R:()=>l,x:()=>d});var s=t(6540);const i={},a=s.createContext(i);function l(e){const n=s.useContext(a);return s.useMemo((function(){return"function"==typeof e?e(n):{...n,...e}}),[n,e])}function d(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(i):e.components||i:l(e.components),s.createElement(a.Provider,{value:n},e.children)}}}]);