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

solace_agent_mesh/agent/protocol/protocol_llm.txt

@@ -0,0 +1,81 @@
+# DEVELOPER GUIDE: protocol
+
+## Quick Summary
+The `protocol` directory implements the core logic for Agent-to-Agent (A2A) communication. It handles receiving and processing requests, responses, and discovery messages (Agent Cards) over the Solace event mesh. It acts as the bridge between the A2A protocol and the underlying Google ADK execution environment.
+
+## Files Overview
+- `__init__.py` - Empty package initialization file
+- `event_handlers.py` - Contains the primary logic for handling all A2A protocol events, including routing incoming messages, managing task execution, and handling agent discovery
+
+## Developer API Reference
+
+### __init__.py
+**Purpose:** Standard Python package initialization file
+**Import:** `from solace_agent_mesh.agent.protocol import *`
+
+This is an empty package initialization file and has no public interfaces.
+
+### event_handlers.py
+**Purpose:** Central hub for processing all events related to the A2A protocol. Routes events to appropriate handlers and manages task lifecycle.
+**Import:** `from solace_agent_mesh.agent.protocol.event_handlers import process_event, handle_a2a_request, handle_agent_card_message, handle_a2a_response, publish_agent_card, handle_sam_event, cleanup_agent_session`
+
+**Functions:**
+- `process_event(component, event: Event) -> None` - Main event router that processes incoming events and delegates to specific handlers based on event type and topic
+- `handle_a2a_request(component, message: SolaceMessage) -> None` - Handles incoming A2A request messages, starts ADK runner for SendTask requests, and processes CancelTask requests
+- `handle_agent_card_message(component, message: SolaceMessage) -> None` - Processes incoming Agent Card discovery messages and updates peer agent registry
+- `handle_a2a_response(component, message: SolaceMessage) -> None` - Handles responses and status updates from peer agents, manages parallel task completion
+- `publish_agent_card(component) -> None` - Publishes the agent's capabilities and information to the discovery topic
+- `handle_sam_event(component, message: SolaceMessage, topic: str) -> None` - Handles incoming SAM system events like session deletion
+- `cleanup_agent_session(component, session_id: str, user_id: str) -> None` - Cleans up agent-side session data when sessions are deleted
+
+**Internal Helper Functions:**
+- `_register_peer_artifacts_in_parent_context(parent_task_context: "TaskExecutionContext", peer_task_object: Task, log_identifier: str) -> None` - Registers artifacts produced by peer agents in the parent task context
+- `_publish_peer_tool_result_notification(component: "SamAgentComponent", correlation_data: Dict[str, Any], payload_to_queue: Any, log_identifier: str) -> None` - Publishes a ToolResultData status update for a completed peer tool call
+
+**Usage Examples:**
+```python
+# Main event processing (typically called by the SAC framework)
+from solace_agent_mesh.agent.protocol.event_handlers import process_event
+from solace_ai_connector.common.event import Event, EventType
+
+# Process an incoming event
+await process_event(component, event)
+
+# Publish agent discovery card
+from solace_agent_mesh.agent.protocol.event_handlers import publish_agent_card
+
+publish_agent_card(component)
+
+# Handle specific message types (usually called internally by process_event)
+from solace_agent_mesh.agent.protocol.event_handlers import handle_a2a_request
+
+await handle_a2a_request(component, solace_message)
+
+# Handle SAM system events
+from solace_agent_mesh.agent.protocol.event_handlers import handle_sam_event
+
+handle_sam_event(component, message, topic)
+
+# Clean up session data
+from solace_agent_mesh.agent.protocol.event_handlers import cleanup_agent_session
+
+await cleanup_agent_session(component, "session_123", "user_456")
+```
+
+**Key Event Flow:**
+1. `process_event()` receives all events and routes based on type (MESSAGE, TIMER, CACHE_EXPIRY)
+2. For MESSAGE events, routes to specific handlers based on topic patterns:
+   - Agent request topics → `handle_a2a_request()`
+   - Discovery topics → `handle_agent_card_message()`
+   - Response/status topics → `handle_a2a_response()`
+   - SAM events topics → `handle_sam_event()`
+3. For TIMER events, handles periodic agent card publishing
+4. For CACHE_EXPIRY events, delegates to component's cache handling
+
+**Dependencies:**
+- Requires `SamAgentComponent` instance with proper configuration
+- Uses A2A protocol types from `a2a.types`
+- Integrates with Google ADK for task execution
+- Manages task contexts through `TaskExecutionContext`
+
+# content_hash: 02e6f51922fe92594201d9e7a07ae8469cad977a13297c53db5a75534ca1e9f7

solace_agent_mesh/agent/protocol/protocol_llm_detail.txt

