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

solace_agent_mesh/agent/proxies/proxies_llm.txt

@@ -1,283 +0,0 @@
-# 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/sac_llm.txt

@@ -1,189 +0,0 @@
-# DEVELOPER GUIDE for the directory: sac
-
-## Quick Summary
-The `sac` (Solace AI Connector) directory provides the core implementation for hosting a Google ADK (Agent Development Kit) agent within the Solace AI Connector framework. It acts as a bridge, enabling ADK agents to communicate using the A2A (Agent-to-Agent) protocol over Solace messaging. This allows for the creation of distributed, collaborative agent systems where agents can delegate tasks, share information, and work together to solve complex problems.
-
-## Files Overview
-- `__init__.py` - Empty package marker file
-- `app.py` - Custom SAC App class that automatically configures Solace subscriptions and broker settings for A2A communication
-- `component.py` - Main SAC Component that hosts the ADK agent, manages its lifecycle, and handles all A2A protocol messaging
-- `patch_adk.py` - Runtime patches for the Google ADK library to enhance or correct its behavior
-- `task_execution_context.py` - State management class that encapsulates all runtime information for a single, in-flight A2A task
-
-## Developer API Reference
-
-### app.py
-**Purpose:** Provides a custom SAC App class that simplifies the configuration of an A2A agent
-**Import:** `from solace_agent_mesh.agent.sac.app import SamAgentApp`
-
-**Classes:**
-- `SamAgentApp(app_info: Dict[str, Any], **kwargs)` - Custom App class for SAM Agent Host with namespace prefixing and automatic subscription generation
-  - `app_schema: Dict` - Class attribute defining comprehensive configuration schema for agent host validation
-
-**Constants/Variables:**
-- `info: Dict[str, str]` - Metadata dictionary about the SamAgentApp class for SAC framework discovery
-
-**Usage Examples:**
-```python
-# SamAgentApp is typically instantiated by the SAC framework from YAML config
-# Example agent-config.yaml:
-# app:
-#   class_name: solace_agent_mesh.agent.sac.app.SamAgentApp
-#   app_config:
-#     namespace: "my-org/production"
-#     agent_name: "customer-support-agent"
-#     model: "gemini-1.5-pro-latest"
-#     tools:
-#       - tool_type: "builtin"
-#         tool_name: "file_search"
-#     agent_card:
-#       description: "An agent that can answer questions about customer accounts."
-#     agent_card_publishing:
-#       interval_seconds: 60
-#     session_service:
-#       type: "memory"
-```
-
-### component.py
-**Purpose:** Core component that hosts a Google ADK agent and bridges communication to A2A protocol
-**Import:** `from solace_agent_mesh.agent.sac.component import SamAgentComponent`
-
-**Classes:**
-- `SamAgentComponent(**kwargs)` - Solace AI Connector component that hosts a Google ADK agent
-  - `process_event(event: Event) -> None` - Main entry point for all SAC framework events
-  - `handle_timer_event(timer_data: Dict[str, Any]) -> None` - Handles scheduled timer events for agent card publishing
-  - `handle_cache_expiry_event(cache_data: Dict[str, Any]) -> None` - Handles cache expiry events for peer agent timeouts
-  - `finalize_task_success(a2a_context: Dict) -> None` - Async method to finalize successful task completion
-  - `finalize_task_canceled(a2a_context: Dict) -> None` - Finalizes task as CANCELED
-  - `finalize_task_error(exception: Exception, a2a_context: Dict) -> None` - Async method to finalize failed tasks
-  - `cleanup() -> None` - Cleans up resources on component shutdown
-  - `set_agent_specific_state(key: str, value: Any) -> None` - Sets key-value pair in agent state dictionary
-  - `get_agent_specific_state(key: str, default: Optional[Any] = None) -> Any` - Retrieves value from agent state
-  - `get_async_loop() -> Optional[asyncio.AbstractEventLoop]` - Returns dedicated asyncio event loop
-  - `set_agent_system_instruction_string(instruction_string: str) -> None` - Sets static system prompt injection
-  - `set_agent_system_instruction_callback(callback_function: Callable) -> None` - Sets dynamic system prompt callback
-  - `get_gateway_id() -> str` - Returns unique identifier for agent host instance
-  - `submit_a2a_task(target_agent_name: str, a2a_message: A2AMessage, user_id: str, user_config: Dict[str, Any], sub_task_id: str) -> str` - Submits task to peer agent
-  - `get_agent_context() -> Dict[str, Any]` - Returns agent context for middleware interactions
-
-**Constants/Variables:**
-- `info: Dict` - Metadata dictionary for SAC framework
-- `CORRELATION_DATA_PREFIX: str` - Prefix for cache keys when tracking peer requests
-- `HOST_COMPONENT_VERSION: str` - Version string of the host component
-
-**Usage Examples:**
-```python
-# Custom initialization function example
-from solace_agent_mesh.agent.sac.component import SamAgentComponent
-
-def initialize_my_agent(host_component: SamAgentComponent, config: dict):
-    """Custom initialization function for the agent."""
-    # Store database connection in agent state
-    db_connection = create_database_connection(config.get('db_url'))
-    host_component.set_agent_specific_state('db_connection', db_connection)
-    
-    # Set custom system instruction
-    host_component.set_agent_system_instruction_string(
-        "You are a specialized customer service agent with access to our database."
-    )
-
-# Tool accessing agent state
-def my_custom_tool(host_component: SamAgentComponent, query: str) -> str:
-    """Tool that uses stored database connection."""
-    db_connection = host_component.get_agent_specific_state('db_connection')
-    if db_connection:
-        return db_connection.execute_query(query)
-    return "Database not available"
-
-# Scheduling async work from synchronous code
-def schedule_background_task(host_component: SamAgentComponent):
-    """Schedule async work on the component's event loop."""
-    loop = host_component.get_async_loop()
-    if loop:
-        asyncio.run_coroutine_threadsafe(my_async_task(), loop)
-```
-
-### patch_adk.py
-**Purpose:** Contains runtime patches for the Google ADK library to enhance behavior
-**Import:** `from solace_agent_mesh.agent.sac.patch_adk import patch_adk`
-
-**Functions:**
-- `patch_adk() -> None` - Applies all necessary patches to the ADK library
-
-**Usage Examples:**
-```python
-from solace_agent_mesh.agent.sac.patch_adk import patch_adk
-
-# Apply patches before using ADK
-patch_adk()
-```
-
-### task_execution_context.py
-**Purpose:** State management class for single, in-flight agent tasks
-**Import:** `from solace_agent_mesh.agent.sac.task_execution_context import TaskExecutionContext`
-
-**Classes:**
-- `TaskExecutionContext(task_id: str, a2a_context: Dict[str, Any])` - Encapsulates runtime state for a single agent task
-  - `cancel() -> None` - Signals that the task should be cancelled
-  - `is_cancelled() -> bool` - Checks if cancellation event has been set
-  - `append_to_streaming_buffer(text: str) -> None` - Appends text to streaming buffer
-  - `flush_streaming_buffer() -> str` - Returns and clears streaming buffer content
-  - `get_streaming_buffer_content() -> str` - Returns buffer content without clearing
-  - `append_to_run_based_buffer(text: str) -> None` - Appends text to run-based response buffer
-  - `register_peer_sub_task(sub_task_id: str, correlation_data: Dict[str, Any]) -> None` - Adds peer sub-task tracking
-  - `claim_sub_task_completion(sub_task_id: str) -> Optional[Dict[str, Any]]` - Atomically retrieves and removes sub-task data
-  - `register_parallel_call_sent(invocation_id: str) -> None` - Registers new parallel tool call
-  - `handle_peer_timeout(sub_task_id: str, correlation_data: Dict, timeout_sec: int, invocation_id: str) -> bool` - Handles peer timeout
-  - `record_parallel_result(result: Dict, invocation_id: str) -> bool` - Records parallel tool call result
-  - `clear_parallel_invocation_state(invocation_id: str) -> None` - Removes completed invocation state
-  - `register_produced_artifact(filename: str, version: int) -> None` - Tracks newly created artifacts
-  - `add_artifact_signal(signal: Dict[str, Any]) -> None` - Adds artifact return signal
-  - `get_and_clear_artifact_signals() -> List[Dict[str, Any]]` - Retrieves and clears artifact signals
-  - `set_event_loop(loop: asyncio.AbstractEventLoop) -> None` - Stores event loop reference
-  - `get_event_loop() -> Optional[asyncio.AbstractEventLoop]` - Retrieves stored event loop
-  - `record_token_usage(input_tokens: int, output_tokens: int, model: str, source: str = "agent", tool_name: Optional[str] = None, cached_input_tokens: int = 0) -> None` - Records token usage for LLM calls
-  - `get_token_usage_summary() -> Dict[str, Any]` - Returns summary of all token usage for the task
-
-**Usage Examples:**
-```python
-from solace_agent_mesh.agent.sac.task_execution_context import TaskExecutionContext
-
-# Create task context
-a2a_context = {
-    "logical_task_id": "task-123",
-    "user_id": "user-456",
-    "session_id": "session-789"
-}
-task_context = TaskExecutionContext("task-123", a2a_context)
-
-# Use streaming buffer
-task_context.append_to_streaming_buffer("Hello ")
-task_context.append_to_streaming_buffer("world!")
-content = task_context.flush_streaming_buffer()  # Returns "Hello world!"
-
-# Track peer sub-tasks
-correlation_data = {
-    "peer_agent_name": "math-agent",
-    "adk_function_call_id": "call-123"
-}
-task_context.register_peer_sub_task("sub-task-456", correlation_data)
-
-# Handle completion
-completed_data = task_context.claim_sub_task_completion("sub-task-456")
-if completed_data:
-    print(f"Sub-task completed: {completed_data}")
-
-# Track token usage
-task_context.record_token_usage(
-    input_tokens=100,
-    output_tokens=50,
-    model="gemini-1.5-pro",
-    source="agent"
-)
-
-# Get usage summary
-usage = task_context.get_token_usage_summary()
-print(f"Total tokens used: {usage['total_tokens']}")
-```
-
-# content_hash: c80bf39278c35fcb73e1df4421b631aabbdb4ba330e8be028fb8a29e097c3fad

