solace-agent-mesh 0.2.4__py3-none-any.whl → 1.0.2__py3-none-any.whl

solace_agent_mesh/agent/sac/patch_adk.py

@@ -0,0 +1,111 @@
+# =============================================================================
+# ADK PATCHES - Two separate patches to modify ADK behavior
+# =============================================================================
+
+# =============================================================================
+# PATCH 1: Event Content Processing
+# Purpose: Fix event filtering and function response handling in LLM flows
+# =============================================================================
+import google.adk.flows.llm_flows.contents
+from google.adk.flows.llm_flows.contents import _is_event_belongs_to_branch
+from google.adk.flows.llm_flows.contents import _is_auth_event
+from google.adk.flows.llm_flows.contents import _convert_foreign_event
+from google.adk.flows.llm_flows.contents import _is_other_agent_reply
+from google.adk.flows.llm_flows.contents import _rearrange_events_for_async_function_responses_in_history
+from google.adk.flows.llm_flows.contents import remove_client_function_call_id
+from google.adk.events.event import Event
+
+import copy
+from typing import Optional
+
+from google.genai import types
+
+def _patch_get_contents(
+    current_branch: Optional[str], events: list[Event], agent_name: str = ''
+) -> list[types.Content]:
+  """Get the contents for the LLM request.
+
+  Applies filtering, rearrangement, and content processing to events.
+
+  Args:
+    current_branch: The current branch of the agent.
+    events: Events to process.
+    agent_name: The name of the agent.
+
+  Returns:
+    A list of processed contents.
+  """
+  filtered_events = []
+  # Parse the events, leaving the contents and the function calls and
+  # responses from the current agent.
+  for event in events:
+    if (
+        not event.content
+        or not event.content.role
+        or not event.content.parts
+        or (event.content.parts[0].text == '' and not event.content.parts[0].function_response)
+    ):
+      # Skip events without content, or generated neither by user nor by model
+      # or has empty text.
+      # E.g. events purely for mutating session states.
+
+      continue
+    if not _is_event_belongs_to_branch(current_branch, event):
+      # Skip events not belong to current branch.
+      continue
+    if _is_auth_event(event):
+      # Skip auth events.
+      continue
+    filtered_events.append(
+        _convert_foreign_event(event)
+        if _is_other_agent_reply(agent_name, event)
+        else event
+    )
+
+  # Rearrange events for proper function call/response pairing
+  result_events = filtered_events
+  result_events = _rearrange_events_for_async_function_responses_in_history(
+      result_events
+  )
+
+  # Convert events to contents
+  contents = []
+  for event in result_events:
+    content = copy.deepcopy(event.content)
+    remove_client_function_call_id(content)
+    contents.append(content)
+  return contents
+
+# =============================================================================
+# PATCH 2: Long-Running Tool Support
+# Purpose: Modify BaseLlmFlow.run_async to properly handle long-running tools
+# =============================================================================
+from google.adk.flows.llm_flows.base_llm_flow import BaseLlmFlow
+from google.adk.agents.invocation_context import InvocationContext
+from typing import AsyncGenerator
+
+async def patch_run_async(
+    self, invocation_context: InvocationContext
+) -> AsyncGenerator[Event, None]:
+    """Runs the flow."""
+    while True:
+        last_event = None
+        has_long_running_call = False
+        async for event in self._run_one_step_async(invocation_context):
+            last_event = event
+            if event.long_running_tool_ids:
+                has_long_running_call = True
+            yield event
+        if not last_event or last_event.is_final_response() or has_long_running_call:
+            break
+        if last_event.partial:
+            # TODO: handle this in BaseLlm level.
+            raise ValueError(
+                f"Last event shouldn't be partial. LLM max output limit may be"
+                f' reached.'
+                )
+
+def patch_adk():
+    """Patch the ADK to use the custom get_contents and run_async methods."""
+    google.adk.flows.llm_flows.contents._get_contents = _patch_get_contents
+    BaseLlmFlow.run_async = patch_run_async

