solace-agent-mesh 0.2.3__py3-none-any.whl → 1.0.1__py3-none-any.whl

solace_agent_mesh/agent/tools/peer_agent_tool.py

@@ -0,0 +1,289 @@
+"""
+ADK Tool implementation for delegating tasks to peer A2A agents over Solace.
+"""
+
+from typing import Any, Dict, Optional, List, Union
+import uuid
+
+from google.adk.tools import BaseTool, ToolContext
+from google.genai import types as adk_types
+from solace_ai_connector.common.log import log
+
+from ...common.types import (
+    Message as A2AMessage,
+    TextPart,
+    FilePart,
+    AgentCard,
+)
+from ...common.constants import DEFAULT_COMMUNICATION_TIMEOUT
+
+PEER_TOOL_PREFIX = "peer_"
+CORRELATION_DATA_PREFIX = "a2a_subtask_"
+
+
+class PeerAgentTool(BaseTool):
+    """
+    An ADK Tool that represents a discovered peer agent and handles task delegation
+    via the A2A protocol over Solace. Uses an asyncio Queue to block and wait for
+    the asynchronous response. Handles artifact passthrough from peer responses.
+    """
+
+    is_long_running = True
+
+    def __init__(self, target_agent_name: str, host_component):
+        """
+        Initializes the PeerAgentTool.
+
+        Args:
+            target_agent_name: The name of the peer agent this tool represents.
+            host_component: A reference to the SamAgentComponent instance.
+        """
+        tool_name = f"{PEER_TOOL_PREFIX}{target_agent_name}"
+        super().__init__(
+            name=tool_name,
+            description=f"Delegate tasks to the {target_agent_name} agent.",
+            is_long_running=True,
+        )
+        self.target_agent_name = target_agent_name
+        self.host_component = host_component
+        self.log_identifier = (
+            f"{host_component.log_identifier}[PeerTool:{target_agent_name}]"
+        )
+        self.sub_task_id: Optional[str] = None
+
+    def _get_peer_agent_card(self) -> Optional[AgentCard]:
+        """Safely retrieves the AgentCard for the target peer."""
+        return self.host_component.peer_agents.get(self.target_agent_name)
+
+    def _get_declaration(self) -> Optional[adk_types.FunctionDeclaration]:
+        """
+        Dynamically generates the FunctionDeclaration based on the peer's AgentCard.
+        Returns None if the peer agent is not currently discovered/allowed.
+        """
+        agent_card = self._get_peer_agent_card()
+        if not agent_card:
+            log.warning(
+                "%s Peer agent '%s' not found in registry. Tool unavailable.",
+                self.log_identifier,
+                self.target_agent_name,
+            )
+            return None
+
+        self.description = (
+            agent_card.description
+            or f"Interact with the {self.target_agent_name} agent."
+        )
+
+        parameters_schema = adk_types.Schema(
+            type=adk_types.Type.OBJECT,
+            properties={
+                "task_description": adk_types.Schema(
+                    type=adk_types.Type.STRING,
+                    description="Detailed description of the task for the peer agent.",
+                ),
+                "user_query": adk_types.Schema(
+                    type=adk_types.Type.STRING,
+                    description="The original user query or relevant context.",
+                ),
+                "data_artifacts": adk_types.Schema(
+                    type=adk_types.Type.ARRAY,
+                    items=adk_types.Schema(type=adk_types.Type.STRING),
+                    description="A list of artifact filenames to be sent to the peer agent for context.",
+                    nullable=True,
+                ),
+            },
+            required=["task_description"],
+        )
+
+        log.debug(
+            "%s Generated declaration for peer '%s'",
+            self.log_identifier,
+            self.target_agent_name,
+        )
+        return adk_types.FunctionDeclaration(
+            name=self.name,
+            description=self.description,
+            parameters=parameters_schema,
+        )
+
+    async def _prepare_a2a_parts(
+        self, args: Dict[str, Any], tool_context: ToolContext
+    ) -> List[Union[TextPart, FilePart]]:
+        """
+        Prepares the A2A message parts from tool arguments, including text and artifacts.
+        """
+        task_description = args.get("task_description", "No description provided.")
+        calling_agent_name = self.host_component.agent_name or "Unknown Agent"
+
+        # Create the multi-agent context message
+        context_message = (
+            f"You are part of a multi-agent AI platform. The task below is being sent to you by agent '{calling_agent_name}'. "
+            f"You must perform this task to the best of your abilities. All artifacts that you create will automatically be "
+            f"returned to the calling agent, but you must provide context and description for which artifacts are important "
+            f"and how they should be used. Note that the calling agent will not see any of your history - only the text "
+            f"that you respond with.\n\n"
+            f"Now please execute this task that was given to you:\n\n{task_description}"
+        )
+
+        a2a_message_parts = [TextPart(text=context_message)]
+
+        artifact_names = args.get("data_artifacts", [])
+        if not isinstance(artifact_names, list):
+            log.warning(
+                "%s 'data_artifacts' argument is not a list, ignoring. Value: %s",
+                self.log_identifier,
+                artifact_names,
+            )
+            artifact_names = []
+
+        if artifact_names:
+            log.debug(
+                "%s Preparing to include %d artifacts in peer request.",
+                self.log_identifier,
+                len(artifact_names),
+            )
+            a2a_context = tool_context.state.get("a2a_context", {})
+            for artifact_name in artifact_names:
+                try:
+                    loaded_part = (
+                        await self.host_component.artifact_service.load_artifact(
+                            app_name=tool_context._invocation_context.app_name,
+                            user_id=tool_context._invocation_context.user_id,
+                            session_id=tool_context._invocation_context.session.id,
+                            filename=artifact_name,
+                            version=None,
+                        )
+                    )
+                    if loaded_part:
+                        a2a_file_part = await self.host_component._translate_adk_part_to_a2a_filepart(
+                            loaded_part, artifact_name, a2a_context
+                        )
+                        if a2a_file_part:
+                            a2a_message_parts.append(a2a_file_part)
+                            log.info(
+                                "%s Included latest artifact '%s' in peer request.",
+                                self.log_identifier,
+                                artifact_name,
+                            )
+                        else:
+                            log.warning(
+                                "%s Failed to translate loaded artifact '%s' to A2A part. Skipping.",
+                                self.log_identifier,
+                                artifact_name,
+                            )
+                    else:
+                        log.warning(
+                            "%s Could not load artifact '%s' to include in peer request. Skipping.",
+                            self.log_identifier,
+                            artifact_name,
+                        )
+                except Exception as e:
+                    log.exception(
+                        "%s Error loading artifact '%s' for peer request: %s",
+                        self.log_identifier,
+                        artifact_name,
+                        e,
+                    )
+        return a2a_message_parts
+
+    async def run_async(
+        self, *, args: Dict[str, Any], tool_context: ToolContext
+    ) -> Any:
+        """
+        Handles the delegation of a task to a peer agent in a non-blocking,
+        "fire-and-forget" manner suitable for a long-running tool.
+        """
+        sub_task_id = f"{CORRELATION_DATA_PREFIX}{uuid.uuid4().hex}"
+        log_identifier = f"{self.log_identifier}[SubTask:{sub_task_id}]"
+        main_logical_task_id = "unknown_task"
+
+        try:
+            agent_card = self._get_peer_agent_card()
+            if not agent_card:
+                raise ValueError(
+                    f"Peer agent '{self.target_agent_name}' not found or unavailable."
+                )
+
+            original_task_context = tool_context.state.get("a2a_context", {})
+            main_logical_task_id = original_task_context.get(
+                "logical_task_id", "unknown_task"
+            )
+            original_session_id = tool_context._invocation_context.session.id
+            user_id = tool_context._invocation_context.user_id
+            user_config = original_task_context.get("a2a_user_config", {})
+
+            invocation_id = tool_context._invocation_context.invocation_id
+            timeout_sec = self.host_component.get_config(
+                "inter_agent_communication", {}
+            ).get("request_timeout_seconds", DEFAULT_COMMUNICATION_TIMEOUT)
+
+            task_context_obj = None
+            with self.host_component.active_tasks_lock:
+                task_context_obj = self.host_component.active_tasks.get(
+                    main_logical_task_id
+                )
+
+            if not task_context_obj:
+                raise ValueError(
+                    f"TaskExecutionContext not found for task '{main_logical_task_id}'"
+                )
+
+            task_context_obj.register_parallel_call_sent(invocation_id)
+            log.info(
+                "%s Registered parallel call for invocation %s. Current state: %s",
+                log_identifier,
+                invocation_id,
+                task_context_obj.parallel_tool_calls.get(invocation_id),
+            )
+
+            a2a_message_parts = await self._prepare_a2a_parts(args, tool_context)
+            a2a_message = A2AMessage(role="user", parts=a2a_message_parts)
+
+            correlation_data = {
+                "adk_function_call_id": tool_context.function_call_id,
+                "original_task_context": original_task_context,
+                "peer_tool_name": self.name,
+                "logical_task_id": main_logical_task_id,
+                "invocation_id": invocation_id,
+            }
+
+            self.host_component.cache_service.add_data(
+                key=sub_task_id,
+                value=correlation_data,
+                expiry=timeout_sec,
+                component=self.host_component,
+            )
+
+            self.host_component.submit_a2a_task(
+                target_agent_name=self.target_agent_name,
+                a2a_message=a2a_message,
+                original_session_id=original_session_id,
+                main_logical_task_id=main_logical_task_id,
+                user_id=user_id,
+                user_config=user_config,
+                sub_task_id=sub_task_id,
+                function_call_id=tool_context.function_call_id,
+            )
+
+            task_context_obj.register_peer_sub_task(
+                sub_task_id=sub_task_id, peer_agent_name=self.target_agent_name
+            )
+            log.info(
+                "%s Registered active peer sub-task %s for main task %s.",
+                log_identifier,
+                sub_task_id,
+                main_logical_task_id,
+            )
+
+            log.info(
+                "%s Task fired. Returning to unblock ADK framework.",
+                log_identifier,
+            )
+            return None
+
+        except Exception as e:
+            log.exception("%s Error during peer tool execution: %s", log_identifier, e)
+            return {
+                "status": "error",
+                "message": f"Failed to delegate task to peer agent '{self.target_agent_name}': {e}",
+            }

