solace-agent-mesh 1.6.3__py3-none-any.whl → 1.7.1__py3-none-any.whl

solace_agent_mesh/agent/proxies/proxies_llm.txt

@@ -0,0 +1,283 @@
+# DEVELOPER GUIDE: proxies
+
+## Quick Summary
+The `proxies` directory provides a framework for creating proxy applications that enable the Solace Agent Mesh to communicate with downstream agents using various protocols. It consists of protocol-agnostic base classes in the `base/` subdirectory that handle common functionality like message routing, agent discovery, and task management, plus concrete implementations like `a2a/` for A2A-over-HTTPS protocol support.
+
+## Files and Subdirectories Overview
+- **Direct files:** 
+  - `__init__.py` - Empty package initialization file
+- **Subdirectories:**
+  - `base/` - Abstract base classes for proxy applications and components with common functionality
+  - `a2a/` - Concrete implementation for proxying A2A-over-HTTPS agents with authentication support
+
+## Developer API Reference
+
+### Direct Files
+
+#### __init__.py
+**Purpose:** Package initialization (empty file)
+**Import:** `from solace_agent_mesh.agent.proxies import *`
+
+No public API - this is an empty initialization file.
+
+### Subdirectory APIs
+
+#### base/
+**Purpose:** Provides abstract base classes and configuration models for building proxy applications
+**Key Exports:** BaseProxyApp, BaseProxyComponent, BaseProxyAppConfig, ProxyTaskContext
+**Import Examples:**
+```python
+from solace_agent_mesh.agent.proxies.base.app import BaseProxyApp
+from solace_agent_mesh.agent.proxies.base.component import BaseProxyComponent
+from solace_agent_mesh.agent.proxies.base.config import BaseProxyAppConfig, ProxiedAgentConfig
+from solace_agent_mesh.agent.proxies.base.proxy_task_context import ProxyTaskContext
+```
+
+#### a2a/
+**Purpose:** Concrete implementation for proxying A2A-over-HTTPS agents with OAuth 2.0 and static authentication
+**Key Exports:** A2AProxyApp, A2AProxyComponent, A2AProxyAppConfig, OAuth2TokenCache
+**Import Examples:**
+```python
+from solace_agent_mesh.agent.proxies.a2a.app import A2AProxyApp
+from solace_agent_mesh.agent.proxies.a2a.component import A2AProxyComponent
+from solace_agent_mesh.agent.proxies.a2a.config import A2AProxyAppConfig, AuthenticationConfig
+from solace_agent_mesh.agent.proxies.a2a.oauth_token_cache import OAuth2TokenCache
+```
+
+## Complete Usage Guide
+
+### 1. Creating a Custom Proxy Implementation
+
+To create a new proxy for a different protocol, extend the base classes:
+
+```python
+from solace_agent_mesh.agent.proxies.base.app import BaseProxyApp
+from solace_agent_mesh.agent.proxies.base.component import BaseProxyComponent
+from solace_agent_mesh.agent.proxies.base.config import BaseProxyAppConfig
+from a2a.types import AgentCard, A2ARequest
+from typing import Optional
+
+# Custom configuration (extend BaseProxyAppConfig)
+class MyProxyAppConfig(BaseProxyAppConfig):
+    custom_setting: str = "default_value"
+
+# Custom component implementation
+class MyProxyComponent(BaseProxyComponent):
+    async def _fetch_agent_card(self, agent_config: dict) -> Optional[AgentCard]:
+        # Implement protocol-specific agent discovery
+        url = agent_config.get("url")
+        # Make HTTP request to get agent capabilities
+        # Return AgentCard with agent information
+        pass
+        
+    async def _forward_request(self, task_context, request: A2ARequest, agent_name: str):
+        # Implement protocol-specific request forwarding
+        # Forward request to downstream agent
+        # Handle response and publish back to Solace
+        pass
+
+# Custom app class
+class MyProxyApp(BaseProxyApp):
+    def _get_component_class(self):
+        return MyProxyComponent
+```
+
+### 2. Using the A2A Proxy Implementation
+
+The most common use case is using the built-in A2A proxy:
+
+```python
+from solace_agent_mesh.agent.proxies.a2a.app import A2AProxyApp
+from solace_agent_mesh.agent.proxies.a2a.config import A2AProxyAppConfig, AuthenticationConfig
+
+# Configuration with OAuth 2.0 authentication
+app_info = {
+    "app_config": {
+        "namespace": "myorg/production",
+        "proxied_agents": [
+            {
+                "name": "external-agent",
+                "url": "https://external-agent.example.com",
+                "request_timeout_seconds": 120,
+                "authentication": {
+                    "type": "oauth2_client_credentials",
+                    "token_url": "https://auth.example.com/oauth/token",
+                    "client_id": "my-client-id",
+                    "client_secret": "my-client-secret",
+                    "scope": "agent:read agent:write",
+                    "token_cache_duration_seconds": 3300
+                }
+            },
+            {
+                "name": "api-key-agent", 
+                "url": "https://api-agent.example.com",
+                "authentication": {
+                    "type": "static_bearer",
+                    "token": "my-api-key"
+                }
+            }
+        ],
+        "artifact_service": {
+            "type": "gcs",
+            "bucket_name": "my-artifacts-bucket",
+            "artifact_scope": "namespace"
+        },
+        "discovery_interval_seconds": 30,
+        "default_request_timeout_seconds": 300
+    }
+}
+
+# Create and run the proxy app
+app = A2AProxyApp(app_info)
+# App automatically handles Solace subscriptions and agent discovery
+```
+
+### 3. Working with Authentication
+
+The A2A proxy supports multiple authentication methods:
+
+```python
+from solace_agent_mesh.agent.proxies.a2a.config import AuthenticationConfig
+
+# OAuth 2.0 Client Credentials
+oauth_auth = AuthenticationConfig(
+    type="oauth2_client_credentials",
+    token_url="https://auth.provider.com/token",
+    client_id="client123",
+    client_secret="secret456", 
+    scope="read write",
+    token_cache_duration_seconds=3300  # Cache for 55 minutes
+)
+
+# Static Bearer Token
+bearer_auth = AuthenticationConfig(
+    type="static_bearer",
+    token="Bearer abc123xyz"
+)
+
+# Static API Key
+apikey_auth = AuthenticationConfig(
+    type="static_apikey",
+    token="api-key-value"
+)
+```
+
+### 4. Managing OAuth Token Cache
+
+For OAuth 2.0 authentication, tokens are automatically cached:
+
+```python
+from solace_agent_mesh.agent.proxies.a2a.oauth_token_cache import OAuth2TokenCache
+from solace_agent_mesh.agent.proxies.a2a.component import A2AProxyComponent
+
+# Access the component to manage cache
+component = A2AProxyComponent(proxied_agents_config=config)
+
+# Clear all cached tokens (useful for testing or credential rotation)
+component.clear_client_cache()
+
+# Direct cache usage (advanced)
+cache = OAuth2TokenCache()
+await cache.set("agent-name", "access_token", 3600)
+token = await cache.get("agent-name")
+await cache.invalidate("agent-name")
+```
+
+### 5. Task Context and Lifecycle Management
+
+The proxy framework automatically manages task contexts:
+
+```python
+from solace_agent_mesh.agent.proxies.base.proxy_task_context import ProxyTaskContext
+
+# Task contexts are created automatically when requests arrive
+# They contain A2A protocol information and task state
+task_context = ProxyTaskContext(
+    task_id="unique-task-id",
+    a2a_context={
+        "jsonrpc_request_id": "req-123",
+        "logical_task_id": "task-456",
+        "session_id": "session-789", 
+        "user_id": "user123",
+        "status_topic": "status/myorg/production/external-agent",
+        "reply_to_topic": "reply/myorg/production/external-agent",
+        "is_streaming": False
+    }
+)
+
+# Access task information in custom components
+print(f"Handling task: {task_context.task_id}")
+print(f"User: {task_context.a2a_context['user_id']}")
+```
+
+### 6. Configuration Validation
+
+All proxy configurations use Pydantic for validation:
+
+```python
+from solace_agent_mesh.agent.proxies.a2a.config import A2AProxyAppConfig
+from pydantic import ValidationError
+
+try:
+    config = A2AProxyAppConfig.model_validate({
+        "namespace": "myorg/dev",
+        "proxied_agents": [
+            {
+                "name": "test-agent",
+                "url": "https://agent.example.com",
+                "authentication": {
+                    "type": "oauth2_client_credentials",
+                    "token_url": "https://auth.example.com/token",
+                    "client_id": "client123"
+                    # Missing client_secret - will cause validation error
+                }
+            }
+        ]
+    })
+except ValidationError as e:
+    print(f"Configuration error: {e}")
+```
+
+### 7. Integration Patterns
+
+Common patterns for integrating proxies into larger applications:
+
+```python
+# Pattern 1: Direct instantiation
+from solace_agent_mesh.agent.proxies.a2a.app import A2AProxyApp
+
+app = A2AProxyApp(app_info)
+# App handles its own lifecycle
+
+# Pattern 2: Component access for advanced control
+from solace_agent_mesh.agent.proxies.a2a.component import A2AProxyComponent
+
+component = A2AProxyComponent(
+    proxied_agents_config=config["proxied_agents"],
+    namespace=config["namespace"],
+    # ... other broker settings
+)
+
+# Manual lifecycle management
+await component.run()
+# ... application logic
+await component.cleanup()
+
+# Pattern 3: Custom proxy with base classes
+class CustomProtocolProxy(BaseProxyComponent):
+    def __init__(self, **kwargs):
+        super().__init__(**kwargs)
+        self.custom_clients = {}
+    
+    async def _fetch_agent_card(self, agent_config):
+        # Custom discovery logic
+        pass
+        
+    async def _forward_request(self, task_context, request, agent_name):
+        # Custom forwarding logic  
+        pass
+```
+
+This comprehensive guide covers all the main use cases for the proxies directory, from using the built-in A2A proxy to creating custom proxy implementations for new protocols.
+
+# content_hash: 2f19070457fccc3f5c8f680f44788fb63495f9ea3b3da7d71ddb5a52f8f5b0f6

