solace-agent-mesh 1.6.2__py3-none-any.whl → 1.7.0__py3-none-any.whl

solace_agent_mesh/agent/adk/tool_wrapper.py

@@ -15,6 +15,7 @@ from ...common.utils.embeds import (
     LATE_EMBED_TYPES,
     EMBED_DELIMITER_OPEN,
 )
+from ...common.utils.embeds.types import ResolutionMode
 
 log = logging.getLogger(__name__)
 
@@ -102,6 +103,7 @@ class ADKToolWrapper:
                         context=context_for_embeds,
                         resolver_func=evaluate_embed,
                         types_to_resolve=self._types_to_resolve,
+                        resolution_mode=ResolutionMode.TOOL_PARAMETER,
                         log_identifier=log_identifier,
                         config=self._tool_config,
                     )
@@ -123,6 +125,7 @@ class ADKToolWrapper:
                         context=context_for_embeds,
                         resolver_func=evaluate_embed,
                         types_to_resolve=self._types_to_resolve,
+                        resolution_mode=ResolutionMode.TOOL_PARAMETER,
                         log_identifier=log_identifier,
                         config=self._tool_config,
                     )

solace_agent_mesh/agent/agent_llm.txt

@@ -10,6 +10,7 @@ The architecture is modular, consisting of several key components:
 - **`protocol/`:** The underlying implementation of the A2A (Agent-to-Agent) communication protocol, handling message routing and event processing.
 - **`utils/`:** A collection of helper modules for common tasks like artifact management, configuration parsing, and context handling.
 - **`testing/`:** Utilities to aid in debugging and testing custom agent implementations.
+- **`proxies/`:** Framework for creating proxy applications that enable communication with downstream agents using various protocols.
 
 These components work together to create a robust environment where an ADK agent can be configured with specific instructions and tools, communicate with other agents, and execute complex tasks in a distributed, event-driven manner.
 
@@ -17,9 +18,11 @@ These components work together to create a robust environment where an ADK agent
 - **Direct files:**
   - `__init__.py`: Standard Python package initializer that marks the `agent` directory as a Python package
   - `agent_llm.txt`: Documentation file containing comprehensive developer guide content
+  - `agent_llm_detail.txt`: Concatenated documentation file from all subdirectories
 - **Subdirectories:**
   - `adk/`: Provides the core integration layer with Google's ADK, including custom agents, services, and callbacks
   - `protocol/`: Implements the A2A protocol event handlers for message routing and agent communication
+  - `proxies/`: Framework for creating proxy applications that bridge different agent protocols
   - `sac/`: Contains the Solace AI Connector app and component implementations for hosting ADK agents
   - `testing/`: Provides utilities for testing the A2A framework and debugging agent behavior
   - `tools/`: A comprehensive, registry-based tool library for AI agents
@@ -41,16 +44,23 @@ These components work together to create a robust environment where an ADK agent
 
 **Classes/Functions/Constants:** [None - documentation file]
 
+#### agent_llm_detail.txt
+**Purpose:** Concatenated documentation file from all subdirectories
+**Import:** Not applicable - this is a documentation file, not a code module
+
+**Classes/Functions/Constants:** [None - documentation file]
+
 ### Subdirectory APIs
 
 #### adk/
 **Purpose:** Provides the core integration layer between the Solace AI Connector and Google's ADK
-**Key Exports:** `AppLlmAgent`, `initialize_adk_agent`, `initialize_adk_runner`, `load_adk_tools`, `FilesystemArtifactService`, `LiteLlm`
+**Key Exports:** `AppLlmAgent`, `initialize_adk_agent`, `initialize_adk_runner`, `load_adk_tools`, `FilesystemArtifactService`, `S3ArtifactService`, `LiteLlm`
 **Import Examples:**
 ```python
 from solace_agent_mesh.agent.adk.setup import load_adk_tools, initialize_adk_agent, initialize_adk_runner
 from solace_agent_mesh.agent.adk.app_llm_agent import AppLlmAgent
-from solace_agent_mesh.agent.adk.filesystem_artifact_service import FilesystemArtifactService
+from solace_agent_mesh.agent.adk.artifacts.filesystem_artifact_service import FilesystemArtifactService
+from solace_agent_mesh.agent.adk.artifacts.s3_artifact_service import S3ArtifactService
 from solace_agent_mesh.agent.adk.models.lite_llm import LiteLlm
 from solace_agent_mesh.agent.adk.services import initialize_session_service, initialize_artifact_service
 ```
