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

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

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

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

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

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

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

solace_agent_mesh/assets/docs/assets/js/924ffdeb.975e428a.js

@@ -0,0 +1 @@
+"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[8907],{3780:(e,n,t)=>{t.r(n),t.d(n,{assets:()=>l,contentTitle:()=>o,default:()=>h,frontMatter:()=>i,metadata:()=>s,toc:()=>c});const s=JSON.parse('{"id":"documentation/components/proxies","title":"Proxies","description":"Proxies act as protocol bridges that connect Agent Mesh to external A2A agents. By translating between A2A over Solace event mesh and A2A over HTTPS protocols, proxies enable agents within the mesh to delegate tasks to external agents and include them in collaborative workflows.","source":"@site/docs/documentation/components/proxies.md","sourceDirName":"documentation/components","slug":"/documentation/components/proxies","permalink":"/solace-agent-mesh/docs/documentation/components/proxies","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/components/proxies.md","tags":[],"version":"current","sidebarPosition":250,"frontMatter":{"title":"Proxies","sidebar_position":250},"sidebar":"docSidebar","previous":{"title":"Orchestrator","permalink":"/solace-agent-mesh/docs/documentation/components/orchestrator"},"next":{"title":"Gateways","permalink":"/solace-agent-mesh/docs/documentation/components/gateways"}}');var a=t(4848),r=t(8453);const i={title:"Proxies",sidebar_position:250},o="Proxies",l={},c=[{value:"Key Functions",id:"key-functions",level:2},{value:"When to Use a Proxy",id:"when-to-use-a-proxy",level:2},{value:"Proxy vs. Native Agent",id:"proxy-vs-native-agent",level:3},{value:"Architecture Overview",id:"architecture-overview",level:2},{value:"Configuration",id:"configuration",level:2},{value:"Basic Configuration",id:"basic-configuration",level:3},{value:"Configuration Parameters",id:"configuration-parameters",level:3},{value:"Authentication Types",id:"authentication-types",level:2},{value:"Static Bearer Token",id:"static-bearer-token",level:3},{value:"Static API Key",id:"static-api-key",level:3},{value:"OAuth 2.0 Client Credentials",id:"oauth-20-client-credentials",level:3},{value:"Custom HTTP Headers",id:"custom-http-headers",level:2},{value:"Header Configuration",id:"header-configuration",level:3},{value:"Header Precedence Rules",id:"header-precedence-rules",level:3},{value:"Use Cases",id:"use-cases",level:3},{value:"Artifact Handling",id:"artifact-handling",level:2},{value:"Request Flow: Agent Mesh to External Agent",id:"request-flow-agent-mesh-to-external-agent",level:3},{value:"Response Flow: External Agent to Agent Mesh",id:"response-flow-external-agent-to-agent-mesh",level:3},{value:"Artifact Metadata",id:"artifact-metadata",level:3},{value:"Status Update Conversion",id:"status-update-conversion",level:2},{value:"Conversion Scope",id:"conversion-scope",level:3},{value:"When to Disable",id:"when-to-disable",level:3},{value:"Discovery and Health",id:"discovery-and-health",level:2},{value:"Initial Discovery",id:"initial-discovery",level:3},{value:"Periodic Refresh",id:"periodic-refresh",level:3},{value:"Agent Card Transformation",id:"agent-card-transformation",level:3},{value:"URL Behavior",id:"url-behavior",level:3},{value:"Task Lifecycle Management",id:"task-lifecycle-management",level:2},{value:"Task Initiation",id:"task-initiation",level:3},{value:"Task Cancellation",id:"task-cancellation",level:3},{value:"Task Completion",id:"task-completion",level:3},{value:"Error Handling and Retry Logic",id:"error-handling-and-retry-logic",level:2},{value:"OAuth 2.0 Automatic Retry",id:"oauth-20-automatic-retry",level:3},{value:"Connection Errors",id:"connection-errors",level:3},{value:"Error Responses",id:"error-responses",level:3},{value:"Creating a Proxy",id:"creating-a-proxy",level:2},{value:"Creating the Configuration File",id:"creating-the-configuration-file",level:3},{value:"Running the Proxy",id:"running-the-proxy",level:3},{value:"Multiple Proxy Configurations",id:"multiple-proxy-configurations",level:3},{value:"Advanced Configuration",id:"advanced-configuration",level:2},{value:"Per-Agent Timeout Override",id:"per-agent-timeout-override",level:3},{value:"Custom Headers with Authentication",id:"custom-headers-with-authentication",level:3},{value:"URL Override for Task Invocations",id:"url-override-for-task-invocations",level:3},{value:"Custom Artifact Service Scope",id:"custom-artifact-service-scope",level:3},{value:"Multiple Proxies",id:"multiple-proxies",level:3},{value:"Troubleshooting",id:"troubleshooting",level:2},{value:"Agent Not Discoverable",id:"agent-not-discoverable",level:3},{value:"Authentication Failures",id:"authentication-failures",level:3},{value:"Timeout Errors",id:"timeout-errors",level:3},{value:"Artifact Issues",id:"artifact-issues",level:3},{value:"Issues Running A2A Samples with <code>Containerfile</code>",id:"issues-running-a2a-samples-with-containerfile",level:3}];function d(e){const n={a:"a",admonition:"admonition",code:"code",h1:"h1",h2:"h2",h3:"h3",header:"header",li:"li",mermaid:"mermaid",ol:"ol",p:"p",pre:"pre",strong:"strong",table:"table",tbody:"tbody",td:"td",th:"th",thead:"thead",tr:"tr",ul:"ul",...(0,r.R)(),...e.components};return(0,a.jsxs)(a.Fragment,{children:[(0,a.jsx)(n.header,{children:(0,a.jsx)(n.h1,{id:"proxies",children:"Proxies"})}),"\n",(0,a.jsx)(n.p,{children:"Proxies act as protocol bridges that connect Agent Mesh to external A2A agents. By translating between A2A over Solace event mesh and A2A over HTTPS protocols, proxies enable agents within the mesh to delegate tasks to external agents and include them in collaborative workflows."}),"\n",(0,a.jsx)(n.p,{children:"A single proxy instance can manage multiple external agents, each with its own URL, authentication configuration, and timeout settings."}),"\n",(0,a.jsx)(n.admonition,{title:"In one sentence",type:"tip",children:(0,a.jsx)(n.p,{children:"Proxies are protocol bridges that connect multiple external A2A-over-HTTPS agents to the Solace event mesh, enabling hybrid agent architectures."})}),"\n",(0,a.jsx)(n.h2,{id:"key-functions",children:"Key Functions"}),"\n",(0,a.jsxs)(n.ol,{children:["\n",(0,a.jsxs)(n.li,{children:["\n",(0,a.jsxs)(n.p,{children:[(0,a.jsx)(n.strong,{children:"Protocol Translation"}),": Proxies translate between A2A over HTTPS and A2A over Solace event mesh, enabling external agents to communicate with agents on the mesh without modification."]}),"\n"]}),"\n",(0,a.jsxs)(n.li,{children:["\n",(0,a.jsxs)(n.p,{children:[(0,a.jsx)(n.strong,{children:"Authentication Management"}),": Proxies handle authentication to downstream agents, supporting multiple authentication schemes including static bearer tokens, API keys, and OAuth 2.0 client credentials flow with automatic token refresh."]}),"\n"]}),"\n",(0,a.jsxs)(n.li,{children:["\n",(0,a.jsxs)(n.p,{children:[(0,a.jsx)(n.strong,{children:"Agent Discovery"}),": Proxies fetch agent cards from external agents and publish them to the mesh discovery topic, making external agents discoverable to other agents in the system."]}),"\n"]}),"\n",(0,a.jsxs)(n.li,{children:["\n",(0,a.jsxs)(n.p,{children:[(0,a.jsx)(n.strong,{children:"Artifact Handling"}),": Proxies manage artifact flow between the mesh and external agents, resolving artifact URIs to byte content before forwarding requests and saving returned artifacts to the mesh's artifact service."]}),"\n"]}),"\n",(0,a.jsxs)(n.li,{children:["\n",(0,a.jsxs)(n.p,{children:[(0,a.jsx)(n.strong,{children:"Task Lifecycle Management"}),": Proxies track active tasks, handle cancellation requests, and ensure proper cleanup when tasks complete or fail."]}),"\n"]}),"\n",(0,a.jsxs)(n.li,{children:["\n",(0,a.jsxs)(n.p,{children:[(0,a.jsx)(n.strong,{children:"Automatic Retry Logic"}),": For OAuth 2.0 authenticated agents, proxies automatically detect authentication failures (401 responses), refresh tokens, and retry requests without manual intervention."]}),"\n"]}),"\n"]}),"\n",(0,a.jsx)(n.h2,{id:"when-to-use-a-proxy",children:"When to Use a Proxy"}),"\n",(0,a.jsx)(n.p,{children:"Proxies are the right choice when you need:"}),"\n",(0,a.jsxs)(n.ul,{children:["\n",(0,a.jsxs)(n.li,{children:["\n",(0,a.jsxs)(n.p,{children:[(0,a.jsx)(n.strong,{children:"Integration with Third-Party Agents"}),": Connect to external A2A agents provided by vendors or partners that run on their own infrastructure."]}),"\n"]}),"\n",(0,a.jsxs)(n.li,{children:["\n",(0,a.jsxs)(n.p,{children:[(0,a.jsx)(n.strong,{children:"Hybrid Cloud Architectures"}),": Bridge agents running in different cloud environments or on-premises systems with your Solace mesh."]}),"\n"]}),"\n",(0,a.jsxs)(n.li,{children:["\n",(0,a.jsxs)(n.p,{children:[(0,a.jsx)(n.strong,{children:"Legacy System Integration"}),": Connect existing A2A agents that cannot be modified to use Solace messaging directly."]}),"\n"]}),"\n",(0,a.jsxs)(n.li,{children:["\n",(0,a.jsxs)(n.p,{children:[(0,a.jsx)(n.strong,{children:"Gradual Migration"}),": Incrementally migrate agents to the Solace mesh while maintaining compatibility with external systems."]}),"\n"]}),"\n",(0,a.jsxs)(n.li,{children:["\n",(0,a.jsxs)(n.p,{children:[(0,a.jsx)(n.strong,{children:"Service Isolation"}),": Keep certain agents isolated on separate infrastructure while still enabling them to participate in collaborative workflows."]}),"\n"]}),"\n"]}),"\n",(0,a.jsx)(n.h3,{id:"proxy-vs-native-agent",children:"Proxy vs. Native Agent"}),"\n",(0,a.jsxs)(n.table,{children:[(0,a.jsx)(n.thead,{children:(0,a.jsxs)(n.tr,{children:[(0,a.jsx)(n.th,{children:"Aspect"}),(0,a.jsx)(n.th,{children:"Proxy"}),(0,a.jsx)(n.th,{children:"Native Agent"})]})}),(0,a.jsxs)(n.tbody,{children:[(0,a.jsxs)(n.tr,{children:[(0,a.jsx)(n.td,{children:(0,a.jsx)(n.strong,{children:"Communication"})}),(0,a.jsx)(n.td,{children:"A2A over HTTPS to external agent"}),(0,a.jsx)(n.td,{children:"A2A over Solace event mesh directly"})]}),(0,a.jsxs)(n.tr,{children:[(0,a.jsx)(n.td,{children:(0,a.jsx)(n.strong,{children:"Deployment"})}),(0,a.jsx)(n.td,{children:"External agent runs separately"}),(0,a.jsx)(n.td,{children:"Runs within Agent Mesh"})]}),(0,a.jsxs)(n.tr,{children:[(0,a.jsx)(n.td,{children:(0,a.jsx)(n.strong,{children:"Authentication"})}),(0,a.jsx)(n.td,{children:"Proxy handles auth to external agent"}),(0,a.jsx)(n.td,{children:"Mesh-level authentication"})]}),(0,a.jsxs)(n.tr,{children:[(0,a.jsx)(n.td,{children:(0,a.jsx)(n.strong,{children:"Latency"})}),(0,a.jsx)(n.td,{children:"Additional HTTP hop"}),(0,a.jsx)(n.td,{children:"Direct mesh communication"})]}),(0,a.jsxs)(n.tr,{children:[(0,a.jsx)(n.td,{children:(0,a.jsx)(n.strong,{children:"Task Initiation"})}),(0,a.jsx)(n.td,{children:"Can only receive tasks from mesh agents"}),(0,a.jsx)(n.td,{children:"Can initiate tasks to any agent"})]}),(0,a.jsxs)(n.tr,{children:[(0,a.jsx)(n.td,{children:(0,a.jsx)(n.strong,{children:"Use Case"})}),(0,a.jsx)(n.td,{children:"External/third-party agents"}),(0,a.jsx)(n.td,{children:"Agents you control"})]})]})]}),"\n",(0,a.jsx)(n.h2,{id:"architecture-overview",children:"Architecture Overview"}),"\n",(0,a.jsx)(n.p,{children:"The proxy sits between the Solace event mesh and external A2A agents, performing bidirectional protocol translation:"}),"\n",(0,a.jsx)(n.mermaid,{value:"graph LR\n    A[Agent Mesh<br/>A2A over Solace Event Mesh] <--\x3e|Solace Topics| B[Proxy Component]\n    B <--\x3e|HTTPS| C[External Agent 1<br/>A2A over HTTPS]\n    B <--\x3e|HTTPS| D[External Agent 2<br/>A2A over HTTPS]\n    B <--\x3e|HTTPS| E[External Agent N<br/>A2A over HTTPS]\n    \n    style B fill:none,stroke:#00C895,stroke-width:2px\n    style A fill:none,stroke:#333,stroke-width:2px\n    style C fill:none,stroke:#333,stroke-width:2px\n    style D fill:none,stroke:#333,stroke-width:2px\n    style E fill:none,stroke:#333,stroke-width:2px"}),"\n",(0,a.jsx)(n.p,{children:"The proxy performs these operations:"}),"\n",(0,a.jsxs)(n.ol,{children:["\n",(0,a.jsxs)(n.li,{children:["\n",(0,a.jsxs)(n.p,{children:[(0,a.jsx)(n.strong,{children:"Request Flow"}),": Receives A2A requests from Agent Mesh, resolves artifact URIs to byte content, forwards HTTPS requests to external agents, and streams responses back to Agent Mesh."]}),"\n"]}),"\n",(0,a.jsxs)(n.li,{children:["\n",(0,a.jsxs)(n.p,{children:[(0,a.jsx)(n.strong,{children:"Response Flow"}),": Receives responses from external agents, saves artifacts to Agent Mesh's artifact service, replaces byte content with artifact URIs, and publishes responses to Agent Mesh topics."]}),"\n"]}),"\n",(0,a.jsxs)(n.li,{children:["\n",(0,a.jsxs)(n.p,{children:[(0,a.jsx)(n.strong,{children:"Discovery Flow"}),": Periodically fetches agent cards from external agents, updates the local registry, and publishes cards to the Agent Mesh discovery topic."]}),"\n"]}),"\n"]}),"\n",(0,a.jsx)(n.h2,{id:"configuration",children:"Configuration"}),"\n",(0,a.jsx)(n.p,{children:"Proxies are configured through YAML files that specify the namespace, downstream agents, authentication, and service settings."}),"\n",(0,a.jsx)(n.h3,{id:"basic-configuration",children:"Basic Configuration"}),"\n",(0,a.jsxs)(n.p,{children:["A single proxy can manage multiple external agents. Each agent in the ",(0,a.jsx)(n.code,{children:"proxied_agents"})," list can have its own URL, authentication, and timeout configuration:"]}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-yaml",children:'app:\n  class_name: solace_agent_mesh.agent.proxies.a2a.app.A2AProxyApp\n  name: my-a2a-proxy\n  app_config:\n    namespace: "myorg/production"\n    proxied_agents:\n      - name: "external-data-agent"\n        url: "https://api.example.com/agent"\n        request_timeout_seconds: 120\n        # Optional: Apply auth to agent card fetching\n        # use_auth_for_agent_card: true\n        # Optional: Use configured URL instead of agent card URL for tasks\n        # use_agent_card_url: false\n        # Optional: Custom headers for agent card fetching\n        # agent_card_headers:\n        #   - name: "X-API-Version"\n        #     value: "v2"\n        # Optional: Custom headers for task invocations\n        # task_headers:\n        #   - name: "X-Tenant-ID"\n        #     value: "${TENANT_ID}"\n      - name: "external-analytics-agent"\n        url: "https://analytics.example.com/agent"\n        request_timeout_seconds: 180\n      - name: "external-reporting-agent"\n        url: "https://reports.example.com/agent"\n    artifact_service:\n      type: "filesystem"\n      base_path: "/tmp/proxy-artifacts"\n    discovery_interval_seconds: 60\n    default_request_timeout_seconds: 300\n\nbroker:\n  # Broker configuration inherited from environment or specified here\n'})}),"\n",(0,a.jsx)(n.h3,{id:"configuration-parameters",children:"Configuration Parameters"}),"\n",(0,a.jsxs)(n.ul,{children:["\n",(0,a.jsxs)(n.li,{children:[(0,a.jsx)(n.code,{children:"namespace"}),': The topic prefix for A2A communication (for example, "myorg/production").']}),"\n",(0,a.jsxs)(n.li,{children:[(0,a.jsx)(n.code,{children:"proxied_agents"}),": A list of external agents to proxy. Each agent can have its own URL, authentication, and timeout settings (see Authentication Types below).","\n",(0,a.jsxs)(n.ul,{children:["\n",(0,a.jsxs)(n.li,{children:[(0,a.jsx)(n.code,{children:"use_auth_for_agent_card"}),": If true, applies the configured authentication when fetching agent cards. If false (default), agent card requests are made without authentication."]}),"\n",(0,a.jsxs)(n.li,{children:[(0,a.jsx)(n.code,{children:"use_agent_card_url"}),": If true (default), uses the URL from the agent card for task invocations. If false, uses the configured URL directly for all task invocations. Note: The configured URL is always used to fetch the agent card itself."]}),"\n",(0,a.jsxs)(n.li,{children:[(0,a.jsx)(n.code,{children:"agent_card_headers"}),": Custom HTTP headers to include when fetching the agent card. These headers are added alongside authentication headers."]}),"\n",(0,a.jsxs)(n.li,{children:[(0,a.jsx)(n.code,{children:"task_headers"}),": Custom HTTP headers to include when invoking A2A tasks. These headers are added alongside authentication headers."]}),"\n",(0,a.jsxs)(n.li,{children:[(0,a.jsx)(n.code,{children:"convert_progress_updates"}),": If true (default), converts TextParts in status updates to AgentProgressUpdateData DataParts for consistent UI behavior. If false, preserves original text parts."]}),"\n"]}),"\n"]}),"\n",(0,a.jsxs)(n.li,{children:[(0,a.jsx)(n.code,{children:"artifact_service"}),": Configuration for storing artifacts. This is shared across all proxied agents. This is configured in the same manner as agents and gateways"]}),"\n",(0,a.jsxs)(n.li,{children:[(0,a.jsx)(n.code,{children:"discovery_interval_seconds"}),": How often to refresh agent cards from all external agents (default: 60)."]}),"\n",(0,a.jsxs)(n.li,{children:[(0,a.jsx)(n.code,{children:"default_request_timeout_seconds"}),": Default timeout for requests to external agents. Individual agents can override this (default: 300)."]}),"\n"]}),"\n",(0,a.jsx)(n.h2,{id:"authentication-types",children:"Authentication Types"}),"\n",(0,a.jsxs)(n.p,{children:["The proxy supports three authentication schemes for connecting to downstream agents. Each agent in the ",(0,a.jsx)(n.code,{children:"proxied_agents"})," list can use a different authentication type, allowing you to integrate agents with varying security requirements in a single proxy instance."]}),"\n",(0,a.jsxs)(n.p,{children:["By default, authentication is only applied to A2A task invocations, not to agent card fetching. You can enable authentication for agent card fetching by setting ",(0,a.jsx)(n.code,{children:"use_auth_for_agent_card: true"})," in the agent configuration."]}),"\n",(0,a.jsx)(n.h3,{id:"static-bearer-token",children:"Static Bearer Token"}),"\n",(0,a.jsx)(n.p,{children:"Use static bearer tokens for agents that require a fixed authentication token."}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-yaml",children:'proxied_agents:\n  - name: "secure-agent"\n    url: "https://api.example.com/agent"\n    authentication:\n      type: "static_bearer"\n      token: "${AGENT_BEARER_TOKEN}"  # Use environment variable\n    # use_auth_for_agent_card: true  # Optional: Apply auth to agent card fetching\n'})}),"\n",(0,a.jsx)(n.h3,{id:"static-api-key",children:"Static API Key"}),"\n",(0,a.jsx)(n.p,{children:"Use static API keys for agents that require API key authentication."}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-yaml",children:'proxied_agents:\n  - name: "api-key-agent"\n    url: "https://api.example.com/agent"\n    authentication:\n      type: "static_apikey"\n      token: "${AGENT_API_KEY}"\n    # use_auth_for_agent_card: true  # Optional: Apply auth to agent card fetching\n'})}),"\n",(0,a.jsx)(n.h3,{id:"oauth-20-client-credentials",children:"OAuth 2.0 Client Credentials"}),"\n",(0,a.jsx)(n.p,{children:"Use OAuth 2.0 client credentials flow for agents that require dynamic token acquisition. The proxy automatically handles token refresh and retry logic."}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-yaml",children:'proxied_agents:\n  - name: "oauth-agent"\n    url: "https://api.example.com/agent"\n    authentication:\n      type: "oauth2_client_credentials"\n      token_url: "https://auth.example.com/oauth/token"\n      client_id: "${OAUTH_CLIENT_ID}"\n      client_secret: "${OAUTH_CLIENT_SECRET}"\n      scope: "agent.read agent.write"  # Optional\n      token_cache_duration_seconds: 3300  # Optional, default: 3300 (55 minutes)\n    # use_auth_for_agent_card: true  # Optional: Apply auth to agent card fetching\n'})}),"\n",(0,a.jsx)(n.p,{children:"The proxy caches OAuth tokens and automatically refreshes them when they expire. If a request receives a 401 Unauthorized response, the proxy invalidates the cached token and retries the request once with a fresh token."}),"\n",(0,a.jsx)(n.admonition,{title:"Security Best Practice",type:"note",children:(0,a.jsx)(n.p,{children:"Always use environment variables for sensitive credentials. Never commit tokens or secrets directly in configuration files."})}),"\n",(0,a.jsx)(n.h2,{id:"custom-http-headers",children:"Custom HTTP Headers"}),"\n",(0,a.jsx)(n.p,{children:"The proxy supports custom HTTP headers for both agent card fetching and A2A task invocations. This is useful for scenarios like API versioning, tenant identification, custom authentication schemes, or any other header-based requirements."}),"\n",(0,a.jsx)(n.h3,{id:"header-configuration",children:"Header Configuration"}),"\n",(0,a.jsxs)(n.p,{children:["Custom headers are defined as name-value pairs and can be configured separately for agent card fetching (",(0,a.jsx)(n.code,{children:"agent_card_headers"}),") and task invocations (",(0,a.jsx)(n.code,{children:"task_headers"}),"):"]}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-yaml",children:'proxied_agents:\n  - name: "custom-header-agent"\n    url: "https://api.example.com/agent"\n    authentication:\n      type: "static_bearer"\n      token: "${AGENT_TOKEN}"\n    agent_card_headers:\n      - name: "X-API-Version"\n        value: "v2"\n      - name: "X-Tenant-ID"\n        value: "${TENANT_ID}"\n    task_headers:\n      - name: "X-API-Version"\n        value: "v2"\n      - name: "X-Request-Priority"\n        value: "high"\n'})}),"\n",(0,a.jsx)(n.h3,{id:"header-precedence-rules",children:"Header Precedence Rules"}),"\n",(0,a.jsx)(n.p,{children:"When both authentication and custom headers are configured:"}),"\n",(0,a.jsxs)(n.ol,{children:["\n",(0,a.jsxs)(n.li,{children:["\n",(0,a.jsxs)(n.p,{children:[(0,a.jsx)(n.strong,{children:"Authentication headers take precedence"}),": The proxy applies authentication headers (like ",(0,a.jsx)(n.code,{children:"Authorization"})," or ",(0,a.jsx)(n.code,{children:"X-API-Key"}),") based on the authentication type configured. These are applied by the A2A SDK's authentication layer after custom headers are set."]}),"\n"]}),"\n",(0,a.jsxs)(n.li,{children:["\n",(0,a.jsxs)(n.p,{children:[(0,a.jsx)(n.strong,{children:"Custom headers are for metadata, not authentication"}),": Custom headers should be used for non-authentication purposes such as API versioning, tenant identification, or request metadata. They cannot override authentication headers."]}),"\n"]}),"\n",(0,a.jsxs)(n.li,{children:["\n",(0,a.jsxs)(n.p,{children:[(0,a.jsx)(n.strong,{children:"For custom authentication"}),": If you need custom authentication logic, omit the ",(0,a.jsx)(n.code,{children:"authentication"})," configuration block and use ",(0,a.jsx)(n.code,{children:"task_headers"})," to set your custom authentication header directly."]}),"\n"]}),"\n"]}),"\n",(0,a.jsx)(n.h3,{id:"use-cases",children:"Use Cases"}),"\n",(0,a.jsxs)(n.p,{children:[(0,a.jsx)(n.strong,{children:"API Versioning"}),": Specify the API version your integration requires:"]}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-yaml",children:'agent_card_headers:\n  - name: "X-API-Version"\n    value: "v2"\ntask_headers:\n  - name: "X-API-Version"\n    value: "v2"\n'})}),"\n",(0,a.jsxs)(n.p,{children:[(0,a.jsx)(n.strong,{children:"Tenant Identification"}),": Pass tenant or organization identifiers:"]}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-yaml",children:'task_headers:\n  - name: "X-Tenant-ID"\n    value: "${TENANT_ID}"\n  - name: "X-Organization"\n    value: "acme-corp"\n'})}),"\n",(0,a.jsxs)(n.p,{children:[(0,a.jsx)(n.strong,{children:"Custom Authentication"}),": If you need custom authentication, omit the ",(0,a.jsx)(n.code,{children:"authentication"})," block and use headers directly:"]}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-yaml",children:'# Note: Do NOT configure the \'authentication\' block if using custom auth headers\ntask_headers:\n  - name: "Authorization"\n    value: "Bearer ${CUSTOM_AUTH_TOKEN}"\n  # Or use a custom auth scheme:\n  - name: "X-Custom-Auth"\n    value: "${CUSTOM_AUTH_TOKEN}"\n'})}),"\n",(0,a.jsxs)(n.p,{children:[(0,a.jsx)(n.strong,{children:"Request Metadata"}),": Add metadata for tracking or routing:"]}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-yaml",children:'task_headers:\n  - name: "X-Request-Source"\n    value: "agent-mesh"\n  - name: "X-Request-Priority"\n    value: "high"\n'})}),"\n",(0,a.jsx)(n.h2,{id:"artifact-handling",children:"Artifact Handling"}),"\n",(0,a.jsx)(n.p,{children:"The proxy manages artifact flow in both directions to ensure seamless integration between Agent Mesh and external agents."}),"\n",(0,a.jsx)(n.h3,{id:"request-flow-agent-mesh-to-external-agent",children:"Request Flow: Agent Mesh to External Agent"}),"\n",(0,a.jsx)(n.p,{children:"When it forwards requests to external agents, the proxy resolves artifact URIs to byte content using the following sequence of operations:"}),"\n",(0,a.jsxs)(n.ol,{children:["\n",(0,a.jsxs)(n.li,{children:["The proxy receives an A2A request containing artifact references (for example, ",(0,a.jsx)(n.code,{children:"artifact://app/user/session/data.csv?version=1"}),")."]}),"\n",(0,a.jsx)(n.li,{children:"The proxy loads the artifact content from Agent Mesh's artifact service."}),"\n",(0,a.jsx)(n.li,{children:"The proxy replaces the URI with the actual byte content in the request."}),"\n",(0,a.jsx)(n.li,{children:"The proxy forwards the modified request to the external agent."}),"\n"]}),"\n",(0,a.jsx)(n.p,{children:"This process ensures that external agents receive complete artifact data without needing access to Agent Mesh's artifact service."}),"\n",(0,a.jsx)(n.h3,{id:"response-flow-external-agent-to-agent-mesh",children:"Response Flow: External Agent to Agent Mesh"}),"\n",(0,a.jsx)(n.p,{children:"When it receives responses from external agents, the proxy saves artifacts to Agent Mesh as follows:"}),"\n",(0,a.jsxs)(n.ol,{children:["\n",(0,a.jsx)(n.li,{children:"The external agent returns artifacts with byte content in the response."}),"\n",(0,a.jsx)(n.li,{children:"The proxy saves each artifact to Agent Mesh's artifact service."}),"\n",(0,a.jsx)(n.li,{children:"The proxy replaces the byte content with an artifact URI."}),"\n",(0,a.jsx)(n.li,{children:"The proxy publishes the modified response to Agent Mesh."}),"\n"]}),"\n",(0,a.jsx)(n.p,{children:"This process ensures that artifacts are stored centrally and can be accessed by other agents in Agent Mesh."}),"\n",(0,a.jsx)(n.h3,{id:"artifact-metadata",children:"Artifact Metadata"}),"\n",(0,a.jsx)(n.p,{children:"The proxy automatically generates metadata for saved artifacts, including:"}),"\n",(0,a.jsxs)(n.ul,{children:["\n",(0,a.jsxs)(n.li,{children:[(0,a.jsx)(n.code,{children:"proxied_from_artifact_id"}),": The original artifact ID from the external agent"]}),"\n",(0,a.jsxs)(n.li,{children:[(0,a.jsx)(n.code,{children:"description"}),": Extracted from the artifact or generated from context"]}),"\n",(0,a.jsxs)(n.li,{children:[(0,a.jsx)(n.code,{children:"produced_artifacts"}),": A manifest of all artifacts created during task execution"]}),"\n"]}),"\n",(0,a.jsx)(n.h2,{id:"status-update-conversion",children:"Status Update Conversion"}),"\n",(0,a.jsx)(n.p,{children:"The proxy can automatically convert text-based status updates from external A2A agents to match the native SAM agent format, ensuring consistent UI behavior across all agents in your mesh."}),"\n",(0,a.jsx)(n.h3,{id:"conversion-scope",children:"Conversion Scope"}),"\n",(0,a.jsxs)(n.p,{children:["The ",(0,a.jsx)(n.code,{children:"convert_progress_updates"})," setting only affects intermediate status updates:"]}),"\n",(0,a.jsxs)(n.ul,{children:["\n",(0,a.jsxs)(n.li,{children:[(0,a.jsx)(n.strong,{children:"Applies to"}),": ",(0,a.jsx)(n.code,{children:"TaskStatusUpdateEvent"})," messages (streaming progress updates)"]}),"\n",(0,a.jsxs)(n.li,{children:[(0,a.jsx)(n.strong,{children:"Does not apply to"}),": Final ",(0,a.jsx)(n.code,{children:"Task"})," responses, artifact content, or other message types"]}),"\n"]}),"\n",(0,a.jsx)(n.p,{children:"This means that final responses from external agents remain as text parts, preserving the agent's intended final output format."}),"\n",(0,a.jsx)(n.h3,{id:"when-to-disable",children:"When to Disable"}),"\n",(0,a.jsxs)(n.p,{children:["Set ",(0,a.jsx)(n.code,{children:"convert_progress_updates: false"})," if:"]}),"\n",(0,a.jsxs)(n.ul,{children:["\n",(0,a.jsx)(n.li,{children:"The external agent sends structured status updates that should be preserved exactly as-is"}),"\n",(0,a.jsx)(n.li,{children:"You have custom UI handling for text-based status updates"}),"\n",(0,a.jsx)(n.li,{children:"You need to preserve original TextParts for debugging or custom processing"}),"\n",(0,a.jsx)(n.li,{children:"The external agent already sends progress updates as DataParts"}),"\n"]}),"\n",(0,a.jsx)(n.p,{children:"Example configuration with conversion disabled:"}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-yaml",children:'proxied_agents:\n  - name: "legacy-agent"\n    url: "https://legacy.example.com/agent"\n    convert_progress_updates: false  # Preserve original text parts\n'})}),"\n",(0,a.jsx)(n.p,{children:"When disabled, all status update content passes through unchanged, allowing you to implement custom handling in your gateway or UI layer."}),"\n",(0,a.jsx)(n.h2,{id:"discovery-and-health",children:"Discovery and Health"}),"\n",(0,a.jsx)(n.p,{children:"The proxy maintains agent discovery and health monitoring through periodic agent card fetching."}),"\n",(0,a.jsx)(n.h3,{id:"initial-discovery",children:"Initial Discovery"}),"\n",(0,a.jsx)(n.p,{children:"When the proxy starts, it performs synchronous discovery of all configured agents by:"}),"\n",(0,a.jsxs)(n.ol,{children:["\n",(0,a.jsxs)(n.li,{children:["Fetching agent cards from each external agent's ",(0,a.jsx)(n.code,{children:"/.well-known/agent-card.json"})," endpoint."]}),"\n",(0,a.jsx)(n.li,{children:"Updating the local agent registry with agent capabilities."}),"\n",(0,a.jsx)(n.li,{children:"Publishing agent cards to the Agent Mesh discovery topic."}),"\n"]}),"\n",(0,a.jsx)(n.p,{children:"This process ensures that external agents are immediately discoverable when the proxy starts."}),"\n",(0,a.jsx)(n.h3,{id:"periodic-refresh",children:"Periodic Refresh"}),"\n",(0,a.jsxs)(n.p,{children:["The proxy periodically refreshes agent cards based on the configured ",(0,a.jsx)(n.code,{children:"discovery_interval_seconds"}),". When the configured interval elapses, the proxy fetches updated agent cards from external agents, updates the local registry with any changes, and then publishes the updated cards to Agent Mesh. This process ensures that Agent Mesh has current information about external agent capabilities and availability."]}),"\n",(0,a.jsx)(n.h3,{id:"agent-card-transformation",children:"Agent Card Transformation"}),"\n",(0,a.jsx)(n.p,{children:"The proxy transforms agent cards to make external agents appear as native Agent Mesh agents:"}),"\n",(0,a.jsxs)(n.ul,{children:["\n",(0,a.jsxs)(n.li,{children:["The ",(0,a.jsx)(n.code,{children:"name"})," field is set to the configured alias (the name you specify in ",(0,a.jsx)(n.code,{children:"proxied_agents"}),")."]}),"\n",(0,a.jsxs)(n.li,{children:["The ",(0,a.jsx)(n.code,{children:"url"})," field is rewritten to use the Solace topic format (for example, ",(0,a.jsx)(n.code,{children:"solace:myorg/production/agent/external-data-agent"}),")."]}),"\n"]}),"\n",(0,a.jsx)(n.p,{children:"These agent cards allow other agents to interact with external agents using the standard A2A protocol over Solace event mesh, without knowing they are proxied."}),"\n",(0,a.jsx)(n.h3,{id:"url-behavior",children:"URL Behavior"}),"\n",(0,a.jsx)(n.p,{children:"The proxy handles URLs in two contexts:"}),"\n",(0,a.jsxs)(n.ol,{children:["\n",(0,a.jsxs)(n.li,{children:["\n",(0,a.jsxs)(n.p,{children:[(0,a.jsx)(n.strong,{children:"Agent Card Fetching"}),": Always uses the configured URL in the ",(0,a.jsx)(n.code,{children:"proxied_agents"})," list to fetch the agent card from the external agent's ",(0,a.jsx)(n.code,{children:"/.well-known/agent-card.json"})," endpoint."]}),"\n"]}),"\n",(0,a.jsxs)(n.li,{children:["\n",(0,a.jsxs)(n.p,{children:[(0,a.jsx)(n.strong,{children:"Task Invocations"}),": By default, uses the URL specified in the agent card returned by the external agent. This allows external agents to advertise their preferred endpoint (which may differ from the agent card endpoint). You can override this behavior by setting ",(0,a.jsx)(n.code,{children:"use_agent_card_url: false"})," to always use the configured URL for both agent card fetching and task invocations."]}),"\n"]}),"\n"]}),"\n",(0,a.jsx)(n.h2,{id:"task-lifecycle-management",children:"Task Lifecycle Management"}),"\n",(0,a.jsx)(n.p,{children:"The proxy tracks active tasks and manages their lifecycle from initiation to completion."}),"\n",(0,a.jsx)(n.h3,{id:"task-initiation",children:"Task Initiation"}),"\n",(0,a.jsx)(n.p,{children:"When a request arrives from Agent Mesh, the proxy:"}),"\n",(0,a.jsxs)(n.ol,{children:["\n",(0,a.jsx)(n.li,{children:"Creates a task context to track the task's state."}),"\n",(0,a.jsx)(n.li,{children:"Resolves inbound artifacts."}),"\n",(0,a.jsx)(n.li,{children:"Forwards the request to the external agent."}),"\n",(0,a.jsx)(n.li,{children:"Begins streaming responses back to Agent Mesh."}),"\n"]}),"\n",(0,a.jsx)(n.h3,{id:"task-cancellation",children:"Task Cancellation"}),"\n",(0,a.jsx)(n.p,{children:"When a cancellation request arrives, the proxy:"}),"\n",(0,a.jsxs)(n.ol,{children:["\n",(0,a.jsx)(n.li,{children:"Looks up the active task context."}),"\n",(0,a.jsx)(n.li,{children:"Forwards the cancellation request to the external agent."}),"\n",(0,a.jsx)(n.li,{children:"Publishes the cancellation response to Agent Mesh."}),"\n"]}),"\n",(0,a.jsx)(n.h3,{id:"task-completion",children:"Task Completion"}),"\n",(0,a.jsx)(n.p,{children:"When a task completes, the proxy:"}),"\n",(0,a.jsxs)(n.ol,{children:["\n",(0,a.jsx)(n.li,{children:"Processes any final artifacts."}),"\n",(0,a.jsx)(n.li,{children:"Publishes the final task response to Agent Mesh."}),"\n",(0,a.jsx)(n.li,{children:"Removes the task context from active tracking."}),"\n"]}),"\n",(0,a.jsx)(n.h2,{id:"error-handling-and-retry-logic",children:"Error Handling and Retry Logic"}),"\n",(0,a.jsx)(n.p,{children:"The proxy implements robust error handling and automatic retry logic for authentication failures."}),"\n",(0,a.jsx)(n.h3,{id:"oauth-20-automatic-retry",children:"OAuth 2.0 Automatic Retry"}),"\n",(0,a.jsx)(n.p,{children:"When using OAuth 2.0 authentication, the proxy automatically handles token expiration using the following sequence:"}),"\n",(0,a.jsxs)(n.ol,{children:["\n",(0,a.jsx)(n.li,{children:"A request receives a 401 Unauthorized response from the external agent."}),"\n",(0,a.jsx)(n.li,{children:"The proxy invalidates the cached token."}),"\n",(0,a.jsx)(n.li,{children:"The proxy removes all cached clients for the agent/session."}),"\n",(0,a.jsx)(n.li,{children:"The proxy fetches a fresh token from the OAuth provider."}),"\n",(0,a.jsx)(n.li,{children:"The proxy retries the request once with the new token."}),"\n"]}),"\n",(0,a.jsx)(n.p,{children:"This sequence ensures seamless operation even when tokens expire during long-running tasks."}),"\n",(0,a.jsx)(n.h3,{id:"connection-errors",children:"Connection Errors"}),"\n",(0,a.jsx)(n.p,{children:"The proxy provides clear error messages for connection failures:"}),"\n",(0,a.jsxs)(n.ul,{children:["\n",(0,a.jsx)(n.li,{children:"Connection refused or agent unreachable"}),"\n",(0,a.jsx)(n.li,{children:"Timeout errors with configurable timeout values"}),"\n",(0,a.jsx)(n.li,{children:"JSON-RPC protocol errors from external agents"}),"\n"]}),"\n",(0,a.jsx)(n.h3,{id:"error-responses",children:"Error Responses"}),"\n",(0,a.jsx)(n.p,{children:"When errors occur, the proxy publishes standard A2A error responses to Agent Mesh, including:"}),"\n",(0,a.jsxs)(n.ul,{children:["\n",(0,a.jsxs)(n.li,{children:[(0,a.jsx)(n.code,{children:"InternalError"}),": For unexpected proxy errors"]}),"\n",(0,a.jsxs)(n.li,{children:[(0,a.jsx)(n.code,{children:"InvalidRequestError"}),": For malformed requests"]}),"\n",(0,a.jsxs)(n.li,{children:[(0,a.jsx)(n.code,{children:"TaskNotFoundError"}),": For cancellation requests on unknown tasks"]}),"\n"]}),"\n",(0,a.jsx)(n.h2,{id:"creating-a-proxy",children:"Creating a Proxy"}),"\n",(0,a.jsx)(n.p,{children:"Proxies are configured using standard YAML configuration files, similar to agents and gateways."}),"\n",(0,a.jsx)(n.h3,{id:"creating-the-configuration-file",children:"Creating the Configuration File"}),"\n",(0,a.jsxs)(n.p,{children:["Create a new YAML file in your ",(0,a.jsx)(n.code,{children:"configs"})," directory (for example, ",(0,a.jsx)(n.code,{children:"configs/my-proxy.yaml"}),"):"]}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-yaml",children:'log:\n  stdout_log_level: INFO\n  log_file_level: DEBUG\n  log_file: my-proxy.log\n\n# Include shared configuration (broker connection, etc.)\n!include shared_config.yaml\n\napps:\n  - name: my_a2a_proxy\n    app_module: solace_agent_mesh.agent.proxies.a2a.app\n    broker:\n      <<: *broker_connection\n\n    app_config:\n      namespace: "${NAMESPACE}"\n      \n      artifact_service:\n        type: "filesystem"\n        base_path: "/tmp/proxy-artifacts"\n        artifact_scope: "namespace"\n      \n      discovery_interval_seconds: 60\n      default_request_timeout_seconds: 300\n      \n      proxied_agents:\n        - name: "external-agent-1"\n          url: "https://api.example.com/agent"\n          request_timeout_seconds: 120\n          authentication:\n            type: "static_bearer"\n            token: "${AGENT_TOKEN}"\n'})}),"\n",(0,a.jsxs)(n.p,{children:["You can use the example file at ",(0,a.jsx)(n.code,{children:"examples/a2a_proxy.yaml"})," as a template."]}),"\n",(0,a.jsx)(n.h3,{id:"running-the-proxy",children:"Running the Proxy"}),"\n",(0,a.jsx)(n.p,{children:"Run the proxy along with your other Agent Mesh components:"}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-bash",children:"sam run\n"})}),"\n",(0,a.jsx)(n.p,{children:"The proxy automatically subscribes to the appropriate Solace topics and begins proxying requests to external agents."}),"\n",(0,a.jsx)(n.h3,{id:"multiple-proxy-configurations",children:"Multiple Proxy Configurations"}),"\n",(0,a.jsx)(n.p,{children:"While a single proxy can manage multiple external agents, you may want to create separate proxy configurations to:"}),"\n",(0,a.jsxs)(n.ul,{children:["\n",(0,a.jsx)(n.li,{children:"Organize agents by domain or team"}),"\n",(0,a.jsx)(n.li,{children:"Isolate agents with different security requirements"}),"\n",(0,a.jsx)(n.li,{children:"Distribute load across multiple proxy instances"}),"\n"]}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-bash",children:"configs/\n\u251c\u2500\u2500 data-agents-proxy.yaml      # Proxies 3 data-related agents\n\u251c\u2500\u2500 analytics-agents-proxy.yaml # Proxies 2 analytics agents\n\u2514\u2500\u2500 third-party-agents-proxy.yaml # Proxies external vendor agents\n"})}),"\n",(0,a.jsx)(n.p,{children:"Run all proxies together:"}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-bash",children:"sam run\n"})}),"\n",(0,a.jsx)(n.p,{children:"Or run specific proxy configurations:"}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-bash",children:"sam run configs/data-agents-proxy.yaml\n"})}),"\n",(0,a.jsx)(n.h2,{id:"advanced-configuration",children:"Advanced Configuration"}),"\n",(0,a.jsx)(n.h3,{id:"per-agent-timeout-override",children:"Per-Agent Timeout Override"}),"\n",(0,a.jsx)(n.p,{children:"You can override the default timeout for specific agents:"}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-yaml",children:'proxied_agents:\n  - name: "slow-agent"\n    url: "https://slow.example.com/agent"\n    request_timeout_seconds: 600  # 10 minutes\n'})}),"\n",(0,a.jsx)(n.h3,{id:"custom-headers-with-authentication",children:"Custom Headers with Authentication"}),"\n",(0,a.jsx)(n.p,{children:"Combine authentication with custom headers for complex integration requirements:"}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-yaml",children:'proxied_agents:\n  - name: "enterprise-agent"\n    url: "https://enterprise.example.com/agent"\n    authentication:\n      type: "oauth2_client_credentials"\n      token_url: "https://auth.example.com/oauth/token"\n      client_id: "${OAUTH_CLIENT_ID}"\n      client_secret: "${OAUTH_CLIENT_SECRET}"\n    use_auth_for_agent_card: true  # Apply OAuth to agent card fetching\n    agent_card_headers:\n      - name: "X-API-Version"\n        value: "v2"\n      - name: "X-Client-Type"\n        value: "agent-mesh"\n    task_headers:\n      - name: "X-API-Version"\n        value: "v2"\n      - name: "X-Tenant-ID"\n        value: "${TENANT_ID}"\n      - name: "X-Request-Priority"\n        value: "high"\n'})}),"\n",(0,a.jsx)(n.h3,{id:"url-override-for-task-invocations",children:"URL Override for Task Invocations"}),"\n",(0,a.jsxs)(n.p,{children:["By default, the proxy uses the URL from the agent card for task invocations. This allows external agents to specify their preferred endpoint. However, you can override this behavior by setting ",(0,a.jsx)(n.code,{children:"use_agent_card_url: false"}),":"]}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-yaml",children:'proxied_agents:\n  - name: "fixed-url-agent"\n    url: "https://api.example.com/agent"\n    use_agent_card_url: false  # Always use the configured URL\n    authentication:\n      type: "static_bearer"\n      token: "${AGENT_TOKEN}"\n'})}),"\n",(0,a.jsx)(n.p,{children:(0,a.jsx)(n.strong,{children:"Important notes:"})}),"\n",(0,a.jsxs)(n.ul,{children:["\n",(0,a.jsx)(n.li,{children:"The configured URL is always used to fetch the agent card, regardless of this setting"}),"\n",(0,a.jsxs)(n.li,{children:["When ",(0,a.jsx)(n.code,{children:"use_agent_card_url: false"}),", all task invocations use the configured URL"]}),"\n",(0,a.jsxs)(n.li,{children:["When ",(0,a.jsx)(n.code,{children:"use_agent_card_url: true"})," (default), the agent card's URL is used for tasks"]}),"\n"]}),"\n",(0,a.jsx)(n.h3,{id:"custom-artifact-service-scope",children:"Custom Artifact Service Scope"}),"\n",(0,a.jsx)(n.p,{children:"Configure artifact storage scope for the proxy:"}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-yaml",children:'artifact_service:\n  type: "filesystem"\n  base_path: "/data/proxy-artifacts"\n  artifact_scope: "namespace"  # Options: namespace, app, custom\n'})}),"\n",(0,a.jsx)(n.h3,{id:"multiple-proxies",children:"Multiple Proxies"}),"\n",(0,a.jsx)(n.p,{children:"You can run multiple proxy instances to distribute load or isolate different sets of external agents. Each proxy instance can manage multiple agents:"}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-yaml",children:'# data-agents-proxy.yaml\napp:\n  name: data-agents-proxy\n  app_config:\n    proxied_agents:\n      - name: "data-agent-1"\n        url: "https://data1.example.com/agent"\n      - name: "data-agent-2"\n        url: "https://data2.example.com/agent"\n      - name: "data-agent-3"\n        url: "https://data3.example.com/agent"\n\n# analytics-agents-proxy.yaml\napp:\n  name: analytics-agents-proxy\n  app_config:\n    proxied_agents:\n      - name: "analytics-agent-1"\n        url: "https://analytics1.example.com/agent"\n      - name: "analytics-agent-2"\n        url: "https://analytics2.example.com/agent"\n'})}),"\n",(0,a.jsx)(n.h2,{id:"troubleshooting",children:"Troubleshooting"}),"\n",(0,a.jsx)(n.h3,{id:"agent-not-discoverable",children:"Agent Not Discoverable"}),"\n",(0,a.jsx)(n.p,{children:"If an external agent does not appear in Agent Mesh:"}),"\n",(0,a.jsxs)(n.ol,{children:["\n",(0,a.jsx)(n.li,{children:"Check that the agent's URL is accessible from the proxy."}),"\n",(0,a.jsxs)(n.li,{children:["Verify that the agent exposes ",(0,a.jsx)(n.code,{children:"/.well-known/agent-card.json"}),"."]}),"\n",(0,a.jsx)(n.li,{children:"Check the proxy logs for discovery errors."}),"\n",(0,a.jsxs)(n.li,{children:["Ensure that ",(0,a.jsx)(n.code,{children:"discovery_interval_seconds"})," is set appropriately and is more frequent than the ",(0,a.jsx)(n.code,{children:"health_check_ttl_seconds"})," that is set on the calling agents and gateways."]}),"\n"]}),"\n",(0,a.jsx)(n.h3,{id:"authentication-failures",children:"Authentication Failures"}),"\n",(0,a.jsx)(n.p,{children:"If requests fail with 401 errors:"}),"\n",(0,a.jsxs)(n.ol,{children:["\n",(0,a.jsx)(n.li,{children:"Verify that the credentials are correctly set in environment variables."}),"\n",(0,a.jsxs)(n.li,{children:["For OAuth 2.0, check that ",(0,a.jsx)(n.code,{children:"token_url"}),", ",(0,a.jsx)(n.code,{children:"client_id"}),", and ",(0,a.jsx)(n.code,{children:"client_secret"})," are correct."]}),"\n",(0,a.jsx)(n.li,{children:"Ensure that the OAuth token URL uses HTTPS (required for security)."}),"\n",(0,a.jsx)(n.li,{children:"Check the proxy logs for token acquisition errors."}),"\n"]}),"\n",(0,a.jsx)(n.h3,{id:"timeout-errors",children:"Timeout Errors"}),"\n",(0,a.jsx)(n.p,{children:"If requests timeout:"}),"\n",(0,a.jsxs)(n.ol,{children:["\n",(0,a.jsxs)(n.li,{children:["Increase ",(0,a.jsx)(n.code,{children:"request_timeout_seconds"})," for slow agents."]}),"\n",(0,a.jsx)(n.li,{children:"Check the network connectivity between the proxy and the external agent."}),"\n",(0,a.jsx)(n.li,{children:"Verify that the external agent is responding within the timeout period."}),"\n"]}),"\n",(0,a.jsx)(n.h3,{id:"artifact-issues",children:"Artifact Issues"}),"\n",(0,a.jsx)(n.p,{children:"If artifacts are not flowing correctly:"}),"\n",(0,a.jsxs)(n.ol,{children:["\n",(0,a.jsx)(n.li,{children:"Verify that the artifact service is properly configured."}),"\n",(0,a.jsx)(n.li,{children:"Check that the proxy has write permissions to the artifact storage location."}),"\n",(0,a.jsx)(n.li,{children:"Ensure that the artifact URIs are correctly formatted."}),"\n",(0,a.jsx)(n.li,{children:"Check the proxy logs for artifact save/load errors."}),"\n"]}),"\n",(0,a.jsxs)(n.h3,{id:"issues-running-a2a-samples-with-containerfile",children:["Issues Running A2A Samples with ",(0,a.jsx)(n.code,{children:"Containerfile"})]}),"\n",(0,a.jsxs)(n.p,{children:["If you encounter a ",(0,a.jsx)(n.code,{children:"ValueError: Invalid context_id: ... is not a valid UUID."})," when running A2A samples using a ",(0,a.jsx)(n.code,{children:"Containerfile"}),", it may be due to outdated dependencies in the ",(0,a.jsx)(n.code,{children:"uv.lock"})," file. This can happen if the sample is pinned to an older version of the ",(0,a.jsx)(n.code,{children:"a2a-sdk"})," package. For more details, see ",(0,a.jsx)(n.a,{href:"https://github.com/a2aproject/a2a-samples/issues/399",children:"this GitHub issue"}),"."]}),"\n",(0,a.jsx)(n.p,{children:"To resolve this, navigate to the sample's directory and upgrade the dependencies:"}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-bash",children:"uv lock --upgrade\n"})}),"\n",(0,a.jsxs)(n.p,{children:["This will update the ",(0,a.jsx)(n.code,{children:"uv.lock"})," file to use the latest version of ",(0,a.jsx)(n.code,{children:"a2a-sdk"}),", which includes the necessary bug fixes."]})]})}function h(e={}){const{wrapper:n}={...(0,r.R)(),...e.components};return n?(0,a.jsx)(n,{...e,children:(0,a.jsx)(d,{...e})}):d(e)}},8453:(e,n,t)=>{t.d(n,{R:()=>i,x:()=>o});var s=t(6540);const a={},r=s.createContext(a);function i(e){const n=s.useContext(r);return s.useMemo((function(){return"function"==typeof e?e(n):{...n,...e}}),[n,e])}function o(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(a):e.components||a:i(e.components),s.createElement(r.Provider,{value:n},e.children)}}}]);

solace_agent_mesh/assets/docs/assets/js/94e8668d.16083b3f.js

@@ -0,0 +1 @@
+"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[8627],{5483:(e,n,i)=>{i.r(n),i.d(n,{assets:()=>c,contentTitle:()=>a,default:()=>h,frontMatter:()=>o,metadata:()=>s,toc:()=>l});const s=JSON.parse('{"id":"documentation/enterprise/rbac-setup-guide","title":"Setting Up RBAC","description":"Agent Mesh Enterprise now uses secure-by-default authorization. If you do not configure an authorization service, the system will deny all access by default. You must explicitly configure RBAC or another authorization type to grant access to users.","source":"@site/docs/documentation/enterprise/rbac-setup-guide.md","sourceDirName":"documentation/enterprise","slug":"/documentation/enterprise/rbac-setup-guide","permalink":"/solace-agent-mesh/docs/documentation/enterprise/rbac-setup-guide","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/enterprise/rbac-setup-guide.md","tags":[],"version":"current","sidebarPosition":10,"frontMatter":{"title":"Setting Up RBAC","sidebar_position":10},"sidebar":"docSidebar","previous":{"title":"Connectors","permalink":"/solace-agent-mesh/docs/documentation/enterprise/connectors/"},"next":{"title":"Enabling SSO","permalink":"/solace-agent-mesh/docs/documentation/enterprise/single-sign-on"}}');var r=i(4848),t=i(8453);const o={title:"Setting Up RBAC",sidebar_position:10},a=void 0,c={},l=[{value:"Table of Contents",id:"table-of-contents",level:2},{value:"Understanding RBAC in Agent Mesh Enterprise",id:"understanding-rbac-in-agent-mesh-enterprise",level:2},{value:"Authorization Types",id:"authorization-types",level:3},{value:"The Three Components",id:"the-three-components",level:3},{value:"How Authorization Works",id:"how-authorization-works",level:3},{value:"Planning Your RBAC Configuration",id:"planning-your-rbac-configuration",level:2},{value:"Identifying User Types",id:"identifying-user-types",level:3},{value:"Designing Roles",id:"designing-roles",level:3},{value:"Mapping Scopes to Features",id:"mapping-scopes-to-features",level:3},{value:"Setting Up RBAC in Docker",id:"setting-up-rbac-in-docker",level:2},{value:"Prerequisites",id:"prerequisites",level:3},{value:"Creating the Configuration Directory Structure",id:"creating-the-configuration-directory-structure",level:3},{value:"Defining Roles and Permissions",id:"defining-roles-and-permissions",level:3},{value:"Assigning Users to Roles",id:"assigning-users-to-roles",level:3},{value:"Creating the Enterprise Configuration",id:"creating-the-enterprise-configuration",level:3},{value:"Alternative: Development Mode (Permissive)",id:"alternative-development-mode-permissive",level:4},{value:"Default Behavior (No Configuration)",id:"default-behavior-no-configuration",level:4},{value:"Running the Docker Container",id:"running-the-docker-container",level:3},{value:"Verifying Your Configuration",id:"verifying-your-configuration",level:3},{value:"Understanding Configuration Files",id:"understanding-configuration-files",level:2},{value:"Role-to-Scope Definitions Structure",id:"role-to-scope-definitions-structure",level:3},{value:"User-to-Role Assignments Structure",id:"user-to-role-assignments-structure",level:3},{value:"Enterprise Configuration Structure",id:"enterprise-configuration-structure",level:3},{value:"Advanced Configuration Options",id:"advanced-configuration-options",level:2},{value:"Production-Ready Role Configuration",id:"production-ready-role-configuration",level:3},{value:"Integrating with Microsoft Graph",id:"integrating-with-microsoft-graph",level:3},{value:"Best Practices",id:"best-practices",level:2},{value:"Security Recommendations",id:"security-recommendations",level:3},{value:"Role Design Principles",id:"role-design-principles",level:3},{value:"Docker-Specific Recommendations",id:"docker-specific-recommendations",level:3},{value:"Troubleshooting",id:"troubleshooting",level:2},{value:"Authorization Denied for Valid User",id:"authorization-denied-for-valid-user",level:3},{value:"Configuration Files Not Found",id:"configuration-files-not-found",level:3},{value:"Microsoft Graph Integration Not Working",id:"microsoft-graph-integration-not-working",level:3},{value:"Debugging Authorization Issues",id:"debugging-authorization-issues",level:3},{value:"Getting Help",id:"getting-help",level:3},{value:"Conclusion",id:"conclusion",level:2}];function d(e){const n={a:"a",admonition:"admonition",code:"code",h2:"h2",h3:"h3",h4:"h4",li:"li",ol:"ol",p:"p",pre:"pre",strong:"strong",ul:"ul",...(0,t.R)(),...e.components};return(0,r.jsxs)(r.Fragment,{children:[(0,r.jsx)(n.admonition,{title:"Security Notice",type:"warning",children:(0,r.jsxs)(n.p,{children:[(0,r.jsx)(n.strong,{children:"Agent Mesh Enterprise now uses secure-by-default authorization."})," If you do not configure an authorization service, the system will ",(0,r.jsx)(n.strong,{children:"deny all access"})," by default. You must explicitly configure RBAC or another authorization type to grant access to users."]})}),"\n",(0,r.jsx)(n.p,{children:"This guide walks you through configuring Role-Based Access Control (RBAC) in a Docker installation for Agent Mesh. You will learn how to control access to Agent Mesh Enterprise features and resources based on user roles and permissions."}),"\n",(0,r.jsx)(n.h2,{id:"table-of-contents",children:"Table of Contents"}),"\n",(0,r.jsxs)(n.ul,{children:["\n",(0,r.jsx)(n.li,{children:(0,r.jsx)(n.a,{href:"#understanding-rbac-in-agent-mesh-enterprise",children:"Understanding RBAC in Agent Mesh Enterprise"})}),"\n",(0,r.jsx)(n.li,{children:(0,r.jsx)(n.a,{href:"#planning-your-rbac-configuration",children:"Planning Your RBAC Configuration"})}),"\n",(0,r.jsx)(n.li,{children:(0,r.jsx)(n.a,{href:"#setting-up-rbac-in-docker",children:"Setting Up RBAC in Docker"})}),"\n",(0,r.jsx)(n.li,{children:(0,r.jsx)(n.a,{href:"#understanding-configuration-files",children:"Understanding Configuration Files"})}),"\n",(0,r.jsx)(n.li,{children:(0,r.jsx)(n.a,{href:"#advanced-configuration-options",children:"Advanced Configuration Options"})}),"\n",(0,r.jsx)(n.li,{children:(0,r.jsx)(n.a,{href:"#best-practices",children:"Best Practices"})}),"\n",(0,r.jsx)(n.li,{children:(0,r.jsx)(n.a,{href:"#troubleshooting",children:"Troubleshooting"})}),"\n"]}),"\n",(0,r.jsx)(n.h2,{id:"understanding-rbac-in-agent-mesh-enterprise",children:"Understanding RBAC in Agent Mesh Enterprise"}),"\n",(0,r.jsx)(n.p,{children:"Before you configure RBAC, you need to understand how the system works. Agent Mesh Enterprise uses a three-tier authorization model that separates identity, roles, and permissions."}),"\n",(0,r.jsx)(n.h3,{id:"authorization-types",children:"Authorization Types"}),"\n",(0,r.jsx)(n.p,{children:"Agent Mesh Enterprise supports multiple authorization types, each suited for different use cases:"}),"\n",(0,r.jsxs)(n.p,{children:[(0,r.jsxs)(n.strong,{children:[(0,r.jsx)(n.code,{children:"deny_all"})," (Default)"]})," - The secure default that denies all access. This type is automatically used when:"]}),"\n",(0,r.jsxs)(n.ul,{children:["\n",(0,r.jsxs)(n.li,{children:["No ",(0,r.jsx)(n.code,{children:"authorization_service"})," configuration block is present"]}),"\n",(0,r.jsxs)(n.li,{children:["The ",(0,r.jsx)(n.code,{children:"authorization_service"})," block is empty"]}),"\n",(0,r.jsxs)(n.li,{children:["The ",(0,r.jsx)(n.code,{children:"type"})," field is explicitly set to ",(0,r.jsx)(n.code,{children:"deny_all"})]}),"\n"]}),"\n",(0,r.jsx)(n.p,{children:"When this type is active, all user requests are denied and logged with WARNING messages. This ensures maximum security by default."}),"\n",(0,r.jsxs)(n.p,{children:[(0,r.jsx)(n.strong,{children:(0,r.jsx)(n.code,{children:"default_rbac"})})," - Role-Based Access Control using configuration files. This type is the recommended type for production deployments where you need fine-grained control over user permissions. It requires both role definitions and user assignments files."]}),"\n",(0,r.jsxs)(n.p,{children:[(0,r.jsx)(n.strong,{children:(0,r.jsx)(n.code,{children:"custom"})})," - Custom authorization service implementation. Use this when you need to integrate with external authorization systems or implement custom authorization logic."]}),"\n",(0,r.jsxs)(n.p,{children:[(0,r.jsx)(n.strong,{children:(0,r.jsx)(n.code,{children:"none"})})," - Disables authorization entirely, granting wildcard ",(0,r.jsx)(n.code,{children:"*"})," scope to all users. This type must be explicitly configured and should ",(0,r.jsx)(n.strong,{children:"only be used in development environments"}),". The system logs prominent security warnings when this type is active."]}),"\n",(0,r.jsx)(n.admonition,{title:"Development Only",type:"danger",children:(0,r.jsxs)(n.p,{children:["The ",(0,r.jsx)(n.code,{children:"type: none"})," authorization configuration grants full access to all users and should ",(0,r.jsx)(n.strong,{children:"never"})," be used in production environments. It is intended only for local development and testing."]})}),"\n",(0,r.jsx)(n.h3,{id:"the-three-components",children:"The Three Components"}),"\n",(0,r.jsx)(n.p,{children:"RBAC in Agent Mesh Enterprise consists of three interconnected components:"}),"\n",(0,r.jsxs)(n.p,{children:[(0,r.jsx)(n.strong,{children:"Users"})," represent identities in your system. Each user has a unique identifier, typically an email address. When a user attempts to access a feature or resource, Agent Mesh Enterprise checks their assigned roles to determine what they can do."]}),"\n",(0,r.jsxs)(n.p,{children:[(0,r.jsx)(n.strong,{children:"Roles"}),' are collections of permissions that you assign to users. Instead of granting permissions directly to individual users, you create roles that represent job functions or responsibilities. For example, you might create a "data_analyst" role for users who need to work with data tools and artifacts. This approach simplifies administration because you can modify a role\'s permissions once and affect all users assigned to that role.']}),"\n",(0,r.jsxs)(n.p,{children:[(0,r.jsx)(n.strong,{children:"Scopes"})," are the actual permissions that grant access to specific features or resources. Each scope follows a pattern that identifies what it controls. For example, the scope ",(0,r.jsx)(n.code,{children:"tool:data:read"})," grants permission to read data tools, while ",(0,r.jsx)(n.code,{children:"artifact:create"})," allows creating artifacts. Scopes use wildcards to grant broader permissions. For example, the scope ",(0,r.jsx)(n.code,{children:"tool:data:*"})," grants all permissions for data tools."]}),"\n",(0,r.jsx)(n.h3,{id:"how-authorization-works",children:"How Authorization Works"}),"\n",(0,r.jsx)(n.p,{children:"When a user attempts an action in Agent Mesh Enterprise, the system follows this authorization flow:"}),"\n",(0,r.jsxs)(n.ol,{children:["\n",(0,r.jsx)(n.li,{children:"The system identifies the user based on their authentication credentials"}),"\n",(0,r.jsx)(n.li,{children:"It retrieves all roles assigned to that user"}),"\n",(0,r.jsx)(n.li,{children:"For each role, it collects all associated scopes (permissions)"}),"\n",(0,r.jsx)(n.li,{children:"It checks if any of the user's scopes match the permission required for the requested action"}),"\n",(0,r.jsx)(n.li,{children:"If a matching scope exists, the system allows the action; otherwise, it denies access"}),"\n"]}),"\n",(0,r.jsx)(n.p,{children:"This model implements the principle of least privilege: users receive only the permissions they need to perform their job functions."}),"\n",(0,r.jsx)(n.h2,{id:"planning-your-rbac-configuration",children:"Planning Your RBAC Configuration"}),"\n",(0,r.jsx)(n.p,{children:"Before you create configuration files, you should plan your RBAC structure. This planning phase helps you design a system that meets your organization's needs while remaining maintainable."}),"\n",(0,r.jsx)(n.h3,{id:"identifying-user-types",children:"Identifying User Types"}),"\n",(0,r.jsx)(n.p,{children:"Start by identifying the different types of users in your organization. Consider their job functions and what they need to accomplish with Agent Mesh Enterprise. Common user types include:"}),"\n",(0,r.jsx)(n.p,{children:"Administrators need full access to all features and resources. They manage the system, configure settings, and troubleshoot issues. You typically assign these users a role with wildcard permissions."}),"\n",(0,r.jsx)(n.p,{children:"Operators perform day-to-day tasks such as running tools, creating artifacts, and monitoring system activity. They need broad access to operational features but not administrative capabilities."}),"\n",(0,r.jsx)(n.p,{children:"Analysts work with data and reports. They need access to data tools, artifact creation, and monitoring capabilities, but they do not need access to system configuration or advanced tools."}),"\n",(0,r.jsx)(n.p,{children:"Viewers need read-only access to monitor system activity and view artifacts. They cannot create, modify, or delete resources."}),"\n",(0,r.jsx)(n.h3,{id:"designing-roles",children:"Designing Roles"}),"\n",(0,r.jsx)(n.p,{children:"Once you identify user types, design roles that match their needs. Each role should represent a specific job function and include only the scopes necessary for that function."}),"\n",(0,r.jsx)(n.p,{children:'Consider creating a role hierarchy where some roles inherit permissions from others. For example, an "operator" role might inherit all permissions from a "viewer" role and add additional capabilities. This approach reduces duplication and makes your configuration easier to maintain.'}),"\n",(0,r.jsx)(n.h3,{id:"mapping-scopes-to-features",children:"Mapping Scopes to Features"}),"\n",(0,r.jsx)(n.p,{children:"Understanding available scopes helps you design effective roles. Agent Mesh Enterprise uses a hierarchical scope naming convention:"}),"\n",(0,r.jsxs)(n.p,{children:["Tool scopes control access to tools and follow the pattern ",(0,r.jsx)(n.code,{children:"tool:<category>:<action>"}),". For example, ",(0,r.jsx)(n.code,{children:"tool:basic:read"})," grants permission to read basic tools, while ",(0,r.jsx)(n.code,{children:"tool:data:*"})," grants all permissions for data tools."]}),"\n",(0,r.jsxs)(n.p,{children:["Artifact scopes control access to artifacts (files and data created by the system) and use the pattern ",(0,r.jsx)(n.code,{children:"artifact:<action>"}),". Common artifact scopes include ",(0,r.jsx)(n.code,{children:"artifact:read"}),", ",(0,r.jsx)(n.code,{children:"artifact:create"}),", and ",(0,r.jsx)(n.code,{children:"artifact:delete"}),"."]}),"\n",(0,r.jsxs)(n.p,{children:["Monitoring scopes control access to system monitoring features and follow the pattern ",(0,r.jsx)(n.code,{children:"monitor/namespace/<namespace>:a2a_messages:subscribe"}),". These scopes allow users to observe message traffic in specific namespaces."]}),"\n",(0,r.jsxs)(n.p,{children:["The wildcard scope ",(0,r.jsx)(n.code,{children:"*"})," grants all permissions and should only be used for administrator roles."]}),"\n",(0,r.jsx)(n.h2,{id:"setting-up-rbac-in-docker",children:"Setting Up RBAC in Docker"}),"\n",(0,r.jsx)(n.p,{children:"Now that you understand RBAC concepts and have planned your configuration, you can set up RBAC in your Docker environment. This process involves creating configuration files, setting up the Docker container, and verifying that everything works correctly."}),"\n",(0,r.jsx)(n.h3,{id:"prerequisites",children:"Prerequisites"}),"\n",(0,r.jsx)(n.p,{children:"Before you begin, ensure you have:"}),"\n",(0,r.jsxs)(n.ul,{children:["\n",(0,r.jsx)(n.li,{children:"Docker installed and running on your system"}),"\n",(0,r.jsxs)(n.li,{children:["The Agent Mesh Enterprise Docker image (",(0,r.jsx)(n.code,{children:"solace-agent-mesh-enterprise"}),")"]}),"\n",(0,r.jsx)(n.li,{children:"A text editor for creating configuration files"}),"\n",(0,r.jsx)(n.li,{children:"Basic familiarity with YAML file format"}),"\n"]}),"\n",(0,r.jsx)(n.h3,{id:"creating-the-configuration-directory-structure",children:"Creating the Configuration Directory Structure"}),"\n",(0,r.jsx)(n.p,{children:"You need to create a directory structure on your host system to store RBAC configuration files. The Docker container will mount this directory to access your configurations."}),"\n",(0,r.jsx)(n.p,{children:"Create the directory structure as follows:"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-bash",children:"mkdir -p sam-enterprise/config/auth\n"})}),"\n",(0,r.jsxs)(n.p,{children:["This command creates a ",(0,r.jsx)(n.code,{children:"sam-enterprise"})," directory with a nested ",(0,r.jsx)(n.code,{children:"config/auth"})," subdirectory. The ",(0,r.jsx)(n.code,{children:"auth"})," subdirectory will contain your RBAC configuration files."]}),"\n",(0,r.jsx)(n.h3,{id:"defining-roles-and-permissions",children:"Defining Roles and Permissions"}),"\n",(0,r.jsxs)(n.p,{children:["Create a file named ",(0,r.jsx)(n.code,{children:"role-to-scope-definitions.yaml"})," in the ",(0,r.jsx)(n.code,{children:"sam-enterprise/config/auth"})," directory.\nThis file defines all roles in your system and the scopes (permissions) associated with each role."]}),"\n",(0,r.jsx)(n.p,{children:"Here is an example configuration that defines three roles:"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-yaml",children:'# role-to-scope-definitions.yaml\nroles:\n  enterprise_admin:\n    description: "Full access for enterprise administrators"\n    scopes:\n      - "*"  # Wildcard grants all permissions\n    \n  data_analyst:\n    description: "Data analysis and visualization specialist"\n    scopes:\n      - "tool:data:*"  # All data tools\n      - "artifact:read"\n      - "artifact:create"\n      - "monitor/namespace/*:a2a_messages:subscribe"  # Can monitor any namespace\n    \n  standard_user:\n    description: "Standard user with basic access"\n    scopes:\n      - "artifact:read"\n      - "tool:basic:read"\n      - "tool:basic:search"\n'})}),"\n",(0,r.jsx)(n.p,{children:"This configuration creates three distinct roles:"}),"\n",(0,r.jsxs)(n.p,{children:["The ",(0,r.jsx)(n.code,{children:"enterprise_admin"})," role receives the wildcard scope ",(0,r.jsx)(n.code,{children:"*"}),", which grants all permissions in the system. You should assign this role only to trusted administrators who need complete control over Agent Mesh Enterprise."]}),"\n",(0,r.jsxs)(n.p,{children:["The ",(0,r.jsx)(n.code,{children:"data_analyst"})," role receives permissions tailored for data analysis work. The scope ",(0,r.jsx)(n.code,{children:"tool:data:*"})," grants all permissions for data-related tools (read, write, execute). The ",(0,r.jsx)(n.code,{children:"artifact:read"})," and ",(0,r.jsx)(n.code,{children:"artifact:create"})," scopes allow analysts to view existing artifacts and create new ones. The monitoring scope ",(0,r.jsx)(n.code,{children:"monitor/namespace/*:a2a_messages:subscribe"})," enables analysts to observe message traffic across all namespaces, which helps them understand data flows."]}),"\n",(0,r.jsxs)(n.p,{children:["The ",(0,r.jsx)(n.code,{children:"standard_user"})," role provides minimal permissions for basic operations. Users with this role can read artifacts and perform basic tool operations but cannot create new artifacts or access advanced features."]}),"\n",(0,r.jsx)(n.h3,{id:"assigning-users-to-roles",children:"Assigning Users to Roles"}),"\n",(0,r.jsxs)(n.p,{children:["Create a file named ",(0,r.jsx)(n.code,{children:"user-to-role-assignments.yaml"})," in the ",(0,r.jsx)(n.code,{children:"sam-enterprise/config/auth"})," directory. This file maps user identities to roles."]}),"\n",(0,r.jsx)(n.p,{children:"Here is an example configuration:"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-yaml",children:'# user-to-role-assignments.yaml\nusers:\n  admin@example.com:\n    roles: ["enterprise_admin"]\n    description: "Enterprise Administrator Account"\n    \n  data.analyst@example.com:\n    roles: ["data_analyst"]\n    description: "Senior Data Analyst"\n    \n  user1@example.com:\n    roles: ["standard_user"]\n    description: "Standard Enterprise User"\n'})}),"\n",(0,r.jsx)(n.p,{children:"Each entry in this file maps a user identity (typically an email address) to one or more roles. The user identity must match exactly what your authentication system provides because Agent Mesh Enterprise performs case-sensitive matching."}),"\n",(0,r.jsxs)(n.p,{children:["You can assign multiple roles to a single user by listing them in the ",(0,r.jsx)(n.code,{children:"roles"})," array. When a user has multiple roles, they receive the combined permissions from all assigned roles. For example, if you assign both ",(0,r.jsx)(n.code,{children:"data_analyst"})," and ",(0,r.jsx)(n.code,{children:"standard_user"})," roles to a user, they receive all scopes from both roles."]}),"\n",(0,r.jsxs)(n.p,{children:["The ",(0,r.jsx)(n.code,{children:"description"})," field is optional but recommended. It helps you document the purpose of each user account, which is valuable when reviewing or auditing your RBAC configuration."]}),"\n",(0,r.jsx)(n.h3,{id:"creating-the-enterprise-configuration",children:"Creating the Enterprise Configuration"}),"\n",(0,r.jsxs)(n.p,{children:["Create a file named ",(0,r.jsx)(n.code,{children:"enterprise_config.yaml"})," in the ",(0,r.jsx)(n.code,{children:"sam-enterprise/config"})," directory (not in the ",(0,r.jsx)(n.code,{children:"auth"})," subdirectory). This file tells Agent Mesh Enterprise where to find your RBAC configuration files and how to use them."]}),"\n",(0,r.jsx)(n.admonition,{title:"Optional Configuration",type:"tip",children:(0,r.jsxs)(n.p,{children:["The ",(0,r.jsx)(n.code,{children:"authorization_service"})," configuration block is ",(0,r.jsx)(n.strong,{children:"optional"}),". If omitted, the system defaults to ",(0,r.jsx)(n.code,{children:"deny_all"})," (secure by default) and logs a WARNING message. You must explicitly configure authorization to grant access to users."]})}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-yaml",children:'# enterprise_config.yaml\nauthorization_service:\n  type: "default_rbac"\n  role_to_scope_definitions_path: "config/auth/role-to-scope-definitions.yaml"\n  user_to_role_assignments_path: "config/auth/user-to-role-assignments.yaml"\n\nnamespace: "enterprise_prod"\n'})}),"\n",(0,r.jsxs)(n.p,{children:["The ",(0,r.jsx)(n.code,{children:"authorization_service"})," section configures the RBAC system. The ",(0,r.jsx)(n.code,{children:"type"})," field specifies ",(0,r.jsx)(n.code,{children:"default_rbac"}),", which tells Agent Mesh Enterprise to use the file-based RBAC system. The two path fields point to your RBAC configuration files\u2014these paths are relative to the container's working directory, not your host system."]}),"\n",(0,r.jsxs)(n.p,{children:[(0,r.jsx)(n.strong,{children:"Important:"})," When using ",(0,r.jsx)(n.code,{children:"type: default_rbac"}),", ",(0,r.jsx)(n.code,{children:"role_to_scope_definitions_path"})," is ",(0,r.jsx)(n.strong,{children:"required"}),". The system fails to start if these files are missing or invalid."]}),"\n",(0,r.jsxs)(n.p,{children:["The ",(0,r.jsx)(n.code,{children:"namespace"})," field configures the Agent Mesh Enterprise instance. The namespace isolates this instance from others."]}),"\n",(0,r.jsx)(n.h4,{id:"alternative-development-mode-permissive",children:"Alternative: Development Mode (Permissive)"}),"\n",(0,r.jsx)(n.p,{children:"For local development and testing only, you can disable authorization:"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-yaml",children:'# enterprise_config.yaml - DEVELOPMENT ONLY\nauthorization_service:\n  type: "none"  # Grants full access to all users\n\nnamespace: "enterprise_dev"\n'})}),"\n",(0,r.jsx)(n.admonition,{title:"Security Warning",type:"danger",children:(0,r.jsxs)(n.p,{children:["Using ",(0,r.jsx)(n.code,{children:"type: none"})," disables all authorization checks and grants wildcard ",(0,r.jsx)(n.code,{children:"*"})," scope to every user. This configuration should ",(0,r.jsx)(n.strong,{children:"never"})," be used in production environments. The system logs prominent security warnings when this type is active."]})}),"\n",(0,r.jsx)(n.h4,{id:"default-behavior-no-configuration",children:"Default Behavior (No Configuration)"}),"\n",(0,r.jsxs)(n.p,{children:["If you omit the ",(0,r.jsx)(n.code,{children:"authorization_service"})," block entirely, the system uses secure defaults:"]}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-yaml",children:'# enterprise_config.yaml - Secure by default\n# No authorization_service block = deny_all\n\nnamespace: "enterprise_prod"\n'})}),"\n",(0,r.jsx)(n.p,{children:"When no authorization configuration is present, the system:"}),"\n",(0,r.jsxs)(n.ol,{children:["\n",(0,r.jsx)(n.li,{children:"Logs a WARNING message about missing configuration"}),"\n",(0,r.jsxs)(n.li,{children:["Defaults to ",(0,r.jsx)(n.code,{children:"deny_all"})," authorization type"]}),"\n",(0,r.jsx)(n.li,{children:"Denies all user requests with WARNING logs"}),"\n",(0,r.jsx)(n.li,{children:"Requires explicit RBAC configuration to grant access"}),"\n"]}),"\n",(0,r.jsx)(n.h3,{id:"running-the-docker-container",children:"Running the Docker Container"}),"\n",(0,r.jsxs)(n.p,{children:["Now you can start the Docker container with your RBAC configuration.\nNavigate to your ",(0,r.jsx)(n.code,{children:"sam-enterprise"})," directory and run:"]}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-bash",children:'cd sam-enterprise\n\ndocker run -d \\\n  --name sam-enterprise \\\n  -p 8001:8000 \\\n  -v "$(pwd):/app" \\\n  -e SAM_AUTHORIZATION_CONFIG="/app/config/enterprise_config.yaml" \\\n  -e NAMESPACE=enterprise_prod \\\n  -e ... list here all other necessary env vars ...\n  solace-agent-mesh-enterprise:<tagname>\n'})}),"\n",(0,r.jsx)(n.h3,{id:"verifying-your-configuration",children:"Verifying Your Configuration"}),"\n",(0,r.jsx)(n.p,{children:"After starting the container, you should verify that RBAC is working correctly. Follow these steps:"}),"\n",(0,r.jsxs)(n.ol,{children:["\n",(0,r.jsxs)(n.li,{children:["Open your web browser and navigate to ",(0,r.jsx)(n.code,{children:"http://localhost:8001"})]}),"\n",(0,r.jsxs)(n.li,{children:["Log in using one of the user identities defined in your ",(0,r.jsx)(n.code,{children:"user-to-role-assignments.yaml"})," file"]}),"\n",(0,r.jsx)(n.li,{children:"Attempt to access features that the user should have permission to use"}),"\n",(0,r.jsx)(n.li,{children:"Attempt to access features that the user should not have permission to use"}),"\n"]}),"\n",(0,r.jsx)(n.p,{children:"If RBAC is configured correctly, the user can access permitted features and receives authorization errors when attempting to access restricted features."}),"\n",(0,r.jsx)(n.p,{children:"You can also check the container logs to verify that Agent Mesh Enterprise loaded your configuration files:"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-bash",children:"docker logs sam-enterprise\n"})}),"\n",(0,r.jsx)(n.p,{children:"Look for log messages that indicate successful configuration loading. You should see messages similar to:"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{children:"INFO:solace_ai_connector:[ConfigurableRbacAuthSvc] Successfully loaded role-to-scope definitions from: /app/config/auth/role-to-scope-definitions.yaml\nDEBUG:solace_ai_connector:[ConfigurableRbacAuthSvc] Role 'enterprise_admin' loaded with 1 direct scopes, 1 resolved scopes.\nDEBUG:solace_ai_connector:[ConfigurableRbacAuthSvc] Role 'data_analyst' loaded with 4 direct scopes, 4 resolved scopes.\nDEBUG:solace_ai_connector:[ConfigurableRbacAuthSvc] Role 'standard_user' loaded with 3 direct scopes, 3 resolved scopes.\n"})}),"\n",(0,r.jsx)(n.p,{children:"These messages confirm that Agent Mesh Enterprise found and parsed your configuration files correctly."}),"\n",(0,r.jsx)(n.h2,{id:"understanding-configuration-files",children:"Understanding Configuration Files"}),"\n",(0,r.jsx)(n.p,{children:"Now that you have a working RBAC configuration, you should understand the full structure and capabilities of each configuration file. This knowledge helps you customize the configuration to meet your specific needs."}),"\n",(0,r.jsx)(n.h3,{id:"role-to-scope-definitions-structure",children:"Role-to-Scope Definitions Structure"}),"\n",(0,r.jsxs)(n.p,{children:["The ",(0,r.jsx)(n.code,{children:"role-to-scope-definitions.yaml"})," file supports several features beyond the basic examples shown earlier. Here is the complete structure:"]}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-yaml",children:'roles:\n  role_name:\n    description: "Role description"\n    scopes:\n      - "scope1"\n      - "scope2"\n    inherits:  # Optional - inherit scopes from other roles\n      - "parent_role1"\n      - "parent_role2"\n'})}),"\n",(0,r.jsxs)(n.p,{children:["The ",(0,r.jsx)(n.code,{children:"inherits"})," field allows you to create role hierarchies. When a role inherits from another role, it receives all scopes from the parent role in addition to its own scopes. This feature reduces duplication and makes your configuration easier to maintain."]}),"\n",(0,r.jsx)(n.p,{children:'For example, you might create a base "viewer" role with read-only permissions, then create an "operator" role that inherits from "viewer" and adds write permissions:'}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-yaml",children:'roles:\n  viewer:\n    description: "Read-only access"\n    scopes:\n      - "tool:basic:read"\n      - "artifact:read"\n  \n  operator:\n    description: "Operational access"\n    inherits:\n      - "viewer"\n    scopes:\n      - "tool:basic:*"\n      - "artifact:create"\n'})}),"\n",(0,r.jsxs)(n.p,{children:['In this example, the "operator" role receives all scopes from "viewer" (',(0,r.jsx)(n.code,{children:"tool:basic:read"})," and ",(0,r.jsx)(n.code,{children:"artifact:read"}),") plus its own scopes (",(0,r.jsx)(n.code,{children:"tool:basic:*"})," and ",(0,r.jsx)(n.code,{children:"artifact:create"}),"). Note that ",(0,r.jsx)(n.code,{children:"tool:basic:*"})," includes ",(0,r.jsx)(n.code,{children:"tool:basic:read"}),", so there is some overlap. Agent Mesh Enterprise handles this correctly by deduplicating scopes."]}),"\n",(0,r.jsx)(n.h3,{id:"user-to-role-assignments-structure",children:"User-to-Role Assignments Structure"}),"\n",(0,r.jsxs)(n.p,{children:["The ",(0,r.jsx)(n.code,{children:"user-to-role-assignments.yaml"})," file supports both global user identities and gateway-specific identities. Here is the complete structure:"]}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-yaml",children:'users:\n  user_identity:\n    roles: ["role1", "role2"]\n    description: "User description"\n\n# Optional: Gateway-specific user identities\ngateway_specific_identities:\n  gateway_id:user_identity:\n    roles: ["role1", "role2"]\n    description: "User with specific roles on this gateway"\n'})}),"\n",(0,r.jsxs)(n.p,{children:["The ",(0,r.jsx)(n.code,{children:"users"})," section defines global user identities that apply across all gateways. Most configurations only need this section."]}),"\n",(0,r.jsxs)(n.p,{children:["The ",(0,r.jsx)(n.code,{children:"gateway_specific_identities"})," section allows you to assign different roles to the same user identity on different gateways. This feature is useful in multi-gateway deployments where you want to grant different permissions based on which gateway a user accesses. The key format is ",(0,r.jsx)(n.code,{children:"gateway_id:user_identity"}),", where ",(0,r.jsx)(n.code,{children:"gateway_id"})," matches the gateway ID in your configuration. The default gateway ID is ",(0,r.jsx)(n.code,{children:"_default_enterprise_gateway"}),"."]}),"\n",(0,r.jsx)(n.h3,{id:"enterprise-configuration-structure",children:"Enterprise Configuration Structure"}),"\n",(0,r.jsx)(n.p,{children:"The enterprise configuration file supports multiple authorization service types. Here is the complete structure for the file-based RBAC system:"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-yaml",children:'authorization_service:\n  type: "default_rbac"\n  role_to_scope_definitions_path: "path/to/role-to-scope-definitions.yaml"\n  user_to_role_assignments_path: "path/to/user-to-role-assignments.yaml"\n'})}),"\n",(0,r.jsx)(n.h2,{id:"advanced-configuration-options",children:"Advanced Configuration Options"}),"\n",(0,r.jsx)(n.p,{children:"After you have a basic RBAC configuration working, you might want to explore advanced options that provide additional flexibility and integration capabilities."}),"\n",(0,r.jsx)(n.h3,{id:"production-ready-role-configuration",children:"Production-Ready Role Configuration"}),"\n",(0,r.jsx)(n.p,{children:"A production environment typically needs more sophisticated role definitions than the basic examples\n. Here is a comprehensive configuration that demonstrates best practices:"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-yaml",children:'# role-to-scope-definitions.yaml\nroles:\n  admin:\n    description: "Administrator with full access"\n    scopes:\n      - "*"\n  \n  operator:\n    description: "System operator"\n    scopes:\n      - "tool:basic:*"\n      - "tool:advanced:read"\n      - "artifact:read"\n      - "artifact:create"\n      - "monitor/namespace/*:a2a_messages:subscribe"\n  \n  viewer:\n    description: "Read-only access"\n    scopes:\n      - "tool:basic:read"\n      - "artifact:read"\n      - "monitor/namespace/*:a2a_messages:subscribe"\n'})}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-yaml",children:'# user-to-role-assignments.yaml\nusers:\n  admin@company.com:\n    roles: ["admin"]\n    description: "System Administrator"\n  \n  operator@company.com:\n    roles: ["operator"]\n    description: "System Operator"\n  \n  viewer@company.com:\n    roles: ["viewer"]\n    description: "Read-only User"\n'})}),"\n",(0,r.jsx)(n.p,{children:"This configuration creates a clear hierarchy of access levels. The admin role has unrestricted access, the operator role can perform most operational tasks, and the viewer role provides read-only access for monitoring and auditing purposes."}),"\n",(0,r.jsx)(n.h3,{id:"integrating-with-microsoft-graph",children:"Integrating with Microsoft Graph"}),"\n",(0,r.jsx)(n.p,{children:"For enterprise environments that use Microsoft Entra ID (formerly Azure AD) for user management, you can integrate Agent Mesh Enterprise with Microsoft Graph. This integration allows you to manage user role assignments through Microsoft Graph instead of maintaining a separate YAML file."}),"\n",(0,r.jsxs)(n.p,{children:["To configure Microsoft Graph integration, modify your ",(0,r.jsx)(n.code,{children:"enterprise_config.yaml"}),":"]}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-yaml",children:'# enterprise_config.yaml\nauthorization_service:\n  type: "default_rbac"\n  role_to_scope_definitions_path: "config/auth/role-to-scope-definitions.yaml"\n  user_to_role_provider: "ms_graph"\n  \n  ms_graph_config:\n    ms_graph_tenant_id: ${MS_GRAPH_TENANT_ID}\n    ms_graph_client_id: ${MS_GRAPH_CLIENT_ID}\n    ms_graph_client_secret: ${MS_GRAPH_CLIENT_SECRET}\n'})}),"\n",(0,r.jsxs)(n.p,{children:["This configuration tells Agent Mesh Enterprise to retrieve user role assignments from Microsoft Graph instead of reading them from a YAML file. The ",(0,r.jsx)(n.code,{children:"${...}"})," syntax indicates that these values come from environment variables, which keeps sensitive credentials out of your configuration files."]}),"\n",(0,r.jsxs)(n.p,{children:["When you use Microsoft Graph integration, you still define roles in the ",(0,r.jsx)(n.code,{children:"role-to-scope-definitions.yaml"})," file, but you manage user-to-role assignments through Microsoft Graph groups or attributes."]}),"\n",(0,r.jsx)(n.p,{children:"Run the Docker container with the Microsoft Graph credentials:"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-bash",children:'docker run -d \\\n  --name sam-enterprise \\\n  -p 8000:8001 \\\n  -v "$(pwd):/app" \\\n  -e MS_GRAPH_TENANT_ID=your-tenant-id \\\n  -e MS_GRAPH_CLIENT_ID=your-client-id \\\n  -e MS_GRAPH_CLIENT_SECRET=your-client-secret \\\n  -e NAMESPACE=enterprise_prod \\\n  solace-agent-mesh-enterprise:<tag>\n'})}),"\n",(0,r.jsx)(n.p,{children:"The Microsoft Graph integration requires that you configure an application registration in Microsoft Entra ID with appropriate permissions to read user and group information. The tenant ID identifies your Microsoft Entra ID tenant, the client ID identifies your application registration, and the client secret authenticates your application."}),"\n",(0,r.jsx)(n.h2,{id:"best-practices",children:"Best Practices"}),"\n",(0,r.jsx)(n.p,{children:"Following best practices helps you create a secure, maintainable RBAC configuration that scales with your organization's needs."}),"\n",(0,r.jsx)(n.h3,{id:"security-recommendations",children:"Security Recommendations"}),"\n",(0,r.jsx)(n.p,{children:"You should implement these security practices to protect your Agent Mesh Enterprise deployment:"}),"\n",(0,r.jsx)(n.p,{children:"Apply the principle of least privilege by assigning users only the minimum permissions necessary for their tasks. Start with restrictive permissions and add more as needed, rather than starting with broad permissions and removing them later. This approach reduces the risk of unauthorized access."}),"\n",(0,r.jsx)(n.p,{children:"Conduct regular audits of your role assignments and permissions. Review who has access to what features and verify that access levels remain appropriate as job responsibilities change. Remove access for users who no longer need it."}),"\n",(0,r.jsx)(n.p,{children:"Protect your RBAC configuration files with appropriate file permissions on your host system. These files control access to your entire Agent Mesh Enterprise deployment, so you should restrict read and write access to authorized administrators only."}),"\n",(0,r.jsx)(n.p,{children:"Store sensitive information like Microsoft Graph credentials as environment variables rather than hardcoding them in configuration files. Environment variables provide better security because they do not appear in version control systems or configuration backups."}),"\n",(0,r.jsx)(n.p,{children:"Never use development configurations in production environments. Development configurations often include test accounts with elevated permissions or relaxed security settings that are inappropriate for production use."}),"\n",(0,r.jsx)(n.h3,{id:"role-design-principles",children:"Role Design Principles"}),"\n",(0,r.jsx)(n.p,{children:"Well-designed roles make your RBAC configuration easier to understand and maintain:"}),"\n",(0,r.jsx)(n.p,{children:"Create roles that align with job functions in your organization. Each role should represent a specific type of work that users perform. This alignment makes it easier to determine which role to assign to new users."}),"\n",(0,r.jsx)(n.p,{children:"Use role inheritance to build a logical hierarchy. If one role needs all the permissions of another role plus additional permissions, use inheritance rather than duplicating scopes. This approach reduces configuration size and makes updates easier."}),"\n",(0,r.jsx)(n.p,{children:'Use clear, descriptive names for roles that indicate their purpose. Names like "data_analyst" or "system_operator" are more meaningful than generic names like "role1" or "user_type_a".'}),"\n",(0,r.jsx)(n.p,{children:"Document the purpose and scope of each role in the description field. This documentation helps other administrators understand your RBAC configuration and makes it easier to maintain over time."}),"\n",(0,r.jsxs)(n.p,{children:["Minimize wildcard usage in scope definitions. While wildcards like ",(0,r.jsx)(n.code,{children:"*"})," or ",(0,r.jsx)(n.code,{children:"tool:*:*"})," are convenient, they grant broad permissions that might include features you did not intend to allow. Use specific scopes whenever possible, and reserve wildcards for administrator roles."]}),"\n",(0,r.jsx)(n.h3,{id:"docker-specific-recommendations",children:"Docker-Specific Recommendations"}),"\n",(0,r.jsx)(n.p,{children:"When you run Agent Mesh Enterprise in Docker, follow these recommendations:"}),"\n",(0,r.jsx)(n.p,{children:"Use Docker volumes for persistent configuration storage. The volume mount approach shown in this guide ensures that your configuration persists even if you remove and recreate the container."}),"\n",(0,r.jsx)(n.p,{children:"Create separate configuration files for different environments (development, staging, production). This separation prevents accidental use of inappropriate configurations and makes it easier to maintain environment-specific settings."}),"\n",(0,r.jsx)(n.p,{children:"Implement health checks to verify that RBAC is functioning correctly. You can add a health check to your Docker run command that periodically tests whether the container is responding correctly."}),"\n",(0,r.jsx)(n.p,{children:"Regularly backup your RBAC configuration files. Store backups in a secure location separate from your Docker host. If you lose your configuration files, you lose control over who can access your Agent Mesh Enterprise deployment."}),"\n",(0,r.jsx)(n.p,{children:"Follow Docker security best practices such as running containers as non-root users and using read-only filesystems where possible. These practices reduce the impact of potential security vulnerabilities."}),"\n",(0,r.jsx)(n.h2,{id:"troubleshooting",children:"Troubleshooting"}),"\n",(0,r.jsx)(n.p,{children:"When you encounter issues with your RBAC configuration, systematic troubleshooting helps you identify and resolve problems quickly."}),"\n",(0,r.jsx)(n.h3,{id:"authorization-denied-for-valid-user",children:"Authorization Denied for Valid User"}),"\n",(0,r.jsx)(n.p,{children:"If a user cannot access features they should have permission to use, you might see authorization denied messages in the logs or user interface."}),"\n",(0,r.jsxs)(n.p,{children:["To resolve this issue, first verify that the user identity matches exactly what appears in your ",(0,r.jsx)(n.code,{children:"user-to-role-assignments.yaml"})," file. Agent Mesh Enterprise performs case-sensitive matching, so ",(0,r.jsx)(n.code,{children:"user@example.com"})," and ",(0,r.jsx)(n.code,{children:"User@example.com"})," are different identities."]}),"\n",(0,r.jsxs)(n.p,{children:["Next, check that the role assigned to the user has the necessary scopes. Review the ",(0,r.jsx)(n.code,{children:"role-to-scope-definitions.yaml"})," file and verify that the role includes scopes for the features the user is trying to access."]}),"\n",(0,r.jsx)(n.p,{children:"Ensure that your configuration files are correctly mounted in the Docker container. You can verify the mount by running:"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-bash",children:"docker exec -it sam-enterprise ls -la /app/config/auth\n"})}),"\n",(0,r.jsxs)(n.p,{children:["This command lists the files in the mounted directory. You should see your ",(0,r.jsx)(n.code,{children:"role-to-scope-definitions.yaml"})," and ",(0,r.jsx)(n.code,{children:"user-to-role-assignments.yaml"})," files."]}),"\n",(0,r.jsx)(n.p,{children:"Check the container logs for authorization service errors:"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-bash",children:"docker logs sam-enterprise\n"})}),"\n",(0,r.jsxs)(n.p,{children:["Look for messages with the ",(0,r.jsx)(n.code,{children:"[ConfigurableRbacAuthSvc]"})," prefix. These messages indicate whether Agent Mesh Enterprise successfully loaded your configuration files and how it resolved roles and scopes. You should see messages like:"]}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{children:"INFO:solace_ai_connector:[ConfigurableRbacAuthSvc] Successfully loaded role-to-scope definitions from: /app/config/auth/role-to-scope-definitions.yaml\nDEBUG:solace_ai_connector:[ConfigurableRbacAuthSvc] Role 'enterprise_admin' loaded with 1 direct scopes, 1 resolved scopes.\nDEBUG:solace_ai_connector:[ConfigurableRbacAuthSvc] Role 'data_analyst' loaded with 4 direct scopes, 4 resolved scopes.\nDEBUG:solace_ai_connector:[ConfigurableRbacAuthSvc] Role 'standard_user' loaded with 1 direct scopes, 1 resolved scopes.\n"})}),"\n",(0,r.jsx)(n.h3,{id:"configuration-files-not-found",children:"Configuration Files Not Found"}),"\n",(0,r.jsx)(n.p,{children:"If you see error messages about missing configuration files or the system uses default authorization behavior, the container cannot find your configuration files."}),"\n",(0,r.jsxs)(n.p,{children:["Check that the volume mount in your Docker run command is correct. The mount should map your host directory to ",(0,r.jsx)(n.code,{children:"/app"})," in the container. Verify that you are using the correct path on your host system."]}),"\n",(0,r.jsx)(n.p,{children:"Ensure that file permissions allow the container user to read the files. On Linux systems, you might need to adjust file permissions:"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-bash",children:"chmod 644 sam-enterprise/config/auth/*.yaml\n"})}),"\n",(0,r.jsx)(n.p,{children:"Check for typos in file names or paths. The file names are case-sensitive, and even small typos prevent Agent Mesh Enterprise from finding your configuration files."}),"\n",(0,r.jsx)(n.h3,{id:"microsoft-graph-integration-not-working",children:"Microsoft Graph Integration Not Working"}),"\n",(0,r.jsx)(n.p,{children:"If users cannot authenticate when you use Microsoft Graph integration, or you see error messages related to Microsoft Graph in the logs, several issues might be causing the problem."}),"\n",(0,r.jsx)(n.p,{children:"Verify that your Microsoft Graph credentials are correct. Double-check the tenant ID, client ID, and client secret against your Microsoft Entra ID application registration."}),"\n",(0,r.jsx)(n.p,{children:"Check that environment variables are properly set in your Docker run command. You can verify environment variables inside the container:"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-bash",children:"docker exec -it sam-enterprise env | grep MS_GRAPH\n"})}),"\n",(0,r.jsx)(n.p,{children:"Ensure that your Microsoft Graph application has the necessary permissions. The application needs permissions to read user and group information from Microsoft Entra ID."}),"\n",(0,r.jsxs)(n.p,{children:["Check network connectivity from the container to Microsoft Graph endpoints. The container must be able to reach ",(0,r.jsx)(n.code,{children:"graph.microsoft.com"})," over HTTPS. Firewall rules or network policies might block this connectivity."]}),"\n",(0,r.jsx)(n.h3,{id:"debugging-authorization-issues",children:"Debugging Authorization Issues"}),"\n",(0,r.jsx)(n.p,{children:"When you need to investigate authorization problems in detail, follow these debugging steps:"}),"\n",(0,r.jsxs)(n.p,{children:["Enable debug logging by adding a log level setting to your ",(0,r.jsx)(n.code,{children:"enterprise_config.yaml"}),":"]}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-yaml",children:'# Add to your enterprise_config.yaml\nlog_level: "DEBUG"\n'})}),"\n",(0,r.jsx)(n.p,{children:"Debug logging provides detailed information about authorization decisions, including which scopes the system checked and why it allowed or denied access."}),"\n",(0,r.jsx)(n.p,{children:"Check the container logs for detailed information:"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-bash",children:"docker logs sam-enterprise\n"})}),"\n",(0,r.jsxs)(n.p,{children:["Look for log messages with the ",(0,r.jsx)(n.code,{children:"[EnterpriseConfigResolverImpl]"})," or ",(0,r.jsx)(n.code,{children:"[ConfigurableRbacAuthSvc]"})," prefixes. These messages show how Agent Mesh Enterprise loaded and processed your configuration."]}),"\n",(0,r.jsx)(n.p,{children:"Temporarily assign the user to an administrator role to verify whether the issue is permission-related. If the user can access features when assigned to an admin role, the problem is with the scopes assigned to their original role."}),"\n",(0,r.jsx)(n.p,{children:"Inspect the mounted configuration files inside the container to verify that they contain the expected content:"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-bash",children:"docker exec -it sam-enterprise cat /app/config/auth/role-to-scope-definitions.yaml\ndocker exec -it sam-enterprise cat /app/config/auth/user-to-role-assignments.yaml\n"})}),"\n",(0,r.jsx)(n.p,{children:"This verification ensures that the files inside the container match your host files and that the volume mount is working correctly."}),"\n",(0,r.jsx)(n.h3,{id:"getting-help",children:"Getting Help"}),"\n",(0,r.jsx)(n.p,{children:"If you continue to experience issues after following these troubleshooting steps, you can get additional help:"}),"\n",(0,r.jsx)(n.p,{children:"Check the Agent Mesh Enterprise documentation for updates or additional information about RBAC configuration."}),"\n",(0,r.jsx)(n.p,{children:"Review the container logs for specific error messages. Error messages often include details about what went wrong and how to fix it."}),"\n",(0,r.jsx)(n.p,{children:"Contact Solace support with details of your configuration and the issues you are experiencing. Include relevant log excerpts and describe the steps you have already taken to troubleshoot the problem."}),"\n",(0,r.jsx)(n.h2,{id:"conclusion",children:"Conclusion"}),"\n",(0,r.jsx)(n.p,{children:"Setting up Role-Based Access Control in your Agent Mesh Enterprise Docker installation provides enhanced security and granular access control. This guide has walked you through understanding RBAC concepts, planning your configuration, creating configuration files, and troubleshooting common issues."}),"\n",(0,r.jsx)(n.p,{children:"You now have the knowledge to configure RBAC to meet your organization's specific requirements while maintaining a secure and manageable environment. Remember to regularly review and update your RBAC configuration as your organization's needs evolve, and always follow security best practices when managing access control."})]})}function h(e={}){const{wrapper:n}={...(0,t.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 s=i(6540);const r={},t=s.createContext(r);function o(e){const n=s.useContext(t);return s.useMemo((function(){return"function"==typeof e?e(n):{...n,...e}}),[n,e])}function a(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(r):e.components||r:o(e.components),s.createElement(t.Provider,{value:n},e.children)}}}]);

solace_agent_mesh/assets/docs/assets/js/9bb13469.4523ae20.js

@@ -0,0 +1 @@
+"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[6239],{1743:(e,n,t)=>{t.r(n),t.d(n,{assets:()=>a,contentTitle:()=>r,default:()=>m,frontMatter:()=>l,metadata:()=>o,toc:()=>c});const o=JSON.parse('{"id":"documentation/developing/tutorials/mcp-integration","title":"MCP Integration","description":"This tutorial walks you through the process of integrating a Model Context Protocol (MCP) Server into Agent Mesh.","source":"@site/docs/documentation/developing/tutorials/mcp-integration.md","sourceDirName":"documentation/developing/tutorials","slug":"/documentation/developing/tutorials/mcp-integration","permalink":"/solace-agent-mesh/docs/documentation/developing/tutorials/mcp-integration","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/developing/tutorials/mcp-integration.md","tags":[],"version":"current","sidebarPosition":10,"frontMatter":{"title":"MCP Integration","sidebar_position":10},"sidebar":"docSidebar","previous":{"title":"Build Your Own Agent","permalink":"/solace-agent-mesh/docs/documentation/developing/tutorials/custom-agent"},"next":{"title":"REST Gateway","permalink":"/solace-agent-mesh/docs/documentation/developing/tutorials/rest-gateway"}}');var s=t(4848),i=t(8453);const l={title:"MCP Integration",sidebar_position:10},r="MCP Integration",a={},c=[{value:"Setting Up the Environment",id:"setting-up-the-environment",level:2},{value:"Adding MCP Tools to an Agent",id:"adding-mcp-tools-to-an-agent",level:2},{value:"1. Stdio Connection (Local MCP Servers)",id:"1-stdio-connection-local-mcp-servers",level:3},{value:"2. SSE Connection (Remote MCP Servers)",id:"2-sse-connection-remote-mcp-servers",level:3},{value:"3. StreamableHTTP Connection (Remote MCP Servers)",id:"3-streamablehttp-connection-remote-mcp-servers",level:3},{value:"4. Docker Connection (Containerized MCP Servers)",id:"4-docker-connection-containerized-mcp-servers",level:3},{value:"Complete Example: Filesystem MCP Agent",id:"complete-example-filesystem-mcp-agent",level:2},{value:"Configuration Options",id:"configuration-options",level:2},{value:"Tool Filtering",id:"tool-filtering",level:3},{value:"Single Tool (tool_name)",id:"single-tool-tool_name",level:4},{value:"Allow List",id:"allow-list",level:4},{value:"Deny List",id:"deny-list",level:4},{value:"Environment Variables",id:"environment-variables",level:3},{value:"Running Your MCP-Enabled Agent",id:"running-your-mcp-enabled-agent",level:2},{value:"How MCP Integration Works",id:"how-mcp-integration-works",level:2},{value:"Testing Your MCP Integration",id:"testing-your-mcp-integration",level:2}];function d(e){const n={a:"a",admonition:"admonition",code:"code",h1:"h1",h2:"h2",h3:"h3",h4:"h4",header:"header",li:"li",ol:"ol",p:"p",pre:"pre",strong:"strong",ul:"ul",...(0,i.R)(),...e.components};return(0,s.jsxs)(s.Fragment,{children:[(0,s.jsx)(n.header,{children:(0,s.jsx)(n.h1,{id:"mcp-integration",children:"MCP Integration"})}),"\n",(0,s.jsx)(n.p,{children:"This tutorial walks you through the process of integrating a Model Context Protocol (MCP) Server into Agent Mesh."}),"\n",(0,s.jsx)(n.admonition,{title:"Learn about agents",type:"info",children:(0,s.jsxs)(n.p,{children:["You should have an understanding of agents in Agent Mesh. For more information, see ",(0,s.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/components/agents",children:"Agents"}),"."]})}),"\n",(0,s.jsxs)(n.p,{children:["Agent Mesh now provides ",(0,s.jsx)(n.strong,{children:"native MCP support"})," through the framework itself. No additional plugins are required - you can connect to MCP servers directly by configuring your agent YAML file with MCP tools."]}),"\n",(0,s.jsx)(n.p,{children:"MCP integration allows your agents to connect to external MCP servers and use their tools, resources, and prompts seamlessly within the A2A protocol ecosystem."}),"\n",(0,s.jsx)(n.h2,{id:"setting-up-the-environment",children:"Setting Up the Environment"}),"\n",(0,s.jsxs)(n.p,{children:["You must ",(0,s.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/installing-and-configuring/installation",children:"install Agent Mesh and the CLI"}),", and then ",(0,s.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/installing-and-configuring/run-project",children:"create a new Agent Mesh project"}),"."]}),"\n",(0,s.jsx)(n.p,{children:"For this tutorial using the filesystem MCP server, you also need Node.js and NPM installed."}),"\n",(0,s.jsx)(n.h2,{id:"adding-mcp-tools-to-an-agent",children:"Adding MCP Tools to an Agent"}),"\n",(0,s.jsx)(n.p,{children:"MCP integration is accomplished by adding MCP tools directly to your agent configuration. There are three main connection types supported:"}),"\n",(0,s.jsx)(n.h3,{id:"1-stdio-connection-local-mcp-servers",children:"1. Stdio Connection (Local MCP Servers)"}),"\n",(0,s.jsx)(n.p,{children:"This is the most common method for connecting to MCP servers that run as local processes:"}),"\n",(0,s.jsxs)(n.admonition,{title:"Install node package",type:"info",children:[(0,s.jsx)(n.p,{children:"You must install node package @modelcontextprotocol/server-filesystem securely in your local system."}),(0,s.jsxs)(n.p,{children:["You must set the ",(0,s.jsx)(n.code,{children:"command"})," parameter to your local path that points to the ",(0,s.jsx)(n.code,{children:"mcp-server-filesystem"})," binary executable."]})]}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-yaml",children:'tools:\n  - tool_type: mcp\n    connection_params:\n      type: stdio\n      command: "./node_modules/.bin/mcp-server-filesystem"\n      args:\n        - "/tmp/samv2"\n'})}),"\n",(0,s.jsx)(n.h3,{id:"2-sse-connection-remote-mcp-servers",children:"2. SSE Connection (Remote MCP Servers)"}),"\n",(0,s.jsx)(n.p,{children:"For connecting to remote MCP servers using Server-Sent Events:"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-yaml",children:'tools:\n  - tool_type: mcp\n    connection_params:\n      type: sse\n      url: "https://mcp.example.com/v1/sse"\n      headers:\n        Authorization: "Bearer ${MCP_AUTH_TOKEN}"\n'})}),"\n",(0,s.jsx)(n.h3,{id:"3-streamablehttp-connection-remote-mcp-servers",children:"3. StreamableHTTP Connection (Remote MCP Servers)"}),"\n",(0,s.jsx)(n.p,{children:"For connecting to remote MCP servers using Server-Sent Events:"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-yaml",children:'tools:\n  - tool_type: mcp\n    connection_params:\n      type: streamable-http\n      url: "https://mcp.example.com:<port>/mcp/message"\n      headers:\n        Authorization: "Bearer ${MCP_AUTH_TOKEN}"\n'})}),"\n",(0,s.jsx)(n.h3,{id:"4-docker-connection-containerized-mcp-servers",children:"4. Docker Connection (Containerized MCP Servers)"}),"\n",(0,s.jsx)(n.p,{children:"For running MCP servers in Docker containers:"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-yaml",children:'tools:\n  - tool_type: mcp\n    connection_params:\n      type: stdio\n      command: "docker"\n      args:\n        - "run"\n        - "-i"\n        - "--rm"\n        - "-e"\n        - "API_KEY"\n        - "mcp-server-image:latest"\n    environment_variables:\n      API_KEY: ${MY_API_KEY}\n'})}),"\n",(0,s.jsx)(n.h2,{id:"complete-example-filesystem-mcp-agent",children:"Complete Example: Filesystem MCP Agent"}),"\n",(0,s.jsx)(n.p,{children:"Here is a complete example of an agent that uses the filesystem MCP server:"}),"\n",(0,s.jsxs)(n.admonition,{title:"Install node package",type:"info",children:[(0,s.jsx)(n.p,{children:"You must install node package @modelcontextprotocol/server-filesystem securely in your local system."}),(0,s.jsxs)(n.p,{children:["You must set the ",(0,s.jsx)(n.code,{children:"command"})," parameter to your local path that points to the ",(0,s.jsx)(n.code,{children:"mcp-server-filesystem"})," binary executable."]})]}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-yaml",children:'# configs/agents/filesystem_agent.yaml\nlog:\n  stdout_log_level: INFO\n  log_file_level: DEBUG\n  log_file: filesystem_agent.log\n\n!include ../shared_config.yaml\n\napps:\n  - name: filesystem_mcp_agent_app\n    app_base_path: .\n    app_module: solace_agent_mesh.agent.sac.app\n    broker:\n      <<: *broker_connection\n\n    app_config:\n      namespace: ${NAMESPACE}\n      supports_streaming: true\n      agent_name: "FileSystemAgent"\n      display_name: "File System"\n      model: *general_model\n      \n      instruction: |\n        You can interact with the local filesystem using MCP tools.\n        Use the available tools to read, write, and manage files as requested.\n\n      tools:\n        - tool_type: mcp\n          connection_params:\n            type: stdio\n            command: "./node_modules/.bin/mcp-server-filesystem"\n            args:\n              - "/tmp/samv2"\n        - tool_type: builtin-group\n          group_name: "artifact_management"\n\n      session_service: *default_session_service\n      artifact_service: *default_artifact_service\n\n      # Agent discovery and communication\n      agent_card:\n        description: "An agent that interacts with the local filesystem via MCP."\n        defaultInputModes: ["text"]\n        defaultOutputModes: ["text", "file"]\n        skills: []\n\n      agent_card_publishing: { interval_seconds: 10 }\n      agent_discovery: { enabled: true }\n      inter_agent_communication:\n        allow_list: ["*"]\n        request_timeout_seconds: 30\n'})}),"\n",(0,s.jsx)(n.h2,{id:"configuration-options",children:"Configuration Options"}),"\n",(0,s.jsx)(n.h3,{id:"tool-filtering",children:"Tool Filtering"}),"\n",(0,s.jsx)(n.p,{children:"You can control which tools from an MCP server are available to your agent using three mutually exclusive filtering options."}),"\n",(0,s.jsx)(n.admonition,{title:"Install node package",type:"info",children:(0,s.jsxs)(n.p,{children:["The examples below use the filesystem MCP server. You must install node package @modelcontextprotocol/server-filesystem securely in your local system and set the ",(0,s.jsx)(n.code,{children:"command"})," parameter to your local path that points to the ",(0,s.jsx)(n.code,{children:"mcp-server-filesystem"})," binary executable."]})}),"\n",(0,s.jsx)(n.h4,{id:"single-tool-tool_name",children:"Single Tool (tool_name)"}),"\n",(0,s.jsxs)(n.p,{children:["Use ",(0,s.jsx)(n.code,{children:"tool_name"})," to expose only a single specific tool:"]}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-yaml",children:'tools:\n  - tool_type: mcp\n    tool_name: "read_file"  # Only expose the read_file tool\n    connection_params:\n      type: stdio\n      command: "./node_modules/.bin/mcp-server-filesystem"\n      args:\n        - "/tmp/samv2"\n'})}),"\n",(0,s.jsx)(n.h4,{id:"allow-list",children:"Allow List"}),"\n",(0,s.jsxs)(n.p,{children:["Use ",(0,s.jsx)(n.code,{children:"allow_list"})," to expose multiple specific tools:"]}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-yaml",children:'tools:\n  - tool_type: mcp\n    allow_list:  # Only expose these tools\n      - read_file\n      - write_file\n      - list_directory\n    connection_params:\n      type: stdio\n      command: "./node_modules/.bin/mcp-server-filesystem"\n      args:\n        - "/tmp/samv2"\n'})}),"\n",(0,s.jsx)(n.h4,{id:"deny-list",children:"Deny List"}),"\n",(0,s.jsxs)(n.p,{children:["Use ",(0,s.jsx)(n.code,{children:"deny_list"})," to expose all tools except specific ones:"]}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-yaml",children:'tools:\n  - tool_type: mcp\n    deny_list:  # Expose all tools EXCEPT these\n      - delete_file\n      - move_file\n    connection_params:\n      type: stdio\n      command: "./node_modules/.bin/mcp-server-filesystem"\n      args:\n        - "/tmp/samv2"\n'})}),"\n",(0,s.jsx)(n.admonition,{title:"Mutual Exclusivity",type:"warning",children:(0,s.jsxs)(n.p,{children:["The ",(0,s.jsx)(n.code,{children:"tool_name"}),", ",(0,s.jsx)(n.code,{children:"allow_list"}),", and ",(0,s.jsx)(n.code,{children:"deny_list"})," options are mutually exclusive. You can only use one of these filtering options per MCP tool configuration."]})}),"\n",(0,s.jsx)(n.h3,{id:"environment-variables",children:"Environment Variables"}),"\n",(0,s.jsxs)(n.p,{children:["Pass environment variables to MCP servers using the ",(0,s.jsx)(n.code,{children:"environment_variables"})," block:"]}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-yaml",children:'tools:\n  - tool_type: mcp\n    connection_params:\n      type: stdio\n      command: "my-mcp-server"\n    environment_variables:\n      API_KEY: ${MY_API_KEY}\n      DEBUG_MODE: "true"\n      CONFIG_PATH: "/etc/myconfig"\n'})}),"\n",(0,s.jsx)(n.h2,{id:"running-your-mcp-enabled-agent",children:"Running Your MCP-Enabled Agent"}),"\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:"Create the working directory"})," (for filesystem example):"]}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-sh",children:'mkdir -p /tmp/samv2\necho "Hello MCP!" > /tmp/samv2/test.txt\n'})}),"\n"]}),"\n",(0,s.jsxs)(n.li,{children:["\n",(0,s.jsxs)(n.p,{children:[(0,s.jsx)(n.strong,{children:"Set required environment variables"}),":"]}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-sh",children:'export NAMESPACE="myorg/dev"\nexport SOLACE_BROKER_URL="ws://localhost:8008"\n# ... other Solace broker settings\n'})}),"\n"]}),"\n",(0,s.jsxs)(n.li,{children:["\n",(0,s.jsxs)(n.p,{children:[(0,s.jsx)(n.strong,{children:"Run the agent"}),":"]}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-sh",children:"sam run configs/agents/filesystem_agent.yaml\n"})}),"\n"]}),"\n"]}),"\n",(0,s.jsx)(n.h2,{id:"how-mcp-integration-works",children:"How MCP Integration Works"}),"\n",(0,s.jsx)(n.p,{children:"When your agent starts:"}),"\n",(0,s.jsxs)(n.ol,{children:["\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Connection"}),": The framework establishes a connection to the MCP server using the specified connection parameters"]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Discovery"}),": It queries the MCP server for available tools, resources, and prompts"]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Registration"}),": Available capabilities are registered as agent tools."]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Communication"}),": The agent can use these tools through the standard A2A protocol, with the framework handling MCP protocol translation"]}),"\n"]}),"\n",(0,s.jsx)(n.h2,{id:"testing-your-mcp-integration",children:"Testing Your MCP Integration"}),"\n",(0,s.jsx)(n.p,{children:"Once your MCP-enabled agent is running, you can test it through any gateway in your project (such as the Web UI gateway):"}),"\n",(0,s.jsxs)(n.ol,{children:["\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Access your gateway"})," (for example, Web UI at ",(0,s.jsx)(n.code,{children:"http://localhost:8000"}),")"]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Send a request"})," to test the MCP functionality:","\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsx)(n.li,{children:'"List the files in the directory"'}),"\n",(0,s.jsx)(n.li,{children:'"Create a simple text file with some content"'}),"\n",(0,s.jsx)(n.li,{children:'"Read the contents of test.txt"'}),"\n"]}),"\n"]}),"\n"]}),"\n",(0,s.jsx)(n.p,{children:"The agent uses the MCP tools to interact with the filesystem and provide responses through the A2A protocol."})]})}function m(e={}){const{wrapper:n}={...(0,i.R)(),...e.components};return n?(0,s.jsx)(n,{...e,children:(0,s.jsx)(d,{...e})}):d(e)}},8453:(e,n,t)=>{t.d(n,{R:()=>l,x:()=>r});var o=t(6540);const s={},i=o.createContext(s);function l(e){const n=o.useContext(i);return o.useMemo((function(){return"function"==typeof e?e(n):{...n,...e}}),[n,e])}function r(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(s):e.components||s:l(e.components),o.createElement(i.Provider,{value:n},e.children)}}}]);