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

solace_agent_mesh/assets/docs/assets/js/04989206.a248f00c.js

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

solace_agent_mesh/assets/docs/assets/js/0e682baa.d54b8668.js

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

solace_agent_mesh/assets/docs/assets/js/1023fc19.8a8a9309.js

@@ -1 +0,0 @@
-"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[1462],{3519:(e,n,t)=>{t.r(n),t.d(n,{assets:()=>l,contentTitle:()=>o,default:()=>h,frontMatter:()=>a,metadata:()=>i,toc:()=>d});const i=JSON.parse('{"id":"documentation/user-guide/builtin-tools/data-analysis-tools","title":"Data Analysis Tools","description":"Solace Agent Mesh includes a suite of optional built-in tools that enable agents to perform data analysis tasks directly on artifacts. These tools provide functionality for SQL querying, JQ transformations, and Plotly chart generation.","source":"@site/docs/documentation/user-guide/builtin-tools/data-analysis-tools.md","sourceDirName":"documentation/user-guide/builtin-tools","slug":"/documentation/user-guide/builtin-tools/data-analysis-tools","permalink":"/solace-agent-mesh/docs/documentation/user-guide/builtin-tools/data-analysis-tools","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/user-guide/builtin-tools/data-analysis-tools.md","tags":[],"version":"current","sidebarPosition":20,"frontMatter":{"title":"Data Analysis Tools","sidebar_position":20},"sidebar":"docSidebar","previous":{"title":"Artifact Management Tools","permalink":"/solace-agent-mesh/docs/documentation/user-guide/builtin-tools/artifact-management"},"next":{"title":"Audio Tools","permalink":"/solace-agent-mesh/docs/documentation/user-guide/builtin-tools/audio-tools"}}');var s=t(4848),r=t(8453);const a={title:"Data Analysis Tools",sidebar_position:20},o="Data Analysis Tools",l={},d=[{value:"Setup and Configuration",id:"setup-and-configuration",level:2},{value:"Available Tools",id:"available-tools",level:2},{value:"<code>query_data_with_sql</code>",id:"query_data_with_sql",level:3},{value:"<code>create_sqlite_db</code>",id:"create_sqlite_db",level:3},{value:"<code>transform_data_with_jq</code>",id:"transform_data_with_jq",level:3},{value:"<code>create_chart_from_plotly_config</code>",id:"create_chart_from_plotly_config",level:3},{value:"Example Workflow: Querying a Large CSV",id:"example-workflow-querying-a-large-csv",level:2},{value:"Technical Considerations",id:"technical-considerations",level:2},{value:"Result Handling",id:"result-handling",level:3},{value:"Security",id:"security",level:3}];function c(e){const n={a:"a",admonition:"admonition",code:"code",h1:"h1",h2:"h2",h3:"h3",header:"header",hr:"hr",li:"li",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:"data-analysis-tools",children:"Data Analysis Tools"})}),"\n",(0,s.jsx)(n.p,{children:"Solace Agent Mesh includes a suite of optional built-in tools that enable agents to perform data analysis tasks directly on artifacts. These tools provide functionality for SQL querying, JQ transformations, and Plotly chart generation."}),"\n",(0,s.jsx)(n.h2,{id:"setup-and-configuration",children:"Setup and Configuration"}),"\n",(0,s.jsxs)(n.p,{children:["Enable the data analysis tool group in the agent's ",(0,s.jsx)(n.code,{children:"app_config.yml"})," file."]}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-yaml",children:'# In your agent\'s app_config:\ntools:\n  - tool_type: builtin-group\n    group_name: "data_analysis"\n\n# Optional: Configure tool behavior\ndata_tools_config:\n  sqlite_memory_threshold_mb: 100\n  max_result_preview_rows: 50\n  max_result_preview_bytes: 4096\n'})}),"\n",(0,s.jsx)(n.h2,{id:"available-tools",children:"Available Tools"}),"\n",(0,s.jsx)(n.h3,{id:"query_data_with_sql",children:(0,s.jsx)(n.code,{children:"query_data_with_sql"})}),"\n",(0,s.jsx)(n.admonition,{title:"Enterprise Only",type:"info",children:(0,s.jsx)(n.p,{children:"This feature is available in the Enterprise Edition only."})}),"\n",(0,s.jsx)(n.p,{children:"Executes a SQL query against data stored in a CSV or SQLite artifact."}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Parameters"}),":","\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.code,{children:"input_filename"})," (str): The filename of the input artifact (for example, ",(0,s.jsx)(n.code,{children:"'data.csv'"}),", ",(0,s.jsx)(n.code,{children:"'mydatabase.sqlite'"}),"). Supports versioning (for example, ",(0,s.jsx)(n.code,{children:"'data.csv:2'"}),")."]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.code,{children:"sql_query"})," (str): The SQL query string to execute."]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.code,{children:"output_format"})," (str, optional): The desired format for the output artifact (",(0,s.jsx)(n.code,{children:"'csv'"})," or ",(0,s.jsx)(n.code,{children:"'json'"}),"). Defaults to ",(0,s.jsx)(n.code,{children:"'csv'"}),"."]}),"\n"]}),"\n"]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Behavior"}),":","\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"For CSV Input"}),": The tool loads the CSV data into a temporary in-memory SQLite database table named ",(0,s.jsx)(n.code,{children:"data"})," and executes the query against it."]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"For SQLite Input"}),": The tool connects directly to the specified SQLite database artifact in ",(0,s.jsx)(n.strong,{children:"read-only mode"}),"."]}),"\n"]}),"\n"]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Returns"}),": A dictionary containing the execution status, a preview of the query result, and the ",(0,s.jsx)(n.code,{children:"output_filename"})," where the full result set is stored."]}),"\n"]}),"\n",(0,s.jsx)(n.hr,{}),"\n",(0,s.jsx)(n.h3,{id:"create_sqlite_db",children:(0,s.jsx)(n.code,{children:"create_sqlite_db"})}),"\n",(0,s.jsx)(n.admonition,{title:"Enterprise Only",type:"info",children:(0,s.jsx)(n.p,{children:"This feature is available in the Enterprise Edition only."})}),"\n",(0,s.jsx)(n.p,{children:"Converts a CSV or JSON artifact into a persistent SQLite database artifact. This is the recommended approach for executing multiple queries on the same dataset, as it avoids repeated parsing of the source file."}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Parameters"}),":","\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.code,{children:"input_filename"})," (str): The filename of the input CSV or JSON artifact."]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.code,{children:"output_db_filename"})," (str): The desired filename for the output SQLite database artifact (for example, ",(0,s.jsx)(n.code,{children:"'queryable_dataset.sqlite'"}),")."]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.code,{children:"table_name"})," (str, optional): The name of the table to be created within the SQLite database. Defaults to ",(0,s.jsx)(n.code,{children:"'data'"}),"."]}),"\n"]}),"\n"]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Returns"}),": A dictionary confirming the successful creation of the database artifact and providing its ",(0,s.jsx)(n.code,{children:"output_filename"}),"."]}),"\n"]}),"\n",(0,s.jsx)(n.hr,{}),"\n",(0,s.jsx)(n.h3,{id:"transform_data_with_jq",children:(0,s.jsx)(n.code,{children:"transform_data_with_jq"})}),"\n",(0,s.jsx)(n.admonition,{title:"Enterprise Only",type:"info",children:(0,s.jsx)(n.p,{children:"This feature is available in the Enterprise Edition only."})}),"\n",(0,s.jsx)(n.p,{children:"Applies a JQ expression to transform data from a JSON, YAML, or CSV artifact."}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Parameters"}),":","\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.code,{children:"input_filename"})," (str): The filename of the input artifact."]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.code,{children:"jq_expression"})," (str): The JQ filter or transformation expression string (for example, ",(0,s.jsx)(n.code,{children:"'.users[] | {name, id}'"}),")."]}),"\n"]}),"\n"]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Returns"}),": A dictionary containing the execution status, a preview of the transformed data, and the ",(0,s.jsx)(n.code,{children:"output_filename"})," where the full JSON result is stored."]}),"\n"]}),"\n",(0,s.jsx)(n.hr,{}),"\n",(0,s.jsx)(n.h3,{id:"create_chart_from_plotly_config",children:(0,s.jsx)(n.code,{children:"create_chart_from_plotly_config"})}),"\n",(0,s.jsx)(n.p,{children:"Generates a static chart image (for example, PNG, JPG, SVG) from a Plotly configuration provided as a string."}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Parameters"}),":","\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.code,{children:"config_content"})," (str): A JSON or YAML formatted string representing the Plotly ",(0,s.jsx)(n.code,{children:"figure"})," dictionary."]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.code,{children:"config_format"})," (str): Specifies whether ",(0,s.jsx)(n.code,{children:"config_content"})," is ",(0,s.jsx)(n.code,{children:"'json'"})," or ",(0,s.jsx)(n.code,{children:"'yaml'"}),"."]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.code,{children:"output_filename"})," (str): The desired filename for the output image artifact (for example, ",(0,s.jsx)(n.code,{children:"'sales_chart.png'"}),")."]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.code,{children:"output_format"})," (str, optional): The desired image format (",(0,s.jsx)(n.code,{children:"'png'"}),", ",(0,s.jsx)(n.code,{children:"'jpeg'"}),", ",(0,s.jsx)(n.code,{children:"'svg'"}),", etc.). Defaults to ",(0,s.jsx)(n.code,{children:"'png'"}),"."]}),"\n"]}),"\n"]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Returns"}),": A dictionary confirming the chart's creation and providing its ",(0,s.jsx)(n.code,{children:"output_filename"}),"."]}),"\n"]}),"\n",(0,s.jsx)(n.h2,{id:"example-workflow-querying-a-large-csv",children:"Example Workflow: Querying a Large CSV"}),"\n",(0,s.jsx)(n.p,{children:"The following workflow demonstrates an efficient method for analyzing a large CSV file:"}),"\n",(0,s.jsxs)(n.ol,{children:["\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"User Request"}),': "I need to run several queries on ',(0,s.jsx)(n.code,{children:"large_data.csv"}),'."']}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Agent Strategy"}),": The agent determines that converting the CSV to a SQLite database is more performant for subsequent queries."]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Agent Call 1"}),": The agent calls ",(0,s.jsx)(n.code,{children:"create_sqlite_db"})," to convert ",(0,s.jsx)(n.code,{children:"large_data.csv"})," into a new artifact, ",(0,s.jsx)(n.code,{children:"queryable_data.sqlite"}),"."]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Agent Response"}),': "The data has been prepared for querying. What is your first question?"']}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"User Request"}),": \"Find all records where the category is 'Sales'.\""]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Agent Call 2"}),": The agent calls ",(0,s.jsx)(n.code,{children:"query_data_with_sql"}),", targeting the ",(0,s.jsx)(n.strong,{children:(0,s.jsx)(n.code,{children:"queryable_data.sqlite"})})," artifact."]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Agent Response"}),": The agent provides the results of the query."]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"User Request"}),": \"Now, find the average amount for the 'Marketing' category.\""]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Agent Call 3"}),": The agent calls ",(0,s.jsx)(n.code,{children:"query_data_with_sql"})," again on the ",(0,s.jsxs)(n.strong,{children:["same ",(0,s.jsx)(n.code,{children:"queryable_data.sqlite"})," artifact"]}),", avoiding the overhead of reprocessing the original CSV file."]}),"\n"]}),"\n",(0,s.jsx)(n.h2,{id:"technical-considerations",children:"Technical Considerations"}),"\n",(0,s.jsx)(n.h3,{id:"result-handling",children:"Result Handling"}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Previews"}),": For ",(0,s.jsx)(n.code,{children:"query_data_with_sql"})," and ",(0,s.jsx)(n.code,{children:"transform_data_with_jq"}),", the tools return a truncated preview of the result directly to the LLM for immediate context."]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Full Results"}),": The complete, untruncated result sets are always saved as new artifacts. The LLM is provided with the filename and version of these artifacts."]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Accessing Full Results"}),": To utilize the full results, the agent can employ file management tools (",(0,s.jsx)(n.code,{children:"load_artifact"}),") or ",(0,s.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/user-guide/builtin-tools/embeds",children:"Dynamic Embeds"})," (",(0,s.jsx)(n.code,{children:"\xabartifact_content:...\xbb"}),")."]}),"\n"]}),"\n",(0,s.jsx)(n.h3,{id:"security",children:"Security"}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"SQL Execution"}),": Queries against existing SQLite artifacts are performed in ",(0,s.jsx)(n.strong,{children:"read-only mode"})," to prevent data modification. Queries against temporary databases generated from CSVs are isolated."]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"JQ Execution"}),": JQ expressions are executed within a sandboxed Python library, not via shell execution."]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Resource Usage"}),": Complex queries or transformations can be resource-intensive. Monitor performance and resource consumption accordingly."]}),"\n"]})]})}function h(e={}){const{wrapper:n}={...(0,r.R)(),...e.components};return n?(0,s.jsx)(n,{...e,children:(0,s.jsx)(c,{...e})}):c(e)}},8453:(e,n,t)=>{t.d(n,{R:()=>a,x:()=>o});var i=t(6540);const s={},r=i.createContext(s);function a(e){const n=i.useContext(r);return i.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:a(e.components),i.createElement(r.Provider,{value:n},e.children)}}}]);

solace_agent_mesh/assets/docs/assets/js/1523c6b4.2645ef68.js

