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

solace_agent_mesh/assets/docs/assets/js/c198a0dc.8f31f867.js

@@ -0,0 +1 @@
+"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[5948],{9061:(e,n,o)=>{o.r(n),o.d(n,{assets:()=>a,contentTitle:()=>l,default:()=>h,frontMatter:()=>r,metadata:()=>i,toc:()=>c});const i=JSON.parse('{"id":"documentation/developing/tutorials/bedrock-agents","title":"Amazon Bedrock Agents","description":"This tutorial walks you through the process of integrating Amazon Bedrock Agents and Flows into Agent Mesh. This integration allows you to create agents that can interact with one or multiple Bedrock Agents or Flows, extending your Agent Mesh project with powerful AI capabilities from AWS.","source":"@site/docs/documentation/developing/tutorials/bedrock-agents.md","sourceDirName":"documentation/developing/tutorials","slug":"/documentation/developing/tutorials/bedrock-agents","permalink":"/solace-agent-mesh/docs/documentation/developing/tutorials/bedrock-agents","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/developing/tutorials/bedrock-agents.md","tags":[],"version":"current","sidebarPosition":30,"frontMatter":{"title":"Amazon Bedrock Agents","sidebar_position":30,"toc_max_heading_level":4},"sidebar":"docSidebar","previous":{"title":"Event Mesh Gateway","permalink":"/solace-agent-mesh/docs/documentation/developing/tutorials/event-mesh-gateway"},"next":{"title":"SQL Database Integration","permalink":"/solace-agent-mesh/docs/documentation/developing/tutorials/sql-database"}}');var s=o(4848),t=o(8453);const r={title:"Amazon Bedrock Agents",sidebar_position:30,toc_max_heading_level:4},l="Amazon Bedrock Agents Integration",a={},c=[{value:"What are Amazon Bedrock Agents and Flows?",id:"what-are-amazon-bedrock-agents-and-flows",level:2},{value:"Setting Up the Environment",id:"setting-up-the-environment",level:2},{value:"Create Bedrock Agents and Flows",id:"create-bedrock-agents-and-flows",level:3},{value:"Create an Agent Mesh Project",id:"create-an-agent-mesh-project",level:3},{value:"Integrating Bedrock with Agent Mesh",id:"integrating-bedrock-with-agent-mesh",level:2},{value:"Adding the Bedrock Agent Plugin",id:"adding-the-bedrock-agent-plugin",level:3},{value:"Configuring the Bedrock Agent",id:"configuring-the-bedrock-agent",level:2},{value:"Understanding the Configuration Structure",id:"understanding-the-configuration-structure",level:3},{value:"Example Configuration",id:"example-configuration",level:3},{value:"Customizing Your Configuration",id:"customizing-your-configuration",level:3},{value:"Environment Variables",id:"environment-variables",level:3},{value:"Required Solace Variables:",id:"required-solace-variables",level:4},{value:"Optional AWS Variables:",id:"optional-aws-variables",level:4},{value:"Running and Testing Your Integration",id:"running-and-testing-your-integration",level:2},{value:"Starting Your Agent Mesh Project",id:"starting-your-agent-mesh-project",level:3},{value:"Testing the Integration",id:"testing-the-integration",level:3},{value:"Using the Web UI Gateway",id:"using-the-web-ui-gateway",level:4},{value:"Testing with File Uploads",id:"testing-with-file-uploads",level:4},{value:"Troubleshooting",id:"troubleshooting",level:2},{value:"Common Issues and Solutions",id:"common-issues-and-solutions",level:3},{value:"Authentication Errors",id:"authentication-errors",level:4},{value:"Configuration Errors",id:"configuration-errors",level:4},{value:"Connection Issues",id:"connection-issues",level:4},{value:"File Upload Issues",id:"file-upload-issues",level:4}];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,t.R)(),...e.components};return(0,s.jsxs)(s.Fragment,{children:[(0,s.jsx)(n.header,{children:(0,s.jsx)(n.h1,{id:"amazon-bedrock-agents-integration",children:"Amazon Bedrock Agents Integration"})}),"\n",(0,s.jsx)(n.p,{children:"This tutorial walks you through the process of integrating Amazon Bedrock Agents and Flows into Agent Mesh. This integration allows you to create agents that can interact with one or multiple Bedrock Agents or Flows, extending your Agent Mesh project with powerful AI capabilities from AWS."}),"\n",(0,s.jsx)(n.h2,{id:"what-are-amazon-bedrock-agents-and-flows",children:"What are Amazon Bedrock Agents and Flows?"}),"\n",(0,s.jsx)(n.p,{children:"Amazon Bedrock Agents are AI assistants that can be customized to perform specific tasks using foundation models (FMs). They can connect to enterprise systems and data sources, allowing them to take actions on behalf of users."}),"\n",(0,s.jsx)(n.p,{children:"Amazon Bedrock Flows are visual workflows that orchestrate multiple foundation models to solve complex problems. They allow you to chain together different AI capabilities without writing code."}),"\n",(0,s.jsx)(n.p,{children:"By integrating these services with Agent Mesh, you can:"}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsx)(n.li,{children:"Use the extensible Agent Mesh framework to combine Bedrock agents and flows with other agents."}),"\n",(0,s.jsx)(n.li,{children:"Create conversational interfaces that leverage Bedrock agents and flows."}),"\n",(0,s.jsx)(n.li,{children:"Connect your Agent Mesh agents to enterprise data sources through Bedrock."}),"\n",(0,s.jsx)(n.li,{children:"Maintain a consistent experience across different agent providers by centralizing them in Agent Mesh."}),"\n"]}),"\n",(0,s.jsx)(n.admonition,{title:"Learn about Bedrock Agents and Flows",type:"info",children:(0,s.jsxs)(n.p,{children:["Check the official documentation for ",(0,s.jsx)(n.a,{href:"https://aws.amazon.com/bedrock/agents/",children:"Amazon Bedrock Agents"})," and ",(0,s.jsx)(n.a,{href:"https://aws.amazon.com/bedrock/flows/",children:"Amazon Bedrock Flows"})," to learn more about these features."]})}),"\n",(0,s.jsx)(n.h2,{id:"setting-up-the-environment",children:"Setting Up the Environment"}),"\n",(0,s.jsx)(n.h3,{id:"create-bedrock-agents-and-flows",children:"Create Bedrock Agents and Flows"}),"\n",(0,s.jsx)(n.p,{children:"Follow these steps to create your Bedrock resources:"}),"\n",(0,s.jsxs)(n.ol,{children:["\n",(0,s.jsxs)(n.li,{children:["\n",(0,s.jsx)(n.p,{children:(0,s.jsx)(n.strong,{children:"Log in to your AWS console"})}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsx)(n.li,{children:"Navigate to the Amazon Bedrock service"}),"\n"]}),"\n"]}),"\n",(0,s.jsxs)(n.li,{children:["\n",(0,s.jsx)(n.p,{children:(0,s.jsx)(n.strong,{children:"Create Bedrock Agents"})}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:["Go to the ",(0,s.jsx)(n.strong,{children:"Agents"})," tab in the Bedrock console"]}),"\n",(0,s.jsx)(n.li,{children:'Click "Create agent"'}),"\n",(0,s.jsxs)(n.li,{children:["Follow the wizard to configure your agent:","\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsx)(n.li,{children:"Select a foundation model"}),"\n",(0,s.jsx)(n.li,{children:"Define the agent's instructions"}),"\n",(0,s.jsx)(n.li,{children:"Configure knowledge bases (optional)"}),"\n",(0,s.jsx)(n.li,{children:"Set up action groups (if needed)"}),"\n"]}),"\n"]}),"\n",(0,s.jsxs)(n.li,{children:["Once created, ",(0,s.jsx)(n.strong,{children:"create an alias"}),' for your agent by selecting it and clicking "Create alias"']}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Copy the Agent ID and Alias ID"})," from the agent details page - you'll need these for the Agent Mesh configuration"]}),"\n"]}),"\n"]}),"\n",(0,s.jsxs)(n.li,{children:["\n",(0,s.jsx)(n.p,{children:(0,s.jsx)(n.strong,{children:"Create Bedrock Flows"})}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:["Go to the ",(0,s.jsx)(n.strong,{children:"Flows"})," tab in the Bedrock console"]}),"\n",(0,s.jsx)(n.li,{children:'Click "Create flow"'}),"\n",(0,s.jsx)(n.li,{children:"Use the visual editor to design your flow"}),"\n",(0,s.jsx)(n.li,{children:"Connect nodes to create your workflow"}),"\n",(0,s.jsx)(n.li,{children:"Test and publish your flow"}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Create an alias"})," for your flow"]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Copy the Flow ID and Alias ID"})," - you'll need these for the Agent Mesh configuration"]}),"\n"]}),"\n"]}),"\n",(0,s.jsxs)(n.li,{children:["\n",(0,s.jsx)(n.p,{children:(0,s.jsx)(n.strong,{children:"Set up IAM permissions"})}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:["Ensure your IAM user or role has the following permissions:","\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsx)(n.li,{children:(0,s.jsx)(n.code,{children:"bedrock:InvokeAgent"})}),"\n",(0,s.jsx)(n.li,{children:(0,s.jsx)(n.code,{children:"bedrock:InvokeFlow"})}),"\n",(0,s.jsx)(n.li,{children:"Any other permissions required by your specific Bedrock configuration"}),"\n"]}),"\n"]}),"\n"]}),"\n"]}),"\n"]}),"\n",(0,s.jsx)(n.h3,{id:"create-an-agent-mesh-project",children:"Create an Agent Mesh Project"}),"\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 Solace Mesh Agent CLI"}),", and then you'll want to ",(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.h2,{id:"integrating-bedrock-with-agent-mesh",children:"Integrating Bedrock with Agent Mesh"}),"\n",(0,s.jsx)(n.h3,{id:"adding-the-bedrock-agent-plugin",children:"Adding the Bedrock Agent Plugin"}),"\n",(0,s.jsxs)(n.p,{children:["The ",(0,s.jsx)(n.code,{children:"sam-bedrock-agent"})," plugin from the ",(0,s.jsx)(n.a,{href:"https://github.com/SolaceLabs/solace-agent-mesh-core-plugins/tree/main/sam-bedrock-agent",children:"solace-agent-mesh-core-plugins"})," repository creates a bridge between Agent Mesh and Amazon Bedrock services. This plugin allows your Agent Mesh agents to invoke Bedrock Agents and Flows as tools."]}),"\n",(0,s.jsxs)(n.ol,{children:["\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Add the plugin to your Agent Mesh project"}),":"]}),"\n"]}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-sh",children:"sam plugin add aws-agent --plugin sam-bedrock-agent\n"})}),"\n",(0,s.jsxs)(n.p,{children:["Replace ",(0,s.jsx)(n.code,{children:"aws-agent"})," with a descriptive name for your agent, such as ",(0,s.jsx)(n.code,{children:"bedrock-summarizer"})," or ",(0,s.jsx)(n.code,{children:"bedrock-customer-service"}),"."]}),"\n",(0,s.jsx)(n.p,{children:"This command:"}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:["Installs the ",(0,s.jsx)(n.code,{children:"sam-bedrock-agent"})," plugin"]}),"\n",(0,s.jsxs)(n.li,{children:["Creates a new agent configuration file in ",(0,s.jsx)(n.code,{children:"configs/agents/aws-agent.yaml"})]}),"\n"]}),"\n",(0,s.jsxs)(n.ol,{start:"2",children:["\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Locate the configuration file"}),":"]}),"\n"]}),"\n",(0,s.jsxs)(n.p,{children:["The command creates an ",(0,s.jsx)(n.code,{children:"aws-agent.yaml"})," file in the ",(0,s.jsx)(n.code,{children:"configs/agents/"})," directory of your Agent Mesh project."]}),"\n",(0,s.jsx)(n.admonition,{title:"Naming Convention",type:"tip",children:(0,s.jsx)(n.p,{children:"Choose a descriptive name that reflects the purpose of your Bedrock integration. This name is used to reference the agent in your Agent Mesh project."})}),"\n",(0,s.jsx)(n.h2,{id:"configuring-the-bedrock-agent",children:"Configuring the Bedrock Agent"}),"\n",(0,s.jsx)(n.p,{children:"The configuration file you created needs to be edited to connect to your specific Amazon Bedrock resources. This section explains each part of the configuration and how to customize it."}),"\n",(0,s.jsx)(n.h3,{id:"understanding-the-configuration-structure",children:"Understanding the Configuration Structure"}),"\n",(0,s.jsxs)(n.p,{children:["Open the ",(0,s.jsx)(n.code,{children:"aws-agent.yaml"})," file in your editor. The core of the agent's configuration consists of:"]}),"\n",(0,s.jsxs)(n.ol,{children:["\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"amazon_bedrock_runtime_config"}),": AWS connection settings"]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"tools"}),": List of Bedrock agents and flows to expose as tools"]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"agent_card"}),": Agent capabilities and skills definition"]}),"\n"]}),"\n",(0,s.jsx)(n.h3,{id:"example-configuration",children:"Example Configuration"}),"\n",(0,s.jsx)(n.p,{children:"Here's an annotated example based on the actual plugin structure:"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-yaml",children:'log:\n  stdout_log_level: INFO\n  log_file_level: DEBUG\n  log_file: aws-agent.log\n\n!include ../shared_config.yaml\n\napps:\n  - name: aws-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: "AwsAgent" \n      display_name: "AwsAgent Component" \n      model: *general_model \n\n      instruction: |\n        You\'re AwsAgent responsible for handling user queries by \n        interacting with Amazon Bedrock agents or flows.\n\n      # AWS Connection Configuration\n      amazon_bedrock_runtime_config: &amazon_bedrock_runtime_config\n        endpoint_url: # Optional: Custom AWS endpoint URL\n        boto3_config:\n          region_name: "us-east-1" # AWS region where your Bedrock resources are located\n          aws_access_key_id: # Your AWS access key (or use profiles/env vars)\n          aws_secret_access_key: # Your AWS secret key\n\n      tools:\n        # Bedrock Agent Tool\n        - tool_type: python\n          component_module: sam_bedrock_agent.bedrock_agent\n          component_base_path: . \n          function_name: invoke_bedrock_agent\n          tool_name: "text_transformer" # Customizable, Name exposed to the LLM\n          tool_description: "Transforms text using the Text Transformer agent which summarizes the given text and extracts key points." # Customizable, Optional description\n          tool_config:\n            amazon_bedrock_runtime_config: *amazon_bedrock_runtime_config\n            bedrock_agent_id: "XXXXXXXXXX" # Your actual Bedrock agent ID\n            bedrock_agent_alias_id: "XXXXXXXXXX" # Your actual Bedrock agent alias ID\n            allow_files: true # Whether to allow file uploads (5 files, 10MB total max)\n\n        # Bedrock Flow Tool\n        - tool_type: python\n          component_module: sam_bedrock_agent.bedrock_flow\n          component_base_path: .\n          function_name: invoke_bedrock_flow\n          tool_name: "poem_writer" # Name exposed to the LLM\n          tool_config: \n            amazon_bedrock_runtime_config: *amazon_bedrock_runtime_config\n            bedrock_flow_id: "XXXXXXXXXX" # Your actual Bedrock flow ID\n            bedrock_flow_alias_id: "XXXXXXXXXX" # Your actual Bedrock flow alias ID\n\n      # Agent capabilities\n      agent_card:\n        description: "Agent that integrates with Amazon Bedrock agents and flows for various AI tasks."\n        defaultInputModes: ["text"]\n        defaultOutputModes: ["text"]\n        skills: \n          - id: "text_transformer"\n            name: "Text Transformer"\n            description: "Transforms text using the Text Transformer agent."\n          - id: "poem_writer"\n            name: "Poem Writer"\n            description: "Generates poems based on user input."\n\n      # A2A Protocol settings\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.h3,{id:"customizing-your-configuration",children:"Customizing Your Configuration"}),"\n",(0,s.jsx)(n.p,{children:"Follow these steps to customize your configuration:"}),"\n",(0,s.jsxs)(n.ol,{children:["\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Configure AWS Connection"}),":","\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:["Set the ",(0,s.jsx)(n.code,{children:"region_name"})," to the AWS region where your Bedrock resources are located"]}),"\n",(0,s.jsxs)(n.li,{children:["Choose one of these authentication methods:","\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:["Set ",(0,s.jsx)(n.code,{children:"aws_access_key_id"})," and ",(0,s.jsx)(n.code,{children:"aws_secret_access_key"})," directly in the config."]}),"\n",(0,s.jsx)(n.li,{children:"Use AWS profiles by removing these fields and configuring your AWS CLI profile."}),"\n",(0,s.jsx)(n.li,{children:"Use environment variables (see Environment Variables section below)."}),"\n"]}),"\n"]}),"\n"]}),"\n"]}),"\n"]}),"\n",(0,s.jsxs)(n.p,{children:["Check the ",(0,s.jsx)(n.a,{href:"https://boto3.amazonaws.com/v1/documentation/api/latest/reference/core/session.html",children:"boto3 documentation"})," for more details."]}),"\n",(0,s.jsxs)(n.ol,{start:"2",children:["\n",(0,s.jsxs)(n.li,{children:["\n",(0,s.jsxs)(n.p,{children:[(0,s.jsx)(n.strong,{children:"Configure Bedrock Agent Tools"}),":"]}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:["For each Bedrock agent you want to expose, add a tool entry:","\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:["Set a descriptive ",(0,s.jsx)(n.code,{children:"tool_name"})," (for example, ",(0,s.jsx)(n.code,{children:"text_summarizer"}),", ",(0,s.jsx)(n.code,{children:"content_generator"}),")."]}),"\n",(0,s.jsxs)(n.li,{children:["Provide a clear ",(0,s.jsx)(n.code,{children:"tool_description"})," of what the agent does."]}),"\n",(0,s.jsxs)(n.li,{children:["Replace ",(0,s.jsx)(n.code,{children:"bedrock_agent_id"})," with your actual Bedrock agent ID."]}),"\n",(0,s.jsxs)(n.li,{children:["Replace ",(0,s.jsx)(n.code,{children:"bedrock_agent_alias_id"})," with your actual Bedrock agent alias ID."]}),"\n",(0,s.jsxs)(n.li,{children:["Set ",(0,s.jsx)(n.code,{children:"allow_files"})," to ",(0,s.jsx)(n.code,{children:"true"})," if your agent can process file uploads."]}),"\n"]}),"\n"]}),"\n"]}),"\n"]}),"\n",(0,s.jsxs)(n.li,{children:["\n",(0,s.jsxs)(n.p,{children:[(0,s.jsx)(n.strong,{children:"Configure Bedrock Flow Tools"}),":"]}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:["For each Bedrock flow you want to expose, add a tool entry:","\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:["Set a descriptive ",(0,s.jsx)(n.code,{children:"tool_name"})," for the flow."]}),"\n",(0,s.jsxs)(n.li,{children:["Provide a clear ",(0,s.jsx)(n.code,{children:"tool_description"})," of what the flow does (optional)."]}),"\n",(0,s.jsxs)(n.li,{children:["Replace ",(0,s.jsx)(n.code,{children:"bedrock_flow_id"})," with your actual Bedrock flow ID."]}),"\n",(0,s.jsxs)(n.li,{children:["Replace ",(0,s.jsx)(n.code,{children:"bedrock_flow_alias_id"})," with your actual Bedrock flow alias ID."]}),"\n"]}),"\n"]}),"\n"]}),"\n"]}),"\n",(0,s.jsxs)(n.li,{children:["\n",(0,s.jsxs)(n.p,{children:[(0,s.jsx)(n.strong,{children:"Update Agent Card Skills"}),":"]}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:["Update the ",(0,s.jsx)(n.code,{children:"agent_card.description"})," to reflect the purpose of your Bedrock agent (This is what other agents see)."]}),"\n",(0,s.jsxs)(n.li,{children:["For each tool you add, create a corresponding skill entry in the ",(0,s.jsx)(n.code,{children:"agent_card.skills"})," section."]}),"\n",(0,s.jsxs)(n.li,{children:["Use the same ",(0,s.jsx)(n.code,{children:"id"})," as the ",(0,s.jsx)(n.code,{children:"tool_name"}),"."]}),"\n",(0,s.jsxs)(n.li,{children:["Provide a user-friendly ",(0,s.jsx)(n.code,{children:"name"})," and ",(0,s.jsx)(n.code,{children:"description"}),"."]}),"\n"]}),"\n"]}),"\n",(0,s.jsxs)(n.li,{children:["\n",(0,s.jsxs)(n.p,{children:[(0,s.jsx)(n.strong,{children:"Update Agent Instructions"}),":"]}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:["Modify the ",(0,s.jsx)(n.code,{children:"instruction"})," field to provide clear guidance on how the agent should respond to user queries."]}),"\n",(0,s.jsx)(n.li,{children:"This instruction is used by the Agent's LLM to understand its role and capabilities."}),"\n"]}),"\n"]}),"\n"]}),"\n",(0,s.jsx)(n.admonition,{type:"info",children:(0,s.jsx)(n.p,{children:"You must provide at least one Bedrock agent or flow tool. You can mix and match agents and flows in the same configuration."})}),"\n",(0,s.jsx)(n.h3,{id:"environment-variables",children:"Environment Variables"}),"\n",(0,s.jsx)(n.p,{children:"The Bedrock agent integration requires standard Solace connection variables and can use AWS environment variables for authentication."}),"\n",(0,s.jsx)(n.h4,{id:"required-solace-variables",children:"Required Solace Variables:"}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"SOLACE_BROKER_URL"}),": URL of your Solace broker"]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"SOLACE_BROKER_USERNAME"}),": Username for Solace broker authentication"]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"SOLACE_BROKER_PASSWORD"}),": Password for Solace broker authentication"]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"SOLACE_BROKER_VPN"}),": Solace message VPN name"]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"SOLACE_AGENT_MESH_NAMESPACE"}),": Namespace for your Agent Mesh project"]}),"\n"]}),"\n",(0,s.jsx)(n.h4,{id:"optional-aws-variables",children:"Optional AWS Variables:"}),"\n",(0,s.jsx)(n.p,{children:"If you prefer to use environment variables for AWS authentication instead of configuration in the YAML file:"}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"AWS_ACCESS_KEY_ID"}),": Your AWS access key"]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"AWS_SECRET_ACCESS_KEY"}),": Your AWS secret key"]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"AWS_SESSION_TOKEN"}),": If using temporary credentials"]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"AWS_REGION"})," or ",(0,s.jsx)(n.strong,{children:"AWS_DEFAULT_REGION"}),": AWS region for Bedrock services"]}),"\n"]}),"\n",(0,s.jsxs)(n.admonition,{title:"AWS Credentials Precedence",type:"tip",children:[(0,s.jsx)(n.p,{children:"AWS credentials are loaded in this order:"}),(0,s.jsxs)(n.ol,{children:["\n",(0,s.jsx)(n.li,{children:"Explicit credentials in the YAML configuration"}),"\n",(0,s.jsx)(n.li,{children:"Environment variables"}),"\n",(0,s.jsx)(n.li,{children:"AWS configuration files (~/.aws/credentials)"}),"\n",(0,s.jsx)(n.li,{children:"EC2/ECS instance profiles (if running on AWS)"}),"\n"]})]}),"\n",(0,s.jsx)(n.h2,{id:"running-and-testing-your-integration",children:"Running and Testing Your Integration"}),"\n",(0,s.jsx)(n.h3,{id:"starting-your-agent-mesh-project",children:"Starting Your Agent Mesh Project"}),"\n",(0,s.jsx)(n.p,{children:"After configuring your Bedrock agent integration, run your Agent Mesh project:"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-sh",children:"sam run configs/agents/aws-agent.yaml\n"})}),"\n",(0,s.jsx)(n.p,{children:"This command starts the Bedrock agent with your specific configuration."}),"\n",(0,s.jsx)(n.h3,{id:"testing-the-integration",children:"Testing the Integration"}),"\n",(0,s.jsx)(n.p,{children:"You can test your Bedrock agent integration through any gateway in your Agent Mesh project:"}),"\n",(0,s.jsx)(n.h4,{id:"using-the-web-ui-gateway",children:"Using the Web UI Gateway"}),"\n",(0,s.jsxs)(n.ol,{children:["\n",(0,s.jsxs)(n.li,{children:["Ensure you have a Web UI gateway running (typically at ",(0,s.jsx)(n.a,{href:"http://localhost:8000",children:"http://localhost:8000"}),")"]}),"\n",(0,s.jsx)(n.li,{children:"Start a conversation with your agent"}),"\n",(0,s.jsx)(n.li,{children:"Ask a question that would trigger your Bedrock agent or flow"}),"\n"]}),"\n",(0,s.jsxs)(n.p,{children:[(0,s.jsx)(n.strong,{children:"Example"}),": If you configured a Bedrock agent for text transformation:"]}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{children:'Transform this text: "The quick brown fox jumps over the lazy dog. The lazy dog did not chase the fox. The fox was brown and quick, while the dog was lazy and slow. Despite their differences, they both enjoyed the sunny day in the meadow."\n'})}),"\n",(0,s.jsxs)(n.p,{children:[(0,s.jsx)(n.strong,{children:"Example"}),": If you configured a Bedrock flow for poem writing:"]}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{children:"Write a poem about a sunset over the ocean.\n"})}),"\n",(0,s.jsx)(n.h4,{id:"testing-with-file-uploads",children:"Testing with File Uploads"}),"\n",(0,s.jsxs)(n.p,{children:["If you have enabled file uploads for your Bedrock agent (",(0,s.jsx)(n.code,{children:"allow_files: true"}),"), you can test file processing:"]}),"\n",(0,s.jsxs)(n.ol,{children:["\n",(0,s.jsx)(n.li,{children:"In the Web UI, use the file upload button to attach a supported file"}),"\n",(0,s.jsx)(n.li,{children:'Include a prompt that references the file, such as "Analyze this document" or "Summarize the content of this file"'}),"\n",(0,s.jsx)(n.li,{children:"The file is sent to the Bedrock agent along with your prompt"}),"\n"]}),"\n",(0,s.jsxs)(n.p,{children:[(0,s.jsx)(n.strong,{children:"Example with file upload"}),":"]}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{children:"Please analyze the attached document and provide key insights.\n"})}),"\n",(0,s.jsxs)(n.admonition,{title:"Supported File Types",type:"info",children:[(0,s.jsx)(n.p,{children:"Bedrock agents support these file types for uploads:"}),(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsx)(n.li,{children:"PDF documents (.pdf)"}),"\n",(0,s.jsx)(n.li,{children:"Text files (.txt)"}),"\n",(0,s.jsx)(n.li,{children:"Word documents (.doc, .docx)"}),"\n",(0,s.jsx)(n.li,{children:"CSV files (.csv)"}),"\n",(0,s.jsx)(n.li,{children:"Excel spreadsheets (.xls, .xlsx)"}),"\n"]}),(0,s.jsx)(n.p,{children:"There's a limit of 5 files with a total size of 10MB per request."})]}),"\n",(0,s.jsx)(n.h2,{id:"troubleshooting",children:"Troubleshooting"}),"\n",(0,s.jsx)(n.h3,{id:"common-issues-and-solutions",children:"Common Issues and Solutions"}),"\n",(0,s.jsx)(n.h4,{id:"authentication-errors",children:"Authentication Errors"}),"\n",(0,s.jsxs)(n.p,{children:[(0,s.jsx)(n.strong,{children:"Issue"}),': "Unable to locate credentials" or "Access denied" errors\n',(0,s.jsx)(n.strong,{children:"Solution"}),":"]}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsx)(n.li,{children:"Verify your AWS credentials are correctly configured"}),"\n",(0,s.jsx)(n.li,{children:"Check that your IAM user/role has the necessary permissions"}),"\n",(0,s.jsxs)(n.li,{children:["Try using AWS CLI to test your credentials: ",(0,s.jsx)(n.code,{children:"aws bedrock list-foundation-models"})]}),"\n"]}),"\n",(0,s.jsx)(n.h4,{id:"configuration-errors",children:"Configuration Errors"}),"\n",(0,s.jsxs)(n.p,{children:[(0,s.jsx)(n.strong,{children:"Issue"}),': "Invalid agent ID" or "Invalid flow ID" errors\n',(0,s.jsx)(n.strong,{children:"Solution"}),":"]}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsx)(n.li,{children:"Double-check your Bedrock agent and flow IDs in the configuration"}),"\n",(0,s.jsx)(n.li,{children:"Ensure you've created aliases for your agents and flows"}),"\n",(0,s.jsx)(n.li,{children:"Verify the region in your configuration matches where your Bedrock resources are located"}),"\n"]}),"\n",(0,s.jsx)(n.h4,{id:"connection-issues",children:"Connection Issues"}),"\n",(0,s.jsxs)(n.p,{children:[(0,s.jsx)(n.strong,{children:"Issue"}),": Agent Mesh can't connect to Bedrock services\n",(0,s.jsx)(n.strong,{children:"Solution"}),":"]}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsx)(n.li,{children:"Check your network connectivity"}),"\n",(0,s.jsx)(n.li,{children:"Verify that Bedrock services are available in your configured region"}),"\n",(0,s.jsx)(n.li,{children:"Check for any VPC or firewall restrictions"}),"\n"]}),"\n",(0,s.jsx)(n.h4,{id:"file-upload-issues",children:"File Upload Issues"}),"\n",(0,s.jsxs)(n.p,{children:[(0,s.jsx)(n.strong,{children:"Issue"}),": Files aren't being processed by the Bedrock agent\n",(0,s.jsx)(n.strong,{children:"Solution"}),":"]}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:["Verify ",(0,s.jsx)(n.code,{children:"allow_files"})," is set to ",(0,s.jsx)(n.code,{children:"true"})," in your configuration"]}),"\n",(0,s.jsx)(n.li,{children:"Check that your file type is supported"}),"\n",(0,s.jsx)(n.li,{children:"Ensure the file size is under the 10MB limit"}),"\n",(0,s.jsx)(n.li,{children:"Check the model context length"}),"\n"]})]})}function h(e={}){const{wrapper:n}={...(0,t.R)(),...e.components};return n?(0,s.jsx)(n,{...e,children:(0,s.jsx)(d,{...e})}):d(e)}},8453:(e,n,o)=>{o.d(n,{R:()=>r,x:()=>l});var i=o(6540);const s={},t=i.createContext(s);function r(e){const n=i.useContext(t);return i.useMemo((function(){return"function"==typeof e?e(n):{...n,...e}}),[n,e])}function l(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(s):e.components||s:r(e.components),i.createElement(t.Provider,{value:n},e.children)}}}]);