solace_agent_mesh/agent/sac/sac_llm_detail.txt

@@ -1,200 +0,0 @@
-# LLM Summary Detail File
-
-This file is a concatenation of all individual *llm.txt files found in the 'sac' directory tree. Each section below corresponds to a specific directory's summary file.
-
-================================================================================
-
-## Section 1: solace_agent_mesh/agent/sac/sac_llm.txt
-
-**Source file:** `solace_agent_mesh/agent/sac/sac_llm.txt`
-
-# DEVELOPER GUIDE for the directory: sac
-
-## Quick Summary
-The `sac` (Solace AI Connector) directory provides the core implementation for hosting a Google ADK (Agent Development Kit) agent within the Solace AI Connector framework. It acts as a bridge, enabling ADK agents to communicate using the A2A (Agent-to-Agent) protocol over Solace messaging. This allows for the creation of distributed, collaborative agent systems where agents can delegate tasks, share information, and work together to solve complex problems.
-
-## Files Overview
-- `__init__.py` - Empty package marker file
-- `app.py` - Custom SAC App class that automatically configures Solace subscriptions and broker settings for A2A communication
-- `component.py` - Main SAC Component that hosts the ADK agent, manages its lifecycle, and handles all A2A protocol messaging
-- `patch_adk.py` - Runtime patches for the Google ADK library to enhance or correct its behavior
-- `task_execution_context.py` - State management class that encapsulates all runtime information for a single, in-flight A2A task
-
-## Developer API Reference
-
-### app.py
-**Purpose:** Provides a custom SAC App class that simplifies the configuration of an A2A agent
-**Import:** `from solace_agent_mesh.agent.sac.app import SamAgentApp`
-
-**Classes:**
-- `SamAgentApp(app_info: Dict[str, Any], **kwargs)` - Custom App class for SAM Agent Host with namespace prefixing and automatic subscription generation
-  - `app_schema: Dict` - Class attribute defining comprehensive configuration schema for agent host validation
-
-**Constants/Variables:**
-- `info: Dict[str, str]` - Metadata dictionary about the SamAgentApp class for SAC framework discovery
-
-**Usage Examples:**
-```python
-# SamAgentApp is typically instantiated by the SAC framework from YAML config
-# Example agent-config.yaml:
-# app:
-#   class_name: solace_agent_mesh.agent.sac.app.SamAgentApp
-#   app_config:
-#     namespace: "my-org/production"
-#     agent_name: "customer-support-agent"
-#     model: "gemini-1.5-pro-latest"
-#     tools:
-#       - tool_type: "builtin"
-#         tool_name: "file_search"
-#     agent_card:
-#       description: "An agent that can answer questions about customer accounts."
-#     agent_card_publishing:
-#       interval_seconds: 60
-#     session_service:
-#       type: "memory"
-```
-
-### component.py
-**Purpose:** Core component that hosts a Google ADK agent and bridges communication to A2A protocol
-**Import:** `from solace_agent_mesh.agent.sac.component import SamAgentComponent`
-
-**Classes:**
-- `SamAgentComponent(**kwargs)` - Solace AI Connector component that hosts a Google ADK agent
-  - `process_event(event: Event) -> None` - Main entry point for all SAC framework events
-  - `handle_timer_event(timer_data: Dict[str, Any]) -> None` - Handles scheduled timer events for agent card publishing
-  - `handle_cache_expiry_event(cache_data: Dict[str, Any]) -> None` - Handles cache expiry events for peer agent timeouts
-  - `finalize_task_success(a2a_context: Dict) -> None` - Async method to finalize successful task completion
-  - `finalize_task_canceled(a2a_context: Dict) -> None` - Finalizes task as CANCELED
-  - `finalize_task_error(exception: Exception, a2a_context: Dict) -> None` - Async method to finalize failed tasks
-  - `cleanup() -> None` - Cleans up resources on component shutdown
-  - `set_agent_specific_state(key: str, value: Any) -> None` - Sets key-value pair in agent state dictionary
-  - `get_agent_specific_state(key: str, default: Optional[Any] = None) -> Any` - Retrieves value from agent state
-  - `get_async_loop() -> Optional[asyncio.AbstractEventLoop]` - Returns dedicated asyncio event loop
-  - `set_agent_system_instruction_string(instruction_string: str) -> None` - Sets static system prompt injection
-  - `set_agent_system_instruction_callback(callback_function: Callable) -> None` - Sets dynamic system prompt callback
-  - `get_gateway_id() -> str` - Returns unique identifier for agent host instance
-  - `submit_a2a_task(target_agent_name: str, a2a_message: A2AMessage, user_id: str, user_config: Dict[str, Any], sub_task_id: str) -> str` - Submits task to peer agent
-  - `get_agent_context() -> Dict[str, Any]` - Returns agent context for middleware interactions
-
-**Constants/Variables:**
-- `info: Dict` - Metadata dictionary for SAC framework
-- `CORRELATION_DATA_PREFIX: str` - Prefix for cache keys when tracking peer requests
-- `HOST_COMPONENT_VERSION: str` - Version string of the host component
-
-**Usage Examples:**
-```python
-# Custom initialization function example
-from solace_agent_mesh.agent.sac.component import SamAgentComponent
-
-def initialize_my_agent(host_component: SamAgentComponent, config: dict):
-    """Custom initialization function for the agent."""
-    # Store database connection in agent state
-    db_connection = create_database_connection(config.get('db_url'))
-    host_component.set_agent_specific_state('db_connection', db_connection)
-    
-    # Set custom system instruction
-    host_component.set_agent_system_instruction_string(
-        "You are a specialized customer service agent with access to our database."
-    )
-
-# Tool accessing agent state
-def my_custom_tool(host_component: SamAgentComponent, query: str) -> str:
-    """Tool that uses stored database connection."""
-    db_connection = host_component.get_agent_specific_state('db_connection')
-    if db_connection:
-        return db_connection.execute_query(query)
-    return "Database not available"
-
-# Scheduling async work from synchronous code
-def schedule_background_task(host_component: SamAgentComponent):
-    """Schedule async work on the component's event loop."""
-    loop = host_component.get_async_loop()
-    if loop:
-        asyncio.run_coroutine_threadsafe(my_async_task(), loop)
-```
-
-### patch_adk.py
-**Purpose:** Contains runtime patches for the Google ADK library to enhance behavior
-**Import:** `from solace_agent_mesh.agent.sac.patch_adk import patch_adk`
-
-**Functions:**
-- `patch_adk() -> None` - Applies all necessary patches to the ADK library
-
-**Usage Examples:**
-```python
-from solace_agent_mesh.agent.sac.patch_adk import patch_adk
-
-# Apply patches before using ADK
-patch_adk()
-```
-
-### task_execution_context.py
-**Purpose:** State management class for single, in-flight agent tasks
-**Import:** `from solace_agent_mesh.agent.sac.task_execution_context import TaskExecutionContext`
-
-**Classes:**
-- `TaskExecutionContext(task_id: str, a2a_context: Dict[str, Any])` - Encapsulates runtime state for a single agent task
-  - `cancel() -> None` - Signals that the task should be cancelled
-  - `is_cancelled() -> bool` - Checks if cancellation event has been set
-  - `append_to_streaming_buffer(text: str) -> None` - Appends text to streaming buffer
-  - `flush_streaming_buffer() -> str` - Returns and clears streaming buffer content
-  - `get_streaming_buffer_content() -> str` - Returns buffer content without clearing
-  - `append_to_run_based_buffer(text: str) -> None` - Appends text to run-based response buffer
-  - `register_peer_sub_task(sub_task_id: str, correlation_data: Dict[str, Any]) -> None` - Adds peer sub-task tracking
-  - `claim_sub_task_completion(sub_task_id: str) -> Optional[Dict[str, Any]]` - Atomically retrieves and removes sub-task data
-  - `register_parallel_call_sent(invocation_id: str) -> None` - Registers new parallel tool call
-  - `handle_peer_timeout(sub_task_id: str, correlation_data: Dict, timeout_sec: int, invocation_id: str) -> bool` - Handles peer timeout
-  - `record_parallel_result(result: Dict, invocation_id: str) -> bool` - Records parallel tool call result
-  - `clear_parallel_invocation_state(invocation_id: str) -> None` - Removes completed invocation state
-  - `register_produced_artifact(filename: str, version: int) -> None` - Tracks newly created artifacts
-  - `add_artifact_signal(signal: Dict[str, Any]) -> None` - Adds artifact return signal
-  - `get_and_clear_artifact_signals() -> List[Dict[str, Any]]` - Retrieves and clears artifact signals
-  - `set_event_loop(loop: asyncio.AbstractEventLoop) -> None` - Stores event loop reference
-  - `get_event_loop() -> Optional[asyncio.AbstractEventLoop]` - Retrieves stored event loop
-  - `record_token_usage(input_tokens: int, output_tokens: int, model: str, source: str = "agent", tool_name: Optional[str] = None, cached_input_tokens: int = 0) -> None` - Records token usage for LLM calls
-  - `get_token_usage_summary() -> Dict[str, Any]` - Returns summary of all token usage for the task
-
-**Usage Examples:**
-```python
-from solace_agent_mesh.agent.sac.task_execution_context import TaskExecutionContext
-
-# Create task context
-a2a_context = {
-    "logical_task_id": "task-123",
-    "user_id": "user-456",
-    "session_id": "session-789"
-}
-task_context = TaskExecutionContext("task-123", a2a_context)
-
-# Use streaming buffer
-task_context.append_to_streaming_buffer("Hello ")
-task_context.append_to_streaming_buffer("world!")
-content = task_context.flush_streaming_buffer()  # Returns "Hello world!"
-
-# Track peer sub-tasks
-correlation_data = {
-    "peer_agent_name": "math-agent",
-    "adk_function_call_id": "call-123"
-}
-task_context.register_peer_sub_task("sub-task-456", correlation_data)
-
-# Handle completion
-completed_data = task_context.claim_sub_task_completion("sub-task-456")
-if completed_data:
-    print(f"Sub-task completed: {completed_data}")
-
-# Track token usage
-task_context.record_token_usage(
-    input_tokens=100,
-    output_tokens=50,
-    model="gemini-1.5-pro",
-    source="agent"
-)
-
-# Get usage summary
-usage = task_context.get_token_usage_summary()
-print(f"Total tokens used: {usage['total_tokens']}")
-```
-
-================================================================================
-