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

solace_agent_mesh/agent/utils/utils_llm.txt

@@ -1,138 +0,0 @@
-## Quick Summary
-The `utils` directory provides a collection of helper modules designed to support the core functionality of the agent. These utilities encapsulate common, reusable logic for tasks such as artifact management (saving, loading, schema inference), configuration parsing, and safe interaction with the ADK's invocation context.
-
-## Files Overview
-- `__init__.py` - Empty package marker file
-- `artifact_helpers.py` - Comprehensive artifact management functions including save/load operations, metadata handling, and schema inference
-- `config_parser.py` - Configuration parsing utilities for resolving instruction providers
-- `context_helpers.py` - Safe utilities for extracting data from ADK callback and invocation contexts
-
-## Developer API Reference
-
-### artifact_helpers.py
-**Purpose:** Comprehensive artifact management with automatic metadata generation, schema inference, and async operations
-**Import:** `from solace_agent_mesh.agent.utils.artifact_helpers import save_artifact_with_metadata, load_artifact_content_or_metadata, get_artifact_info_list, is_filename_safe, ensure_correct_extension`
-
-**Functions:**
-- `is_filename_safe(filename: str) -> bool` - Validates filename safety (no path traversal, separators, or reserved names)
-- `ensure_correct_extension(filename_from_llm: str, desired_extension: str) -> str` - Ensures filename has correct extension
-- `format_artifact_uri(app_name: str, user_id: str, session_id: str, filename: str, version: Union[int, str]) -> str` - Formats components into standard artifact:// URI
-- `parse_artifact_uri(uri: str) -> Dict[str, Any]` - Parses artifact:// URI into constituent parts
-- `save_artifact_with_metadata(artifact_service: BaseArtifactService, app_name: str, user_id: str, session_id: str, filename: str, content_bytes: bytes, mime_type: str, metadata_dict: Dict[str, Any], timestamp: datetime, explicit_schema: Optional[Dict] = None, schema_inference_depth: int = 2, schema_max_keys: int = 20, tool_context: Optional["ToolContext"] = None) -> Dict[str, Any]` - Saves artifact with auto-generated metadata and schema inference
-- `load_artifact_content_or_metadata(artifact_service: BaseArtifactService, app_name: str, user_id: str, session_id: str, filename: str, version: Union[int, str], load_metadata_only: bool = False, return_raw_bytes: bool = False, max_content_length: Optional[int] = None, component: Optional[Any] = None, log_identifier_prefix: str = "[ArtifactHelper:load]", encoding: str = "utf-8", error_handling: str = "strict") -> Dict[str, Any]` - Loads artifact content or metadata with flexible options
-- `get_artifact_info_list(artifact_service: BaseArtifactService, app_name: str, user_id: str, session_id: str) -> List[ArtifactInfo]` - Retrieves detailed info for all artifacts
-- `get_latest_artifact_version(artifact_service: BaseArtifactService, app_name: str, user_id: str, session_id: str, filename: str) -> Optional[int]` - Gets latest version number for an artifact
-- `format_metadata_for_llm(metadata: Dict[str, Any]) -> str` - Formats metadata into LLM-friendly text
-- `decode_and_get_bytes(content_str: str, mime_type: str, log_identifier: str) -> Tuple[bytes, str]` - Decodes content based on MIME type (base64 for binary, UTF-8 for text)
-- `generate_artifact_metadata_summary(component: "SamAgentComponent", artifact_identifiers: List[Dict[str, Any]], user_id: str, session_id: str, app_name: str, header_text: Optional[str] = None) -> str` - Generates YAML summary of multiple artifacts' metadata
-
-**Constants/Variables:**
-- `METADATA_SUFFIX: str` - Suffix for metadata files (".metadata.json")
-- `DEFAULT_SCHEMA_MAX_KEYS: int` - Default max keys for schema inference (20)
-
-**Usage Examples:**
-```python
-import asyncio
-from datetime import datetime, timezone
-from solace_agent_mesh.agent.utils.artifact_helpers import (
-    save_artifact_with_metadata,
-    load_artifact_content_or_metadata,
-    get_artifact_info_list,
-    ensure_correct_extension,
-    format_artifact_uri,
-    parse_artifact_uri
-)
-
-async def artifact_example():
-    # Ensure safe filename
-    safe_name = ensure_correct_extension("report", "csv")  # -> "report.csv"
-    
-    # Save artifact with metadata
-    csv_data = b"name,age\nAlice,30\nBob,25"
-    result = await save_artifact_with_metadata(
-        artifact_service=service,
-        app_name="my_app",
-        user_id="user123",
-        session_id="session456",
-        filename=safe_name,
-        content_bytes=csv_data,
-        mime_type="text/csv",
-        metadata_dict={"source": "user_upload", "description": "Employee data"},
-        timestamp=datetime.now(timezone.utc)
-    )
-    
-    # Load artifact content
-    loaded = await load_artifact_content_or_metadata(
-        artifact_service=service,
-        app_name="my_app",
-        user_id="user123", 
-        session_id="session456",
-        filename=safe_name,
-        version="latest"
-    )
-    
-    # Work with artifact URIs
-    uri = format_artifact_uri("my_app", "user123", "session456", "report.csv", 1)
-    # Returns: "artifact://my_app/user123/session456/report.csv?version=1"
-    
-    parsed = parse_artifact_uri(uri)
-    # Returns: {"app_name": "my_app", "user_id": "user123", ...}
-    
-    # List all artifacts
-    artifacts = await get_artifact_info_list(
-        artifact_service=service,
-        app_name="my_app",
-        user_id="user123",
-        session_id="session456"
-    )
-```
-
-### config_parser.py
-**Purpose:** Resolves configuration values that can be static strings or dynamic callable providers
-**Import:** `from solace_agent_mesh.agent.utils.config_parser import resolve_instruction_provider, InstructionProvider`
-
-**Functions:**
-- `resolve_instruction_provider(component, config_value: Any) -> Union[str, InstructionProvider]` - Resolves instruction config from string or invoke block
-
-**Usage Examples:**
-```python
-from solace_agent_mesh.agent.utils.config_parser import resolve_instruction_provider
-
-# Static string instruction
-instruction = resolve_instruction_provider(component, "You are a helpful assistant.")
-# Returns: "You are a helpful assistant."
-
-# Dynamic instruction provider (from YAML invoke block)
-def dynamic_instruction(context):
-    return f"Assistant for {context.user_id}"
-
-instruction_func = resolve_instruction_provider(component, dynamic_instruction)
-# Returns: the callable function
-```
-
-### context_helpers.py
-**Purpose:** Safe utilities for extracting information from ADK contexts
-**Import:** `from solace_agent_mesh.agent.utils.context_helpers import get_session_from_callback_context, get_original_session_id`
-
-**Functions:**
-- `get_session_from_callback_context(callback_context: CallbackContext) -> Session` - Safely extracts Session object from CallbackContext
-- `get_original_session_id(invocation_context: Any) -> str` - Extracts base session ID, removing any colon-separated suffixes
-
-**Usage Examples:**
-```python
-from solace_agent_mesh.agent.utils.context_helpers import (
-    get_session_from_callback_context,
-    get_original_session_id
-)
-
-# In a tool function with callback_context
-def my_tool(callback_context):
-    # Get full session object
-    session = get_session_from_callback_context(callback_context)
-    
-    # Get original session ID (strips suffixes after colon)
-    original_id = get_original_session_id(tool_context._invocation_context)
-    # "session123:tool456" -> "session123"
-```
-
-# content_hash: a47bd4722e780a6a8146c6913cb0cbb053515a6f17dac92171ba79aef00d61b0