solace_agent_mesh/assets/docs/assets/js/c93cbaa0.0e0d8baf.js

@@ -0,0 +1 @@
+"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[1537],{9377:(e,n,t)=>{t.r(n),t.d(n,{assets:()=>l,contentTitle:()=>s,default:()=>h,frontMatter:()=>o,metadata:()=>i,toc:()=>c});const i=JSON.parse('{"id":"documentation/developing/tutorials/rag-integration","title":"RAG Integration","description":"This tutorial guides you through setting up and configuring Agent Mesh Retrieval Augmented Generation (RAG) plugin. The RAG plugin enables your agents to answer questions by retrieving information from a knowledge base of your documents.","source":"@site/docs/documentation/developing/tutorials/rag-integration.md","sourceDirName":"documentation/developing/tutorials","slug":"/documentation/developing/tutorials/rag-integration","permalink":"/solace-agent-mesh/docs/documentation/developing/tutorials/rag-integration","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/developing/tutorials/rag-integration.md","tags":[],"version":"current","sidebarPosition":70,"frontMatter":{"title":"RAG Integration","sidebar_position":70,"toc_max_heading_level":4},"sidebar":"docSidebar","previous":{"title":"Slack Integration","permalink":"/solace-agent-mesh/docs/documentation/developing/tutorials/slack-integration"},"next":{"title":"Microsoft Teams Integration (Enterprise)","permalink":"/solace-agent-mesh/docs/documentation/developing/tutorials/teams-integration"}}');var r=t(4848),a=t(8453);const o={title:"RAG Integration",sidebar_position:70,toc_max_heading_level:4},s="RAG Integration",l={},c=[{value:"What is Agent Mesh RAG?",id:"what-is-agent-mesh-rag",level:2},{value:"Prerequisites",id:"prerequisites",level:2},{value:"Adding the RAG Plugin",id:"adding-the-rag-plugin",level:2},{value:"Configuring the RAG Agent",id:"configuring-the-rag-agent",level:2},{value:"Shared Configuration",id:"shared-configuration",level:3},{value:"RAG Pipeline Configuration",id:"rag-pipeline-configuration",level:3},{value:"1. Scanner Configuration",id:"1-scanner-configuration",level:4},{value:"2. Preprocessor Configuration",id:"2-preprocessor-configuration",level:4},{value:"3. Splitter Configuration",id:"3-splitter-configuration",level:4},{value:"4. Embedding Configuration",id:"4-embedding-configuration",level:4},{value:"5. Vector Database Configuration",id:"5-vector-database-configuration",level:4},{value:"6. LLM Configuration",id:"6-llm-configuration",level:4},{value:"7. Retrieval Configuration",id:"7-retrieval-configuration",level:4},{value:"Environment Variables",id:"environment-variables",level:3},{value:"Running the RAG Agent",id:"running-the-rag-agent",level:2},{value:"Testing the RAG Agent",id:"testing-the-rag-agent",level:2},{value:"Ingesting Documents",id:"ingesting-documents",level:3},{value:"Option 1: Automatic Scanning (Batch Ingestion)",id:"option-1-automatic-scanning-batch-ingestion",level:4},{value:"Option 2: Manual Upload via Gateway",id:"option-2-manual-upload-via-gateway",level:4},{value:"Querying the Knowledge Base",id:"querying-the-knowledge-base",level:3},{value:"Troubleshooting",id:"troubleshooting",level:2}];function d(e){const n={a:"a",blockquote:"blockquote",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,a.R)(),...e.components};return(0,r.jsxs)(r.Fragment,{children:[(0,r.jsx)(n.header,{children:(0,r.jsx)(n.h1,{id:"rag-integration",children:"RAG Integration"})}),"\n",(0,r.jsx)(n.p,{children:"This tutorial guides you through setting up and configuring Agent Mesh Retrieval Augmented Generation (RAG) plugin. The RAG plugin enables your agents to answer questions by retrieving information from a knowledge base of your documents."}),"\n",(0,r.jsx)(n.h2,{id:"what-is-agent-mesh-rag",children:"What is Agent Mesh RAG?"}),"\n",(0,r.jsx)(n.p,{children:"The Agent Mesh RAG plugin enhances your agents with the ability to perform retrieval-augmented generation. This means the agent can:"}),"\n",(0,r.jsxs)(n.ul,{children:["\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"Scan"})," documents from various sources (local filesystem, Google Drive, etc.)."]}),"\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"Preprocess"})," and ",(0,r.jsx)(n.strong,{children:"split"})," the text into manageable chunks."]}),"\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"Embed"})," these chunks into vectors and store them in a vector database."]}),"\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"Retrieve"})," relevant chunks of text based on a user's query."]}),"\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"Generate"})," an answer using a large language model (LLM) augmented with the retrieved information."]}),"\n"]}),"\n",(0,r.jsx)(n.p,{children:"This allows you to build agents that can answer questions about your own private data."}),"\n",(0,r.jsx)(n.h2,{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.jsxs)(n.li,{children:[(0,r.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/installing-and-configuring/installation",children:"Installed Agent Mesh and the Agent Mesh CLI"}),"."]}),"\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/installing-and-configuring/run-project",children:"Created a new Agent Mesh project"}),"."]}),"\n",(0,r.jsx)(n.li,{children:"Access to a vector database (for example, Qdrant, Chroma, and Pinecone)."}),"\n",(0,r.jsx)(n.li,{children:"Access to an LLM for generation and an embedding model."}),"\n",(0,r.jsx)(n.li,{children:"A directory with some documents for the agent to ingest."}),"\n"]}),"\n",(0,r.jsx)(n.h2,{id:"adding-the-rag-plugin",children:"Adding the RAG Plugin"}),"\n",(0,r.jsx)(n.p,{children:"To add the RAG plugin to your Agent Mesh project, run the following command:"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-sh",children:"sam plugin add my-rag-agent --plugin sam-rag\n"})}),"\n",(0,r.jsxs)(n.p,{children:["Replace ",(0,r.jsx)(n.code,{children:"my-rag-agent"})," with your preferred agent name. This command:"]}),"\n",(0,r.jsxs)(n.ul,{children:["\n",(0,r.jsxs)(n.li,{children:["Installs the ",(0,r.jsx)(n.code,{children:"sam-rag"})," plugin."]}),"\n",(0,r.jsxs)(n.li,{children:["Creates a new agent configuration file at ",(0,r.jsx)(n.code,{children:"configs/agents/my-rag-agent.yaml"}),"."]}),"\n"]}),"\n",(0,r.jsx)(n.h2,{id:"configuring-the-rag-agent",children:"Configuring the RAG Agent"}),"\n",(0,r.jsxs)(n.p,{children:["The RAG agent requires a detailed configuration. Open ",(0,r.jsx)(n.code,{children:"configs/agents/my-rag-agent.yaml"})," to configure the following sections:"]}),"\n",(0,r.jsx)(n.h3,{id:"shared-configuration",children:"Shared Configuration"}),"\n",(0,r.jsxs)(n.p,{children:["Like other agents, the RAG agent needs a connection to the Solace broker and a configured LLM. This is typically done in a ",(0,r.jsx)(n.code,{children:"shared_config.yaml"})," file."]}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-yaml",children:"# configs/shared_config.yaml\nshared_config:\n  - broker_connection: &broker_connection\n      dev_mode: ${SOLACE_DEV_MODE, false}\n      broker_url: ${SOLACE_BROKER_URL, ws://localhost:8008}\n      broker_username: ${SOLACE_BROKER_USERNAME, default}\n      broker_password: ${SOLACE_BROKER_PASSWORD, default}\n      broker_vpn: ${SOLACE_BROKER_VPN, default}\n      temporary_queue: ${USE_TEMPORARY_QUEUES, true}\n\n  - models:\n    general: &general_model\n      model: ${LLM_SERVICE_GENERAL_MODEL_NAME}\n      api_base: ${LLM_SERVICE_ENDPOINT}\n      api_key: ${LLM_SERVICE_API_KEY}\n"})}),"\n",(0,r.jsx)(n.h3,{id:"rag-pipeline-configuration",children:"RAG Pipeline Configuration"}),"\n",(0,r.jsxs)(n.p,{children:["The RAG pipeline has several stages, each with its own configuration block within the ",(0,r.jsx)(n.code,{children:"app_config"})," section of your ",(0,r.jsx)(n.code,{children:"my-rag-agent.yaml"})," file."]}),"\n",(0,r.jsx)(n.h4,{id:"1-scanner-configuration",children:"1. Scanner Configuration"}),"\n",(0,r.jsx)(n.p,{children:"The scanner discovers documents to be ingested. You can configure it to scan a local filesystem or cloud sources."}),"\n",(0,r.jsx)(n.p,{children:(0,r.jsx)(n.strong,{children:"Local Filesystem Example:"})}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-yaml",children:'scanner:\n  batch: true\n  use_memory_storage: true\n  source:\n    type: filesystem\n    directories:\n      - "/path/to/your/documents" # Important: Replace with your actual document directory path\n    filters:\n      file_formats:\n        - ".txt"\n        - ".pdf"\n        - ".md"\n'})}),"\n",(0,r.jsxs)(n.p,{children:[(0,r.jsx)(n.strong,{children:"Multi-Cloud Source Example:"}),"\nYou can also configure multiple sources, including Google Drive, OneDrive, and S3."]}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-yaml",children:'scanner:\n  batch: true\n  use_memory_storage: true\n  sources:\n    - type: filesystem\n      directories: ["${LOCAL_DOCUMENTS_PATH}"]\n    - type: google_drive\n      credentials_path: "${GOOGLE_DRIVE_CREDENTIALS_PATH}"\n      folders:\n        - folder_id: "${GOOGLE_DRIVE_FOLDER_ID_1}"\n          name: "Documents"\n          recursive: true\n'})}),"\n",(0,r.jsx)(n.h4,{id:"2-preprocessor-configuration",children:"2. Preprocessor Configuration"}),"\n",(0,r.jsx)(n.p,{children:"The preprocessor cleans the text extracted from documents."}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-yaml",children:"preprocessor:\n  default_preprocessor:\n    type: enhanced\n    params:\n      lowercase: true\n      normalize_whitespace: true\n      remove_urls: true\n  preprocessors:\n    pdf: \n      type: document\n      params:\n        lowercase: true\n        normalize_whitespace: true\n        remove_non_ascii: true\n        remove_urls: true\n"})}),"\n",(0,r.jsx)(n.h4,{id:"3-splitter-configuration",children:"3. Splitter Configuration"}),"\n",(0,r.jsx)(n.p,{children:"The splitter breaks down large documents into smaller chunks. Different splitters are available for different file types."}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-yaml",children:"splitter:\n  default_splitter:\n    type: recursive_character\n    params:\n      chunk_size: 2048\n      chunk_overlap: 400\n  splitters:\n    markdown:\n      type: markdown\n      params:\n        chunk_size: 2048\n        chunk_overlap: 400\n    pdf:\n      type: token\n      params:\n        chunk_size: 500\n        chunk_overlap: 100\n"})}),"\n",(0,r.jsx)(n.h4,{id:"4-embedding-configuration",children:"4. Embedding Configuration"}),"\n",(0,r.jsx)(n.p,{children:"This section defines the model used to create vector embeddings from the text chunks."}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-yaml",children:'embedding:\n  embedder_type: "openai"\n  embedder_params:\n    model: "${OPENAI_EMBEDDING_MODEL}"\n    api_key: "${OPENAI_API_KEY}"\n    api_base: "${OPENAI_API_ENDPOINT}"\n  normalize_embeddings: true\n'})}),"\n",(0,r.jsx)(n.h4,{id:"5-vector-database-configuration",children:"5. Vector Database Configuration"}),"\n",(0,r.jsx)(n.p,{children:"Configure the connection to your vector database where the embeddings are stored."}),"\n",(0,r.jsx)(n.p,{children:(0,r.jsx)(n.strong,{children:"Qdrant Example:"})}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-yaml",children:'vector_db:\n  db_type: "qdrant"\n  db_params:\n    url: "${QDRANT_URL}"\n    api_key: "${QDRANT_API_KEY}"\n    collection_name: "${QDRANT_COLLECTION}"\n    embedding_dimension: ${QDRANT_EMBEDDING_DIMENSION}\n'})}),"\n",(0,r.jsx)(n.p,{children:(0,r.jsx)(n.strong,{children:"Chroma Example:"})}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-yaml",children:'vector_db:\n  db_type: "chroma"\n  db_params:\n    host: "${CHROMA_HOST}"\n    port: "${CHROMA_PORT}"\n    collection_name: "${CHROMA_COLLECTION}"\n'})}),"\n",(0,r.jsx)(n.h4,{id:"6-llm-configuration",children:"6. LLM Configuration"}),"\n",(0,r.jsx)(n.p,{children:"Configure the LLM that is used to generate answers based on the retrieved context."}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-yaml",children:'llm:\n  load_balancer:\n    - model_name: "gpt-4o"\n      litellm_params:\n        model: "openai/${OPENAI_MODEL_NAME}"\n        api_key: "${OPENAI_API_KEY}"\n        api_base: "${OPENAI_API_ENDPOINT}"\n'})}),"\n",(0,r.jsx)(n.h4,{id:"7-retrieval-configuration",children:"7. Retrieval Configuration"}),"\n",(0,r.jsx)(n.p,{children:"This defines how many document chunks are retrieved to answer a query."}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-yaml",children:"retrieval:\n  top_k: 7\n"})}),"\n",(0,r.jsx)(n.h3,{id:"environment-variables",children:"Environment Variables"}),"\n",(0,r.jsxs)(n.p,{children:["The RAG agent relies heavily on environment variables. Here are some of the most important ones you'll need to set in your ",(0,r.jsx)(n.code,{children:".env"})," file:"]}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-bash",children:'# Solace Connection\nSOLACE_BROKER_URL=ws://localhost:8008\nSOLACE_BROKER_VPN=default\nSOLACE_BROKER_USERNAME=default\nSOLACE_BROKER_PASSWORD=default\nNAMESPACE=my-org/dev\n\n# LLM and Embedding Models\nOPENAI_API_KEY="your-openai-api-key"\nOPENAI_API_ENDPOINT="your-openai-api-endpoint"\nOPENAI_MODEL_NAME="model name. E.g., gpt-4o"\nOPENAI_EMBEDDING_MODEL="embedding model name. E.g., text-embedding-3-small"\n\n# Vector Database (Qdrant example)\nQDRANT_URL="Qdrant url"\nQDRANT_API_KEY="API key"\nQDRANT_COLLECTION="my-rag-collection"\nQDRANT_EMBEDDING_DIMENSION=1536 # Depends on your embedding model\n\n# Scanner\nDOCUMENTS_PATH="./my_documents" # Relative path to your documents folder\n'})}),"\n",(0,r.jsxs)(n.p,{children:["Create a directory named ",(0,r.jsx)(n.code,{children:"my_documents"})," in your project root and place some text or markdown files inside it."]}),"\n",(0,r.jsx)(n.h2,{id:"running-the-rag-agent",children:"Running the RAG Agent"}),"\n",(0,r.jsx)(n.p,{children:"Once you have configured your agent and set the environment variables, you can run it:"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-sh",children:"sam run configs/agents/my-rag-agent.yaml\n"})}),"\n",(0,r.jsx)(n.p,{children:"When the agent starts, it begins scanning the documents in the configured source, processing and ingesting them into your vector database. This process may take some time, depending on the number and size of your documents."}),"\n",(0,r.jsx)(n.h2,{id:"testing-the-rag-agent",children:"Testing the RAG Agent"}),"\n",(0,r.jsx)(n.p,{children:"Once your agent is running, you can test its retrieval capabilities and ingest new documents."}),"\n",(0,r.jsx)(n.h3,{id:"ingesting-documents",children:"Ingesting Documents"}),"\n",(0,r.jsx)(n.p,{children:"There are two primary ways to ingest documents into your RAG agent's knowledge base:"}),"\n",(0,r.jsx)(n.h4,{id:"option-1-automatic-scanning-batch-ingestion",children:"Option 1: Automatic Scanning (Batch Ingestion)"}),"\n",(0,r.jsxs)(n.p,{children:["This method uses the configured ",(0,r.jsx)(n.code,{children:"scanner"})," component. The agent automatically ingests documents from the directories specified in your configuration upon startup."]}),"\n",(0,r.jsx)(n.p,{children:(0,r.jsx)(n.strong,{children:"Step 1: Create a Document"})}),"\n",(0,r.jsxs)(n.p,{children:["First, create a simple text file named ",(0,r.jsx)(n.code,{children:"sam_features.txt"})," and add some content to it. For example:"]}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-text",children:"Agent Mesh is a powerful framework for building AI agents.\nKey features of Agent Mesh include:\n- A flexible plugin architecture.\n- Integration with various LLMs and vector databases.\n- Scalable gateways for different communication protocols.\n- An event-driven design based on Solace event broker.\n"})}),"\n",(0,r.jsx)(n.p,{children:(0,r.jsx)(n.strong,{children:"Step 2: Place the Document in the Scanned Directory"})}),"\n",(0,r.jsxs)(n.p,{children:['In the "Environment Variables" section, we configured ',(0,r.jsx)(n.code,{children:"LOCAL_DOCUMENTS_PATH"})," to point to a directory (e.g., ",(0,r.jsx)(n.code,{children:"./my_documents"}),")."]}),"\n",(0,r.jsxs)(n.p,{children:["Create this directory in your project's root folder if you haven't already, and move your ",(0,r.jsx)(n.code,{children:"sam_features.txt"})," file into it."]}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-sh",children:"mkdir -p my_documents\nmv sam_features.txt my_documents/\n"})}),"\n",(0,r.jsx)(n.p,{children:(0,r.jsx)(n.strong,{children:"Step 3: Run the Agent to Trigger Ingestion"})}),"\n",(0,r.jsx)(n.p,{children:"If your agent is already running, you'll need to restart it to trigger the batch scan. If it's not running, start it now:"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-sh",children:"sam run configs/agents/my-rag-agent.yaml\n"})}),"\n",(0,r.jsx)(n.p,{children:"You will see logs indicating that the file is being processed. Once the agent is running and the initial scan is complete, the document is successfully ingested and ready for retrieval."}),"\n",(0,r.jsx)(n.h4,{id:"option-2-manual-upload-via-gateway",children:"Option 2: Manual Upload via Gateway"}),"\n",(0,r.jsx)(n.p,{children:"You can also ingest documents dynamically by uploading them directly through a gateway, like the Web UI. This is useful for adding single documents without restarting the agent. The RAG agent exposes a tool for this purpose."}),"\n",(0,r.jsx)(n.p,{children:(0,r.jsx)(n.strong,{children:"Step 1: Start the RAG Agent and Web UI"})}),"\n",(0,r.jsx)(n.p,{children:"Ensure both your RAG agent and the Web UI gateway are running."}),"\n",(0,r.jsx)(n.p,{children:(0,r.jsx)(n.strong,{children:"Step 2: Upload a Document in the Web UI"})}),"\n",(0,r.jsxs)(n.ol,{children:["\n",(0,r.jsxs)(n.li,{children:["Open the Web UI (usually at ",(0,r.jsx)(n.a,{href:"http://localhost:8000",children:"http://localhost:8000"}),", or check your gateway configuration for the correct URL) and start a chat with your RAG agent."]}),"\n",(0,r.jsx)(n.li,{children:"Use the file attachment button to select a document from your local machine."}),"\n",(0,r.jsxs)(n.li,{children:["Send a prompt along with the file, instructing the agent to ingest it. For example:","\n",(0,r.jsxs)(n.blockquote,{children:["\n",(0,r.jsx)(n.p,{children:'"Please ingest the attached document into your knowledge base."'}),"\n"]}),"\n"]}),"\n"]}),"\n",(0,r.jsxs)(n.p,{children:["The RAG agent uses its ",(0,r.jsx)(n.code,{children:"built-in"})," ingest_document tool to process the file you uploaded. The file goes through the same preprocessing, splitting, and embedding pipeline as the documents from the automatic scan."]}),"\n",(0,r.jsx)(n.p,{children:(0,r.jsx)(n.strong,{children:"Step 3: Confirm Ingestion"})}),"\n",(0,r.jsx)(n.p,{children:"After the agent confirms that the document has been ingested, you can immediately ask questions about its content."}),"\n",(0,r.jsx)(n.h3,{id:"querying-the-knowledge-base",children:"Querying the Knowledge Base"}),"\n",(0,r.jsx)(n.p,{children:"You can interact with your RAG agent through any gateway, such as the Web UI gateway."}),"\n",(0,r.jsxs)(n.ol,{children:["\n",(0,r.jsx)(n.li,{children:"Make sure you have a Web UI gateway running (or add one to your project)."}),"\n",(0,r.jsxs)(n.li,{children:["Open the Web UI (usually at ",(0,r.jsx)(n.code,{children:"http://localhost:8000"}),")."]}),"\n",(0,r.jsxs)(n.li,{children:["Start a conversation with ",(0,r.jsx)(n.code,{children:"my-rag-agent"}),"."]}),"\n",(0,r.jsx)(n.li,{children:"Ask a question related to the content of the documents you provided during the initial scan."}),"\n"]}),"\n",(0,r.jsx)(n.p,{children:"For example, if you have a document about product features, you could ask:"}),"\n",(0,r.jsxs)(n.blockquote,{children:["\n",(0,r.jsx)(n.p,{children:'"What are the key features of Product X?"'}),"\n"]}),"\n",(0,r.jsx)(n.p,{children:"The agent searches its knowledge base, finds the relevant information, and generates an answer based on the content of your documents."}),"\n",(0,r.jsx)(n.h2,{id:"troubleshooting",children:"Troubleshooting"}),"\n",(0,r.jsxs)(n.ul,{children:["\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"Connection Errors"}),": Double-check all your URLs, API keys, and credentials for your LLM and vector database."]}),"\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"Ingestion Issues"}),": Check the agent logs for errors during the scanning, preprocessing, or embedding stages. Ensure the file formats are supported and the paths are correct."]}),"\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"No Answers"}),": If the agent can't answer, it might be because the information is not in the documents, or the ",(0,r.jsx)(n.code,{children:"top_k"})," retrieval setting is too low."]}),"\n"]})]})}function h(e={}){const{wrapper:n}={...(0,a.R)(),...e.components};return n?(0,r.jsx)(n,{...e,children:(0,r.jsx)(d,{...e})}):d(e)}},8453:(e,n,t)=>{t.d(n,{R:()=>o,x:()=>s});var i=t(6540);const r={},a=i.createContext(r);function o(e){const n=i.useContext(a);return i.useMemo((function(){return"function"==typeof e?e(n):{...n,...e}}),[n,e])}function s(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(r):e.components||r:o(e.components),i.createElement(a.Provider,{value:n},e.children)}}}]);

