solace-agent-mesh 1.6.3__py3-none-any.whl → 1.7.0__py3-none-any.whl

solace_agent_mesh/assets/docs/assets/js/dd817ffc.0aa9630a.js

@@ -1 +0,0 @@
-"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[1188],{7026:(e,n,t)=>{t.r(n),t.d(n,{assets:()=>c,contentTitle:()=>a,default:()=>d,frontMatter:()=>o,metadata:()=>i,toc:()=>l});const i=JSON.parse('{"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.","source":"@site/docs/documentation/enterprise/enterprise.md","sourceDirName":"documentation/enterprise","slug":"/documentation/enterprise/","permalink":"/solace-agent-mesh/docs/documentation/enterprise/","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/enterprise/enterprise.md","tags":[],"version":"current","sidebarPosition":700,"frontMatter":{"title":"Agent Mesh Enterprise","sidebar_position":700},"sidebar":"docSidebar","previous":{"title":"A2A Technical Migration Map","permalink":"/solace-agent-mesh/docs/documentation/migrations/a2a-upgrade/a2a-technical-migration-map"},"next":{"title":"Installing Agent Mesh Enterprise","permalink":"/solace-agent-mesh/docs/documentation/enterprise/installation"}}');var s=t(4848),r=t(8453);const o={title:"Agent Mesh Enterprise",sidebar_position:700},a="Agent Mesh Enterprise",c={},l=[{value:"Enterprise Features",id:"enterprise-features",level:2},{value:"Getting Started with Enterprise",id:"getting-started-with-enterprise",level:2},{value:"Installation",id:"installation",level:3},{value:"Access Control",id:"access-control",level:3},{value:"Single Sign-On",id:"single-sign-on",level:3},{value:"What's Next",id:"whats-next",level:2}];function h(e){const n={a:"a",h1:"h1",h2:"h2",h3:"h3",header:"header",p:"p",...(0,r.R)(),...e.components};return(0,s.jsxs)(s.Fragment,{children:[(0,s.jsx)(n.header,{children:(0,s.jsx)(n.h1,{id:"agent-mesh-enterprise",children:"Agent Mesh Enterprise"})}),"\n",(0,s.jsx)(n.p,{children:"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."}),"\n",(0,s.jsxs)(n.p,{children:["Enterprise is available as a self-managed container image that you can deploy in your own infrastructure. You can obtain access by joining the pilot program at ",(0,s.jsx)(n.a,{href:"https://solace.com/solace-agent-mesh-pilot-registration/",children:"solace.com/solace-agent-mesh-pilot-registration"}),"."]}),"\n",(0,s.jsx)(n.h2,{id:"enterprise-features",children:"Enterprise Features"}),"\n",(0,s.jsx)(n.p,{children:"The Enterprise version delivers several key capabilities that distinguish it from the Community edition."}),"\n",(0,s.jsx)(n.p,{children:"Authentication and authorization integrate with your existing identity systems through SSO, eliminating the need for separate credentials while maintaining security standards. You can configure role-based access control to implement granular authorization policies that determine which agents and resources each user can access through the Agent Mesh Gateways."}),"\n",(0,s.jsx)(n.p,{children:"Data management features help you optimize costs and improve accuracy. Smart filtering capabilities reduce unnecessary compute expenses while precise data governance helps prevent hallucinations by controlling what information reaches your language models."}),"\n",(0,s.jsx)(n.p,{children:"Observability tools provide complete visibility into your agent ecosystem. The built-in workflow viewer tracks LLM interactions and agent communications in real time, giving you the insights needed to monitor performance, diagnose issues, and understand system behavior."}),"\n",(0,s.jsx)(n.h2,{id:"getting-started-with-enterprise",children:"Getting Started with Enterprise"}),"\n",(0,s.jsx)(n.p,{children:"Setting up Agent Mesh Enterprise involves three main areas: installation, security configuration, and authentication setup."}),"\n",(0,s.jsx)(n.h3,{id:"installation",children:"Installation"}),"\n",(0,s.jsxs)(n.p,{children:["The Docker-based installation process downloads the enterprise image from the Solace Product Portal, loads it into your container environment, and launches it with the appropriate configuration for your deployment scenario. You can run Enterprise in development mode with an embedded broker for testing, or connect it to an external Solace broker for production deployments. For complete installation instructions, see ",(0,s.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/enterprise/installation",children:"Installing Agent Mesh Enterprise"}),"."]}),"\n",(0,s.jsx)(n.h3,{id:"access-control",children:"Access Control"}),"\n",(0,s.jsxs)(n.p,{children:["Role-based access control lets you define who can access which agents and features in your deployment. You create roles that represent job functions, assign permissions to those roles through scopes, and then assign roles to users. This three-tier model implements the principle of least privilege while simplifying administration. For guidance on planning and implementing RBAC, see ",(0,s.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/enterprise/rbac-setup-guide",children:"Setting Up RBAC"}),"."]}),"\n",(0,s.jsx)(n.h3,{id:"single-sign-on",children:"Single Sign-On"}),"\n",(0,s.jsxs)(n.p,{children:["SSO integration connects Agent Mesh Enterprise with your organization's identity provider, whether you use Azure, Google, Auth0, Okta, Keycloak, or another OAuth2-compliant system. The configuration process involves creating YAML files that define the authentication service and provider settings, then launching the container with the appropriate environment variables. For step-by-step configuration instructions, see ",(0,s.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/enterprise/single-sign-on",children:"Enabling SSO"}),"."]}),"\n",(0,s.jsx)(n.h2,{id:"whats-next",children:"What's Next"}),"\n",(0,s.jsx)(n.p,{children:"After you complete the initial setup, you can begin developing agents and gateways using the same patterns and tools available in the Community edition. The Enterprise features operate transparently\u2014your agents and tools work the same way, but with the added security, governance, and observability that production environments demand."})]})}function d(e={}){const{wrapper:n}={...(0,r.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:()=>o,x:()=>a});var i=t(6540);const s={},r=i.createContext(s);function o(e){const n=i.useContext(r);return i.useMemo((function(){return"function"==typeof e?e(n):{...n,...e}}),[n,e])}function a(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(s):e.components||s:o(e.components),i.createElement(r.Provider,{value:n},e.children)}}}]);

solace_agent_mesh/assets/docs/assets/js/dd81e2b8.d590bc9e.js