solace_agent_mesh/agent/tools/registry.py

@@ -0,0 +1,36 @@
+"""
+A singleton registry for discovering and holding all BuiltinTool definitions.
+"""
+
+from typing import Dict, List, Optional
+from .tool_definition import BuiltinTool
+from solace_ai_connector.common.log import log
+
+
+class _ToolRegistry:
+    def __init__(self):
+        self._tools: Dict[str, BuiltinTool] = {}
+
+    def register(self, tool: BuiltinTool):
+        if tool.name in self._tools:
+            log.warning("Tool '%s' is already registered. Overwriting.", tool.name)
+        self._tools[tool.name] = tool
+
+    def get_tool_by_name(self, name: str) -> Optional[BuiltinTool]:
+        """Returns a tool by its registered name."""
+        return self._tools.get(name)
+
+    def get_tools_by_category(self, category_name: str) -> List[BuiltinTool]:
+        """Returns a list of all tools belonging to a specific category."""
+        return [tool for tool in self._tools.values() if tool.category == category_name]
+
+    def get_all_tools(self) -> List[BuiltinTool]:
+        return list(self._tools.values())
+
+    def clear(self):
+        """Clears all registered tools. For testing purposes only."""
+        self._tools.clear()
+        log.debug("Tool registry cleared.")
+
+
+tool_registry = _ToolRegistry()