@@ -0,0 +1,92 @@
+# LLM Summary Detail File
+
+This file is a concatenation of all individual *llm.txt files found in the 'protocol' directory tree. Each section below corresponds to a specific directory's summary file.
+
+================================================================================
+
+## Section 1: solace_agent_mesh/agent/protocol/protocol_llm.txt
+
+**Source file:** `solace_agent_mesh/agent/protocol/protocol_llm.txt`
+
+# DEVELOPER GUIDE: protocol
+
+## Quick Summary
+The `protocol` directory implements the core logic for Agent-to-Agent (A2A) communication. It handles receiving and processing requests, responses, and discovery messages (Agent Cards) over the Solace event mesh. It acts as the bridge between the A2A protocol and the underlying Google ADK execution environment.
+
+## Files Overview
+- `__init__.py` - Empty package initialization file
+- `event_handlers.py` - Contains the primary logic for handling all A2A protocol events, including routing incoming messages, managing task execution, and handling agent discovery
+
+## Developer API Reference
+
+### __init__.py
+**Purpose:** Standard Python package initialization file
+**Import:** `from solace_agent_mesh.agent.protocol import *`
+
+This is an empty package initialization file and has no public interfaces.
+
+### event_handlers.py
+**Purpose:** Central hub for processing all events related to the A2A protocol. Routes events to appropriate handlers and manages task lifecycle.
+**Import:** `from solace_agent_mesh.agent.protocol.event_handlers import process_event, handle_a2a_request, handle_agent_card_message, handle_a2a_response, publish_agent_card, handle_sam_event, cleanup_agent_session`
+
+**Functions:**
+- `process_event(component, event: Event) -> None` - Main event router that processes incoming events and delegates to specific handlers based on event type and topic
+- `handle_a2a_request(component, message: SolaceMessage) -> None` - Handles incoming A2A request messages, starts ADK runner for SendTask requests, and processes CancelTask requests
+- `handle_agent_card_message(component, message: SolaceMessage) -> None` - Processes incoming Agent Card discovery messages and updates peer agent registry
+- `handle_a2a_response(component, message: SolaceMessage) -> None` - Handles responses and status updates from peer agents, manages parallel task completion
+- `publish_agent_card(component) -> None` - Publishes the agent's capabilities and information to the discovery topic
+- `handle_sam_event(component, message: SolaceMessage, topic: str) -> None` - Handles incoming SAM system events like session deletion
+- `cleanup_agent_session(component, session_id: str, user_id: str) -> None` - Cleans up agent-side session data when sessions are deleted
+
+**Internal Helper Functions:**
+- `_register_peer_artifacts_in_parent_context(parent_task_context: "TaskExecutionContext", peer_task_object: Task, log_identifier: str) -> None` - Registers artifacts produced by peer agents in the parent task context
+- `_publish_peer_tool_result_notification(component: "SamAgentComponent", correlation_data: Dict[str, Any], payload_to_queue: Any, log_identifier: str) -> None` - Publishes a ToolResultData status update for a completed peer tool call
+
+**Usage Examples:**
+```python
+# Main event processing (typically called by the SAC framework)
+from solace_agent_mesh.agent.protocol.event_handlers import process_event
+from solace_ai_connector.common.event import Event, EventType
+
+# Process an incoming event
+await process_event(component, event)
+
+# Publish agent discovery card
+from solace_agent_mesh.agent.protocol.event_handlers import publish_agent_card
+
+publish_agent_card(component)
+
+# Handle specific message types (usually called internally by process_event)
+from solace_agent_mesh.agent.protocol.event_handlers import handle_a2a_request
+
+await handle_a2a_request(component, solace_message)
+
+# Handle SAM system events
+from solace_agent_mesh.agent.protocol.event_handlers import handle_sam_event
+
+handle_sam_event(component, message, topic)
+
+# Clean up session data
+from solace_agent_mesh.agent.protocol.event_handlers import cleanup_agent_session
+
+await cleanup_agent_session(component, "session_123", "user_456")
+```
+
+**Key Event Flow:**
+1. `process_event()` receives all events and routes based on type (MESSAGE, TIMER, CACHE_EXPIRY)
+2. For MESSAGE events, routes to specific handlers based on topic patterns:
+   - Agent request topics → `handle_a2a_request()`
+   - Discovery topics → `handle_agent_card_message()`
+   - Response/status topics → `handle_a2a_response()`
+   - SAM events topics → `handle_sam_event()`
+3. For TIMER events, handles periodic agent card publishing
+4. For CACHE_EXPIRY events, delegates to component's cache handling
+
+**Dependencies:**
+- Requires `SamAgentComponent` instance with proper configuration
+- Uses A2A protocol types from `a2a.types`
+- Integrates with Google ADK for task execution
+- Manages task contexts through `TaskExecutionContext`
+
+================================================================================
+

