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

solace_agent_mesh/assets/docs/assets/js/dd81e2b8.b682e9c2.js

@@ -0,0 +1 @@
+"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":"Creating Custom 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/de5f4c65.e8241890.js

@@ -0,0 +1 @@
+"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[6963],{7586:(e,a,n)=>{n.r(a),n.d(a,{assets:()=>l,contentTitle:()=>r,default:()=>h,frontMatter:()=>o,metadata:()=>t,toc:()=>c});const t=JSON.parse('{"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.","source":"@site/docs/documentation/developing/tutorials/sql-database.md","sourceDirName":"documentation/developing/tutorials","slug":"/documentation/developing/tutorials/sql-database","permalink":"/solace-agent-mesh/docs/documentation/developing/tutorials/sql-database","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/developing/tutorials/sql-database.md","tags":[],"version":"current","sidebarPosition":40,"frontMatter":{"title":"SQL Database Integration","sidebar_position":40},"sidebar":"docSidebar","previous":{"title":"Amazon Bedrock Agents","permalink":"/solace-agent-mesh/docs/documentation/developing/tutorials/bedrock-agents"},"next":{"title":"MongoDB Integration","permalink":"/solace-agent-mesh/docs/documentation/developing/tutorials/mongodb-integration"}}');var s=n(4848),i=n(8453);const o={title:"SQL Database Integration",sidebar_position:40},r="SQL Database Integration",l={},c=[{value:"Prerequisites",id:"prerequisites",level:2},{value:"Adding the SQL Database Plugin",id:"adding-the-sql-database-plugin",level:2},{value:"Downloading Example Data",id:"downloading-example-data",level:2},{value:"Using wget",id:"using-wget",level:4},{value:"Using curl",id:"using-curl",level:4},{value:"Configuring the Agent",id:"configuring-the-agent",level:2},{value:"Setting the Environment Variables",id:"setting-the-environment-variables",level:2},{value:"Running the Agent",id:"running-the-agent",level:2},{value:"Interacting with the Database",id:"interacting-with-the-database",level:2},{value:"Advanced Configuration",id:"advanced-configuration",level:2},{value:"Customizing the Agent Card",id:"customizing-the-agent-card",level:2},{value:"Key Agent Card Elements",id:"key-agent-card-elements",level:3},{value:"Example of a Well-Configured Agent Card",id:"example-of-a-well-configured-agent-card",level:3}];function d(e){const a={a:"a",code:"code",h1:"h1",h2:"h2",h3:"h3",h4:"h4",header:"header",li:"li",ol:"ol",p:"p",pre:"pre",strong:"strong",ul:"ul",...(0,i.R)(),...e.components};return(0,s.jsxs)(s.Fragment,{children:[(0,s.jsx)(a.header,{children:(0,s.jsx)(a.h1,{id:"sql-database-integration",children:"SQL Database Integration"})}),"\n",(0,s.jsx)(a.p,{children:"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."}),"\n",(0,s.jsx)(a.h2,{id:"prerequisites",children:"Prerequisites"}),"\n",(0,s.jsx)(a.p,{children:"Before starting this tutorial, ensure that you have installed and configured Agent Mesh:"}),"\n",(0,s.jsxs)(a.ul,{children:["\n",(0,s.jsx)(a.li,{children:(0,s.jsx)(a.a,{href:"/solace-agent-mesh/docs/documentation/installing-and-configuring/installation",children:"Installed Agent Mesh and the Agent Mesh CLI"})}),"\n",(0,s.jsx)(a.li,{children:(0,s.jsx)(a.a,{href:"/solace-agent-mesh/docs/documentation/installing-and-configuring/run-project",children:"Created a new Agent Mesh project"})}),"\n",(0,s.jsx)(a.li,{children:"Access to a SQL database (local or remote)"}),"\n"]}),"\n",(0,s.jsx)(a.h2,{id:"adding-the-sql-database-plugin",children:"Adding the SQL Database Plugin"}),"\n",(0,s.jsx)(a.p,{children:"Add the SQL Database plugin to your Agent Mesh project:"}),"\n",(0,s.jsx)(a.pre,{children:(0,s.jsx)(a.code,{className:"language-sh",children:"sam plugin add abc-coffee-info --plugin sam-sql-database\n"})}),"\n",(0,s.jsxs)(a.p,{children:["You can use any name for your agent, in this tutorial we use ",(0,s.jsx)(a.code,{children:"abc-coffee-info"}),"."]}),"\n",(0,s.jsx)(a.p,{children:"This command:"}),"\n",(0,s.jsxs)(a.ul,{children:["\n",(0,s.jsxs)(a.li,{children:["Installs the ",(0,s.jsx)(a.code,{children:"sam-sql-database"})," plugin"]}),"\n",(0,s.jsxs)(a.li,{children:["Creates a new agent configuration file at ",(0,s.jsx)(a.code,{children:"configs/agents/abc-coffee-info.yaml"})]}),"\n"]}),"\n",(0,s.jsx)(a.h2,{id:"downloading-example-data",children:"Downloading Example Data"}),"\n",(0,s.jsx)(a.p,{children:"For this tutorial, you can use a sample SQLite database for a fictional coffee company called ABC Coffee Co."}),"\n",(0,s.jsx)(a.p,{children:"First, download the example data."}),"\n",(0,s.jsx)(a.p,{children:"You can either visit this link to download with your browser:"}),"\n",(0,s.jsx)(a.p,{children:(0,s.jsx)(a.a,{href:"https://github.com/SolaceLabs/solace-agent-mesh-core-plugins/raw/refs/heads/main/sam-sql-database/example-data/abc_coffee_co.zip",children:"https://github.com/SolaceLabs/solace-agent-mesh-core-plugins/raw/refs/heads/main/sam-sql-database/example-data/abc_coffee_co.zip"})}),"\n",(0,s.jsx)(a.p,{children:"Or you can use the command line to download the ZIP file:"}),"\n",(0,s.jsx)(a.h4,{id:"using-wget",children:"Using wget"}),"\n",(0,s.jsx)(a.pre,{children:(0,s.jsx)(a.code,{className:"language-sh",children:"wget https://github.com/SolaceLabs/solace-agent-mesh-core-plugins/raw/refs/heads/main/sam-sql-database/example-data/abc_coffee_co.zip\n"})}),"\n",(0,s.jsx)(a.h4,{id:"using-curl",children:"Using curl"}),"\n",(0,s.jsx)(a.pre,{children:(0,s.jsx)(a.code,{className:"language-sh",children:"curl -LO https://github.com/SolaceLabs/solace-agent-mesh-core-plugins/raw/refs/heads/main/sam-sql-database/example-data/abc_coffee_co.zip\n"})}),"\n",(0,s.jsx)(a.p,{children:"After downloading the ZIP file, extract it to a directory of your choice. You can use the following command to extract the ZIP file:"}),"\n",(0,s.jsx)(a.pre,{children:(0,s.jsx)(a.code,{className:"language-sh",children:"unzip abc_coffee_co.zip\n"})}),"\n",(0,s.jsx)(a.h2,{id:"configuring-the-agent",children:"Configuring the Agent"}),"\n",(0,s.jsxs)(a.p,{children:["Now, update the agent configuration to use the SQLite database and import the CSV files.\nOpen the ",(0,s.jsx)(a.code,{children:"configs/agents/abc-coffee-info.yaml"})," file and modify the ",(0,s.jsx)(a.code,{children:"agent_init_function.config"})," section to specify the CSV directory."]}),"\n",(0,s.jsx)(a.p,{children:"Here is what you need to modify in the configuration file:"}),"\n",(0,s.jsx)(a.pre,{children:(0,s.jsx)(a.code,{className:"language-yaml",children:'# Find the agent_init_function section and update the config:\nagent_init_function:\n  module: "sam_sql_database.lifecycle"\n  name: "initialize_sql_agent"\n  config:\n    db_type: "${ABC_COFFEE_INFO_DB_TYPE}"\n    db_name: "${ABC_COFFEE_INFO_DB_NAME}"\n    database_purpose: "${ABC_COFFEE_INFO_DB_PURPOSE}"\n    data_description: "${ABC_COFFEE_INFO_DB_DESCRIPTION}"\n    # Add the CSV directory path\n    csv_directories:\n      - /path/to/your/unzipped/data\n'})}),"\n",(0,s.jsxs)(a.p,{children:["Ensure you replace ",(0,s.jsx)(a.code,{children:"/path/to/your/unzipped/data"})," with the path where you extracted the example data. For example, if you put the ZIP file in the root directory of your Agent Mesh project, you can use ",(0,s.jsx)(a.code,{children:"abc_coffee_co"}),"."]}),"\n",(0,s.jsx)(a.h2,{id:"setting-the-environment-variables",children:"Setting the Environment Variables"}),"\n",(0,s.jsxs)(a.p,{children:["The SQL Database agent requires that you configure several environment variables. You must create or update your ",(0,s.jsx)(a.code,{children:".env"})," file with the following variables for this tutorial:"]}),"\n",(0,s.jsx)(a.pre,{children:(0,s.jsx)(a.code,{className:"language-bash",children:'ABC_COFFEE_INFO_DB_TYPE=sqlite\nABC_COFFEE_INFO_DB_NAME=abc_coffee.db\nABC_COFFEE_INFO_DB_PURPOSE="ABC Coffee Co. sales and operations database"\nABC_COFFEE_INFO_DB_DESCRIPTION="Contains information about ABC Coffee Co. products, sales, customers, employees, and store locations."\n# You can leave other environment variables as unset or empty\n'})}),"\n",(0,s.jsx)(a.p,{children:"SQLite stores the database in a local file and doesn't require a username or password for access. If you're using a database such as MySQL or PostgreSQL, you'll need to provide the appropriate environment variables for them."}),"\n",(0,s.jsx)(a.h2,{id:"running-the-agent",children:"Running the Agent"}),"\n",(0,s.jsx)(a.p,{children:"Now, you can start your SQL database agent:"}),"\n",(0,s.jsx)(a.pre,{children:(0,s.jsx)(a.code,{className:"language-sh",children:"sam run configs/agents/abc-coffee-info.yaml\n"})}),"\n",(0,s.jsx)(a.p,{children:"The agent:"}),"\n",(0,s.jsxs)(a.ol,{children:["\n",(0,s.jsx)(a.li,{children:"Connects to the A2A control plane"}),"\n",(0,s.jsx)(a.li,{children:"Initializes the SQLite database and imports CSV data from the specified directory"}),"\n",(0,s.jsx)(a.li,{children:"Detects the database schema automatically"}),"\n",(0,s.jsx)(a.li,{children:"Registers its capabilities with the agent discovery system"}),"\n"]}),"\n",(0,s.jsx)(a.h2,{id:"interacting-with-the-database",children:"Interacting with the Database"}),"\n",(0,s.jsxs)(a.p,{children:["After your SQL database agent is running, you can interact with the ABC Coffee database through any gateway in your Agent Mesh project (such as the Web UI gateway at ",(0,s.jsx)(a.code,{children:"http://localhost:8000"}),")."]}),"\n",(0,s.jsx)(a.p,{children:"You can ask natural language questions about the ABC Coffee Co. database, such as:"}),"\n",(0,s.jsxs)(a.ul,{children:["\n",(0,s.jsx)(a.li,{children:'"How many customers does ABC Coffee have?"'}),"\n",(0,s.jsx)(a.li,{children:'"What are the top-selling products?"'}),"\n",(0,s.jsx)(a.li,{children:'"Show me the sales by region"'}),"\n",(0,s.jsx)(a.li,{children:'"List all orders from the last 30 days"'}),"\n",(0,s.jsx)(a.li,{children:'"What products are currently low in inventory?"'}),"\n"]}),"\n",(0,s.jsx)(a.p,{children:"Try creating reports by asking questions such as:"}),"\n",(0,s.jsxs)(a.ul,{children:["\n",(0,s.jsx)(a.li,{children:'"Create a report of our sales in 2024"'}),"\n",(0,s.jsx)(a.li,{children:'"Generate a summary of customer demographics"'}),"\n"]}),"\n",(0,s.jsx)(a.p,{children:"The SQL Database agent converts your natural language questions into SQL queries, executes them against the database, and returns the results. For large result sets, the agent automatically saves the results as artifacts that you can download."}),"\n",(0,s.jsx)(a.h2,{id:"advanced-configuration",children:"Advanced Configuration"}),"\n",(0,s.jsx)(a.p,{children:"The SQL Database plugin supports many advanced configuration options. Here is a complete example based on the plugin structure:"}),"\n",(0,s.jsx)(a.pre,{children:(0,s.jsx)(a.code,{className:"language-yaml",children:'log:\n  stdout_log_level: INFO\n  log_file_level: DEBUG\n  log_file: abc-coffee-info.log\n\n!include ../shared_config.yaml\n\napps:\n  - name: abc-coffee-info-app\n    app_module: solace_agent_mesh.agent.sac.app \n    broker:\n      <<: *broker_connection\n\n    app_config:\n      namespace: ${NAMESPACE}\n      agent_name: "AbcCoffeeInfo"\n      display_name: "ABC Coffee Database Agent"\n      supports_streaming: false\n      model: *general_model\n\n      instruction: |\n        You are an expert SQL assistant for the ABC Coffee Co. database.\n        The database schema and query examples are provided to you.\n        Your primary goal is to translate user questions into accurate SQL queries.\n        If a user asks to query the database, generate the SQL and call the \'execute_sql_query\' tool.\n        If the \'execute_sql_query\' tool returns an error, analyze the error message and the original SQL,\n        then try to correct the SQL query and call the tool again.\n        If the results are large and the tool indicates they were saved as an artifact, inform the user about the artifact.\n        Always use the \'execute_sql_query\' tool to interact with the database.\n\n      # Agent initialization with database setup\n      agent_init_function:\n        module: "sam_sql_database.lifecycle"\n        name: "initialize_sql_agent"\n        config:\n          db_type: "${ABC_COFFEE_INFO_DB_TYPE}"\n          db_name: "${ABC_COFFEE_INFO_DB_NAME}"\n          database_purpose: "${ABC_COFFEE_INFO_DB_PURPOSE}"\n          data_description: "${ABC_COFFEE_INFO_DB_DESCRIPTION}"\n          auto_detect_schema: true\n          csv_directories:\n            - "abc_coffee_co"  # Path to your extracted data\n          query_examples:\n            - natural_language: "Show all customers from New York"\n              sql_query: "SELECT * FROM customers WHERE city = \'New York\';"\n            - natural_language: "What are the top 5 best-selling products?"\n              sql_query: "SELECT product_name, SUM(quantity) as total_sold FROM order_items JOIN products ON order_items.product_id = products.id GROUP BY product_name ORDER BY total_sold DESC LIMIT 5;"\n\n      agent_cleanup_function:\n        module: "sam_sql_database.lifecycle"\n        name: "cleanup_sql_agent_resources"\n\n      # SQL query tool\n      tools:\n        - tool_type: python\n          component_module: "sam_sql_database.tools"\n          function_name: "execute_sql_query"\n\n      session_service: *default_session_service\n      artifact_service: *default_artifact_service\n\n      # Agent capabilities - This is what other agents see during discovery\n      agent_card:\n        description: "ABC Coffee Co. Database Agent - Access to comprehensive coffee shop data including customers, orders, products, inventory, and sales history. Can answer questions about business metrics, customer analytics, product performance, and operational data."\n        defaultInputModes: ["text"]\n        defaultOutputModes: ["text", "file"]\n        skills:\n          - id: "sql_query"\n            name: "Coffee Shop Database Query"\n            description: "Queries ABC Coffee Co. database containing customer orders, product catalog, inventory levels, sales history, and employee data."\n\n      # A2A Protocol settings\n      agent_card_publishing: { interval_seconds: 30 }\n      agent_discovery: { enabled: true }\n      inter_agent_communication:\n        allow_list: ["*"]\n        request_timeout_seconds: 60\n'})}),"\n",(0,s.jsx)(a.h2,{id:"customizing-the-agent-card",children:"Customizing the Agent Card"}),"\n",(0,s.jsxs)(a.p,{children:["The ",(0,s.jsx)(a.code,{children:"agent_card"})," section is crucial as it defines how other agents in your Agent Mesh ecosystem discover and understand this database agent's capabilities. When other agents use agent discovery, they can see this information to decide whether to delegate tasks to your database agent."]}),"\n",(0,s.jsx)(a.h3,{id:"key-agent-card-elements",children:"Key Agent Card Elements"}),"\n",(0,s.jsxs)(a.ol,{children:["\n",(0,s.jsxs)(a.li,{children:[(0,s.jsx)(a.strong,{children:"Description"}),": Clearly describe what data the agent has access to and what types of questions it can answer"]}),"\n",(0,s.jsxs)(a.li,{children:[(0,s.jsx)(a.strong,{children:"Skills"}),": List specific capabilities with concrete examples that show the scope of data available"]}),"\n",(0,s.jsxs)(a.li,{children:[(0,s.jsx)(a.strong,{children:"Data Context"}),": Mention the business domain, data types, and scope of information available"]}),"\n"]}),"\n",(0,s.jsx)(a.h3,{id:"example-of-a-well-configured-agent-card",children:"Example of a Well-Configured Agent Card"}),"\n",(0,s.jsx)(a.pre,{children:(0,s.jsx)(a.code,{className:"language-yaml",children:'agent_card:\n  description: "ABC Coffee Co. Database Agent - Access to comprehensive coffee shop data including customers, orders, products, inventory, and sales history. Can answer questions about business metrics, customer analytics, product performance, and operational data."\n  defaultInputModes: ["text"]\n  defaultOutputModes: ["text", "file"]\n  skills:\n    - id: "sql_query"\n      name: "Coffee Shop Database Query"\n      description: "Queries ABC Coffee Co. database containing customer orders, product catalog, inventory levels, sales history, and employee data."\n'})}),"\n",(0,s.jsx)(a.p,{children:"This detailed information helps other agents understand:"}),"\n",(0,s.jsxs)(a.ul,{children:["\n",(0,s.jsx)(a.li,{children:"What business domain this agent covers (coffee shop operations)"}),"\n",(0,s.jsx)(a.li,{children:"What types of data are available (customers, orders, products, inventory, sales)"}),"\n",(0,s.jsx)(a.li,{children:"What kinds of questions can be answered (metrics, analytics, performance data)"}),"\n",(0,s.jsx)(a.li,{children:"Specific examples of queries that work well"}),"\n"]}),"\n",(0,s.jsx)(a.p,{children:"When configuring your own database agent, customize the description and examples to match your specific data and use cases."})]})}function h(e={}){const{wrapper:a}={...(0,i.R)(),...e.components};return a?(0,s.jsx)(a,{...e,children:(0,s.jsx)(d,{...e})}):d(e)}},8453:(e,a,n)=>{n.d(a,{R:()=>o,x:()=>r});var t=n(6540);const s={},i=t.createContext(s);function o(e){const a=t.useContext(i);return t.useMemo((function(){return"function"==typeof e?e(a):{...a,...e}}),[a,e])}function r(e){let a;return a=e.disableParentContext?"function"==typeof e.components?e.components(s):e.components||s:o(e.components),t.createElement(i.Provider,{value:a},e.children)}}}]);