solace_agent_mesh/agent/tools/test_tools.py

@@ -0,0 +1,135 @@
+"""
+Test-specific ADK Tools.
+"""
+
+import asyncio
+from typing import Dict, Optional, Any
+
+from google.adk.tools import ToolContext
+from solace_ai_connector.common.log import log
+
+from google.genai import types as adk_types
+from .tool_definition import BuiltinTool
+from .registry import tool_registry
+
+
+async def time_delay(
+    seconds: float,
+    tool_context: ToolContext = None,
+    tool_config: Optional[Dict[str, Any]] = None,
+) -> Dict[str, any]:
+    """
+    Pauses execution for a specified number of seconds.
+    Useful for testing timeouts and asynchronous behavior.
+
+    Args:
+        seconds: The duration of the delay in seconds.
+        tool_context: The context provided by the ADK framework.
+
+    Returns:
+        A dictionary indicating the status and duration of the delay.
+    """
+    log_identifier = "[TestTool:time_delay]"
+    log.info("%s Requesting delay for %.2f seconds.", log_identifier, seconds)
+
+    if not tool_context:
+        log.warning("%s ToolContext is missing.", log_identifier)
+
+    try:
+        if not isinstance(seconds, (int, float)) or seconds < 0:
+            log.error(
+                "%s Invalid 'seconds' argument: %s. Must be a non-negative number.",
+                log_identifier,
+                seconds,
+            )
+            return {
+                "status": "error",
+                "message": f"Invalid 'seconds' argument: {seconds}. Must be a non-negative number.",
+            }
+
+        await asyncio.sleep(float(seconds))
+        log.info("%s Successfully delayed for %.2f seconds.", log_identifier, seconds)
+        return {
+            "status": "success",
+            "message": f"Delayed for {seconds} seconds.",
+            "delayed_seconds": seconds,
+        }
+    except Exception as e:
+        log.exception("%s Error during time_delay: %s", log_identifier, e)
+        return {
+            "status": "error",
+            "message": f"Error during delay: {e}",
+            "requested_seconds": seconds,
+        }
+
+
+time_delay_tool_def = BuiltinTool(
+    name="time_delay",
+    implementation=time_delay,
+    description="Pauses execution for a specified number of seconds. Useful for testing timeouts and asynchronous behavior.",
+    category="test",
+    required_scopes=["tool:test:delay"],
+    parameters=adk_types.Schema(
+        type=adk_types.Type.OBJECT,
+        properties={
+            "seconds": adk_types.Schema(
+                type=adk_types.Type.NUMBER,
+                description="The duration of the delay in seconds.",
+            ),
+        },
+        required=["seconds"],
+    ),
+    examples=[],
+)
+
+
+def always_fail_tool() -> dict:
+    """This tool is designed to always raise an exception for testing error handling."""
+    raise ValueError("This tool is designed to fail.")
+
+
+def dangling_tool_call_test_tool() -> None:
+    """
+    This tool is designed to return None, which simulates a silent failure
+    where the ADK does not create a function_response, leaving a dangling
+    function_call in the history. This is used to test the proactive
+    history repair callback ("the suspenders").
+    """
+    log.info(
+        "[TestTool:dangling_tool_call] Executing and returning None to create a dangling tool call."
+    )
+    return None
+
+
+always_fail_tool_def = BuiltinTool(
+    name="always_fail_tool",
+    implementation=always_fail_tool,
+    description="This tool is designed to always raise an exception for testing error handling.",
+    category="test",
+    required_scopes=["tool:test:fail"],
+    parameters=adk_types.Schema(
+        type=adk_types.Type.OBJECT,
+        properties={},
+        required=[],
+    ),
+    examples=[],
+)
+
+dangling_tool_call_test_tool_def = BuiltinTool(
+    name="dangling_tool_call_test_tool",
+    implementation=dangling_tool_call_test_tool,
+    description="A test tool that returns None to create a dangling tool call in the history.",
+    category="test",
+    required_scopes=["tool:test:dangle"],
+    parameters=adk_types.Schema(
+        type=adk_types.Type.OBJECT,
+        properties={},
+        required=[],
+    ),
+    examples=[],
+)
+
+
+tool_registry.register(time_delay_tool_def)
+tool_registry.register(always_fail_tool_def)
+tool_registry.register(dangling_tool_call_test_tool_def)