@@ -1 +0,0 @@
-"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[4777],{3112:(e,n,i)=>{i.r(n),i.d(n,{assets:()=>c,contentTitle:()=>r,default:()=>h,frontMatter:()=>l,metadata:()=>t,toc:()=>d});const t=JSON.parse('{"id":"documentation/user-guide/builtin-tools/audio-tools","title":"Audio Tools","description":"This guide provides technical documentation for the text-to-speech (TTS) tools available in Solace Agent Mesh.","source":"@site/docs/documentation/user-guide/builtin-tools/audio-tools.md","sourceDirName":"documentation/user-guide/builtin-tools","slug":"/documentation/user-guide/builtin-tools/audio-tools","permalink":"/solace-agent-mesh/docs/documentation/user-guide/builtin-tools/audio-tools","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/user-guide/builtin-tools/audio-tools.md","tags":[],"version":"current","sidebarPosition":30,"frontMatter":{"title":"Audio Tools","sidebar_position":30},"sidebar":"docSidebar","previous":{"title":"Data Analysis Tools","permalink":"/solace-agent-mesh/docs/documentation/user-guide/builtin-tools/data-analysis-tools"},"next":{"title":"Dynamic Embeds","permalink":"/solace-agent-mesh/docs/documentation/user-guide/builtin-tools/embeds"}}');var s=i(4848),o=i(8453);const l={title:"Audio Tools",sidebar_position:30},r="Using Text-to-Speech (TTS) Tools",c={},d=[{value:"Overview",id:"overview",level:2},{value:"Setup and Configuration",id:"setup-and-configuration",level:2},{value:"Prerequisites",id:"prerequisites",level:3},{value:"Basic Configuration",id:"basic-configuration",level:3},{value:"Advanced Configuration",id:"advanced-configuration",level:2},{value:"<code>text_to_speech</code> Configuration",id:"text_to_speech-configuration",level:3},{value:"<code>multi_speaker_text_to_speech</code> Configuration",id:"multi_speaker_text_to_speech-configuration",level:3},{value:"Features",id:"features",level:2},{value:"Intelligent Tone Selection",id:"intelligent-tone-selection",level:3},{value:"Multi-Language Support",id:"multi-language-support",level:3},{value:"Usage Examples",id:"usage-examples",level:2},{value:"Single-Voice Text-to-Speech (<code>text_to_speech</code>)",id:"single-voice-text-to-speech-text_to_speech",level:3},{value:"Multi-Speaker Text-to-Speech (<code>multi_speaker_text_to_speech</code>)",id:"multi-speaker-text-to-speech-multi_speaker_text_to_speech",level:3},{value:"Tool Reference",id:"tool-reference",level:2},{value:"<code>text_to_speech</code>",id:"text_to_speech",level:3},{value:"<code>multi_speaker_text_to_speech</code>",id:"multi_speaker_text_to_speech",level:3},{value:"Output and Metadata",id:"output-and-metadata",level:2},{value:"Troubleshooting",id:"troubleshooting",level:2}];function a(e){const n={code:"code",h1:"h1",h2:"h2",h3:"h3",header:"header",li:"li",ol:"ol",p:"p",pre:"pre",strong:"strong",table:"table",tbody:"tbody",td:"td",th:"th",thead:"thead",tr:"tr",ul:"ul",...(0,o.R)(),...e.components};return(0,s.jsxs)(s.Fragment,{children:[(0,s.jsx)(n.header,{children:(0,s.jsx)(n.h1,{id:"using-text-to-speech-tts-tools",children:"Using Text-to-Speech (TTS) Tools"})}),"\n",(0,s.jsx)(n.p,{children:"This guide provides technical documentation for the text-to-speech (TTS) tools available in Solace Agent Mesh."}),"\n",(0,s.jsx)(n.h2,{id:"overview",children:"Overview"}),"\n",(0,s.jsxs)(n.p,{children:["The ",(0,s.jsx)(n.code,{children:"audio"})," tool group provides two primary TTS tools for generating high-quality audio artifacts:"]}),"\n",(0,s.jsxs)(n.ol,{children:["\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:(0,s.jsx)(n.code,{children:"text_to_speech"})}),": Converts a string of text to speech using a single voice, featuring intelligent tone selection."]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:(0,s.jsx)(n.code,{children:"multi_speaker_text_to_speech"})}),": Converts a conversational script, delineated by speaker, into a multi-speaker audio file."]}),"\n"]}),"\n",(0,s.jsx)(n.h2,{id:"setup-and-configuration",children:"Setup and Configuration"}),"\n",(0,s.jsx)(n.h3,{id:"prerequisites",children:"Prerequisites"}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"API Key"}),": A valid Google Gemini API key with access to the TTS model is required."]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Dependencies"}),": The ",(0,s.jsx)(n.code,{children:"pydub"})," library is necessary for audio processing and format conversion. It can be installed via ",(0,s.jsx)(n.code,{children:"pip install pydub"}),"."]}),"\n"]}),"\n",(0,s.jsx)(n.h3,{id:"basic-configuration",children:"Basic Configuration"}),"\n",(0,s.jsxs)(n.ol,{children:["\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Environment Variable"}),": The Gemini API key must be set as an environment variable.","\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-bash",children:'export GEMINI_API_KEY="your_gemini_api_key_here"\n'})}),"\n"]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Enablement"}),": The ",(0,s.jsx)(n.code,{children:"audio"})," tool group must be enabled in the agent's ",(0,s.jsx)(n.code,{children:"app_config.yml"}),".","\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-yaml",children:'tools:\n  - tool_type: builtin-group\n    group_name: "audio"\n'})}),"\n"]}),"\n"]}),"\n",(0,s.jsx)(n.h2,{id:"advanced-configuration",children:"Advanced Configuration"}),"\n",(0,s.jsxs)(n.p,{children:["You can exercise more granular control over the TTS tools by providing a ",(0,s.jsx)(n.code,{children:"tool_config"})," block for each tool in your ",(0,s.jsx)(n.code,{children:"app_config.yml"}),"."]}),"\n",(0,s.jsxs)(n.h3,{id:"text_to_speech-configuration",children:[(0,s.jsx)(n.code,{children:"text_to_speech"})," Configuration"]}),"\n",(0,s.jsx)(n.p,{children:"This example shows how to set a default voice and define the mapping between tones and specific voice models."}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-yaml",children:'- tool_type: builtin\n  tool_name: "text_to_speech"\n  tool_config:\n    gemini_api_key: ${GEMINI_API_KEY}\n    model: "gemini-2.5-flash-preview-tts"\n    voice_name: "Kore"  # Default voice if no tone is matched\n    language: "en-US"   # Default language\n    output_format: "mp3"\n    # Voice selection by tone mapping\n    voice_tone_mapping:\n      bright: ["Zephyr", "Autonoe"]\n      upbeat: ["Puck", "Laomedeia"]\n      informative: ["Charon", "Rasalgethi"]\n      firm: ["Kore", "Orus", "Alnilam"]\n      friendly: ["Achird"]\n      casual: ["Zubenelgenubi"]\n      warm: ["Sulafar"]\n'})}),"\n",(0,s.jsxs)(n.h3,{id:"multi_speaker_text_to_speech-configuration",children:[(0,s.jsx)(n.code,{children:"multi_speaker_text_to_speech"})," Configuration"]}),"\n",(0,s.jsx)(n.p,{children:"This example defines default voice configurations for up to five speakers."}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-yaml",children:'- tool_type: builtin\n  tool_name: "multi_speaker_text_to_speech"\n  tool_config:\n    gemini_api_key: ${GEMINI_API_KEY}\n    model: "gemini-2.5-flash-preview-tts"\n    language: "en-US"\n    output_format: "mp3"\n    # Default speaker voice configurations\n    default_speakers:\n      - { name: "Speaker1", voice: "Kore", tone: "firm" }\n      - { name: "Speaker2", voice: "Puck", tone: "upbeat" }\n      - { name: "Speaker3", voice: "Charon", tone: "informative" }\n      - { name: "Speaker4", voice: "Achird", tone: "friendly" }\n      - { name: "Speaker5", voice: "Sulafar", tone: "warm" }\n    # The voice_tone_mapping can also be included here\n'})}),"\n",(0,s.jsx)(n.h2,{id:"features",children:"Features"}),"\n",(0,s.jsx)(n.h3,{id:"intelligent-tone-selection",children:"Intelligent Tone Selection"}),"\n",(0,s.jsx)(n.p,{children:"The system supports tone-based voice selection, allowing for dynamic voice choice based on desired emotional or stylistic output, rather than explicit voice names."}),"\n",(0,s.jsxs)(n.p,{children:[(0,s.jsx)(n.strong,{children:"Available Tones"}),":\n",(0,s.jsx)(n.code,{children:"bright"}),", ",(0,s.jsx)(n.code,{children:"upbeat"}),", ",(0,s.jsx)(n.code,{children:"informative"}),", ",(0,s.jsx)(n.code,{children:"firm"}),", ",(0,s.jsx)(n.code,{children:"excitable"}),", ",(0,s.jsx)(n.code,{children:"youthful"}),", ",(0,s.jsx)(n.code,{children:"breezy"}),", ",(0,s.jsx)(n.code,{children:"easy-going"}),", ",(0,s.jsx)(n.code,{children:"breathy"}),", ",(0,s.jsx)(n.code,{children:"clear"}),", ",(0,s.jsx)(n.code,{children:"smooth"}),", ",(0,s.jsx)(n.code,{children:"gravelly"}),", ",(0,s.jsx)(n.code,{children:"soft"}),", ",(0,s.jsx)(n.code,{children:"even"}),", ",(0,s.jsx)(n.code,{children:"mature"}),", ",(0,s.jsx)(n.code,{children:"forward"}),", ",(0,s.jsx)(n.code,{children:"friendly"}),", ",(0,s.jsx)(n.code,{children:"casual"}),", ",(0,s.jsx)(n.code,{children:"gentle"}),", ",(0,s.jsx)(n.code,{children:"lively"}),", ",(0,s.jsx)(n.code,{children:"knowledgeable"}),", ",(0,s.jsx)(n.code,{children:"warm"})]}),"\n",(0,s.jsxs)(n.p,{children:[(0,s.jsx)(n.strong,{children:"Tone Aliases"}),":"]}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.code,{children:"professional"})," \u2192 ",(0,s.jsx)(n.code,{children:"firm"})]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.code,{children:"cheerful"})," \u2192 ",(0,s.jsx)(n.code,{children:"upbeat"})]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.code,{children:"calm"})," \u2192 ",(0,s.jsx)(n.code,{children:"soft"})]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.code,{children:"conversational"})," \u2192 ",(0,s.jsx)(n.code,{children:"casual"})]}),"\n"]}),"\n",(0,s.jsx)(n.h3,{id:"multi-language-support",children:"Multi-Language Support"}),"\n",(0,s.jsxs)(n.p,{children:["The tools support over 25 languages, specified via BCP-47 language codes (for example, ",(0,s.jsx)(n.code,{children:"en-US"}),", ",(0,s.jsx)(n.code,{children:"fr-FR"}),", ",(0,s.jsx)(n.code,{children:"es-US"}),", ",(0,s.jsx)(n.code,{children:"ja-JP"}),")."]}),"\n",(0,s.jsx)(n.h2,{id:"usage-examples",children:"Usage Examples"}),"\n",(0,s.jsxs)(n.h3,{id:"single-voice-text-to-speech-text_to_speech",children:["Single-Voice Text-to-Speech (",(0,s.jsx)(n.code,{children:"text_to_speech"}),")"]}),"\n",(0,s.jsx)(n.p,{children:(0,s.jsx)(n.strong,{children:"Basic Usage"})}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{children:'Convert the following text to speech: "Welcome to the technical briefing on artificial intelligence."\n'})}),"\n",(0,s.jsx)(n.p,{children:(0,s.jsx)(n.strong,{children:"With Tone Selection"})}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{children:'Convert this text to speech with a professional tone: "Thank you for joining today\'s technical review."\n'})}),"\n",(0,s.jsxs)(n.h3,{id:"multi-speaker-text-to-speech-multi_speaker_text_to_speech",children:["Multi-Speaker Text-to-Speech (",(0,s.jsx)(n.code,{children:"multi_speaker_text_to_speech"}),")"]}),"\n",(0,s.jsx)(n.p,{children:(0,s.jsx)(n.strong,{children:"Basic Conversation"})}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{children:"Convert this conversation to speech:\nSpeaker1: Welcome to the podcast.\nSpeaker2: Thank you for having me.\n"})}),"\n",(0,s.jsx)(n.p,{children:(0,s.jsx)(n.strong,{children:"With Custom Speaker Tones"})}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{children:"Convert this conversation using specific tones for each speaker:\n- Speaker1 should sound professional\n- Speaker2 should sound friendly\n\nConversation:\nSpeaker1: Good morning, this is the daily security briefing.\nSpeaker2: Hi everyone, let's review the agenda for today's session.\n"})}),"\n",(0,s.jsx)(n.h2,{id:"tool-reference",children:"Tool Reference"}),"\n",(0,s.jsx)(n.h3,{id:"text_to_speech",children:(0,s.jsx)(n.code,{children:"text_to_speech"})}),"\n",(0,s.jsxs)(n.table,{children:[(0,s.jsx)(n.thead,{children:(0,s.jsxs)(n.tr,{children:[(0,s.jsx)(n.th,{children:"Parameter"}),(0,s.jsx)(n.th,{children:"Type"}),(0,s.jsx)(n.th,{children:"Description"})]})}),(0,s.jsxs)(n.tbody,{children:[(0,s.jsxs)(n.tr,{children:[(0,s.jsx)(n.td,{children:(0,s.jsx)(n.code,{children:"text"})}),(0,s.jsx)(n.td,{children:"string"}),(0,s.jsx)(n.td,{children:"The text to be synthesized."})]}),(0,s.jsxs)(n.tr,{children:[(0,s.jsx)(n.td,{children:(0,s.jsx)(n.code,{children:"output_filename"})}),(0,s.jsx)(n.td,{children:"string"}),(0,s.jsx)(n.td,{children:"(Optional) A custom MP3 filename."})]}),(0,s.jsxs)(n.tr,{children:[(0,s.jsx)(n.td,{children:(0,s.jsx)(n.code,{children:"voice_name"})}),(0,s.jsx)(n.td,{children:"string"}),(0,s.jsx)(n.td,{children:"(Optional) A specific voice name to use."})]}),(0,s.jsxs)(n.tr,{children:[(0,s.jsx)(n.td,{children:(0,s.jsx)(n.code,{children:"tone"})}),(0,s.jsx)(n.td,{children:"string"}),(0,s.jsx)(n.td,{children:"(Optional) The desired voice tone."})]}),(0,s.jsxs)(n.tr,{children:[(0,s.jsx)(n.td,{children:(0,s.jsx)(n.code,{children:"language"})}),(0,s.jsx)(n.td,{children:"string"}),(0,s.jsx)(n.td,{children:"(Optional) The BCP-47 language code."})]})]})]}),"\n",(0,s.jsx)(n.h3,{id:"multi_speaker_text_to_speech",children:(0,s.jsx)(n.code,{children:"multi_speaker_text_to_speech"})}),"\n",(0,s.jsxs)(n.table,{children:[(0,s.jsx)(n.thead,{children:(0,s.jsxs)(n.tr,{children:[(0,s.jsx)(n.th,{children:"Parameter"}),(0,s.jsx)(n.th,{children:"Type"}),(0,s.jsx)(n.th,{children:"Description"})]})}),(0,s.jsxs)(n.tbody,{children:[(0,s.jsxs)(n.tr,{children:[(0,s.jsx)(n.td,{children:(0,s.jsx)(n.code,{children:"conversation_text"})}),(0,s.jsx)(n.td,{children:"string"}),(0,s.jsxs)(n.td,{children:["A string of text with speaker labels (for example, ",(0,s.jsx)(n.code,{children:"S1: ..."}),")."]})]}),(0,s.jsxs)(n.tr,{children:[(0,s.jsx)(n.td,{children:(0,s.jsx)(n.code,{children:"output_filename"})}),(0,s.jsx)(n.td,{children:"string"}),(0,s.jsx)(n.td,{children:"(Optional) A custom MP3 filename."})]}),(0,s.jsxs)(n.tr,{children:[(0,s.jsx)(n.td,{children:(0,s.jsx)(n.code,{children:"speaker_configs"})}),(0,s.jsx)(n.td,{children:"array"}),(0,s.jsx)(n.td,{children:"(Optional) An array to configure tones for specific speakers."})]}),(0,s.jsxs)(n.tr,{children:[(0,s.jsx)(n.td,{children:(0,s.jsx)(n.code,{children:"language"})}),(0,s.jsx)(n.td,{children:"string"}),(0,s.jsx)(n.td,{children:"(Optional) The BCP-47 language code."})]})]})]}),"\n",(0,s.jsx)(n.h2,{id:"output-and-metadata",children:"Output and Metadata"}),"\n",(0,s.jsx)(n.p,{children:"Both tools generate an MP3 audio artifact that includes a rich set of metadata:"}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsx)(n.li,{children:"The source text (or a truncated version for long inputs)"}),"\n",(0,s.jsx)(n.li,{children:"The voice(s) and language used for synthesis"}),"\n",(0,s.jsx)(n.li,{children:"The generation timestamp and the specific tool invoked"}),"\n",(0,s.jsx)(n.li,{children:"The requested tone and any speaker-specific configurations"}),"\n"]}),"\n",(0,s.jsx)(n.h2,{id:"troubleshooting",children:"Troubleshooting"}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:(0,s.jsx)(n.code,{children:"Error: GEMINI_API_KEY is required"})}),": This indicates that the ",(0,s.jsx)(n.code,{children:"GEMINI_API_KEY"})," environment variable has not been set correctly."]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:(0,s.jsx)(n.code,{children:"Warning: Unknown tone 'xyz'"})}),": The specified tone is not recognized. Refer to the list of supported tones. The system will fall back to a default voice."]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:(0,s.jsx)(n.code,{children:"Error: Failed to convert WAV to MP3"})}),": This typically indicates that ",(0,s.jsx)(n.code,{children:"pydub"})," is not installed or that the underlying system is missing necessary audio codecs (for example, ",(0,s.jsx)(n.code,{children:"ffmpeg"}),")."]}),"\n"]})]})}function h(e={}){const{wrapper:n}={...(0,o.R)(),...e.components};return n?(0,s.jsx)(n,{...e,children:(0,s.jsx)(a,{...e})}):a(e)}},8453:(e,n,i)=>{i.d(n,{R:()=>l,x:()=>r});var t=i(6540);const s={},o=t.createContext(s);function l(e){const n=t.useContext(o);return t.useMemo((function(){return"function"==typeof e?e(n):{...n,...e}}),[n,e])}function r(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(s):e.components||s:l(e.components),t.createElement(o.Provider,{value:n},e.children)}}}]);