solace_agent_mesh/assets/docs/assets/js/cab03b5b.6a073091.js

@@ -0,0 +1 @@
+"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[3731],{7376:(e,n,i)=>{i.r(n),i.d(n,{assets:()=>c,contentTitle:()=>o,default:()=>h,frontMatter:()=>l,metadata:()=>s,toc:()=>a});const s=JSON.parse('{"id":"documentation/enterprise/openapi-tools","title":"OpenAPI Tools","description":"This guide walks you through configuring OpenAPI-based tools for Agent Mesh Enterprise. You will learn how to integrate REST APIs into your agents using OpenAPI specifications, enabling them to interact with any OpenAPI-compliant service.","source":"@site/docs/documentation/enterprise/openapi-tools.md","sourceDirName":"documentation/enterprise","slug":"/documentation/enterprise/openapi-tools","permalink":"/solace-agent-mesh/docs/documentation/enterprise/openapi-tools","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/enterprise/openapi-tools.md","tags":[],"version":"current","sidebarPosition":16,"frontMatter":{"title":"OpenAPI Tools","sidebar_position":16},"sidebar":"docSidebar","previous":{"title":"Secure User Delegated Access","permalink":"/solace-agent-mesh/docs/documentation/enterprise/secure-user-delegated-access"}}');var t=i(4848),r=i(8453);const l={title:"OpenAPI Tools",sidebar_position:16},o=void 0,c={},a=[{value:"Table of Contents",id:"table-of-contents",level:2},{value:"Overview",id:"overview",level:2},{value:"Why Use OpenAPI Tools",id:"why-use-openapi-tools",level:3},{value:"Supported Features",id:"supported-features",level:3},{value:"Understanding OpenAPI Tools",id:"understanding-openapi-tools",level:2},{value:"How OpenAPI Tools Work",id:"how-openapi-tools-work",level:3},{value:"Prerequisites",id:"prerequisites",level:2},{value:"OpenAPI Specification",id:"openapi-specification",level:3},{value:"API Access",id:"api-access",level:3},{value:"Target Server URL",id:"target-server-url",level:3},{value:"Configuration Steps",id:"configuration-steps",level:2},{value:"Basic Configuration Structure",id:"basic-configuration-structure",level:3},{value:"Configuration Parameters",id:"configuration-parameters",level:3},{value:"tool_type",id:"tool_type",level:4},{value:"Specification Source (Mutually Exclusive)",id:"specification-source-mutually-exclusive",level:4},{value:"base_url",id:"base_url",level:4},{value:"Complete Example",id:"complete-example",level:3},{value:"Tool Filtering",id:"tool-filtering",level:2},{value:"Why Filter Tools",id:"why-filter-tools",level:3},{value:"Filter Types",id:"filter-types",level:3},{value:"allow_list",id:"allow_list",level:4},{value:"deny_list",id:"deny_list",level:4},{value:"Filter Configuration",id:"filter-configuration",level:3},{value:"Filtering Examples",id:"filtering-examples",level:3},{value:"Authentication",id:"authentication",level:2},{value:"API Key Authentication",id:"api-key-authentication",level:3},{value:"Service Account Authentication",id:"service-account-authentication",level:3},{value:"Best Practices",id:"best-practices",level:2},{value:"Use Environment Variables for Secrets",id:"use-environment-variables-for-secrets",level:3},{value:"Fetch Specs from URLs When Possible",id:"fetch-specs-from-urls-when-possible",level:3},{value:"Use allow_list for Security-Sensitive APIs",id:"use-allow_list-for-security-sensitive-apis",level:3},{value:"Provide Clear Agent Instructions",id:"provide-clear-agent-instructions",level:3},{value:"Test with Local APIs First",id:"test-with-local-apis-first",level:3},{value:"Troubleshooting",id:"troubleshooting",level:2},{value:"Specification Loading Fails",id:"specification-loading-fails",level:3},{value:"Tools Not Available to Agent",id:"tools-not-available-to-agent",level:3},{value:"Authentication Errors",id:"authentication-errors",level:3},{value:"API Calls Fail or Return Errors",id:"api-calls-fail-or-return-errors",level:3},{value:"Conclusion",id:"conclusion",level:2}];function d(e){const n={a:"a",code:"code",h2:"h2",h3:"h3",h4:"h4",li:"li",ol:"ol",p:"p",pre:"pre",strong:"strong",ul:"ul",...(0,r.R)(),...e.components};return(0,t.jsxs)(t.Fragment,{children:[(0,t.jsx)(n.p,{children:"This guide walks you through configuring OpenAPI-based tools for Agent Mesh Enterprise. You will learn how to integrate REST APIs into your agents using OpenAPI specifications, enabling them to interact with any OpenAPI-compliant service."}),"\n",(0,t.jsx)(n.h2,{id:"table-of-contents",children:"Table of Contents"}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsx)(n.li,{children:(0,t.jsx)(n.a,{href:"#overview",children:"Overview"})}),"\n",(0,t.jsx)(n.li,{children:(0,t.jsx)(n.a,{href:"#understanding-openapi-tools",children:"Understanding OpenAPI Tools"})}),"\n",(0,t.jsx)(n.li,{children:(0,t.jsx)(n.a,{href:"#prerequisites",children:"Prerequisites"})}),"\n",(0,t.jsx)(n.li,{children:(0,t.jsx)(n.a,{href:"#configuration-steps",children:"Configuration Steps"})}),"\n",(0,t.jsx)(n.li,{children:(0,t.jsx)(n.a,{href:"#tool-filtering",children:"Tool Filtering"})}),"\n",(0,t.jsx)(n.li,{children:(0,t.jsx)(n.a,{href:"#authentication",children:"Authentication"})}),"\n",(0,t.jsx)(n.li,{children:(0,t.jsx)(n.a,{href:"#best-practices",children:"Best Practices"})}),"\n",(0,t.jsx)(n.li,{children:(0,t.jsx)(n.a,{href:"#troubleshooting",children:"Troubleshooting"})}),"\n"]}),"\n",(0,t.jsx)(n.h2,{id:"overview",children:"Overview"}),"\n",(0,t.jsx)(n.p,{children:"OpenAPI Tools allow agents to interact with REST APIs by automatically generating tool definitions from OpenAPI (Swagger) specifications. This enables agents to call API endpoints as if they were native tools, with proper parameter validation, type checking, and documentation."}),"\n",(0,t.jsx)(n.h3,{id:"why-use-openapi-tools",children:"Why Use OpenAPI Tools"}),"\n",(0,t.jsx)(n.p,{children:"OpenAPI tools provide several important benefits for agent development:"}),"\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Automatic Tool Generation"}),": Define REST API integrations declaratively using existing OpenAPI specifications. No manual tool implementation required."]}),"\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Type Safety"}),": Parameter types, validation, and required fields are automatically enforced based on the OpenAPI schema."]}),"\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Documentation"}),": Tool descriptions and parameter documentation are extracted from the OpenAPI spec, helping the AI model understand how to use each tool effectively."]}),"\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Flexibility"}),": Support for multiple OpenAPI spec sources (files, URLs, inline), server URL overrides, and authentication methods."]}),"\n",(0,t.jsx)(n.h3,{id:"supported-features",children:"Supported Features"}),"\n",(0,t.jsx)(n.p,{children:"Agent Mesh Enterprise's OpenAPI tool integration supports:"}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:"OpenAPI 3.0+ specifications"})," in JSON or YAML format"]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:"Multiple specification sources"}),": local files, remote URLs, or inline specs"]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:"Server URL overrides"}),": Point specs to different environments (development, staging, production)"]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:"Tool filtering"}),": Include or exclude specific API operations using allow/deny lists"]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:"Authentication"}),": API key, and service account authentication"]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:"Automatic name conversion"}),": Handles camelCase operation IDs correctly"]}),"\n"]}),"\n",(0,t.jsx)(n.h2,{id:"understanding-openapi-tools",children:"Understanding OpenAPI Tools"}),"\n",(0,t.jsx)(n.p,{children:"Before you configure OpenAPI tools, you need to understand how they work and how API operations become callable tools."}),"\n",(0,t.jsx)(n.h3,{id:"how-openapi-tools-work",children:"How OpenAPI Tools Work"}),"\n",(0,t.jsx)(n.p,{children:"When you configure an OpenAPI tool, Agent Mesh Enterprise performs the following steps:"}),"\n",(0,t.jsxs)(n.ol,{children:["\n",(0,t.jsxs)(n.li,{children:["\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Specification Loading"}),": The system loads the OpenAPI specification from the configured source (file, URL, or inline)."]}),"\n"]}),"\n",(0,t.jsxs)(n.li,{children:["\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Operation Discovery"}),": Each path and HTTP method combination in the spec becomes a potential tool. The operation's ",(0,t.jsx)(n.code,{children:"operationId"})," becomes the tool name."]}),"\n"]}),"\n",(0,t.jsxs)(n.li,{children:["\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Schema Conversion"}),": OpenAPI parameter schemas are converted to the format expected by the AI model, including type information, validation rules, and descriptions."]}),"\n"]}),"\n",(0,t.jsxs)(n.li,{children:["\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Tool Registration"}),": Each operation is registered as a callable tool with the agent. The AI model can then invoke these tools by name."]}),"\n"]}),"\n",(0,t.jsxs)(n.li,{children:["\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Request Execution"}),": When the agent calls a tool, Agent Mesh Enterprise constructs the appropriate HTTP request based on the OpenAPI spec and executes it against the target API."]}),"\n"]}),"\n",(0,t.jsxs)(n.li,{children:["\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Response Handling"}),": API responses are returned to the agent and can be used in subsequent tool calls or included in the agent's response to the user."]}),"\n"]}),"\n"]}),"\n",(0,t.jsx)(n.h2,{id:"prerequisites",children:"Prerequisites"}),"\n",(0,t.jsx)(n.p,{children:"Before you configure OpenAPI tools, ensure you have the following:"}),"\n",(0,t.jsx)(n.h3,{id:"openapi-specification",children:"OpenAPI Specification"}),"\n",(0,t.jsx)(n.p,{children:"You need access to an OpenAPI specification for the API you want to integrate. This can be:"}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsx)(n.li,{children:"A local OpenAPI spec file (JSON or YAML)"}),"\n",(0,t.jsx)(n.li,{children:"A URL to a remote OpenAPI spec"}),"\n",(0,t.jsx)(n.li,{children:"An inline OpenAPI spec defined in your configuration"}),"\n"]}),"\n",(0,t.jsx)(n.p,{children:"Most modern REST APIs provide OpenAPI specifications. Check the API provider's documentation for:"}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsx)(n.li,{children:"Swagger/OpenAPI spec download links"}),"\n",(0,t.jsx)(n.li,{children:"API documentation pages (often generated from the spec)"}),"\n",(0,t.jsx)(n.li,{children:"Developer portals that provide spec access"}),"\n"]}),"\n",(0,t.jsx)(n.h3,{id:"api-access",children:"API Access"}),"\n",(0,t.jsx)(n.p,{children:"Depending on the API's authentication requirements, you may need:"}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:"API Keys"}),": For APIs using API key authentication"]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:"Service Account"}),": For Google Cloud and similar services"]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:"Network Access"}),": Ensure your Agent Mesh Enterprise deployment can reach the API endpoints"]}),"\n"]}),"\n",(0,t.jsx)(n.h3,{id:"target-server-url",children:"Target Server URL"}),"\n",(0,t.jsx)(n.p,{children:"If the OpenAPI spec's server URLs don't match your target environment, you'll need the correct base URL for the API. For example:"}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsxs)(n.li,{children:["Spec may contain: ",(0,t.jsx)(n.code,{children:"https://api.production.com"})]}),"\n",(0,t.jsxs)(n.li,{children:["You may want to use: ",(0,t.jsx)(n.code,{children:"http://localhost:8080"})," (local development)"]}),"\n"]}),"\n",(0,t.jsx)(n.h2,{id:"configuration-steps",children:"Configuration Steps"}),"\n",(0,t.jsx)(n.p,{children:"Configuring OpenAPI tools involves specifying the spec source, optional server URL override, authentication, and tool filtering."}),"\n",(0,t.jsx)(n.h3,{id:"basic-configuration-structure",children:"Basic Configuration Structure"}),"\n",(0,t.jsx)(n.p,{children:"An OpenAPI tool configuration follows this structure:"}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-yaml",children:'tools:\n  - tool_type: openapi\n    specification_url: "https://petstore3.swagger.io/api/v3/openapi.json"\n    base_url: "http://localhost:8080"\n    auth:\n      type: apikey\n      in: header\n      name: api_key\n      value: ${API_KEY}\n'})}),"\n",(0,t.jsx)(n.h3,{id:"configuration-parameters",children:"Configuration Parameters"}),"\n",(0,t.jsx)(n.h4,{id:"tool_type",children:"tool_type"}),"\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Required"}),": Yes"]}),"\n",(0,t.jsx)(n.p,{children:"Identifies this as an OpenAPI tool configuration."}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-yaml",children:"tool_type: openapi\n"})}),"\n",(0,t.jsx)(n.h4,{id:"specification-source-mutually-exclusive",children:"Specification Source (Mutually Exclusive)"}),"\n",(0,t.jsx)(n.p,{children:"You must provide exactly one of the following specification sources:"}),"\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"specification_file"})," - Path to a local OpenAPI spec file:"]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-yaml",children:'specification_file: "examples/petstore_openapi.json"\n'})}),"\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"specification_url"})," - URL to fetch the OpenAPI spec from:"]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-yaml",children:'specification_url: "https://petstore3.swagger.io/api/v3/openapi.json"\n'})}),"\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"specification"})," - Inline OpenAPI spec as a string:"]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-yaml",children:'specification: |\n  {\n    "openapi": "3.0.0",\n    "info": {\n      "title": "My API",\n      "version": "1.0.0"\n    },\n    "paths": {}\n  }\nspecification_format: "json" # Optional: "json" or "yaml"\n'})}),"\n",(0,t.jsxs)(n.p,{children:["When using inline ",(0,t.jsx)(n.code,{children:"specification"}),", you can optionally provide ",(0,t.jsx)(n.code,{children:"specification_format"})," to hint at the format. The system auto-detects the format if not specified. Provide this only if auto-detection fails."]}),"\n",(0,t.jsx)(n.h4,{id:"base_url",children:"base_url"}),"\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Required"}),": No"]}),"\n",(0,t.jsx)(n.p,{children:"Override the server URLs in the OpenAPI specification. This is useful when:"}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsxs)(n.li,{children:["The spec contains only a path (e.g., ",(0,t.jsx)(n.code,{children:"/api/v3"}),") without a base URL"]}),"\n",(0,t.jsx)(n.li,{children:"You want to point to a different environment (development, staging, production)"}),"\n",(0,t.jsx)(n.li,{children:"You're using a spec from one source but targeting a different server"}),"\n"]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-yaml",children:'base_url: "http://localhost:8080"\n'})}),"\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"How it works"}),":"]}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsxs)(n.li,{children:["If the original spec URL is ",(0,t.jsx)(n.code,{children:"/api/v3"})," and ",(0,t.jsx)(n.code,{children:"base_url"})," is ",(0,t.jsx)(n.code,{children:"http://localhost:8080"}),", the result is ",(0,t.jsx)(n.code,{children:"http://localhost:8080/api/v3"})]}),"\n",(0,t.jsxs)(n.li,{children:["If the original spec URL is ",(0,t.jsx)(n.code,{children:"https://petstore.swagger.io/api/v3"})," and ",(0,t.jsx)(n.code,{children:"base_url"})," is ",(0,t.jsx)(n.code,{children:"http://localhost:8080"}),", the result is ",(0,t.jsx)(n.code,{children:"http://localhost:8080/api/v3"})," (path is preserved, base is replaced)"]}),"\n",(0,t.jsx)(n.li,{children:"Duplicate slashes are automatically handled"}),"\n"]}),"\n",(0,t.jsx)(n.h3,{id:"complete-example",children:"Complete Example"}),"\n",(0,t.jsx)(n.p,{children:"Here's a complete agent configuration using an OpenAPI tool:"}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-yaml",children:'apps:\n  - name: pet_store_agent\n    app_config:\n      agent_name: "PetStoreAgent"\n      display_name: "Pet Store API Agent"\n\n      model: gemini-2.5-pro\n\n      instruction: |\n        You are a Pet Store API agent that can manage pets, orders, and users.\n        Always provide the required fields when creating or updating resources.\n\n      tools:\n        - tool_type: openapi\n          specification_url: "https://petstore3.swagger.io/api/v3/openapi.json"\n          base_url: "http://localhost:8080"\n          auth:\n            type: apikey\n            in: header\n            name: api_key\n            value: ${PET_STORE_API_KEY}\n\n      session_service:\n        type: "sql"\n        database_url: "${DATABASE_URL}"\n        default_behavior: "PERSISTENT"\n'})}),"\n",(0,t.jsx)(n.h2,{id:"tool-filtering",children:"Tool Filtering"}),"\n",(0,t.jsx)(n.p,{children:"OpenAPI specifications often include many operations, but you may only want to expose a subset to your agent. Tool filtering allows you to control which operations are available."}),"\n",(0,t.jsx)(n.h3,{id:"why-filter-tools",children:"Why Filter Tools"}),"\n",(0,t.jsx)(n.p,{children:"Filtering tools provides several benefits:"}),"\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Security"}),": Exclude dangerous or administrative operations from agent access."]}),"\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Focused Agents"}),": Create specialized agents that only access relevant operations."]}),"\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Performance"}),": Reduce the number of tools the AI model must consider, improving response time and accuracy."]}),"\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Cost Control"}),": Fewer tools mean less token usage when the AI model selects tools."]}),"\n",(0,t.jsx)(n.h3,{id:"filter-types",children:"Filter Types"}),"\n",(0,t.jsx)(n.p,{children:"You can use two mutually exclusive filter types:"}),"\n",(0,t.jsx)(n.h4,{id:"allow_list",children:"allow_list"}),"\n",(0,t.jsx)(n.p,{children:"Include only specific operations. All other operations are excluded."}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-yaml",children:'tools:\n  - tool_type: openapi\n    specification_url: "https://petstore3.swagger.io/api/v3/openapi.json"\n    allow_list:\n      - "getPetById"\n      - "findPetsByStatus"\n      - "updatePet"\n'})}),"\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Use when"}),": You want explicit control over allowed operations, typically for security-sensitive APIs."]}),"\n",(0,t.jsx)(n.h4,{id:"deny_list",children:"deny_list"}),"\n",(0,t.jsx)(n.p,{children:"Exclude specific operations. All other operations are included."}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-yaml",children:'tools:\n  - tool_type: openapi\n    specification_url: "https://petstore3.swagger.io/api/v3/openapi.json"\n    deny_list:\n      - "deletePet"\n      - "deleteOrder"\n      - "deleteUser"\n'})}),"\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Use when"}),": You want most operations available but need to exclude a few dangerous or unnecessary ones."]}),"\n",(0,t.jsx)(n.h3,{id:"filter-configuration",children:"Filter Configuration"}),"\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Specifying Operation IDs"}),": Use the ",(0,t.jsx)(n.code,{children:"operationId"})," as they appear in the OpenAPI spec."]}),"\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Finding Operation IDs"}),": Look in the OpenAPI spec under ",(0,t.jsx)(n.code,{children:"paths[path][method].operationId"}),":"]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-json",children:'{\n  "paths": {\n    "/pet/{petId}": {\n      "get": {\n        "operationId": "getPetById",\n        "summary": "Find pet by ID"\n      }\n    }\n  }\n}\n'})}),"\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Mutual Exclusivity"}),": You cannot specify both ",(0,t.jsx)(n.code,{children:"allow_list"})," and ",(0,t.jsx)(n.code,{children:"deny_list"}),". The system will reject the configuration with a validation error."]}),"\n",(0,t.jsx)(n.h3,{id:"filtering-examples",children:"Filtering Examples"}),"\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Read-Only Agent"}),":"]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-yaml",children:'tools:\n  - tool_type: openapi\n    specification_url: "https://petstore3.swagger.io/api/v3/openapi.json"\n    allow_list:\n      - "getPetById"\n      - "findPetsByStatus"\n      - "findPetsByTags"\n      - "getInventory"\n      - "getOrderById"\n      - "getUserByName"\n'})}),"\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Full Access Except Deletes"}),":"]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-yaml",children:'tools:\n  - tool_type: openapi\n    specification_url: "https://petstore3.swagger.io/api/v3/openapi.json"\n    deny_list:\n      - "deletePet"\n      - "deleteOrder"\n      - "deleteUser"\n'})}),"\n",(0,t.jsx)(n.h2,{id:"authentication",children:"Authentication"}),"\n",(0,t.jsx)(n.p,{children:"OpenAPI tools support two authentication methods: API key, and service account authentication."}),"\n",(0,t.jsx)(n.h3,{id:"api-key-authentication",children:"API Key Authentication"}),"\n",(0,t.jsx)(n.p,{children:"API key authentication sends a key in either the request header or query parameter."}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-yaml",children:'auth:\n  type: apikey\n  in: header # or "query"\n  name: api_key\n  value: ${API_KEY}\n'})}),"\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Parameters"}),":"]}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.code,{children:"type"}),": Must be ",(0,t.jsx)(n.code,{children:'"apikey"'})]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.code,{children:"in"}),": Where to send the key - ",(0,t.jsx)(n.code,{children:'"header"'})," or ",(0,t.jsx)(n.code,{children:'"query"'})]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.code,{children:"name"}),": The name of the header or query parameter"]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.code,{children:"value"}),": The API key value (use environment variables for security)"]}),"\n"]}),"\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Example"})," (header-based):"]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-yaml",children:"auth:\n  type: apikey\n  in: header\n  name: X-API-Key\n  value: ${MY_API_KEY}\n"})}),"\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Example"})," (query-based):"]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-yaml",children:"auth:\n  type: apikey\n  in: query\n  name: apikey\n  value: ${MY_API_KEY}\n"})}),"\n",(0,t.jsx)(n.h3,{id:"service-account-authentication",children:"Service Account Authentication"}),"\n",(0,t.jsx)(n.p,{children:"Service account authentication uses Google Cloud service account credentials."}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-yaml",children:'auth:\n  type: serviceaccount\n  service_account_json: ${SERVICE_ACCOUNT_JSON}\n  scopes:\n    - "https://www.googleapis.com/auth/cloud-platform"\n'})}),"\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Parameters"}),":"]}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.code,{children:"type"}),": Must be ",(0,t.jsx)(n.code,{children:'"serviceaccount"'})]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.code,{children:"service_account_json"}),": JSON string containing the service account credentials"]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.code,{children:"scopes"}),": List of API scopes to request"]}),"\n"]}),"\n",(0,t.jsx)(n.h2,{id:"best-practices",children:"Best Practices"}),"\n",(0,t.jsx)(n.p,{children:"Following these best practices helps you deploy OpenAPI tools effectively."}),"\n",(0,t.jsx)(n.h3,{id:"use-environment-variables-for-secrets",children:"Use Environment Variables for Secrets"}),"\n",(0,t.jsx)(n.p,{children:"Never hardcode API keys or other credentials in configuration files:"}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-yaml",children:'# Good - use environment variables\nauth:\n  type: apikey\n  in: header\n  name: api_key\n  value: ${API_KEY}\n\n# Bad - hardcoded credentials\nauth:\n  type: apikey\n  in: header\n  name: api_key\n  value: "sk-1234567890abcdef"  # Don\'t do this!\n'})}),"\n",(0,t.jsx)(n.h3,{id:"fetch-specs-from-urls-when-possible",children:"Fetch Specs from URLs When Possible"}),"\n",(0,t.jsx)(n.p,{children:"Fetching specs from URLs ensures you always use the latest version:"}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-yaml",children:'# Good - fetches latest spec\nspecification_url: "https://api.example.com/openapi.json"\n\n# Less ideal - may become outdated\nspecification_file: "examples/api_spec.json"\n'})}),"\n",(0,t.jsx)(n.p,{children:"Use local files only when:"}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsx)(n.li,{children:"The API doesn't provide a public spec URL"}),"\n",(0,t.jsx)(n.li,{children:"You need to use a modified or customized spec"}),"\n",(0,t.jsx)(n.li,{children:"You want to lock to a specific API version"}),"\n"]}),"\n",(0,t.jsx)(n.h3,{id:"use-allow_list-for-security-sensitive-apis",children:"Use allow_list for Security-Sensitive APIs"}),"\n",(0,t.jsxs)(n.p,{children:["For APIs with dangerous operations (delete, administrative functions), use ",(0,t.jsx)(n.code,{children:"allow_list"})," to explicitly control access:"]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-yaml",children:'allow_list:\n  - "getResource"\n  - "listResources"\n  - "updateResource"\n# Deliberately exclude "deleteResource"\n'})}),"\n",(0,t.jsxs)(n.p,{children:["Use ",(0,t.jsx)(n.code,{children:"deny_list"})," only when you're confident about the safety of unlisted operations."]}),"\n",(0,t.jsx)(n.h3,{id:"provide-clear-agent-instructions",children:"Provide Clear Agent Instructions"}),"\n",(0,t.jsx)(n.p,{children:"Include guidance in your agent's instructions about the API and required parameters:"}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-yaml",children:'instruction: |\n  You are a Pet Store API agent.\n\n  When creating pets:\n  - name (required): The pet\'s name\n  - photoUrls (required): Array of photo URLs\n  - id (required): Unique integer ID\n  - category: Optional object with id and name\n  - status: "available", "pending", or "sold"\n\n  Always validate required fields before making requests.\n'})}),"\n",(0,t.jsx)(n.h3,{id:"test-with-local-apis-first",children:"Test with Local APIs First"}),"\n",(0,t.jsx)(n.p,{children:"Test your configuration against local or development API instances before connecting to production:"}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-yaml",children:'# Development\nbase_url: "http://localhost:8080"\n\n# Production (after testing)\nbase_url: "https://api.production.com"\n'})}),"\n",(0,t.jsx)(n.h2,{id:"troubleshooting",children:"Troubleshooting"}),"\n",(0,t.jsx)(n.p,{children:"This section addresses common issues when configuring OpenAPI tools."}),"\n",(0,t.jsx)(n.h3,{id:"specification-loading-fails",children:"Specification Loading Fails"}),"\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Symptoms"}),": Agent fails to start with errors about loading or parsing the OpenAPI specification."]}),"\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Possible Causes and Solutions"}),":"]}),"\n",(0,t.jsxs)(n.ol,{children:["\n",(0,t.jsxs)(n.li,{children:["\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Invalid Specification Format"}),":"]}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsx)(n.li,{children:"Verify the spec is valid JSON or YAML"}),"\n",(0,t.jsx)(n.li,{children:"Validate using online tools (Swagger Editor, OpenAPI Validator)"}),"\n",(0,t.jsx)(n.li,{children:"Check for syntax errors (missing commas, quotes, etc.)"}),"\n"]}),"\n"]}),"\n",(0,t.jsxs)(n.li,{children:["\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"URL Not Accessible"}),":"]}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsxs)(n.li,{children:["Verify the ",(0,t.jsx)(n.code,{children:"specification_url"})," is accessible from your deployment"]}),"\n",(0,t.jsx)(n.li,{children:"Check network connectivity and firewall rules"}),"\n",(0,t.jsx)(n.li,{children:"Ensure HTTPS certificates are valid"}),"\n"]}),"\n"]}),"\n",(0,t.jsxs)(n.li,{children:["\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"File Not Found"}),":"]}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsxs)(n.li,{children:["Verify the ",(0,t.jsx)(n.code,{children:"specification_file"})," path is correct relative to the working directory"]}),"\n",(0,t.jsx)(n.li,{children:"Check file permissions"}),"\n",(0,t.jsx)(n.li,{children:"Use absolute paths if relative paths fail"}),"\n"]}),"\n"]}),"\n"]}),"\n",(0,t.jsx)(n.h3,{id:"tools-not-available-to-agent",children:"Tools Not Available to Agent"}),"\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Symptoms"}),": The AI model reports that tools are not available or cannot be found."]}),"\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Possible Causes and Solutions"}),":"]}),"\n",(0,t.jsxs)(n.ol,{children:["\n",(0,t.jsxs)(n.li,{children:["\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Filtering Excluded All Tools"}),":"]}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsxs)(n.li,{children:["Review your ",(0,t.jsx)(n.code,{children:"allow_list"})," or ",(0,t.jsx)(n.code,{children:"deny_list"})," configuration"]}),"\n",(0,t.jsx)(n.li,{children:"Verify operation IDs match those in the spec (case-sensitive)"}),"\n",(0,t.jsx)(n.li,{children:"Check agent logs for tool loading messages"}),"\n"]}),"\n"]}),"\n",(0,t.jsxs)(n.li,{children:["\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Empty Specification"}),":"]}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsxs)(n.li,{children:["Verify the OpenAPI spec contains ",(0,t.jsx)(n.code,{children:"paths"})," with operations"]}),"\n",(0,t.jsxs)(n.li,{children:["Check that operations have ",(0,t.jsx)(n.code,{children:"operationId"})," fields"]}),"\n"]}),"\n"]}),"\n"]}),"\n",(0,t.jsx)(n.h3,{id:"authentication-errors",children:"Authentication Errors"}),"\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Symptoms"}),": API calls fail with 401 or 403 errors."]}),"\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Possible Causes and Solutions"}),":"]}),"\n",(0,t.jsxs)(n.ol,{children:["\n",(0,t.jsxs)(n.li,{children:["\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Invalid or Missing Credentials"}),":"]}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsx)(n.li,{children:"Verify environment variables are set correctly"}),"\n",(0,t.jsx)(n.li,{children:"Check that credentials haven't expired"}),"\n",(0,t.jsx)(n.li,{children:"Test credentials directly with the API using curl or Postman"}),"\n"]}),"\n"]}),"\n",(0,t.jsxs)(n.li,{children:["\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Wrong Authentication Location"}),":"]}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsxs)(n.li,{children:["Verify ",(0,t.jsx)(n.code,{children:"in: header"})," vs ",(0,t.jsx)(n.code,{children:"in: query"})," matches API requirements"]}),"\n",(0,t.jsxs)(n.li,{children:["Check the ",(0,t.jsx)(n.code,{children:"name"})," parameter matches what the API expects"]}),"\n",(0,t.jsx)(n.li,{children:"Review API documentation for exact auth requirements"}),"\n"]}),"\n"]}),"\n"]}),"\n",(0,t.jsx)(n.h3,{id:"api-calls-fail-or-return-errors",children:"API Calls Fail or Return Errors"}),"\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Symptoms"}),": Tools execute but API returns errors or unexpected responses."]}),"\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Possible Causes and Solutions"}),":"]}),"\n",(0,t.jsxs)(n.ol,{children:["\n",(0,t.jsxs)(n.li,{children:["\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Wrong Server URL"}),":"]}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsxs)(n.li,{children:["Verify ",(0,t.jsx)(n.code,{children:"base_url"})," points to the correct environment"]}),"\n",(0,t.jsx)(n.li,{children:"Check that paths are correctly combined with base URL"}),"\n",(0,t.jsx)(n.li,{children:"Review server URL in agent logs"}),"\n"]}),"\n"]}),"\n",(0,t.jsxs)(n.li,{children:["\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Missing Required Parameters"}),":"]}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsx)(n.li,{children:"Review API error messages for missing parameters"}),"\n",(0,t.jsx)(n.li,{children:"Update agent instructions to include required parameter guidance"}),"\n",(0,t.jsx)(n.li,{children:"Check OpenAPI spec for parameter requirements"}),"\n"]}),"\n"]}),"\n",(0,t.jsxs)(n.li,{children:["\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Type Mismatches"}),":"]}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsx)(n.li,{children:"Verify parameter types match spec (string vs integer, etc.)"}),"\n",(0,t.jsx)(n.li,{children:"Check that enum values are valid"}),"\n",(0,t.jsx)(n.li,{children:"Review validation errors in API responses"}),"\n"]}),"\n"]}),"\n"]}),"\n",(0,t.jsx)(n.h2,{id:"conclusion",children:"Conclusion"}),"\n",(0,t.jsx)(n.p,{children:"OpenAPI tools provide a powerful way to integrate REST APIs into your agents without manual tool implementation. By following the configuration steps, authentication methods, and best practices in this guide, you can quickly enable agents to interact with any OpenAPI-compliant service."}),"\n",(0,t.jsx)(n.p,{children:"Key takeaways:"}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsxs)(n.li,{children:["Use ",(0,t.jsx)(n.code,{children:"specification_url"})," to fetch specs from URLs when possible"]}),"\n",(0,t.jsxs)(n.li,{children:["Override server URLs with ",(0,t.jsx)(n.code,{children:"base_url"})," for environment-specific deployments"]}),"\n",(0,t.jsxs)(n.li,{children:["Filter tools using ",(0,t.jsx)(n.code,{children:"allow_list"})," (security-sensitive) or ",(0,t.jsx)(n.code,{children:"deny_list"})," (convenience)"]}),"\n",(0,t.jsx)(n.li,{children:"Always use environment variables for credentials"}),"\n",(0,t.jsx)(n.li,{children:"Use camelCase operation IDs in filter configurations"}),"\n",(0,t.jsx)(n.li,{children:"Test with local/development APIs before production deployment"}),"\n",(0,t.jsx)(n.li,{children:"Monitor tool usage and API errors through logging"}),"\n"]})]})}function h(e={}){const{wrapper:n}={...(0,r.R)(),...e.components};return n?(0,t.jsx)(n,{...e,children:(0,t.jsx)(d,{...e})}):d(e)}},8453:(e,n,i)=>{i.d(n,{R:()=>l,x:()=>o});var s=i(6540);const t={},r=s.createContext(t);function l(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(t):e.components||t:l(e.components),s.createElement(r.Provider,{value:n},e.children)}}}]);