solace_agent_mesh/agent/sac/app.py

@@ -551,3 +551,25 @@ class SamAgentApp(App):
 
         super().__init__(app_info, **kwargs)
         log.debug("%s Agent initialization complete.", agent_name)
+
+    def get_component(self, component_name: str = None) -> "SamAgentComponent":
+        """
+        Retrieves the running SamAgentComponent instance from the app's flow.
+        
+        Args:
+            component_name: Optional component name (for compatibility, but ignored since there's only one component)
+            
+        Returns:
+            The SamAgentComponent instance or None if not found
+        """
+        if self.flows and self.flows[0].component_groups:
+            for group in self.flows[0].component_groups:
+                for component_wrapper in group:
+                    component = (
+                        component_wrapper.component
+                        if hasattr(component_wrapper, "component")
+                        else component_wrapper
+                    )
+                    if isinstance(component, SamAgentComponent):
+                        return component
+        return None

solace_agent_mesh/agent/sac/component.py

@@ -129,7 +129,7 @@ class SamAgentComponent(SamComponentBase):
         super().__init__(info, **kwargs)
         self.agent_name = self.get_config("agent_name")
         log.info("%s Initializing agent: %s (A2A ADK Host Component)...", self.log_identifier, self.agent_name)
-        
+
         # Initialize the agent registry for health tracking
         self.agent_registry = AgentRegistry()
         try:
