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

solace_agent_mesh/agent/proxies/a2a/config.py

@@ -0,0 +1,216 @@
+"""
+Pydantic configuration models for A2A proxy applications.
+"""
+
+from typing import List, Literal, Optional
+from urllib.parse import urlparse
+
+from pydantic import Field, model_validator
+
+from ..base.config import BaseProxyAppConfig, ProxiedAgentConfig
+from ....common.utils.pydantic_utils import SamConfigBase
+
+
+class HttpHeaderConfig(SamConfigBase):
+    """Configuration for a single HTTP header."""
+
+    name: str = Field(
+        ...,
+        description="The HTTP header name (e.g., 'X-API-Key', 'Authorization').",
+    )
+    value: str = Field(
+        ...,
+        description="The HTTP header value.",
+    )
+
+
+class AuthenticationConfig(SamConfigBase):
+    """Authentication configuration for downstream A2A agents."""
+
+    type: Optional[
+        Literal["static_bearer", "static_apikey", "oauth2_client_credentials", "oauth2_authorization_code"]
+    ] = Field(
+        default=None,
+        description="Authentication type. If not specified, inferred from 'scheme' for backward compatibility.",
+    )
+    scheme: Optional[str] = Field(
+        default=None,
+        description="(Legacy) The authentication scheme (e.g., 'bearer', 'apikey'). Use 'type' field instead.",
+    )
+    token: Optional[str] = Field(
+        default=None,
+        description="The authentication token or API key (for static_bearer and static_apikey types).",
+    )
+    token_url: Optional[str] = Field(
+        default=None,
+        description="OAuth 2.0 token endpoint URL (required for oauth2_client_credentials type).",
+    )
+    client_id: Optional[str] = Field(
+        default=None,
+        description="OAuth 2.0 client identifier (required for oauth2_client_credentials and oauth2_authorization_code types).",
+    )
+    client_secret: Optional[str] = Field(
+        default=None,
+        description="OAuth 2.0 client secret (required for oauth2_client_credentials type, optional for oauth2_authorization_code).",
+    )
+    scope: Optional[str] = Field(
+        default=None,
+        description="OAuth 2.0 scope as a space-separated string (optional for oauth2_client_credentials type).",
+    )
+    token_cache_duration_seconds: int = Field(
+        default=3300,
+        gt=0,
+        description="How long to cache OAuth 2.0 tokens before refresh, in seconds (default: 3300 = 55 minutes).",
+    )
+
+    # NEW fields for oauth2_authorization_code
+    authorization_url: Optional[str] = Field(
+        default=None,
+        description="OAuth 2.0 authorization endpoint URL (for oauth2_authorization_code type). Can override agent card URL.",
+    )
+    redirect_uri: Optional[str] = Field(
+        default=None,
+        description="OAuth 2.0 redirect URI (required for oauth2_authorization_code type).",
+    )
+    scopes: Optional[List[str]] = Field(
+        default=None,
+        description="OAuth 2.0 scopes as a list of strings (optional for oauth2_authorization_code type).",
+    )
+
+    @model_validator(mode="after")
+    def validate_auth_config(self) -> "AuthenticationConfig":
+        """Validates authentication configuration based on type."""
+        # Determine effective auth type (with backward compatibility)
+        auth_type = self.type
+        if not auth_type and self.scheme:
+            # Legacy config: infer type from scheme
+            if self.scheme == "bearer":
+                auth_type = "static_bearer"
+            elif self.scheme == "apikey":
+                auth_type = "static_apikey"
+            else:
+                raise ValueError(
+                    f"Unknown legacy authentication scheme '{self.scheme}'. "
+                    f"Supported schemes: 'bearer', 'apikey'."
+                )
+
+        if not auth_type:
+            # No authentication configured
+            return self
+
+        # Validate based on auth type
+        if auth_type in ["static_bearer", "static_apikey"]:
+            if not self.token:
+                raise ValueError(
+                    f"Authentication type '{auth_type}' requires 'token' field."
+                )
+
+        elif auth_type == "oauth2_client_credentials":
+            # Validate token_url
+            if not self.token_url:
+                raise ValueError(
+                    "OAuth 2.0 client credentials flow requires 'token_url'."
+                )
+
+            # Validate token_url is HTTPS
+            try:
+                parsed_url = urlparse(self.token_url)
+                if parsed_url.scheme != "https":
+                    raise ValueError(
+                        f"OAuth 2.0 'token_url' must use HTTPS for security. "
+                        f"Got scheme: '{parsed_url.scheme}'"
+                    )
+            except Exception as e:
+                raise ValueError(f"Failed to parse 'token_url': {e}")
+
+            # Validate client_id
+            if not self.client_id:
+                raise ValueError(
+                    "OAuth 2.0 client credentials flow requires 'client_id'."
+                )
+
+            # Validate client_secret
+            if not self.client_secret:
+                raise ValueError(
+                    "OAuth 2.0 client credentials flow requires 'client_secret'."
+                )
+
+        elif auth_type == "oauth2_authorization_code":
+            # Validate client_id
+            if not self.client_id:
+                raise ValueError(
+                    "OAuth 2.0 authorization code flow requires 'client_id'."
+                )
+
+            # Validate redirect_uri
+            if not self.redirect_uri:
+                raise ValueError(
+                    "OAuth 2.0 authorization code flow requires 'redirect_uri'."
+                )
+
+            # Optional: Validate authorization_url if provided (can also come from agent card)
+            if self.authorization_url:
+                try:
+                    parsed_url = urlparse(self.authorization_url)
+                    if parsed_url.scheme not in ["https", "http"]:
+                        raise ValueError(
+                            f"OAuth 2.0 'authorization_url' must use HTTP(S). "
+                            f"Got scheme: '{parsed_url.scheme}'"
+                        )
+                except Exception as e:
+                    raise ValueError(f"Failed to parse 'authorization_url': {e}")
+
+        else:
+            raise ValueError(
+                f"Unsupported authentication type '{auth_type}'. "
+                f"Supported types: static_bearer, static_apikey, oauth2_client_credentials, oauth2_authorization_code."
+            )
+
+        return self
+
+
+class A2AProxiedAgentConfig(ProxiedAgentConfig):
+    """Configuration for an A2A-over-HTTPS proxied agent."""
+
+    url: str = Field(
+        ...,
+        description="The base URL of the downstream A2A agent's HTTP endpoint.",
+    )
+    authentication: Optional[AuthenticationConfig] = Field(
+        default=None,
+        description="Authentication details for the downstream agent.",
+    )
+    use_auth_for_agent_card: bool = Field(
+        default=False,
+        description="If true, applies the configured authentication to agent card fetching. "
+        "If false, agent card requests are made without authentication.",
+    )
+    use_agent_card_url: bool = Field(
+        default=True,
+        description="If true, uses the URL from the agent card for task invocations. "
+        "If false, uses the configured URL directly for task invocations. "
+        "Note: The configured URL is always used to fetch the agent card itself.",
+    )
+    agent_card_headers: Optional[List[HttpHeaderConfig]] = Field(
+        default=None,
+        description="Custom HTTP headers to include when fetching the agent card. "
+        "These headers are added alongside authentication headers.",
+    )
+    task_headers: Optional[List[HttpHeaderConfig]] = Field(
+        default=None,
+        description="Custom HTTP headers to include when invoking A2A tasks. "
+        "These headers are added alongside authentication headers. Note: The A2A SDK's "
+        "AuthInterceptor applies authentication headers after these are set, so custom "
+        "headers cannot override authentication. For custom auth, omit the 'authentication' "
+        "config and use task_headers to set auth headers directly.",
+    )
+
+
+class A2AProxyAppConfig(BaseProxyAppConfig):
+    """Complete configuration for an A2A proxy application."""
+
+    proxied_agents: List[A2AProxiedAgentConfig] = Field(
+        ...,
+        min_length=1,
+        description="A list of downstream A2A agents to be proxied.",
+    )