solace_agent_mesh/agent/utils/utils_llm_detail.txt

@@ -1,149 +0,0 @@
-# LLM Summary Detail File
-
-This file is a concatenation of all individual *llm.txt files found in the 'utils' directory tree. Each section below corresponds to a specific directory's summary file.
-
-================================================================================
-
-## Section 1: solace_agent_mesh/agent/utils/utils_llm.txt
-
-**Source file:** `solace_agent_mesh/agent/utils/utils_llm.txt`
-
-## Quick Summary
-The `utils` directory provides a collection of helper modules designed to support the core functionality of the agent. These utilities encapsulate common, reusable logic for tasks such as artifact management (saving, loading, schema inference), configuration parsing, and safe interaction with the ADK's invocation context.
-
-## Files Overview
-- `__init__.py` - Empty package marker file
-- `artifact_helpers.py` - Comprehensive artifact management functions including save/load operations, metadata handling, and schema inference
-- `config_parser.py` - Configuration parsing utilities for resolving instruction providers
-- `context_helpers.py` - Safe utilities for extracting data from ADK callback and invocation contexts
-
-## Developer API Reference
-
-### artifact_helpers.py
-**Purpose:** Comprehensive artifact management with automatic metadata generation, schema inference, and async operations
-**Import:** `from solace_agent_mesh.agent.utils.artifact_helpers import save_artifact_with_metadata, load_artifact_content_or_metadata, get_artifact_info_list, is_filename_safe, ensure_correct_extension`
-
-**Functions:**
-- `is_filename_safe(filename: str) -> bool` - Validates filename safety (no path traversal, separators, or reserved names)
-- `ensure_correct_extension(filename_from_llm: str, desired_extension: str) -> str` - Ensures filename has correct extension
-- `format_artifact_uri(app_name: str, user_id: str, session_id: str, filename: str, version: Union[int, str]) -> str` - Formats components into standard artifact:// URI
-- `parse_artifact_uri(uri: str) -> Dict[str, Any]` - Parses artifact:// URI into constituent parts
-- `save_artifact_with_metadata(artifact_service: BaseArtifactService, app_name: str, user_id: str, session_id: str, filename: str, content_bytes: bytes, mime_type: str, metadata_dict: Dict[str, Any], timestamp: datetime, explicit_schema: Optional[Dict] = None, schema_inference_depth: int = 2, schema_max_keys: int = 20, tool_context: Optional["ToolContext"] = None) -> Dict[str, Any]` - Saves artifact with auto-generated metadata and schema inference
-- `load_artifact_content_or_metadata(artifact_service: BaseArtifactService, app_name: str, user_id: str, session_id: str, filename: str, version: Union[int, str], load_metadata_only: bool = False, return_raw_bytes: bool = False, max_content_length: Optional[int] = None, component: Optional[Any] = None, log_identifier_prefix: str = "[ArtifactHelper:load]", encoding: str = "utf-8", error_handling: str = "strict") -> Dict[str, Any]` - Loads artifact content or metadata with flexible options
-- `get_artifact_info_list(artifact_service: BaseArtifactService, app_name: str, user_id: str, session_id: str) -> List[ArtifactInfo]` - Retrieves detailed info for all artifacts
-- `get_latest_artifact_version(artifact_service: BaseArtifactService, app_name: str, user_id: str, session_id: str, filename: str) -> Optional[int]` - Gets latest version number for an artifact
-- `format_metadata_for_llm(metadata: Dict[str, Any]) -> str` - Formats metadata into LLM-friendly text
-- `decode_and_get_bytes(content_str: str, mime_type: str, log_identifier: str) -> Tuple[bytes, str]` - Decodes content based on MIME type (base64 for binary, UTF-8 for text)
-- `generate_artifact_metadata_summary(component: "SamAgentComponent", artifact_identifiers: List[Dict[str, Any]], user_id: str, session_id: str, app_name: str, header_text: Optional[str] = None) -> str` - Generates YAML summary of multiple artifacts' metadata
-
-**Constants/Variables:**
-- `METADATA_SUFFIX: str` - Suffix for metadata files (".metadata.json")
-- `DEFAULT_SCHEMA_MAX_KEYS: int` - Default max keys for schema inference (20)
-
-**Usage Examples:**
-```python
-import asyncio
-from datetime import datetime, timezone
-from solace_agent_mesh.agent.utils.artifact_helpers import (
-    save_artifact_with_metadata,
-    load_artifact_content_or_metadata,
-    get_artifact_info_list,
-    ensure_correct_extension,
-    format_artifact_uri,
-    parse_artifact_uri
-)
-
-async def artifact_example():
-    # Ensure safe filename
-    safe_name = ensure_correct_extension("report", "csv")  # -> "report.csv"
-    
-    # Save artifact with metadata
-    csv_data = b"name,age\nAlice,30\nBob,25"
-    result = await save_artifact_with_metadata(
-        artifact_service=service,
-        app_name="my_app",
-        user_id="user123",
-        session_id="session456",
-        filename=safe_name,
-        content_bytes=csv_data,
-        mime_type="text/csv",
-        metadata_dict={"source": "user_upload", "description": "Employee data"},
-        timestamp=datetime.now(timezone.utc)
-    )
-    
-    # Load artifact content
-    loaded = await load_artifact_content_or_metadata(
-        artifact_service=service,
-        app_name="my_app",
-        user_id="user123", 
-        session_id="session456",
-        filename=safe_name,
-        version="latest"
-    )
-    
-    # Work with artifact URIs
-    uri = format_artifact_uri("my_app", "user123", "session456", "report.csv", 1)
-    # Returns: "artifact://my_app/user123/session456/report.csv?version=1"
-    
-    parsed = parse_artifact_uri(uri)
-    # Returns: {"app_name": "my_app", "user_id": "user123", ...}
-    
-    # List all artifacts
-    artifacts = await get_artifact_info_list(
-        artifact_service=service,
-        app_name="my_app",
-        user_id="user123",
-        session_id="session456"
-    )
-```
-
-### config_parser.py
-**Purpose:** Resolves configuration values that can be static strings or dynamic callable providers
-**Import:** `from solace_agent_mesh.agent.utils.config_parser import resolve_instruction_provider, InstructionProvider`
-
-**Functions:**
-- `resolve_instruction_provider(component, config_value: Any) -> Union[str, InstructionProvider]` - Resolves instruction config from string or invoke block
-
-**Usage Examples:**
-```python
-from solace_agent_mesh.agent.utils.config_parser import resolve_instruction_provider
-
-# Static string instruction
-instruction = resolve_instruction_provider(component, "You are a helpful assistant.")
-# Returns: "You are a helpful assistant."
-
-# Dynamic instruction provider (from YAML invoke block)
-def dynamic_instruction(context):
-    return f"Assistant for {context.user_id}"
-
-instruction_func = resolve_instruction_provider(component, dynamic_instruction)
-# Returns: the callable function
-```
-
-### context_helpers.py
-**Purpose:** Safe utilities for extracting information from ADK contexts
-**Import:** `from solace_agent_mesh.agent.utils.context_helpers import get_session_from_callback_context, get_original_session_id`
-
-**Functions:**
-- `get_session_from_callback_context(callback_context: CallbackContext) -> Session` - Safely extracts Session object from CallbackContext
-- `get_original_session_id(invocation_context: Any) -> str` - Extracts base session ID, removing any colon-separated suffixes
-
-**Usage Examples:**
-```python
-from solace_agent_mesh.agent.utils.context_helpers import (
-    get_session_from_callback_context,
-    get_original_session_id
-)
-
-# In a tool function with callback_context
-def my_tool(callback_context):
-    # Get full session object
-    session = get_session_from_callback_context(callback_context)
-    
-    # Get original session ID (strips suffixes after colon)
-    original_id = get_original_session_id(tool_context._invocation_context)
-    # "session123:tool456" -> "session123"
-```
-
-================================================================================
-

