solace-agent-mesh 0.2.3__py3-none-any.whl → 1.0.1__py3-none-any.whl

solace_agent_mesh/assets/docs/assets/js/165.6a39807d.js.LICENSE.txt

@@ -0,0 +1,9 @@
+/*!
+Embeddable Minimum Strictly-Compliant Promises/A+ 1.1.1 Thenable
+Copyright (c) 2013-2014 Ralf S. Engelschall (http://engelschall.com)
+Licensed under The MIT License (http://opensource.org/licenses/MIT)
+*/
+
+/*! Bezier curve function generator. Copyright Gaetan Renaudeau. MIT License: http://en.wikipedia.org/wiki/MIT_License */
+
+/*! Runge-Kutta spring physics function generator. Adapted from Framer.js, copyright Koen Bok. MIT License: http://en.wikipedia.org/wiki/MIT_License */

solace_agent_mesh/assets/docs/assets/js/166ab619.7d97ccaf.js

@@ -0,0 +1 @@
+"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[515],{644:(e,t,s)=>{s.r(t),s.d(t,{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":"Component Overview","permalink":"/solace-agent-mesh/docs/documentation/getting-started/component-overview"},"next":{"title":"Solace Agent Mesh CLI","permalink":"/solace-agent-mesh/docs/documentation/concepts/cli"}}');var i=s(4848),r=s(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 PubSub+ Event Broker",id:"solace-pubsub-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 t={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)(t.header,{children:(0,i.jsx)(t.h1,{id:"solace-agent-mesh-architecture",children:"Solace Agent Mesh Architecture"})}),"\n",(0,i.jsx)(t.h2,{id:"overview",children:"Overview"}),"\n",(0,i.jsx)(t.p,{children:"The 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)(t.p,{children:"It integrates three primary technologies:"}),"\n",(0,i.jsxs)(t.ul,{children:["\n",(0,i.jsxs)(t.li,{children:[(0,i.jsx)(t.strong,{children:"Solace PubSub+ 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)(t.li,{children:[(0,i.jsx)(t.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)(t.li,{children:[(0,i.jsx)(t.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)(t.h2,{id:"architectural-principles",children:"Architectural Principles"}),"\n",(0,i.jsx)(t.p,{children:"The design of the Solace Agent Mesh is founded on several key architectural principles:"}),"\n",(0,i.jsxs)(t.ul,{children:["\n",(0,i.jsxs)(t.li,{children:[(0,i.jsx)(t.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)(t.li,{children:[(0,i.jsx)(t.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)(t.li,{children:[(0,i.jsx)(t.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)(t.h2,{id:"system-components",children:"System Components"}),"\n",(0,i.jsx)(t.p,{children:"The architecture comprises several distinct types of components that interact through the Solace PubSub+ broker."}),"\n",(0,i.jsx)(t.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 PubSub+ 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)(t.h3,{id:"solace-pubsub-event-broker",children:"Solace PubSub+ Event Broker"}),"\n",(0,i.jsx)(t.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)(t.h3,{id:"gateways",children:"Gateways"}),"\n",(0,i.jsx)(t.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)(t.ul,{children:["\n",(0,i.jsxs)(t.li,{children:[(0,i.jsx)(t.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)(t.li,{children:[(0,i.jsx)(t.strong,{children:"Authentication and Authorization"}),": Authenticate incoming requests and, using a pluggable ",(0,i.jsx)(t.code,{children:"AuthorizationService"}),", retrieve the user's permission scopes."]}),"\n",(0,i.jsxs)(t.li,{children:[(0,i.jsx)(t.strong,{children:"Session Management"}),": Manage external user sessions and map them to A2A task lifecycles."]}),"\n",(0,i.jsxs)(t.li,{children:[(0,i.jsx)(t.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)(t.p,{children:["The ",(0,i.jsx)(t.strong,{children:"Gateway Development Kit (GDK)"})," provides ",(0,i.jsx)(t.code,{children:"BaseGatewayApp"})," and ",(0,i.jsx)(t.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)(t.h3,{id:"agent-hosts",children:"Agent Hosts"}),"\n",(0,i.jsxs)(t.p,{children:["An Agent Host is a SAC application (",(0,i.jsx)(t.code,{children:"SamAgentApp"}),") that hosts a single ADK-based agent. Its key architectural functions include:"]}),"\n",(0,i.jsxs)(t.ul,{children:["\n",(0,i.jsxs)(t.li,{children:[(0,i.jsx)(t.strong,{children:"Hosting the ADK Runtime"}),": It manages the lifecycle of the ADK ",(0,i.jsx)(t.code,{children:"Runner"})," and ",(0,i.jsx)(t.code,{children:"LlmAgent"}),"."]}),"\n",(0,i.jsxs)(t.li,{children:[(0,i.jsx)(t.strong,{children:"A2A Protocol Handling"}),": The internal ",(0,i.jsx)(t.code,{children:"SamAgentComponent"})," translates incoming A2A requests into ADK ",(0,i.jsx)(t.code,{children:"Task"})," objects and converts ADK ",(0,i.jsx)(t.code,{children:"Event"})," objects into outgoing A2A ",(0,i.jsx)(t.code,{children:"TaskStatusUpdateEvent"}),", ",(0,i.jsx)(t.code,{children:"TaskArtifactUpdateEvent"}),", or final response messages."]}),"\n",(0,i.jsxs)(t.li,{children:[(0,i.jsx)(t.strong,{children:"Scope Enforcement"}),": It extracts permission scopes from incoming message properties and filters the agent's available tools accordingly."]}),"\n",(0,i.jsxs)(t.li,{children:[(0,i.jsx)(t.strong,{children:"Service Initialization"}),": It initializes ADK services like the ",(0,i.jsx)(t.code,{children:"ArtifactService"})," and ",(0,i.jsx)(t.code,{children:"MemoryService"})," based on its configuration."]}),"\n"]}),"\n",(0,i.jsx)(t.h3,{id:"agents",children:"Agents"}),"\n",(0,i.jsx)(t.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)(t.ul,{children:["\n",(0,i.jsxs)(t.li,{children:[(0,i.jsx)(t.strong,{children:"Instructions"}),": The base prompt that defines its persona, capabilities, and constraints."]}),"\n",(0,i.jsxs)(t.li,{children:[(0,i.jsx)(t.strong,{children:"LLM Configuration"}),": The specific large language model to use."]}),"\n",(0,i.jsxs)(t.li,{children:[(0,i.jsx)(t.strong,{children:"Toolset"}),": A collection of available tools, which can be built-in, custom Python functions, or MCP Toolsets."]}),"\n"]}),"\n",(0,i.jsx)(t.h2,{id:"key-architectural-flows",children:"Key Architectural Flows"}),"\n",(0,i.jsx)(t.h3,{id:"user-task-processing-flow",children:"User Task Processing Flow"}),"\n",(0,i.jsxs)(t.ol,{children:["\n",(0,i.jsxs)(t.li,{children:["An external client sends a request to a ",(0,i.jsx)(t.strong,{children:"Gateway"}),"."]}),"\n",(0,i.jsxs)(t.li,{children:["The Gateway authenticates the request, retrieves the user's permission scopes via its ",(0,i.jsx)(t.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)(t.li,{children:["The Gateway publishes the message to the target agent's request topic on the ",(0,i.jsx)(t.strong,{children:"Solace Broker"}),"."]}),"\n",(0,i.jsxs)(t.li,{children:["The corresponding ",(0,i.jsx)(t.strong,{children:"Agent Host"})," receives the message. The ",(0,i.jsx)(t.code,{children:"SamAgentComponent"})," extracts the scopes and initiates an ADK task."]}),"\n",(0,i.jsxs)(t.li,{children:["The ADK ",(0,i.jsx)(t.code,{children:"LlmAgent"})," processes the task. Before invoking the LLM, a ",(0,i.jsx)(t.code,{children:"before_model_callback"})," filters the available tools based on the user's scopes."]}),"\n",(0,i.jsxs)(t.li,{children:["As the agent executes, the ",(0,i.jsx)(t.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)(t.li,{children:["The Gateway receives these streaming updates, performs any necessary late-stage processing (like resolving ",(0,i.jsx)(t.code,{children:"artifact_content"})," embeds), and forwards them to the client."]}),"\n",(0,i.jsx)(t.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)(t.h3,{id:"agent-to-agent-delegation-flow",children:"Agent-to-Agent Delegation Flow"}),"\n",(0,i.jsxs)(t.ol,{children:["\n",(0,i.jsxs)(t.li,{children:[(0,i.jsx)(t.strong,{children:"Agent A"}),", while processing a task, determines a sub-task should be delegated to ",(0,i.jsx)(t.strong,{children:"Agent B"}),"."]}),"\n",(0,i.jsxs)(t.li,{children:["Agent A uses its ",(0,i.jsx)(t.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)(t.li,{children:"The request is published to Agent B's request topic."}),"\n",(0,i.jsxs)(t.li,{children:[(0,i.jsx)(t.strong,{children:"Agent B's Host"})," receives and processes the sub-task, enforcing the propagated scopes on its own toolset."]}),"\n",(0,i.jsx)(t.li,{children:"Agent B sends status updates and a final response to topics designated by Agent A."}),"\n",(0,i.jsx)(t.li,{children:"Agent A receives the results and incorporates them into its ongoing task."}),"\n"]}),"\n",(0,i.jsx)(t.h3,{id:"agent-discovery-flow",children:"Agent Discovery Flow"}),"\n",(0,i.jsxs)(t.ol,{children:["\n",(0,i.jsxs)(t.li,{children:["On startup and periodically, each ",(0,i.jsx)(t.strong,{children:"Agent Host"})," publishes an ",(0,i.jsx)(t.code,{children:"AgentCard"})," (a JSON document describing its agent's capabilities) to a well-known discovery topic (for example, ",(0,i.jsx)(t.code,{children:"{namespace}/a2a/v1/discovery/agentcards"}),")."]}),"\n",(0,i.jsxs)(t.li,{children:[(0,i.jsx)(t.strong,{children:"Gateways"})," and other ",(0,i.jsx)(t.strong,{children:"Agent Hosts"})," subscribe to this topic."]}),"\n",(0,i.jsxs)(t.li,{children:["Upon receiving an ",(0,i.jsx)(t.code,{children:"AgentCard"}),", components update their local ",(0,i.jsx)(t.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)(t.h2,{id:"a2a-protocol-and-topic-structure",children:"A2A Protocol and Topic Structure"}),"\n",(0,i.jsx)(t.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)(t.table,{children:[(0,i.jsx)(t.thead,{children:(0,i.jsxs)(t.tr,{children:[(0,i.jsx)(t.th,{children:"Purpose"}),(0,i.jsx)(t.th,{children:"Topic Pattern"})]})}),(0,i.jsxs)(t.tbody,{children:[(0,i.jsxs)(t.tr,{children:[(0,i.jsx)(t.td,{children:(0,i.jsx)(t.strong,{children:"Agent Discovery"})}),(0,i.jsx)(t.td,{children:(0,i.jsx)(t.code,{children:"{namespace}/a2a/v1/discovery/agentcards"})})]}),(0,i.jsxs)(t.tr,{children:[(0,i.jsx)(t.td,{children:(0,i.jsx)(t.strong,{children:"Task Requests"})}),(0,i.jsx)(t.td,{children:(0,i.jsx)(t.code,{children:"{namespace}/a2a/v1/agent/request/{target_agent_name}"})})]}),(0,i.jsxs)(t.tr,{children:[(0,i.jsx)(t.td,{children:(0,i.jsx)(t.strong,{children:"Status Updates"})}),(0,i.jsx)(t.td,{children:(0,i.jsx)(t.code,{children:"{namespace}/a2a/v1/gateway/status/{gateway_id}/{task_id}"})})]}),(0,i.jsxs)(t.tr,{children:[(0,i.jsx)(t.td,{children:(0,i.jsx)(t.strong,{children:"Final Responses"})}),(0,i.jsx)(t.td,{children:(0,i.jsx)(t.code,{children:"{namespace}/a2a/v1/gateway/response/{gateway_id}/{task_id}"})})]}),(0,i.jsxs)(t.tr,{children:[(0,i.jsx)(t.td,{children:(0,i.jsx)(t.strong,{children:"Peer Delegation Status"})}),(0,i.jsx)(t.td,{children:(0,i.jsx)(t.code,{children:"{namespace}/a2a/v1/agent/status/{delegating_agent_name}/{sub_task_id}"})})]}),(0,i.jsxs)(t.tr,{children:[(0,i.jsx)(t.td,{children:(0,i.jsx)(t.strong,{children:"Peer Delegation Response"})}),(0,i.jsx)(t.td,{children:(0,i.jsx)(t.code,{children:"{namespace}/a2a/v1/agent/response/{delegating_agent_name}/{sub_task_id}"})})]})]})]}),"\n",(0,i.jsx)(t.p,{children:"This topic structure allows for precise, point-to-point routing in a decoupled, asynchronous environment."})]})}function h(e={}){const{wrapper:t}={...(0,r.R)(),...e.components};return t?(0,i.jsx)(t,{...e,children:(0,i.jsx)(d,{...e})}):d(e)}},8453:(e,t,s)=>{s.d(t,{R:()=>o,x:()=>a});var n=s(6540);const i={},r=n.createContext(i);function o(e){const t=n.useContext(r);return n.useMemo((function(){return"function"==typeof e?e(t):{...t,...e}}),[t,e])}function a(e){let t;return t=e.disableParentContext?"function"==typeof e.components?e.components(i):e.components||i:o(e.components),n.createElement(r.Provider,{value:t},e.children)}}}]);