solace_agent_mesh/agent/proxies/a2a/oauth_token_cache.py

@@ -0,0 +1,104 @@
+"""
+OAuth 2.0 token caching for A2A proxy authentication.
+
+This module provides an in-memory cache for OAuth 2.0 access tokens
+with automatic expiration. Tokens are cached per agent to minimize
+token acquisition overhead and reduce load on authorization servers.
+
+The cache is thread-safe using asyncio.Lock and implements lazy
+expiration (tokens are checked for expiration on retrieval).
+"""
+
+import asyncio
+import time
+from dataclasses import dataclass
+from typing import Dict, Optional
+
+from solace_ai_connector.common.log import log
+
+
+@dataclass
+class CachedToken:
+    """Represents a cached OAuth token with expiration."""
+
+    access_token: str
+    expires_at: float  # Unix timestamp when token expires (time.time() + cache_duration)
+
+
+class OAuth2TokenCache:
+    """
+    Thread-safe in-memory cache for OAuth 2.0 access tokens.
+
+    Tokens are cached per agent and automatically expire based on
+    the configured cache duration.
+    """
+
+    def __init__(self):
+        """Initialize the token cache with an empty dictionary and lock."""
+        self._cache: Dict[str, CachedToken] = {}
+        self._lock = asyncio.Lock()
+
+    async def get(self, agent_name: str) -> Optional[str]:
+        """
+        Retrieves a cached token if it exists and hasn't expired.
+
+        Args:
+            agent_name: The name of the agent to get the token for.
+
+        Returns:
+            The access token if cached and valid, None otherwise.
+        """
+        async with self._lock:
+            cached = self._cache.get(agent_name)
+            if not cached:
+                return None
+
+            # Check if token has expired
+            if time.time() >= cached.expires_at:
+                log.debug(
+                    "Cached token for '%s' has expired. Removing from cache.",
+                    agent_name,
+                )
+                del self._cache[agent_name]
+                return None
+
+            log.debug(
+                "Using cached OAuth token for '%s' (expires in %.0fs)",
+                agent_name,
+                cached.expires_at - time.time(),
+            )
+            return cached.access_token
+
+    async def set(
+        self, agent_name: str, access_token: str, cache_duration_seconds: int
+    ):
+        """
+        Caches a token with an expiration time.
+
+        Args:
+            agent_name: The name of the agent.
+            access_token: The OAuth 2.0 access token.
+            cache_duration_seconds: How long the token should be cached.
+        """
+        async with self._lock:
+            expires_at = time.time() + cache_duration_seconds
+            self._cache[agent_name] = CachedToken(
+                access_token=access_token, expires_at=expires_at
+            )
+            log.debug(
+                "Cached token for '%s' (expires in %ds)",
+                agent_name,
+                cache_duration_seconds,
+            )
+
+    async def invalidate(self, agent_name: str):
+        """
+        Removes a token from the cache.
+
+        Args:
+            agent_name: The name of the agent.
+        """
+        async with self._lock:
+            if agent_name in self._cache:
+                del self._cache[agent_name]
+                log.info("Invalidated cached token for '%s'", agent_name)