solace_agent_mesh/agent/tools/tool_definition.py

@@ -0,0 +1,45 @@
+"""
+Defines the Pydantic model for a self-contained BuiltinTool definition.
+"""
+
+from typing import Callable, List, Dict, Any, Optional
+from pydantic import BaseModel, Field
+from google.genai import types as adk_types
+
+
+class BuiltinTool(BaseModel):
+    """A self-contained, declarative definition for a built-in agent tool."""
+
+    name: str = Field(..., description="The function name the LLM will call.")
+    implementation: Callable = Field(
+        ..., description="The async Python function that implements the tool."
+    )
+    description: str = Field(
+        ...,
+        description="High-level description for the LLM to understand the tool's purpose.",
+    )
+    parameters: adk_types.Schema = Field(
+        ..., description="The OpenAPI-like schema for the tool's parameters."
+    )
+    examples: List[Dict[str, Any]] = Field(
+        default_factory=list, description="Few-shot examples for the LLM."
+    )
+    required_scopes: List[str] = Field(
+        default_factory=list,
+        description="A list of scopes required to execute this tool.",
+    )
+    category: str = Field(
+        default="General",
+        description="A category for grouping tools, e.g., 'Artifact', 'Data Analysis'. Used for configuration toggles.",
+    )
+    initializer: Optional[Callable[[Any, Dict[str, Any]], None]] = Field(
+        default=None,
+        description="An optional function to initialize the tool or its dependencies.",
+    )
+    raw_string_args: List[str] = Field(
+        default_factory=list,
+        description="A list of argument names that should be passed as raw strings without embed pre-resolution.",
+    )
+
+    class Config:
+        arbitrary_types_allowed = True