solace_agent_mesh/assets/docs/assets/js/166ab619.e27886d9.js

@@ -1 +0,0 @@
-"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[515],{644:(e,s,t)=>{t.r(s),t.d(s,{assets:()=>c,contentTitle:()=>a,default:()=>h,frontMatter:()=>o,metadata:()=>n,toc:()=>l});const n=JSON.parse('{"id":"documentation/concepts/architecture","title":"Architecture","description":"Overview","source":"@site/docs/documentation/concepts/architecture.md","sourceDirName":"documentation/concepts","slug":"/documentation/concepts/architecture","permalink":"/solace-agent-mesh/docs/documentation/concepts/architecture","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/concepts/architecture.md","tags":[],"version":"current","sidebarPosition":4,"frontMatter":{"title":"Architecture","sidebar_position":4},"sidebar":"docSidebar","previous":{"title":"LLM Models","permalink":"/solace-agent-mesh/docs/documentation/getting-started/configurations/litellm_models"},"next":{"title":"Solace Agent Mesh CLI","permalink":"/solace-agent-mesh/docs/documentation/concepts/cli"}}');var i=t(4848),r=t(8453);const o={title:"Architecture",sidebar_position:4},a="Solace Agent Mesh Architecture",c={},l=[{value:"Overview",id:"overview",level:2},{value:"Architectural Principles",id:"architectural-principles",level:2},{value:"System Components",id:"system-components",level:2},{value:"Solace Event Broker",id:"solace-event-broker",level:3},{value:"Gateways",id:"gateways",level:3},{value:"Agent Hosts",id:"agent-hosts",level:3},{value:"Agents",id:"agents",level:3},{value:"Key Architectural Flows",id:"key-architectural-flows",level:2},{value:"User Task Processing Flow",id:"user-task-processing-flow",level:3},{value:"Agent-to-Agent Delegation Flow",id:"agent-to-agent-delegation-flow",level:3},{value:"Agent Discovery Flow",id:"agent-discovery-flow",level:3},{value:"A2A Protocol and Topic Structure",id:"a2a-protocol-and-topic-structure",level:2}];function d(e){const s={code:"code",h1:"h1",h2:"h2",h3:"h3",header:"header",li:"li",mermaid:"mermaid",ol:"ol",p:"p",strong:"strong",table:"table",tbody:"tbody",td:"td",th:"th",thead:"thead",tr:"tr",ul:"ul",...(0,r.R)(),...e.components};return(0,i.jsxs)(i.Fragment,{children:[(0,i.jsx)(s.header,{children:(0,i.jsx)(s.h1,{id:"solace-agent-mesh-architecture",children:"Solace Agent Mesh Architecture"})}),"\n",(0,i.jsx)(s.h2,{id:"overview",children:"Overview"}),"\n",(0,i.jsx)(s.p,{children:"Solace Agent Mesh is an event-driven framework for creating a distributed ecosystem of collaborative AI agents. The architecture is designed to decouple agent logic from communication and orchestration, enabling scalability, resilience, and modularity."}),"\n",(0,i.jsx)(s.p,{children:"It integrates three primary technologies:"}),"\n",(0,i.jsxs)(s.ul,{children:["\n",(0,i.jsxs)(s.li,{children:[(0,i.jsx)(s.strong,{children:"Solace Event Broker"}),": Provides the messaging fabric for all asynchronous communication, utilizing topic-based routing for the Agent-to-Agent (A2A) protocol."]}),"\n",(0,i.jsxs)(s.li,{children:[(0,i.jsx)(s.strong,{children:"Solace AI Connector (SAC)"}),": Serves as the runtime environment for hosting and managing the lifecycle of all system components (Agents and Gateways)."]}),"\n",(0,i.jsxs)(s.li,{children:[(0,i.jsx)(s.strong,{children:"Google Agent Development Kit (ADK)"}),": Provides the core logic for individual agents, including LLM interaction, tool execution, and state management."]}),"\n"]}),"\n",(0,i.jsx)(s.h2,{id:"architectural-principles",children:"Architectural Principles"}),"\n",(0,i.jsx)(s.p,{children:"The design of Solace Agent Mesh is founded on several key architectural principles:"}),"\n",(0,i.jsxs)(s.ul,{children:["\n",(0,i.jsxs)(s.li,{children:[(0,i.jsx)(s.strong,{children:"Event-Driven Architecture (EDA)"}),": All interactions between major components are asynchronous and mediated by the event broker. This eliminates direct dependencies, allowing components to be developed, deployed, and scaled independently."]}),"\n",(0,i.jsxs)(s.li,{children:[(0,i.jsx)(s.strong,{children:"Component Decoupling"}),": Gateways, Agent Hosts, and other services communicate through standardized A2A protocol messages over the event mesh. They do not require knowledge of each other's network location, implementation language, or internal logic."]}),"\n",(0,i.jsxs)(s.li,{children:[(0,i.jsx)(s.strong,{children:"Scalability and Resilience"}),": The architecture supports horizontal scaling of Agent Hosts and Gateways. The event broker provides fault tolerance and guaranteed message delivery, ensuring system resilience even if individual components fail or are restarted."]}),"\n"]}),"\n",(0,i.jsx)(s.h2,{id:"system-components",children:"System Components"}),"\n",(0,i.jsx)(s.p,{children:"The architecture comprises several distinct types of components that interact through the Solace broker."}),"\n",(0,i.jsx)(s.mermaid,{value:'graph TD\n    subgraph External Systems\n        direction TB\n        UserInterfaces["User Interfaces<br/>(Web UI, Slack, CLI)"]\n        APIs["External Systems & APIs"]\n    end\n\n    subgraph SolaceAgentMesh [Solace Agent Mesh]\n        direction TB\n        subgraph Gateways\n            WebUIGateway["Web UI Gateway"]\n            CustomGateway["Custom Gateway"]\n        end\n\n        Broker["Solace Broker<br/>(A2A Protocol over Topics)"]\n\n        subgraph AgentHosts ["Agent Hosts (SAC Applications)"]\n            AgentHost1["Agent Host<br/>(Runs Agent A)"]\n            AgentHost2["Agent Host<br/>(Runs Agent B)"]\n            AgentHostN["..."]\n        end\n    end\n\n    subgraph BackendServices [Backend Services & Tools]\n        LLM["Large Language Models"]\n        CustomTools["Custom Tools<br/>(Python, MCP)"]\n        DataStores["Databases & Vector Stores"]\n        ArtifactService["Artifact Service<br/>(Filesystem, Cloud Storage)"]\n    end\n\n    %% Connections\n    UserInterfaces -- Interacts with --\x3e Gateways\n    APIs -- Interacts with --\x3e Gateways\n\n    Gateways -- Pub/Sub --\x3e Broker\n    AgentHosts -- Pub/Sub --\x3e Broker\n\n    AgentHost1 -- Uses --\x3e LLM\n    AgentHost1 -- Uses --\x3e CustomTools\n    AgentHost1 -- Uses --\x3e DataStores\n    AgentHost1 -- Uses --\x3e ArtifactService\n\n    AgentHost2 -- Uses --\x3e LLM\n    AgentHost2 -- Uses --\x3e CustomTools\n    AgentHost2 -- Uses --\x3e DataStores\n    AgentHost2 -- Uses --\x3e ArtifactService\n\n    %% Styling\n    classDef external fill:#E3F2FD,stroke:#1976D2,stroke-width:2px,color:#0D47A1;\n    classDef gateway fill:#E8F5E8,stroke:#388E3C,stroke-width:2px,color:#1B5E20;\n    classDef mesh fill:#FFF8E1,stroke:#F57C00,stroke-width:2px,color:#E65100;\n    classDef agent fill:#FFF3E0,stroke:#FF9800,stroke-width:2px,color:#E65100;\n    classDef service fill:#F3E5F5,stroke:#7B1FA2,stroke-width:2px,color:#4A148C;\n\n    class UserInterfaces,APIs external;\n    class WebUIGateway,CustomGateway gateway;\n    class Broker,SolaceAgentMesh mesh;\n    class AgentHosts,AgentHost1,AgentHost2,AgentHostN agent;\n    class LLM,CustomTools,DataStores,ArtifactService service;'}),"\n",(0,i.jsx)(s.h3,{id:"solace-event-broker",children:"Solace Event Broker"}),"\n",(0,i.jsx)(s.p,{children:"The broker is the central messaging fabric. It is responsible for routing all A2A protocol messages between components using a hierarchical topic structure. This enables patterns like request/reply, streaming updates, and publish/subscribe for discovery."}),"\n",(0,i.jsx)(s.h3,{id:"gateways",children:"Gateways"}),"\n",(0,i.jsx)(s.p,{children:"Gateways are SAC applications that act as bridges between external systems and the agent mesh. Their primary responsibilities are:"}),"\n",(0,i.jsxs)(s.ul,{children:["\n",(0,i.jsxs)(s.li,{children:[(0,i.jsx)(s.strong,{children:"Protocol Translation"}),": Convert external protocols (for example, HTTP, WebSockets, Slack RTM) into the standardized A2A protocol, and vice-versa."]}),"\n",(0,i.jsxs)(s.li,{children:[(0,i.jsx)(s.strong,{children:"Authentication and Authorization"}),": Authenticate incoming requests and, using a pluggable ",(0,i.jsx)(s.code,{children:"AuthorizationService"}),", retrieve the user's permission scopes."]}),"\n",(0,i.jsxs)(s.li,{children:[(0,i.jsx)(s.strong,{children:"Session Management"}),": Manage external user sessions and map them to A2A task lifecycles."]}),"\n",(0,i.jsxs)(s.li,{children:[(0,i.jsx)(s.strong,{children:"Response Handling"}),": Receive asynchronous A2A responses and status updates from agents and deliver them to the external client."]}),"\n"]}),"\n",(0,i.jsxs)(s.p,{children:["The ",(0,i.jsx)(s.strong,{children:"Gateway Development Kit (GDK)"})," provides ",(0,i.jsx)(s.code,{children:"BaseGatewayApp"})," and ",(0,i.jsx)(s.code,{children:"BaseGatewayComponent"})," classes to abstract common gateway logic, such as A2A protocol handling, agent discovery, and late-stage embed resolution, simplifying the creation of new gateways."]}),"\n",(0,i.jsx)(s.h3,{id:"agent-hosts",children:"Agent Hosts"}),"\n",(0,i.jsxs)(s.p,{children:["An Agent Host is a SAC application (",(0,i.jsx)(s.code,{children:"SamAgentApp"}),") that hosts a single ADK-based agent. Its key architectural functions include:"]}),"\n",(0,i.jsxs)(s.ul,{children:["\n",(0,i.jsxs)(s.li,{children:[(0,i.jsx)(s.strong,{children:"Hosting the ADK Runtime"}),": It manages the lifecycle of the ADK ",(0,i.jsx)(s.code,{children:"Runner"})," and ",(0,i.jsx)(s.code,{children:"LlmAgent"}),"."]}),"\n",(0,i.jsxs)(s.li,{children:[(0,i.jsx)(s.strong,{children:"A2A Protocol Handling"}),": The internal ",(0,i.jsx)(s.code,{children:"SamAgentComponent"})," translates incoming A2A requests into ADK ",(0,i.jsx)(s.code,{children:"Task"})," objects and converts ADK ",(0,i.jsx)(s.code,{children:"Event"})," objects into outgoing A2A ",(0,i.jsx)(s.code,{children:"TaskStatusUpdateEvent"}),", ",(0,i.jsx)(s.code,{children:"TaskArtifactUpdateEvent"}),", or final response messages."]}),"\n",(0,i.jsxs)(s.li,{children:[(0,i.jsx)(s.strong,{children:"Scope Enforcement"}),": It extracts permission scopes from incoming message properties and filters the agent's available tools accordingly."]}),"\n",(0,i.jsxs)(s.li,{children:[(0,i.jsx)(s.strong,{children:"Service Initialization"}),": It initializes ADK services like the ",(0,i.jsx)(s.code,{children:"ArtifactService"})," and ",(0,i.jsx)(s.code,{children:"MemoryService"})," based on its configuration."]}),"\n"]}),"\n",(0,i.jsx)(s.h3,{id:"agents",children:"Agents"}),"\n",(0,i.jsx)(s.p,{children:"An agent is the logical entity within an Agent Host that performs tasks. It is defined by its configuration, which includes:"}),"\n",(0,i.jsxs)(s.ul,{children:["\n",(0,i.jsxs)(s.li,{children:[(0,i.jsx)(s.strong,{children:"Instructions"}),": The base prompt that defines its persona, capabilities, and constraints."]}),"\n",(0,i.jsxs)(s.li,{children:[(0,i.jsx)(s.strong,{children:"LLM Configuration"}),": The specific large language model to use."]}),"\n",(0,i.jsxs)(s.li,{children:[(0,i.jsx)(s.strong,{children:"Toolset"}),": A collection of available tools, which can be built-in, custom Python functions, or MCP Toolsets."]}),"\n"]}),"\n",(0,i.jsx)(s.h2,{id:"key-architectural-flows",children:"Key Architectural Flows"}),"\n",(0,i.jsx)(s.h3,{id:"user-task-processing-flow",children:"User Task Processing Flow"}),"\n",(0,i.jsxs)(s.ol,{children:["\n",(0,i.jsxs)(s.li,{children:["An external client sends a request to a ",(0,i.jsx)(s.strong,{children:"Gateway"}),"."]}),"\n",(0,i.jsxs)(s.li,{children:["The Gateway authenticates the request, retrieves the user's permission scopes via its ",(0,i.jsx)(s.code,{children:"AuthorizationService"}),", and translates the request into an A2A task message. It includes the scopes in the Solace message's user properties."]}),"\n",(0,i.jsxs)(s.li,{children:["The Gateway publishes the message to the target agent's request topic on the ",(0,i.jsx)(s.strong,{children:"Solace Broker"}),"."]}),"\n",(0,i.jsxs)(s.li,{children:["The corresponding ",(0,i.jsx)(s.strong,{children:"Agent Host"})," receives the message. The ",(0,i.jsx)(s.code,{children:"SamAgentComponent"})," extracts the scopes and initiates an ADK task."]}),"\n",(0,i.jsxs)(s.li,{children:["The ADK ",(0,i.jsx)(s.code,{children:"LlmAgent"})," processes the task. Before invoking the LLM, a ",(0,i.jsx)(s.code,{children:"before_model_callback"})," filters the available tools based on the user's scopes."]}),"\n",(0,i.jsxs)(s.li,{children:["As the agent executes, the ",(0,i.jsx)(s.code,{children:"SamAgentComponent"})," translates ADK events into A2A status and artifact update messages, publishing them to the originating Gateway's status topic."]}),"\n",(0,i.jsxs)(s.li,{children:["The Gateway receives these streaming updates, performs any necessary late-stage processing (like resolving ",(0,i.jsx)(s.code,{children:"artifact_content"})," embeds), and forwards them to the client."]}),"\n",(0,i.jsx)(s.li,{children:"Upon completion, the Agent Host sends a final A2A response message to the Gateway, which delivers it to the client."}),"\n"]}),"\n",(0,i.jsx)(s.h3,{id:"agent-to-agent-delegation-flow",children:"Agent-to-Agent Delegation Flow"}),"\n",(0,i.jsxs)(s.ol,{children:["\n",(0,i.jsxs)(s.li,{children:[(0,i.jsx)(s.strong,{children:"Agent A"}),", while processing a task, determines a sub-task should be delegated to ",(0,i.jsx)(s.strong,{children:"Agent B"}),"."]}),"\n",(0,i.jsxs)(s.li,{children:["Agent A uses its ",(0,i.jsx)(s.code,{children:"PeerAgentTool"})," to construct a new A2A task request for Agent B. It propagates the original user's permission scopes to maintain the security context."]}),"\n",(0,i.jsx)(s.li,{children:"The request is published to Agent B's request topic."}),"\n",(0,i.jsxs)(s.li,{children:[(0,i.jsx)(s.strong,{children:"Agent B's Host"})," receives and processes the sub-task, enforcing the propagated scopes on its own toolset."]}),"\n",(0,i.jsx)(s.li,{children:"Agent B sends status updates and a final response to topics designated by Agent A."}),"\n",(0,i.jsx)(s.li,{children:"Agent A receives the results and incorporates them into its ongoing task."}),"\n"]}),"\n",(0,i.jsx)(s.h3,{id:"agent-discovery-flow",children:"Agent Discovery Flow"}),"\n",(0,i.jsxs)(s.ol,{children:["\n",(0,i.jsxs)(s.li,{children:["On startup and periodically, each ",(0,i.jsx)(s.strong,{children:"Agent Host"})," publishes an ",(0,i.jsx)(s.code,{children:"AgentCard"})," (a JSON document describing its agent's capabilities) to a well-known discovery topic (for example, ",(0,i.jsx)(s.code,{children:"{namespace}/a2a/v1/discovery/agentcards"}),")."]}),"\n",(0,i.jsxs)(s.li,{children:[(0,i.jsx)(s.strong,{children:"Gateways"})," and other ",(0,i.jsx)(s.strong,{children:"Agent Hosts"})," subscribe to this topic."]}),"\n",(0,i.jsxs)(s.li,{children:["Upon receiving an ",(0,i.jsx)(s.code,{children:"AgentCard"}),", components update their local ",(0,i.jsx)(s.code,{children:"AgentRegistry"}),", making them aware of available agents for user selection (at the Gateway) or peer delegation (at the Agent)."]}),"\n"]}),"\n",(0,i.jsx)(s.h2,{id:"a2a-protocol-and-topic-structure",children:"A2A Protocol and Topic Structure"}),"\n",(0,i.jsx)(s.p,{children:"The A2A protocol is based on JSON-RPC 2.0 and defines the message formats for all interactions. Communication is routed via a hierarchical topic structure on the Solace broker."}),"\n",(0,i.jsxs)(s.table,{children:[(0,i.jsx)(s.thead,{children:(0,i.jsxs)(s.tr,{children:[(0,i.jsx)(s.th,{children:"Purpose"}),(0,i.jsx)(s.th,{children:"Topic Pattern"})]})}),(0,i.jsxs)(s.tbody,{children:[(0,i.jsxs)(s.tr,{children:[(0,i.jsx)(s.td,{children:(0,i.jsx)(s.strong,{children:"Agent Discovery"})}),(0,i.jsx)(s.td,{children:(0,i.jsx)(s.code,{children:"{namespace}/a2a/v1/discovery/agentcards"})})]}),(0,i.jsxs)(s.tr,{children:[(0,i.jsx)(s.td,{children:(0,i.jsx)(s.strong,{children:"Task Requests"})}),(0,i.jsx)(s.td,{children:(0,i.jsx)(s.code,{children:"{namespace}/a2a/v1/agent/request/{target_agent_name}"})})]}),(0,i.jsxs)(s.tr,{children:[(0,i.jsx)(s.td,{children:(0,i.jsx)(s.strong,{children:"Status Updates"})}),(0,i.jsx)(s.td,{children:(0,i.jsx)(s.code,{children:"{namespace}/a2a/v1/gateway/status/{gateway_id}/{task_id}"})})]}),(0,i.jsxs)(s.tr,{children:[(0,i.jsx)(s.td,{children:(0,i.jsx)(s.strong,{children:"Final Responses"})}),(0,i.jsx)(s.td,{children:(0,i.jsx)(s.code,{children:"{namespace}/a2a/v1/gateway/response/{gateway_id}/{task_id}"})})]}),(0,i.jsxs)(s.tr,{children:[(0,i.jsx)(s.td,{children:(0,i.jsx)(s.strong,{children:"Peer Delegation Status"})}),(0,i.jsx)(s.td,{children:(0,i.jsx)(s.code,{children:"{namespace}/a2a/v1/agent/status/{delegating_agent_name}/{sub_task_id}"})})]}),(0,i.jsxs)(s.tr,{children:[(0,i.jsx)(s.td,{children:(0,i.jsx)(s.strong,{children:"Peer Delegation Response"})}),(0,i.jsx)(s.td,{children:(0,i.jsx)(s.code,{children:"{namespace}/a2a/v1/agent/response/{delegating_agent_name}/{sub_task_id}"})})]})]})]}),"\n",(0,i.jsx)(s.p,{children:"This topic structure allows for precise, point-to-point routing in a decoupled, asynchronous environment."})]})}function h(e={}){const{wrapper:s}={...(0,r.R)(),...e.components};return s?(0,i.jsx)(s,{...e,children:(0,i.jsx)(d,{...e})}):d(e)}},8453:(e,s,t)=>{t.d(s,{R:()=>o,x:()=>a});var n=t(6540);const i={},r=n.createContext(i);function o(e){const s=n.useContext(r);return n.useMemo((function(){return"function"==typeof e?e(s):{...s,...e}}),[s,e])}function a(e){let s;return s=e.disableParentContext?"function"==typeof e.components?e.components(i):e.components||i:o(e.components),n.createElement(r.Provider,{value:s},e.children)}}}]);