@@ -1 +0,0 @@
-"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[7669],{2260:(e,n,t)=>{t.r(n),t.d(n,{assets:()=>l,contentTitle:()=>r,default:()=>h,frontMatter:()=>a,metadata:()=>o,toc:()=>c});const o=JSON.parse('{"id":"documentation/developing/create-agents","title":"Creating Agents","description":"For a more comprehensive tutorial example, see the Build Your Own Agent guide.","source":"@site/docs/documentation/developing/create-agents.md","sourceDirName":"documentation/developing","slug":"/documentation/developing/create-agents","permalink":"/solace-agent-mesh/docs/documentation/developing/create-agents","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/developing/create-agents.md","tags":[],"version":"current","sidebarPosition":420,"frontMatter":{"title":"Creating Agents","sidebar_position":420},"sidebar":"docSidebar","previous":{"title":"Project Structure","permalink":"/solace-agent-mesh/docs/documentation/developing/structure"},"next":{"title":"Create Gateways","permalink":"/solace-agent-mesh/docs/documentation/developing/create-gateways"}}');var i=t(4848),s=t(8453);const a={title:"Creating Agents",sidebar_position:420},r=void 0,l={},c=[{value:"Understanding the Architecture",id:"understanding-the-architecture",level:2},{value:"Core Concepts",id:"core-concepts",level:2},{value:"Tools: The Building Blocks",id:"tools-the-building-blocks",level:3},{value:"Configuration File: The Blueprint",id:"configuration-file-the-blueprint",level:3},{value:"Tool Configuration: Customizing Behavior",id:"tool-configuration-customizing-behavior",level:3},{value:"ToolContext: Accessing Framework Services",id:"toolcontext-accessing-framework-services",level:3},{value:"Lifecycle Functions: Managing Resources",id:"lifecycle-functions-managing-resources",level:3},{value:"Creating Your First Agent: Step-by-Step",id:"creating-your-first-agent-step-by-step",level:2},{value:"Step 1: Initialize Your Agent Plugin",id:"step-1-initialize-your-agent-plugin",level:3},{value:"Step 2: Create Your Tool Functions",id:"step-2-create-your-tool-functions",level:3},{value:"Step 3: Configure Your Agent",id:"step-3-configure-your-agent",level:3},{value:"Step 4: Create Lifecycle Functions",id:"step-4-create-lifecycle-functions",level:3},{value:"Running Your Agent",id:"running-your-agent",level:2},{value:"Building and Installing the Plugin",id:"building-and-installing-the-plugin",level:3},{value:"Quick Debug Mode",id:"quick-debug-mode",level:3},{value:"Advanced Concepts",id:"advanced-concepts",level:2},{value:"Working with Artifacts",id:"working-with-artifacts",level:3},{value:"Using Multiple Tool Configurations",id:"using-multiple-tool-configurations",level:3},{value:"Quick Start: Using the CLI",id:"quick-start-using-the-cli",level:2},{value:"CLI Options",id:"cli-options",level:3},{value:"Best Practices",id:"best-practices",level:2},{value:"Tool Design",id:"tool-design",level:3},{value:"Configuration",id:"configuration",level:3},{value:"Testing",id:"testing",level:3}];function d(e){const n={a:"a",admonition:"admonition",code:"code",h2:"h2",h3:"h3",mermaid:"mermaid",p:"p",pre:"pre",...(0,s.R)(),...e.components};return(0,i.jsxs)(i.Fragment,{children:[(0,i.jsx)(n.admonition,{type:"tip",children:(0,i.jsxs)(n.p,{children:["For a more comprehensive tutorial example, see the ",(0,i.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/developing/tutorials/custom-agent",children:"Build Your Own Agent"})," guide.\nThis page walks through the fundamental concepts for creating agents in Agent Mesh."]})}),"\n",(0,i.jsx)(n.p,{children:"Agent Mesh is a powerful platform that enables you to create intelligent agents that can communicate with each other and perform complex tasks. At its core, Agent Mesh uses a tool-based architecture where LLM-powered agents are equipped with specific capabilities (tools) that they can use to accomplish user requests."}),"\n",(0,i.jsxs)(n.p,{children:["Before continuing with this tutorial, make sure you are familiar with the basic ",(0,i.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/components/agents",children:"agent concept"}),"."]}),"\n",(0,i.jsx)(n.p,{children:'This tutorial guides you through creating your first Agent Mesh agent from scratch. You will learn how to define tools as Python functions, configure an agent using YAML, and set up agent lifecycle functions. By the end of this tutorial, you should have a working "Hello World" agent that demonstrates the fundamental concepts of Agent Mesh agent development.'}),"\n",(0,i.jsx)(n.h2,{id:"understanding-the-architecture",children:"Understanding the Architecture"}),"\n",(0,i.jsx)(n.p,{children:"Before diving into implementation, you need to understand how the different components of an Agent Mesh agent work together. This architectural overview will help you see the big picture before you start building."}),"\n",(0,i.jsx)(n.mermaid,{value:"graph TD\n    subgraph Agent Configuration\n        direction LR\n        A[config.yaml] --\x3e|Defines| B(Agent Properties);\n        A --\x3e|Lists & Configures| C(Tools);\n    end\n\n    subgraph Agent Host\n        direction TB\n        D[Agent Mesh Host] --\x3e|Loads| A;\n        D --\x3e|Instantiates| E[Agent];\n        E --\x3e|Initializes with| F[Lifecycle Functions];\n    end\n\n    subgraph Tool Implementation\n        direction LR\n        G[Python Module tools.py] --\x3e|Contains| H[Tool Functions];\n    end\n\n    subgraph Execution Flow\n        direction TB\n        I[User Request] --\x3e J[LLM Orchestrator];\n        J --\x3e|Selects Tool| K{ADKToolWrapper};\n        K --\x3e|Calls| H;\n        H --\x3e|Accesses| L[ToolContext];\n        H --\x3e|Uses| M[tool_config];\n        H --\x3e|Returns Result| J;\n    end\n\n    C --\x3e|Wrapped by| K;\n\n    style A fill:#b60000,stroke:#faa,stroke-width:2px\n    style H fill:#b60000,stroke:#faa,stroke-width:2px\n    style F fill:#007000,stroke:#faa,stroke-width:2px"}),"\n",(0,i.jsx)(n.p,{children:"When a user sends a request to your agent, the LLM orchestrator analyzes the request and decides which tool to use. The framework wraps your tool functions and provides them with context and configuration. Your tool executes its logic and returns results to the LLM, which then formulates a response to the user."}),"\n",(0,i.jsx)(n.h2,{id:"core-concepts",children:"Core Concepts"}),"\n",(0,i.jsx)(n.p,{children:"Understanding these fundamental concepts will help you build effective agents."}),"\n",(0,i.jsx)(n.h3,{id:"tools-the-building-blocks",children:"Tools: The Building Blocks"}),"\n",(0,i.jsx)(n.p,{children:"Tools are the fundamental building blocks of Agent Mesh agents. Each tool is implemented as a Python function that performs a specific task. The LLM orchestrating your agent decides which tools to use based on the user's request and the tool descriptions you provide."}),"\n",(0,i.jsx)(n.p,{children:"Tools can process text and data, interact with external APIs, create and manipulate files, communicate with other agents, and access databases and services. You write tools as standard Python functions, and the framework handles the integration with the LLM."}),"\n",(0,i.jsx)(n.admonition,{type:"tip",children:(0,i.jsxs)(n.p,{children:["Agent Mesh provides a set of ",(0,i.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/components/builtin-tools/",children:"built-in tools"})," plus support for ",(0,i.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/developing/tutorials/mcp-integration",children:"model context protocol (MCP)"})," servers, which can be configured in the tools list of your agent configuration."]})}),"\n",(0,i.jsx)(n.h3,{id:"configuration-file-the-blueprint",children:"Configuration File: The Blueprint"}),"\n",(0,i.jsxs)(n.p,{children:["The ",(0,i.jsx)(n.code,{children:"config.yaml"})," (for plugin template) or ",(0,i.jsx)(n.code,{children:"agent-name.yaml"})," (for agent instances) file is the blueprint of your agent. This YAML file defines your agent's identity (name, description, and capabilities), model configuration (which LLM to use), tools list (which tools the agent can access and how they're configured), lifecycle functions (setup and cleanup procedures), framework services (session management, artifact storage, and so on), and ",(0,i.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/components/agents#agent-card",children:"agent card"})," (metadata describing the agent capabilities, skills and its visibility in the system)."]}),"\n",(0,i.jsx)(n.p,{children:"The configuration file connects all the pieces together. It tells the framework where to find your tool functions, how to configure them, and what instructions to give the LLM about your agent's purpose."}),"\n",(0,i.jsx)(n.h3,{id:"tool-configuration-customizing-behavior",children:"Tool Configuration: Customizing Behavior"}),"\n",(0,i.jsxs)(n.p,{children:["Within the ",(0,i.jsx)(n.code,{children:"tools"})," list in your YAML config, each tool can have its own ",(0,i.jsx)(n.code,{children:"tool_config"})," section. This allows you to configure the same tool function for different purposes, pass specific parameters to tool instances, and customize tool behavior per agent."]}),"\n",(0,i.jsx)(n.p,{children:"This design pattern enables code reuse. You can write a single generic tool function and configure it multiple times with different parameters to serve different purposes within the same agent."}),"\n",(0,i.jsxs)(n.admonition,{type:"info",children:[(0,i.jsxs)(n.p,{children:['For tools of type "python", you can also use the ',(0,i.jsx)(n.code,{children:"tool_name"})," and ",(0,i.jsx)(n.code,{children:"tool_description"})," to overwrite the function name and description in the tool docstring."]}),(0,i.jsx)(n.p,{children:"This is useful when using a generic tool function for multiple purposes, allowing you to provide a more descriptive name and description for each instance."})]}),"\n",(0,i.jsx)(n.h3,{id:"toolcontext-accessing-framework-services",children:"ToolContext: Accessing Framework Services"}),"\n",(0,i.jsxs)(n.p,{children:["The ",(0,i.jsx)(n.code,{children:"ToolContext"})," object (passed as one of the arguments to your tool function) provides your tools with access to Agent Mesh core services. Through this context object, your tools can access structured logging for debugging and monitoring, the artifact service for file storage and retrieval, session information about the current user and session context, and agent state for sharing data between tool calls."]}),"\n",(0,i.jsx)(n.p,{children:"The framework automatically provides this context to your tool functions. You don't need to create or manage it yourself."}),"\n",(0,i.jsx)(n.h3,{id:"lifecycle-functions-managing-resources",children:"Lifecycle Functions: Managing Resources"}),"\n",(0,i.jsxs)(n.p,{children:["Lifecycle functions allow you to manage resources that should persist for the agent's lifetime. The ",(0,i.jsx)(n.code,{children:"agent_init_function"})," runs when the agent starts (for example, to establish database connections), and the ",(0,i.jsx)(n.code,{children:"agent_cleanup_function"})," runs when the agent shuts down (for example, to close connections gracefully)."]}),"\n",(0,i.jsx)(n.p,{children:"These functions are optional but recommended for managing resources effectively. They ensure that your agent properly initializes any required resources and cleans them up when shutting down."}),"\n",(0,i.jsx)(n.admonition,{type:"note",children:(0,i.jsx)(n.p,{children:"Lifecycle functions are optional but recommended for managing resources effectively."})}),"\n",(0,i.jsx)(n.h2,{id:"creating-your-first-agent-step-by-step",children:"Creating Your First Agent: Step-by-Step"}),"\n",(0,i.jsx)(n.p,{children:'Now that you understand the core concepts, you can create a simple agent that demonstrates how these pieces work together. You will build a "Hello World" agent that can greet users and say goodbye.'}),"\n",(0,i.jsx)(n.h3,{id:"step-1-initialize-your-agent-plugin",children:"Step 1: Initialize Your Agent Plugin"}),"\n",(0,i.jsxs)(n.p,{children:["You can create an agent either by using the ",(0,i.jsx)(n.code,{children:"sam add agent"})," command or by creating a new plugin of type agent with ",(0,i.jsx)(n.code,{children:"sam plugin create my-hello-agent --type agent"}),"."]}),"\n",(0,i.jsx)(n.admonition,{type:"tip",children:(0,i.jsxs)(n.p,{children:["For information and recommendations about these options, see ",(0,i.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/components/plugins#agent-or-plugin-which-to-use",children:(0,i.jsx)(n.code,{children:"Agent or Plugin: Which To use?"})}),"."]})}),"\n",(0,i.jsxs)(n.p,{children:["In this tutorial, you create a new agent by creating a new plugin of type agent. For an example of custom agents, see ",(0,i.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/developing/tutorials/custom-agent",children:"Build Your Own Agent"})," guide."]}),"\n",(0,i.jsx)(n.p,{children:"Although the directory structure for plugins is slightly different than the one for agents, both require a YAML configuration file, and a python module with the tools and lifecycle functions you want."}),"\n",(0,i.jsx)(n.p,{children:"To create a new agent plugin, run the following command:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:"sam plugin create my-hello-agent --type agent\n"})}),"\n",(0,i.jsx)(n.p,{children:"Follow the prompts to set up your agent. The prompts create a new directory structure for your agent:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{children:"my-hello-agent/\n\u251c\u2500\u2500 src/\n\u2502   \u2514\u2500\u2500 my_hello_agent/\n\u2502       \u251c\u2500\u2500 __init__.py\n\u2502       \u251c\u2500\u2500 tools.py\n\u2502       \u2514\u2500\u2500 lifecycle.py # This file won't be automatically created\n\u251c\u2500\u2500 config.yaml\n\u251c\u2500\u2500 pyproject.toml\n\u2514\u2500\u2500 README.md\n"})}),"\n",(0,i.jsx)(n.mermaid,{value:"graph TD\n    A[my-hello-agent/] --\x3e B[src/]\n    A --\x3e C[config.yaml]\n    A --\x3e D[pyproject.toml]\n    A --\x3e E[README.md]\n    \n    B --\x3e F[my_hello_agent/]\n    F --\x3e G[__init__.py]\n    F --\x3e H[tools.py]\n    F --\x3e I[lifecycle.py]\n    \n    style C fill:#b60000,stroke:#333,stroke-width:2px\n    style H fill:#b60000,stroke:#333,stroke-width:2px\n    style I fill:#007000,stroke:#333,stroke-width:2px"}),"\n",(0,i.jsxs)(n.p,{children:["The ",(0,i.jsx)(n.code,{children:"config.yaml"})," file will contain your agent configuration, ",(0,i.jsx)(n.code,{children:"tools.py"})," will contain your tool functions, and ",(0,i.jsx)(n.code,{children:"lifecycle.py"})," (which you'll create manually) will contain your lifecycle functions. The ",(0,i.jsx)(n.code,{children:"pyproject.toml"})," file manages your plugin's dependencies and metadata."]}),"\n",(0,i.jsx)(n.h3,{id:"step-2-create-your-tool-functions",children:"Step 2: Create Your Tool Functions"}),"\n",(0,i.jsx)(n.p,{children:"Tools are where your agent's actual capabilities live. You will create two simple tools: one to greet users and one to say goodbye."}),"\n",(0,i.jsxs)(n.p,{children:["Create your tool functions in the ",(0,i.jsx)(n.code,{children:"src/my_hello_agent/tools.py"})," file. For a complete guide on creating python tools, see our ",(0,i.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/developing/creating-python-tools",children:"Creating Python Tools"})," documentation."]}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-python",children:'# src/my_hello_agent/tools.py\n"""\nTools for the Hello World agent.\n"""\n\nfrom typing import Any, Dict, Optional\nfrom google.adk.tools import ToolContext\nfrom solace_ai_connector.common.log import log\n\n\nasync def hello_tool(\n    name: str,\n    tool_context: Optional[ToolContext] = None,\n    tool_config: Optional[Dict[str, Any]] = None\n) -> Dict[str, Any]:\n    """\n    Greets a user with a personalized message.\n    \n    Args:\n        name: The name of the person to greet\n    \n    Returns:\n        A dictionary with the greeting message\n    """\n    log_identifier = "[HelloTool]"\n    log.info(f"{log_identifier} Greeting user: {name}")\n    \n    # Get configuration from tool_config\n    greeting_prefix = "Hello"\n    if tool_config:\n        greeting_prefix = tool_config.get("greeting_prefix", "Hello")\n    \n    # Create the greeting message\n    greeting_message = f"{greeting_prefix}, {name}! Welcome to Agent Mesh!"\n    \n    log.info(f"{log_identifier} Generated greeting: {greeting_message}")\n    \n    return {\n        "status": "success",\n        "message": greeting_message,\n        "greeted_name": name\n    }\n\n\nasync def farewell_tool(\n    name: str,\n    tool_context: Optional[ToolContext] = None,\n    tool_config: Optional[Dict[str, Any]] = None\n) -> Dict[str, Any]:\n    """\n    Says goodbye to a user.\n    \n    Args:\n        name: The name of the person to say goodbye to\n    \n    Returns:\n        A dictionary with the farewell message\n    """\n    log_identifier = "[FarewellTool]"\n    log.info(f"{log_identifier} Saying goodbye to user: {name}")\n    \n    # Get configuration from tool_config\n    farewell_prefix = "Goodbye"\n    if tool_config:\n        farewell_prefix = tool_config.get("farewell_prefix", "Goodbye")\n    \n    # Create the farewell message\n    farewell_message = f"{farewell_prefix}, {name}! Thanks for using Agent Mesh!"\n    \n    log.info(f"{log_identifier} Generated farewell: {farewell_message}")\n    \n    return {\n        "status": "success",\n        "message": farewell_message,\n        "farewell_name": name\n    }\n'})}),"\n",(0,i.jsxs)(n.p,{children:["Let's examine what makes these tool functions work. All tool functions must be asynchronous (defined with ",(0,i.jsx)(n.code,{children:"async def"}),") because the framework uses asynchronous execution. The framework automatically provides two special parameters: ",(0,i.jsx)(n.code,{children:"tool_context"})," gives you access to framework services like logging and artifact storage, and ",(0,i.jsx)(n.code,{children:"tool_config"})," contains any custom configuration you define in your YAML file."]}),"\n",(0,i.jsxs)(n.p,{children:["The function signature includes regular parameters (like ",(0,i.jsx)(n.code,{children:"name"}),") that the LLM will provide when calling the tool. The docstring is important because the LLM uses it to understand what the tool does and when to use it. You should always write clear, descriptive docstrings."]}),"\n",(0,i.jsxs)(n.p,{children:["The tool retrieves its configuration from the ",(0,i.jsx)(n.code,{children:"tool_config"})," dictionary. This allows you to customize the tool's behavior without changing the code. In this example, you can configure different greeting prefixes for different use cases."]}),"\n",(0,i.jsxs)(n.p,{children:["The tool returns a dictionary with at least a ",(0,i.jsx)(n.code,{children:"status"})," field. This structured format makes it easy for the LLM to understand the result. You can include any additional data that might be useful for the LLM or for debugging."]}),"\n",(0,i.jsx)(n.p,{children:"The logging statements help you track what your tool is doing. The framework provides a logger that you should use for consistent logging across your agent."}),"\n",(0,i.jsx)(n.h3,{id:"step-3-configure-your-agent",children:"Step 3: Configure Your Agent"}),"\n",(0,i.jsxs)(n.p,{children:["Now you need to tell the framework about your agent and its tools. Create the main configuration file for your agent in ",(0,i.jsx)(n.code,{children:"config.yaml"}),":"]}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-yaml",children:'# File: config.yaml (at root of project directory)\n# ... (additional services and configurations)\n\napps:\n  - name: my-hello-agent\n    app_module: solace_agent_mesh.agent.sac.app \n    broker:\n      # Can be found in configs/shared_config.yaml after running sam init\n      <<: *broker_connection\n    \n    # Agent-specific configuration\n    app_config:\n      # Basic agent identity\n      namespace: ${NAMESPACE} \n      supports_streaming: true \n      agent_name: "HelloAgent"\n      display_name: "Hello World Agent"\n      \n      # LLM model configuration\n      model: *general_model \n      \n      # Agent instructions (system prompt)\n      instruction: |\n        You are a friendly Hello World agent. Your purpose is to greet users and \n        demonstrate the capabilities of Agent Mesh. You can:\n        \n        1. Greet users with personalized messages using the hello_tool\n        2. Say goodbye to users using the farewell_tool\n        \n        Always be polite and helpful. When greeting someone, ask for their name \n        if they haven\'t provided it.\n      \n      # Lifecycle functions\n      agent_init_function:\n        module: "my_hello_agent.lifecycle" # This should point to your lifecycle python module\n        name: "initialize_hello_agent"\n        base_path: .\n        config:\n          startup_message: "Hello Agent is starting up!"\n          log_level: "INFO"\n      \n      agent_cleanup_function:\n        module: "my_hello_agent.lifecycle"\n        base_path: .\n        name: "cleanup_hello_agent"\n      \n      # Tools configuration\n      tools:\n        # Hello tool with custom greeting\n        - tool_type: python\n          component_module: "my_hello_agent.tools"\n          component_base_path: .\n          function_name: "hello_tool"\n          tool_name: "greet_user" # Renaming the tool, must use this name in the agent card\n          tool_config:\n            greeting_prefix: "Hello there"\n        \n        # Farewell tool with custom farewell\n        - tool_type: python\n          component_module: "my_hello_agent.tools"\n          component_base_path: .\n          function_name: "farewell_tool"\n          tool_name: "say_goodbye"\n          tool_config:\n            farewell_prefix: "See you later"\n        \n        # Built-in artifact tools for file operations\n        - tool_type: builtin-group\n          group_name: "artifact_management"\n      \n      # Agent card (describes the agent\'s capabilities)\n      agent_card:\n        description: "A friendly Hello World agent that demonstrates Agent Mesh capabilities"\n        defaultInputModes: ["text"]\n        defaultOutputModes: ["text"]\n        skills:\n          - id: "greet_user"\n            name: "Greet User"\n            description: "Greets users with personalized messages"\n          - id: "say_goodbye"\n            name: "Say Goodbye"\n            description: "Says goodbye to users"\n          - id: "file_operations"\n            name: "File Operations"\n            description: "Create, read, and manage files and artifacts"\n      \n      # Session and artifact services\n      session_service: *default_session_service\n      artifact_service: *default_artifact_service\n# ... (additional services and configurations)\n'})}),"\n",(0,i.jsx)(n.p,{children:"This configuration file connects all the pieces of your agent. Let's examine each section to understand its purpose."}),"\n",(0,i.jsxs)(n.p,{children:["The ",(0,i.jsx)(n.code,{children:"namespace"})," uniquely identifies your agent in the mesh. This allows multiple agents to coexist and communicate. The ",(0,i.jsx)(n.code,{children:"agent_name"})," and ",(0,i.jsx)(n.code,{children:"display_name"})," provide human-readable identifiers for your agent."]}),"\n",(0,i.jsxs)(n.p,{children:["The ",(0,i.jsx)(n.code,{children:"model"})," section specifies which LLM to use. The ",(0,i.jsx)(n.code,{children:"*general_model"})," reference points to a model configuration defined elsewhere in your configuration files (typically in ",(0,i.jsx)(n.code,{children:"shared_config.yaml"}),"). This allows you to centrally manage model configurations across multiple agents."]}),"\n",(0,i.jsxs)(n.p,{children:["The ",(0,i.jsx)(n.code,{children:"instruction"})," field contains the system prompt that defines your agent's personality and behavior. This text tells the LLM what role it should play and what capabilities it has. You\nshould write clear, specific instructions that help the LLM understand its role."]}),"\n",(0,i.jsxs)(n.p,{children:["The ",(0,i.jsx)(n.code,{children:"tools"})," section lists all the tools your agent can use. Each tool entry specifies the ",(0,i.jsx)(n.code,{children:"tool_type"})," (python for custom functions, builtin-group for built-in tools), the ",(0,i.jsx)(n.code,{children:"component_module"})," that contains the function, the ",(0,i.jsx)(n.code,{children:"function_name"})," to call, and optionally a ",(0,i.jsx)(n.code,{children:"tool_name"})," to rename the tool for the LLM. The ",(0,i.jsx)(n.code,{children:"tool_config"})," section passes custom configuration to each tool instance. This is where you provide the ",(0,i.jsx)(n.code,{children:"greeting_prefix"})," and ",(0,i.jsx)(n.code,{children:"farewell_prefix"})," values that your tool functions read."]}),"\n",(0,i.jsxs)(n.p,{children:["Notice that you can configure the same function multiple times with different names and configurations. The ",(0,i.jsx)(n.code,{children:"hello_tool"})," function is configured as ",(0,i.jsx)(n.code,{children:"greet_user"})," with one greeting prefix, but you could add another configuration with a different prefix for formal greetings."]}),"\n",(0,i.jsxs)(n.p,{children:["The ",(0,i.jsx)(n.code,{children:"agent_card"})," section describes your agent's capabilities to other parts of the system. The ",(0,i.jsx)(n.code,{children:"skills"})," list should match the tools you've configured. Each skill has an ",(0,i.jsx)(n.code,{children:"id"})," that corresponds to a tool name, making it discoverable by other agents and the user interface."]}),"\n",(0,i.jsxs)(n.p,{children:["The ",(0,i.jsx)(n.code,{children:"session_service"})," and ",(0,i.jsx)(n.code,{children:"artifact_service"})," references connect your agent to framework services for managing user sessions and storing files. These services are typically defined in your shared configuration."]}),"\n",(0,i.jsx)(n.h3,{id:"step-4-create-lifecycle-functions",children:"Step 4: Create Lifecycle Functions"}),"\n",(0,i.jsx)(n.p,{children:"Lifecycle functions manage resources that should persist for your agent's lifetime. Although these functions are optional, they demonstrate how to properly initialize and clean up resources."}),"\n",(0,i.jsx)(n.p,{children:"The lifecycle file is not automatically created, so you need to create it manually:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:"touch src/my_hello_agent/lifecycle.py\n"})}),"\n",(0,i.jsx)(n.p,{children:"Now add your lifecycle functions:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-python",children:'# src/my_hello_agent/lifecycle.py\n"""\nLifecycle functions for the Hello World agent.\n"""\n\nfrom typing import Any, Dict\nfrom pydantic import BaseModel, Field\nfrom solace_ai_connector.common.log import log\n\n\nclass HelloAgentInitConfig(BaseModel):\n    """\n    Configuration model for the Hello Agent initialization.\n    """\n    startup_message: str = Field(description="Message to log on startup")\n    log_level: str = Field(default="INFO", description="Logging level for the agent")\n\n\ndef initialize_hello_agent(host_component: Any, init_config: HelloAgentInitConfig):\n    """\n    Initializes the Hello World agent.\n    \n    Args:\n        host_component: The agent host component\n        init_config: Validated initialization configuration\n    """\n    log_identifier = f"[{host_component.agent_name}:init]"\n    log.info(f"{log_identifier} Starting Hello Agent initialization...")\n    \n    # Log the startup message from config\n    log.info(f"{log_identifier} {init_config.startup_message}")\n    \n    # You could initialize shared resources here, such as:\n    # - Database connections\n    # - API clients\n    # - Caches or shared data structures\n    \n    # Store any shared state in the agent\n    host_component.set_agent_specific_state("initialized_at", "2024-01-01T00:00:00Z")\n    host_component.set_agent_specific_state("greeting_count", 0)\n    \n    log.info(f"{log_identifier} Hello Agent initialization completed successfully")\n\n\ndef cleanup_hello_agent(host_component: Any):\n    """\n    Cleans up resources when the Hello World agent shuts down.\n    \n    Args:\n        host_component: The agent host component\n    """\n    log_identifier = f"[{host_component.agent_name}:cleanup]"\n    log.info(f"{log_identifier} Starting Hello Agent cleanup...")\n    \n    # Retrieve any shared state\n    greeting_count = host_component.get_agent_specific_state("greeting_count", 0)\n    log.info(f"{log_identifier} Agent processed {greeting_count} greetings during its lifetime")\n    \n    # Clean up resources here, such as:\n    # - Closing database connections\n    # - Shutting down background tasks\n    # - Saving final state\n    \n    log.info(f"{log_identifier} Hello Agent cleanup completed")\n'})}),"\n",(0,i.jsxs)(n.p,{children:["The lifecycle functions follow a specific pattern. The ",(0,i.jsx)(n.code,{children:"initialize_hello_agent"})," function receives two parameters: ",(0,i.jsx)(n.code,{children:"host_component"})," provides access to the agent instance and its methods, and ",(0,i.jsx)(n.code,{children:"init_config"})," contains the validated configuration from your YAML file's ",(0,i.jsx)(n.code,{children:"agent_init_function.config"})," section."]}),"\n",(0,i.jsxs)(n.p,{children:["Using a Pydantic model for ",(0,i.jsx)(n.code,{children:"init_config"})," provides automatic validation. The framework validates your configuration against this model when the agent starts, catching configuration errors early. This is better than manually checking configuration values in your code."]}),"\n",(0,i.jsxs)(n.p,{children:["The ",(0,i.jsx)(n.code,{children:"host_component"})," object provides methods for managing agent state. The ",(0,i.jsx)(n.code,{children:"set_agent_specific_state"})," method stores data that persists across tool calls within the same agent instance. This is useful for tracking statistics, caching data, or maintaining connections. The state is specific to this agent instance and is not shared with other agents."]}),"\n",(0,i.jsxs)(n.p,{children:["The ",(0,i.jsx)(n.code,{children:"cleanup_hello_agent"})," function runs when the agent shuts down. This is your opportunity to gracefully close connections, save final state, or perform any other cleanup tasks. The function receives only the ",(0,i.jsx)(n.code,{children:"host_component"})," parameter because cleanup typically doesn't need additional configuration."]}),"\n",(0,i.jsx)(n.p,{children:"In this example, you retrieve the greeting count from the agent state and log it. In a real application, you might close database connections, flush caches to disk, or notify other services that the agent is shutting down."}),"\n",(0,i.jsx)(n.h2,{id:"running-your-agent",children:"Running Your Agent"}),"\n",(0,i.jsx)(n.p,{children:"Now that you have created all the necessary components, you can run your agent. The process involves building your plugin and adding it to your Agent Mesh project."}),"\n",(0,i.jsx)(n.h3,{id:"building-and-installing-the-plugin",children:"Building and Installing the Plugin"}),"\n",(0,i.jsxs)(n.p,{children:["To properly instantiate your plugin agent, first build the plugin. The following command will produce a python wheel file under ",(0,i.jsx)(n.code,{children:"dist"})," directory:"]}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:"sam plugin build\n"})}),"\n",(0,i.jsx)(n.p,{children:"This command packages your agent code, configuration, and dependencies into a distributable wheel file. The wheel file is a standard Python package format that can be installed into any Python environment."}),"\n",(0,i.jsxs)(n.p,{children:["Check into ",(0,i.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/getting-started/try-agent-mesh",children:"your Agent Mesh project directory"}),", and add the plugin wheel with a given name:"]}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:"sam plugin add my-first-weather-agent --plugin PATH/TO/weather-agent/dist/weather-agent.whl\n"})}),"\n",(0,i.jsx)(n.admonition,{type:"note",children:(0,i.jsxs)(n.p,{children:["Using the ",(0,i.jsx)(n.code,{children:"sam plugin add"})," command installs your plugin as a python dependency into your python environment.\nThis also means changing the source code without reinstalling the plugin will not reflect the changes."]})}),"\n",(0,i.jsxs)(n.p,{children:["The ",(0,i.jsx)(n.code,{children:"sam plugin add"})," command does several things. It installs your plugin package into your Python environment, making your tool functions and lifecycle functions importable. It also creates a configuration file in your project's ",(0,i.jsx)(n.code,{children:"configs/agents/"})," directory that references your plugin. This configuration file is what the framework loads when you run your agent."]}),"\n",(0,i.jsx)(n.p,{children:"Now, you can run the complete Agent Mesh application along with your newly added agent:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:"sam run\n"})}),"\n",(0,i.jsxs)(n.p,{children:["Alternatively, only run the newly added agent using ",(0,i.jsx)(n.code,{children:"sam run configs/agents/my-first-weather-agent.yaml"})]}),"\n",(0,i.jsx)(n.h3,{id:"quick-debug-mode",children:"Quick Debug Mode"}),"\n",(0,i.jsxs)(n.admonition,{title:"Quick Debug",type:"tip",children:[(0,i.jsxs)(n.p,{children:["For debugging or isolated development testing, you can run your agent from the ",(0,i.jsx)(n.code,{children:"src"})," directory directly using the Agent Mesh CLI."]}),(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:"cd src\nsam run ../config.yaml\n"})}),(0,i.jsx)(n.p,{children:"Changing to the src directory allows the module path to be set correctly so that Agent Mesh can find your functions without your having to install them in your python environment as a plugin package."})]}),"\n",(0,i.jsx)(n.p,{children:"This quick debug mode is useful during development because you can make changes to your code and immediately test them without rebuilding and reinstalling the plugin. However, you should always test with the full plugin installation process before deploying to production."}),"\n",(0,i.jsx)(n.h2,{id:"advanced-concepts",children:"Advanced Concepts"}),"\n",(0,i.jsx)(n.p,{children:"Once you understand the basics, you can explore more advanced patterns for building sophisticated agents."}),"\n",(0,i.jsx)(n.h3,{id:"working-with-artifacts",children:"Working with Artifacts"}),"\n",(0,i.jsx)(n.p,{children:"The artifact service allows your tools to create, store, and retrieve files. You can enhance your hello tool to save greetings to a file using the artifact service:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-python",children:'\nfrom datetime import datetime\nfrom solace_agent_mesh.agent.utils.artifact_helpers import save_artifact_with_metadata\n\nasync def hello_tool_with_artifact(\n    name: str,\n    save_to_file: bool = False,\n    tool_context: Optional[ToolContext] = None,\n    tool_config: Optional[Dict[str, Any]] = None\n) -> Dict[str, Any]:\n    """\n    Greets a user and optionally saves the greeting to a file.\n    """\n    log_identifier = "[HelloToolWithArtifact]"\n    \n    # Generate greeting (same as before)\n    greeting_prefix = tool_config.get("greeting_prefix", "Hello") if tool_config else "Hello"\n    greeting_message = f"{greeting_prefix}, {name}! Welcome to Agent Mesh!"\n    \n    result = {\n        "status": "success",\n        "message": greeting_message,\n        "greeted_name": name\n    }\n    \n    # Save to artifact if requested\n    if save_to_file and tool_context:\n        try:\n            # Prepare content\n            timestamp = datetime.now(timezone.utc)\n            filename = f"greeting_{name}_{timestamp}.txt"\n            content = f"Greeting: {greeting_message}\\nTimestamp: {timestamp}\\n"\n            \n            # Save artifact\n            artifact_service = tool_context._invocation_context.artifact_service\n            await save_artifact_with_metadata(\n                artifact_service=artifact_service,\n                app_name=tool_context._invocation_context.app_name,\n                user_id=tool_context._invocation_context.user_id,\n                session_id=tool_context._invocation_context.session.id,\n                filename=filename,\n                content_bytes=content.encode(\'utf-8\'),\n                mime_type="application/json",\n                metadata_dict={\n                    "description": "Greeting message",\n                    "source": "Greeting Agent",\n                },\n                timestamp=timestamp\n            )\n            \n            result["artifact_saved"] = filename\n            log.info(f"{log_identifier} Saved greeting to artifact: {filename}")\n        \n        except Exception as e:\n            log.error(f"{log_identifier} Failed to save artifact: {e}")\n            result["artifact_error"] = str(e)\n    \n    return result\n'})}),"\n",(0,i.jsxs)(n.p,{children:["This enhanced tool demonstrates several important concepts. The ",(0,i.jsx)(n.code,{children:"save_to_file"})," parameter allows the LLM to decide whether to save the greeting based on the user's request. This gives your agent flexibility in how it uses the tool."]}),"\n",(0,i.jsxs)(n.p,{children:["The ",(0,i.jsx)(n.code,{children:"tool_context"})," object provides access to the artifact service through its ",(0,i.jsx)(n.code,{children:"_invocation_context"})," property. The invocation context contains information about the current execution environment, including the user ID, session ID, and app name. These identifiers are necessary for properly organizing and retrieving artifacts."]}),"\n",(0,i.jsxs)(n.p,{children:["The ",(0,i.jsx)(n.code,{children:"save_artifact_with_metadata"})," helper function handles the details of saving files to the artifact service. You provide the content as bytes, specify a MIME type, and include metadata that describes the artifact. The metadata makes it easier to search for and manage artifacts later."]}),"\n",(0,i.jsx)(n.p,{children:"Error handling is important when working with external services. The try-except block ensures that if artifact saving fails, your tool can still return a successful greeting. The error is logged and included in the result, allowing the LLM to inform the user about the issue."}),"\n",(0,i.jsx)(n.h3,{id:"using-multiple-tool-configurations",children:"Using Multiple Tool Configurations"}),"\n",(0,i.jsx)(n.p,{children:"You can configure the same tool function multiple times with different settings. This pattern is useful when you want to provide the LLM with multiple variations of the same capability:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-yaml",children:'tools:\n  # Formal greeting\n  - tool_type: python\n    component_module: "my_hello_agent.tools"\n    function_name: "hello_tool"\n    tool_name: "formal_greeting"\n    tool_config:\n      greeting_prefix: "Good day"\n  \n  # Casual greeting\n  - tool_type: python\n    component_module: "my_hello_agent.tools"\n    function_name: "hello_tool"\n    tool_name: "casual_greeting"\n    tool_config:\n      greeting_prefix: "Hey there"\n  \n  # Enthusiastic greeting\n  - tool_type: python\n    component_module: "my_hello_agent.tools"\n    function_name: "hello_tool"\n    tool_name: "enthusiastic_greeting"\n    tool_config:\n      greeting_prefix: "Hello and welcome"\n'})}),"\n",(0,i.jsx)(n.p,{children:"This configuration creates three different tools from the same function. The LLM sees these as distinct capabilities and can choose the appropriate greeting style based on the context of the conversation. For example, it might use the formal greeting for business contexts and the casual greeting for friendly conversations."}),"\n",(0,i.jsxs)(n.p,{children:["Each tool configuration should have a unique ",(0,i.jsx)(n.code,{children:"tool_name"})," and should be listed in your agent card's skills section. This makes each variation discoverable and allows you to provide specific descriptions for each greeting style."]}),"\n",(0,i.jsx)(n.h2,{id:"quick-start-using-the-cli",children:"Quick Start: Using the CLI"}),"\n",(0,i.jsx)(n.p,{children:"If you want to get started quickly without manually creating all the files, you can use the Agent Mesh CLI to generate the basic structure:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:"sam add agent my-first-agent\n"})}),"\n",(0,i.jsxs)(n.p,{children:["This command launches an interactive setup (or use ",(0,i.jsx)(n.code,{children:"--gui"})," for browser-based configuration) that generates the necessary files and configuration, and sets up the basic agent structure."]}),"\n",(0,i.jsx)(n.p,{children:"Note that creating an agent as a plugin is preferred over creating an agent directly because plugins are more portable and easier to share."}),"\n",(0,i.jsx)(n.h3,{id:"cli-options",children:"CLI Options"}),"\n",(0,i.jsx)(n.p,{children:"You can customize the agent creation with provided CLI options. For a complete list of options, run:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:"sam add agent --help\n"})}),"\n",(0,i.jsx)(n.p,{children:"The CLI tool is useful for quickly scaffolding new agents, but understanding the manual process helps you customize and troubleshoot your agents more effectively."}),"\n",(0,i.jsx)(n.h2,{id:"best-practices",children:"Best Practices"}),"\n",(0,i.jsx)(n.p,{children:"Following these best practices will help you create robust, maintainable agents."}),"\n",(0,i.jsx)(n.h3,{id:"tool-design",children:"Tool Design"}),"\n",(0,i.jsx)(n.p,{children:"Each tool should do one thing well. This single responsibility principle makes your tools easier to test, debug, and reuse. Instead of creating one large tool that handles multiple tasks, create several focused tools that each handle a specific task."}),"\n",(0,i.jsx)(n.p,{children:"Write detailed docstrings for your tools. The LLM uses these docstrings to understand what each tool does and when to use it. Include descriptions of all parameters, return values, and any important behavior or limitations."}),"\n",(0,i.jsx)(n.p,{children:"Always return structured error responses. When something goes wrong, your tool should return a dictionary with a status field indicating failure and a message explaining what went wrong. This allows the LLM to understand the error and potentially retry with different parameters or inform the user about the issue."}),"\n",(0,i.jsx)(n.p,{children:"Use consistent logging for debugging and monitoring. Log important events, parameter values, and results. This makes it much easier to troubleshoot issues when your agent is running in production."}),"\n",(0,i.jsx)(n.h3,{id:"configuration",children:"Configuration"}),"\n",(0,i.jsx)(n.p,{children:"Use environment variables for sensitive data like API keys, database passwords, and other credentials. Never hardcode sensitive information in your configuration files or source code."}),"\n",(0,i.jsx)(n.p,{children:"Use Pydantic models for configuration validation. This catches configuration errors early and provides clear error messages when something is wrong. It also serves as documentation for what configuration options are available."}),"\n",(0,i.jsx)(n.p,{children:"Comment your configuration files thoroughly. YAML files can become complex, and clear comments help other developers (and your future self) understand what each section does and why it's configured that way."}),"\n",(0,i.jsx)(n.h3,{id:"testing",children:"Testing"}),"\n",(0,i.jsxs)(n.p,{children:["Write unit tests for your tool functions independently. Test them with various inputs, including edge cases and error conditions. Mock the ",(0,i.jsx)(n.code,{children:"tool_context"})," and ",(0,i.jsx)(n.code,{children:"tool_config"})," parameters to isolate your tool logic from the framework."]}),"\n",(0,i.jsx)(n.p,{children:"Write integration tests that test your agent with real Agent Mesh infrastructure. These tests verify that your configuration is correct and that your tools work properly when called by the LLM."}),"\n",(0,i.jsx)(n.p,{children:"Mock external dependencies for reliable testing. If your tools call external APIs or databases, create mock versions for testing. This makes your tests faster and more reliable because they don't depend on external services being available."})]})}function h(e={}){const{wrapper:n}={...(0,s.R)(),...e.components};return n?(0,i.jsx)(n,{...e,children:(0,i.jsx)(d,{...e})}):d(e)}},8453:(e,n,t)=>{t.d(n,{R:()=>a,x:()=>r});var o=t(6540);const i={},s=o.createContext(i);function a(e){const n=o.useContext(s);return o.useMemo((function(){return"function"==typeof e?e(n):{...n,...e}}),[n,e])}function r(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(i):e.components||i:a(e.components),o.createElement(s.Provider,{value:n},e.children)}}}]);

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

@@ -1 +0,0 @@
-"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.6b9493d0.js

@@ -1 +0,0 @@
-"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[7798],{7098:(e,n,i)=>{i.r(n),i.d(n,{assets:()=>d,contentTitle:()=>a,default:()=>h,frontMatter:()=>s,metadata:()=>t,toc:()=>l});const t=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=i(4848),r=i(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:t}=n;return t||function(e,n){throw new Error("Expected "+(n?"component":"object")+" `"+e+"` to be defined: you likely forgot to import, pass, or provide it.")}("Details",!0),(0,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)(t,{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)(t,{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:i(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 ",(0,o.jsx)(n.a,{href:"../deploying/debugging",children:"Diagnosing and Resolving Problems"}),"."]})]})}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,i)=>{i.d(n,{A:()=>t});const t=i.p+"assets/images/sam-enterprise-credentials-b269f095349473118b2b33bdfcc40122.png"},8453:(e,n,i)=>{i.d(n,{R:()=>s,x:()=>a});var t=i(6540);const o={},r=t.createContext(o);function s(e){const n=t.useContext(r);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(o):e.components||o:s(e.components),t.createElement(r.Provider,{value:n},e.children)}}}]);

solace_agent_mesh/assets/docs/assets/js/e92d0134.4f395c6b.js

@@ -1 +0,0 @@
-"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.admonition,{title:"Complementary Tools",type:"tip",children:(0,s.jsxs)(i.p,{children:["The observability features described here focus on runtime behavior and message flows. For information about application logging, see ",(0,s.jsx)(i.a,{href:"/solace-agent-mesh/docs/documentation/deploying/logging",children:"Logging Configuration"}),"."]})}),"\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.720d2ef2.js

@@ -1 +0,0 @@
-"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},{"type":"link","label":"Logging","href":"/solace-agent-mesh/docs/documentation/deploying/logging","docId":"documentation/deploying/logging","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/logging":{"id":"documentation/deploying/logging","title":"Logging","description":"Agent Mesh uses Python\'s built-in logging module to provide flexible and powerful logging capabilities.","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

@@ -1 +0,0 @@
-"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)}}}]);