solace_agent_mesh/agent/proxies/a2a/__init__.py

@@ -0,0 +1,3 @@
+"""
+This package contains the concrete implementation for proxying standard A2A-over-HTTPS agents.
+"""

solace_agent_mesh/agent/proxies/a2a/a2a_llm.txt

@@ -0,0 +1,190 @@
+# DEVELOPER GUIDE: a2a
+
+## Quick Summary
+The `a2a` directory provides a concrete implementation for proxying standard A2A-over-HTTPS agents. It enables the Solace Agent Mesh to communicate with downstream agents that implement the A2A (Agent-to-Agent) protocol over HTTP/HTTPS, handling authentication, request forwarding, and response processing.
+
+## Files Overview
+- `__init__.py` - Package initialization for A2A-over-HTTPS proxy implementation
+- `app.py` - Main application class that validates A2A-specific configuration
+- `component.py` - Core proxy component that handles A2A protocol communication and request forwarding
+- `config.py` - Pydantic configuration models for A2A proxy settings and authentication
+- `oauth_token_cache.py` - OAuth 2.0 token caching system with automatic expiration
+
+## Developer API Reference
+
+### app.py
+**Purpose:** Provides the main application class for A2A proxy with configuration validation
+**Import:** `from solace_agent_mesh.agent.proxies.a2a.app import A2AProxyApp`
+
+**Classes:**
+- `A2AProxyApp(app_info: Dict[str, Any], **kwargs)` - Main A2A proxy application class
+  - Inherits from `BaseProxyApp` and adds A2A-specific configuration validation
+  - Validates authentication settings, URLs, and other A2A-specific parameters
+
+**Usage Examples:**
+```python
+from solace_agent_mesh.agent.proxies.a2a.app import A2AProxyApp
+
+# Create A2A proxy app with configuration
+app_info = {
+    "app_config": {
+        "proxied_agents": [
+            {
+                "name": "my-agent",
+                "url": "https://agent.example.com",
+                "authentication": {
+                    "type": "oauth2_client_credentials",
+                    "token_url": "https://auth.example.com/token",
+                    "client_id": "my-client-id",
+                    "client_secret": "my-secret"
+                }
+            }
+        ]
+    }
+}
+
+app = A2AProxyApp(app_info)
+```
+
+### component.py
+**Purpose:** Core component that handles A2A protocol communication, authentication, and request forwarding
+**Import:** `from solace_agent_mesh.agent.proxies.a2a.component import A2AProxyComponent`
+
+**Classes:**
+- `A2AProxyComponent(**kwargs: Any)` - Main proxy component for A2A-over-HTTPS agents
+  - `clear_client_cache() -> None` - Clears all cached A2A clients and OAuth tokens
+  - `cleanup() -> None` - Cleans up resources on component shutdown
+
+**Usage Examples:**
+```python
+from solace_agent_mesh.agent.proxies.a2a.component import A2AProxyComponent
+
+# Create component (typically done by the framework)
+component = A2AProxyComponent(
+    proxied_agents_config=[
+        {
+            "name": "my-agent",
+            "url": "https://agent.example.com",
+            "authentication": {
+                "type": "static_bearer",
+                "token": "my-bearer-token"
+            }
+        }
+    ]
+)
+
+# Clear cache if needed (useful for testing)
+component.clear_client_cache()
+
+# Cleanup when shutting down
+component.cleanup()
+```
+
+### config.py
+**Purpose:** Pydantic configuration models for A2A proxy settings and authentication validation
+**Import:** `from solace_agent_mesh.agent.proxies.a2a.config import A2AProxyAppConfig, AuthenticationConfig, A2AProxiedAgentConfig`
+
+**Classes:**
+- `AuthenticationConfig()` - Authentication configuration for downstream A2A agents
+  - `type: Optional[Literal["static_bearer", "static_apikey", "oauth2_client_credentials"]]` - Authentication type
+  - `token: Optional[str]` - Authentication token (for static types)
+  - `token_url: Optional[str]` - OAuth 2.0 token endpoint URL
+  - `client_id: Optional[str]` - OAuth 2.0 client identifier
+  - `client_secret: Optional[str]` - OAuth 2.0 client secret
+  - `scope: Optional[str]` - OAuth 2.0 scope string
+  - `token_cache_duration_seconds: int` - Token cache duration (default: 3300)
+
+- `A2AProxiedAgentConfig()` - Configuration for a single A2A agent
+  - `url: str` - Base URL of the downstream A2A agent
+  - `authentication: Optional[AuthenticationConfig]` - Authentication details
+
+- `A2AProxyAppConfig()` - Complete configuration for A2A proxy application
+  - `proxied_agents: List[A2AProxiedAgentConfig]` - List of agents to proxy
+
+**Usage Examples:**
+```python
+from solace_agent_mesh.agent.proxies.a2a.config import (
+    A2AProxyAppConfig, 
+    A2AProxiedAgentConfig, 
+    AuthenticationConfig
+)
+
+# OAuth 2.0 authentication
+oauth_auth = AuthenticationConfig(
+    type="oauth2_client_credentials",
+    token_url="https://auth.example.com/token",
+    client_id="my-client-id",
+    client_secret="my-secret",
+    scope="agent:read agent:write",
+    token_cache_duration_seconds=3300
+)
+
+# Static bearer token authentication
+bearer_auth = AuthenticationConfig(
+    type="static_bearer",
+    token="my-bearer-token"
+)
+
+# Agent configuration
+agent_config = A2AProxiedAgentConfig(
+    name="my-agent",
+    url="https://agent.example.com",
+    authentication=oauth_auth
+)
+
+# Complete app configuration
+app_config = A2AProxyAppConfig(
+    proxied_agents=[agent_config]
+)
+
+# Validate configuration
+validated_config = A2AProxyAppConfig.model_validate({
+    "proxied_agents": [
+        {
+            "name": "test-agent",
+            "url": "https://agent.example.com",
+            "authentication": {
+                "type": "static_bearer",
+                "token": "abc123"
+            }
+        }
+    ]
+})
+```
+
+### oauth_token_cache.py
+**Purpose:** Thread-safe OAuth 2.0 token caching with automatic expiration
+**Import:** `from solace_agent_mesh.agent.proxies.a2a.oauth_token_cache import OAuth2TokenCache, CachedToken`
+
+**Classes:**
+- `CachedToken(access_token: str, expires_at: float)` - Represents a cached token with expiration
+  - `access_token: str` - The OAuth 2.0 access token
+  - `expires_at: float` - Unix timestamp when token expires
+
+- `OAuth2TokenCache()` - Thread-safe in-memory cache for OAuth tokens
+  - `get(agent_name: str) -> Optional[str]` - Retrieves cached token if valid
+  - `set(agent_name: str, access_token: str, cache_duration_seconds: int) -> None` - Caches token with expiration
+  - `invalidate(agent_name: str) -> None` - Removes token from cache
+
+**Usage Examples:**
+```python
+from solace_agent_mesh.agent.proxies.a2a.oauth_token_cache import OAuth2TokenCache
+
+# Create token cache
+cache = OAuth2TokenCache()
+
+# Cache a token for 1 hour
+await cache.set("my-agent", "access_token_123", 3600)
+
+# Retrieve cached token
+token = await cache.get("my-agent")
+if token:
+    print(f"Using cached token: {token}")
+else:
+    print("No valid cached token found")
+
+# Invalidate cached token
+await cache.invalidate("my-agent")
+```
+
+# content_hash: 7bb671773b0ece239704f18e12a92ac5dc3f97dd0ebb154ac56f53e0d277a1b7

