solace-agent-mesh 1.5.0__py3-none-any.whl → 1.6.0__py3-none-any.whl

solace_agent_mesh/assets/docs/assets/js/de915948.27d6b065.js

@@ -0,0 +1 @@
+"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[6426],{1007:(e,n,i)=>{i.r(n),i.d(n,{assets:()=>c,contentTitle:()=>a,default:()=>h,frontMatter:()=>o,metadata:()=>t,toc:()=>l});const t=JSON.parse('{"id":"documentation/installing-and-configuring/large_language_models","title":"Configuring LLMs","description":"Large Language Models (LLMs) serve as the intelligence foundation for Agent Mesh, powering everything from natural language understanding to complex reasoning and decision-making. The system provides flexible configuration options that allow you to connect with various LLM providers through a unified interface, making it easy to switch between providers or use multiple models for different purposes.","source":"@site/docs/documentation/installing-and-configuring/large_language_models.md","sourceDirName":"documentation/installing-and-configuring","slug":"/documentation/installing-and-configuring/large_language_models","permalink":"/solace-agent-mesh/docs/documentation/installing-and-configuring/large_language_models","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/installing-and-configuring/large_language_models.md","tags":[],"version":"current","sidebarPosition":340,"frontMatter":{"title":"Configuring LLMs","sidebar_position":340},"sidebar":"docSidebar","previous":{"title":"Configuring Agent Mesh","permalink":"/solace-agent-mesh/docs/documentation/installing-and-configuring/configurations"},"next":{"title":"Developing with Agent Mesh","permalink":"/solace-agent-mesh/docs/documentation/developing/"}}');var r=i(4848),s=i(8453);const o={title:"Configuring LLMs",sidebar_position:340},a=void 0,c={},l=[{value:"Understanding LiteLLM Integration",id:"understanding-litellm-integration",level:2},{value:"Provider-Specific Configurations",id:"provider-specific-configurations",level:2},{value:"OpenAI",id:"openai",level:3},{value:"Azure OpenAI",id:"azure-openai",level:3},{value:"Google Vertex AI",id:"google-vertex-ai",level:3},{value:"Amazon Bedrock",id:"amazon-bedrock",level:3},{value:"Anthropic",id:"anthropic",level:3},{value:"Additional Providers",id:"additional-providers",level:3},{value:"Prompt Caching",id:"prompt-caching",level:2},{value:"How Prompt Caching Works",id:"how-prompt-caching-works",level:3},{value:"Supported Providers",id:"supported-providers",level:3},{value:"Cache Strategy Configuration",id:"cache-strategy-configuration",level:3},{value:"Configuration Examples",id:"configuration-examples",level:3},{value:"Cache Strategy Selection Guidelines",id:"cache-strategy-selection-guidelines",level:3},{value:"What Gets Cached",id:"what-gets-cached",level:3},{value:"Cache Invalidation",id:"cache-invalidation",level:3},{value:"OAuth 2.0 Authentication",id:"oauth-20-authentication",level:2},{value:"Overview",id:"overview",level:3},{value:"Configuration Parameters",id:"configuration-parameters",level:3},{value:"Environment Variables",id:"environment-variables",level:3},{value:"YAML Configuration",id:"yaml-configuration",level:3},{value:"Error Handling and Fallback",id:"error-handling-and-fallback",level:3},{value:"Security Considerations",id:"security-considerations",level:3},{value:"Troubleshooting OAuth Issues",id:"troubleshooting-oauth-issues",level:3},{value:"Supported Providers",id:"supported-providers-1",level:3},{value:"Security and SSL/TLS Configuration",id:"security-and-ssltls-configuration",level:2},{value:"Example Environment Configuration",id:"example-environment-configuration",level:3}];function d(e){const n={a:"a",code:"code",h2:"h2",h3:"h3",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,r.jsxs)(r.Fragment,{children:[(0,r.jsx)(n.p,{children:"Large Language Models (LLMs) serve as the intelligence foundation for Agent Mesh, powering everything from natural language understanding to complex reasoning and decision-making. The system provides flexible configuration options that allow you to connect with various LLM providers through a unified interface, making it easy to switch between providers or use multiple models for different purposes."}),"\n",(0,r.jsxs)(n.p,{children:["You can configure LLM settings in two locations within your Agent Mesh deployment. The ",(0,r.jsx)(n.code,{children:"apps.app_config.model"})," field allows you to specify model settings for individual agents or gateways, providing fine-grained control over which models specific components use. Alternatively, you can define models globally in the ",(0,r.jsx)(n.code,{children:"shared_config.yaml"})," file under the ",(0,r.jsx)(n.code,{children:"models"})," section, creating reusable configurations that multiple components can reference. For detailed information about the overall configuration structure and shared configuration management, see the ",(0,r.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/installing-and-configuring/configurations",children:"Configuring Agent Mesh"}),"."]}),"\n",(0,r.jsx)(n.h2,{id:"understanding-litellm-integration",children:"Understanding LiteLLM Integration"}),"\n",(0,r.jsxs)(n.p,{children:["Agent Mesh leverages ",(0,r.jsx)(n.a,{href:"https://docs.litellm.ai/docs/providers",children:"LiteLLM"})," to provide seamless integration with numerous LLM providers. This integration layer abstracts the differences between various provider APIs, allowing you to use a consistent configuration format regardless of whether you're connecting to OpenAI, Anthropic, Google, Amazon, or other supported providers."]}),"\n",(0,r.jsxs)(n.p,{children:["The configuration system passes all fields from the ",(0,r.jsx)(n.code,{children:"models"})," section directly to LiteLLM, giving you access to the full range of provider-specific options and features. This approach ensures that you can take advantage of advanced capabilities offered by different providers while maintaining a consistent configuration experience across your deployment."]}),"\n",(0,r.jsxs)(n.p,{children:["Environment variables provide a secure and flexible way to manage sensitive information such as API keys and endpoint URLs. The configuration system supports environment variable substitution using the format ",(0,r.jsx)(n.code,{children:"${ENV_VAR_NAME, default_value}"}),", allowing you to keep secrets out of your configuration files while providing sensible defaults for development environments."]}),"\n",(0,r.jsx)(n.h2,{id:"provider-specific-configurations",children:"Provider-Specific Configurations"}),"\n",(0,r.jsx)(n.h3,{id:"openai",children:"OpenAI"}),"\n",(0,r.jsx)(n.p,{children:"OpenAI provides some of the most widely-used language models, including the GPT series. The configuration requires minimal setup, needing only the model name and your API key. The system uses OpenAI's default endpoints automatically, simplifying the configuration process."}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-yaml",children:"model: gpt-5\napi_key: ${OPENAI_API_KEY}\n"})}),"\n",(0,r.jsxs)(n.p,{children:["If your organization belongs to multiple OpenAI organizations, you can specify which organization to use by adding the ",(0,r.jsx)(n.code,{children:"organization"})," parameter. This parameter helps ensure billing and usage tracking align with your organizational structure."]}),"\n",(0,r.jsxs)(n.p,{children:["For comprehensive details about OpenAI-specific configuration options and advanced features, see the ",(0,r.jsx)(n.a,{href:"https://docs.litellm.ai/docs/providers/openai",children:"OpenAI documentation"}),"."]}),"\n",(0,r.jsx)(n.h3,{id:"azure-openai",children:"Azure OpenAI"}),"\n",(0,r.jsx)(n.p,{children:"Azure OpenAI Service provides OpenAI models through Microsoft's cloud infrastructure, offering additional enterprise features such as private networking and enhanced security controls. The configuration requires specifying your custom Azure endpoint, API key, and API version."}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-yaml",children:'model: azure/gpt-5\napi_base: ${AZURE_API_BASE,"https://your-custom-endpoint.openai.azure.com/"}\napi_key: ${AZURE_API_KEY}\napi_version: ${AZURE_API_VERSION,"2024-12-01-preview"}\n'})}),"\n",(0,r.jsxs)(n.p,{children:["The model name must include the ",(0,r.jsx)(n.code,{children:"azure/"})," prefix to indicate you're using Azure OpenAI rather than the standard OpenAI service. The API base URL points to your specific Azure OpenAI resource, which you configure during the Azure setup process."]}),"\n",(0,r.jsxs)(n.p,{children:["For detailed information about Azure-specific configuration options, deployment models, and enterprise features, see the ",(0,r.jsx)(n.a,{href:"https://docs.litellm.ai/docs/providers/azure/",children:"Azure OpenAI documentation"}),"."]}),"\n",(0,r.jsx)(n.h3,{id:"google-vertex-ai",children:"Google Vertex AI"}),"\n",(0,r.jsx)(n.p,{children:"Google Vertex AI provides access to both Google's own models and third-party models through a unified platform. This service offers enterprise-grade features including fine-tuning capabilities, model versioning, and integration with other Google Cloud services."}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-yaml",children:'model: vertex_ai/claude-sonnet-4@20250514\nvertex_project: ${VERTEX_PROJECT}\nvertex_location: ${VERTEX_LOCATION,"us-east5"}\nvertex_credentials: ${VERTEX_CREDENTIALS}\n'})}),"\n",(0,r.jsxs)(n.p,{children:["The ",(0,r.jsx)(n.code,{children:"vertex_credentials"})," parameter requires a JSON string containing your Google Cloud service account key. This credential provides the necessary authentication for accessing Vertex AI services. You can obtain this key from the Google Cloud Console by creating a service account with appropriate Vertex AI permissions."]}),"\n",(0,r.jsx)(n.p,{children:"An example of the credential structure follows this format:"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-sh",children:'export VERTEX_CREDENTIALS=\'{"type": "", "project_id": "", "private_key_id": "", "private_key": "", "client_email": "", "client_id": "", "auth_uri": "", "token_uri": "", "auth_provider_x509_cert_url": "", "client_x509_cert_url": "", "universe_domain": ""}\'\n'})}),"\n",(0,r.jsxs)(n.p,{children:["For comprehensive information about Vertex AI configuration, available models, and advanced features, see the ",(0,r.jsx)(n.a,{href:"https://docs.litellm.ai/docs/providers/vertex",children:"Vertex AI documentation"}),"."]}),"\n",(0,r.jsx)(n.h3,{id:"amazon-bedrock",children:"Amazon Bedrock"}),"\n",(0,r.jsx)(n.p,{children:"Amazon Bedrock provides access to foundation models from various providers through AWS infrastructure. This service offers enterprise features such as private VPC connectivity, AWS IAM integration, and comprehensive logging through AWS CloudTrail."}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-yaml",children:'model: bedrock/anthropic.claude-3-5-sonnet-20240620-v1:0\naws_region_name: ${AWS_REGION_NAME,"us-east-1"}\naws_access_key_id: ${AWS_ACCESS_KEY_ID}\naws_secret_access_key: ${AWS_SECRET_ACCESS_KEY}\n'})}),"\n",(0,r.jsxs)(n.p,{children:["The model name includes the ",(0,r.jsx)(n.code,{children:"bedrock/"})," prefix followed by the specific model identifier as defined in the Bedrock service. AWS credentials follow standard AWS authentication patterns, allowing you to use IAM roles, environment variables, or credential files depending on your deployment environment."]}),"\n",(0,r.jsxs)(n.p,{children:["For detailed information about Bedrock-specific configuration options, available models, and AWS integration features, see the ",(0,r.jsx)(n.a,{href:"https://docs.litellm.ai/docs/providers/bedrock",children:"AWS Bedrock documentation"}),"."]}),"\n",(0,r.jsx)(n.h3,{id:"anthropic",children:"Anthropic"}),"\n",(0,r.jsx)(n.p,{children:"Anthropic provides the Claude family of models, known for their strong reasoning capabilities and helpful, harmless, and honest behavior. The direct Anthropic API offers the most up-to-date model versions and features."}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-yaml",children:"model: claude-4\napi_key: ${ANTHROPIC_API_KEY}\n"})}),"\n",(0,r.jsx)(n.p,{children:"The configuration requires only the model name and your Anthropic API key, making it straightforward to integrate Claude models into your agent workflows. Anthropic regularly updates their models with improved capabilities, and the direct API typically provides access to the latest versions first."}),"\n",(0,r.jsxs)(n.p,{children:["For comprehensive details about Anthropic-specific configuration options and model capabilities, see the ",(0,r.jsx)(n.a,{href:"https://docs.litellm.ai/docs/providers/anthropic",children:"Anthropic documentation"}),"."]}),"\n",(0,r.jsx)(n.h3,{id:"additional-providers",children:"Additional Providers"}),"\n",(0,r.jsx)(n.p,{children:"LiteLLM supports numerous other providers including Cohere, Hugging Face, Together AI, and many more. Each provider may have specific configuration requirements and capabilities, but the general pattern of specifying model names, endpoints, and authentication credentials remains consistent."}),"\n",(0,r.jsxs)(n.p,{children:["For a complete list of supported providers and their specific configuration requirements, see the ",(0,r.jsx)(n.a,{href:"https://docs.litellm.ai/docs/providers",children:"LiteLLM providers documentation"}),"."]}),"\n",(0,r.jsx)(n.h2,{id:"prompt-caching",children:"Prompt Caching"}),"\n",(0,r.jsx)(n.p,{children:"Agent Mesh supports prompt caching to significantly reduce costs and latency when using LLM providers that support this feature. Prompt caching allows frequently-used content such as system instructions and tool definitions to be cached by the LLM provider, reducing both processing time and token costs on subsequent requests."}),"\n",(0,r.jsx)(n.h3,{id:"how-prompt-caching-works",children:"How Prompt Caching Works"}),"\n",(0,r.jsx)(n.p,{children:"When you configure prompt caching, the system marks specific portions of each request for caching by the LLM provider. These cached portions persist for a provider-defined duration (typically 5 minutes to 1 hour) and can be reused across multiple requests without re-processing. This approach provides substantial cost savings for agents with large system instructions or extensive tool definitions."}),"\n",(0,r.jsx)(n.h3,{id:"supported-providers",children:"Supported Providers"}),"\n",(0,r.jsx)(n.p,{children:"The caching mechanism operates transparently through LiteLLM's provider-agnostic interface. Prompt caching support varies by provider:"}),"\n",(0,r.jsxs)(n.ul,{children:["\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"Anthropic Claude"}),": Full support with explicit cache control, 90% cost reduction on cache hits"]}),"\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"OpenAI"}),": Automatic caching for content exceeding 1,024 tokens"]}),"\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"Azure OpenAI"}),": Automatic caching following OpenAI behavior"]}),"\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"AWS Bedrock"}),": Native caching support via LiteLLM translation"]}),"\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"Deepseek"}),": Native caching support via LiteLLM translation"]}),"\n"]}),"\n",(0,r.jsx)(n.p,{children:"Providers without caching support safely ignore cache control markers, ensuring backward compatibility across all providers."}),"\n",(0,r.jsx)(n.h3,{id:"cache-strategy-configuration",children:"Cache Strategy Configuration"}),"\n",(0,r.jsx)(n.p,{children:"Agent Mesh provides three cache strategies that you can configure per model to optimize costs based on usage patterns:"}),"\n",(0,r.jsxs)(n.table,{children:[(0,r.jsx)(n.thead,{children:(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.th,{children:"Strategy"}),(0,r.jsx)(n.th,{children:"Description"}),(0,r.jsx)(n.th,{children:"Cache Duration"}),(0,r.jsx)(n.th,{children:"Best For"})]})}),(0,r.jsxs)(n.tbody,{children:[(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:'"5m"'})}),(0,r.jsx)(n.td,{children:"5-minute ephemeral cache"}),(0,r.jsx)(n.td,{children:"5 minutes"}),(0,r.jsx)(n.td,{children:"High-frequency agents (10+ calls/hour)"})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:'"1h"'})}),(0,r.jsx)(n.td,{children:"1-hour extended cache"}),(0,r.jsx)(n.td,{children:"1 hour"}),(0,r.jsx)(n.td,{children:"Burst patterns with gaps (3-10 calls/hour)"})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:'"none"'})}),(0,r.jsx)(n.td,{children:"Disable caching"}),(0,r.jsx)(n.td,{children:"N/A"}),(0,r.jsx)(n.td,{children:"Rarely-used agents (less than 2 calls/hour)"})]})]})]}),"\n",(0,r.jsxs)(n.p,{children:["The default strategy is ",(0,r.jsx)(n.code,{children:'"5m"'})," when not explicitly specified, providing optimal performance for most use cases without requiring configuration changes."]}),"\n",(0,r.jsx)(n.h3,{id:"configuration-examples",children:"Configuration Examples"}),"\n",(0,r.jsxs)(n.p,{children:["Configure prompt caching in your model settings using the ",(0,r.jsx)(n.code,{children:"cache_strategy"})," parameter:"]}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-yaml",children:'models:\n  # High-frequency orchestrator with 5-minute cache\n  planning:\n    model: anthropic/claude-sonnet-4-5-20250929\n    api_key: ${ANTHROPIC_API_KEY}\n    cache_strategy: "5m"\n    temperature: 0.1\n\n  # Burst-pattern agent with 1-hour cache\n  analysis:\n    model: anthropic/claude-sonnet-4-5-20250929\n    api_key: ${ANTHROPIC_API_KEY}\n    cache_strategy: "1h"\n    temperature: 0.7\n\n  # Low-frequency agent with caching disabled\n  maintenance:\n    model: anthropic/claude-sonnet-4-5-20250929\n    api_key: ${ANTHROPIC_API_KEY}\n    cache_strategy: "none"\n'})}),"\n",(0,r.jsx)(n.h3,{id:"cache-strategy-selection-guidelines",children:"Cache Strategy Selection Guidelines"}),"\n",(0,r.jsx)(n.p,{children:"Choose your cache strategy based on agent usage patterns:"}),"\n",(0,r.jsxs)(n.p,{children:[(0,r.jsx)(n.strong,{children:'Use "5m" strategy'})," when:"]}),"\n",(0,r.jsxs)(n.ul,{children:["\n",(0,r.jsx)(n.li,{children:"Agent receives 10 or more requests per hour"}),"\n",(0,r.jsx)(n.li,{children:"Requests arrive in steady streams rather than isolated bursts"}),"\n",(0,r.jsx)(n.li,{children:"Cache remains warm through continuous use"}),"\n",(0,r.jsx)(n.li,{children:"Example: Primary orchestrator agents handling user interactions"}),"\n"]}),"\n",(0,r.jsxs)(n.p,{children:[(0,r.jsx)(n.strong,{children:'Use "1h" strategy'})," when:"]}),"\n",(0,r.jsxs)(n.ul,{children:["\n",(0,r.jsx)(n.li,{children:"Agent receives 3-10 requests per hour in burst patterns"}),"\n",(0,r.jsx)(n.li,{children:"Gaps between request bursts exceed 5 minutes"}),"\n",(0,r.jsx)(n.li,{children:"Extended cache duration bridges usage gaps"}),"\n",(0,r.jsx)(n.li,{children:"Example: Development and testing scenarios, periodic analysis agents"}),"\n"]}),"\n",(0,r.jsxs)(n.p,{children:[(0,r.jsx)(n.strong,{children:'Use "none" strategy'})," when:"]}),"\n",(0,r.jsxs)(n.ul,{children:["\n",(0,r.jsx)(n.li,{children:"Agent receives fewer than 2 requests per hour"}),"\n",(0,r.jsx)(n.li,{children:"Cache write premium exceeds potential savings"}),"\n",(0,r.jsx)(n.li,{children:"System instructions change frequently"}),"\n",(0,r.jsx)(n.li,{children:"Example: Maintenance agents, backup handlers, rarely-used specialized agents"}),"\n"]}),"\n",(0,r.jsx)(n.h3,{id:"what-gets-cached",children:"What Gets Cached"}),"\n",(0,r.jsx)(n.p,{children:"The caching system optimizes two primary components of LLM requests:"}),"\n",(0,r.jsxs)(n.p,{children:[(0,r.jsx)(n.strong,{children:"System Instructions"}),": The complete agent system prompt, including capabilities, guidelines, and any static context. System instructions typically represent the largest cacheable content and provide the most significant cost savings."]}),"\n",(0,r.jsxs)(n.p,{children:[(0,r.jsx)(n.strong,{children:"Tool Definitions"}),": All tool declarations available to the agent, including peer agent communication tools. Agent Mesh ensures tool order stability through alphabetical sorting, maintaining cache validity across requests."]}),"\n",(0,r.jsx)(n.p,{children:"Conversation history and user messages are never cached, as these components change with each request and represent the unique context for each interaction."}),"\n",(0,r.jsx)(n.h3,{id:"cache-invalidation",children:"Cache Invalidation"}),"\n",(0,r.jsx)(n.p,{children:"The system automatically handles cache invalidation, requiring no manual intervention. When the cache expires or invalidates, the next request writes new cache content, and subsequent requests benefit from the refreshed cache."}),"\n",(0,r.jsx)(n.h2,{id:"oauth-20-authentication",children:"OAuth 2.0 Authentication"}),"\n",(0,r.jsx)(n.p,{children:"Agent Mesh supports OAuth 2.0 Client Credentials authentication for LLM providers that require OAuth-based authentication instead of traditional API keys. This authentication method provides enhanced security through automatic token management, secure credential handling, and seamless integration with OAuth-enabled LLM endpoints."}),"\n",(0,r.jsx)(n.h3,{id:"overview",children:"Overview"}),"\n",(0,r.jsxs)(n.p,{children:["The OAuth 2.0 Client Credentials flow is a machine-to-machine authentication method defined in ",(0,r.jsx)(n.a,{href:"https://tools.ietf.org/html/rfc6749#section-4.4",children:"RFC 6749"}),". Agent Mesh handles the complete OAuth lifecycle automatically, including token acquisition, caching, refresh, and injection into LLM requests. This implementation ensures secure and efficient authentication without requiring manual token management."]}),"\n",(0,r.jsx)(n.h3,{id:"configuration-parameters",children:"Configuration Parameters"}),"\n",(0,r.jsx)(n.p,{children:"OAuth authentication requires several configuration parameters that you can specify through environment variables and YAML configuration:"}),"\n",(0,r.jsxs)(n.table,{children:[(0,r.jsx)(n.thead,{children:(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.th,{children:"Parameter"}),(0,r.jsx)(n.th,{children:"Required"}),(0,r.jsx)(n.th,{children:"Description"}),(0,r.jsx)(n.th,{children:"Default"})]})}),(0,r.jsxs)(n.tbody,{children:[(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"oauth_token_url"})}),(0,r.jsx)(n.td,{children:"Yes"}),(0,r.jsx)(n.td,{children:"OAuth token endpoint URL"}),(0,r.jsx)(n.td,{children:"-"})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"oauth_client_id"})}),(0,r.jsx)(n.td,{children:"Yes"}),(0,r.jsx)(n.td,{children:"OAuth client identifier"}),(0,r.jsx)(n.td,{children:"-"})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"oauth_client_secret"})}),(0,r.jsx)(n.td,{children:"Yes"}),(0,r.jsx)(n.td,{children:"OAuth client secret"}),(0,r.jsx)(n.td,{children:"-"})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"oauth_scope"})}),(0,r.jsx)(n.td,{children:"No"}),(0,r.jsx)(n.td,{children:"OAuth scope (space-separated)"}),(0,r.jsx)(n.td,{children:"None"})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"oauth_ca_cert"})}),(0,r.jsx)(n.td,{children:"No"}),(0,r.jsx)(n.td,{children:"Custom CA certificate path for OAuth endpoint"}),(0,r.jsx)(n.td,{children:"None"})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"oauth_token_refresh_buffer_seconds"})}),(0,r.jsx)(n.td,{children:"No"}),(0,r.jsx)(n.td,{children:"Seconds before expiration to refresh token"}),(0,r.jsx)(n.td,{children:"300"})]})]})]}),"\n",(0,r.jsx)(n.h3,{id:"environment-variables",children:"Environment Variables"}),"\n",(0,r.jsxs)(n.p,{children:["Configure OAuth credentials securely using environment variables in your ",(0,r.jsx)(n.code,{children:".env"})," file:"]}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-bash",children:'# Required OAuth Configuration\nOAUTH_TOKEN_URL="https://auth.example.com/oauth/token"\nOAUTH_CLIENT_ID="your_client_id"\nOAUTH_CLIENT_SECRET="your_client_secret"\n\n# Optional OAuth Configuration\nOAUTH_SCOPE="llm.read llm.write"\nOAUTH_CA_CERT_PATH="/path/to/ca.crt"\nOAUTH_TOKEN_REFRESH_BUFFER_SECONDS="300"\n\n# LLM Endpoint Configuration\nOAUTH_LLM_API_BASE="https://api.example.com/v1"\n'})}),"\n",(0,r.jsx)(n.h3,{id:"yaml-configuration",children:"YAML Configuration"}),"\n",(0,r.jsxs)(n.p,{children:["Configure OAuth-authenticated models in your ",(0,r.jsx)(n.code,{children:"shared_config.yaml"})," file:"]}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-yaml",children:"models:\n  # OAuth-authenticated planning model\n  planning:\n    model: ${OAUTH_LLM_PLANNING_MODEL_NAME}\n    api_base: ${OAUTH_LLM_API_BASE}\n    \n    # OAuth 2.0 Client Credentials configuration\n    oauth_token_url: ${OAUTH_TOKEN_URL}\n    oauth_client_id: ${OAUTH_CLIENT_ID}\n    oauth_client_secret: ${OAUTH_CLIENT_SECRET}\n    oauth_scope: ${OAUTH_SCOPE}\n    oauth_ca_cert: ${OAUTH_CA_CERT_PATH}\n    oauth_token_refresh_buffer_seconds: ${OAUTH_TOKEN_REFRESH_BUFFER_SECONDS, 300}\n    \n    parallel_tool_calls: true\n    temperature: 0.1\n\n  # OAuth-authenticated general model\n  general:\n    model: ${OAUTH_LLM_GENERAL_MODEL_NAME}\n    api_base: ${OAUTH_LLM_API_BASE}\n    \n    # OAuth 2.0 Client Credentials configuration\n    oauth_token_url: ${OAUTH_TOKEN_URL}\n    oauth_client_id: ${OAUTH_CLIENT_ID}\n    oauth_client_secret: ${OAUTH_CLIENT_SECRET}\n    oauth_scope: ${OAUTH_SCOPE}\n    oauth_ca_cert: ${OAUTH_CA_CERT_PATH}\n    oauth_token_refresh_buffer_seconds: ${OAUTH_TOKEN_REFRESH_BUFFER_SECONDS, 300}\n"})}),"\n",(0,r.jsx)(n.h3,{id:"error-handling-and-fallback",children:"Error Handling and Fallback"}),"\n",(0,r.jsx)(n.p,{children:"The OAuth system implements robust error handling:"}),"\n",(0,r.jsxs)(n.ul,{children:["\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"4xx Errors"}),": Client configuration errors result in no retries, as these indicate credential or configuration issues"]}),"\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"5xx Errors"}),": Server errors trigger exponential backoff with jitter for up to 3 retry attempts"]}),"\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"Network Errors"}),": Connection issues trigger exponential backoff with jitter for up to 3 retry attempts"]}),"\n"]}),"\n",(0,r.jsxs)(n.p,{children:["If OAuth authentication fails and an ",(0,r.jsx)(n.code,{children:"api_key"})," is configured in the model settings, the system automatically falls back to API key authentication and logs the OAuth failure. If no fallback is available, the request fails with the OAuth error."]}),"\n",(0,r.jsx)(n.h3,{id:"security-considerations",children:"Security Considerations"}),"\n",(0,r.jsx)(n.p,{children:"When implementing OAuth authentication, follow these security best practices:"}),"\n",(0,r.jsxs)(n.ol,{children:["\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"Credential Storage"}),": Always store OAuth credentials securely using environment variables, never hardcode them in configuration files"]}),"\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"Token Caching"}),": Tokens are cached in memory only and never persisted to disk"]}),"\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"SSL/TLS"}),": Always use HTTPS for OAuth endpoints to protect credentials in transit"]}),"\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"Custom CA Certificates"}),": Use the ",(0,r.jsx)(n.code,{children:"oauth_ca_cert"})," parameter for private or internal OAuth servers with custom certificate authorities"]}),"\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"Scope Limitation"}),": Request only the minimal OAuth scopes required for your LLM operations"]}),"\n"]}),"\n",(0,r.jsx)(n.h3,{id:"troubleshooting-oauth-issues",children:"Troubleshooting OAuth Issues"}),"\n",(0,r.jsx)(n.p,{children:"Common OAuth authentication issues and their solutions:"}),"\n",(0,r.jsx)(n.p,{children:(0,r.jsx)(n.strong,{children:"Invalid Client Credentials"})}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{children:"ERROR: OAuth token request failed with status 401: Invalid client credentials\n"})}),"\n",(0,r.jsxs)(n.p,{children:["Verify that ",(0,r.jsx)(n.code,{children:"OAUTH_CLIENT_ID"})," and ",(0,r.jsx)(n.code,{children:"OAUTH_CLIENT_SECRET"})," are correct and properly URL-encoded if they contain special characters."]}),"\n",(0,r.jsx)(n.p,{children:(0,r.jsx)(n.strong,{children:"Invalid Scope"})}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{children:"ERROR: OAuth token request failed with status 400: Invalid scope\n"})}),"\n",(0,r.jsxs)(n.p,{children:["Verify that ",(0,r.jsx)(n.code,{children:"OAUTH_SCOPE"})," matches your provider's requirements and that scope values are space-separated."]}),"\n",(0,r.jsx)(n.p,{children:(0,r.jsx)(n.strong,{children:"SSL Certificate Issues"})}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{children:"ERROR: OAuth token request failed: SSL certificate verification failed\n"})}),"\n",(0,r.jsxs)(n.p,{children:["Set ",(0,r.jsx)(n.code,{children:"OAUTH_CA_CERT_PATH"})," to point to your custom CA certificate file and verify the certificate chain is complete."]}),"\n",(0,r.jsx)(n.p,{children:(0,r.jsx)(n.strong,{children:"Token Refresh Issues"})}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{children:"WARNING: OAuth token request failed (attempt 1/4): Connection timeout\n"})}),"\n",(0,r.jsx)(n.p,{children:"Check network connectivity to the OAuth endpoint, verify the OAuth endpoint URL is correct, and consider increasing timeout values if needed."}),"\n",(0,r.jsx)(n.h3,{id:"supported-providers-1",children:"Supported Providers"}),"\n",(0,r.jsxs)(n.p,{children:["This OAuth implementation works with any LLM provider that supports OAuth 2.0 Client Credentials flow, accepts Bearer tokens in the ",(0,r.jsx)(n.code,{children:"Authorization"})," header, and is compatible with LiteLLM's request format. Examples include Azure OpenAI with OAuth-enabled endpoints, custom enterprise LLM deployments, and third-party LLM services with OAuth support."]}),"\n",(0,r.jsx)(n.h2,{id:"security-and-ssltls-configuration",children:"Security and SSL/TLS Configuration"}),"\n",(0,r.jsx)(n.p,{children:"Agent Mesh provides comprehensive security controls for connections to LLM endpoints, allowing you to fine-tune SSL/TLS behavior to meet your organization's security requirements. These settings help ensure secure communication with LLM providers while providing flexibility for various network environments and security policies."}),"\n",(0,r.jsx)(n.p,{children:"The SSL verification setting controls whether the system validates SSL certificates when connecting to LLM endpoints. Although disabling verification can resolve connectivity issues in development environments, production deployments should always use proper SSL verification to maintain security."}),"\n",(0,r.jsx)(n.p,{children:"SSL security levels determine the cryptographic standards required for connections. Higher security levels enforce stricter requirements but may cause compatibility issues with older endpoints. The default level provides a good balance between security and compatibility for most deployments."}),"\n",(0,r.jsx)(n.p,{children:"Custom SSL certificates allow you to specify additional trusted certificate authorities or use self-signed certificates in controlled environments. You can provide certificates either as file paths or as direct certificate content in PEM format."}),"\n",(0,r.jsxs)(n.table,{children:[(0,r.jsx)(n.thead,{children:(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.th,{children:"Parameter"}),(0,r.jsx)(n.th,{children:"Type"}),(0,r.jsx)(n.th,{children:"Description"}),(0,r.jsx)(n.th,{children:"Default"})]})}),(0,r.jsxs)(n.tbody,{children:[(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"SSL_VERIFY"})}),(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"boolean"})}),(0,r.jsx)(n.td,{children:"Controls SSL certificate verification for outbound connections."}),(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"true"})})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"SSL_SECURITY_LEVEL"})}),(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"integer"})}),(0,r.jsx)(n.td,{children:"Sets the SSL security level (higher values enforce stricter checks)."}),(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"2"})})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"SSL_CERT_FILE"})}),(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"string"})}),(0,r.jsx)(n.td,{children:"Path to a custom SSL certificate file to use for verification."}),(0,r.jsx)(n.td,{children:"(none)"})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"SSL_CERTIFICATE"})}),(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"string"})}),(0,r.jsx)(n.td,{children:"Direct content of the SSL certificate (PEM format)."}),(0,r.jsx)(n.td,{children:"(none)"})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"DISABLE_AIOHTTP_TRANSPORT"})}),(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"boolean"})}),(0,r.jsx)(n.td,{children:"Flag to disable the use of aiohttp transport for HTTP requests."}),(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"false"})})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"AIOHTTP_TRUST_ENV"})}),(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"boolean"})}),(0,r.jsx)(n.td,{children:"Flag to enable aiohttp to trust environment proxy settings."}),(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"false"})})]})]})]}),"\n",(0,r.jsx)(n.p,{children:"The HTTP transport settings control how the system makes network requests to LLM endpoints. The aiohttp transport provides efficient asynchronous HTTP handling, although some environments may require disabling it for compatibility reasons. The trust environment setting allows the HTTP client to use proxy settings from environment variables, which can be useful in corporate networks."}),"\n",(0,r.jsxs)(n.p,{children:["For detailed information about each security setting and specific use cases, see the ",(0,r.jsx)(n.a,{href:"https://docs.litellm.ai/docs/guides/security_settings",children:"LiteLLM security documentation"}),"."]}),"\n",(0,r.jsx)(n.h3,{id:"example-environment-configuration",children:"Example Environment Configuration"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-bash",children:'# SSL Configuration\nSSL_VERIFY=true\nSSL_SECURITY_LEVEL=2\nSSL_CERT_FILE=/path/to/your/certificate.pem\nSSL_CERTIFICATE="-----BEGIN CERTIFICATE-----\nMIIDXTCCAkWgAwIBAg...T2u3V4w5X6y7Z8\n-----END CERTIFICATE-----"\n\n# HTTP Transport Configuration\nDISABLE_AIOHTTP_TRANSPORT=false\nAIOHTTP_TRUST_ENV=false\n'})}),"\n",(0,r.jsx)(n.p,{children:"This example demonstrates how to configure SSL settings through environment variables, providing a secure foundation for LLM communications while maintaining flexibility for different deployment scenarios. The certificate content should be replaced with your actual certificate data, and file paths should point to your specific certificate locations."})]})}function h(e={}){const{wrapper:n}={...(0,s.R)(),...e.components};return n?(0,r.jsx)(n,{...e,children:(0,r.jsx)(d,{...e})}):d(e)}},8453:(e,n,i)=>{i.d(n,{R:()=>o,x:()=>a});var t=i(6540);const r={},s=t.createContext(r);function o(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(r):e.components||r:o(e.components),t.createElement(s.Provider,{value:n},e.children)}}}]);

solace_agent_mesh/assets/docs/assets/js/e3d9abda.2b916f9e.js

@@ -0,0 +1 @@
+"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[7798],{7098:(e,n,t)=>{t.r(n),t.d(n,{assets:()=>d,contentTitle:()=>a,default:()=>h,frontMatter:()=>s,metadata:()=>i,toc:()=>l});const i=JSON.parse('{"id":"documentation/enterprise/installation","title":"Installing Agent Mesh Enterprise","description":"This guide walks you through installing and running Agent Mesh Enterprise using Docker. You will download the enterprise image, load it into Docker, and launch a container configured for either development or production use.","source":"@site/docs/documentation/enterprise/installation.md","sourceDirName":"documentation/enterprise","slug":"/documentation/enterprise/installation","permalink":"/solace-agent-mesh/docs/documentation/enterprise/installation","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/enterprise/installation.md","tags":[],"version":"current","sidebarPosition":5,"frontMatter":{"title":"Installing Agent Mesh Enterprise","sidebar_position":5},"sidebar":"docSidebar","previous":{"title":"Agent Mesh Enterprise","permalink":"/solace-agent-mesh/docs/documentation/enterprise/"},"next":{"title":"Setting Up RBAC","permalink":"/solace-agent-mesh/docs/documentation/enterprise/rbac-setup-guide"}}');var o=t(4848),r=t(8453);const s={title:"Installing Agent Mesh Enterprise",sidebar_position:5},a=void 0,d={},l=[{value:"Prerequisites",id:"prerequisites",level:2},{value:"Understanding the Installation Process",id:"understanding-the-installation-process",level:2},{value:"Step 1: Download and Load the Enterprise Image",id:"step-1-download-and-load-the-enterprise-image",level:2},{value:"Step 2: Identify the Image Name",id:"step-2-identify-the-image-name",level:2},{value:"Step 3: Run the Container",id:"step-3-run-the-container",level:2},{value:"Running in Development Mode",id:"running-in-development-mode",level:3},{value:"Running in Production Mode",id:"running-in-production-mode",level:3},{value:"Accessing the Web UI",id:"accessing-the-web-ui",level:2},{value:"Troubleshooting and Debugging",id:"troubleshooting-and-debugging",level:2}];function c(e){const n={a:"a",admonition:"admonition",code:"code",h2:"h2",h3:"h3",img:"img",li:"li",p:"p",pre:"pre",ul:"ul",...(0,r.R)(),...e.components},{Details:i}=n;return i||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,o.jsxs)(o.Fragment,{children:[(0,o.jsx)(n.p,{children:"This guide walks you through installing and running Agent Mesh Enterprise using Docker. You will download the enterprise image, load it into Docker, and launch a container configured for either development or production use."}),"\n",(0,o.jsx)(n.admonition,{type:"tip",children:(0,o.jsxs)(n.p,{children:["All the ",(0,o.jsx)(n.code,{children:"docker"})," commands can also be run using any Docker-compatible tool, such as ",(0,o.jsx)(n.a,{href:"https://podman.io/",children:"Podman"}),"."]})}),"\n",(0,o.jsx)(n.h2,{id:"prerequisites",children:"Prerequisites"}),"\n",(0,o.jsx)(n.p,{children:"Before you begin, ensure you have the following:"}),"\n",(0,o.jsxs)(n.ul,{children:["\n",(0,o.jsx)(n.li,{children:"Docker installed on your system"}),"\n",(0,o.jsxs)(n.li,{children:["Access to the ",(0,o.jsx)(n.a,{href:"https://products.solace.com/prods/Agent_Mesh/Enterprise/",children:"Solace Product Portal"})]}),"\n",(0,o.jsx)(n.li,{children:"An LLM service API key and endpoint"}),"\n",(0,o.jsx)(n.li,{children:"For production deployments, Solace broker credentials"}),"\n"]}),"\n",(0,o.jsx)(n.h2,{id:"understanding-the-installation-process",children:"Understanding the Installation Process"}),"\n",(0,o.jsx)(n.p,{children:"The installation process consists of three main steps. First, you download and load the Docker image into your local Docker environment. This makes the Agent Mesh Enterprise software available on your system. Second, you identify the exact image name and tag that Docker assigned during the load process. You need this information to reference the correct image when starting your container. Finally, you run the container with the appropriate configuration for your use case\u2014either development mode with an embedded broker or production mode connected to an external Solace broker."}),"\n",(0,o.jsx)(n.h2,{id:"step-1-download-and-load-the-enterprise-image",children:"Step 1: Download and Load the Enterprise Image"}),"\n",(0,o.jsx)(n.p,{children:"You need to obtain the Agent Mesh Enterprise Docker image from the Solace Product Portal and load it into your Docker environment."}),"\n",(0,o.jsxs)(n.p,{children:["Download the latest enterprise docker image tarball from the ",(0,o.jsx)(n.a,{href:"https://products.solace.com/prods/Agent_Mesh/Enterprise/",children:"Solace Product Portal"}),"."]}),"\n",(0,o.jsx)(n.p,{children:"After downloading the tarball, load the image into Docker. This command extracts the image from the compressed archive and makes it available in your local Docker image repository."}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-bash",children:"docker load -i solace-agent-mesh-enterprise-<tag>.tar.gz\n"})}),"\n",(0,o.jsxs)(n.p,{children:["Ensure you replace ",(0,o.jsx)(n.code,{children:"<tag>"})," with the appropriate version number from your downloaded file."]}),"\n",(0,o.jsx)(n.h2,{id:"step-2-identify-the-image-name",children:"Step 2: Identify the Image Name"}),"\n",(0,o.jsx)(n.p,{children:"After loading the image, you need to identify its full name and tag. Docker assigns a repository name and tag to the image during the load process, and you will use this information when running the container."}),"\n",(0,o.jsx)(n.p,{children:"Run the following command to list all Docker images on your system:"}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-bash",children:"docker images\n"})}),"\n",(0,o.jsx)(n.p,{children:"The output displays all available images with their repository names, tags, image IDs, creation dates, and sizes. Look for the Agent Mesh Enterprise image in the list."}),"\n",(0,o.jsx)(n.p,{children:"Example output:"}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-bash",children:"REPOSITORY                                                                 TAG                IMAGE ID      CREATED      SIZE\n868978040651.dkr.ecr.us-east-1.amazonaws.com/solace-agent-mesh-enterprise  1.0.37-c8890c7f31  2589d25d0917  9 days ago   5.25 GB\n"})}),"\n",(0,o.jsxs)(n.p,{children:["Take note of the complete repository name and tag. You will need this full identifier when starting the container. In the example above, the complete image name is ",(0,o.jsx)(n.code,{children:"868978040651.dkr.ecr.us-east-1.amazonaws.com/solace-agent-mesh-enterprise:1.0.37-c8890c7f31"}),"."]}),"\n",(0,o.jsxs)(n.p,{children:["The numeric hashes at the beginning and end of the repository name (such as ",(0,o.jsx)(n.code,{children:"868978040651"})," and ",(0,o.jsx)(n.code,{children:"c8890c7f31"}),") vary between versions and builds. Your image will have different hash values."]}),"\n",(0,o.jsx)(n.h2,{id:"step-3-run-the-container",children:"Step 3: Run the Container"}),"\n",(0,o.jsx)(n.p,{children:"You can run Agent Mesh Enterprise in two different modes depending on your needs. Development mode uses an embedded Solace broker for quick testing and experimentation, while production mode connects to an external Solace broker for enterprise deployments."}),"\n",(0,o.jsx)(n.admonition,{type:"tip",children:(0,o.jsxs)(n.p,{children:["You may need to include ",(0,o.jsx)(n.code,{children:"--platform linux/amd64"})," depending on the host machine you're using."]})}),"\n",(0,o.jsx)(n.h3,{id:"running-in-development-mode",children:"Running in Development Mode"}),"\n",(0,o.jsx)(n.p,{children:"Development mode simplifies getting started by using an embedded Solace broker. This configuration requires fewer parameters and allows you to test Agent Mesh Enterprise without setting up external infrastructure. Use this mode for local development, testing, and evaluation."}),"\n",(0,o.jsxs)(n.p,{children:["The following command starts a container in development mode. The ",(0,o.jsx)(n.code,{children:"-itd"})," flags run the container in interactive mode with a pseudo-TTY, detached in the background. The ",(0,o.jsx)(n.code,{children:"-p 8001:8000"})," flag maps port 8000 inside the container to port 8001 on your host machine, making the web UI accessible at ",(0,o.jsx)(n.code,{children:"http://localhost:8001"}),"."]}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-bash",children:'docker run -itd -p 8001:8000 \\\n  -e LLM_SERVICE_API_KEY="<YOUR_LLM_TOKEN>" \\\n  -e LLM_SERVICE_ENDPOINT="<YOUR_LLM_SERVICE_ENDPOINT>" \\\n  -e LLM_SERVICE_PLANNING_MODEL_NAME="<YOUR_MODEL_NAME>" \\\n  -e LLM_SERVICE_GENERAL_MODEL_NAME="<YOUR_MODEL_NAME>" \\\n  -e NAMESPACE="<YOUR_NAMESPACE>" \\\n  -e SOLACE_DEV_MODE="true" \\\n  --name sam-ent-dev \\\n  solace-agent-mesh-enterprise:<tag>\n'})}),"\n",(0,o.jsx)(n.p,{children:"Replace the placeholder values with your actual configuration:"}),"\n",(0,o.jsxs)(n.ul,{children:["\n",(0,o.jsxs)(n.li,{children:[(0,o.jsx)(n.code,{children:"<YOUR_LLM_TOKEN>"}),": Your API key for the LLM service"]}),"\n",(0,o.jsxs)(n.li,{children:[(0,o.jsx)(n.code,{children:"<YOUR_LLM_SERVICE_ENDPOINT>"}),": The URL endpoint for your LLM service"]}),"\n",(0,o.jsxs)(n.li,{children:[(0,o.jsx)(n.code,{children:"<YOUR_MODEL_NAME>"}),": The name of the LLM model you want to use (you can specify the same model for both planning and general tasks, or use different models)"]}),"\n",(0,o.jsxs)(n.li,{children:[(0,o.jsx)(n.code,{children:"<YOUR_NAMESPACE>"}),': A unique identifier for your deployment (such as "sam-dev")']}),"\n",(0,o.jsxs)(n.li,{children:[(0,o.jsx)(n.code,{children:"<tag>"}),": The image tag you identified in Step 2"]}),"\n"]}),"\n",(0,o.jsxs)(n.p,{children:["The ",(0,o.jsx)(n.code,{children:'SOLACE_DEV_MODE="true"'})," environment variable tells the container to use the embedded broker instead of connecting to an external one."]}),"\n",(0,o.jsxs)(i,{children:[(0,o.jsx)("summary",{children:"Example"}),(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-bash",children:'docker run -itd -p 8001:8000 \\\n  -e LLM_SERVICE_API_KEY="<YOUR_LLM_TOKEN>" \\\n  -e LLM_SERVICE_ENDPOINT="https://lite-llm.mymaas.net/" \\\n  -e LLM_SERVICE_PLANNING_MODEL_NAME="openai/vertex-claude-4-sonnet" \\\n  -e LLM_SERVICE_GENERAL_MODEL_NAME="openai/vertex-claude-4-sonnet" \\\n  -e NAMESPACE="sam-dev" \\\n  -e SOLACE_DEV_MODE="true" \\\n  --name sam-ent-dev \\\n  868978040651.dkr.ecr.us-east-1.amazonaws.com/solace-agent-mesh-enterprise:1.0.37-c8890c7f31\n'})})]}),"\n",(0,o.jsx)(n.h3,{id:"running-in-production-mode",children:"Running in Production Mode"}),"\n",(0,o.jsx)(n.p,{children:"Production mode connects to an external Solace broker, which provides enterprise-grade messaging capabilities including high availability, disaster recovery, and scalability. Use this mode when deploying Agent Mesh Enterprise in production environments."}),"\n",(0,o.jsx)(n.p,{children:"The production configuration requires additional environment variables to specify the Solace broker connection details. These credentials allow the container to connect to your Solace Cloud service or on-premises broker."}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-bash",children:'docker run -itd -p 8001:8000 \\\n  -e LLM_SERVICE_API_KEY="<YOUR_LLM_TOKEN>" \\\n  -e LLM_SERVICE_ENDPOINT="<YOUR_LLM_SERVICE_ENDPOINT>" \\\n  -e LLM_SERVICE_PLANNING_MODEL_NAME="<YOUR_MODEL_NAME>" \\\n  -e LLM_SERVICE_GENERAL_MODEL_NAME="<YOUR_MODEL_NAME>" \\\n  -e NAMESPACE="<YOUR_NAMESPACE>" \\\n  -e SOLACE_DEV_MODE="false" \\\n  -e SOLACE_BROKER_URL="<YOUR_BROKER_URL>" \\\n  -e SOLACE_BROKER_VPN="<YOUR_BROKER_VPN>" \\\n  -e SOLACE_BROKER_USERNAME="<YOUR_BROKER_USERNAME>" \\\n  -e SOLACE_BROKER_PASSWORD="<YOUR_BROKER_PASSWORD>" \\\n  --name sam-ent-prod \\\n  solace-agent-mesh-enterprise:<tag>\n'})}),"\n",(0,o.jsx)(n.p,{children:"Replace the placeholder values with your actual configuration. In addition to the LLM service parameters described in the development mode section, you need to provide:"}),"\n",(0,o.jsxs)(n.ul,{children:["\n",(0,o.jsxs)(n.li,{children:[(0,o.jsx)(n.code,{children:"<YOUR_BROKER_URL>"}),": The secured SMF URI for your Solace broker"]}),"\n",(0,o.jsxs)(n.li,{children:[(0,o.jsx)(n.code,{children:"<YOUR_BROKER_VPN>"}),": The Message VPN name for your Solace service"]}),"\n",(0,o.jsxs)(n.li,{children:[(0,o.jsx)(n.code,{children:"<YOUR_BROKER_USERNAME>"}),": The username for broker authentication"]}),"\n",(0,o.jsxs)(n.li,{children:[(0,o.jsx)(n.code,{children:"<YOUR_BROKER_PASSWORD>"}),": The password for broker authentication"]}),"\n"]}),"\n",(0,o.jsxs)(n.p,{children:["The ",(0,o.jsx)(n.code,{children:'SOLACE_DEV_MODE="false"'})," environment variable tells the container to connect to the external broker specified by the other SOLACE_BROKER parameters instead of using the embedded broker."]}),"\n",(0,o.jsxs)(i,{children:[(0,o.jsx)("summary",{children:"How to find your credentials"}),(0,o.jsx)(n.p,{children:"Go to Solace Cloud."}),(0,o.jsx)(n.p,{children:"Cluster manager > Your Service > Connect"}),(0,o.jsx)(n.p,{children:"Switch dropdown to View by Language"}),(0,o.jsx)(n.p,{children:"Open the connect with Python dropdown"}),(0,o.jsx)(n.p,{children:"Click Solace Python with smf as the protocol."}),(0,o.jsx)(n.p,{children:"Copy:"}),(0,o.jsxs)(n.ul,{children:["\n",(0,o.jsx)(n.li,{children:"Username for SOLACE_BROKER_USERNAME,"}),"\n",(0,o.jsx)(n.li,{children:"Password for SOLACE_BROKER_PASSWORD,"}),"\n",(0,o.jsx)(n.li,{children:"Message VPN for SOLACE_BROKER_VPN"}),"\n",(0,o.jsx)(n.li,{children:"Secured SMF URI for SOLACE_BROKER_URL"}),"\n"]}),(0,o.jsx)(n.p,{children:(0,o.jsx)(n.img,{alt:"How to get credentials",src:t(5981).A+"",width:"3456",height:"1916"})})]}),"\n",(0,o.jsx)(n.h2,{id:"accessing-the-web-ui",children:"Accessing the Web UI"}),"\n",(0,o.jsx)(n.p,{children:"After starting the container in either development or production mode, you can access the Agent Mesh Enterprise web interface through your browser. The UI provides a graphical interface for managing agents, monitoring activity, and configuring your deployment."}),"\n",(0,o.jsxs)(n.p,{children:["Navigate to ",(0,o.jsx)(n.code,{children:"http://localhost:8001"})," in your web browser. The port number corresponds to the host port you specified in the ",(0,o.jsx)(n.code,{children:"-p 8001:8000"})," flag when running the container."]}),"\n",(0,o.jsx)(n.h2,{id:"troubleshooting-and-debugging",children:"Troubleshooting and Debugging"}),"\n",(0,o.jsx)(n.p,{children:"If you encounter issues or need to investigate the behavior of your Agent Mesh Enterprise deployment, you can examine the log files generated by the container. These logs provide detailed information about system operations, errors, and debugging information."}),"\n",(0,o.jsxs)(n.p,{children:["To view logs, check the ",(0,o.jsx)(n.code,{children:".log"})," files in your container. For information about changing debug levels and advanced debugging techniques, see the debugging documentation at ",(0,o.jsx)(n.a,{href:"https://solacelabs.github.io/solace-agent-mesh/docs/documentation/deployment/debugging/",children:"https://solacelabs.github.io/solace-agent-mesh/docs/documentation/deployment/debugging/"}),"."]})]})}function h(e={}){const{wrapper:n}={...(0,r.R)(),...e.components};return n?(0,o.jsx)(n,{...e,children:(0,o.jsx)(c,{...e})}):c(e)}},5981:(e,n,t)=>{t.d(n,{A:()=>i});const i=t.p+"assets/images/sam-enterprise-credentials-b269f095349473118b2b33bdfcc40122.png"},8453:(e,n,t)=>{t.d(n,{R:()=>s,x:()=>a});var i=t(6540);const o={},r=i.createContext(o);function s(e){const n=i.useContext(r);return i.useMemo((function(){return"function"==typeof e?e(n):{...n,...e}}),[n,e])}function a(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(o):e.components||o:s(e.components),i.createElement(r.Provider,{value:n},e.children)}}}]);

solace_agent_mesh/assets/docs/assets/js/e6f9706b.e74a984d.js

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

solace_agent_mesh/assets/docs/assets/js/e92d0134.cf6d6522.js

@@ -0,0 +1 @@
+"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[7567],{9392:(e,i,t)=>{t.r(i),t.d(i,{assets:()=>l,contentTitle:()=>a,default:()=>h,frontMatter:()=>r,metadata:()=>n,toc:()=>c});const n=JSON.parse('{"id":"documentation/deploying/observability","title":"Monitoring Your Agent Mesh","description":"Understanding how your Agent Mesh system operates in real-time is crucial for maintaining optimal performance and quickly identifying issues. The platform provides a comprehensive observability suite that gives you deep insights into system behavior, message flows, and agent interactions.","source":"@site/docs/documentation/deploying/observability.md","sourceDirName":"documentation/deploying","slug":"/documentation/deploying/observability","permalink":"/solace-agent-mesh/docs/documentation/deploying/observability","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/deploying/observability.md","tags":[],"version":"current","sidebarPosition":20,"frontMatter":{"title":"Monitoring Your Agent Mesh","sidebar_position":20},"sidebar":"docSidebar","previous":{"title":"Choosing Deployment Options","permalink":"/solace-agent-mesh/docs/documentation/deploying/deployment-options"},"next":{"title":"Diagnosing and Resolving Problems","permalink":"/solace-agent-mesh/docs/documentation/deploying/debugging"}}');var s=t(4848),o=t(8453);const r={title:"Monitoring Your Agent Mesh",sidebar_position:20},a="Monitoring Your Agent Mesh",l={},c=[{value:"Viewing Workflows",id:"viewing-workflows",level:2},{value:"Viewing Agents",id:"viewing-agents",level:2},{value:"Monitoring Event Broker Activity",id:"monitoring-event-broker-activity",level:2},{value:"Monitoring Message Flows",id:"monitoring-message-flows",level:3},{value:"Examining Stimulus Logs",id:"examining-stimulus-logs",level:2},{value:"Understanding Stimulus Log Content",id:"understanding-stimulus-log-content",level:3},{value:"Storage Location",id:"storage-location",level:3}];function d(e){const i={a:"a",admonition:"admonition",code:"code",em:"em",h1:"h1",h2:"h2",h3:"h3",header:"header",p:"p",pre:"pre",strong:"strong",...(0,o.R)(),...e.components};return(0,s.jsxs)(s.Fragment,{children:[(0,s.jsx)(i.header,{children:(0,s.jsx)(i.h1,{id:"monitoring-your-agent-mesh",children:"Monitoring Your Agent Mesh"})}),"\n",(0,s.jsx)(i.p,{children:"Understanding how your Agent Mesh system operates in real-time is crucial for maintaining optimal performance and quickly identifying issues. The platform provides a comprehensive observability suite that gives you deep insights into system behavior, message flows, and agent interactions."}),"\n",(0,s.jsx)(i.p,{children:"These observability tools work together to create a complete picture of your system's health and performance. Whether you're troubleshooting a specific issue, optimizing performance, or simply monitoring day-to-day operations, these tools provide the visibility you need to maintain a robust agent mesh."}),"\n",(0,s.jsx)(i.h2,{id:"viewing-workflows",children:"Viewing Workflows"}),"\n",(0,s.jsx)(i.p,{children:"The workflow viewer serves as your primary window into how individual requests flow through your agent mesh. This interactive visualization tool transforms complex multi-agent interactions into clear, understandable diagrams that show exactly how your system processes each user query."}),"\n",(0,s.jsx)(i.p,{children:"Understanding request flow is essential because Agent Mesh operates as a distributed system where multiple agents collaborate to fulfill user requests. The workflow viewer makes these interactions transparent by providing an interactive web-based interface for each user query and its corresponding response."}),"\n",(0,s.jsx)(i.p,{children:"The workflow viewer enables you to:"}),"\n",(0,s.jsxs)(i.p,{children:[(0,s.jsx)(i.strong,{children:"Track complete request lifecycles"}),": Follow a stimulus (request) from its initial entry point through every agent interaction until the final response is delivered to the user."]}),"\n",(0,s.jsxs)(i.p,{children:[(0,s.jsx)(i.strong,{children:"Visualize inter-component communication"}),": See how requests and responses flow between agents, the user gateway, and language models, helping you understand the collaboration patterns in your mesh."]}),"\n",(0,s.jsxs)(i.p,{children:[(0,s.jsx)(i.strong,{children:"Monitor real-time agent activity"}),": Observe which agents are actively participating in request processing and identify potential bottlenecks or failures."]}),"\n",(0,s.jsxs)(i.p,{children:["To access the workflow viewer for any specific interaction, click the ",(0,s.jsx)(i.strong,{children:"View Agent Workflow"})," icon located at the bottom left of the final response in the web UI. The complete workflow chart will appear in the side panel on the right, providing an immediate visual representation of the entire request processing flow."]}),"\n",(0,s.jsx)(i.h2,{id:"viewing-agents",children:"Viewing Agents"}),"\n",(0,s.jsx)(i.p,{children:"The Agents view complements the workflow viewer by providing a bird's-eye perspective of your entire agent ecosystem. While the workflow viewer focuses on individual request flows, the Agents view helps you understand the overall structure and health of your agent mesh."}),"\n",(0,s.jsx)(i.p,{children:"This real-time dashboard becomes particularly valuable as your agent mesh grows in complexity. It allows you to quickly assess which agents are available, understand their capabilities, and visualize how they relate to each other within the system hierarchy."}),"\n",(0,s.jsx)(i.p,{children:"The Agents view provides several key insights:"}),"\n",(0,s.jsxs)(i.p,{children:[(0,s.jsx)(i.strong,{children:"Real-time agent registry"}),": See all agents currently registered and active in your system, giving you immediate visibility into system availability and health."]}),"\n",(0,s.jsxs)(i.p,{children:[(0,s.jsx)(i.strong,{children:"Agent capabilities and descriptions"}),": Review what each agent can do, including their specific skills and the types of requests they can handle, helping you understand how work gets distributed across your mesh."]}),"\n",(0,s.jsxs)(i.p,{children:[(0,s.jsx)(i.strong,{children:"Hierarchical topology visualization"}),": Understand the relationships between agents and how they're organized within your system architecture, which is crucial for troubleshooting and optimization."]}),"\n",(0,s.jsxs)(i.p,{children:["To access this comprehensive overview, open the web interface in your browser and switch to the ",(0,s.jsx)(i.strong,{children:"Agents"})," tab."]}),"\n",(0,s.jsx)(i.h2,{id:"monitoring-event-broker-activity",children:"Monitoring Event Broker Activity"}),"\n",(0,s.jsx)(i.p,{children:"The Solace event broker serves as the central nervous system of your agent mesh, handling all communication between components. Monitoring Solace event broker activity provides deep insights into system behavior and helps identify communication issues before they impact users."}),"\n",(0,s.jsx)(i.p,{children:"Understanding message flows at the event broker level is essential because it reveals the actual communication patterns between your agents, regardless of how they're configured. This low-level visibility complements the higher-level views provided by the workflow viewer and agents dashboard."}),"\n",(0,s.jsx)(i.p,{children:"Several specialized tools help you monitor and interact with the Solace event broker:"}),"\n",(0,s.jsxs)(i.p,{children:[(0,s.jsx)(i.strong,{children:"Solace Broker Manager"}),": This web-based interface provides comprehensive event broker management capabilities. The ",(0,s.jsx)(i.em,{children:"Try Me!"})," tab is particularly useful for interactive message testing, allowing you to send and receive messages manually to verify system behavior."]}),"\n",(0,s.jsxs)(i.p,{children:[(0,s.jsx)(i.strong,{children:(0,s.jsx)(i.a,{href:"https://marketplace.visualstudio.com/items?itemName=solace-tools.solace-try-me-vsc-extension",children:"Solace Try Me VSCode Extension"})}),": Integrates message testing directly into your development environment, making it convenient to test message flows without leaving Visual Studio Code."]}),"\n",(0,s.jsxs)(i.p,{children:[(0,s.jsx)(i.strong,{children:(0,s.jsx)(i.a,{href:"https://github.com/SolaceLabs/solace-tryme-cli",children:"Solace Try Me (STM) CLI Tool"})}),": Provides command-line access to message testing capabilities, ideal for scripting and automation scenarios."]}),"\n",(0,s.jsx)(i.h3,{id:"monitoring-message-flows",children:"Monitoring Message Flows"}),"\n",(0,s.jsx)(i.p,{children:"To observe comprehensive message activity within your agent mesh, subscribe to the following topic pattern:"}),"\n",(0,s.jsx)(i.pre,{children:(0,s.jsx)(i.code,{children:"[NAME_SPACES]a2a/v1/>\n"})}),"\n",(0,s.jsxs)(i.p,{children:["Replace ",(0,s.jsx)(i.code,{children:"[NAME_SPACES]"})," with the namespace you are using. If you're not using namespaces, omit the ",(0,s.jsx)(i.code,{children:"[NAME_SPACES]"})," part entirely."]}),"\n",(0,s.jsx)(i.p,{children:"This subscription captures all agent-to-agent communication, providing complete visibility into your mesh's message flows."}),"\n",(0,s.jsxs)(i.admonition,{title:"Filtering Registration Messages",type:"tip",children:[(0,s.jsx)(i.p,{children:"Agents periodically send registration messages to announce their availability. These messages can clutter your monitoring interface when using tools like the STM VSCode extension. To focus on actual request/response traffic, add the following topic to your ignore list:"}),(0,s.jsx)(i.pre,{children:(0,s.jsx)(i.code,{children:"[NAME_SPACES]/a2a/v1/discovery/agentcards\n"})}),(0,s.jsx)(i.p,{children:"This filter removes routine registration messages while preserving visibility into meaningful agent interactions."})]}),"\n",(0,s.jsx)(i.h2,{id:"examining-stimulus-logs",children:"Examining Stimulus Logs"}),"\n",(0,s.jsx)(i.p,{children:"Stimulus logs provide the most detailed level of observability in your Agent Mesh system. While the workflow viewer gives you visual representations and the Solace event broker tools show real-time message flows, stimulus logs create permanent, comprehensive records of every request that flows through your system."}),"\n",(0,s.jsx)(i.p,{children:"These logs serve as your system's memory, capturing complete traces that you can analyze long after events occur. This persistent record becomes invaluable for performance analysis, debugging complex issues, and understanding usage patterns over time."}),"\n",(0,s.jsxs)(i.p,{children:["Agent Mesh includes a default monitor that automatically records each request (stimulus) lifecycle without requiring additional configuration. These detailed traces are stored as ",(0,s.jsx)(i.code,{children:".stim"})," files, creating a comprehensive audit trail of system activity."]}),"\n",(0,s.jsx)(i.h3,{id:"understanding-stimulus-log-content",children:"Understanding Stimulus Log Content"}),"\n",(0,s.jsxs)(i.p,{children:["Each ",(0,s.jsx)(i.code,{children:".stim"})," file contains a complete trace of a single stimulus journey through your agent mesh:"]}),"\n",(0,s.jsxs)(i.p,{children:[(0,s.jsx)(i.strong,{children:"Component traversal paths"}),": Every agent, gateway, and service that handled the request, providing a complete map of the processing pipeline."]}),"\n",(0,s.jsxs)(i.p,{children:[(0,s.jsx)(i.strong,{children:"Timing and sequencing details"}),": Precise timestamps showing when each component received, processed, and forwarded the request, enabling performance analysis and bottleneck identification."]}),"\n",(0,s.jsxs)(i.p,{children:[(0,s.jsx)(i.strong,{children:"Contextual metadata"}),": Additional information about the request context, user session, and system state that influenced processing decisions."]}),"\n",(0,s.jsx)(i.p,{children:"These comprehensive logs create a valuable data source for advanced visualization tools, detailed troubleshooting sessions, and performance optimization efforts. Because they capture the complete picture of each request, they're particularly useful for understanding complex multi-agent interactions that might be difficult to trace through other observability tools."}),"\n",(0,s.jsx)(i.h3,{id:"storage-location",children:"Storage Location"}),"\n",(0,s.jsxs)(i.p,{children:["By default, ",(0,s.jsx)(i.code,{children:".stim"})," files are written to the ",(0,s.jsx)(i.code,{children:"/tmp/solace-agent-mesh/"})," directory. This location provides fast access for analysis while keeping logs separate from your application data."]})]})}function h(e={}){const{wrapper:i}={...(0,o.R)(),...e.components};return i?(0,s.jsx)(i,{...e,children:(0,s.jsx)(d,{...e})}):d(e)}},8453:(e,i,t)=>{t.d(i,{R:()=>r,x:()=>a});var n=t(6540);const s={},o=n.createContext(s);function r(e){const i=n.useContext(o);return n.useMemo((function(){return"function"==typeof e?e(i):{...i,...e}}),[i,e])}function a(e){let i;return i=e.disableParentContext?"function"==typeof e.components?e.components(s):e.components||s:r(e.components),n.createElement(o.Provider,{value:i},e.children)}}}]);

solace_agent_mesh/assets/docs/assets/js/f284c35a.42f59cdd.js

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

solace_agent_mesh/assets/docs/assets/js/ff4d71f2.15b02f97.js

@@ -0,0 +1 @@
+"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[1339],{7119:(e,t,n)=>{n.r(t),n.d(t,{assets:()=>l,contentTitle:()=>r,default:()=>g,frontMatter:()=>s,metadata:()=>a,toc:()=>c});const a=JSON.parse('{"id":"documentation/developing/developing","title":"Developing with Agent Mesh","description":"Agent Mesh provides a framework for creating distributed AI applications using an event-driven architecture. You can build agents that communicate through the A2A (Agent-to-Agent) protocol, extend them with custom tools, integrate external systems through gateways, and create reusable components as plugins.","source":"@site/docs/documentation/developing/developing.md","sourceDirName":"documentation/developing","slug":"/documentation/developing/","permalink":"/solace-agent-mesh/docs/documentation/developing/","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/developing/developing.md","tags":[],"version":"current","sidebarPosition":400,"frontMatter":{"title":"Developing with Agent Mesh","sidebar_position":400},"sidebar":"docSidebar","previous":{"title":"Configuring LLMs","permalink":"/solace-agent-mesh/docs/documentation/installing-and-configuring/large_language_models"},"next":{"title":"Project Structure","permalink":"/solace-agent-mesh/docs/documentation/developing/structure"}}');var o=n(4848),i=n(8453);const s={title:"Developing with Agent Mesh",sidebar_position:400},r="Developing with Agent Mesh",l={},c=[{value:"Understanding the Project Structure",id:"understanding-the-project-structure",level:2},{value:"Building Intelligent Agents",id:"building-intelligent-agents",level:2},{value:"Extending Agent Capabilities",id:"extending-agent-capabilities",level:2},{value:"Connecting External Systems",id:"connecting-external-systems",level:2},{value:"Integrating Enterprise Data Sources",id:"integrating-enterprise-data-sources",level:2},{value:"Practical Integration Examples",id:"practical-integration-examples",level:2},{value:"Development Patterns",id:"development-patterns",level:2},{value:"Evaluating Agents",id:"evaluating-agents",level:2}];function d(e){const t={a:"a",h1:"h1",h2:"h2",header:"header",p:"p",...(0,i.R)(),...e.components};return(0,o.jsxs)(o.Fragment,{children:[(0,o.jsx)(t.header,{children:(0,o.jsx)(t.h1,{id:"developing-with-agent-mesh",children:"Developing with Agent Mesh"})}),"\n",(0,o.jsx)(t.p,{children:"Agent Mesh provides a framework for creating distributed AI applications using an event-driven architecture. You can build agents that communicate through the A2A (Agent-to-Agent) protocol, extend them with custom tools, integrate external systems through gateways, and create reusable components as plugins."}),"\n",(0,o.jsx)(t.h2,{id:"understanding-the-project-structure",children:"Understanding the Project Structure"}),"\n",(0,o.jsxs)(t.p,{children:["The framework uses YAML configuration files to define agents, gateways, and plugins, although you can extend functionality with custom Python components when needed. For a complete overview of project organization and component relationships, see ",(0,o.jsx)(t.a,{href:"/solace-agent-mesh/docs/documentation/developing/structure",children:"Project Structure"}),"."]}),"\n",(0,o.jsx)(t.h2,{id:"building-intelligent-agents",children:"Building Intelligent Agents"}),"\n",(0,o.jsxs)(t.p,{children:["Agents are LLM-powered components that use tools to accomplish tasks and communicate with other agents through the A2A protocol. You can define tools as Python functions, configure agent behavior through YAML, and manage agent lifecycles effectively. For comprehensive guidance on agent development, see ",(0,o.jsx)(t.a,{href:"/solace-agent-mesh/docs/documentation/developing/create-agents",children:"Creating Agents"}),"."]}),"\n",(0,o.jsxs)(t.p,{children:["The ",(0,o.jsx)(t.a,{href:"/solace-agent-mesh/docs/documentation/developing/tutorials/custom-agent",children:"Build Your Own Agent"})," tutorial demonstrates creating a weather agent with external API integration, resource management, and artifact creation."]}),"\n",(0,o.jsx)(t.h2,{id:"extending-agent-capabilities",children:"Extending Agent Capabilities"}),"\n",(0,o.jsxs)(t.p,{children:["You can create custom Python tools using three patterns: simple function-based tools, advanced single-class tools, or tool providers that generate multiple related tools dynamically. The framework handles tool discovery, parameter validation, and lifecycle management automatically. For detailed information on all patterns, see ",(0,o.jsx)(t.a,{href:"/solace-agent-mesh/docs/documentation/developing/creating-python-tools",children:"Creating Python Tools"}),"."]}),"\n",(0,o.jsx)(t.h2,{id:"connecting-external-systems",children:"Connecting External Systems"}),"\n",(0,o.jsxs)(t.p,{children:["Gateways bridge external systems and the A2A ecosystem by translating external events into standardized A2A tasks and responses back to external formats. Whether you're integrating chat systems, web applications, IoT devices, or file systems, gateways provide the necessary translation layer. For complete guidance on gateway development, see ",(0,o.jsx)(t.a,{href:"/solace-agent-mesh/docs/documentation/developing/create-gateways",children:"Create Gateways"}),"."]}),"\n",(0,o.jsx)(t.h2,{id:"integrating-enterprise-data-sources",children:"Integrating Enterprise Data Sources"}),"\n",(0,o.jsxs)(t.p,{children:["Service providers offer a standardized way to integrate backend systems like HR platforms or CRMs through well-defined interfaces. You can create providers that handle both identity enrichment and directory queries, reducing code duplication while maintaining clean separation of concerns. For implementation guidance, see ",(0,o.jsx)(t.a,{href:"/solace-agent-mesh/docs/documentation/developing/creating-service-providers",children:"Creating Service Providers"}),"."]}),"\n",(0,o.jsx)(t.h2,{id:"practical-integration-examples",children:"Practical Integration Examples"}),"\n",(0,o.jsxs)(t.p,{children:["The tutorials provide hands-on examples for common scenarios: ",(0,o.jsx)(t.a,{href:"/solace-agent-mesh/docs/documentation/developing/tutorials/slack-integration",children:"Slack Integration"})," for workspace connectivity, ",(0,o.jsx)(t.a,{href:"/solace-agent-mesh/docs/documentation/developing/tutorials/rest-gateway",children:"REST Gateway"})," for RESTful APIs, and ",(0,o.jsx)(t.a,{href:"/solace-agent-mesh/docs/documentation/developing/tutorials/mcp-integration",children:"MCP Integration"})," for Model Context Protocol servers. Additional tutorials cover database integration, RAG implementations, and cloud service connections."]}),"\n",(0,o.jsx)(t.h2,{id:"development-patterns",children:"Development Patterns"}),"\n",(0,o.jsx)(t.p,{children:"The framework supports both direct component creation and plugin-based development. Plugins offer better reusability and distribution, while direct components provide simpler project-specific implementations. The configuration-driven approach uses YAML files to define behavior and Python code for core logic, enabling flexible deployment scenarios and easier management of complex distributed systems."}),"\n",(0,o.jsx)(t.h2,{id:"evaluating-agents",children:"Evaluating Agents"}),"\n",(0,o.jsxs)(t.p,{children:["The framework includes an evaluation system that helps you test your agents' behavior in a structured way. You can define test suites, run them against your agents, and generate detailed reports to analyze the results. When running evaluations locally, you can also benchmark different language models to see how they affect your agents' responses. For more information, see ",(0,o.jsx)(t.a,{href:"/solace-agent-mesh/docs/documentation/developing/evaluations",children:"Evaluating Agents"}),"."]})]})}function g(e={}){const{wrapper:t}={...(0,i.R)(),...e.components};return t?(0,o.jsx)(t,{...e,children:(0,o.jsx)(d,{...e})}):d(e)}},8453:(e,t,n)=>{n.d(t,{R:()=>s,x:()=>r});var a=n(6540);const o={},i=a.createContext(o);function s(e){const t=a.useContext(i);return a.useMemo((function(){return"function"==typeof e?e(t):{...t,...e}}),[t,e])}function r(e){let t;return t=e.disableParentContext?"function"==typeof e.components?e.components(o):e.components||o:s(e.components),a.createElement(i.Provider,{value:t},e.children)}}}]);