solace_agent_mesh/assets/docs/assets/js/cbe2e9ea.07e170dd.js

@@ -0,0 +1 @@
+"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[9489],{8730:(e,n,t)=>{t.r(n),t.d(n,{assets:()=>c,contentTitle:()=>r,default:()=>u,frontMatter:()=>i,metadata:()=>s,toc:()=>d});const s=JSON.parse('{"id":"documentation/enterprise/connectors/connectors","title":"Connectors","description":"Connectors link agents to external data sources and services. Each connector type provides access to different systems using configured credentials and connection details. Agents use connectors to retrieve information, execute queries, and interact with external platforms through natural language conversations.","source":"@site/docs/documentation/enterprise/connectors/connectors.md","sourceDirName":"documentation/enterprise/connectors","slug":"/documentation/enterprise/connectors/","permalink":"/solace-agent-mesh/docs/documentation/enterprise/connectors/","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/enterprise/connectors/connectors.md","tags":[],"version":"current","sidebarPosition":10,"frontMatter":{"title":"Connectors","sidebar_position":10},"sidebar":"docSidebar","previous":{"title":"Agent Builder","permalink":"/solace-agent-mesh/docs/documentation/enterprise/agent-builder"},"next":{"title":"Setting Up RBAC","permalink":"/solace-agent-mesh/docs/documentation/enterprise/rbac-setup-guide"}}');var a=t(4848),o=t(8453);const i={title:"Connectors",sidebar_position:10},r="Connectors",c={},d=[{value:"SQL Connectors",id:"sql-connectors",level:2},{value:"Supported Databases",id:"supported-databases",level:3},{value:"Creating SQL Connectors",id:"creating-sql-connectors",level:3},{value:"Security Considerations",id:"security-considerations",level:3},{value:"Shared Credential Architecture",id:"shared-credential-architecture",level:4},{value:"Implementing Database-Level Security",id:"implementing-database-level-security",level:4},{value:"Natural Language Query Risks",id:"natural-language-query-risks",level:4},{value:"Best Practices",id:"best-practices",level:4},{value:"Assigning Connectors to Agents",id:"assigning-connectors-to-agents",level:3},{value:"Managing Connectors",id:"managing-connectors",level:3},{value:"Editing Connectors",id:"editing-connectors",level:4},{value:"Testing Connections",id:"testing-connections",level:4},{value:"Deleting Connectors",id:"deleting-connectors",level:4},{value:"Troubleshooting",id:"troubleshooting",level:3},{value:"Access Control",id:"access-control",level:2}];function l(e){const n={a:"a",code:"code",h1:"h1",h2:"h2",h3:"h3",h4:"h4",header:"header",li:"li",p:"p",table:"table",tbody:"tbody",td:"td",th:"th",thead:"thead",tr:"tr",ul:"ul",...(0,o.R)(),...e.components};return(0,a.jsxs)(a.Fragment,{children:[(0,a.jsx)(n.header,{children:(0,a.jsx)(n.h1,{id:"connectors",children:"Connectors"})}),"\n",(0,a.jsx)(n.p,{children:"Connectors link agents to external data sources and services. Each connector type provides access to different systems using configured credentials and connection details. Agents use connectors to retrieve information, execute queries, and interact with external platforms through natural language conversations."}),"\n",(0,a.jsx)(n.h2,{id:"sql-connectors",children:"SQL Connectors"}),"\n",(0,a.jsx)(n.p,{children:"SQL connectors enable agents to query and analyze database information using natural language. These connectors convert user questions into SQL queries, execute them against configured databases, and return results in a conversational format. This capability makes database information accessible through agent interactions without requiring users to write SQL code."}),"\n",(0,a.jsx)(n.h3,{id:"supported-databases",children:"Supported Databases"}),"\n",(0,a.jsx)(n.p,{children:"SQL connectors support three database types:"}),"\n",(0,a.jsxs)(n.ul,{children:["\n",(0,a.jsx)(n.li,{children:"MySQL"}),"\n",(0,a.jsx)(n.li,{children:"PostgreSQL"}),"\n",(0,a.jsx)(n.li,{children:"MariaDB"}),"\n"]}),"\n",(0,a.jsx)(n.p,{children:"Each database type follows the same configuration process but may have specific connection string requirements or authentication methods."}),"\n",(0,a.jsx)(n.h3,{id:"creating-sql-connectors",children:"Creating SQL Connectors"}),"\n",(0,a.jsx)(n.p,{children:"You create SQL connectors in the Connectors section of the Enterprise web interface. This process must be completed before you can assign connectors to agents."}),"\n",(0,a.jsx)(n.p,{children:"Each SQL connector configuration includes the database type selection, connection details (host address, port number, and database name), and authentication credentials (username and password). The connection configuration establishes a persistent connection pool that agents use to execute queries. You should verify that the database server allows connections from the Agent Mesh deployment and that any required firewall rules permit access."}),"\n",(0,a.jsx)(n.p,{children:"Once you create a connector, it becomes available for assignment to any agent in your deployment. This reusability means you can connect multiple agents to the same database without duplicating connection configuration. All agents assigned to a connector share the same database connection pool and credentials."}),"\n",(0,a.jsx)(n.h3,{id:"security-considerations",children:"Security Considerations"}),"\n",(0,a.jsx)(n.p,{children:"The framework implements a shared credential model that has significant implications for access control when planning your deployment architecture."}),"\n",(0,a.jsx)(n.h4,{id:"shared-credential-architecture",children:"Shared Credential Architecture"}),"\n",(0,a.jsx)(n.p,{children:"The framework does not sandbox database access at the agent level. All agents assigned to a connector share the same database credentials and permissions. This design means that any agent with the connector can access all data the connector's credentials permit. Security boundaries exist at the database level, not between agents."}),"\n",(0,a.jsx)(n.h4,{id:"implementing-database-level-security",children:"Implementing Database-Level Security"}),"\n",(0,a.jsx)(n.p,{children:"Database-level access control is your primary security mechanism. You should create database users with minimal necessary privileges, use database views or restricted schemas to limit what agents can access, and audit database queries to monitor what agents are accessing."}),"\n",(0,a.jsx)(n.p,{children:"For example, if you have agents that should only read customer data and other agents that need full database access, you must create separate connectors with different database users. Each database user has appropriate permissions configured at the database level. You cannot restrict access by assigning the same connector to different agents because all agents sharing a connector have identical database permissions."}),"\n",(0,a.jsx)(n.h4,{id:"natural-language-query-risks",children:"Natural Language Query Risks"}),"\n",(0,a.jsx)(n.p,{children:"The natural language to SQL conversion capability makes databases accessible through conversation, but this also means users can potentially request any data the connector can access. You should plan your database permissions accordingly and consider what information should be available through agent interactions."}),"\n",(0,a.jsx)(n.p,{children:"Users might phrase questions in ways that expose data you intended to restrict, or they might discover table and column names through exploratory questions. Database views that present only approved data columns, user accounts with read-only permissions on specific tables, and query result size limits all help mitigate these risks."}),"\n",(0,a.jsx)(n.h4,{id:"best-practices",children:"Best Practices"}),"\n",(0,a.jsx)(n.p,{children:"Create separate connectors for different security boundaries. If agents require different levels of database access, configure multiple connectors with appropriately scoped database users rather than sharing a single connector across all agents."}),"\n",(0,a.jsx)(n.p,{children:"Use read-only database accounts whenever possible. Many agent use cases only require reading data, and read-only permissions prevent accidental or malicious data modification."}),"\n",(0,a.jsx)(n.p,{children:"Implement database views to present filtered data. Views can hide sensitive columns, join tables to present aggregated information, or implement row-level security logic at the database level."}),"\n",(0,a.jsx)(n.p,{children:"Enable query logging and monitoring to track what agents access. Database audit logs help you detect suspicious query patterns or unauthorized data access attempts."}),"\n",(0,a.jsx)(n.h3,{id:"assigning-connectors-to-agents",children:"Assigning Connectors to Agents"}),"\n",(0,a.jsx)(n.p,{children:"You assign connectors to agents through Agent Builder. When creating or editing an agent, you select connectors from a list during agent configuration. You can assign connectors before or after deployment, and changes to connector assignments take effect when you deploy or update the agent."}),"\n",(0,a.jsx)(n.h3,{id:"managing-connectors",children:"Managing Connectors"}),"\n",(0,a.jsx)(n.p,{children:"Connector management operations require specific RBAC capabilities and follow particular patterns to prevent service disruptions."}),"\n",(0,a.jsx)(n.h4,{id:"editing-connectors",children:"Editing Connectors"}),"\n",(0,a.jsx)(n.p,{children:"You can modify connector configurations at any time. Changes to connection details or credentials take effect immediately for new database connections. Existing connections in the pool may continue using previous credentials until they expire and reconnect."}),"\n",(0,a.jsx)(n.p,{children:"If agents are actively using a connector when you modify it, query failures may occur during the transition period. You should plan connector updates during maintenance windows or coordinate with agent users to minimize disruptions."}),"\n",(0,a.jsx)(n.h4,{id:"testing-connections",children:"Testing Connections"}),"\n",(0,a.jsx)(n.p,{children:"The Connectors interface provides connection testing functionality that validates credentials and connectivity before you save the connector configuration. This testing helps identify configuration errors before agents attempt to use the connector."}),"\n",(0,a.jsx)(n.h4,{id:"deleting-connectors",children:"Deleting Connectors"}),"\n",(0,a.jsx)(n.p,{children:"You can delete connectors, but the system enforces restrictions to prevent breaking deployed agents. If any agents are assigned to a connector, you must first remove the connector from those agents or undeploy them before deletion succeeds."}),"\n",(0,a.jsx)(n.p,{children:"The deletion process removes the connector configuration but does not affect the database itself. Database users and permissions remain in place, requiring separate cleanup if you no longer need them."}),"\n",(0,a.jsx)(n.h3,{id:"troubleshooting",children:"Troubleshooting"}),"\n",(0,a.jsx)(n.p,{children:"When connecting SAM to a PostgreSQL databases hosted on Supabase, you may encounter network errors like:"}),"\n",(0,a.jsx)(n.p,{children:(0,a.jsx)(n.code,{children:'{ "detail": "Invalid token", "error_type": "invalid_token" }'})}),"\n",(0,a.jsx)(n.p,{children:"This is because Supabase's direct connection endpoint uses IPv6, however most Kubernetes clusters are IPv4 by default.\nThe solution is to use the Session Pooler endpoint as it is IPv4 compatible."}),"\n",(0,a.jsx)(n.h2,{id:"access-control",children:"Access Control"}),"\n",(0,a.jsx)(n.p,{children:"Connector operations require specific RBAC capabilities. The table below shows the capabilities and what they control:"}),"\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:"Capability"}),(0,a.jsx)(n.th,{children:"Purpose"})]})}),(0,a.jsxs)(n.tbody,{children:[(0,a.jsxs)(n.tr,{children:[(0,a.jsx)(n.td,{children:(0,a.jsx)(n.code,{children:"sam:connectors:create"})}),(0,a.jsx)(n.td,{children:"Create new connectors in the Connectors section"})]}),(0,a.jsxs)(n.tr,{children:[(0,a.jsx)(n.td,{children:(0,a.jsx)(n.code,{children:"sam:connectors:read"})}),(0,a.jsx)(n.td,{children:"View connector configurations and list available connectors"})]}),(0,a.jsxs)(n.tr,{children:[(0,a.jsx)(n.td,{children:(0,a.jsx)(n.code,{children:"sam:connectors:update"})}),(0,a.jsx)(n.td,{children:"Modify connector configurations and credentials"})]}),(0,a.jsxs)(n.tr,{children:[(0,a.jsx)(n.td,{children:(0,a.jsx)(n.code,{children:"sam:connectors:delete"})}),(0,a.jsx)(n.td,{children:"Remove connectors from the system"})]})]})]}),"\n",(0,a.jsxs)(n.p,{children:["For detailed information about configuring role-based access control, see ",(0,a.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/enterprise/rbac-setup-guide",children:"Setting Up RBAC"}),"."]})]})}function u(e={}){const{wrapper:n}={...(0,o.R)(),...e.components};return n?(0,a.jsx)(n,{...e,children:(0,a.jsx)(l,{...e})}):l(e)}},8453:(e,n,t)=>{t.d(n,{R:()=>i,x:()=>r});var s=t(6540);const a={},o=s.createContext(a);function i(e){const n=s.useContext(o);return s.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(a):e.components||a:i(e.components),s.createElement(o.Provider,{value:n},e.children)}}}]);

solace_agent_mesh/assets/docs/assets/js/ceb2a7a6.5d92d7d0.js

@@ -0,0 +1 @@
+"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[3478],{2467:(e,n,t)=>{t.r(n),t.d(n,{assets:()=>r,contentTitle:()=>l,default:()=>h,frontMatter:()=>i,metadata:()=>s,toc:()=>c});const s=JSON.parse('{"id":"documentation/developing/evaluations","title":"Evaluating Agents","description":"The framework includes an evaluation system that helps you test your agents\' behavior in a structured way. You can define test suites, run them against your agents, and generate detailed reports to analyze the results. When running evaluations locally, you can also benchmark different language models to see how they affect your agents\' responses.","source":"@site/docs/documentation/developing/evaluations.md","sourceDirName":"documentation/developing","slug":"/documentation/developing/evaluations","permalink":"/solace-agent-mesh/docs/documentation/developing/evaluations","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/developing/evaluations.md","tags":[],"version":"current","sidebarPosition":450,"frontMatter":{"title":"Evaluating Agents","sidebar_position":450},"sidebar":"docSidebar","previous":{"title":"Creating Service Providers","permalink":"/solace-agent-mesh/docs/documentation/developing/creating-service-providers"},"next":{"title":"Build Your Own Agent","permalink":"/solace-agent-mesh/docs/documentation/developing/tutorials/custom-agent"}}');var a=t(4848),o=t(8453);const i={title:"Evaluating Agents",sidebar_position:450},l="Evaluating Agents",r={},c=[{value:"Creating a Test Case",id:"creating-a-test-case",level:2},{value:"Test Case Configuration",id:"test-case-configuration",level:3},{value:"Test Case Examples",id:"test-case-examples",level:3},{value:"Creating a Test Suite",id:"creating-a-test-suite",level:2},{value:"Local Evaluation",id:"local-evaluation",level:3},{value:"Local Test Suite Configuration",id:"local-test-suite-configuration",level:4},{value:"Example Local Test Suite",id:"example-local-test-suite",level:4},{value:"Remote Evaluation",id:"remote-evaluation",level:3},{value:"Remote Test Suite Configuration",id:"remote-test-suite-configuration",level:4},{value:"Example Remote Test Suite",id:"example-remote-test-suite",level:4},{value:"Evaluation Settings",id:"evaluation-settings",level:2},{value:"<code>tool_match</code>",id:"tool_match",level:3},{value:"<code>response_match</code>",id:"response_match",level:3},{value:"<code>llm_evaluator</code>",id:"llm_evaluator",level:3},{value:"Running Evaluations",id:"running-evaluations",level:2},{value:"Command",id:"command",level:3},{value:"Options",id:"options",level:3},{value:"Example",id:"example",level:3},{value:"Interpreting the Results",id:"interpreting-the-results",level:2},{value:"Results Directory",id:"results-directory",level:3},{value:"HTML Report",id:"html-report",level:3}];function d(e){const n={a:"a",code:"code",h1:"h1",h2:"h2",h3:"h3",h4:"h4",header:"header",li:"li",p:"p",pre:"pre",strong:"strong",ul:"ul",...(0,o.R)(),...e.components};return(0,a.jsxs)(a.Fragment,{children:[(0,a.jsx)(n.header,{children:(0,a.jsx)(n.h1,{id:"evaluating-agents",children:"Evaluating Agents"})}),"\n",(0,a.jsx)(n.p,{children:"The framework includes an evaluation system that helps you test your agents' behavior in a structured way. You can define test suites, run them against your agents, and generate detailed reports to analyze the results. When running evaluations locally, you can also benchmark different language models to see how they affect your agents' responses."}),"\n",(0,a.jsx)(n.p,{children:"At a high level, the evaluation process involves three main components:"}),"\n",(0,a.jsxs)(n.ul,{children:["\n",(0,a.jsxs)(n.li,{children:[(0,a.jsx)(n.strong,{children:"Test Case"}),": A ",(0,a.jsx)(n.code,{children:"JSON"})," file that defines a single, specific task for an agent to perform. It includes the initial prompt, any required files (artifacts), and the criteria for a successful outcome."]}),"\n",(0,a.jsxs)(n.li,{children:[(0,a.jsx)(n.strong,{children:"Test Suite"}),": A ",(0,a.jsx)(n.code,{children:"JSON"})," file that groups one or more test cases into a single evaluation run. It also defines the environment for the evaluation, such as whether to run the agents locally or connect to a remote Agent Mesh."]}),"\n",(0,a.jsxs)(n.li,{children:[(0,a.jsx)(n.strong,{children:"Evaluation Settings"}),": A configuration block within the test suite that specifies how to score the agent's performance. You can choose from several methods, from simple metric-based comparisons to more advanced evaluations using a language model."]}),"\n"]}),"\n",(0,a.jsx)(n.p,{children:"This document guides you through creating test cases, assembling them into test suites, and running evaluations to test your agents."}),"\n",(0,a.jsx)(n.h2,{id:"creating-a-test-case",children:"Creating a Test Case"}),"\n",(0,a.jsxs)(n.p,{children:["A test case is a ",(0,a.jsx)(n.code,{children:"JSON"})," file that defines a specific task for an agent to perform. It serves as the fundamental building block of an evaluation. You create a test case to represent a single interaction you want to test, such as asking a question, providing a file for processing, or requesting a specific action from an agent."]}),"\n",(0,a.jsx)(n.h3,{id:"test-case-configuration",children:"Test Case Configuration"}),"\n",(0,a.jsxs)(n.p,{children:["The following fields are available in the test case ",(0,a.jsx)(n.code,{children:"JSON"})," file."]}),"\n",(0,a.jsxs)(n.ul,{children:["\n",(0,a.jsxs)(n.li,{children:[(0,a.jsx)(n.code,{children:"test_case_id"})," (Required): A unique identifier for the test case."]}),"\n",(0,a.jsxs)(n.li,{children:[(0,a.jsx)(n.code,{children:"query"})," (Required): The initial prompt to be sent to the agent."]}),"\n",(0,a.jsxs)(n.li,{children:[(0,a.jsx)(n.code,{children:"target_agent"})," (Required): The name of the agent to which the query should be sent."]}),"\n",(0,a.jsxs)(n.li,{children:[(0,a.jsx)(n.code,{children:"category"})," (Optional): The category of the test case. Defaults to ",(0,a.jsx)(n.code,{children:"Other"}),"."]}),"\n",(0,a.jsxs)(n.li,{children:[(0,a.jsx)(n.code,{children:"description"})," (Optional): A description of the test case."]}),"\n",(0,a.jsxs)(n.li,{children:[(0,a.jsx)(n.code,{children:"artifacts"})," (Optional): A list of artifacts to be sent with the initial query. Each artifact has a ",(0,a.jsx)(n.code,{children:"type"})," and a ",(0,a.jsx)(n.code,{children:"path"}),"."]}),"\n",(0,a.jsxs)(n.li,{children:[(0,a.jsx)(n.code,{children:"wait_time"})," (Optional): The maximum time in seconds to wait for a response from the agent. Defaults to ",(0,a.jsx)(n.code,{children:"60"}),"."]}),"\n",(0,a.jsxs)(n.li,{children:[(0,a.jsx)(n.code,{children:"evaluation"})," (Optional): The evaluation criteria for the test case.","\n",(0,a.jsxs)(n.ul,{children:["\n",(0,a.jsxs)(n.li,{children:[(0,a.jsx)(n.code,{children:"expected_tools"})," (Optional): A list of tools that the agent is expected to use. Defaults to an empty list."]}),"\n",(0,a.jsxs)(n.li,{children:[(0,a.jsx)(n.code,{children:"expected_response"})," (Optional): The expected final response from the agent. Defaults to an empty string."]}),"\n",(0,a.jsxs)(n.li,{children:[(0,a.jsx)(n.code,{children:"criterion"})," (Optional): The criterion to be used by the ",(0,a.jsx)(n.code,{children:"llm_evaluator"}),". Defaults to an empty string."]}),"\n"]}),"\n"]}),"\n"]}),"\n",(0,a.jsx)(n.h3,{id:"test-case-examples",children:"Test Case Examples"}),"\n",(0,a.jsx)(n.p,{children:"Here is an example of a simple test case. It sends a greeting to an agent and checks for a standard response."}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-json",children:'{\n    "test_case_id": "hello_world",\n    "category": "Content Generation",\n    "description": "A simple test case to check the basic functionality of the system.",\n    "query": "Hello, world!",\n    "target_agent": "OrchestratorAgent",\n    "wait_time": 30,\n    "evaluation": {\n        "expected_tools": [],\n        "expected_response": "Hello! How can I help you today?",\n        "criterion": "Evaluate if the agent provides a standard greeting."\n    }\n}\n'})}),"\n",(0,a.jsxs)(n.p,{children:["This next example shows a more complex test case. It includes a ",(0,a.jsx)(n.code,{children:"CSV"})," file as an artifact and asks the agent to filter the data in the file."]}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-json",children:'{\n  "test_case_id": "filter_csv_employees_by_age_and_country",\n  "category": "Tool Usage",\n  "description": "A test case to filter employees from a CSV file based on age and country.",\n  "target_agent": "OrchestratorAgent",\n  "query": "From the attached CSV, please list the names of all people who are older or equal to 30 and live in the USA.",\n  "artifacts": [\n    {\n      "type": "file",\n      "path": "artifacts/sample.csv"\n    }\n  ],\n  "wait_time": 120,\n  "evaluation": {\n    "expected_tools": ["extract_content_from_artifact"],\n    "expected_response": "The person who is 30 or older and lives in the USA is John Doe.",\n    "criterion": "Evaluate if the agent correctly filters the CSV data."\n  }\n}\n'})}),"\n",(0,a.jsx)(n.h2,{id:"creating-a-test-suite",children:"Creating a Test Suite"}),"\n",(0,a.jsxs)(n.p,{children:["The test suite is a ",(0,a.jsx)(n.code,{children:"JSON"})," file that defines the parameters of an evaluation run. You use it to group test cases and configure the environment in which they run."]}),"\n",(0,a.jsxs)(n.p,{children:["A common convention in the test suite configuration is to use keys ending with ",(0,a.jsx)(n.code,{children:"_VAR"}),". These keys indicate that the corresponding value is the name of an environment variable from which the framework should read the actual value. This practice helps you keep sensitive information\u2014like API keys and credentials\u2014out of your configuration files. This convention applies to the ",(0,a.jsx)(n.code,{children:"broker"})," object, the ",(0,a.jsx)(n.code,{children:"env"})," object within ",(0,a.jsx)(n.code,{children:"llm_models"}),", and the ",(0,a.jsx)(n.code,{children:"env"})," object within the ",(0,a.jsx)(n.code,{children:"llm_evaluator"})," in ",(0,a.jsx)(n.code,{children:"evaluation_settings"}),"."]}),"\n",(0,a.jsx)(n.p,{children:"You can run evaluations in two modes: local and remote. Both modes require a connection to a Solace event broker to function."}),"\n",(0,a.jsx)(n.h3,{id:"local-evaluation",children:"Local Evaluation"}),"\n",(0,a.jsx)(n.p,{children:"In a local evaluation, the evaluation framework brings up a local instance of Solace Agent Mesh (SAM) and runs the agents on your local machine. This mode is useful for development and testing because it allows you to iterate quickly on your agents and test cases. You can also use this mode to benchmark different language models against your agents to see how they perform."}),"\n",(0,a.jsxs)(n.p,{children:["To run a local evaluation, you need to install the ",(0,a.jsx)(n.code,{children:"sam-rest-gateway"})," plugin. This plugin allows the evaluation framework to communicate with the local SAM instance. You can install it with the following command:"]}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-bash",children:'pip install "sam-rest-gateway @ git+https://github.com/SolaceLabs/solace-agent-mesh-core-plugins#subdirectory=sam-rest-gateway"\n'})}),"\n",(0,a.jsx)(n.h4,{id:"local-test-suite-configuration",children:"Local Test Suite Configuration"}),"\n",(0,a.jsxs)(n.p,{children:["For a local evaluation, you must define the ",(0,a.jsx)(n.code,{children:"agents"}),", ",(0,a.jsx)(n.code,{children:"broker"}),", ",(0,a.jsx)(n.code,{children:"llm_models"}),", and ",(0,a.jsx)(n.code,{children:"test_cases"})," fields."]}),"\n",(0,a.jsxs)(n.p,{children:["The ",(0,a.jsx)(n.code,{children:"agents"})," field is a required list of paths to the agent configuration files. You must specify at least one agent."]}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-json",children:'"agents": [ "examples/agents/a2a_agents_example.yaml" ]\n'})}),"\n",(0,a.jsxs)(n.p,{children:["The ",(0,a.jsx)(n.code,{children:"broker"})," field is a required object containing the connection details for the Solace event broker."]}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-json",children:'"broker": {\n    "SOLACE_BROKER_URL_VAR": "SOLACE_BROKER_URL",\n    "SOLACE_BROKER_USERNAME_VAR": "SOLACE_BROKER_USERNAME",\n    "SOLACE_BROKER_PASSWORD_VAR": "SOLACE_BROKER_PASSWORD",\n    "SOLACE_BROKER_VPN_VAR": "SOLACE_BROKER_VPN"\n}\n'})}),"\n",(0,a.jsxs)(n.p,{children:["The ",(0,a.jsx)(n.code,{children:"llm_models"})," field is a required list of language models to use. You must specify at least one model. The ",(0,a.jsx)(n.code,{children:"env"})," object contains environment variables required by the model, such as the model name, endpoint, and API key."]}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-json",children:'"llm_models": [\n    {\n        "name": "gpt-4-1",\n        "env": {\n            "LLM_SERVICE_PLANNING_MODEL_NAME": "openai/azure-gpt-4-1",\n            "LLM_SERVICE_ENDPOINT_VAR": "LLM_SERVICE_ENDPOINT",\n            "LLM_SERVICE_API_KEY_VAR": "LLM_SERVICE_API_KEY"\n        }\n    },\n    {\n        "name": "gemini-1.5-pro",\n        "env": {\n            "LLM_SERVICE_PLANNING_MODEL_NAME": "google/gemini-1.5-pro-latest",\n            "LLM_SERVICE_ENDPOINT_VAR": "LLM_SERVICE_ENDPOINT_GOOGLE",\n            "LLM_SERVICE_API_KEY_VAR": "LLM_SERVICE_API_KEY_GOOGLE"\n        }\n    }\n]\n'})}),"\n",(0,a.jsxs)(n.p,{children:["The ",(0,a.jsx)(n.code,{children:"test_cases"})," field is a required list of paths to the test case ",(0,a.jsx)(n.code,{children:"JSON"})," files. You must specify at least one test case."]}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-json",children:'"test_cases": [ "tests/evaluation/test_cases/hello_world.test.json" ]\n'})}),"\n",(0,a.jsxs)(n.p,{children:["You can also provide optional settings for ",(0,a.jsx)(n.code,{children:"results_dir_name"}),", ",(0,a.jsx)(n.code,{children:"runs"}),", ",(0,a.jsx)(n.code,{children:"workers"}),", and ",(0,a.jsx)(n.code,{children:"evaluation_settings"}),"."]}),"\n",(0,a.jsxs)(n.p,{children:["The ",(0,a.jsx)(n.code,{children:"results_dir_name"})," field is an optional string that specifies the name of the directory for evaluation results. It defaults to ",(0,a.jsx)(n.code,{children:"tests"}),"."]}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-json",children:'"results_dir_name": "my-local-test-results"\n'})}),"\n",(0,a.jsxs)(n.p,{children:["The ",(0,a.jsx)(n.code,{children:"runs"})," field is an optional integer that specifies the number of times to run each test case. It defaults to ",(0,a.jsx)(n.code,{children:"1"}),"."]}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-json",children:'"runs": 3\n'})}),"\n",(0,a.jsxs)(n.p,{children:["The ",(0,a.jsx)(n.code,{children:"workers"})," field is an optional integer that specifies the number of parallel workers for running tests. It defaults to ",(0,a.jsx)(n.code,{children:"4"}),"."]}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-json",children:'"workers": 8\n'})}),"\n",(0,a.jsxs)(n.p,{children:["The ",(0,a.jsx)(n.code,{children:"evaluation_settings"})," field is an optional object that allows you to configure the evaluation. This object can contain ",(0,a.jsx)(n.code,{children:"tool_match"}),", ",(0,a.jsx)(n.code,{children:"response_match"}),", and ",(0,a.jsx)(n.code,{children:"llm_evaluator"})," settings."]}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-json",children:'"evaluation_settings": {\n    "tool_match": {\n        "enabled": true\n    },\n    "response_match": {\n        "enabled": true\n    },\n    "llm_evaluator": {\n        "enabled": true,\n        "env": {\n            "LLM_SERVICE_PLANNING_MODEL_NAME": "openai/gemini-2.5-pro",\n            "LLM_SERVICE_ENDPOINT_VAR": "LLM_SERVICE_ENDPOINT",\n            "LLM_SERVICE_API_KEY_VAR": "LLM_SERVICE_API_KEY"\n        }\n    }\n}\n'})}),"\n",(0,a.jsx)(n.h4,{id:"example-local-test-suite",children:"Example Local Test Suite"}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-json",children:'{\n    "agents": [\n        "examples/agents/a2a_agents_example.yaml",\n        "examples/agents/multimodal_example.yaml",\n        "examples/agents/orchestrator_example.yaml"\n    ],\n    "broker": {\n        "SOLACE_BROKER_URL_VAR": "SOLACE_BROKER_URL",\n        "SOLACE_BROKER_USERNAME_VAR": "SOLACE_BROKER_USERNAME",\n        "SOLACE_BROKER_PASSWORD_VAR": "SOLACE_BROKER_PASSWORD",\n        "SOLACE_BROKER_VPN_VAR": "SOLACE_BROKER_VPN"\n    },\n    "llm_models": [\n        {\n            "name": "gpt-4-1",\n            "env": {\n                "LLM_SERVICE_PLANNING_MODEL_NAME": "openai/azure-gpt-4-1",\n                "LLM_SERVICE_ENDPOINT_VAR": "LLM_SERVICE_ENDPOINT",\n                "LLM_SERVICE_API_KEY_VAR": "LLM_SERVICE_API_KEY"\n            }\n        }\n    ],\n    "results_dir_name": "sam-local-eval-test",\n    "runs": 3,\n    "workers": 4,\n    "test_cases": [\n        "tests/evaluation/test_cases/filter_csv_employees_by_age_and_country.test.json",\n        "tests/evaluation/test_cases/hello_world.test.json"\n    ],\n    "evaluation_settings": {\n        "tool_match": {\n            "enabled": true\n        },\n        "response_match": {\n            "enabled": true\n        },\n        "llm_evaluator": {\n            "enabled": true,\n            "env": {\n                "LLM_SERVICE_PLANNING_MODEL_NAME": "openai/gemini-2.5-pro",\n                "LLM_SERVICE_ENDPOINT_VAR": "LLM_SERVICE_ENDPOINT",\n                "LLM_SERVICE_API_KEY_VAR": "LLM_SERVICE_API_KEY"\n            }\n        }\n    }\n}\n'})}),"\n",(0,a.jsx)(n.h3,{id:"remote-evaluation",children:"Remote Evaluation"}),"\n",(0,a.jsx)(n.p,{children:"In a remote evaluation, the evaluation framework sends requests to a remote Agent Mesh instance. This mode is useful for testing agents in a production-like environment where the agents are running on a separate server. The remote environment must have a REST gateway running to accept requests from the evaluation framework. You can also use an authentication token to communicate securely with the remote SAM instance."}),"\n",(0,a.jsx)(n.h4,{id:"remote-test-suite-configuration",children:"Remote Test Suite Configuration"}),"\n",(0,a.jsxs)(n.p,{children:["For a remote evaluation, you must define the ",(0,a.jsx)(n.code,{children:"broker"}),", ",(0,a.jsx)(n.code,{children:"remote"}),", and ",(0,a.jsx)(n.code,{children:"test_cases"})," fields."]}),"\n",(0,a.jsxs)(n.p,{children:["The ",(0,a.jsx)(n.code,{children:"broker"})," field is a required object with connection details for the Solace event broker."]}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-json",children:'"broker": {\n    "SOLACE_BROKER_URL_VAR": "SOLACE_BROKER_URL",\n    "SOLACE_BROKER_USERNAME_VAR": "SOLACE_BROKER_USERNAME",\n    "SOLACE_BROKER_PASSWORD_VAR": "SOLACE_BROKER_PASSWORD",\n    "SOLACE_BROKER_VPN_VAR": "SOLACE_BROKER_VPN"\n}\n'})}),"\n",(0,a.jsxs)(n.p,{children:["The ",(0,a.jsx)(n.code,{children:"remote"})," field is a required object containing the connection details for the remote Agent Mesh instance."]}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-json",children:'"remote": {\n    "EVAL_REMOTE_URL_VAR": "EVAL_REMOTE_URL",\n    "EVAL_AUTH_TOKEN_VAR": "EVAL_AUTH_TOKEN",\n    "EVAL_NAMESPACE_VAR": "EVAL_NAMESPACE"\n}\n'})}),"\n",(0,a.jsxs)(n.p,{children:["The ",(0,a.jsx)(n.code,{children:"test_cases"})," field is a required list of paths to the test case ",(0,a.jsx)(n.code,{children:"JSON"})," files. You must specify at least one test case."]}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-json",children:'"test_cases": [ "tests/evaluation/test_cases/hello_world.test.json" ]\n'})}),"\n",(0,a.jsxs)(n.p,{children:["You can also provide optional settings for ",(0,a.jsx)(n.code,{children:"results_dir_name"}),", ",(0,a.jsx)(n.code,{children:"runs"}),", and ",(0,a.jsx)(n.code,{children:"evaluation_settings"}),"."]}),"\n",(0,a.jsxs)(n.p,{children:["The ",(0,a.jsx)(n.code,{children:"results_dir_name"})," field is an optional string that specifies the name of the directory for evaluation results. It defaults to ",(0,a.jsx)(n.code,{children:"tests"}),"."]}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-json",children:'"results_dir_name": "my-remote-test-results"\n'})}),"\n",(0,a.jsxs)(n.p,{children:["The ",(0,a.jsx)(n.code,{children:"runs"})," field is an optional integer that specifies the number of times to run each test case. It defaults to ",(0,a.jsx)(n.code,{children:"1"}),"."]}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-json",children:'"runs": 5\n'})}),"\n",(0,a.jsxs)(n.p,{children:["The ",(0,a.jsx)(n.code,{children:"evaluation_settings"})," field is an optional object that allows you to configure the evaluation."]}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-json",children:'"evaluation_settings": {\n    "tool_match": {\n        "enabled": true\n    },\n    "response_match": {\n        "enabled": true\n    }\n}\n'})}),"\n",(0,a.jsx)(n.h4,{id:"example-remote-test-suite",children:"Example Remote Test Suite"}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-json",children:'{\n    "broker": {\n        "SOLACE_BROKER_URL_VAR": "SOLACE_BROKER_URL",\n        "SOLACE_BROKER_USERNAME_VAR": "SOLACE_BROKER_USERNAME",\n        "SOLACE_BROKER_PASSWORD_VAR": "SOLACE_BROKER_PASSWORD",\n        "SOLACE_BROKER_VPN_VAR": "SOLACE_BROKER_VPN"\n    },\n    "remote": {\n        "EVAL_REMOTE_URL_VAR": "EVAL_REMOTE_URL",\n        "EVAL_AUTH_TOKEN_VAR": "EVAL_AUTH_TOKEN",\n        "EVAL_NAMESPACE_VAR": "EVAL_NAMESPACE"\n    },\n    "results_dir_name": "sam-remote-eval-test",\n    "runs": 1,\n    "test_cases": [\n        "tests/evaluation/test_cases/filter_csv_employees_by_age_and_country.test.json",\n        "tests/evaluation/test_cases/hello_world.test.json"\n    ],\n    "evaluation_settings": {\n        "tool_match": {\n            "enabled": true\n        },\n        "response_match": {\n            "enabled": true\n        },\n        "llm_evaluator": {\n            "enabled": true,\n            "env": {\n                "LLM_SERVICE_PLANNING_MODEL_NAME": "openai/gemini-2.5-pro",\n                "LLM_SERVICE_ENDPOINT_VAR": "LLM_SERVICE_ENDPOINT",\n                "LLM_SERVICE_API_KEY_VAR": "LLM_SERVICE_API_KEY"\n            }\n        }\n    }\n}\n'})}),"\n",(0,a.jsx)(n.h2,{id:"evaluation-settings",children:"Evaluation Settings"}),"\n",(0,a.jsxs)(n.p,{children:["The ",(0,a.jsx)(n.code,{children:"evaluation_settings"})," block in the test suite ",(0,a.jsx)(n.code,{children:"JSON"})," file allows you to configure how the evaluation is performed. Each enabled setting provides a score from 0 to 1, which contributes to the overall score for the test case."]}),"\n",(0,a.jsx)(n.h3,{id:"tool_match",children:(0,a.jsx)(n.code,{children:"tool_match"})}),"\n",(0,a.jsxs)(n.p,{children:["The ",(0,a.jsx)(n.code,{children:"tool_match"})," setting compares the tools the agent used with the ",(0,a.jsx)(n.code,{children:"expected_tools"})," defined in the test case. This is a simple, direct comparison and does not use a language model for the evaluation. It is most effective when the agent's expected behavior is straightforward and there is a clear, correct sequence of tools to be used. In more complex scenarios where multiple paths could lead to a successful outcome, this method may not be the best way to evaluate the agent's performance."]}),"\n",(0,a.jsx)(n.h3,{id:"response_match",children:(0,a.jsx)(n.code,{children:"response_match"})}),"\n",(0,a.jsxs)(n.p,{children:["The ",(0,a.jsx)(n.code,{children:"response_match"})," setting compares the agent's final response with the ",(0,a.jsx)(n.code,{children:"expected_response"})," from the test case. This comparison is based on the ROUGE metric, which evaluates the similarity between two responses by comparing their sequence of words. This method does not use a language model for the evaluation and does not work well with synonyms, so it is most effective when the expected answer is consistent. For more information about the ROUGE metric, see the ",(0,a.jsx)(n.a,{href:"https://pypi.org/project/rouge-metric/",children:"official documentation"}),"."]}),"\n",(0,a.jsx)(n.h3,{id:"llm_evaluator",children:(0,a.jsx)(n.code,{children:"llm_evaluator"})}),"\n",(0,a.jsxs)(n.p,{children:["The ",(0,a.jsx)(n.code,{children:"llm_evaluator"})," setting uses a language model to evaluate the entire lifecycle of a request within the agent mesh. This includes the initial prompt, all tool calls, delegation between agents, artifact inputs and outputs, and the final message output. The evaluation is based on a ",(0,a.jsx)(n.code,{children:"criterion"})," you provide in the test case, which defines what a successful outcome looks like. This is the most comprehensive evaluation method because it considers the full context of the request's execution."]}),"\n",(0,a.jsx)(n.h2,{id:"running-evaluations",children:"Running Evaluations"}),"\n",(0,a.jsxs)(n.p,{children:["After you create your test cases and test suite, you can run the evaluation from the command line using the ",(0,a.jsx)(n.code,{children:"sam eval"})," command."]}),"\n",(0,a.jsx)(n.h3,{id:"command",children:"Command"}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-bash",children:"sam eval <PATH> [OPTIONS]\n"})}),"\n",(0,a.jsxs)(n.p,{children:["The command takes the path to the evaluation test suite ",(0,a.jsx)(n.code,{children:"JSON"})," file as a required argument."]}),"\n",(0,a.jsx)(n.h3,{id:"options",children:"Options"}),"\n",(0,a.jsxs)(n.ul,{children:["\n",(0,a.jsxs)(n.li,{children:[(0,a.jsx)(n.code,{children:"-v"}),", ",(0,a.jsx)(n.code,{children:"--verbose"}),": Enable verbose output to see detailed logs during the evaluation run."]}),"\n",(0,a.jsxs)(n.li,{children:[(0,a.jsx)(n.code,{children:"-h"}),", ",(0,a.jsx)(n.code,{children:"--help"}),": Show a help message with information about the command and its options."]}),"\n"]}),"\n",(0,a.jsx)(n.h3,{id:"example",children:"Example"}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-bash",children:"sam eval tests/evaluation/local_example.json --verbose\n"})}),"\n",(0,a.jsx)(n.h2,{id:"interpreting-the-results",children:"Interpreting the Results"}),"\n",(0,a.jsxs)(n.p,{children:["After an evaluation run is complete, the framework stores the results in a directory. The path to this directory is ",(0,a.jsx)(n.code,{children:"results/"})," followed by the ",(0,a.jsx)(n.code,{children:"results_dir_name"})," you specified in the test suite."]}),"\n",(0,a.jsx)(n.h3,{id:"results-directory",children:"Results Directory"}),"\n",(0,a.jsx)(n.p,{children:"The results directory has the following structure:"}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{children:"<results_dir_name>/\n\u251c\u2500\u2500 report.html\n\u251c\u2500\u2500 stats.json\n\u2514\u2500\u2500 <model_name>/\n    \u251c\u2500\u2500 full_messages.json\n    \u251c\u2500\u2500 results.json\n    \u2514\u2500\u2500 <test_case_id>/\n        \u2514\u2500\u2500 run_1/\n            \u251c\u2500\u2500 messages.json\n            \u251c\u2500\u2500 summary.json\n            \u2514\u2500\u2500 test_case_info.json\n        \u2514\u2500\u2500 run_2/\n            \u251c\u2500\u2500 ...\n"})}),"\n",(0,a.jsxs)(n.ul,{children:["\n",(0,a.jsxs)(n.li,{children:[(0,a.jsx)(n.strong,{children:(0,a.jsx)(n.code,{children:"report.html"})}),": An ",(0,a.jsx)(n.code,{children:"HTML"})," report that provides a comprehensive overview of the evaluation results. It includes a summary of the test runs, a breakdown of the results for each test case, and detailed logs for each test run. This report is the primary tool for analyzing the results of an evaluation."]}),"\n",(0,a.jsxs)(n.li,{children:[(0,a.jsx)(n.strong,{children:(0,a.jsx)(n.code,{children:"stats.json"})}),": A ",(0,a.jsx)(n.code,{children:"JSON"})," file containing detailed statistics about the evaluation run, including scores for each evaluation metric."]}),"\n",(0,a.jsxs)(n.li,{children:[(0,a.jsx)(n.strong,{children:(0,a.jsx)(n.code,{children:"<model_name>/"})}),": A directory for each language model tested (or a single ",(0,a.jsx)(n.code,{children:"remote"})," directory for remote evaluations).","\n",(0,a.jsxs)(n.ul,{children:["\n",(0,a.jsxs)(n.li,{children:[(0,a.jsx)(n.strong,{children:(0,a.jsx)(n.code,{children:"full_messages.json"})}),": A log of all messages exchanged during the evaluation for that model."]}),"\n",(0,a.jsxs)(n.li,{children:[(0,a.jsx)(n.strong,{children:(0,a.jsx)(n.code,{children:"results.json"})}),": The raw evaluation results for each test case."]}),"\n",(0,a.jsxs)(n.li,{children:[(0,a.jsx)(n.strong,{children:(0,a.jsx)(n.code,{children:"<test_case_id>/"})}),": A directory for each test case, containing a ",(0,a.jsx)(n.code,{children:"run_n"})," subdirectory for each run of the test case. These directories contain detailed logs and artifacts for each run."]}),"\n"]}),"\n"]}),"\n"]}),"\n",(0,a.jsx)(n.h3,{id:"html-report",children:"HTML Report"}),"\n",(0,a.jsxs)(n.p,{children:["The ",(0,a.jsx)(n.code,{children:"report.html"})," file provides a comprehensive overview of the evaluation results. It includes a summary of the test runs, a breakdown of the results for each test case, and detailed logs for each test run. This report is the primary tool for analyzing the results of an evaluation. You can open this file in a web browser to view the report."]})]})}function h(e={}){const{wrapper:n}={...(0,o.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:()=>l});var s=t(6540);const a={},o=s.createContext(a);function i(e){const n=s.useContext(o);return s.useMemo((function(){return"function"==typeof e?e(n):{...n,...e}}),[n,e])}function l(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(a):e.components||a:i(e.components),s.createElement(o.Provider,{value:n},e.children)}}}]);

solace_agent_mesh/assets/docs/assets/js/da0b5bad.b62f7b08.js

@@ -0,0 +1 @@
+"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[582],{4415:(e,n,t)=>{t.r(n),t.d(n,{assets:()=>l,contentTitle:()=>o,default:()=>p,frontMatter:()=>i,metadata:()=>a,toc:()=>c});const a=JSON.parse('{"id":"documentation/developing/create-gateways","title":"Creating Custom Gateways","description":"Gateway adapters connect external systems to the Agent Mesh through custom interfaces. They translate between platform-specific formats (Slack messages, HTTP requests, webhook payloads) and the standardized A2A protocol that agents understand. Gateway adapters handle platform events, extract user identity, and deliver agent responses back to users in the appropriate format.","source":"@site/docs/documentation/developing/create-gateways.md","sourceDirName":"documentation/developing","slug":"/documentation/developing/create-gateways","permalink":"/solace-agent-mesh/docs/documentation/developing/create-gateways","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/developing/create-gateways.md","tags":[],"version":"current","sidebarPosition":430,"frontMatter":{"title":"Creating Custom Gateways","sidebar_position":430},"sidebar":"docSidebar","previous":{"title":"Creating Agents","permalink":"/solace-agent-mesh/docs/documentation/developing/create-agents"},"next":{"title":"Creating Python Tools","permalink":"/solace-agent-mesh/docs/documentation/developing/creating-python-tools"}}');var s=t(4848),r=t(8453);const i={title:"Creating Custom Gateways",sidebar_position:430},o="Creating Custom Gateways",l={},c=[{value:"Key Functions",id:"key-functions",level:2},{value:"Architecture Overview",id:"architecture-overview",level:2},{value:"Core Concepts",id:"core-concepts",level:2},{value:"The Gateway Adapter Contract",id:"the-gateway-adapter-contract",level:3},{value:"The Gateway Context",id:"the-gateway-context",level:3},{value:"The Type System",id:"the-type-system",level:3},{value:"Adapter Lifecycle",id:"adapter-lifecycle",level:2},{value:"Initialization",id:"initialization",level:3},{value:"Active Processing",id:"active-processing",level:3},{value:"Cleanup",id:"cleanup",level:3},{value:"Implementing an Adapter",id:"implementing-an-adapter",level:2},{value:"Required Configuration",id:"required-configuration",level:3},{value:"Authentication: extract_auth_claims()",id:"authentication-extract_auth_claims",level:3},{value:"Inbound: prepare_task()",id:"inbound-prepare_task",level:3},{value:"Outbound: handle_update()",id:"outbound-handle_update",level:3},{value:"Completion: handle_task_complete()",id:"completion-handle_task_complete",level:3},{value:"Error Handling: handle_error()",id:"error-handling-handle_error",level:3},{value:"Gateway Context Services",id:"gateway-context-services",level:2},{value:"Task Management",id:"task-management",level:3},{value:"Artifact Management",id:"artifact-management",level:3},{value:"Feedback Collection",id:"feedback-collection",level:3},{value:"State Management",id:"state-management",level:3},{value:"Timer Management",id:"timer-management",level:3},{value:"Configuration",id:"configuration",level:2},{value:"Example: Slack Adapter",id:"example-slack-adapter",level:2},{value:"Configuration Model",id:"configuration-model",level:3},{value:"Authentication with Caching",id:"authentication-with-caching",level:3},{value:"Streaming Updates with Message Queue",id:"streaming-updates-with-message-queue",level:3},{value:"Creating Your Own Adapter",id:"creating-your-own-adapter",level:2},{value:"Option 1: Create as a Plugin (Recommended)",id:"option-1-create-as-a-plugin-recommended",level:3},{value:"Option 2: Add to Existing Project",id:"option-2-add-to-existing-project",level:3},{value:"Advanced: Full Custom Gateways",id:"advanced-full-custom-gateways",level:2},{value:"Related Documentation",id:"related-documentation",level:2}];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",ul:"ul",...(0,r.R)(),...e.components};return(0,s.jsxs)(s.Fragment,{children:[(0,s.jsx)(n.header,{children:(0,s.jsx)(n.h1,{id:"creating-custom-gateways",children:"Creating Custom Gateways"})}),"\n",(0,s.jsx)(n.p,{children:"Gateway adapters connect external systems to the Agent Mesh through custom interfaces. They translate between platform-specific formats (Slack messages, HTTP requests, webhook payloads) and the standardized A2A protocol that agents understand. Gateway adapters handle platform events, extract user identity, and deliver agent responses back to users in the appropriate format."}),"\n",(0,s.jsx)(n.p,{children:"This guide walks you through creating custom gateways using the gateway adapter pattern."}),"\n",(0,s.jsx)(n.admonition,{title:"In one sentence",type:"tip",children:(0,s.jsx)(n.p,{children:"Gateway adapters are custom interfaces that connect external platforms to the agent mesh by translating events and responses between platform formats and the A2A protocol."})}),"\n",(0,s.jsx)(n.h2,{id:"key-functions",children:"Key Functions"}),"\n",(0,s.jsx)(n.p,{children:"Gateway adapters provide the following capabilities:"}),"\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:"Platform Integration"}),": Connect external systems such as Slack, webhooks, REST APIs, or custom protocols to the agent mesh. Handle incoming events, commands, and messages from these platforms."]}),"\n"]}),"\n",(0,s.jsxs)(n.li,{children:["\n",(0,s.jsxs)(n.p,{children:[(0,s.jsx)(n.strong,{children:"Authentication"}),": Extract user identity from platform events (OAuth tokens, API keys, platform user IDs) and integrate with identity providers for user enrichment."]}),"\n"]}),"\n",(0,s.jsxs)(n.li,{children:["\n",(0,s.jsxs)(n.p,{children:[(0,s.jsx)(n.strong,{children:"Message Translation"}),": Convert platform-specific message formats into standardized content that agents can process. Transform agent responses back into platform-native formats."]}),"\n"]}),"\n",(0,s.jsxs)(n.li,{children:["\n",(0,s.jsxs)(n.p,{children:[(0,s.jsx)(n.strong,{children:"Streaming Responses"}),": Deliver real-time updates from agents to users as they are generated. Handle text streaming, status updates, and progress indicators."]}),"\n"]}),"\n",(0,s.jsxs)(n.li,{children:["\n",(0,s.jsxs)(n.p,{children:[(0,s.jsx)(n.strong,{children:"File Management"}),": Process file uploads from users and deliver agent-generated artifacts (reports, images, data files) back to the platform in the appropriate format."]}),"\n"]}),"\n",(0,s.jsxs)(n.li,{children:["\n",(0,s.jsxs)(n.p,{children:[(0,s.jsx)(n.strong,{children:"Built-in Services"}),": Access state management for maintaining conversation context, timer scheduling for delayed operations, and feedback collection for gathering user ratings."]}),"\n"]}),"\n"]}),"\n",(0,s.jsx)(n.h2,{id:"architecture-overview",children:"Architecture Overview"}),"\n",(0,s.jsx)(n.p,{children:"Gateway adapters work alongside a generic gateway component to connect platforms to the agent mesh:"}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Gateway Adapter"}),": Your platform-specific code that receives events from external systems and formats responses for delivery back to users"]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Generic Gateway Component"}),": Handles A2A protocol communication, authentication flow, user enrichment, message routing, and artifact management"]}),"\n"]}),"\n",(0,s.jsx)(n.p,{children:"The following diagram illustrates the complete flow from external platform to agent mesh and back:"}),"\n",(0,s.jsx)(n.mermaid,{value:"sequenceDiagram\n    participant Platform as External Platform\n    participant Adapter as Gateway Adapter\n    participant Generic as Generic Gateway\n    participant Mesh as Agent Mesh\n\n    rect rgba(234, 234, 234, 1)\n        Note over Platform,Adapter: 1. External Event Arrives\n        Platform->>Adapter: Platform Event\n    end\n\n    rect rgba(234, 234, 234, 1)\n        Note over Adapter,Generic: 2. Adapter Processes Event\n        Adapter->>Adapter: extract_auth_claims()\n        Adapter->>Adapter: prepare_task()\n        Adapter->>Generic: handle_external_input(SamTask)\n    end\n\n    rect rgba(234, 234, 234, 1)\n        Note over Generic,Mesh: 3. Generic Gateway Handles A2A\n        Generic->>Generic: Authenticate & Enrich User\n        Generic->>Generic: Convert to A2A Format\n        Generic->>Mesh: Submit A2A Task\n    end\n\n    rect rgba(234, 234, 234, 1)\n        Note over Mesh,Adapter: 4. Response Flow\n        Mesh--\x3e>Generic: A2A Updates\n        Generic->>Generic: Convert to SAM Types\n        Generic->>Adapter: handle_update(SamUpdate)\n        Adapter->>Platform: Platform Response\n    end\n\n    %%{init: {\n        'theme': 'base',\n        'themeVariables': {\n            'actorBkg': '#00C895',\n            'actorBorder': '#00C895',\n            'actorTextColor': '#000000',\n            'noteBkgColor': '#FFF7C2',\n            'noteTextColor': '#000000',\n            'noteBorderColor': '#FFF7C2'\n        }\n    }}%%"}),"\n",(0,s.jsx)(n.h2,{id:"core-concepts",children:"Core Concepts"}),"\n",(0,s.jsx)(n.h3,{id:"the-gateway-adapter-contract",children:"The Gateway Adapter Contract"}),"\n",(0,s.jsxs)(n.p,{children:["Gateway adapters extend the ",(0,s.jsx)(n.code,{children:"GatewayAdapter"})," base class and implement methods for handling platform-specific events:"]}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsx)(n.li,{children:"Extract authentication information from platform events"}),"\n",(0,s.jsx)(n.li,{children:"Convert platform events into standardized task format"}),"\n",(0,s.jsx)(n.li,{children:"Format and send responses back to the platform"}),"\n"]}),"\n",(0,s.jsx)(n.h3,{id:"the-gateway-context",children:"The Gateway Context"}),"\n",(0,s.jsxs)(n.p,{children:["When your adapter initializes, it receives a ",(0,s.jsx)(n.code,{children:"GatewayContext"})," object that provides access to framework services:"]}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsx)(n.li,{children:"Task submission and cancellation"}),"\n",(0,s.jsx)(n.li,{children:"Artifact loading and management"}),"\n",(0,s.jsx)(n.li,{children:"User feedback collection"}),"\n",(0,s.jsx)(n.li,{children:"State management (task-level and session-level)"}),"\n",(0,s.jsx)(n.li,{children:"Timer scheduling"}),"\n"]}),"\n",(0,s.jsx)(n.h3,{id:"the-type-system",children:"The Type System"}),"\n",(0,s.jsx)(n.p,{children:"Gateway adapters use a standardized type system for messages:"}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"SamTask"}),": An inbound request with content parts and metadata"]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"SamUpdate"}),": An outbound update containing one or more content parts"]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"SamTextPart"}),": Text content in tasks or updates"]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"SamFilePart"}),": File content with bytes or URI"]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"SamDataPart"}),": Structured data with metadata"]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"AuthClaims"}),": User authentication information"]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"ResponseContext"}),": Context provided with each outbound callback"]}),"\n"]}),"\n",(0,s.jsx)(n.h2,{id:"adapter-lifecycle",children:"Adapter Lifecycle"}),"\n",(0,s.jsx)(n.p,{children:"Gateway adapters follow a simple lifecycle:"}),"\n",(0,s.jsx)(n.h3,{id:"initialization",children:"Initialization"}),"\n",(0,s.jsxs)(n.p,{children:["The ",(0,s.jsx)(n.code,{children:"init()"})," method is called when the gateway starts:"]}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-python",children:'async def init(self, context: GatewayContext) -> None:\n    """\n    Initialize the gateway adapter.\n\n    This is where you should:\n    - Store the context for later use\n    - Start platform listeners (WebSocket, HTTP server, etc.)\n    - Connect to external services\n    """\n    self.context = context\n    # Initialize your platform connection\n    await self.start_platform_listener()\n'})}),"\n",(0,s.jsx)(n.h3,{id:"active-processing",children:"Active Processing"}),"\n",(0,s.jsx)(n.p,{children:"During normal operation, the generic gateway calls your adapter methods:"}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.code,{children:"extract_auth_claims()"})," - Extract user identity from platform events"]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.code,{children:"prepare_task()"})," - Convert platform events to SamTask format"]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.code,{children:"handle_update()"})," - Process updates from agents"]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.code,{children:"handle_task_complete()"})," - Handle task completion"]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.code,{children:"handle_error()"})," - Handle errors"]}),"\n"]}),"\n",(0,s.jsx)(n.h3,{id:"cleanup",children:"Cleanup"}),"\n",(0,s.jsxs)(n.p,{children:["The ",(0,s.jsx)(n.code,{children:"cleanup()"})," method is called during shutdown:"]}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-python",children:'async def cleanup(self) -> None:\n    """\n    Clean up resources on shutdown.\n\n    This is where you should:\n    - Stop platform listeners\n    - Close connections\n    - Release resources\n    """\n    await self.stop_platform_listener()\n'})}),"\n",(0,s.jsx)(n.h2,{id:"implementing-an-adapter",children:"Implementing an Adapter"}),"\n",(0,s.jsx)(n.h3,{id:"required-configuration",children:"Required Configuration"}),"\n",(0,s.jsx)(n.p,{children:"Define a configuration model for your adapter using Pydantic:"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-python",children:'from pydantic import BaseModel, Field\n\nclass MyAdapterConfig(BaseModel):\n    """Configuration model for MyAdapter."""\n\n    api_token: str = Field(..., description="API token for the platform.")\n    webhook_url: str = Field(..., description="Webhook URL to listen on.")\n    timeout_seconds: int = Field(default=30, description="Request timeout.")\n'})}),"\n",(0,s.jsxs)(n.p,{children:["Set the ",(0,s.jsx)(n.code,{children:"ConfigModel"})," class attribute:"]}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-python",children:"from solace_agent_mesh.gateway.adapter.base import GatewayAdapter\n\nclass MyAdapter(GatewayAdapter):\n    ConfigModel = MyAdapterConfig\n"})}),"\n",(0,s.jsx)(n.h3,{id:"authentication-extract_auth_claims",children:"Authentication: extract_auth_claims()"}),"\n",(0,s.jsx)(n.p,{children:"Extract user identity from platform events:"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-python",children:'async def extract_auth_claims(\n    self,\n    external_input: Dict,\n    endpoint_context: Optional[Dict[str, Any]] = None,\n) -> Optional[AuthClaims]:\n    """\n    Extract authentication claims from platform input.\n\n    Return AuthClaims with user info, or None to use config-based auth.\n    """\n    user_id = external_input.get("user_id")\n    user_email = external_input.get("user_email")\n\n    if user_id and user_email:\n        return AuthClaims(\n            id=user_email,\n            email=user_email,\n            source="platform_api",\n            raw_context={"platform_user_id": user_id}\n        )\n\n    return None\n'})}),"\n",(0,s.jsx)(n.h3,{id:"inbound-prepare_task",children:"Inbound: prepare_task()"}),"\n",(0,s.jsx)(n.p,{children:"Convert platform events into standardized task format:"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-python",children:'async def prepare_task(\n    self,\n    external_input: Dict,\n    endpoint_context: Optional[Dict[str, Any]] = None,\n) -> SamTask:\n    """\n    Prepare a task from platform input.\n\n    This method is called after authentication succeeds. Convert your\n    platform\'s event format into a SamTask with parts.\n    """\n    message_text = external_input.get("message", "")\n    conversation_id = external_input.get("conversation_id")\n\n    # Create content parts\n    parts = [self.context.create_text_part(message_text)]\n\n    # Handle file attachments if present\n    if "attachments" in external_input:\n        for attachment in external_input["attachments"]:\n            file_bytes = await self._download_attachment(attachment)\n            parts.append(\n                self.context.create_file_part_from_bytes(\n                    name=attachment["filename"],\n                    content_bytes=file_bytes,\n                    mime_type=attachment["mime_type"]\n                )\n            )\n\n    return SamTask(\n        parts=parts,\n        session_id=conversation_id,\n        target_agent=self.context.config.get("default_agent_name", "default"),\n        platform_context={\n            "conversation_id": conversation_id,\n            # Store any platform-specific data needed for responses\n        }\n    )\n'})}),"\n",(0,s.jsx)(n.h3,{id:"outbound-handle_update",children:"Outbound: handle_update()"}),"\n",(0,s.jsx)(n.p,{children:"Process updates from agents and send them to your platform:"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-python",children:'async def handle_update(self, update: SamUpdate, context: ResponseContext) -> None:\n    """\n    Handle an update from the agent.\n\n    By default, this dispatches to individual part handlers.\n    Override for custom batch processing.\n    """\n    # Default implementation handles each part type\n    for part in update.parts:\n        if isinstance(part, SamTextPart):\n            await self.handle_text_chunk(part.text, context)\n        elif isinstance(part, SamFilePart):\n            await self.handle_file(part, context)\n        elif isinstance(part, SamDataPart):\n            await self.handle_data_part(part, context)\n'})}),"\n",(0,s.jsx)(n.p,{children:"Implement individual part handlers:"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-python",children:'async def handle_text_chunk(self, text: str, context: ResponseContext) -> None:\n    """Handle streaming text chunk from the agent."""\n    conversation_id = context.platform_context["conversation_id"]\n    await self.platform_api.send_message(conversation_id, text)\n\nasync def handle_file(self, file_part: SamFilePart, context: ResponseContext) -> None:\n    """Handle file/artifact from the agent."""\n    conversation_id = context.platform_context["conversation_id"]\n    await self.platform_api.upload_file(\n        conversation_id,\n        filename=file_part.name,\n        content=file_part.content_bytes\n    )\n\nasync def handle_data_part(self, data_part: SamDataPart, context: ResponseContext) -> None:\n    """Handle structured data part from the agent."""\n    # Check for special data part types\n    if data_part.data.get("type") == "agent_progress_update":\n        status_text = data_part.data.get("status_text")\n        if status_text:\n            await self.handle_status_update(status_text, context)\n\nasync def handle_status_update(self, status_text: str, context: ResponseContext) -> None:\n    """Handle agent status update (progress indicator)."""\n    conversation_id = context.platform_context["conversation_id"]\n    await self.platform_api.update_status(conversation_id, status_text)\n'})}),"\n",(0,s.jsx)(n.h3,{id:"completion-handle_task_complete",children:"Completion: handle_task_complete()"}),"\n",(0,s.jsx)(n.p,{children:"Handle task completion notification:"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-python",children:'async def handle_task_complete(self, context: ResponseContext) -> None:\n    """Handle task completion notification."""\n    conversation_id = context.platform_context["conversation_id"]\n    await self.platform_api.send_message(\n        conversation_id,\n        "\u2705 Task complete."\n    )\n'})}),"\n",(0,s.jsx)(n.h3,{id:"error-handling-handle_error",children:"Error Handling: handle_error()"}),"\n",(0,s.jsx)(n.p,{children:"Handle errors from the agent or gateway:"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-python",children:'async def handle_error(self, error: SamError, context: ResponseContext) -> None:\n    """Handle error from the agent or gateway."""\n    conversation_id = context.platform_context.get("conversation_id")\n\n    if error.category == "CANCELED":\n        error_message = "\ud83d\uded1 Task canceled."\n    else:\n        error_message = f"\u274c Error: {error.message}"\n\n    if conversation_id:\n        await self.platform_api.send_message(conversation_id, error_message)\n'})}),"\n",(0,s.jsx)(n.h2,{id:"gateway-context-services",children:"Gateway Context Services"}),"\n",(0,s.jsxs)(n.p,{children:["The ",(0,s.jsx)(n.code,{children:"GatewayContext"})," provides access to framework services:"]}),"\n",(0,s.jsx)(n.h3,{id:"task-management",children:"Task Management"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-python",children:'# Submit a new task to the agent mesh\ntask_id = await self.context.handle_external_input(\n    external_input=platform_event,\n    endpoint_context={"source": "webhook"}\n)\n\n# Cancel an in-flight task\nawait self.context.cancel_task(task_id)\n'})}),"\n",(0,s.jsx)(n.h3,{id:"artifact-management",children:"Artifact Management"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-python",children:'# Load artifact content\ncontent_bytes = await self.context.load_artifact_content(\n    context=response_context,\n    filename="report.pdf",\n    version="latest"\n)\n\n# List available artifacts\nartifacts = await self.context.list_artifacts(response_context)\nfor artifact in artifacts:\n    print(f"{artifact.filename}: {artifact.version}")\n'})}),"\n",(0,s.jsx)(n.h3,{id:"feedback-collection",children:"Feedback Collection"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-python",children:'# Submit user feedback\nfeedback = SamFeedback(\n    task_id=task_id,\n    session_id=session_id,\n    rating="up",  # or "down"\n    comment="Great response!",\n    user_id=user_id\n)\nawait self.context.submit_feedback(feedback)\n'})}),"\n",(0,s.jsx)(n.h3,{id:"state-management",children:"State Management"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-python",children:'# Task-level state (expires after 1 hour)\nself.context.set_task_state(task_id, "status_message_id", message_id)\nmessage_id = self.context.get_task_state(task_id, "status_message_id")\n\n# Session-level state (expires after 24 hours)\nself.context.set_session_state(session_id, "user_preferences", preferences)\npreferences = self.context.get_session_state(session_id, "user_preferences")\n'})}),"\n",(0,s.jsx)(n.h3,{id:"timer-management",children:"Timer Management"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-python",children:"# Schedule a one-time callback\ntimer_id = self.context.add_timer(\n    delay_ms=5000,\n    callback=self.my_async_callback\n)\n\n# Schedule a recurring callback\ntimer_id = self.context.add_timer(\n    delay_ms=1000,\n    callback=self.my_async_callback,\n    interval_ms=1000\n)\n\n# Cancel a timer\nself.context.cancel_timer(timer_id)\n"})}),"\n",(0,s.jsx)(n.h2,{id:"configuration",children:"Configuration"}),"\n",(0,s.jsx)(n.p,{children:"Configure a gateway adapter in your YAML file:"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-yaml",children:'apps:\n  - name: my_gateway_app\n    app_base_path: .\n    app_module: solace_agent_mesh.gateway.generic.app\n\n    broker:\n      # Broker connection configuration\n      <<: *broker_connection\n\n    app_config:\n      # Required: namespace for A2A topics\n      namespace: ${NAMESPACE}\n\n      # Required: path to your adapter class\n      gateway_adapter: my_package.adapters.MyAdapter\n\n      # Adapter-specific configuration\n      adapter_config:\n        api_token: ${MY_PLATFORM_API_TOKEN}\n        webhook_url: ${WEBHOOK_URL}\n        timeout_seconds: 30\n\n      # Standard gateway configuration\n      default_agent_name: OrchestratorAgent\n\n      # Artifact service configuration\n      artifact_service:\n        type: "filesystem"\n        base_path: "/tmp/artifacts"\n        artifact_scope: "namespace"\n\n      # System purpose and response format\n      system_purpose: >\n        The system is an AI assistant that helps users\n        accomplish tasks through natural language interaction.\n\n      response_format: >\n        Responses should be clear, concise, and formatted\n        appropriately for the platform.\n'})}),"\n",(0,s.jsx)(n.h2,{id:"example-slack-adapter",children:"Example: Slack Adapter"}),"\n",(0,s.jsx)(n.p,{children:"The Slack gateway adapter demonstrates a complete implementation of the adapter pattern. It handles:"}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Socket Mode Connection"}),": Maintains WebSocket connection to Slack"]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Event Handling"}),": Processes messages, mentions, slash commands, and button actions"]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Message Queuing"}),": Manages streaming updates with proper ordering"]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"File Uploads"}),": Handles artifact uploads to Slack"]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Markdown Conversion"}),": Converts standard Markdown to Slack format"]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Feedback Collection"}),": Provides thumbs up/down buttons for user feedback"]}),"\n"]}),"\n",(0,s.jsx)(n.p,{children:"Key highlights from the Slack adapter implementation:"}),"\n",(0,s.jsx)(n.h3,{id:"configuration-model",children:"Configuration Model"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-python",children:'class SlackAdapterConfig(BaseModel):\n    slack_bot_token: str = Field(..., description="Slack Bot Token (xoxb-...).")\n    slack_app_token: str = Field(..., description="Slack App Token (xapp-...).")\n    slack_initial_status_message: str = Field(\n        "Got it, thinking...",\n        description="Message posted to Slack upon receiving a user request."\n    )\n    correct_markdown_formatting: bool = Field(\n        True,\n        description="Attempt to convert common Markdown to Slack\'s format."\n    )\n    feedback_enabled: bool = Field(\n        False,\n        description="Enable thumbs up/down feedback buttons."\n    )\n'})}),"\n",(0,s.jsx)(n.h3,{id:"authentication-with-caching",children:"Authentication with Caching"}),"\n",(0,s.jsx)(n.p,{children:"The Slack adapter extracts user email from Slack's API and caches the results:"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-python",children:'async def extract_auth_claims(\n    self,\n    external_input: Dict,\n    endpoint_context: Optional[Dict[str, Any]] = None,\n) -> Optional[AuthClaims]:\n    slack_user_id = external_input.get("user")\n\n    # Check cache first\n    if cached_email := self.get_cached_email(slack_user_id):\n        return AuthClaims(id=cached_email, email=cached_email, source="slack_api")\n\n    # Fetch from Slack API\n    profile = await self.slack_app.client.users_profile_get(user=slack_user_id)\n    user_email = profile.get("profile", {}).get("email")\n\n    if user_email:\n        self.cache_email(slack_user_id, user_email)\n        return AuthClaims(id=user_email, email=user_email, source="slack_api")\n'})}),"\n",(0,s.jsx)(n.h3,{id:"streaming-updates-with-message-queue",children:"Streaming Updates with Message Queue"}),"\n",(0,s.jsx)(n.p,{children:"The Slack adapter uses a message queue to handle streaming updates efficiently:"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-python",children:"async def handle_update(self, update: SamUpdate, context: ResponseContext) -> None:\n    task_id = context.task_id\n    queue = await self._get_or_create_queue(task_id, channel_id, thread_ts)\n\n    for part in update.parts:\n        if isinstance(part, SamTextPart):\n            await queue.queue_text_update(part.text)\n        elif isinstance(part, SamFilePart):\n            await queue.queue_file_upload(part.name, part.content_bytes)\n"})}),"\n",(0,s.jsxs)(n.p,{children:["For the complete Slack adapter implementation, see ",(0,s.jsx)(n.code,{children:"src/solace_agent_mesh/gateway/slack/adapter.py"}),"."]}),"\n",(0,s.jsx)(n.h2,{id:"creating-your-own-adapter",children:"Creating Your Own Adapter"}),"\n",(0,s.jsx)(n.h3,{id:"option-1-create-as-a-plugin-recommended",children:"Option 1: Create as a Plugin (Recommended)"}),"\n",(0,s.jsx)(n.p,{children:"For reusable adapters that you plan to share or use across multiple projects:"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-bash",children:"sam plugin create my-gateway-plugin\n"})}),"\n",(0,s.jsx)(n.p,{children:'Select "Gateway Plugin" when prompted. This creates a complete plugin structure with:'}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsx)(n.li,{children:"Python package structure"}),"\n",(0,s.jsx)(n.li,{children:"Sample adapter implementation"}),"\n",(0,s.jsx)(n.li,{children:"Configuration template"}),"\n",(0,s.jsx)(n.li,{children:"Build tooling"}),"\n"]}),"\n",(0,s.jsx)(n.p,{children:"After implementing your adapter, build and distribute:"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-bash",children:"cd my-gateway-plugin\nsam plugin build\n"})}),"\n",(0,s.jsxs)(n.p,{children:["For more information on plugins, see ",(0,s.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/components/plugins",children:"Plugins"}),"."]}),"\n",(0,s.jsx)(n.h3,{id:"option-2-add-to-existing-project",children:"Option 2: Add to Existing Project"}),"\n",(0,s.jsx)(n.p,{children:"For project-specific adapters, create your adapter class in your project:"}),"\n",(0,s.jsxs)(n.ol,{children:["\n",(0,s.jsx)(n.li,{children:"Create your adapter module:"}),"\n"]}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-python",children:"# my_project/gateways/my_adapter.py\nfrom solace_agent_mesh.gateway.adapter.base import GatewayAdapter\nfrom solace_agent_mesh.gateway.adapter.types import (\n    AuthClaims,\n    GatewayContext,\n    ResponseContext,\n    SamTask,\n    SamUpdate\n)\n\nclass MyAdapter(GatewayAdapter):\n    async def init(self, context: GatewayContext) -> None:\n        self.context = context\n        # Initialize your platform connection\n\n    async def prepare_task(self, external_input, endpoint_context=None) -> SamTask:\n        # Convert platform event to SamTask\n        pass\n\n    async def handle_update(self, update: SamUpdate, context: ResponseContext) -> None:\n        # Send update to platform\n        pass\n"})}),"\n",(0,s.jsxs)(n.ol,{start:"2",children:["\n",(0,s.jsx)(n.li,{children:"Reference it in your configuration:"}),"\n"]}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-yaml",children:"app_config:\n  gateway_adapter: my_project.gateways.my_adapter.MyAdapter\n  adapter_config:\n    # Your adapter configuration\n"})}),"\n",(0,s.jsx)(n.h2,{id:"advanced-full-custom-gateways",children:"Advanced: Full Custom Gateways"}),"\n",(0,s.jsx)(n.p,{children:"For most use cases, gateway adapters provide all the functionality you need to connect external platforms to the agent mesh. However, if you have highly specialized requirements, you can create a full custom gateway that implements the complete gateway lifecycle and A2A protocol handling from scratch."}),"\n",(0,s.jsx)(n.p,{children:"Consider a full custom gateway only if you need:"}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsx)(n.li,{children:"Highly specialized authentication flows not supported by the standard flow"}),"\n",(0,s.jsx)(n.li,{children:"Custom A2A protocol behavior or extensions"}),"\n",(0,s.jsx)(n.li,{children:"Complex multi-stage processing pipelines with custom state management"}),"\n",(0,s.jsx)(n.li,{children:"Fine-grained control over every aspect of the gateway lifecycle"}),"\n"]}),"\n",(0,s.jsxs)(n.p,{children:["Full custom gateways extend ",(0,s.jsx)(n.code,{children:"BaseGatewayComponent"})," directly and implement all protocol handling manually. This approach requires significantly more code and expertise but provides complete control over the gateway behavior."]}),"\n",(0,s.jsx)(n.h2,{id:"related-documentation",children:"Related Documentation"}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/components/gateways",children:"Gateways"})," - Overview of gateway concepts and types"]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/components/plugins",children:"Plugins"})," - Creating and distributing gateway plugins"]}),"\n"]})]})}function p(e={}){const{wrapper:n}={...(0,r.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:()=>i,x:()=>o});var a=t(6540);const s={},r=a.createContext(s);function i(e){const n=a.useContext(r);return a.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(s):e.components||s:i(e.components),a.createElement(r.Provider,{value:n},e.children)}}}]);

solace_agent_mesh/assets/docs/assets/js/db5d6442.3daf1696.js

@@ -0,0 +1 @@
+"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[4262],{1148:(e,n,t)=>{t.r(n),t.d(n,{assets:()=>l,contentTitle:()=>a,default:()=>d,frontMatter:()=>r,metadata:()=>s,toc:()=>c});const s=JSON.parse('{"id":"documentation/deploying/kubernetes-deployment","title":"Kubernetes","description":"You can deploy Agent Mesh to Kubernetes using Helm charts, which handle the complexity of creating and configuring Kubernetes resources such as deployments, services, persistent volumes, and configuration management.","source":"@site/docs/documentation/deploying/kubernetes-deployment.md","sourceDirName":"documentation/deploying","slug":"/documentation/deploying/kubernetes-deployment","permalink":"/solace-agent-mesh/docs/documentation/deploying/kubernetes-deployment","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/deploying/kubernetes-deployment.md","tags":[],"version":"current","sidebarPosition":11,"frontMatter":{"title":"Kubernetes","sidebar_position":11},"sidebar":"docSidebar","previous":{"title":"Choosing Deployment Options","permalink":"/solace-agent-mesh/docs/documentation/deploying/deployment-options"},"next":{"title":"Monitoring Your Agent Mesh","permalink":"/solace-agent-mesh/docs/documentation/deploying/observability"}}');var o=t(4848),i=t(8453);const r={title:"Kubernetes",sidebar_position:11},a="Deploying Agent Mesh to Kubernetes",l={},c=[{value:"Prerequisites",id:"prerequisites",level:2},{value:"Understanding Kubernetes Deployment",id:"understanding-kubernetes-deployment",level:2},{value:"Using the Helm Quickstart",id:"using-the-helm-quickstart",level:2},{value:"Kubernetes Deployment Architecture",id:"kubernetes-deployment-architecture",level:2},{value:"Configuring for Kubernetes",id:"configuring-for-kubernetes",level:2},{value:"Queue Configuration",id:"queue-configuration",level:3},{value:"Secrets Management",id:"secrets-management",level:3},{value:"Storage",id:"storage",level:3},{value:"Resource Limits",id:"resource-limits",level:3}];function u(e){const n={a:"a",code:"code",h1:"h1",h2:"h2",h3:"h3",header:"header",li:"li",p:"p",pre:"pre",ul:"ul",...(0,i.R)(),...e.components};return(0,o.jsxs)(o.Fragment,{children:[(0,o.jsx)(n.header,{children:(0,o.jsx)(n.h1,{id:"deploying-agent-mesh-to-kubernetes",children:"Deploying Agent Mesh to Kubernetes"})}),"\n",(0,o.jsx)(n.p,{children:"You can deploy Agent Mesh to Kubernetes using Helm charts, which handle the complexity of creating and configuring Kubernetes resources such as deployments, services, persistent volumes, and configuration management."}),"\n",(0,o.jsx)(n.h2,{id:"prerequisites",children:"Prerequisites"}),"\n",(0,o.jsx)(n.p,{children:"To deploy Agent Mesh to Kubernetes, you need:"}),"\n",(0,o.jsxs)(n.ul,{children:["\n",(0,o.jsx)(n.li,{children:"A running Kubernetes cluster (version 1.20 or later)"}),"\n",(0,o.jsxs)(n.li,{children:["The ",(0,o.jsx)(n.code,{children:"kubectl"})," command-line tool configured to access your cluster"]}),"\n",(0,o.jsx)(n.li,{children:"Helm installed on your system (version 3.0 or later)"}),"\n",(0,o.jsx)(n.li,{children:"Container registry credentials (if you use private registries)"}),"\n",(0,o.jsx)(n.li,{children:"Solace broker credentials or Solace Cloud connection details"}),"\n"]}),"\n",(0,o.jsx)(n.h2,{id:"understanding-kubernetes-deployment",children:"Understanding Kubernetes Deployment"}),"\n",(0,o.jsx)(n.p,{children:"The deployment process involves adding the Helm chart repository, customizing values for your environment, and deploying Agent Mesh to your cluster. The Helm charts simplify this process compared to manually managing individual YAML manifests."}),"\n",(0,o.jsx)(n.h2,{id:"using-the-helm-quickstart",children:"Using the Helm Quickstart"}),"\n",(0,o.jsx)(n.p,{children:"The Solace Agent Mesh Helm quickstart includes pre-configured Helm values, deployment examples, and detailed documentation for common deployment scenarios."}),"\n",(0,o.jsxs)(n.p,{children:["For the quickstart repository and installation files, see ",(0,o.jsx)(n.a,{href:"https://github.com/SolaceProducts/solace-agent-mesh-helm-quickstart",children:"solace-agent-mesh-helm-quickstart"}),"."]}),"\n",(0,o.jsxs)(n.p,{children:["For step-by-step deployment instructions, see the ",(0,o.jsx)(n.a,{href:"https://solaceproducts.github.io/solace-agent-mesh-helm-quickstart/docs-site/",children:"Helm Deployment Guide"}),"."]}),"\n",(0,o.jsx)(n.h2,{id:"kubernetes-deployment-architecture",children:"Kubernetes Deployment Architecture"}),"\n",(0,o.jsx)(n.p,{children:"You can deploy Agent Mesh as a single monolithic deployment or as multiple specialized deployments that scale independently. The Helm charts support both patterns based on your scale requirements and operational preferences."}),"\n",(0,o.jsx)(n.p,{children:"When you deploy multiple components as separate deployments, each component runs independently and communicates through the Solace event broker. This approach provides better fault isolation and allows you to scale specific components based on demand. All components must connect to the same Solace broker and use consistent storage configurations to maintain system coherence."}),"\n",(0,o.jsx)(n.h2,{id:"configuring-for-kubernetes",children:"Configuring for Kubernetes"}),"\n",(0,o.jsx)(n.p,{children:"Several configuration considerations apply specifically to Kubernetes deployments."}),"\n",(0,o.jsx)(n.h3,{id:"queue-configuration",children:"Queue Configuration"}),"\n",(0,o.jsx)(n.p,{children:"For Kubernetes environments with container restarts, you should configure Agent Mesh to use durable queues instead of temporary queues. Set the environment variable:"}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-bash",children:"USE_TEMPORARY_QUEUES=false\n"})}),"\n",(0,o.jsxs)(n.p,{children:["This configuration ensures that messages persist even when pods restart and allows multiple instances to connect to the same queue. For detailed queue configuration guidance, including Queue Template setup in Solace Cloud, see ",(0,o.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/deploying/deployment-options#setting-up-queue-templates",children:"Choosing Deployment Options"}),"."]}),"\n",(0,o.jsx)(n.h3,{id:"secrets-management",children:"Secrets Management"}),"\n",(0,o.jsx)(n.p,{children:"You should use Kubernetes Secrets to store sensitive information such as API keys, broker credentials, and authentication tokens. Never embed these values in container images or configuration files."}),"\n",(0,o.jsx)(n.h3,{id:"storage",children:"Storage"}),"\n",(0,o.jsx)(n.p,{children:"If you run multiple pod replicas, ensure all instances access the same persistent storage with identical configurations. Inconsistent storage across instances can cause data synchronization issues."}),"\n",(0,o.jsx)(n.h3,{id:"resource-limits",children:"Resource Limits"}),"\n",(0,o.jsx)(n.p,{children:"You should define resource requests and limits for your containers to ensure stable operation and enable effective autoscaling. The Helm quickstart includes recommended resource configurations."})]})}function d(e={}){const{wrapper:n}={...(0,i.R)(),...e.components};return n?(0,o.jsx)(n,{...e,children:(0,o.jsx)(u,{...e})}):u(e)}},8453:(e,n,t)=>{t.d(n,{R:()=>r,x:()=>a});var s=t(6540);const o={},i=s.createContext(o);function r(e){const n=s.useContext(i);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(o):e.components||o:r(e.components),s.createElement(i.Provider,{value:n},e.children)}}}]);

solace_agent_mesh/assets/docs/assets/js/db924877.e98d12a1.js

@@ -0,0 +1 @@
+"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[9066],{7517:(e,n,r)=>{r.r(n),r.d(n,{assets:()=>c,contentTitle:()=>d,default:()=>h,frontMatter:()=>o,metadata:()=>i,toc:()=>l});const i=JSON.parse('{"id":"documentation/developing/creating-service-providers","title":"Creating Service Providers","description":"This guide details the process for developers to create service provider plugins for integrating backend systems (for example, HR platforms, CRMs) with Agent Mesh.","source":"@site/docs/documentation/developing/creating-service-providers.md","sourceDirName":"documentation/developing","slug":"/documentation/developing/creating-service-providers","permalink":"/solace-agent-mesh/docs/documentation/developing/creating-service-providers","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/developing/creating-service-providers.md","tags":[],"version":"current","sidebarPosition":450,"frontMatter":{"title":"Creating Service Providers","sidebar_position":450},"sidebar":"docSidebar","previous":{"title":"Creating Python Tools","permalink":"/solace-agent-mesh/docs/documentation/developing/creating-python-tools"},"next":{"title":"Evaluating Agents","permalink":"/solace-agent-mesh/docs/documentation/developing/evaluations"}}');var t=r(4848),s=r(8453);const o={title:"Creating Service Providers",sidebar_position:450},d="Creating Service Providers",c={},l=[{value:"Understanding Service Providers",id:"understanding-service-providers",level:2},{value:"The "Dual-Role Provider" Pattern",id:"the-dual-role-provider-pattern",level:2},{value:"Step-by-Step Implementation Guide",id:"step-by-step-implementation-guide",level:2},{value:"Step 1: Establish the Plugin Structure",id:"step-1-establish-the-plugin-structure",level:3},{value:"Step 2: Define the Provider Class",id:"step-2-define-the-provider-class",level:3},{value:"Step 3: Map to the Canonical Employee Schema",id:"step-3-map-to-the-canonical-employee-schema",level:3},{value:"Step 4: Register the Plugin",id:"step-4-register-the-plugin",level:3},{value:"Configuring the Provider",id:"configuring-the-provider",level:2}];function a(e){const n={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,s.R)(),...e.components};return(0,t.jsxs)(t.Fragment,{children:[(0,t.jsx)(n.header,{children:(0,t.jsx)(n.h1,{id:"creating-service-providers",children:"Creating Service Providers"})}),"\n",(0,t.jsx)(n.p,{children:"This guide details the process for developers to create service provider plugins for integrating backend systems (for example, HR platforms, CRMs) with Agent Mesh."}),"\n",(0,t.jsx)(n.h2,{id:"understanding-service-providers",children:"Understanding Service Providers"}),"\n",(0,t.jsx)(n.p,{children:"Service Providers function as the abstraction layer between Agent Mesh and enterprise data sources. They are implemented as Python classes that adhere to a specific abstract base class, enabling standardized interaction between Agent Mesh components (Gateways and Agents) and the underlying data."}),"\n",(0,t.jsx)(n.p,{children:"There are two primary service provider interfaces:"}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:(0,t.jsx)(n.code,{children:"BaseIdentityService"})}),": Responsible for ",(0,t.jsx)(n.strong,{children:"identity enrichment"}),". This service is utilized by Gateways to augment the profile of an authenticated user with additional details (for example, full name, job title) based on their initial authentication claims."]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:(0,t.jsx)(n.code,{children:"BaseEmployeeService"})}),": Responsible for ",(0,t.jsx)(n.strong,{children:"general directory querying"}),". This service is utilized by agents (for example, the ",(0,t.jsx)(n.code,{children:"EmployeeAgent"}),") to execute lookups across the entire employee directory."]}),"\n"]}),"\n",(0,t.jsx)(n.h2,{id:"the-dual-role-provider-pattern",children:'The "Dual-Role Provider" Pattern'}),"\n",(0,t.jsx)(n.p,{children:'In many enterprise systems, particularly HR platforms, the data source for identity enrichment and general employee queries is identical. To optimize development, Agent Mesh promotes a "Dual-Role Provider" pattern.'}),"\n",(0,t.jsxs)(n.p,{children:["This pattern involves creating a single class that inherits from both ",(0,t.jsx)(n.code,{children:"BaseIdentityService"})," and ",(0,t.jsx)(n.code,{children:"BaseEmployeeService"}),". This consolidated class can then be configured to fulfill either or both roles, thereby reducing code duplication."]}),"\n",(0,t.jsx)(n.h2,{id:"step-by-step-implementation-guide",children:"Step-by-Step Implementation Guide"}),"\n",(0,t.jsx)(n.p,{children:'This section provides a walkthrough for creating a new provider for a fictional "CorpHR" system.'}),"\n",(0,t.jsx)(n.h3,{id:"step-1-establish-the-plugin-structure",children:"Step 1: Establish the Plugin Structure"}),"\n",(0,t.jsxs)(n.p,{children:["The recommended structure for a custom service provider plugin should include a ",(0,t.jsx)(n.code,{children:"pyproject.toml"})," for packaging and a ",(0,t.jsx)(n.code,{children:"src"})," directory for the source code."]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-bash",children:"sam plugin create my_corp_hr_provider --type custom\n"})}),"\n",(0,t.jsx)(n.h3,{id:"step-2-define-the-provider-class",children:"Step 2: Define the Provider Class"}),"\n",(0,t.jsxs)(n.p,{children:["Create a ",(0,t.jsx)(n.code,{children:"provider.py"})," module and define the provider class, ensuring it inherits from both base service classes."]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-python",children:'# my_corp_hr_provider/provider.py\n\n# Import base classes from the Agent Mesh framework\ntry:\n    from solace_agent_mesh.common.services.identity_service import BaseIdentityService\n    from solace_agent_mesh.common.services.employee_service import BaseEmployeeService\nexcept ImportError:\n    # Fallback for local development environments\n    from src.solace_agent_mesh.common.services.identity_service import BaseIdentityService\n    from src.solace_agent_mesh.common.services.employee_service import BaseEmployeeService\n\n# Import any other necessary libraries, such as \'requests\' or a proprietary SDK\n# from .corp_hr_sdk import CorpHR_SDK\n\nclass CorpHRProvider(BaseIdentityService, BaseEmployeeService):\n    """\n    A dual-role provider for the CorpHR system, implementing methods\n    for both identity enrichment and employee directory services.\n    """\n    def __init__(self, config):\n        super().__init__(config)\n        # Initialize the backend service/SDK client here.\n        # It is best practice to implement this as a singleton to share\n        # connection pools and cache.\n        # self.corp_hr_sdk = CorpHR_SDK(api_key=config.get("api_key"))\n\n    # --- BaseIdentityService Method Implementations ---\n\n    async def get_user_profile(self, auth_claims):\n        """Enrich the current user\'s profile based on their auth claims."""\n        # TODO: Implement logic to fetch user data from CorpHR\n        pass\n\n    async def search_users(self, query, limit=10):\n        """Search for users, for features like @-mentions."""\n        # TODO: Implement user search logic against CorpHR\n        pass\n\n    # --- BaseEmployeeService Method Implementations ---\n\n    async def get_employee_dataframe(self):\n        """Return all employees as a pandas DataFrame for directory-wide queries."""\n        # TODO: Fetch all employee data and return as a DataFrame\n        pass\n\n    async def get_employee_profile(self, employee_id):\n        """Get a single employee\'s full profile by their ID."""\n        # Note: This is a general directory lookup, distinct from get_user_profile.\n        # TODO: Implement single employee lookup\n        pass\n\n    async def get_time_off_data(self, employee_id):\n        """Get an employee\'s raw time off data."""\n        # Example return format:\n        # return [{\'start\': \'2025-07-04\', \'end\': \'2025-07-04\', \'type\': \'Holiday\'}]\n        # TODO: Implement time off data retrieval\n        pass\n\n    async def get_employee_profile_picture(self, employee_id):\n        """Fetch a profile picture as a data URI string."""\n        # Example return format: "data:image/jpeg;base64,..."\n        # TODO: Implement profile picture fetching\n        pass\n'})}),"\n",(0,t.jsx)(n.h3,{id:"step-3-map-to-the-canonical-employee-schema",children:"Step 3: Map to the Canonical Employee Schema"}),"\n",(0,t.jsxs)(n.p,{children:["When implementing the service methods, it is ",(0,t.jsx)(n.strong,{children:"mandatory"})," to map the data from the source system to the ",(0,t.jsx)(n.strong,{children:"canonical employee schema"})," of Agent Mesh. This ensures data consistency and interoperability with all tools and components across the mesh."]}),"\n",(0,t.jsxs)(n.table,{children:[(0,t.jsx)(n.thead,{children:(0,t.jsxs)(n.tr,{children:[(0,t.jsx)(n.th,{children:"Field Name"}),(0,t.jsx)(n.th,{children:"Data Type"}),(0,t.jsx)(n.th,{children:"Description"})]})}),(0,t.jsxs)(n.tbody,{children:[(0,t.jsxs)(n.tr,{children:[(0,t.jsx)(n.td,{children:(0,t.jsx)(n.code,{children:"id"})}),(0,t.jsx)(n.td,{children:(0,t.jsx)(n.code,{children:"string"})}),(0,t.jsxs)(n.td,{children:["A unique, stable, and ",(0,t.jsx)(n.strong,{children:"lowercase"})," identifier (e.g., email, GUID)."]})]}),(0,t.jsxs)(n.tr,{children:[(0,t.jsx)(n.td,{children:(0,t.jsx)(n.code,{children:"displayName"})}),(0,t.jsx)(n.td,{children:(0,t.jsx)(n.code,{children:"string"})}),(0,t.jsx)(n.td,{children:"The employee's full name for display purposes."})]}),(0,t.jsxs)(n.tr,{children:[(0,t.jsx)(n.td,{children:(0,t.jsx)(n.code,{children:"workEmail"})}),(0,t.jsx)(n.td,{children:(0,t.jsx)(n.code,{children:"string"})}),(0,t.jsx)(n.td,{children:"The employee's primary work email address."})]}),(0,t.jsxs)(n.tr,{children:[(0,t.jsx)(n.td,{children:(0,t.jsx)(n.code,{children:"jobTitle"})}),(0,t.jsx)(n.td,{children:(0,t.jsx)(n.code,{children:"string"})}),(0,t.jsx)(n.td,{children:"The employee's official job title."})]}),(0,t.jsxs)(n.tr,{children:[(0,t.jsx)(n.td,{children:(0,t.jsx)(n.code,{children:"department"})}),(0,t.jsx)(n.td,{children:(0,t.jsx)(n.code,{children:"string"})}),(0,t.jsx)(n.td,{children:"The department to which the employee belongs."})]}),(0,t.jsxs)(n.tr,{children:[(0,t.jsx)(n.td,{children:(0,t.jsx)(n.code,{children:"location"})}),(0,t.jsx)(n.td,{children:(0,t.jsx)(n.code,{children:"string"})}),(0,t.jsx)(n.td,{children:"The physical or regional location of the employee."})]}),(0,t.jsxs)(n.tr,{children:[(0,t.jsx)(n.td,{children:(0,t.jsx)(n.code,{children:"supervisorId"})}),(0,t.jsx)(n.td,{children:(0,t.jsx)(n.code,{children:"string"})}),(0,t.jsxs)(n.td,{children:["The unique ",(0,t.jsx)(n.code,{children:"id"})," of the employee's direct manager."]})]}),(0,t.jsxs)(n.tr,{children:[(0,t.jsx)(n.td,{children:(0,t.jsx)(n.code,{children:"hireDate"})}),(0,t.jsx)(n.td,{children:(0,t.jsx)(n.code,{children:"string"})}),(0,t.jsxs)(n.td,{children:["The date the employee was hired (ISO 8601: ",(0,t.jsx)(n.code,{children:"YYYY-MM-DD"}),")."]})]}),(0,t.jsxs)(n.tr,{children:[(0,t.jsx)(n.td,{children:(0,t.jsx)(n.code,{children:"mobilePhone"})}),(0,t.jsx)(n.td,{children:(0,t.jsx)(n.code,{children:"string"})}),(0,t.jsx)(n.td,{children:"The employee's mobile phone number (optional)."})]})]})]}),"\n",(0,t.jsx)(n.admonition,{type:"info",children:(0,t.jsxs)(n.p,{children:["If a field is not available in the source system, return ",(0,t.jsx)(n.code,{children:"None"})," or omit the key from the returned dictionary."]})}),"\n",(0,t.jsx)(n.h3,{id:"step-4-register-the-plugin",children:"Step 4: Register the Plugin"}),"\n",(0,t.jsx)(n.p,{children:"To make the provider discoverable by Agent Mesh, it must be registered as a plugin via entry points."}),"\n",(0,t.jsxs)(n.p,{children:[(0,t.jsxs)(n.strong,{children:["1. Add an entry point in ",(0,t.jsx)(n.code,{children:"pyproject.toml"}),":"]}),"\nThe key assigned here (",(0,t.jsx)(n.code,{children:"corphr"}),") is used as the ",(0,t.jsx)(n.code,{children:"type"})," identifier in YAML configurations."]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-toml",children:'[project.entry-points."solace_agent_mesh.plugins"]\ncorphr = "my_corp_hr_provider:info"\n'})}),"\n",(0,t.jsxs)(n.p,{children:[(0,t.jsxs)(n.strong,{children:["2. Define the ",(0,t.jsx)(n.code,{children:"info"})," object in the plugin's ",(0,t.jsx)(n.code,{children:"__init__.py"}),":"]}),"\nThis object points to the provider's class path and provides a brief description."]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-python",children:'# my_corp_hr_provider/__init__.py\ninfo = {\n    "class_path": "my_corp_hr_provider.provider.CorpHRProvider",\n    "description": "Identity and People Service provider for CorpHR.",\n}\n'})}),"\n",(0,t.jsx)(n.h2,{id:"configuring-the-provider",children:"Configuring the Provider"}),"\n",(0,t.jsxs)(n.p,{children:["Once the plugin is created and installed (for example, via ",(0,t.jsx)(n.code,{children:"pip install ."}),"), it can be configured in any Gateway or Agent ",(0,t.jsx)(n.code,{children:"app_config.yml"}),"."]}),"\n",(0,t.jsx)(n.p,{children:(0,t.jsx)(n.strong,{children:"For a Gateway (Identity Service Role):"})}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-yaml",children:'app_config:\n  identity_service:\n    type: "corphr" # Matches the key in pyproject.toml\n    api_key: "${CORPHR_API_KEY}"\n    lookup_key: "email" # The field from auth_claims to use for lookup\n'})}),"\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"For an Agent (Employee Service Role):"}),"\nThis example demonstrates configuring the provider for the ",(0,t.jsx)(n.code,{children:"employee_tools"})," group."]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-yaml",children:'app_config:\n  tools:\n    - tool_type: builtin-group\n      group_name: "employee_tools"\n      config:\n        type: "corphr" # Same provider, different role\n        api_key: "${CORPHR_API_KEY}"\n'})})]})}function h(e={}){const{wrapper:n}={...(0,s.R)(),...e.components};return n?(0,t.jsx)(n,{...e,children:(0,t.jsx)(a,{...e})}):a(e)}},8453:(e,n,r)=>{r.d(n,{R:()=>o,x:()=>d});var i=r(6540);const t={},s=i.createContext(t);function o(e){const n=i.useContext(s);return i.useMemo((function(){return"function"==typeof e?e(n):{...n,...e}}),[n,e])}function d(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(t):e.components||t:o(e.components),i.createElement(s.Provider,{value:n},e.children)}}}]);

solace_agent_mesh/assets/docs/assets/js/dd817ffc.c37a755e.js

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