solace_agent_mesh/agent/proxies/a2a/app.py

@@ -0,0 +1,56 @@
+"""
+Concrete App class for the A2A-over-HTTPS proxy.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Type
+
+from pydantic import ValidationError
+from solace_ai_connector.common.log import log
+
+from ..base.app import BaseProxyApp
+from ..base.component import BaseProxyComponent
+from .component import A2AProxyComponent
+from .config import A2AProxyAppConfig
+
+info = {
+    "class_name": "A2AProxyApp",
+}
+
+
+class A2AProxyApp(BaseProxyApp):
+    """
+    Concrete App class for the A2A-over-HTTPS proxy.
+
+    Extends the BaseProxyApp to add specific configuration validation for
+    A2A agents (e.g., URL, authentication).
+    """
+
+    # Keep app_schema for documentation purposes, but it's now redundant
+    # The Pydantic models handle all validation
+    app_schema = {}
+
+    def __init__(self, app_info: Dict[str, Any], **kwargs):
+        app_info["class_name"] = "A2AProxyApp"
+        
+        # Validate A2A-specific configuration before calling super().__init__
+        app_config_dict = app_info.get("app_config", {})
+        try:
+            # Validate with A2A-specific config model
+            app_config = A2AProxyAppConfig.model_validate_and_clean(app_config_dict)
+            # Overwrite the raw dict with the validated object
+            app_info["app_config"] = app_config
+            log.debug("A2A proxy configuration validated successfully.")
+        except ValidationError as e:
+            message = A2AProxyAppConfig.format_validation_error_message(e, app_info['name'])
+            log.error("Invalid A2A Proxy configuration:\n%s", message)
+            raise
+        
+        super().__init__(app_info, **kwargs)
+
+    def _get_component_class(self) -> Type[BaseProxyComponent]:
+        """
+        Returns the concrete A2AProxyComponent class.
+        """
+        return A2AProxyComponent