solace_agent_mesh/assets/docs/assets/js/15ba94aa.932dd2db.js

@@ -1 +0,0 @@
-"use strict";(self.webpackChunksolace_agenitc_mesh_docs=self.webpackChunksolace_agenitc_mesh_docs||[]).push([[7791],{8634:(e,t,n)=>{n.r(t),n.d(t,{assets:()=>c,contentTitle:()=>r,default:()=>h,frontMatter:()=>i,metadata:()=>s,toc:()=>l});const s=JSON.parse('{"id":"documentation/getting-started/architecture","title":"Architecture Overview","description":"Agent Mesh is an event-driven framework that creates a distributed ecosystem of collaborative AI agents. The architecture decouples agent logic from communication and orchestration, enabling you to build scalable, resilient, and modular AI systems.","source":"@site/docs/documentation/getting-started/architecture.md","sourceDirName":"documentation/getting-started","slug":"/documentation/getting-started/architecture","permalink":"/solace-agent-mesh/docs/documentation/getting-started/architecture","draft":false,"unlisted":false,"editUrl":"https://github.com/SolaceLabs/solace-agent-mesh/edit/main/docs/docs/documentation/getting-started/architecture.md","tags":[],"version":"current","sidebarPosition":18,"frontMatter":{"title":"Architecture Overview","sidebar_position":18},"sidebar":"docSidebar","previous":{"title":"Try Agent Mesh","permalink":"/solace-agent-mesh/docs/documentation/getting-started/try-agent-mesh"},"next":{"title":"Components","permalink":"/solace-agent-mesh/docs/documentation/components/"}}');var a=n(4848),o=n(8453);const i={title:"Architecture Overview",sidebar_position:18},r=void 0,c={},l=[{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 and Agents",id:"agent-hosts-and-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={a:"a",code:"code",h2:"h2",h3:"h3",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,o.R)(),...e.components};return(0,a.jsxs)(a.Fragment,{children:[(0,a.jsx)(t.p,{children:"Agent Mesh is an event-driven framework that creates a distributed ecosystem of collaborative AI agents. The architecture decouples agent logic from communication and orchestration, enabling you to build scalable, resilient, and modular AI systems."}),"\n",(0,a.jsx)(t.p,{children:"The framework integrates three primary technologies:"}),"\n",(0,a.jsxs)(t.ul,{children:["\n",(0,a.jsxs)(t.li,{children:[(0,a.jsx)(t.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,a.jsxs)(t.li,{children:[(0,a.jsx)(t.strong,{children:"Solace AI Connector (SAC)"}),": Serves as the runtime environment for hosting and managing the lifecycle of all system components"]}),"\n",(0,a.jsxs)(t.li,{children:[(0,a.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,a.jsx)(t.h2,{id:"architectural-principles",children:"Architectural Principles"}),"\n",(0,a.jsx)(t.p,{children:"The design of Agent Mesh is founded on several key architectural principles:"}),"\n",(0,a.jsxs)(t.ul,{children:["\n",(0,a.jsxs)(t.li,{children:[(0,a.jsx)(t.strong,{children:"Event-Driven Architecture (EDA)"}),": All interactions between major components are asynchronous and mediated by the Solace event broker. This eliminates direct dependencies, allowing components to be developed, deployed, and scaled independently."]}),"\n",(0,a.jsxs)(t.li,{children:[(0,a.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,a.jsxs)(t.li,{children:[(0,a.jsx)(t.strong,{children:"Scalability and Resilience"}),": The architecture supports horizontal scaling of Agent Hosts and Gateways. The Solace event broker provides fault tolerance and guaranteed message delivery, ensuring system resilience even if individual components fail or are restarted."]}),"\n"]}),"\n",(0,a.jsx)(t.h2,{id:"system-components",children:"System Components"}),"\n",(0,a.jsxs)(t.p,{children:["The architecture comprises several distinct types of components that interact through the Solace Event Broker. External systems connect through gateways, which translate requests into the A2A protocol, while agent hosts run individual agents that can communicate with each other and access backend services like LLMs and databases. For detailed information about each component, see ",(0,a.jsx)(t.a,{href:"/solace-agent-mesh/docs/documentation/components/",children:"Components"}),". The architecture diagram below illustrates how these components work together."]}),"\n",(0,a.jsx)(t.mermaid,{value:'graph TB\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 ["Agent Mesh"]\n        direction TB\n        subgraph Gateways\n            WebUIGateway("Web UI Gateway")\n            CustomGateway("Custom Gateway")\n        end\n\n        Broker("Solace Event 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        direction TB\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\n    %% Styling\n    classDef externalBoxes fill:#FFF7C2,stroke:#03213B,stroke-width:2px,color:#03213B;\n    classDef gatewayContainer fill:#F4F4F4,stroke:#03213B,stroke-width:2px,color:#03213B;\n    classDef gatewayBoxes fill:#C2F7FF,stroke:#03213B,stroke-width:2px,color:#03213B;\n    classDef mesh fill:#E8FFF0,stroke:#03213B,stroke-width:2px,color:#03213B;\n    classDef broker fill:#00C895,stroke:#03213B,stroke-width:2px,color:#03213B;\n    classDef agentContainer fill:#F4F4F4,stroke:#03213B,stroke-width:2px,color:#03213B;\n    classDef agentBoxes fill:#C2F7FF,stroke:#03213B,stroke-width:2px,color:#03213B;\n    classDef serviceBoxes fill:#FFF7C2,stroke:#03213B,stroke-width:2px,color:#03213B\n\n    class UserInterfaces,APIs externalBoxes;\n    class WebUIGateway,CustomGateway gatewayBoxes;\n    class Gateways gatewayContainer;\n    class Broker broker;\n    class SolaceAgentMesh mesh;\n    class AgentHosts agentContainer;\n    class AgentHost1,AgentHost2,AgentHostN agentBoxes;\n    class LLM,CustomTools,DataStores,ArtifactService serviceBoxes;'}),"\n",(0,a.jsx)(t.h3,{id:"solace-event-broker",children:"Solace Event Broker"}),"\n",(0,a.jsxs)(t.p,{children:["The Solace Event Broker serves as the central messaging fabric that enables all communication within the agent mesh. It routes A2A protocol messages between components using a hierarchical topic structure, supporting patterns like request/reply, streaming updates, and publish/subscribe for agent discovery. For more information about the event broker, see (solace.com)[",(0,a.jsx)(t.a,{href:"https://solace.com/products/event-broker/",children:"https://solace.com/products/event-broker/"}),"]"]}),"\n",(0,a.jsx)(t.h3,{id:"gateways",children:"Gateways"}),"\n",(0,a.jsx)(t.p,{children:"Gateways are SAC applications that act as bridges between external systems and the agent mesh. They handle protocol translation, converting external protocols (such as HTTP, WebSockets, or Slack RTM) into the standardized A2A protocol and vice versa. Gateways also manage authentication and authorization, authenticate incoming requests, and use a pluggable AuthorizationService to retrieve user permission scopes. Additionally, they manage external user sessions and map them to A2A task lifecycles, while handling asynchronous responses and status updates from agents."}),"\n",(0,a.jsxs)(t.p,{children:["The Gateway Development Kit (GDK) provides BaseGatewayApp and BaseGatewayComponent classes that abstract common gateway logic, including A2A protocol handling, agent discovery, and late-stage embed resolution. For more information about gateways, see ",(0,a.jsx)(t.a,{href:"/solace-agent-mesh/docs/documentation/components/gateways",children:"Gateways"}),"."]}),"\n",(0,a.jsx)(t.h3,{id:"agent-hosts-and-agents",children:"Agent Hosts and Agents"}),"\n",(0,a.jsx)(t.p,{children:"An Agent Host is a SAC application (SamAgentApp) that hosts a single ADK-based agent. It manages the lifecycle of the ADK Runner and LlmAgent, handles A2A protocol translation between incoming requests and ADK Task objects, enforces permission scopes by filtering available tools, and initializes ADK services like the ArtifactService and MemoryService."}),"\n",(0,a.jsxs)(t.p,{children:["An agent is the logical entity within an Agent Host that performs tasks. Each agent is defined by its configuration, which includes instructions that define its persona and capabilities, LLM configuration specifying which large language model to use, and a toolset containing built-in tools, custom Python functions, or MCP Toolsets. For more information about agents, see ",(0,a.jsx)(t.a,{href:"/solace-agent-mesh/docs/documentation/components/agents",children:"Agents"}),"."]}),"\n",(0,a.jsx)(t.h2,{id:"key-architectural-flows",children:"Key Architectural Flows"}),"\n",(0,a.jsx)(t.p,{children:"The following flows illustrate how data moves through the system and demonstrate the relationships between components in the event-driven architecture."}),"\n",(0,a.jsx)(t.h3,{id:"user-task-processing-flow",children:"User Task Processing Flow"}),"\n",(0,a.jsx)(t.p,{children:"When you submit a request through any gateway, the system processes it through several stages:"}),"\n",(0,a.jsxs)(t.ol,{children:["\n",(0,a.jsx)(t.li,{children:"An external client sends a request to a gateway"}),"\n",(0,a.jsx)(t.li,{children:"The gateway authenticates the request, retrieves your permission scopes via its AuthorizationService, and translates the request into an A2A task message, including the scopes in the Solace message's user properties"}),"\n",(0,a.jsx)(t.li,{children:"The gateway publishes the message to the target agent's request topic on the Solace Broker"}),"\n",(0,a.jsx)(t.li,{children:"The corresponding Agent Host receives the message, with the SamAgentComponent extracting the scopes and initiating an ADK task"}),"\n",(0,a.jsx)(t.li,{children:"The ADK LlmAgent processes the task, with a before_model_callback filtering the available tools based on your scopes before invoking the LLM"}),"\n",(0,a.jsx)(t.li,{children:"As the agent executes, the SamAgentComponent translates ADK events into A2A status and artifact update messages, publishing them to the originating gateway's status topic"}),"\n",(0,a.jsx)(t.li,{children:"The gateway receives these streaming updates, performs any necessary late-stage processing (such as resolving artifact_content embeds), and forwards them to you"}),"\n",(0,a.jsx)(t.li,{children:"Upon completion, the Agent Host sends a final A2A response message to the gateway, which delivers it to you"}),"\n"]}),"\n",(0,a.jsx)(t.h3,{id:"agent-to-agent-delegation-flow",children:"Agent-to-Agent Delegation Flow"}),"\n",(0,a.jsx)(t.p,{children:"Agents can delegate subtasks to other agents while maintaining security context:"}),"\n",(0,a.jsxs)(t.ol,{children:["\n",(0,a.jsx)(t.li,{children:"Agent A, while processing a task, determines that a subtask should be delegated to Agent B"}),"\n",(0,a.jsx)(t.li,{children:"Agent A uses its PeerAgentTool to construct a new A2A task request for Agent B, propagating the original user's permission scopes to maintain the security context"}),"\n",(0,a.jsx)(t.li,{children:"The request is published to Agent B's request topic"}),"\n",(0,a.jsx)(t.li,{children:"Agent B's Host receives and processes the subtask, enforcing the propagated scopes on its own toolset"}),"\n",(0,a.jsx)(t.li,{children:"Agent B sends status updates and a final response to topics designated by Agent A"}),"\n",(0,a.jsx)(t.li,{children:"Agent A receives the results and incorporates them into its ongoing task"}),"\n"]}),"\n",(0,a.jsx)(t.h3,{id:"agent-discovery-flow",children:"Agent Discovery Flow"}),"\n",(0,a.jsx)(t.p,{children:"The system automatically discovers available agents through a publish-subscribe mechanism:"}),"\n",(0,a.jsxs)(t.ol,{children:["\n",(0,a.jsx)(t.li,{children:"On startup and periodically, each Agent Host publishes an AgentCard (a JSON document describing its agent's capabilities) to a well-known discovery topic"}),"\n",(0,a.jsx)(t.li,{children:"Gateways and other Agent Hosts subscribe to this topic"}),"\n",(0,a.jsx)(t.li,{children:"Upon receiving an AgentCard, components update their local AgentRegistry, making them aware of available agents for user selection (at gateways) or peer delegation (at agents)"}),"\n"]}),"\n",(0,a.jsx)(t.h2,{id:"a2a-protocol-and-topic-structure",children:"A2A Protocol and Topic Structure"}),"\n",(0,a.jsx)(t.p,{children:"The A2A protocol is based on JSON-RPC 2.0 and defines the message formats for all interactions between components. Communication is routed via a hierarchical topic structure on the Solace event broker, which allows for precise, point-to-point routing in a decoupled, asynchronous environment."}),"\n",(0,a.jsxs)(t.table,{children:[(0,a.jsx)(t.thead,{children:(0,a.jsxs)(t.tr,{children:[(0,a.jsx)(t.th,{children:"Purpose"}),(0,a.jsx)(t.th,{children:"Topic Pattern"})]})}),(0,a.jsxs)(t.tbody,{children:[(0,a.jsxs)(t.tr,{children:[(0,a.jsx)(t.td,{children:(0,a.jsx)(t.strong,{children:"Agent Discovery"})}),(0,a.jsx)(t.td,{children:(0,a.jsx)(t.code,{children:"{namespace}/a2a/v1/discovery/agentcards"})})]}),(0,a.jsxs)(t.tr,{children:[(0,a.jsx)(t.td,{children:(0,a.jsx)(t.strong,{children:"Task Requests"})}),(0,a.jsx)(t.td,{children:(0,a.jsx)(t.code,{children:"{namespace}/a2a/v1/agent/request/{target_agent_name}"})})]}),(0,a.jsxs)(t.tr,{children:[(0,a.jsx)(t.td,{children:(0,a.jsx)(t.strong,{children:"Status Updates"})}),(0,a.jsx)(t.td,{children:(0,a.jsx)(t.code,{children:"{namespace}/a2a/v1/gateway/status/{gateway_id}/{task_id}"})})]}),(0,a.jsxs)(t.tr,{children:[(0,a.jsx)(t.td,{children:(0,a.jsx)(t.strong,{children:"Final Responses"})}),(0,a.jsx)(t.td,{children:(0,a.jsx)(t.code,{children:"{namespace}/a2a/v1/gateway/response/{gateway_id}/{task_id}"})})]}),(0,a.jsxs)(t.tr,{children:[(0,a.jsx)(t.td,{children:(0,a.jsx)(t.strong,{children:"Peer Delegation Status"})}),(0,a.jsx)(t.td,{children:(0,a.jsx)(t.code,{children:"{namespace}/a2a/v1/agent/status/{delegating_agent_name}/{sub_task_id}"})})]}),(0,a.jsxs)(t.tr,{children:[(0,a.jsx)(t.td,{children:(0,a.jsx)(t.strong,{children:"Peer Delegation Response"})}),(0,a.jsx)(t.td,{children:(0,a.jsx)(t.code,{children:"{namespace}/a2a/v1/agent/response/{delegating_agent_name}/{sub_task_id}"})})]})]})]}),"\n",(0,a.jsxs)(t.p,{children:["For more information about the CLI tools that help you work with these components, see ",(0,a.jsx)(t.a,{href:"/solace-agent-mesh/docs/documentation/components/cli",children:"CLI"}),". To learn about extending the system with custom functionality, see ",(0,a.jsx)(t.a,{href:"/solace-agent-mesh/docs/documentation/components/plugins",children:"Plugins"}),"."]})]})}function h(e={}){const{wrapper:t}={...(0,o.R)(),...e.components};return t?(0,a.jsx)(t,{...e,children:(0,a.jsx)(d,{...e})}):d(e)}},8453:(e,t,n)=>{n.d(t,{R:()=>i,x:()=>r});var s=n(6540);const a={},o=s.createContext(a);function i(e){const t=s.useContext(o);return s.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(a):e.components||a:i(e.components),s.createElement(o.Provider,{value:t},e.children)}}}]);