@@ -63,6 +73,18 @@ from solace_agent_mesh.agent.adk.services import initialize_session_service, ini
 from solace_agent_mesh.agent.protocol.event_handlers import process_event, publish_agent_card
 ```
 
+#### proxies/
+**Purpose:** Framework for creating proxy applications that enable communication with downstream agents using various protocols
+**Key Exports:** `BaseProxyApp`, `BaseProxyComponent`, `A2AProxyApp`, `A2AProxyComponent`, `OAuth2TokenCache`
+**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.a2a.app import A2AProxyApp
+from solace_agent_mesh.agent.proxies.a2a.component import A2AProxyComponent
+from solace_agent_mesh.agent.proxies.a2a.oauth_token_cache import OAuth2TokenCache
+```
+
 #### sac/
 **Purpose:** Provides the Solace AI Connector app and component implementations for hosting ADK agents
 **Key Exports:** `SamAgentApp`, `SamAgentComponent`, `TaskExecutionContext`
@@ -90,6 +112,7 @@ from solace_agent_mesh.agent.tools.registry import tool_registry
 from solace_agent_mesh.agent.tools.peer_agent_tool import PeerAgentTool
 from solace_agent_mesh.agent.tools.audio_tools import text_to_speech
 from solace_agent_mesh.agent.tools.builtin_artifact_tools import list_artifacts, load_artifact
+from solace_agent_mesh.agent.tools.image_tools import create_image_from_description
 ```
 
 #### utils/
@@ -290,7 +313,40 @@ async def multimedia_example(tool_context):
     return tts_result, conversation_result, image_result
 ```
 