solace_agent_mesh/assets/docs/assets/js/de915948.44a432bc.js

@@ -0,0 +1 @@
+"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[6426],{1007:(e,n,i)=>{i.r(n),i.d(n,{assets:()=>c,contentTitle:()=>a,default:()=>h,frontMatter:()=>o,metadata:()=>t,toc:()=>l});const t=JSON.parse('{"id":"documentation/installing-and-configuring/large_language_models","title":"Configuring LLMs","description":"Large Language Models (LLMs) serve as the intelligence foundation for Agent Mesh, powering everything from natural language understanding to complex reasoning and decision-making. The system provides flexible configuration options that allow you to connect with various LLM providers through a unified interface, making it easy to switch between providers or use multiple models for different purposes.","source":"@site/docs/documentation/installing-and-configuring/large_language_models.md","sourceDirName":"documentation/installing-and-configuring","slug":"/documentation/installing-and-configuring/large_language_models","permalink":"/solace-agent-mesh/docs/documentation/installing-and-configuring/large_language_models","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/installing-and-configuring/large_language_models.md","tags":[],"version":"current","sidebarPosition":340,"frontMatter":{"title":"Configuring LLMs","sidebar_position":340},"sidebar":"docSidebar","previous":{"title":"Configuring Agent Mesh","permalink":"/solace-agent-mesh/docs/documentation/installing-and-configuring/configurations"},"next":{"title":"User Feedback","permalink":"/solace-agent-mesh/docs/documentation/installing-and-configuring/user-feedback"}}');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/e04b235d.52cb25ed.js

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

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

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