solace_agent_mesh/agent/tools/tools_llm.txt

@@ -0,0 +1,104 @@
+## Quick Summary
+The `tools` directory contains the complete set of built-in tools available to the agent. It follows a declarative, registry-based pattern where each tool module defines its functions and registers them with a central `tool_registry`. This allows for automatic discovery and dynamic availability of tools based on configuration and agent capabilities. The tools cover a wide range of functionalities including artifact management, audio/image processing, data analysis, web requests, and inter-agent communication.
+
+## Files Overview
+- `__init__.py`: Imports all tool modules, triggering their registration with the central registry.
+- `audio_tools.py`: Provides tools for text-to-speech (TTS), multi-speaker TTS, audio concatenation, and transcription.
+- `builtin_artifact_tools.py`: Contains core tools for creating, listing, loading, modifying, and deleting artifacts.
+- `builtin_data_analysis_tools.py`: Offers tools for generating charts from Plotly configurations.
+- `general_agent_tools.py`: Includes general-purpose utilities like file-to-markdown conversion and Mermaid diagram generation.
+- `image_tools.py`: Provides tools for image generation, editing, and vision-based description of images and audio.
+- `peer_agent_tool.py`: Defines the `PeerAgentTool` class for delegating tasks to other agents.
+- `registry.py`: Implements the singleton `tool_registry` for managing all tool definitions.
+- `test_tools.py`: Contains tools specifically for testing agent behavior, such as delays and failures.
+- `tool_definition.py`: Defines the `BuiltinTool` Pydantic model used for declaring tools.
+- `web_tools.py`: Contains a tool for making HTTP requests to external web resources.
+
+## Developer API Reference
+
+### __init__.py
+**Purpose:** This 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.
+**Import:** `import src.solace_agent_mesh.agent.tools`
+
+**Usage Examples:**
+```python
+# Importing the tools package is sufficient to register all built-in tools.
+import src.solace_agent_mesh.agent.tools
+
+# You can then access the registry to see all registered tools.
+from src.solace_agent_mesh.agent.tools.registry import tool_registry
+all_tools = tool_registry.get_all_tools()
+print(f"Registered {len(all_tools)} tools.")
+```
+
+### audio_tools.py
+**Purpose:** This file provides a collection of tools for audio processing, including text-to-speech (TTS) generation, audio concatenation, and transcription.
+**Import:** `from src.solace_agent_mesh.agent.tools.audio_tools import select_voice, text_to_speech, multi_speaker_text_to_speech, concatenate_audio, transcribe_audio`
+
+**Functions:**
+- `select_voice(gender: Optional[str] = None, tone: Optional[str] = None, exclude_voices: Optional[List[str]] = None, tool_context: ToolContext = None, tool_config: Optional[Dict[str, Any]] = None) -> Dict[str, Any]` - Selects a suitable voice name based on criteria like gender and tone. Use this to get a consistent voice name that can be passed to the `text_to_speech` tool for multiple calls.
+- `text_to_speech(text: str, output_filename: Optional[str] = None, voice_name: Optional[str] = None, gender: Optional[str] = None, tone: Optional[str] = None, language: Optional[str] = None, tool_context: ToolContext = None, tool_config: Optional[Dict[str, Any]] = None) -> Dict[str, Any]` - Converts text to speech using Gemini TTS API and saves as an MP3 artifact.
+- `multi_speaker_text_to_speech(conversation_text: str, output_filename: Optional[str] = None, speaker_configs: Optional[List[Dict[str, str]]] = None, language: Optional[str] = None, tool_context: ToolContext = None, tool_config: Optional[Dict[str, Any]] = None) -> Dict[str, Any]` - Converts conversation text with speaker labels to speech using multiple voices.
+- `concatenate_audio(clips_to_join: List[Dict[str, Any]], output_filename: Optional[str] = None, tool_context: ToolContext = None, tool_config: Optional[Dict[str, Any]] = None) -> Dict[str, Any]` - Combines multiple audio artifacts in a specified order into a single audio file, with optional pauses.
+- `transcribe_audio(audio_filename: str, tool_context: ToolContext = None, tool_config: Optional[Dict[str, Any]] = None) -> Dict[str, Any]` - Transcribes an audio recording using an OpenAI-compatible audio transcription API.
+
+**Constants/Variables:**
+- `ALL_AVAILABLE_VOICES: List[str]` - A list of all available voice names for TTS.
+- `SUPPORTED_LANGUAGES: Dict[str, str]` - A mapping of common language names to their BCP-47 codes.
+- `VOICE_TONE_MAPPING: Dict[str, List[str]]` - A dictionary mapping descriptive tones to lists of voice names.
+- `GENDER_TO_VOICE_MAPPING: Dict[str, List[str]]` - A dictionary mapping genders ('male', 'female', 'neutral') to lists of voice names.
+
+**Usage Examples:**
+```python
+# Assume 'tool_context' is a valid ToolContext object.
+
+# 1. Generate a simple audio file
+tts_result = await text_to_speech(
+    text="Welcome to the developer guide.",
+    output_filename="welcome.mp3",
+    gender="female",
+    tone="friendly",
+    language="en-US",
+    tool_context=tool_context
+)
+print(tts_result)
+
+# 2. Generate a multi-speaker conversation
+convo_result = await multi_speaker_text_to_speech(
+    conversation_text="SpeakerA: How are you?\nSpeakerB: I am fine, thank you.",
+    speaker_configs=[
+        {"name": "SpeakerA", "gender": "male", "tone": "warm"},
+        {"name": "SpeakerB", "gender": "female", "tone": "bright"}
+    ],
+    output_filename="dialogue.mp3",
+    tool_context=tool_context
+)
+print(convo_result)
+
+# 3. Concatenate the generated audio files
+concat_result = await concatenate_audio(
+    clips_to_join=[
+        {"filename": "welcome.mp3:1", "pause_after_ms": 500},
+        {"filename": "dialogue.mp3:1"}
+    ],
+    output_filename="combined_audio.mp3",
+    tool_context=tool_context
+)
+print(concat_result)
+
+# 4. Transcribe the combined audio
+transcribe_result = await transcribe_audio(
+    audio_filename="combined_audio.mp3:1",
+    tool_context=tool_context
+)
+print(transcribe_result)
+```
+
+### builtin_artifact_tools.py
+**Purpose:** This file provides the core tools for artifact management, allowing the agent to create, read, list, update, and delete data artifacts within the current session.
+**Import:** `from src.solace_agent_mesh.agent.tools.builtin_artifact_tools import list_artifacts, load_artifact, signal_artifact_for_return, append_to_artifact, apply_embed_and_create_artifact, extract_content_from_artifact, delete_artifact`
+
+**Functions:**
+- `list_artifacts(tool_context: ToolContext = None) -> Dict[str, Any]` - Lists all available data artifact filenames and their versions for the current session.
+- `load_artifact(filename: str, version: int, load_metadata_only: bool = False, max_content_length: Optional[int] = None, tool_context: ToolContext = None) -> Dict[str, Any]` - Loads the content or metadata of a specific artifact version.
+- `signal_artifact_for_return(filename: str, version: int, tool_context: ToolContext = None