-### 7. Testing and Debugging
+### 7. Proxy Applications for External Agents
+
+```python
+from solace_agent_mesh.agent.proxies.a2a.app import A2AProxyApp
+
+# Configure proxy for external A2A-over-HTTPS agents
+proxy_config = {
+    "app_config": {
+        "namespace": "myorg/production",
+        "proxied_agents": [
+            {
+                "name": "external-agent",
+                "url": "https://external-agent.example.com",
+                "authentication": {
+                    "type": "oauth2_client_credentials",
+                    "token_url": "https://auth.example.com/oauth/token",
+                    "client_id": "my-client-id",
+                    "client_secret": "my-client-secret"
+                }
+            }
+        ],
+        "artifact_service": {
+            "type": "gcs",
+            "bucket_name": "my-artifacts-bucket"
+        }
+    }
+}
+
+# Create and run the proxy
+proxy_app = A2AProxyApp(proxy_config)
+# Proxy automatically handles discovery and request forwarding
+```
+
+### 8. Testing and Debugging
 
 ```python
 from solace_agent_mesh.agent.testing.debug_utils import pretty_print_event_history
@@ -308,71 +364,6 @@ def test_agent_behavior():
 
 # Monitor agent invocations
 monitor = InvocationMonitor()
-monitor.log_message_event("incoming", "agent/request", {"task": "analyze data"})
-```
-
-### 8. Configuration and Context Handling
-
-```python
-from solace_agent_mesh.agent.utils.config_parser import resolve_instruction_provider
-from solace_agent_mesh.agent.utils.context_helpers import get_session_from_callback_context
-
-# Resolve dynamic instructions
-def setup_agent_instructions(component):
-    # Static instruction
-    static_instruction = resolve_instruction_provider(
-        component, 
-        "You are a helpful customer service agent."
-    )
-    
-    # Dynamic instruction function
-    def dynamic_instruction(context):
-        return f"You are assisting user {context.user_id} in session {context.session_id}"
-    
-    dynamic_provider = resolve_instruction_provider(component, dynamic_instruction)
-    
-    return static_instruction, dynamic_provider
-
-# Safe context extraction in tools
-def my_tool_with_context(tool_context):
-    session = get_session_from_callback_context(tool_context)
-    original_session_id = get_original_session_id(tool_context._invocation_context)
-    
-    return {"session_id": original_session_id, "session_data": session}
-```
-
-### 9. Complete Agent Implementation Example
-
-```python
-from solace_agent_mesh.agent.sac.app import SamAgentApp
-from solace_agent_mesh.agent.sac.component import SamAgentComponent
-from solace_agent_mesh.agent.adk.setup import load_adk_tools, initialize_adk_agent, initialize_adk_runner
-from solace_agent_mesh.agent.tools.registry import tool_registry
-from solace_agent_mesh.agent.tools.tool_definition import BuiltinTool
-
-# Custom initialization function
-def initialize_my_agent(host_component: SamAgentComponent, config: dict):
-    """Custom initialization function for the agent."""
-    # Store custom state
-    host_component.set_agent_specific_state('custom_data', config.get('custom_data'))
-    
-    # Set dynamic system instruction
-    def dynamic_instruction(context):
-        return f"You are a specialized agent for user {context.user_id}"
-    
-    host_component.set_agent_system_instruction_callback(dynamic_instruction)
-
-# Custom tool
-async def my_business_tool(
-    query: str,
-    tool_context = None,
-    tool_config: dict = None
-) -> dict:
-    """Custom business logic tool."""
-    host_component = tool_context._invocation_context.agent.host_component
-    custom_data = host_component.get_agent_specific_state('custom_data')
-    
-    # Process business logic
-    result =
+monitor.log_message_event("
 
-# content_hash: 596f8253b415eaca3335f7660837dee9a090b3cab0b6e0a4daf92ca9a16d0123
+# content_hash: 044545e92d39d61fac8f9bf62598018a7cbee362201bc3a6f0ae74b299fa4374

solace_agent_mesh/agent/protocol/event_handlers.py

@@ -27,7 +27,7 @@ from solace_ai_connector.common.event import Event, EventType
 from solace_ai_connector.common.message import Message as SolaceMessage
 
 from ...agent.adk.callbacks import _publish_data_part_status_update
-from ...agent.adk.runner import run_adk_async_task_thread_wrapper
+from ...agent.adk.runner import TaskCancelledError, run_adk_async_task_thread_wrapper
 from ...agent.utils.artifact_helpers import generate_artifact_metadata_summary
 from ...common import a2a
 from ...common.a2a import (
@@ -489,6 +489,34 @@ async def handle_a2a_request(component, message: SolaceMessage):
                                 logical_task_id,
                                 sub_task_info,
                             )
+                else:
+                    # No peer sub-tasks - check if task is paused and needs immediate finalization
+                    if task_context.get_is_paused():
+                        log.info(
+                            "%s Task %s is paused with no peer sub-tasks. Scheduling immediate finalization.",
+                            component.log_identifier,
+                            logical_task_id,
+                        )
+                        loop = component.get_async_loop()
+                        if loop and loop.is_running():
+                            task_context.set_paused(False)
+
+                            asyncio.run_coroutine_threadsafe(
+                                component.finalize_task_with_cleanup(
+                                    task_context.a2a_context,
+                                    is_paused=False,
+                                    exception=TaskCancelledError(
+                                        f"Task {logical_task_id} cancelled while paused."
+                                    )
+                                ),
+                                loop,
+                            )
+                        else:
+                            log.error(
+                                "%s Cannot finalize cancelled paused task %s - event loop not available.",
+                                component.log_identifier,
+                                logical_task_id,
+                            )
             else:
                 log.info(
                     "%s No active task found for cancellation (ID: %s) or task already completed. Ignoring signal.",

solace_agent_mesh/agent/protocol/protocol_llm.txt

@@ -78,4 +78,4 @@ await cleanup_agent_session(component, "session_123", "user_456")
 - Integrates with Google ADK for task execution
 - Manages task contexts through `TaskExecutionContext`
 
-# content_hash: 4b8a426320c6f06c621b469c79087c315f5590ef14497ccf17de02eeb66db91d
+# content_hash: 02e6f51922fe92594201d9e7a07ae8469cad977a13297c53db5a75534ca1e9f7

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/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