@@ -437,9 +437,11 @@ class SamAgentComponent(SamComponentBase):
                     "%s Agent card publishing interval not configured or invalid, card will not be published periodically.",
                     self.log_identifier,
                 )
-                
+
             # Set up health check timer if enabled
-            health_check_interval_seconds = self.agent_discovery_config.get("health_check_interval_seconds", HEALTH_CHECK_INTERVAL_SECONDS)
+            health_check_interval_seconds = self.agent_discovery_config.get(
+                "health_check_interval_seconds", HEALTH_CHECK_INTERVAL_SECONDS
+            )
             if health_check_interval_seconds > 0:
                 log.info(
                     "%s Scheduling agent health check every %d seconds.",
@@ -457,7 +459,7 @@ class SamAgentComponent(SamComponentBase):
                     "%s Agent health check interval not configured or invalid, health checks will not run periodically.",
                     self.log_identifier,
                 )
-                
+
             log.info(
                 "%s Initialized agent: %s",
                 self.log_identifier,
@@ -497,6 +499,16 @@ class SamAgentComponent(SamComponentBase):
         event = Event(EventType.MESSAGE, message)
         await process_event(self, event)
 
+    def handle_timer_event(self, timer_data: Dict[str, Any]):
+        """Handles timer events for agent card publishing and health checks."""
+        log.debug("%s Received timer event: %s", self.log_identifier, timer_data)
+        timer_id = timer_data.get("timer_id")
+
+        if timer_id == self._card_publish_timer_id:
+            publish_agent_card(self)
+        elif timer_id == self.HEALTH_CHECK_TIMER_ID:
+            self._check_agent_health()
+
     async def handle_cache_expiry_event(self, cache_data: Dict[str, Any]):
         """
         Handles cache expiry events for peer timeouts by calling the atomic claim helper.
@@ -743,6 +755,14 @@ class SamAgentComponent(SamComponentBase):
         paused_invocation_id = correlation_data.get("invocation_id")
         log_retrigger = f"{self.log_identifier}[RetriggerManager:{logical_task_id}]"
 
+        # Clear paused state - task is resuming now
+        task_context.set_paused(False)
+        log.debug(
+            "%s Task %s resuming from paused state with peer responses.",
+            log_retrigger,
+            logical_task_id,
+        )
+
         try:
             effective_session_id = original_task_context.get("effective_session_id")
             user_id = original_task_context.get("user_id")
@@ -1872,7 +1892,7 @@ class SamAgentComponent(SamComponentBase):
                 log_id,
                 len(signals_found),
             )
-            for _signal_index, signal_data_tuple in signals_found:
+            for _signal_index, signal_data_tuple, _placeholder in signals_found:
                 if (
                     isinstance(signal_data_tuple, tuple)
                     and len(signal_data_tuple) == 3
@@ -1888,6 +1908,7 @@ class SamAgentComponent(SamComponentBase):
                     await self._publish_agent_status_signal_update(
                         status_text, a2a_context
                     )
+                    resolved_text = resolved_text.replace(_placeholder, "")
 
         return resolved_text, unprocessed_tail
 
@@ -3308,79 +3329,93 @@ class SamAgentComponent(SamComponentBase):
         For now, using the agent name, but could be made more robust (e.g., hostname + agent name).
         """
         return self.agent_name
-        
+
     def _check_agent_health(self):
         """
         Checks the health of peer agents and de-registers unresponsive ones.
         This is called periodically by the health check timer.
         Uses TTL-based expiration to determine if an agent is unresponsive.
         """
-            
+
         log.debug("%s Performing agent health check...", self.log_identifier)
-        
-        ttl_seconds = self.agent_discovery_config.get("health_check_ttl_seconds", HEALTH_CHECK_TTL_SECONDS)
-        health_check_interval = self.agent_discovery_config.get("health_check_interval_seconds", HEALTH_CHECK_INTERVAL_SECONDS)
-        
+
+        ttl_seconds = self.agent_discovery_config.get(
+            "health_check_ttl_seconds", HEALTH_CHECK_TTL_SECONDS
+        )
+        health_check_interval = self.agent_discovery_config.get(
+            "health_check_interval_seconds", HEALTH_CHECK_INTERVAL_SECONDS
+        )
+
         log.debug(
             "%s Health check configuration: interval=%d seconds, TTL=%d seconds",
             self.log_identifier,
             health_check_interval,
-            ttl_seconds
+            ttl_seconds,
         )
 
         # Validate configuration values
-        if ttl_seconds <= 0 or health_check_interval <= 0 or ttl_seconds < health_check_interval:
+        if (
+            ttl_seconds <= 0
+            or health_check_interval <= 0
+            or ttl_seconds < health_check_interval
+        ):
             log.error(
                 "%s agent_health_check_ttl_seconds (%d) and agent_health_check_interval_seconds (%d) must be positive and TTL must be greater than interval.",
                 self.log_identifier,
                 ttl_seconds,
-                health_check_interval
+                health_check_interval,
+            )
+            raise ValueError(
+                f"Invalid health check configuration. agent_health_check_ttl_seconds ({ttl_seconds}) and agent_health_check_interval_seconds ({health_check_interval}) must be positive and TTL must be greater than interval."
             )
-            raise ValueError(f"Invalid health check configuration. agent_health_check_ttl_seconds ({ttl_seconds}) and agent_health_check_interval_seconds ({health_check_interval}) must be positive and TTL must be greater than interval.")
-        
+
         # Get all agent names from the registry
         agent_names = self.agent_registry.get_agent_names()
         total_agents = len(agent_names)
         agents_to_deregister = []
-        
-        log.debug("%s Checking health of %d peer agents", self.log_identifier, total_agents)
-        
+
+        log.debug(
+            "%s Checking health of %d peer agents", self.log_identifier, total_agents
+        )
+
         for agent_name in agent_names:
             # Skip our own agent
             if agent_name == self.agent_name:
                 continue
-                
+
             # Check if the agent's TTL has expired
-            is_expired, time_since_last_seen = self.agent_registry.check_ttl_expired(agent_name, ttl_seconds)
-            
+            is_expired, time_since_last_seen = self.agent_registry.check_ttl_expired(
+                agent_name, ttl_seconds
+            )
+
             if is_expired:
                 log.warning(
                     "%s Agent '%s' TTL has expired. De-registering. Time since last seen: %d seconds (TTL: %d seconds)",
                     self.log_identifier,
                     agent_name,
                     time_since_last_seen,
-                    ttl_seconds
+                    ttl_seconds,
                 )
                 agents_to_deregister.append(agent_name)
-            
+
         # De-register unresponsive agents
         for agent_name in agents_to_deregister:
             self._deregister_agent(agent_name)
-            
+
         log.debug(
             "%s Agent health check completed. Total agents: %d, De-registered: %d",
             self.log_identifier,
             total_agents,
-            len(agents_to_deregister)
+            len(agents_to_deregister),
         )
-        
+
     def _deregister_agent(self, agent_name: str):
         """
         De-registers an agent from the registry and publishes a de-registration event.
         """
         # Remove from registry
         registry_removed = self.agent_registry.remove_agent(agent_name)
-        
+
         # Always remove from peer_agents regardless of registry result
         peer_removed = False
         if agent_name in self.peer_agents:
@@ -3389,18 +3424,18 @@ class SamAgentComponent(SamComponentBase):
             log.info(
                 "%s Removed agent '%s' from peer_agents dictionary",
                 self.log_identifier,
-                agent_name
+                agent_name,
             )
-        
+
         # Publish de-registration event if agent was in either data structure
         if registry_removed or peer_removed:
             try:
                 # Create a de-registration event topic
                 namespace = self.get_config("namespace")
                 deregistration_topic = f"{namespace}/a2a/events/agent/deregistered"
-                
+
                 current_time = time.time()
-                
+
                 # Create the payload
                 deregistration_payload = {
                     "event_type": "agent.deregistered",
@@ -3408,28 +3443,27 @@ class SamAgentComponent(SamComponentBase):
                     "reason": "health_check_failure",
                     "metadata": {
                         "timestamp": current_time,
-                        "deregistered_by": self.agent_name
-                    }
+                        "deregistered_by": self.agent_name,
+                    },
                 }