solace_agent_mesh/assets/docs/assets/js/e3d9abda.1476f570.js

@@ -0,0 +1 @@
+"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":"Running from Wheel File","permalink":"/solace-agent-mesh/docs/documentation/enterprise/wheel-installation"}}');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",strong:"strong",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.jsxs)(n.admonition,{title:"Authorization Required",type:"warning",children:[(0,o.jsxs)(n.p,{children:[(0,o.jsx)(n.strong,{children:"Agent Mesh Enterprise uses secure-by-default authorization."})," Without explicit authorization configuration, the system will ",(0,o.jsx)(n.strong,{children:"deny all access"})," to protect your deployment."]}),(0,o.jsxs)(n.p,{children:["For production use, you must configure RBAC (Role-Based Access Control) to grant access to users. See the ",(0,o.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/enterprise/rbac-setup-guide",children:"RBAC Setup Guide"})," for details."]}),(0,o.jsxs)(n.p,{children:["For development/testing only, you can disable authorization by setting ",(0,o.jsx)(n.code,{children:"type: none"})," in your configuration, but this should ",(0,o.jsx)(n.strong,{children:"never"})," be used in production. (see example below)"]})]}),"\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  -e SAM_AUTHORIZATION_CONFIG="/preset/auth/insecure_permissive_auth_config.yaml" \\\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: Basic Development Mode (Secure Default - Access Denied)"}),(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'})}),(0,o.jsxs)(n.p,{children:[(0,o.jsx)(n.strong,{children:"Note:"})," This configuration uses secure defaults and will deny all access. You must configure RBAC or use the permissive development configuration below."]})]}),"\n",(0,o.jsxs)(t,{children:[(0,o.jsx)("summary",{children:"Example: Development Mode with Permissive Authorization (Development Only)"}),(0,o.jsxs)(n.p,{children:["You can use the pre-configured development configuration file provided in the ",(0,o.jsx)(n.code,{children:"preset"})," directory. Run the container with the ",(0,o.jsx)(n.code,{children:"SAM_AUTHORIZATION_CONFIG"})," environment variable pointing to this file to disable authorization checks."]}),(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  -e SAM_AUTHORIZATION_CONFIG="/preset/auth/insecure_permissive_auth_config.yaml" \\\n  --name sam-ent-dev \\\n  868978040651.dkr.ecr.us-east-1.amazonaws.com/solace-agent-mesh-enterprise:1.0.37-c8890c7f31\n'})}),(0,o.jsxs)(n.p,{children:[(0,o.jsx)(n.strong,{children:"\u26a0\ufe0f Warning:"})," This configuration disables authorization and grants full access. Use only for local development."]})]}),"\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)(n.p,{children:[(0,o.jsx)(n.strong,{children:"Ensure you have set up proper RBAC authorization for production deployments."})," For more information, see ",(0,o.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/enterprise/rbac-setup-guide",children:"RBAC Setup Guide"}),"."]}),"\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/e6f9706b.4488e34c.js

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

solace_agent_mesh/assets/docs/assets/js/e92d0134.3bda61dd.js

@@ -0,0 +1 @@
+"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[7567],{9392:(e,i,t)=>{t.r(i),t.d(i,{assets:()=>l,contentTitle:()=>a,default:()=>h,frontMatter:()=>r,metadata:()=>n,toc:()=>c});const n=JSON.parse('{"id":"documentation/deploying/observability","title":"Monitoring Your Agent Mesh","description":"Understanding how your Agent Mesh system operates in real-time is crucial for maintaining optimal performance and quickly identifying issues. The platform provides a comprehensive observability suite that gives you deep insights into system behavior, message flows, and agent interactions.","source":"@site/docs/documentation/deploying/observability.md","sourceDirName":"documentation/deploying","slug":"/documentation/deploying/observability","permalink":"/solace-agent-mesh/docs/documentation/deploying/observability","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/deploying/observability.md","tags":[],"version":"current","sidebarPosition":20,"frontMatter":{"title":"Monitoring Your Agent Mesh","sidebar_position":20},"sidebar":"docSidebar","previous":{"title":"Kubernetes","permalink":"/solace-agent-mesh/docs/documentation/deploying/kubernetes-deployment"},"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)}}}]);