solace_agent_mesh/agent/sac/sac_llm.txt

@@ -0,0 +1,105 @@
+## 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.
+
+The main components are `SamAgentApp`, which handles the initial setup and configuration, and `SamAgentComponent`, which hosts the ADK agent instance, manages its lifecycle, and translates between the A2A protocol and the ADK's internal event model.
+
+## Files Overview
+- `__init__.py`: An empty file that marks the `sac` directory as a Python package.
+- `app.py`: Defines a custom SAC `App` class that automatically configures Solace subscriptions and broker settings for A2A communication.
+- `component.py`: The main SAC `Component` that hosts the ADK agent, manages its lifecycle, and handles all A2A protocol messaging.
+- `patch_adk.py`: Contains runtime patches for the Google ADK library to enhance or correct its behavior for this specific use case.
+- `task_execution_context.py`: A state management class that encapsulates all runtime information for a single, in-flight A2A task.
+
+## Developer API Reference
+
+---
+### __init__.py
+**Purpose:** A standard Python file that makes the `sac` directory a package, allowing its modules to be imported.
+**Import:** This file is not meant to be imported from directly.
+
+---
+### app.py
+**Purpose:** Provides a custom SAC `App` class (`SamAgentApp`) that simplifies the configuration of an A2A agent. It automatically generates the required Solace topic subscriptions and configures the message broker based on the provided `namespace` and `agent_name` in the configuration file. This class is the main entry point for running an agent host.
+**Import:** `from src.solace_agent_mesh.agent.sac.app import SamAgentApp`
+
+**Classes:**
+- `SamAgentApp(app_info: Dict[str, Any], **kwargs)` - A custom App class for the SAM Agent Host. It handles namespace prefixing, automatic subscription generation, and programmatic definition of the `SamAgentComponent`.
+  - `app_schema: Dict` - A class attribute that defines the comprehensive configuration schema for the agent host. This schema is used by the SAC framework to validate the application's YAML configuration file, ensuring all required parameters are present and correctly typed.
+
+**Constants/Variables:**
+- `info: Dict[str, str]` - A dictionary containing metadata about the `SamAgentApp` class, required by the SAC framework for discovery.
+
+**Usage Examples:**
+```python
+# The SamAgentApp is typically instantiated by the Solace AI Connector framework,
+# not directly by a developer. The framework reads a YAML configuration file,
+# validates it against the app_schema, and passes the resulting configuration
+# to the SamAgentApp constructor.
+
+# --- Example agent-config.yaml ---
+# app:
+#   class_name: src.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
+#     agent_discovery:
+#       enabled: true
+#     inter_agent_communication:
+#       allow_list: ["*"]
+#       request_timeout_seconds: 45
+#     session_service:
+#       type: "memory"
+#     # ... other configuration parameters
+```
+
+---
+### component.py
+**Purpose:** This is the core component that hosts a Google ADK agent and bridges its communication to the A2A protocol over Solace. It handles incoming task requests, manages the agent's lifecycle, processes ADK events, orchestrates tool calls (including peer agent delegation), and sends status updates and final responses. Developers can interact with this component's state and lifecycle via custom initialization and cleanup functions.
+**Import:** `from src.solace_agent_mesh.agent.sac.component import SamAgentComponent`
+
+**Classes:**
+- `SamAgentComponent(**kwargs)` - A Solace AI Connector component that hosts a Google ADK agent and communicates via the A2A protocol.
+  - `process_event(self, event: Event)` - The main entry point for all events from the SAC framework (e.g., incoming messages, timers). This method orchestrates the processing of A2A requests.
+  - `handle_timer_event(self, timer_data: Dict[str, Any])` - Handles scheduled timer events, primarily used for periodically publishing the agent's discovery card.
+  - `handle_cache_expiry_event(self, cache_data: Dict[str, Any])` - Handles cache expiry events, used to detect timeouts for requests sent to peer agents.
+  - `finalize_task_success(self, a2a_context: Dict)` - An async method that finalizes a task successfully, sending the final `COMPLETED` response.
+  - `finalize_task_canceled(self, a2a_context: Dict)` - Finalizes a task as `CANCELED` and sends the corresponding response.
+  - `finalize_task_error(self, exception: Exception, a2a_context: Dict)` - An async method that finalizes a task as `FAILED`, sending an error response.
+  - `cleanup(self)` - Cleans up all resources when the component is shut down, including stopping the async loop and calling any custom cleanup functions.
+  - `set_agent_specific_state(self, key: str, value: Any)` - Sets a key-value pair in a dedicated state dictionary. This is intended for use within a custom `agent_init_function` to store state (e.g., database connections, API clients) that can be accessed by tools.
+  - `get_agent_specific_state(self, key: str, default: Optional[Any] = None) -> Any` - Retrieves a value from the agent-specific state dictionary. This is intended for use by tools or a custom `agent_cleanup_function`.
+  - `get_async_loop(self) -> Optional[asyncio.AbstractEventLoop]` - Returns the dedicated asyncio event loop used by the component for all its asynchronous operations. This is useful for scheduling custom async work from synchronous code (e.g., tools).
+  - `set_agent_system_instruction_string(self, instruction_string: str) -> None` - Sets a static string to be injected into the agent's system prompt. This should be called from a custom `agent_init_function`.
+  - `set_agent_system_instruction_callback(self, callback_function: Callable[[CallbackContext, LlmRequest], Optional[str]]) -> None` - Sets a callback function to dynamically generate parts of the system prompt at runtime. This should be called from a custom `agent_init_function`.
+  - `get_gateway_id(self) -> str` - Returns a unique identifier for this agent host instance, typically the agent's name.
+  - `submit_a2a_task(self, target_agent_name: str, a2a_message: A2AMessage, original_session_id: str, main_logical_task_id: str, user_id: str, user_config: Dict[str, Any], sub_task_id: str, function_call_id: Optional[str] = None) -> str` - Submits a task to a peer agent in a non-blocking way. This is the core mechanism for agent delegation. Returns the `sub_task_id` used for correlation.
+  - `get_agent_context(self) -> Dict[str, Any]` - Returns a dictionary containing context about the agent, used for interactions with the middleware system.
+
+**Constants/Variables:**
+- `info: Dict` - A dictionary containing metadata about the `SamAgentComponent` class, required by the SAC framework.
+- `CORRELATION_DATA_PREFIX: str` - A public constant string used as a prefix for cache keys when tracking peer-to-peer requests.
+- `HOST_COMPONENT_VERSION: str` - The version string of the host component.
+
+**Usage Examples:**
+```python
+# This component is instantiated by the SamAgentApp. Developers interact with it
+# primarily through custom init/cleanup functions and by building tools that
+# may need access to its state or methods.
+
+# --- In a custom init module (e.g., my_agent_init.py) ---
+import asyncio
+from src.solace_agent_mesh.agent.sac.component import SamAgentComponent
+from src.solace_agent_mesh.common.types import A2AMessage, TextPart
+
+# This function would be configured in the agent's YAML config
+def initialize_my_agent(host_component: SamAgentComponent, config: dict):
+    """Custom initialization function for the agent."""
+    print("Initializing my custom agent...")

solace_agent_mesh/agent/sac/task_execution_context.py

@@ -0,0 +1,185 @@
+"""
+Encapsulates the runtime state for a single, in-flight agent task.
+"""
+
+import asyncio
+import threading
+from typing import Any, Dict, List, Optional
+
+
+class TaskExecutionContext:
+    """
+    A class to hold all runtime state and control mechanisms for a single agent task.
+    This object is created when a task is initiated and destroyed when it completes,
+    ensuring that all state is properly encapsulated and cleaned up.
+    """
+
+    def __init__(self, task_id: str, a2a_context: Dict[str, Any]):
+        """
+        Initializes the TaskExecutionContext.
+
+        Args:
+            task_id: The unique logical ID of the task.
+            a2a_context: The original, rich context dictionary from the A2A request.
+        """
+        self.task_id: str = task_id
+        self.a2a_context: Dict[str, Any] = a2a_context
+        self.cancellation_event: asyncio.Event = asyncio.Event()
+        self.streaming_buffer: str = ""
+        self.run_based_response_buffer: str = ""
+        self.active_peer_sub_tasks: Dict[str, Dict[str, Any]] = {}
+        self.parallel_tool_calls: Dict[str, Dict[str, Any]] = {}
+        self.produced_artifacts: List[Dict[str, Any]] = []
+        self.artifact_signals_to_return: List[Dict[str, Any]] = []
+        self.event_loop: Optional[asyncio.AbstractEventLoop] = None
+        self.lock: threading.Lock = threading.Lock()
+
+    def cancel(self) -> None:
+        """Signals that the task should be cancelled."""
+        self.cancellation_event.set()
+
+    def is_cancelled(self) -> bool:
+        """Checks if the cancellation event has been set."""
+        return self.cancellation_event.is_set()
+
+    def append_to_streaming_buffer(self, text: str) -> None:
+        """Appends a chunk of text to the main streaming buffer."""
+        with self.lock:
+            self.streaming_buffer += text
+
+    def flush_streaming_buffer(self) -> str:
+        """Returns the entire content of the streaming buffer and clears it."""
+        with self.lock:
+            content = self.streaming_buffer
+            self.streaming_buffer = ""
+            return content
+
+    def get_streaming_buffer_content(self) -> str:
+        """Returns the current buffer content without clearing it."""
+        with self.lock:
+            return self.streaming_buffer
+
+    def append_to_run_based_buffer(self, text: str) -> None:
+        """Appends a chunk of processed text to the run-based response buffer."""
+        with self.lock:
+            self.run_based_response_buffer += text
+
+    def register_peer_sub_task(
+        self, sub_task_id: str, correlation_data: Dict[str, Any]
+    ) -> None:
+        """Adds a new peer sub-task's correlation data to the tracking dictionary."""
+        with self.lock:
+            self.active_peer_sub_tasks[sub_task_id] = correlation_data
+
+    def claim_sub_task_completion(self, sub_task_id: str) -> Optional[Dict[str, Any]]:
+        """
+        Atomically retrieves and removes a sub-task's correlation data.
+        This is the core atomic operation to prevent race conditions.
+        Returns the correlation data if the claim is successful, otherwise None.
+        """
+        with self.lock:
+            return self.active_peer_sub_tasks.pop(sub_task_id, None)
+
+    def register_parallel_call_sent(self, invocation_id: str) -> None:
+        """
+        Registers that a new parallel tool call has been sent for a specific invocation.
+        Initializes the tracking dictionary for the invocation if it's the first call,
+        otherwise increments the total.
+        """
+        with self.lock:
+            if invocation_id not in self.parallel_tool_calls:
+                self.parallel_tool_calls[invocation_id] = {
+                    "total": 1,
+                    "completed": 0,
+                    "results": [],
+                }
+            else:
+                self.parallel_tool_calls[invocation_id]["total"] += 1
+
+    def handle_peer_timeout(
+        self,
+        sub_task_id: str,
+        correlation_data: Dict,
+        timeout_sec: int,
+        invocation_id: str,
+    ) -> bool:
+        """
+        Handles a timeout for a specific peer sub-task for a given invocation.
+
+        Updates the parallel call tracker with a formatted error message and returns
+        True if all peer calls for that invocation are now complete.
+
+        Args:
+            sub_task_id: The ID of the sub-task that timed out.
+            correlation_data: The correlation data associated with the sub-task.
+            timeout_sec: The timeout duration in seconds.
+            invocation_id: The ID of the invocation that initiated the parallel calls.
+
+        Returns:
+            A boolean indicating if all parallel calls for the invocation are now complete.
+        """
+        peer_tool_name = correlation_data.get("peer_tool_name", "unknown_tool")
+        timeout_message = f"Request to peer agent tool '{peer_tool_name}' timed out after {timeout_sec} seconds."
+
+        # The payload must be a dictionary with a 'result' key containing the simple string.
+        # This ensures the ADK framework presents it to the LLM as a simple text response.
+        simple_error_payload = {"result": timeout_message}
+
+        current_result = {
+            "adk_function_call_id": correlation_data.get("adk_function_call_id"),
+            "peer_tool_name": peer_tool_name,
+            "payload": simple_error_payload,
+        }
+        return self.record_parallel_result(current_result, invocation_id)
+
+    def record_parallel_result(self, result: Dict, invocation_id: str) -> bool:
+        """
+        Records a result for a parallel tool call for a specific invocation
+        and returns True if all calls for that invocation are now complete.
+        """
+        with self.lock:
+            invocation_state = self.parallel_tool_calls.get(invocation_id)
+            if not invocation_state:
+                # This can happen if a response arrives after a timeout has cleaned up.
+                return False
+
+            invocation_state["results"].append(result)
+            invocation_state["completed"] += 1
+            return invocation_state["completed"] >= invocation_state["total"]
+
+    def clear_parallel_invocation_state(self, invocation_id: str) -> None:
+        """
+        Removes the state for a completed parallel tool call invocation.
+        """
+        with self.lock:
+            if invocation_id in self.parallel_tool_calls:
+                del self.parallel_tool_calls[invocation_id]
+
+    def register_produced_artifact(self, filename: str, version: int) -> None:
+        """Adds a newly created artifact to the tracking list."""
+        with self.lock:
+            self.produced_artifacts.append({"filename": filename, "version": version})
+
+    def add_artifact_signal(self, signal: Dict[str, Any]) -> None:
+        """Adds an artifact return signal to the list in a thread-safe manner."""
+        with self.lock:
+            self.artifact_signals_to_return.append(signal)
+
+    def get_and_clear_artifact_signals(self) -> List[Dict[str, Any]]:
+        """
+        Retrieves all pending artifact signals and clears the list atomically.
+        """
+        with self.lock:
+            signals = list(self.artifact_signals_to_return)  # Create a copy
+            self.artifact_signals_to_return.clear()
+            return signals
+
+    def set_event_loop(self, loop: asyncio.AbstractEventLoop) -> None:
+        """Stores a reference to the task's event loop."""
+        with self.lock:
+            self.event_loop = loop
+
+    def get_event_loop(self) -> Optional[asyncio.AbstractEventLoop]:
+        """Retrieves the stored event loop."""
+        with self.lock:
+            return self.event_loop

solace_agent_mesh/agent/testing/__init__.py

@@ -0,0 +1,3 @@
+"""
+Contains utilities for testing the A2A agent framework.
+"""

solace_agent_mesh/agent/testing/debug_utils.py

@@ -0,0 +1,135 @@
+"""
+Provides debugging utilities for the declarative test framework,
+including a pretty-printer for A2A event history.
+"""
+
+import json
+from datetime import datetime
+from typing import List, Dict, Any
+
+
+def _truncate(s: str, max_len: int) -> str:
+    """Truncates a string if it exceeds max_len, appending '...'."""
+    if not isinstance(s, str):
+        s = str(s)
+    if max_len <= 0 or len(s) <= max_len:
+        return s
+    if max_len <= 3:
+        return s[:max_len]
+    return s[: max_len - 3] + "..."
+
+
+def _format_a2a_parts(parts: List[Dict], max_string_length: int) -> str:
+    """Helper to format A2A message parts into a readable string."""
+    if not parts:
+        return "[No Parts]"
+
+    formatted_parts = []
+    for part in parts:
+        part_type = part.get("type", "unknown")
+        if part_type == "text":
+            text = part.get("text", "")
+            formatted_parts.append(
+                f"  - [Text]: '{_truncate(text, max_string_length)}'"
+            )
+        elif part_type == "data":
+            data_content = json.dumps(part.get("data", {}))
+            formatted_parts.append(
+                f"  - [Data]: {_truncate(data_content, max_string_length)}"
+            )
+        elif part_type == "file":
+            file_info = part.get("file", {})
+            name = file_info.get("name", "N/A")
+            mime = file_info.get("mimeType", "N/A")
+            formatted_parts.append(
+                f"  - [File]: {_truncate(name, max_string_length)} ({mime})"
+            )
+        else:
+            part_str = json.dumps(part)
+            formatted_parts.append(
+                f"  - [Unknown Part]: {_truncate(part_str, max_string_length)}"
+            )
+    return "\n".join(formatted_parts)
+
+
+def _truncate_dict_strings(data: Any, max_len: int) -> Any:
+    """Recursively traverses a dict/list and truncates all string values."""
+    if max_len <= 0:
+        return data
+    if isinstance(data, dict):
+        return {k: _truncate_dict_strings(v, max_len) for k, v in data.items()}
+    elif isinstance(data, list):
+        return [_truncate_dict_strings(item, max_len) for item in data]
+    elif isinstance(data, str):
+        return _truncate(data, max_len)
+    else:
+        return data
+
+
+def pretty_print_event_history(
+    event_history: List[Dict[str, Any]], max_string_length: int = 200
+):
+    """
+    Formats and prints a list of A2A event payloads for debugging.
+    """
+    if not event_history:
+        print("\n" + "=" * 25 + " NO EVENTS RECORDED " + "=" * 25)
+        print("--- The test failed before any events were received from the agent. ---")
+        print("=" * 70 + "\n")
+        return
+
+    print("\n" + "=" * 25 + " TASK EVENT HISTORY " + "=" * 25)
+    for i, event_payload in enumerate(event_history):
+        print(f"\n--- Event {i+1} ---")
+
+        event_type = "Unknown Event"
+        details = ""
+
+        result = event_payload.get("result", {})
+        error = event_payload.get("error")
+
+        if error:
+            event_type = "Error Response"
+            details += f"  Error Code: {error.get('code')}\n"
+            details += f"  Error Message: {_truncate(error.get('message'), max_string_length)}\n"
+
+        elif result.get("status") and result.get("final") is not None:
+            event_type = "Task Status Update"
+            status = result.get("status", {})
+            state = status.get("state", "UNKNOWN")
+            message = status.get("message", {})
+            parts = message.get("parts", [])
+            details += f"  State: {state}\n"
+            details += f"  Parts:\n{_format_a2a_parts(parts, max_string_length)}\n"
+
+        elif result.get("status") and result.get("sessionId"):
+            event_type = "Final Task Response"
+            status = result.get("status", {})
+            state = status.get("state", "UNKNOWN")
+            message = status.get("message", {})
+            parts = message.get("parts", [])
+            details += f"  Final State: {state}\n"
+            details += (
+                f"  Final Parts:\n{_format_a2a_parts(parts, max_string_length)}\n"
+            )
+            if result.get("artifacts"):
+                artifacts_str = json.dumps(result.get("artifacts"))
+                details += (
+                    f"  Artifacts: {_truncate(artifacts_str, max_string_length)}\n"
+                )
+
+        elif result.get("artifact"):
+            event_type = "Task Artifact Update"
+            artifact = result.get("artifact", {})
+            details += f"  Artifact Name: {_truncate(artifact.get('name'), max_string_length)}\n"
+            details += f"  Artifact Parts:\n{_format_a2a_parts(artifact.get('parts', []), max_string_length)}\n"
+
+        print(f"Type: {event_type}")
+        if details:
+            print(details, end="")
+
+        print("Raw Payload:")
+        truncated_payload = _truncate_dict_strings(event_payload, max_string_length)
+        print(json.dumps(truncated_payload, indent=2))
+
+    print("=" * 70 + "\n")

solace_agent_mesh/agent/testing/testing_llm.txt

@@ -0,0 +1,90 @@
+## Quick Summary
+
+The `testing` directory provides a suite of utilities designed to facilitate the testing of the A2A (Agent-to-Agent) framework. Its primary function is to offer tools that simplify debugging and validation of agent interactions during test runs, particularly for declarative tests.
+
+## Files Overview
+
+-   `__init__.py`: Marks the directory as a Python package.
+-   `debug_utils.py`: Provides helper functions for debugging test failures, most notably a pretty-printer for A2A event histories.
+
+## Developer API Reference
+
+### debug_utils.py
+
+**Purpose:** This module contains utilities to help developers debug failing tests by providing human-readable representations of complex data structures, such as the event history from an A2A task.
+
+**Import:** `from agent.testing.debug_utils import pretty_print_event_history`
+
+**Functions:**
+
+-   `pretty_print_event_history(event_history: List[Dict[str, Any]], max_string_length: int = 200) -> None`
+    Formats and prints a list of A2A event payloads to the console in a structured, readable format. It intelligently parses different event types (status updates, final responses, errors) and truncates long strings to keep the output concise. This is invaluable for quickly diagnosing why a test failed by inspecting the sequence of events leading up to the failure.
+
+**Usage Examples:**
+
+```python
+# Show how to import and use the main classes/functions
+from agent.testing.debug_utils import pretty_print_event_history
+from typing import List, Dict, Any
+
+# Example event history captured during a test run
+sample_event_history: List[Dict[str, Any]] = [
+    {
+        "result": {
+            "status": {
+                "state": "EXECUTING",
+                "message": {
+                    "parts": [
+                        {"type": "text", "text": "Okay, I am starting the process to find the latest sales report."}
+                    ]
+                },
+            },
+            "final": False,
+        }
+    },
+    {
+        "result": {
+            "artifact": {
+                "name": "sales_report_q4.pdf",
+                "parts": [
+                    {
+                        "type": "file",
+                        "file": {
+                            "name": "sales_report_q4.pdf",
+                            "mimeType": "application/pdf",
+                            "uri": "file://path/to/sales_report_q4.pdf"
+                        }
+                    }
+                ]
+            }
+        }
+    },
+    {
+        "error": {
+            "code": "INTERNAL_ERROR",
+            "message": "Failed to access the database due to a connection timeout. The database server at db.example.com might be down or unreachable. Please check the server status and network connectivity."
+        }
+    },
+    {
+        "result": {
+            "status": {
+                "state": "FAILED",
+                "message": {
+                    "parts": [
+                        {"type": "text", "text": "I encountered an error and could not complete the task."}
+                    ]
+                }
+            },
+            "sessionId": "task-12345",
+        }
+    }
+]
+
+# In a test's `tearDown` or `except` block, you can print the history.
+print("A test failed! Dumping the event history for review:")
+pretty_print_event_history(sample_event_history, max_string_length=100)
+
+# Example with no events
+print("\n--- Example with no events ---")
+pretty_print_event_history([])
+```

solace_agent_mesh/agent/tools/__init__.py

@@ -0,0 +1,14 @@
+"""
+This __init__.py file ensures that all built-in tool modules are imported
+when the 'tools' package is loaded. This is crucial for the declarative
+tool registration pattern, as it triggers the `tool_registry.register()`
+calls within each tool module.
+"""
+
+from . import builtin_artifact_tools
+from . import builtin_data_analysis_tools
+from . import general_agent_tools
+from . import audio_tools
+from . import image_tools
+from . import web_tools
+from . import test_tools