-                
+
                 # Publish the event
                 self.publish_a2a_message(
-                    payload=deregistration_payload,
-                    topic=deregistration_topic
+                    payload=deregistration_payload, topic=deregistration_topic
                 )
-                
+
                 log.info(
                     "%s Published de-registration event for agent '%s' to topic '%s'",
                     self.log_identifier,
                     agent_name,
-                    deregistration_topic
+                    deregistration_topic,
                 )
             except Exception as e:
                 log.error(
                     "%s Failed to publish de-registration event for agent '%s': %s",
                     self.log_identifier,
                     agent_name,
-                    e
+                    e,
                 )
 
     async def _resolve_early_embeds_and_handle_signals(
@@ -3485,6 +3519,7 @@ class SamAgentComponent(SamComponentBase):
 
         try:
             from ...common.utils.embeds.constants import EARLY_EMBED_TYPES
+            from ...common.utils.embeds.types import ResolutionMode
             from ...common.utils.embeds.resolver import (
                 evaluate_embed,
                 resolve_embeds_in_string,
@@ -3496,6 +3531,7 @@ class SamAgentComponent(SamComponentBase):
                     context=context_for_embeds,
                     resolver_func=evaluate_embed,
                     types_to_resolve=EARLY_EMBED_TYPES,
+                    resolution_mode=ResolutionMode.TOOL_PARAMETER,
                     log_identifier=method_context_log_identifier,
                     config=resolver_config,
                 )

solace_agent_mesh/agent/sac/sac_llm.txt

@@ -186,4 +186,4 @@ usage = task_context.get_token_usage_summary()
 print(f"Total tokens used: {usage['total_tokens']}")
 ```
 
-# content_hash: 27b0000d250131d578d28ab8c4d06c2e2084d888b47102e9b3b133adbc61a169
+# content_hash: c80bf39278c35fcb73e1df4421b631aabbdb4ba330e8be028fb8a29e097c3fad

solace_agent_mesh/agent/sac/task_execution_context.py

@@ -36,6 +36,7 @@ class TaskExecutionContext:
         self.artifact_signals_to_return: List[Dict[str, Any]] = []
         self.event_loop: Optional[asyncio.AbstractEventLoop] = None
         self.lock: threading.Lock = threading.Lock()
+        self.is_paused: bool = False  # Track if task is paused waiting for peer/auth
 
         # Token usage tracking
         self.total_input_tokens: int = 0
@@ -59,6 +60,26 @@ class TaskExecutionContext:
         """Checks if the cancellation event has been set."""
         return self.cancellation_event.is_set()
 
+    def set_paused(self, paused: bool) -> None:
+        """
+        Marks the task as paused (waiting for peer response or user input).
+
+        Args:
+            paused: True if task is paused, False if resuming.
+        """
+        with self.lock:
+            self.is_paused = paused
+
+    def get_is_paused(self) -> bool:
+        """
+        Checks if the task is currently paused.
+
+        Returns:
+            True if task is paused (waiting for peer/auth), False otherwise.
+        """
+        with self.lock:
+            return self.is_paused
+
     def append_to_streaming_buffer(self, text: str) -> None:
         """Appends a chunk of text to the main streaming buffer."""
         with self.lock:

solace_agent_mesh/agent/testing/testing_llm.txt

@@ -5,6 +5,7 @@ The `testing` directory provides utilities for testing the A2A (Agent-to-Agent)
 - `__init__.py` - Package initialization file marking the directory as a Python module
 - `debug_utils.py` - Debugging utilities including pretty-printing for A2A event history
 - `testing_llm.txt` - Documentation file (not a code module)
+- `testing_llm_detail.txt` - Concatenated documentation file (not a code module)
 
 ## Developer API Reference
 
@@ -54,4 +55,4 @@ pretty_print_event_history(event_history, max_string_length=100)
 pretty_print_event_history([])
 ```
 
-# content_hash: 890ba89aa47c5be30f5ec9cdbb4a05e9ee3bd022e56a56fcc4feea72aac653e8
+# content_hash: 09db923206be2f0cd02c12cb97cf50f7b6364773fae328dd0570e69067cc1971