solace_agent_mesh/assets/docs/assets/js/1c6e87d2.e056b7e0.js

@@ -1 +0,0 @@
-"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[2037],{6317:(e,n,s)=>{s.r(n),s.d(n,{assets:()=>a,contentTitle:()=>l,default:()=>g,frontMatter:()=>r,metadata:()=>i,toc:()=>d});const i=JSON.parse('{"id":"documentation/deployment/debugging","title":"Debugging","description":"Debugging issues in Solace Agent Mesh starts with identifying the problem. You can monitor your system to debug it more effectively. For more information, see Observability.","source":"@site/docs/documentation/deployment/debugging.md","sourceDirName":"documentation/deployment","slug":"/documentation/deployment/debugging","permalink":"/solace-agent-mesh/docs/documentation/deployment/debugging","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/deployment/debugging.md","tags":[],"version":"current","sidebarPosition":30,"frontMatter":{"title":"Debugging","sidebar_position":30},"sidebar":"docSidebar","previous":{"title":"Observability","permalink":"/solace-agent-mesh/docs/documentation/deployment/observability"},"next":{"title":"Build Your Own Agent","permalink":"/solace-agent-mesh/docs/documentation/tutorials/custom-agent"}}');var o=s(4848),t=s(8453);const r={title:"Debugging",sidebar_position:30},l="Debugging",a={},d=[{value:"Isolate Components",id:"isolate-components",level:2},{value:"Examine STIM Files",id:"examine-stim-files",level:2},{value:"Monitor Broker Activity",id:"monitor-broker-activity",level:2},{value:"Debug Mode",id:"debug-mode",level:2},{value:"Debugging in VSCode",id:"debugging-in-vscode",level:3},{value:"Invoke the Agent Directly",id:"invoke-the-agent-directly",level:2},{value:"Tools for Sending Messages",id:"tools-for-sending-messages",level:4},{value:"Message Format",id:"message-format",level:4},{value:"System Logs",id:"system-logs",level:2},{value:"Configuring Log Rotation",id:"configuring-log-rotation",level:3}];function c(e){const n={a:"a",code:"code",h1:"h1",h2:"h2",h3:"h3",h4:"h4",header:"header",li:"li",ol:"ol",p:"p",pre:"pre",strong:"strong",ul:"ul",...(0,t.R)(),...e.components};return(0,o.jsxs)(o.Fragment,{children:[(0,o.jsx)(n.header,{children:(0,o.jsx)(n.h1,{id:"debugging",children:"Debugging"})}),"\n",(0,o.jsxs)(n.p,{children:["Debugging issues in Solace Agent Mesh starts with identifying the problem. You can monitor your system to debug it more effectively. For more information, see ",(0,o.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/deployment/observability",children:"Observability"}),".\nThe following sections provide common debugging approaches to help you diagnose and resolve issues."]}),"\n",(0,o.jsx)(n.h2,{id:"isolate-components",children:"Isolate Components"}),"\n",(0,o.jsxs)(n.p,{children:["Running only the necessary components in isolation can help pinpoint issues. The ",(0,o.jsx)(n.code,{children:"run"})," Solace Agent Mesh CLI command allows you to specify which files to run."]}),"\n",(0,o.jsx)(n.p,{children:"For example:"}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-bash",children:"sam run configs/agents/my_tool_1.yaml configs/agents/my_tool_2.yaml\n"})}),"\n",(0,o.jsxs)(n.p,{children:["This command runs only the agents defined in ",(0,o.jsx)(n.code,{children:"my_tool_1.yaml"})," and ",(0,o.jsx)(n.code,{children:"my_tool_2.yaml"}),", reducing noise from unrelated components."]}),"\n",(0,o.jsx)(n.h2,{id:"examine-stim-files",children:"Examine STIM Files"}),"\n",(0,o.jsxs)(n.p,{children:[(0,o.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/deployment/observability#stimulus-logs",children:"STIM files"})," provide detailed traces of stimulus life cycles. If you have access to the storage location, you can inspect them to analyze message flows."]}),"\n",(0,o.jsxs)(n.p,{children:["Each ",(0,o.jsx)(n.code,{children:".stim"})," file contains all broker events related to a single stimulus, from the initial request to the final response."]}),"\n",(0,o.jsx)(n.h2,{id:"monitor-broker-activity",children:"Monitor Broker Activity"}),"\n",(0,o.jsxs)(n.p,{children:["For insights into message flows and event interactions, see ",(0,o.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/deployment/observability#broker-observability",children:"Broker Observability"}),"."]}),"\n",(0,o.jsx)(n.h2,{id:"debug-mode",children:"Debug Mode"}),"\n",(0,o.jsx)(n.p,{children:"Because Solace Agent Mesh is a Python-based framework, you can run it in debug mode using an IDE with breakpoints."}),"\n",(0,o.jsx)(n.h3,{id:"debugging-in-vscode",children:"Debugging in VSCode"}),"\n",(0,o.jsxs)(n.p,{children:["If you're using VSCode, configure debugging in ",(0,o.jsx)(n.code,{children:".vscode/launch.json"}),":"]}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-json",children:'{\n  "version": "0.2.0",\n  "configurations": [\n    {\n      "name": "sam-debug",\n      "type": "debugpy",\n      "request": "launch",\n      "module": "solace_agent_mesh.cli.main",\n      "console": "integratedTerminal",\n      "envFile": "${workspaceFolder}/.env",\n      "args": [\n        "run",\n        "configs/agents/main_orchestrator.yaml",\n        "configs/gateways/webui.yaml"\n        // Add any other components you want to run here\n      ],\n      "justMyCode": false\n    }\n  ]\n}\n'})}),"\n",(0,o.jsx)(n.p,{children:"To start debugging:"}),"\n",(0,o.jsxs)(n.ol,{children:["\n",(0,o.jsxs)(n.li,{children:["Open the ",(0,o.jsx)(n.strong,{children:"RUN AND DEBUG"})," panel on the left sidebar."]}),"\n",(0,o.jsxs)(n.li,{children:["Select ",(0,o.jsx)(n.code,{children:"sam-debug"})," from the dropdown."]}),"\n",(0,o.jsxs)(n.li,{children:["Click the ",(0,o.jsx)(n.strong,{children:"Play"})," to start in debug mode."]}),"\n"]}),"\n",(0,o.jsx)(n.p,{children:"Set breakpoints in your code to pause execution and inspect variable states."}),"\n",(0,o.jsx)(n.h2,{id:"invoke-the-agent-directly",children:"Invoke the Agent Directly"}),"\n",(0,o.jsx)(n.p,{children:"For debugging and testing, you can send direct messages to an agent by directly selecting the agent in the web UI agent dropdown or by using the Solace event broker. This requires specifying the appropriate topic, user properties, and payload."}),"\n",(0,o.jsx)(n.h4,{id:"tools-for-sending-messages",children:"Tools for Sending Messages"}),"\n",(0,o.jsxs)(n.ul,{children:["\n",(0,o.jsx)(n.li,{children:(0,o.jsx)(n.strong,{children:(0,o.jsx)(n.a,{href:"https://marketplace.visualstudio.com/items?itemName=solace-tools.solace-try-me-vsc-extension",children:"Solace Try Me VSCode Extension"})})}),"\n",(0,o.jsx)(n.li,{children:(0,o.jsx)(n.strong,{children:(0,o.jsx)(n.a,{href:"https://github.com/SolaceLabs/solace-tryme-cli",children:"Solace Try Me (STM) CLI Tool"})})}),"\n"]}),"\n",(0,o.jsx)(n.h4,{id:"message-format",children:"Message Format"}),"\n",(0,o.jsxs)(n.p,{children:[(0,o.jsx)(n.strong,{children:"Topic"}),":"]}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{children:"[NAME_SPACES]a2a/v1/agent/request/<agent_name>\n"})}),"\n",(0,o.jsxs)(n.p,{children:[(0,o.jsx)(n.strong,{children:"User Properties"}),":"]}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{children:"userId: test-0000\nclientId: test-0000\nreplyTo: [NAME_SPACES]a2a/v1/gateway/response/0000000/task-0000000\na2aUserConfig: {}\n"})}),"\n",(0,o.jsxs)(n.p,{children:[(0,o.jsx)(n.strong,{children:"Payload"}),":"]}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-json",children:'{\n    "jsonrpc": "2.0",\n    "id": "000000000",\n    "method": "tasks/sendSubscribe",\n    "params": {\n      "id": "task-0000000",\n      "sessionId": "web-session-00000000",\n      "message": {\n        "role": "user",\n        "parts": [\n          {\n            "type": "text",\n            "text": "Hello World!"\n          }\n        ]\n      },\n      "acceptedOutputModes": [\n        "text"\n      ],\n      "metadata": {\n        "system_purpose": "The system is an AI Chatbot with agentic capabilities. It uses the agents available to provide information, reasoning and general assistance for the users in this system. **Always return useful artifacts and files that you create to the user.** Provide a status update before each tool call. Your external name is Agent Mesh.\\n",\n        "response_format": "Responses should be clear, concise, and professionally toned. Format responses to the user in Markdown using appropriate formatting.\\n"\n      }\n  }\n}\n'})}),"\n",(0,o.jsxs)(n.p,{children:[(0,o.jsx)(n.strong,{children:"Response Topic"}),":"]}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{children:"[NAME_SPACES]a2a/v1/gateway/response/0000000/task-0000000\n"})}),"\n",(0,o.jsx)(n.p,{children:"By sending a request and observing the response, you can verify an agent's behavior in isolation, making it easier to identify issues."}),"\n",(0,o.jsx)(n.h2,{id:"system-logs",children:"System Logs"}),"\n",(0,o.jsxs)(n.p,{children:["System logs provide detailed insights into the system's behavior. The logging behavior is configured in the ",(0,o.jsx)(n.code,{children:"configs/logging_config.ini"})," file, which controls both console (STDOUT) and file-based logging."]}),"\n",(0,o.jsx)(n.p,{children:"By default, the system is configured to:"}),"\n",(0,o.jsxs)(n.ul,{children:["\n",(0,o.jsxs)(n.li,{children:["Output logs with a severity of ",(0,o.jsx)(n.code,{children:"INFO"})," and higher to the console (STDOUT)."]}),"\n",(0,o.jsxs)(n.li,{children:["Write more detailed logs with a severity of ",(0,o.jsx)(n.code,{children:"DEBUG"})," and higher to a rotating log file named ",(0,o.jsx)(n.code,{children:"sam.log"})," in the project's root directory."]}),"\n"]}),"\n",(0,o.jsx)(n.h3,{id:"configuring-log-rotation",children:"Configuring Log Rotation"}),"\n",(0,o.jsxs)(n.p,{children:["The log file rotation is managed by the ",(0,o.jsx)(n.code,{children:"rotatingFileHandler"})," in ",(0,o.jsx)(n.code,{children:"configs/logging_config.ini"}),". You can customize its behavior by modifying the ",(0,o.jsx)(n.code,{children:"args"})," line:"]}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-ini",children:"[handler_rotatingFileHandler]\nclass=logging.handlers.RotatingFileHandler\nlevel=DEBUG\nformatter=simpleFormatter\nargs=('sam.log', 'a', 52428800, 10)\n"})}),"\n",(0,o.jsxs)(n.p,{children:["The ",(0,o.jsx)(n.code,{children:"args"})," tuple is defined as follows:"]}),"\n",(0,o.jsxs)(n.ul,{children:["\n",(0,o.jsxs)(n.li,{children:[(0,o.jsx)(n.code,{children:"'sam.log'"}),": The name of the log file."]}),"\n",(0,o.jsxs)(n.li,{children:[(0,o.jsx)(n.code,{children:"'a'"}),": The file mode (append)."]}),"\n",(0,o.jsxs)(n.li,{children:[(0,o.jsx)(n.code,{children:"52428800"}),": The maximum size of the log file in bytes before it is rotated. In this case, it's 50 MB."]}),"\n",(0,o.jsxs)(n.li,{children:[(0,o.jsx)(n.code,{children:"10"}),": The number of backup log files to keep."]}),"\n"]}),"\n",(0,o.jsxs)(n.p,{children:["For example, to change the log file size to 20 MB and keep 5 backup files, you would modify the line to:\n",(0,o.jsx)(n.code,{children:"args=('sam.log', 'a', 20971520, 5)"})]}),"\n",(0,o.jsx)(n.p,{children:"This level of configuration allows you to manage log verbosity and disk space usage according to your needs."})]})}function g(e={}){const{wrapper:n}={...(0,t.R)(),...e.components};return n?(0,o.jsx)(n,{...e,children:(0,o.jsx)(c,{...e})}):c(e)}},8453:(e,n,s)=>{s.d(n,{R:()=>r,x:()=>l});var i=s(6540);const o={},t=i.createContext(o);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(o):e.components||o:r(e.components),i.createElement(t.Provider,{value:n},e.children)}}}]);

solace_agent_mesh/assets/docs/assets/js/21ceee5f.3bf39250.js

@@ -1 +0,0 @@
-"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[8423],{8782:(e,n,t)=>{t.r(n),t.d(n,{assets:()=>c,contentTitle:()=>i,default:()=>h,frontMatter:()=>r,metadata:()=>s,toc:()=>l});const s=JSON.parse('{"id":"documentation/concepts/orchestrator","title":"Orchestrator","description":"The A2A (Agent-to-Agent) protocol is the communication backbone of Solace Agent Mesh that enables distributed agent coordination and workflow management. Unlike traditional centralized orchestration, the A2A protocol enables agents to discover each other, delegate tasks, and collaborate directly through standardized message patterns.","source":"@site/docs/documentation/concepts/orchestrator.md","sourceDirName":"documentation/concepts","slug":"/documentation/concepts/orchestrator","permalink":"/solace-agent-mesh/docs/documentation/concepts/orchestrator","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/concepts/orchestrator.md","tags":[],"version":"current","sidebarPosition":40,"frontMatter":{"title":"Orchestrator","sidebar_position":40},"sidebar":"docSidebar","previous":{"title":"Agents","permalink":"/solace-agent-mesh/docs/documentation/concepts/agents"},"next":{"title":"Plugins","permalink":"/solace-agent-mesh/docs/documentation/concepts/plugins"}}');var o=t(4848),a=t(8453);const r={title:"Orchestrator",sidebar_position:40},i="Orchestrator Agent",c={},l=[{value:"Key Functions",id:"key-functions",level:2}];function d(e){const n={admonition:"admonition",h1:"h1",h2:"h2",header:"header",li:"li",ol:"ol",p:"p",strong:"strong",ul:"ul",...(0,a.R)(),...e.components};return(0,o.jsxs)(o.Fragment,{children:[(0,o.jsx)(n.header,{children:(0,o.jsx)(n.h1,{id:"orchestrator-agent",children:"Orchestrator Agent"})}),"\n",(0,o.jsx)(n.p,{children:"The A2A (Agent-to-Agent) protocol is the communication backbone of Solace Agent Mesh that enables distributed agent coordination and workflow management. Unlike traditional centralized orchestration, the A2A protocol enables agents to discover each other, delegate tasks, and collaborate directly through standardized message patterns."}),"\n",(0,o.jsxs)(n.p,{children:["The advantages of centralized orchestration such as task breakdown and management, centralized point of communication and session management are still achieved in Solace Agent Mesh through a specialized agent called the ",(0,o.jsx)(n.strong,{children:"OrchestratorAgent"})," that acts as the central coordinator for complex workflows."]}),"\n",(0,o.jsx)(n.admonition,{title:"In one sentence",type:"tip",children:(0,o.jsx)(n.p,{children:"The OrchestratorAgent allows for a centralized workflow management in Solace Agent Mesh by coordinating tasks and communication between agents."})}),"\n",(0,o.jsx)(n.p,{children:"The system is not limited to a single orchestrator agent, and multiple orchestrator agents can be deployed to handle different workflows or domains. This allows for flexibility and scalability in managing complex tasks."}),"\n",(0,o.jsx)(n.h2,{id:"key-functions",children:"Key Functions"}),"\n",(0,o.jsx)(n.p,{children:"The orchestrator agent provides the following key functions:"}),"\n",(0,o.jsxs)(n.ol,{children:["\n",(0,o.jsxs)(n.li,{children:["\n",(0,o.jsxs)(n.p,{children:[(0,o.jsx)(n.strong,{children:"Request Analysis and Action Planning"}),":"]}),"\n",(0,o.jsxs)(n.ul,{children:["\n",(0,o.jsx)(n.li,{children:"Receives high-level goals or requests"}),"\n",(0,o.jsx)(n.li,{children:"Analyzes them in the context of available actions registered by agents in the system"}),"\n",(0,o.jsx)(n.li,{children:"Uses state-of-the-art generative AI techniques to plan a sequence of actions to fulfill the request"}),"\n"]}),"\n"]}),"\n",(0,o.jsxs)(n.li,{children:["\n",(0,o.jsxs)(n.p,{children:[(0,o.jsx)(n.strong,{children:"Task Creation and Distribution"}),":"]}),"\n",(0,o.jsxs)(n.ul,{children:["\n",(0,o.jsx)(n.li,{children:"Creates tasks based on the action plan"}),"\n",(0,o.jsx)(n.li,{children:"Distributes tasks to appropriate agents"}),"\n",(0,o.jsx)(n.li,{children:"Enables efficient parallel processing and optimal resource utilization"}),"\n"]}),"\n"]}),"\n",(0,o.jsxs)(n.li,{children:["\n",(0,o.jsxs)(n.p,{children:[(0,o.jsx)(n.strong,{children:"Workflow Management"}),":"]}),"\n",(0,o.jsxs)(n.ul,{children:["\n",(0,o.jsx)(n.li,{children:"Tracks outstanding tasks"}),"\n",(0,o.jsx)(n.li,{children:"Aggregates responses from various agents"}),"\n",(0,o.jsx)(n.li,{children:"Ensures all parts of a complex request are processed and combined coherently"}),"\n"]}),"\n"]}),"\n",(0,o.jsxs)(n.li,{children:["\n",(0,o.jsxs)(n.p,{children:[(0,o.jsx)(n.strong,{children:"Response Formatting"}),":"]}),"\n",(0,o.jsxs)(n.ul,{children:["\n",(0,o.jsx)(n.li,{children:"Formats aggregated responses suitable for the gateway"}),"\n",(0,o.jsx)(n.li,{children:"Ensures the final output meets the requirements of the specific use case or interface"}),"\n"]}),"\n"]}),"\n"]})]})}function h(e={}){const{wrapper:n}={...(0,a.R)(),...e.components};return n?(0,o.jsx)(n,{...e,children:(0,o.jsx)(d,{...e})}):d(e)}},8453:(e,n,t)=>{t.d(n,{R:()=>r,x:()=>i});var s=t(6540);const o={},a=s.createContext(o);function r(e){const n=s.useContext(a);return s.useMemo((function(){return"function"==typeof e?e(n):{...n,...e}}),[n,e])}function i(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(o):e.components||o:r(e.components),s.createElement(a.Provider,{value:n},e.children)}}}]);

solace_agent_mesh/assets/docs/assets/js/2a9cab12.2afaee76.js

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

solace_agent_mesh/assets/docs/assets/js/332e10b5.f7629851.js

@@ -1 +0,0 @@
-"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[9150],{4897:(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/tutorials/bedrock-agents","title":"Amazon Bedrock Agents","description":"This tutorial walks you through the process of integrating Amazon Bedrock Agents and Flows into Solace Agent Mesh. This integration allows you to create agents that can interact with one or multiple Bedrock Agents or Flows, extending your Solace Agent Mesh project with powerful AI capabilities from AWS.","source":"@site/docs/documentation/tutorials/bedrock-agents.md","sourceDirName":"documentation/tutorials","slug":"/documentation/tutorials/bedrock-agents","permalink":"/solace-agent-mesh/docs/documentation/tutorials/bedrock-agents","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/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/tutorials/event-mesh-gateway"},"next":{"title":"SQL Database Integration","permalink":"/solace-agent-mesh/docs/documentation/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 a Solace Agent Mesh Project",id:"create-a-solace-agent-mesh-project",level:3},{value:"Integrating Bedrock with Solace Agent Mesh",id:"integrating-bedrock-with-solace-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 Solace Agent Mesh Project",id:"starting-your-solace-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 Solace Agent Mesh. This integration allows you to create agents that can interact with one or multiple Bedrock Agents or Flows, extending your Solace 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 Solace Agent Mesh, you can:"}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsx)(n.li,{children:"Use the extensible Solace 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 Solace 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 Solace 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 Solace 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 Solace 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-a-solace-agent-mesh-project",children:"Create a Solace Agent Mesh Project"}),"\n",(0,s.jsxs)(n.p,{children:["You must ",(0,s.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/getting-started/installation",children:"install Solace Agent Mesh and Solace Mesh Agent CLI"}),", and then you'll want to ",(0,s.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/getting-started/quick-start",children:"create a new Solace Agent Mesh project"}),"."]}),"\n",(0,s.jsx)(n.h2,{id:"integrating-bedrock-with-solace-agent-mesh",children:"Integrating Bedrock with Solace 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 Solace Agent Mesh and Amazon Bedrock services. This plugin allows your Solace 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 Solace 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 Solace 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 Solace 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 Solace 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-solace-agent-mesh-project",children:"Starting Your Solace Agent Mesh Project"}),"\n",(0,s.jsx)(n.p,{children:"After configuring your Bedrock agent integration, run your Solace 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 Solace 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"}),": Solace 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/3d406171.5560fdf9.js

@@ -1 +0,0 @@
-"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[8357],{3960:(e,n,t)=>{t.r(n),t.d(n,{assets:()=>c,contentTitle:()=>s,default:()=>h,frontMatter:()=>i,metadata:()=>a,toc:()=>l});const a=JSON.parse('{"id":"documentation/tutorials/custom-agent","title":"Build Your Own Agent","description":"This tutorial shows you how to build a sophisticated weather agent using the Solace Agent Mesh framework. Learn how to integrate with external APIs, manage resources properly, and create production-ready agents.","source":"@site/docs/documentation/tutorials/custom-agent.md","sourceDirName":"documentation/tutorials","slug":"/documentation/tutorials/custom-agent","permalink":"/solace-agent-mesh/docs/documentation/tutorials/custom-agent","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/tutorials/custom-agent.md","tags":[],"version":"current","sidebarPosition":5,"frontMatter":{"title":"Build Your Own Agent","sidebar_position":5},"sidebar":"docSidebar","previous":{"title":"Debugging","permalink":"/solace-agent-mesh/docs/documentation/deployment/debugging"},"next":{"title":"MCP Integration","permalink":"/solace-agent-mesh/docs/documentation/tutorials/mcp-integration"}}');var r=t(4848),o=t(8453);const i={title:"Build Your Own Agent",sidebar_position:5},s="Build Your Own Agent",c={},l=[{value:"Overview",id:"overview",level:2},{value:"Prerequisites",id:"prerequisites",level:2},{value:"Planning the Weather Agent",id:"planning-the-weather-agent",level:2},{value:"Step 1: Project Structure",id:"step-1-project-structure",level:2},{value:"Step 2: Weather Service Implementation",id:"step-2-weather-service-implementation",level:2},{value:"Step 3: Weather Tools Implementation",id:"step-3-weather-tools-implementation",level:2},{value:"Step 4: Lifecycle Functions",id:"step-4-lifecycle-functions",level:2},{value:"Step 5: Agent Configuration",id:"step-5-agent-configuration",level:2},{value:"Step 6: Environment Setup",id:"step-6-environment-setup",level:2},{value:"Step 7: Running the Agent",id:"step-7-running-the-agent",level:2},{value:"Step 8: Testing the Weather Agent",id:"step-8-testing-the-weather-agent",level:2},{value:"Key Features Demonstrated",id:"key-features-demonstrated",level:2},{value:"1. External API Integration",id:"1-external-api-integration",level:3},{value:"2. Resource Management",id:"2-resource-management",level:3},{value:"3. Configuration Management",id:"3-configuration-management",level:3},{value:"4. Error Handling",id:"4-error-handling",level:3},{value:"5. Artifact Management",id:"5-artifact-management",level:3}];function d(e){const n={a:"a",admonition:"admonition",blockquote:"blockquote",code:"code",h1:"h1",h2:"h2",h3:"h3",header:"header",li:"li",ol:"ol",p:"p",pre:"pre",strong:"strong",ul:"ul",...(0,o.R)(),...e.components},{Details:t}=n;return t||function(e,n){throw new Error("Expected "+(n?"component":"object")+" `"+e+"` to be defined: you likely forgot to import, pass, or provide it.")}("Details",!0),(0,r.jsxs)(r.Fragment,{children:[(0,r.jsx)(n.header,{children:(0,r.jsx)(n.h1,{id:"build-your-own-agent",children:"Build Your Own Agent"})}),"\n",(0,r.jsx)(n.p,{children:"This tutorial shows you how to build a sophisticated weather agent using the Solace Agent Mesh framework. Learn how to integrate with external APIs, manage resources properly, and create production-ready agents."}),"\n",(0,r.jsx)(n.h2,{id:"overview",children:"Overview"}),"\n",(0,r.jsx)(n.p,{children:"Our weather agent will demonstrate:"}),"\n",(0,r.jsxs)(n.ul,{children:["\n",(0,r.jsx)(n.li,{children:"External API integration (OpenWeatherMap)"}),"\n",(0,r.jsx)(n.li,{children:"Professional service layer architecture"}),"\n",(0,r.jsx)(n.li,{children:"Multiple sophisticated tools"}),"\n",(0,r.jsx)(n.li,{children:"Proper lifecycle management"}),"\n",(0,r.jsx)(n.li,{children:"Error handling and validation"}),"\n",(0,r.jsx)(n.li,{children:"Artifact creation and management"}),"\n"]}),"\n",(0,r.jsx)(n.h2,{id:"prerequisites",children:"Prerequisites"}),"\n",(0,r.jsx)(n.p,{children:"Before starting this tutorial, make sure you have:"}),"\n",(0,r.jsxs)(n.ul,{children:["\n",(0,r.jsxs)(n.li,{children:["Read the ",(0,r.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/user-guide/create-agents",children:"Create Agent"})," tutorial"]}),"\n",(0,r.jsxs)(n.li,{children:["An OpenWeatherMap API key (free at ",(0,r.jsx)(n.a,{href:"https://openweathermap.org/api",children:"openweathermap.org"}),")"]}),"\n",(0,r.jsx)(n.li,{children:"Basic understanding of Python async/await"}),"\n",(0,r.jsx)(n.li,{children:"Familiarity with HTTP APIs"}),"\n"]}),"\n",(0,r.jsx)(n.h2,{id:"planning-the-weather-agent",children:"Planning the Weather Agent"}),"\n",(0,r.jsx)(n.p,{children:"Our weather agent will have the following capabilities:"}),"\n",(0,r.jsxs)(n.ol,{children:["\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"Get Current Weather"}),": Fetch current weather conditions for a specified location"]}),"\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"Get Weather Forecast"}),": Retrieve a multi-day weather forecast"]}),"\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"Save Weather Reports"}),": Store weather data as artifacts"]}),"\n"]}),"\n",(0,r.jsx)(n.p,{children:"The agent will demonstrate:"}),"\n",(0,r.jsxs)(n.ul,{children:["\n",(0,r.jsx)(n.li,{children:"External API integration"}),"\n",(0,r.jsx)(n.li,{children:"Error handling and validation"}),"\n",(0,r.jsx)(n.li,{children:"Configuration management"}),"\n",(0,r.jsx)(n.li,{children:"Artifact creation"}),"\n",(0,r.jsx)(n.li,{children:"Resource lifecycle management"}),"\n"]}),"\n",(0,r.jsx)(n.h2,{id:"step-1-project-structure",children:"Step 1: Project Structure"}),"\n",(0,r.jsx)(n.p,{children:"Run the following command to create a new custom agent:"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-bash",children:"sam add agent --gui\n"})}),"\n",(0,r.jsxs)(n.admonition,{type:"tip",children:[(0,r.jsxs)(n.p,{children:["You can create an agent either by using the ",(0,r.jsx)(n.code,{children:"sam add agent"})," command or by creating a new plugin of type agent, ",(0,r.jsx)(n.code,{children:"sam plugin create my-hello-agent --type agent"}),"."]}),(0,r.jsxs)(n.p,{children:["For information and recommendations about these options, see ",(0,r.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/concepts/plugins#agent-or-plugin-which-to-use",children:(0,r.jsx)(n.code,{children:"Agent or Plugin: Which To use?"})}),"."]}),(0,r.jsxs)(n.p,{children:["For an example of plugin agents, see the ",(0,r.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/user-guide/create-agents#step-1-initialize-your-agent",children:"Create Agents"})," guide."]})]}),"\n",(0,r.jsx)(n.p,{children:'Follow the steps on the GUI to create a new agent named "Weather Agent". We can update the tools/skills section directly in the configuration file later.'}),"\n",(0,r.jsxs)(n.admonition,{title:"Important Notice",type:"warning",children:[(0,r.jsx)(n.p,{children:"This tutorial is intentionally comprehensive to demonstrate the full flexibility and advanced features available in Solace Agent Mesh agents. For most straightforward use cases, you only need a simple Python function and a corresponding reference in your YAML configuration file."}),(0,r.jsxs)(t,{children:[(0,r.jsx)("summary",{children:"Simple Weather Agent Example"}),(0,r.jsxs)(n.p,{children:["After going through the add agent wizard from ",(0,r.jsx)(n.code,{children:"sam add agent --gui"}),", create the following file under ",(0,r.jsx)(n.code,{children:"src/weather_agent/tools.py"})," directory:"]}),(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-py",children:'# src/weather_agent/tools.py\nimport httpx\nfrom typing import Any, Dict, Optional\nfrom google.adk.tools import ToolContext\nfrom solace_ai_connector.common.log import log\n\n\nasync def get_current_weather(\n    location: str,\n    units: str = "metric",\n    tool_context: Optional[ToolContext] = None,\n    tool_config: Optional[Dict[str, Any]] = None\n) -> Dict[str, Any]:\n    """\n    Get current weather conditions for a specified location.\n    \n    Args:\n        location: City name, state, and country (for example, "New York, NY, US")\n        units: Temperature units - "metric" (Celsius), "imperial" (Fahrenheit), or "kelvin"\n    """\n    log.info("[GetCurrentWeather] Getting current weather for: %s", location)\n    base_url = "https://api.openweathermap.org/data/2.5"\n    api_key = tool_config.get("api_key") if tool_config else None\n\n    url = f"{base_url}/weather"\n    params = {\n        "q": location,\n        "appid": api_key,\n        "units": units\n    }\n\n    try:\n        # Fetch weather data\n        async with httpx.AsyncClient() as client:\n            response = await client.get(url, params=params)\n            response.raise_for_status()\n            weather_data = response.json()\n        \n        result = {\n            "status": "success",\n            "location": location,\n            "units": units,\n            "data": weather_data\n        }\n        return result\n    \n    except Exception as e:\n        log.error(f"[GetCurrentWeather] Error getting weather: {e}")\n        return {\n            "status": "error",\n            "message": f"Weather service error: {str(e)}"\n        }\n\n\nasync def get_weather_forecast(\n    location: str,\n    days: int = 5,\n    units: str = "metric",\n    tool_context: Optional[ToolContext] = None,\n    tool_config: Optional[Dict[str, Any]] = None\n) -> Dict[str, Any]:\n    """\n    Get weather forecast for a specified location.\n    \n    Args:\n        location: City name, state, and country\n        days: Number of days for forecast (1-5)\n        units: Temperature units\n    """\n    log.info("[GetWeatherForecast] Getting %d-day forecast for: %s", days, location)\n    base_url = "https://api.openweathermap.org/data/2.5"\n    api_key = tool_config.get("api_key") if tool_config else None\n\n    url = f"{base_url}/forecast"\n    params = {\n        "q": location,\n        "appid": api_key,\n        "units": units,\n        "cnt": min(days * 8, 40) \n    }\n\n    try:\n        # Fetch forecast data\n        async with httpx.AsyncClient() as client:\n            response = await client.get(url, params=params)\n            response.raise_for_status()\n            forecast_data = response.json()\n\n        result = {\n            "status": "success",\n            "location": forecast_data["location"],\n            "days": days,\n            "units": units,\n            "data": forecast_data\n        }\n        return result\n    except Exception as e:\n        log.error(f"[GetWeatherForecast] Error getting forecast: {e}")\n        return {\n            "status": "error",\n            "message": f"Weather service error: {str(e)}"\n        }\n\n'})}),(0,r.jsxs)(n.p,{children:["And update the weather agent config file's tool section under ",(0,r.jsx)(n.code,{children:"configs/agent/weather-agent.yaml"})," as follows:"]}),(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-yaml",children:'      # Tools configuration\n      tools:\n        # Current weather tool\n        - tool_type: python\n          component_module: "src.weather_agent.tools"\n          component_base_path: .\n          function_name: "get_current_weather"\n          tool_description: "Get current weather conditions for a specified location"\n          tool_config:\n            api_key: ${OPENWEATHER_API_KEY}\n\n        # Weather forecast tool\n        - tool_type: python\n          component_module: "src.weather_agent.tools"\n          function_name: "get_weather_forecast"\n          component_base_path: .\n          tool_description: "Get weather forecast for up to 5 days for a specified location"\n          tool_config:\n            api_key: ${OPENWEATHER_API_KEY}\n\n'})}),(0,r.jsxs)(n.p,{children:["For better discoverability, update the ",(0,r.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/concepts/agents#agent-card",children:"agent card"})," section in the same YAML file as follows:"]}),(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-yaml",children:'      # Agent card\n      agent_card:\n        description: "Professional weather agent providing current conditions, forecasts, and weather comparisons"\n        defaultInputModes: ["text"]\n        defaultOutputModes: ["text"]\n        skills:\n          - id: "get_current_weather"\n            name: "Get Current Weather"\n            description: "Retrieve current weather conditions for any location worldwide"\n          - id: "get_weather_forecast"\n            name: "Get Weather Forecast"\n            description: "Provide detailed weather forecasts up to 5 days ahead"\n'})}),(0,r.jsxs)(n.p,{children:["To run the agent, you can continue following documentation from ",(0,r.jsx)(n.a,{href:"#step-6-environment-setup",children:"Step 6"})," of this tutorial."]})]}),(0,r.jsx)(n.p,{children:"Other concepts mentioned in this page such as lifecycle, services, artifacts are just to showcase more advanced patterns."})]}),"\n",(0,r.jsx)(n.p,{children:"Create the directory structure for the weather agent:"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{children:"sam-project/\n\u251c\u2500\u2500 src/\n\u2502   \u2514\u2500\u2500 weather_agent/\n\u2502       \u251c\u2500\u2500 __init__.py\n\u2502       \u251c\u2500\u2500 tools.py\n\u2502       \u251c\u2500\u2500 lifecycle.py\n\u2502       \u2514\u2500\u2500 services/\n\u2502           \u251c\u2500\u2500 __init__.py\n\u2502           \u2514\u2500\u2500 weather_service.py\n\u251c\u2500\u2500 configs\n\u2502   \u2514\u2500\u2500 shared_config.yaml\n\u2502   \u2514\u2500\u2500 agents/\n\u2502       \u2514\u2500\u2500 weather_agent.yaml\n...\n"})}),"\n",(0,r.jsxs)(n.admonition,{type:"tip",children:[(0,r.jsxs)(n.p,{children:["IN Solace Agent Mesh, you can create an agent either by using the ",(0,r.jsx)(n.code,{children:"sam add agent"})," command or by creating a new plugin of type agent, ",(0,r.jsx)(n.code,{children:"sam plugin create your-agent --type agent"}),"."]}),(0,r.jsxs)(n.p,{children:["This tutorial uses the ",(0,r.jsx)(n.code,{children:"sam add agent"}),' command to create a new agent named "Weather Agent", for an example of creating a custom agent plugin, see the ',(0,r.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/user-guide/create-agents",children:"Create Agents"})," tutorial."]})]}),"\n",(0,r.jsx)(n.h2,{id:"step-2-weather-service-implementation",children:"Step 2: Weather Service Implementation"}),"\n",(0,r.jsx)(n.p,{children:"First, create a service class to handle weather API interactions:"}),"\n",(0,r.jsx)(n.p,{children:(0,r.jsxs)(n.strong,{children:[(0,r.jsx)(n.code,{children:"src/weather_agent/services/weather_service.py"}),":"]})}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-python",children:'"""\nWeather service for interacting with external weather APIs.\n"""\n\nimport aiohttp\nfrom typing import Dict, Any, Optional, List\nfrom datetime import datetime, timezone\nfrom solace_ai_connector.common.log import log\n\n\nclass WeatherService:\n    """Service for fetching weather data from external APIs."""\n    \n    def __init__(self, api_key: str, base_url: str = "https://api.openweathermap.org/data/2.5"):\n        self.api_key = api_key\n        self.base_url = base_url\n        self.session: Optional[aiohttp.ClientSession] = None\n        self.log_identifier = "[WeatherService]"\n    \n    async def _get_session(self) -> aiohttp.ClientSession:\n        """Get or create an HTTP session."""\n        if self.session is None or self.session.closed:\n            self.session = aiohttp.ClientSession()\n        return self.session\n    \n    async def close(self):\n        """Close the HTTP session."""\n        if self.session and not self.session.closed:\n            await self.session.close()\n            log.info(f"{self.log_identifier} HTTP session closed")\n    \n    async def get_current_weather(self, location: str, units: str = "metric") -> Dict[str, Any]:\n        """\n        Get current weather for a location.\n        \n        Args:\n            location: City name, state code, and country code (for example, "London,UK")\n            units: Temperature units (metric, imperial, kelvin)\n        \n        Returns:\n            Dictionary containing current weather data\n        """\n        log.info(f"{self.log_identifier} Fetching current weather for: {location}")\n        \n        session = await self._get_session()\n        url = f"{self.base_url}/weather"\n        params = {\n            "q": location,\n            "appid": self.api_key,\n            "units": units\n        }\n        \n        try:\n            async with session.get(url, params=params) as response:\n                if response.status == 200:\n                    data = await response.json()\n                    log.info(f"{self.log_identifier} Successfully fetched weather for {location}")\n                    return self._format_current_weather(data)\n                elif response.status == 404:\n                    raise ValueError(f"Location \'{location}\' not found")\n                else:\n                    error_data = await response.json()\n                    raise Exception(f"Weather API error: {error_data.get(\'message\', \'Unknown error\')}")\n        \n        except aiohttp.ClientError as e:\n            log.error(f"{self.log_identifier} Network error fetching weather: {e}")\n            raise Exception(f"Network error: {str(e)}")\n    \n    async def get_weather_forecast(self, location: str, days: int = 5, units: str = "metric") -> Dict[str, Any]:\n        """\n        Get weather forecast for a location.\n        \n        Args:\n            location: City name, state code, and country code\n            days: Number of days for forecast (1-5)\n            units: Temperature units\n        \n        Returns:\n            Dictionary containing forecast data\n        """\n        log.info(f"{self.log_identifier} Fetching {days}-day forecast for: {location}")\n        \n        session = await self._get_session()\n        url = f"{self.base_url}/forecast"\n        params = {\n            "q": location,\n            "appid": self.api_key,\n            "units": units,\n            "cnt": min(days * 8, 40)  # API returns 3-hour intervals, max 40 entries\n        }\n        \n        try:\n            async with session.get(url, params=params) as response:\n                if response.status == 200:\n                    data = await response.json()\n                    log.info(f"{self.log_identifier} Successfully fetched forecast for {location}")\n                    return self._format_forecast_data(data, days)\n                elif response.status == 404:\n                    raise ValueError(f"Location \'{location}\' not found")\n                else:\n                    error_data = await response.json()\n                    raise Exception(f"Weather API error: {error_data.get(\'message\', \'Unknown error\')}")\n        \n        except aiohttp.ClientError as e:\n            log.error(f"{self.log_identifier} Network error fetching forecast: {e}")\n            raise Exception(f"Network error: {str(e)}")\n    \n    def _format_current_weather(self, data: Dict) -> Dict[str, Any]:\n        """Format current weather data for consistent output."""\n        return {\n            "location": f"{data[\'name\']}, {data[\'sys\'][\'country\']}",\n            "temperature": data[\'main\'][\'temp\'],\n            "feels_like": data[\'main\'][\'feels_like\'],\n            "humidity": data[\'main\'][\'humidity\'],\n            "pressure": data[\'main\'][\'pressure\'],\n            "description": data[\'weather\'][0][\'description\'].title(),\n            "wind_speed": data.get(\'wind\', {}).get(\'speed\', 0),\n            "wind_direction": data.get(\'wind\', {}).get(\'deg\', 0),\n            "visibility": data.get(\'visibility\', 0) / 1000,  # Convert to km\n            "timestamp": datetime.fromtimestamp(data[\'dt\']).isoformat(),\n            "sunrise": datetime.fromtimestamp(data[\'sys\'][\'sunrise\']).isoformat(),\n            "sunset": datetime.fromtimestamp(data[\'sys\'][\'sunset\']).isoformat()\n        }\n    \n    def _format_forecast_data(self, data: Dict, days: int) -> Dict[str, Any]:\n        """Format forecast data for consistent output."""\n        forecasts = []\n        current_date = None\n        daily_data = []\n        \n        for item in data[\'list\'][:days * 8]:\n            forecast_date = datetime.fromtimestamp(item[\'dt\']).date()\n            \n            if current_date != forecast_date:\n                if daily_data:\n                    forecasts.append(self._aggregate_daily_forecast(daily_data))\n                current_date = forecast_date\n                daily_data = []\n            \n            daily_data.append(item)\n        \n        # Add the last day\'s data\n        if daily_data:\n            forecasts.append(self._aggregate_daily_forecast(daily_data))\n        \n        return {\n            "location": f"{data[\'city\'][\'name\']}, {data[\'city\'][\'country\']}",\n            "forecasts": forecasts[:days]\n        }\n    \n    def _aggregate_daily_forecast(self, daily_data: List[Dict]) -> Dict[str, Any]:\n        """Aggregate 3-hour forecasts into daily summary."""\n        if not daily_data:\n            return {}\n        \n        # Get temperatures for min/max calculation\n        temps = [item[\'main\'][\'temp\'] for item in daily_data]\n        \n        # Use the forecast closest to noon for general conditions\n        noon_forecast = min(daily_data, key=lambda x: abs(\n            datetime.fromtimestamp(x[\'dt\']).hour - 12\n        ))\n        \n        return {\n            "date": datetime.fromtimestamp(daily_data[0][\'dt\']).date().isoformat(),\n            "temperature_min": min(temps),\n            "temperature_max": max(temps),\n            "description": noon_forecast[\'weather\'][0][\'description\'].title(),\n            "humidity": noon_forecast[\'main\'][\'humidity\'],\n            "wind_speed": noon_forecast.get(\'wind\', {}).get(\'speed\', 0),\n            "precipitation_probability": noon_forecast.get(\'pop\', 0) * 100\n        }\n'})}),"\n",(0,r.jsx)(n.h2,{id:"step-3-weather-tools-implementation",children:"Step 3: Weather Tools Implementation"}),"\n",(0,r.jsx)(n.p,{children:"Now create the tool functions:"}),"\n",(0,r.jsx)(n.p,{children:(0,r.jsxs)(n.strong,{children:[(0,r.jsx)(n.code,{children:"src/weather_agent/tools.py"}),":"]})}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-python",children:'"""\nWeather agent tools for fetching and processing weather data.\n"""\n\nimport json\nfrom typing import Any, Dict, Optional\nfrom datetime import datetime, timezone\nfrom google.adk.tools import ToolContext\nfrom solace_ai_connector.common.log import log\nfrom solace_agent_mesh.agent.utils.artifact_helpers import save_artifact_with_metadata\n\nasync def get_current_weather(\n    location: str,\n    units: str = "metric",\n    save_to_file: bool = False,\n    tool_context: Optional[ToolContext] = None,\n    tool_config: Optional[Dict[str, Any]] = None\n) -> Dict[str, Any]:\n    """\n    Get current weather conditions for a specified location.\n    \n    Args:\n        location: City name, state, and country (for example, "New York, NY, US")\n        units: Temperature units - "metric" (Celsius), "imperial" (Fahrenheit), or "kelvin"\n        save_to_file: Whether to save the weather report as an artifact\n    \n    Returns:\n        Dictionary containing current weather information\n    """\n    log_identifier = "[GetCurrentWeather]"\n    log.info(f"{log_identifier} Getting current weather for: {location}")\n    \n    if not tool_context:\n        return {\n            "status": "error",\n            "message": "Tool context is required for weather operations"\n        }\n    \n    try:\n        # Get weather service from agent state\n        host_component = getattr(tool_context._invocation_context, "agent", None)\n        if host_component:\n            host_component = getattr(host_component, "host_component", None)\n        \n        if not host_component:\n            return {\n                "status": "error",\n                "message": "Could not access agent host component"\n            }\n        \n        weather_service = host_component.get_agent_specific_state("weather_service")\n        if not weather_service:\n            return {\n                "status": "error",\n                "message": "Weather service not initialized"\n            }\n        \n        # Fetch weather data\n        weather_data = await weather_service.get_current_weather(location, units)\n        \n        # Create human-readable summary\n        summary = _create_weather_summary(weather_data)\n        \n        result = {\n            "status": "success",\n            "location": weather_data["location"],\n            "summary": summary,\n            "data": weather_data\n        }\n        \n        # Save to artifact if requested\n        if save_to_file:\n            artifact_result = await _save_weather_artifact(\n                weather_data, f"current_weather_{location}", tool_context\n            )\n            result["artifact"] = artifact_result\n        \n        log.info(f"{log_identifier} Successfully retrieved weather for {location}")\n        return result\n    \n    except ValueError as e:\n        log.warning(f"{log_identifier} Invalid location: {e}")\n        return {\n            "status": "error",\n            "message": f"Location error: {str(e)}"\n        }\n    except Exception as e:\n        log.error(f"{log_identifier} Error getting weather: {e}")\n        return {\n            "status": "error",\n            "message": f"Weather service error: {str(e)}"\n        }\n\n\nasync def get_weather_forecast(\n    location: str,\n    days: int = 5,\n    units: str = "metric",\n    save_to_file: bool = False,\n    tool_context: Optional[ToolContext] = None,\n    tool_config: Optional[Dict[str, Any]] = None\n) -> Dict[str, Any]:\n    """\n    Get weather forecast for a specified location.\n    \n    Args:\n        location: City name, state, and country\n        days: Number of days for forecast (1-5)\n        units: Temperature units\n        save_to_file: Whether to save the forecast as an artifact\n    \n    Returns:\n        Dictionary containing weather forecast information\n    """\n    log_identifier = "[GetWeatherForecast]"\n    log.info(f"{log_identifier} Getting {days}-day forecast for: {location}")\n    \n    if not tool_context:\n        return {\n            "status": "error",\n            "message": "Tool context is required for weather operations"\n        }\n    \n    # Validate days parameter\n    if not 1 <= days <= 5:\n        return {\n            "status": "error",\n            "message": "Days must be between 1 and 5"\n        }\n    \n    try:\n        # Get weather service from agent state\n        host_component = getattr(tool_context._invocation_context, "agent", None)\n        if host_component:\n            host_component = getattr(host_component, "host_component", None)\n        \n        if not host_component:\n            return {\n                "status": "error",\n                "message": "Could not access agent host component"\n            }\n        \n        weather_service = host_component.get_agent_specific_state("weather_service")\n        if not weather_service:\n            return {\n                "status": "error",\n                "message": "Weather service not initialized"\n            }\n        \n        # Fetch forecast data\n        forecast_data = await weather_service.get_weather_forecast(location, days, units)\n        \n        # Create human-readable summary\n        summary = _create_forecast_summary(forecast_data)\n        \n        result = {\n            "status": "success",\n            "location": forecast_data["location"],\n            "summary": summary,\n            "data": forecast_data\n        }\n        \n        # Save to artifact if requested\n        if save_to_file:\n            artifact_result = await _save_weather_artifact(\n                forecast_data, f"forecast_{location}_{days}day", tool_context\n            )\n            result["artifact"] = artifact_result\n        \n        log.info(f"{log_identifier} Successfully retrieved forecast for {location}")\n        return result\n    \n    except ValueError as e:\n        log.warning(f"{log_identifier} Invalid location: {e}")\n        return {\n            "status": "error",\n            "message": f"Location error: {str(e)}"\n        }\n    except Exception as e:\n        log.error(f"{log_identifier} Error getting forecast: {e}")\n        return {\n            "status": "error",\n            "message": f"Weather service error: {str(e)}"\n        }\n\n\ndef _create_weather_summary(weather_data: Dict[str, Any]) -> str:\n    """Create a human-readable weather summary."""\n    temp_unit = "\xb0C"  # Assuming metric units for summary\n    \n    summary = f"Current weather in {weather_data[\'location\']}:\\n"\n    summary += f"\u2022 Temperature: {weather_data[\'temperature\']}{temp_unit} (feels like {weather_data[\'feels_like\']}{temp_unit})\\n"\n    summary += f"\u2022 Conditions: {weather_data[\'description\']}\\n"\n    summary += f"\u2022 Humidity: {weather_data[\'humidity\']}%\\n"\n    summary += f"\u2022 Wind: {weather_data[\'wind_speed\']} m/s\\n"\n    summary += f"\u2022 Visibility: {weather_data[\'visibility\']} km"\n    \n    return summary\n\n\ndef _create_forecast_summary(forecast_data: Dict[str, Any]) -> str:\n    """Create a human-readable forecast summary."""\n    summary = f"Weather forecast for {forecast_data[\'location\']}:\\n\\n"\n    \n    for forecast in forecast_data[\'forecasts\']:\n        date = datetime.fromisoformat(forecast[\'date\']).strftime(\'%A, %B %d\')\n        summary += f"\u2022 {date}: {forecast[\'description\']}\\n"\n        summary += f"  High: {forecast[\'temperature_max\']:.1f}\xb0C, Low: {forecast[\'temperature_min\']:.1f}\xb0C\\n"\n        if forecast[\'precipitation_probability\'] > 0:\n            summary += f"  Precipitation: {forecast[\'precipitation_probability\']:.0f}% chance\\n"\n        summary += "\\n"\n    \n    return summary.strip()\n\n\nasync def _save_weather_artifact(\n    weather_data: Dict[str, Any],\n    filename_base: str,\n    tool_context: ToolContext\n) -> Dict[str, Any]:\n    """Save weather data as an artifact."""\n    try:\n        # Prepare content\n        content = json.dumps(weather_data, indent=2, default=str)\n        timestamp = datetime.now(timezone.utc)\n        filename = f"{filename_base}_{timestamp.strftime(\'%Y%m%d_%H%M%S\')}.json"\n        \n        # Save artifact\n        artifact_service = tool_context._invocation_context.artifact_service\n        result = await save_artifact_with_metadata(\n            artifact_service=artifact_service,\n            app_name=tool_context._invocation_context.app_name,\n            user_id=tool_context._invocation_context.user_id,\n            session_id=tool_context._invocation_context.session.id,\n            filename=filename,\n            content_bytes=content.encode(\'utf-8\'),\n            mime_type="application/json",\n            metadata_dict={\n                "description": "Weather data report",\n                "source": "Weather Agent"\n            },\n            timestamp=timestamp\n        )\n        \n        return {\n            "filename": filename,\n            "status": result.get("status", "success")\n        }\n    \n    except Exception as e:\n        log.error(f"[WeatherArtifact] Error saving artifact: {e}")\n        return {\n            "status": "error",\n            "message": f"Failed to save artifact: {str(e)}"\n        }\n'})}),"\n",(0,r.jsx)(n.h2,{id:"step-4-lifecycle-functions",children:"Step 4: Lifecycle Functions"}),"\n",(0,r.jsx)(n.p,{children:"Create the lifecycle management:"}),"\n",(0,r.jsx)(n.p,{children:(0,r.jsxs)(n.strong,{children:[(0,r.jsx)(n.code,{children:"src/weather_agent/lifecycle.py"}),":"]})}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-python",children:'"""\nLifecycle functions for the Weather Agent.\n"""\n\nfrom typing import Any\nimport asyncio\nfrom pydantic import BaseModel, Field, SecretStr\nfrom solace_ai_connector.common.log import log\nfrom .services.weather_service import WeatherService\n\n\nclass WeatherAgentInitConfig(BaseModel):\n    """\n    Configuration model for Weather Agent initialization.\n    """\n    api_key: SecretStr = Field(description="OpenWeatherMap API key")\n    base_url: str = Field(\n        default="https://api.openweathermap.org/data/2.5",\n        description="Weather API base URL"\n    )\n    startup_message: str = Field(\n        default="Weather Agent is ready to provide weather information!",\n        description="Message to log on startup"\n    )\n\n\ndef initialize_weather_agent(host_component: Any, init_config: WeatherAgentInitConfig):\n    """\n    Initialize the Weather Agent with weather service.\n    \n    Args:\n        host_component: The agent host component\n        init_config: Validated initialization configuration\n    """\n    log_identifier = f"[{host_component.agent_name}:init]"\n    log.info(f"{log_identifier} Starting Weather Agent initialization...")\n    \n    try:\n        # Initialize weather service\n        weather_service = WeatherService(\n            api_key=init_config.api_key.get_secret_value(),\n            base_url=init_config.base_url\n        )\n        \n        # Store service in agent state\n        host_component.set_agent_specific_state("weather_service", weather_service)\n        \n        # Log startup message\n        log.info(f"{log_identifier} {init_config.startup_message}")\n        \n        # Store initialization metadata\n        host_component.set_agent_specific_state("initialized_at", "2024-01-01T00:00:00Z")\n        host_component.set_agent_specific_state("weather_requests_count", 0)\n        \n        log.info(f"{log_identifier} Weather Agent initialization completed successfully")\n    \n    except Exception as e:\n        log.error(f"{log_identifier} Failed to initialize Weather Agent: {e}")\n        raise\n\n\ndef cleanup_weather_agent(host_component: Any):\n    """\n    Clean up Weather Agent resources.\n    \n    Args:\n        host_component: The agent host component\n    """\n    log_identifier = f"[{host_component.agent_name}:cleanup]"\n    log.info(f"{log_identifier} Starting Weather Agent cleanup...")\n\n    async def cleanup_async(host_component: Any):\n        try:\n            # Get and close weather service\n            weather_service = host_component.get_agent_specific_state("weather_service")\n            if weather_service:\n                await weather_service.close()\n                log.info(f"{log_identifier} Weather service closed successfully")\n            \n            # Log final statistics\n            request_count = host_component.get_agent_specific_state("weather_requests_count", 0)\n            log.info(f"{log_identifier} Agent processed {request_count} weather requests during its lifetime")\n            \n            log.info(f"{log_identifier} Weather Agent cleanup completed")\n        \n        except Exception as e:\n            log.error(f"{log_identifier} Error during cleanup: {e}")\n    \n    # run cleanup in the event loop\n    loop = asyncio.get_event_loop()\n    loop.run_until_complete(cleanup_async(host_component))\n    log.info(f"{log_identifier} Weather Agent cleanup completed successfully")\n'})}),"\n",(0,r.jsx)(n.h2,{id:"step-5-agent-configuration",children:"Step 5: Agent Configuration"}),"\n",(0,r.jsx)(n.p,{children:"Create the comprehensive YAML configuration:"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-yaml",children:'# Weather Agent Configuration\nlog:\n  stdout_log_level: INFO\n  log_file_level: DEBUG\n  log_file: weather-agent.log\n\n!include ../shared_config.yaml\n\napps:\n  - name: weather-agent\n    # Broker configuration\n    app_module: solace_agent_mesh.agent.sac.app\n    broker:\n      <<: *broker_connection\n\n    app_config:\n      namespace: "${NAMESPACE}"\n      agent_name: "WeatherAgent"\n      display_name: "Weather Information Agent"\n      supports_streaming: true\n      \n      # LLM model configuration\n      model: *general_model\n      \n      # Agent instructions\n      instruction: |\n        You are a professional weather agent that provides accurate, up-to-date weather information.\n        \n        Your capabilities include:\n        1. Getting current weather conditions for any location worldwide\n        2. Providing detailed weather forecasts up to 5 days\n        3. Saving weather reports as files for future reference\n        \n        Guidelines:\n        - Always specify the location clearly when providing weather information\n        - Include relevant details like temperature, conditions, humidity, and wind\n        - Offer to save weather reports when providing detailed information\n        - Be helpful in suggesting appropriate clothing or activities based on weather\n        - If a location is ambiguous, ask for clarification (city, state/province, country)\n        \n        When users ask about weather, use the appropriate tools to fetch real-time data.\n        Present information in a clear, organized manner that\'s easy to understand.\n      \n      # Lifecycle functions\n      agent_init_function:\n        module: "src.weather_agent.lifecycle"\n        name: "initialize_weather_agent"\n        base_path: .\n        config:\n          api_key: ${OPENWEATHER_API_KEY}\n          base_url: "https://api.openweathermap.org/data/2.5"\n          startup_message: "Weather Agent is ready to provide weather information!"\n      \n      agent_cleanup_function:\n        module: "src.weather_agent.lifecycle"\n        base_path: .\n        name: "cleanup_weather_agent"\n      \n      # Tools configuration\n      tools:\n        # Current weather tool\n        - tool_type: python\n          component_module: "src.weather_agent.tools"\n          component_base_path: .\n          function_name: "get_current_weather"\n          tool_description: "Get current weather conditions for a specified location"\n        \n        # Weather forecast tool\n        - tool_type: python\n          component_module: "src.weather_agent.tools"\n          component_base_path: .\n          function_name: "get_weather_forecast"\n          tool_description: "Get weather forecast for up to 5 days for a specified location"\n        \n        # Built-in artifact tools for file operations\n        - tool_type: builtin-group\n          group_name: "artifact_management"\n    \n      session_service: *default_session_service\n      artifact_service: *default_artifact_service\n\n      artifact_handling_mode: "reference"\n      enable_embed_resolution: true\n      enable_artifact_content_instruction: true\n      # Agent card\n      agent_card:\n        description: "Professional weather agent providing current conditions, forecasts, and weather comparisons"\n        defaultInputModes: ["text"]\n        defaultOutputModes: ["text", "file"]\n        skills:\n          - id: "get_current_weather"\n            name: "Get Current Weather"\n            description: "Retrieve current weather conditions for any location worldwide"\n          - id: "get_weather_forecast"\n            name: "Get Weather Forecast"\n            description: "Provide detailed weather forecasts up to 5 days ahead"\n      \n      agent_card_publishing:\n        interval_seconds: 30\n\n      agent_discovery:\n        enabled: false\n\n      inter_agent_communication:\n        allow_list: []\n        request_timeout_seconds: 30\n'})}),"\n",(0,r.jsxs)(n.p,{children:["For more details on agent cards, see the ",(0,r.jsx)(n.a,{href:"/solace-agent-mesh/docs/documentation/concepts/agents#agent-card",children:"Agent Card Concepts"})," documentation."]}),"\n",(0,r.jsx)(n.h2,{id:"step-6-environment-setup",children:"Step 6: Environment Setup"}),"\n",(0,r.jsx)(n.p,{children:"Before running your weather agent, you'll need to:"}),"\n",(0,r.jsxs)(n.ol,{children:["\n",(0,r.jsxs)(n.li,{children:["\n",(0,r.jsxs)(n.p,{children:[(0,r.jsx)(n.strong,{children:"Get an OpenWeatherMap API key"}),":"]}),"\n",(0,r.jsxs)(n.ul,{children:["\n",(0,r.jsxs)(n.li,{children:["Sign up at ",(0,r.jsx)(n.a,{href:"https://openweathermap.org/api",children:"OpenWeatherMap"})]}),"\n",(0,r.jsx)(n.li,{children:"Get your free API key"}),"\n"]}),"\n"]}),"\n",(0,r.jsxs)(n.li,{children:["\n",(0,r.jsxs)(n.p,{children:[(0,r.jsx)(n.strong,{children:"Set environment variables"}),":"]}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-bash",children:'export OPENWEATHER_API_KEY="your_api_key_here"\n# Other environment variables as needed\n'})}),"\n"]}),"\n"]}),"\n",(0,r.jsx)(n.h2,{id:"step-7-running-the-agent",children:"Step 7: Running the Agent"}),"\n",(0,r.jsxs)(n.p,{children:["To start the agent, it is preferred to build the plugin and then install it with your agent name. But for debugging or isolated development testing, you can run your agent from the ",(0,r.jsx)(n.code,{children:"src"})," directory directly using the Solace Agent Mesh CLI."]}),"\n",(0,r.jsx)(n.p,{children:"Start your weather agent for development purposes run:"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-bash",children:"sam run\n"})}),"\n",(0,r.jsxs)(n.ul,{children:["\n",(0,r.jsxs)(n.li,{children:["To solely run the agent, use ",(0,r.jsx)(n.code,{children:"sam run configs/agents/weather_agent.yaml"})]}),"\n"]}),"\n",(0,r.jsx)(n.h2,{id:"step-8-testing-the-weather-agent",children:"Step 8: Testing the Weather Agent"}),"\n",(0,r.jsx)(n.p,{children:"You can test your weather agent with these example requests:"}),"\n",(0,r.jsx)(n.p,{children:(0,r.jsx)(n.strong,{children:"Current Weather:"})}),"\n",(0,r.jsxs)(n.blockquote,{children:["\n",(0,r.jsx)(n.p,{children:'"What\'s the current weather in New York City?"'}),"\n"]}),"\n",(0,r.jsx)(n.p,{children:(0,r.jsx)(n.strong,{children:"Weather Forecast:"})}),"\n",(0,r.jsxs)(n.blockquote,{children:["\n",(0,r.jsx)(n.p,{children:'"Can you give me a 5-day forecast for London, UK and save it to a file?"'}),"\n"]}),"\n",(0,r.jsx)(n.p,{children:(0,r.jsx)(n.strong,{children:"Weather with File Save:"})}),"\n",(0,r.jsxs)(n.blockquote,{children:["\n",(0,r.jsx)(n.p,{children:'"Get the current weather for Tokyo, Japan and save the report"'}),"\n"]}),"\n",(0,r.jsx)(n.h2,{id:"key-features-demonstrated",children:"Key Features Demonstrated"}),"\n",(0,r.jsx)(n.h3,{id:"1-external-api-integration",children:"1. External API Integration"}),"\n",(0,r.jsxs)(n.ul,{children:["\n",(0,r.jsx)(n.li,{children:"Proper HTTP session management"}),"\n",(0,r.jsx)(n.li,{children:"Error handling for network issues"}),"\n",(0,r.jsx)(n.li,{children:"API response transformation"}),"\n"]}),"\n",(0,r.jsx)(n.h3,{id:"2-resource-management",children:"2. Resource Management"}),"\n",(0,r.jsxs)(n.ul,{children:["\n",(0,r.jsx)(n.li,{children:"Lifecycle functions for initialization and cleanup"}),"\n",(0,r.jsx)(n.li,{children:"Shared service instances across tool calls"}),"\n",(0,r.jsx)(n.li,{children:"Proper resource disposal"}),"\n"]}),"\n",(0,r.jsx)(n.h3,{id:"3-configuration-management",children:"3. Configuration Management"}),"\n",(0,r.jsxs)(n.ul,{children:["\n",(0,r.jsx)(n.li,{children:"Pydantic models for type-safe configuration"}),"\n",(0,r.jsx)(n.li,{children:"Environment variable integration"}),"\n",(0,r.jsx)(n.li,{children:"Flexible tool configuration"}),"\n"]}),"\n",(0,r.jsx)(n.h3,{id:"4-error-handling",children:"4. Error Handling"}),"\n",(0,r.jsxs)(n.ul,{children:["\n",(0,r.jsx)(n.li,{children:"Comprehensive exception handling"}),"\n",(0,r.jsx)(n.li,{children:"User-friendly error messages"}),"\n",(0,r.jsx)(n.li,{children:"Logging for debugging"}),"\n"]}),"\n",(0,r.jsx)(n.h3,{id:"5-artifact-management",children:"5. Artifact Management"}),"\n",(0,r.jsxs)(n.ul,{children:["\n",(0,r.jsx)(n.li,{children:"Saving structured data as files"}),"\n",(0,r.jsx)(n.li,{children:"Metadata enrichment"}),"\n",(0,r.jsx)(n.li,{children:"File format handling"}),"\n"]})]})}function h(e={}){const{wrapper:n}={...(0,o.R)(),...e.components};return n?(0,r.jsx)(n,{...e,children:(0,r.jsx)(d,{...e})}):d(e)}},8453:(e,n,t)=>{t.d(n,{R:()=>i,x:()=>s});var a=t(6540);const r={},o=a.createContext(r);function i(e){const n=a.useContext(o);return a.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:i(e.components),a.createElement(o.Provider,{value:n},e.children)}}}]);