solace_agent_mesh/agent/proxies/base/__init__.py

@@ -0,0 +1,3 @@
+"""
+This package contains the protocol-agnostic base classes for all proxy implementations.
+"""

solace_agent_mesh/agent/proxies/base/app.py

@@ -0,0 +1,100 @@
+"""
+Abstract base class for proxy apps.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any, Dict, Type
+
+from pydantic import ValidationError
+from solace_ai_connector.common.log import log
+from solace_ai_connector.flow.app import App
+
+from ....common.a2a import get_agent_request_topic
+from .component import BaseProxyComponent
+from .config import BaseProxyAppConfig
+
+
+info = {
+    "class_name": "BaseProxyApp",
+    "description": "Abstract base class for proxy apps. Handles common configuration and subscription generation.",
+}
+
+
+class BaseProxyApp(App, ABC):
+    """
+    Abstract base class for proxy apps.
+
+    Handles common configuration schema, generates Solace topic subscriptions for all
+    proxied agents, and programmatically defines the single proxy component instance.
+    """
+
+    app_schema = {}
+
+    def __init__(self, app_info: Dict[str, Any], **kwargs):
+        log.debug("Initializing BaseProxyApp...")
+
+        app_config_dict = app_info.get("app_config", {})
+
+        try:
+            # Validate the raw dict, cleaning None values to allow defaults to apply
+            app_config = BaseProxyAppConfig.model_validate_and_clean(app_config_dict)
+            # Overwrite the raw dict with the validated object for downstream use
+            app_info["app_config"] = app_config
+        except ValidationError as e:
+            message = BaseProxyAppConfig.format_validation_error_message(e, app_info['name'])
+            log.error("Invalid Proxy configuration:\n%s", message)
+            raise
+
+        namespace = app_config.get("namespace")
+        proxied_agents = app_config.get("proxied_agents", [])
+
+        # Generate subscriptions for each proxied agent
+        required_topics = [
+            get_agent_request_topic(namespace, agent["name"])
+            for agent in proxied_agents
+            if "name" in agent
+        ]
+        generated_subs = [{"topic": topic} for topic in required_topics]
+        log.info(
+            "Automatically generated subscriptions for proxy: %s",
+            generated_subs,
+        )
+
+        # Programmatically define the component
+        component_class = self._get_component_class()
+        component_definition = {
+            "name": f"{app_info.get('name', 'proxy')}_component",
+            "component_class": component_class,
+            "component_config": {},  # Component will get config from app_config
+            "subscriptions": generated_subs,
+        }
+        app_info["components"] = [component_definition]
+        log.debug("Replaced 'components' in app_info with programmatic definition.")
+
+        # Ensure broker is configured for input/output
+        broker_config = app_info.setdefault("broker", {})
+        broker_config["input_enabled"] = True
+        broker_config["output_enabled"] = True
+        log.debug("Injected broker.input_enabled=True and broker.output_enabled=True")
+
+        # Generate a unique queue name
+        app_name = app_info.get("name", "proxy-app")
+        generated_queue_name = f"{namespace.strip('/')}/q/proxy/{app_name}"
+        broker_config["queue_name"] = generated_queue_name
+        log.debug("Injected generated broker.queue_name: %s", generated_queue_name)
+
+        broker_config["temporary_queue"] = True
+        log.debug("Set broker_config.temporary_queue = True")
+
+        super().__init__(app_info, **kwargs)
+        log.debug("BaseProxyApp initialization complete.")
+
+    @abstractmethod
+    def _get_component_class(self) -> Type[BaseProxyComponent]:
+        """
+        Abstract method to be implemented by concrete proxy apps.
+        Must return the specific proxy component class to be instantiated.
+        """
+        raise NotImplementedError

solace_agent_mesh/agent/proxies/base/base_llm.txt

@@ -0,0 +1,148 @@
+# DEVELOPER GUIDE: base
+
+## Quick Summary
+The `base` directory contains protocol-agnostic abstract base classes for implementing proxy applications in the Solace Agent Mesh. These classes handle common functionality like A2A message routing, agent discovery, task lifecycle management, and artifact resolution, allowing concrete proxy implementations to focus on protocol-specific details.
+
+## Files Overview
+- `__init__.py` - Package initialization for base proxy classes
+- `app.py` - Abstract base class for proxy applications with configuration validation and component setup
+- `component.py` - Abstract base class for proxy components handling Solace interaction and task management
+- `config.py` - Pydantic configuration models for proxy applications
+- `proxy_task_context.py` - Runtime state container for individual proxied agent tasks
+
+## Developer API Reference
+
+### __init__.py
+**Purpose:** Package initialization file for base proxy classes
+**Import:** `from solace_agent_mesh.agent.proxies.base import *`
+
+This file contains only package documentation and no public API.
+
+### app.py
+**Purpose:** Abstract base class for proxy applications that handles configuration validation and automatic component setup
+**Import:** `from solace_agent_mesh.agent.proxies.base.app import BaseProxyApp`
+
+**Classes:**
+- `BaseProxyApp(app_info: Dict[str, Any], **kwargs)` - Abstract base for proxy apps that automatically configures subscriptions and components
+  - `_get_component_class() -> Type[BaseProxyComponent]` - Abstract method to return the specific proxy component class
+
+**Usage Examples:**
+```python
+from solace_agent_mesh.agent.proxies.base.app import BaseProxyApp
+from solace_agent_mesh.agent.proxies.base.component import BaseProxyComponent
+
+class MyProxyApp(BaseProxyApp):
+    def _get_component_class(self):
+        return MyProxyComponent
+
+# App will automatically:
+# - Validate configuration against BaseProxyAppConfig
+# - Generate Solace subscriptions for all proxied agents
+# - Create component instance with proper broker settings
+```
+
+### component.py
+**Purpose:** Abstract base class for proxy components that handles Solace interaction, discovery, and task lifecycle
+**Import:** `from solace_agent_mesh.agent.proxies.base.component import BaseProxyComponent`
+
+**Classes:**
+- `BaseProxyComponent(**kwargs: Any)` - Abstract base for proxy components with async event processing
+  - `process_event(event: Event) -> None` - Processes incoming Solace events
+  - `invoke(message: SolaceMessage, data: dict) -> dict` - Placeholder invoke method (not used)
+  - `run() -> None` - Starts component operations and discovery timers
+  - `cleanup() -> None` - Cleans up resources on shutdown
+  - `clear_client_cache() -> None` - Clears cached clients (override in subclasses)
+  - `_fetch_agent_card(agent_config: dict) -> Optional[AgentCard]` - Abstract method to fetch agent cards
+  - `_forward_request(task_context: ProxyTaskContext, request: A2ARequest, agent_name: str) -> None` - Abstract method to forward requests
+
+**Usage Examples:**
+```python
+from solace_agent_mesh.agent.proxies.base.component import BaseProxyComponent
+from a2a.types import AgentCard, A2ARequest
+
+class MyProxyComponent(BaseProxyComponent):
+    async def _fetch_agent_card(self, agent_config: dict) -> Optional[AgentCard]:
+        # Implement protocol-specific agent discovery
+        url = agent_config.get("url")
+        # ... fetch and return AgentCard
+        
+    async def _forward_request(self, task_context, request: A2ARequest, agent_name: str):
+        # Implement protocol-specific request forwarding
+        # ... forward request to downstream agent
+        # ... handle responses and publish back to Solace
+```
+
+### config.py
+**Purpose:** Pydantic configuration models for proxy applications
+**Import:** `from solace_agent_mesh.agent.proxies.base.config import BaseProxyAppConfig, ProxiedAgentConfig, ArtifactServiceConfig`
+
+**Classes:**
+- `ArtifactServiceConfig()` - Configuration for artifact service
+  - `type: str` - Service type ('memory', 'gcs', 'filesystem')
+  - `base_path: Optional[str]` - Base directory for filesystem type
+  - `bucket_name: Optional[str]` - GCS bucket name
+  - `artifact_scope: Literal["namespace", "app", "custom"]` - Scope for artifacts
+  - `artifact_scope_value: Optional[str]` - Custom scope identifier
+
+- `ProxiedAgentConfig()` - Configuration for individual proxied agents
+  - `name: str` - Agent name on Solace mesh
+  - `request_timeout_seconds: Optional[int]` - Timeout override for this agent
+
+- `BaseProxyAppConfig()` - Base configuration for proxy applications
+  - `namespace: str` - Topic prefix for A2A communication
+  - `proxied_agents: List[ProxiedAgentConfig]` - List of agents to proxy
+  - `artifact_service: ArtifactServiceConfig` - Artifact service configuration
+  - `discovery_interval_seconds: int` - Agent discovery interval (default: 60)
+  - `default_request_timeout_seconds: int` - Default request timeout (default: 300)
+
+**Usage Examples:**
+```python
+from solace_agent_mesh.agent.proxies.base.config import BaseProxyAppConfig
+
+# Configuration validation
+config_dict = {
+    "namespace": "myorg/dev",
+    "proxied_agents": [
+        {"name": "my-agent", "request_timeout_seconds": 120}
+    ],
+    "artifact_service": {"type": "memory"},
+    "discovery_interval_seconds": 30
+}
+
+config = BaseProxyAppConfig.model_validate(config_dict)
+```
+
+### proxy_task_context.py
+**Purpose:** Runtime state container for individual proxied agent tasks
+**Import:** `from solace_agent_mesh.agent.proxies.base.proxy_task_context import ProxyTaskContext`
+
+**Classes:**
+- `ProxyTaskContext(task_id: str, a2a_context: Dict[str, Any])` - Runtime state for a proxied task
+  - `task_id: str` - Unique identifier for the task
+  - `a2a_context: Dict[str, Any]` - A2A protocol context information
+
+**Usage Examples:**
+```python
+from solace_agent_mesh.agent.proxies.base.proxy_task_context import ProxyTaskContext
+
+# Create task context when handling new request
+a2a_context = {
+    "jsonrpc_request_id": "req-123",
+    "logical_task_id": "task-456", 
+    "session_id": "session-789",
+    "user_id": "user123",
+    "status_topic": "status/topic",
+    "reply_to_topic": "reply/topic",
+    "is_streaming": False
+}
+
+task_context = ProxyTaskContext(
+    task_id="task-456",
+    a2a_context=a2a_context
+)
+
+# Store in active tasks for lifecycle management
+self.active_tasks[task_context.task_id] = task_context
+```
+
+# content_hash: 40cb6427440b8b946d69d0d721d47ca5994dd19621e6e631544e8e39b7a96624