solace-agent-mesh 1.7.1__py3-none-any.whl → 1.13.2__py3-none-any.whl

solace_agent_mesh/agent/tools/peer_agent_tool.py

@@ -20,6 +20,7 @@ from ...common.exceptions import MessageSizeExceededError
 
 log = logging.getLogger(__name__)
 
+
 class ArtifactIdentifier(BaseModel):
     """Identifies a specific version of an artifact."""
 
@@ -74,6 +75,81 @@ class PeerAgentTool(BaseTool):
         """Safely retrieves the AgentCard for the target peer."""
         return self.host_component.peer_agents.get(self.target_agent_name)
 
+    def _build_enhanced_description(self, agent_card: AgentCard) -> str:
+        """
+        Builds an enhanced description including skills.
+        Returns a structured, markdown-formatted description with:
+        - Base description
+        - Skills section (if skills are available)
+        - Summary format (counts + skill names, up to 8 skills before truncation)
+        - Soft limit of ~500 chars (allows overflow to ~600 for important info)
+
+        Args:
+            agent_card: The AgentCard to extract information from
+
+        Returns:
+            Enhanced description string with markdown formatting
+        """
+        # Start with base description - ensure it's clean (no extra whitespace)
+        base_desc = (
+            agent_card.description
+            or f"Interact with the {self.target_agent_name} agent."
+        )
+        base_desc = " ".join(base_desc.split())  # Normalize whitespace
+
+        # Extract skills information
+        if agent_card.skills and len(agent_card.skills) > 0:
+            skill_count = len(agent_card.skills)
+            # Get first 8 skill names
+            max_skills_to_show = 8
+            skill_names = []
+            for skill in agent_card.skills[:max_skills_to_show]:
+                # Prefer name, fallback to id
+                skill_name = getattr(skill, "name", None) or getattr(skill, "id", None)
+                if skill_name:
+                    skill_names.append(skill_name)
+
+            skills_str = ", ".join(skill_names)
+            # Add truncation indicator with count if there are more skills
+            if skill_count > max_skills_to_show:
+                remaining = skill_count - max_skills_to_show
+                skills_str += f" ({remaining} more...)"
+
+            # Include skill count in the header
+            if skill_count > 1:
+                enhanced_desc = (
+                    f"{base_desc}\n\n**Skills ({skill_count}):** {skills_str}"
+                )
+            else:
+                enhanced_desc = f"{base_desc}\n\n**Skills:** {skills_str}"
+
+            # Check length and truncate if needed (soft limit ~600 chars)
+            if len(enhanced_desc) > 600:
+                # Truncate to first 4 skills to keep it concise
+                skill_names = []
+                for skill in agent_card.skills[:4]:
+                    skill_name = getattr(skill, "name", None) or getattr(
+                        skill, "id", None
+                    )
+                    if skill_name:
+                        skill_names.append(skill_name)
+                skills_str = ", ".join(skill_names)
+                if skill_count > 4:
+                    remaining = skill_count - 4
+                    skills_str += f" ({remaining} more...)"
+
+                if skill_count > 1:
+                    enhanced_desc = (
+                        f"{base_desc}\n\n**Skills ({skill_count}):** {skills_str}"
+                    )
+                else:
+                    enhanced_desc = f"{base_desc}\n\n**Skills:** {skills_str}"
+        else:
+            # No skills - just return base description
+            enhanced_desc = base_desc
+
+        return enhanced_desc
+
     def _get_declaration(self) -> Optional[adk_types.FunctionDeclaration]:
         """
         Dynamically generates the FunctionDeclaration based on the peer's AgentCard.
@@ -88,10 +164,8 @@ class PeerAgentTool(BaseTool):
             )
             return None
 
-        self.description = (
-            agent_card.description
-            or f"Interact with the {self.target_agent_name} agent."
-        )
+        # Use enhanced description with capabilities information
+        self.description = self._build_enhanced_description(agent_card)
 
         parameters_schema = adk_types.Schema(
             type=adk_types.Type.OBJECT,
@@ -100,10 +174,6 @@ class PeerAgentTool(BaseTool):
                     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.",
-                ),
                 "artifacts": adk_types.Schema(
                     type=adk_types.Type.ARRAY,
                     items=adk_types.Schema(
@@ -204,13 +274,10 @@ class PeerAgentTool(BaseTool):
                     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),
-            )
+            # NOTE: register_parallel_call_sent is called in
+            # preregister_long_running_tools_callback (after_model_callback)
+            # BEFORE tool execution begins. This prevents race conditions where
+            # one tool completes before another registers.
 
             a2a_message_parts = self._prepare_a2a_parts(args, tool_context)
             a2a_metadata = {}

solace_agent_mesh/agent/tools/time_tools.py

@@ -0,0 +1,126 @@
+"""
+Collection of Python tools for time and date operations.
+"""
+
+import logging
+from datetime import datetime
+from zoneinfo import ZoneInfo
+from typing import Any, Dict, Optional
+
+from google.adk.tools import ToolContext
+from google.genai import types as adk_types
+
+from .tool_definition import BuiltinTool
+from .registry import tool_registry
+from ...agent.utils.context_helpers import get_user_timezone
+
+log = logging.getLogger(__name__)
+
+CATEGORY_NAME = "Time & Date"
+CATEGORY_DESCRIPTION = "Get current time and date information in the user's timezone."
+
+
+async def get_current_time(
+    tool_context: ToolContext = None,
+    tool_config: Optional[Dict[str, Any]] = None,
+) -> Dict[str, Any]:
+    """
+    Gets the current date and time in the user's local timezone.
+
+    Args:
+        tool_context: The context provided by the ADK framework.
+        tool_config: Optional. Configuration passed by the ADK, generally not used by this tool.
+
+    Returns:
+        A dictionary with status, current time information, and timezone details.
+    """
+    log_identifier = "[TimeTools:get_current_time]"
+    
+    if not tool_context:
+        log.error(f"{log_identifier} ToolContext is missing.")
+        return {"status": "error", "message": "ToolContext is missing."}
+
+    try:
+        inv_context = tool_context._invocation_context
+        if not inv_context:
+            raise ValueError("InvocationContext is not available.")
+
+        # Get user's timezone from context
+        user_timezone_str = get_user_timezone(inv_context)
+        log.info(f"{log_identifier} Retrieved timezone: {user_timezone_str}")
+
+        # Create timezone object
+        try:
+            user_tz = ZoneInfo(user_timezone_str)
+        except Exception as tz_error:
+            log.warning(
+                f"{log_identifier} Invalid timezone '{user_timezone_str}', falling back to UTC: {tz_error}"
+            )
+            user_tz = ZoneInfo("UTC")
+            user_timezone_str = "UTC"
+
+        # Get current time in user's timezone
+        current_time = datetime.now(user_tz)
+
+        # Calculate timezone offset
+        offset = current_time.strftime("%z")
+        # Format offset as "+HH:MM" or "-HH:MM"
+        if len(offset) == 5:  # Format: +HHMM or -HHMM
+            timezone_offset = f"{offset[:3]}:{offset[3:]}"
+        else:
+            timezone_offset = "+00:00"
+
+        # Get timezone abbreviation (e.g., EST, PST)
+        tz_abbrev = current_time.strftime("%Z")
+
+        # Format various time representations
+        iso_format = current_time.isoformat()
+        formatted_time = current_time.strftime(f"%Y-%m-%d %H:%M:%S {tz_abbrev}")
+        date_only = current_time.strftime("%Y-%m-%d")
+        time_only = current_time.strftime("%H:%M:%S")
+        day_of_week = current_time.strftime("%A")
+        timestamp = int(current_time.timestamp())
+
+        log.info(
+            f"{log_identifier} Successfully retrieved time for timezone {user_timezone_str}: {formatted_time}"
+        )
+
+        return {
+            "status": "success",
+            "current_time": iso_format,
+            "timezone": user_timezone_str,
+            "timezone_offset": timezone_offset,
+            "timezone_abbreviation": tz_abbrev,
+            "formatted_time": formatted_time,
+            "timestamp": timestamp,
+            "date": date_only,
+            "time": time_only,
+            "day_of_week": day_of_week,
+            "message": f"Current time in {user_timezone_str}: {formatted_time}",
+        }
+
+    except ValueError as ve:
+        log.error(f"{log_identifier} Value error: {ve}", exc_info=True)
+        return {"status": "error", "message": str(ve)}
+    except Exception as e:
+        log.exception(f"{log_identifier} Unexpected error in get_current_time: {e}")
+        return {"status": "error", "message": f"An unexpected error occurred: {e}"}
+
+
+get_current_time_tool_def = BuiltinTool(
+    name="get_current_time",
+    implementation=get_current_time,
+    description="Gets the current date and time in the user's local timezone. Returns comprehensive time information including formatted timestamps, timezone details, and date components. Use this tool when you need to know what time it is for the user.",
+    category="time",
+    category_name=CATEGORY_NAME,
+    category_description=CATEGORY_DESCRIPTION,
+    required_scopes=["tool:time:read"],
+    parameters=adk_types.Schema(
+        type=adk_types.Type.OBJECT,
+        properties={},
+        required=[],
+    ),
+    examples=[],
+)
+
+tool_registry.register(get_current_time_tool_def)

solace_agent_mesh/agent/tools/tool_config_types.py

@@ -2,7 +2,7 @@
 Pydantic models for agent tool configurations defined in YAML.
 """
 from typing import Any, Dict, List, Literal, Optional, Union
-from pydantic import Field
+from pydantic import Field, model_validator
 from ...common.utils.pydantic_utils import SamConfigBase
 
 
@@ -47,15 +47,67 @@ class McpToolConfig(BaseToolConfig):
     """Configuration for an MCP tool or toolset."""
     tool_type: Literal["mcp"]
     connection_params: Dict[str, Any]
-    tool_name: Optional[str] = None # Optional filter
+    tool_name: Optional[str] = None  # Single tool filter (backward compat)
+    tool_name_prefix: Optional[str] = None # Optional prefix for tool names
     environment_variables: Optional[Dict[str, Any]] = None
     auth: dict[str, Any] | None = None
     manifest: list[dict[str, Any]] | None = None
 
+    # Tool filtering options (mutually exclusive with each other AND with tool_name)
+    allow_list: Optional[List[str]] = None  # Include only these tools
+    deny_list: Optional[List[str]] = None   # Exclude these tools
+
+    @model_validator(mode='after')
+    def validate_tool_filtering(self):
+        """Ensure tool_name, allow_list, and deny_list are mutually exclusive."""
+        filters_specified = [
+            self.tool_name is not None,
+            self.allow_list is not None,
+            self.deny_list is not None,
+        ]
+        if sum(filters_specified) > 1:
+            raise ValueError(
+                "MCP tool configuration error: 'tool_name', 'allow_list', and 'deny_list' "
+                "are mutually exclusive. Please use only one."
+            )
+        return self
+
+
+class OpenApiToolConfig(BaseToolConfig):
+    """Configuration for OpenAPI-based tools."""
+    tool_type: Literal["openapi"]
+
+    # Specification input (mutually exclusive - only one should be provided)
+    specification_file: Optional[str] = None  # Path to OpenAPI spec file
+    specification: Optional[str] = None       # Inline OpenAPI spec (JSON/YAML)
+    specification_url: Optional[str] = None   # URL to fetch OpenAPI spec from
+    specification_format: Optional[Literal["json", "yaml"]] = None  # Optional format hint
+
+    # Server URL override
+    base_url: Optional[str] = None  # Base URL to override/complete the server URL in the spec
+
+    # Tool filtering (mutually exclusive - only one should be provided)
+    allow_list: Optional[List[str]] = None  # Include only these specific operations/endpoints
+    deny_list: Optional[List[str]] = None   # Exclude these specific operations/endpoints
+
+    # Authentication
+    auth: Optional[Dict[str, Any]] = None
+
+    @model_validator(mode='after')
+    def validate_tool_filtering(self):
+        """Ensure allow_list and deny_list are mutually exclusive."""
+        if self.allow_list is not None and self.deny_list is not None:
+            raise ValueError(
+                "OpenAPI tool configuration error: Cannot specify both 'allow_list' and 'deny_list'. "
+                "Please use only one."
+            )
+        return self
+
 
 AnyToolConfig = Union[
     BuiltinToolConfig,
     BuiltinGroupToolConfig,
     PythonToolConfig,
     McpToolConfig,
+    OpenApiToolConfig,
 ]

solace_agent_mesh/agent/tools/web_search_tools.py

@@ -0,0 +1,279 @@
+"""
+Web Search Tools for Solace Agent Mesh
+Provides web search capabilities using Google Custom Search API.
+
+For other search providers (e.g., Exa, Brave, Tavily), please use the corresponding
+plugins from the solace-agent-mesh-plugins repository.
+"""
+
+import logging
+from typing import Any, Dict, Optional
+from datetime import datetime, timezone
+from google.adk.tools import ToolContext
+
+from ...tools.web_search import GoogleSearchTool, SearchResult
+from .tool_definition import BuiltinTool
+from .registry import tool_registry
+from ...common.rag_dto import create_rag_source, create_rag_search_result
+
+log = logging.getLogger(__name__)
+
+CATEGORY_NAME = "web_search"
+CATEGORY_DESCRIPTION = "Tools for searching the web and retrieving current information"
+
+# State key for tracking search turns within a task/session
+_SEARCH_TURN_STATE_KEY = "web_search_turn_counter"
+
+
+def _get_next_search_turn(tool_context: Optional[ToolContext]) -> int:
+    """
+    Get the next search turn number using tool context state.
+    
+    This approach stores the turn counter in the tool context state, which is:
+    - Per-task/session scoped (not global)
+    - Automatically cleaned up when the task ends
+    
+    Each search within a task gets a unique turn number, so citations from
+    different searches never collide (e.g., s0r0, s0r1 for first search,
+    s1r0, s1r1 for second search).
+    """
+    if not tool_context:
+        # Fallback: return 0 if no context (shouldn't happen in practice)
+        log.warning("[web_search] No tool_context provided, using turn=0")
+        return 0
+    
+    # Get current turn from state, defaulting to 0
+    current_turn = tool_context.state.get(_SEARCH_TURN_STATE_KEY, 0)
+    
+    # Increment for next search
+    tool_context.state[_SEARCH_TURN_STATE_KEY] = current_turn + 1
+    
+    return current_turn
+
+
+async def web_search_google(
+    query: str,
+    max_results: int = 5,
+    search_type: Optional[str] = None,
+    date_restrict: Optional[str] = None,
+    safe_search: Optional[str] = None,
+    tool_context: ToolContext = None,
+    tool_config: Optional[Dict[str, Any]] = None,
+    **kwargs
+) -> str:
+    """
+    Search the web using Google Custom Search API.
+    
+    Args:
+        query: The search query string
+        max_results: Maximum number of results to return (1-10)
+        search_type: Set to 'image' for image search
+        date_restrict: Restrict results by recency (e.g., 'd7' for last 7 days)
+        safe_search: Safe search level - 'off', 'medium', or 'high'
+        tool_context: ADK tool context
+        tool_config: Tool configuration containing API keys
+        
+    Returns:
+        JSON string containing search results with sources for citation
+    """
+    log_identifier = "[web_search_google]"
+    
+    try:
+        config = tool_config or {}
+        api_key = config.get("google_search_api_key")
+        search_engine_id = config.get("google_cse_id")
+        
+        if not api_key or not search_engine_id:
+            error_msg = "google_search_api_key or google_cse_id not configured in tool_config"
+            log.error("%s %s", log_identifier, error_msg)
+            return f"Error: {error_msg}"
+        
+        tool = GoogleSearchTool(
+            api_key=api_key,
+            search_engine_id=search_engine_id
+        )
+        
+        result: SearchResult = await tool.search(
+            query=query,
+            max_results=max_results,
+            search_type=search_type,
+            date_restrict=date_restrict,
+            safe_search=safe_search,
+            **kwargs
+        )
+        
+        if not result.success:
+            log.error("%s Search failed: %s", log_identifier, result.error)
+            return f"Error: {result.error}"
+        
+        # Get unique search turn for this search to prevent citation ID collisions
+        # Uses tool context state (per-task scoped, automatically cleaned up)
+        search_turn = _get_next_search_turn(tool_context)
+        citation_prefix = f"s{search_turn}r"  # e.g., s0r0, s0r1 for first search; s1r0, s1r1 for second
+        
+        log.info(
+            "%s Search successful: %d results, %d images (turn=%d, citation_prefix=%s)",
+            log_identifier,
+            len(result.organic),
+            len(result.images),
+            search_turn,
+            citation_prefix
+        )
+        
+        rag_sources = []
+        valid_citation_ids = []
+        
+        # Log citation-to-source mapping for debugging
+        log.debug("%s === CITATION TO SOURCE MAPPING (turn %d) ===", log_identifier, search_turn)
+        
+        for i, source in enumerate(result.organic):
+            citation_id = f"{citation_prefix}{i}"
+            valid_citation_ids.append(citation_id)
+            
+            # Log each citation mapping at debug level
+            log.debug(
+                "%s Citation [[cite:%s]] -> URL: %s | Title: %s",
+                log_identifier,
+                citation_id,
+                source.link,
+                source.title[:50] if source.title else "N/A"
+            )
+            
+            rag_source = create_rag_source(
+                citation_id=citation_id,
+                file_id=f"web_search_{search_turn}_{i}",
+                filename=source.attribution or source.title,
+                title=source.title,
+                source_url=source.link,
+                url=source.link,
+                content_preview=source.snippet,
+                relevance_score=1.0,
+                source_type="web",
+                retrieved_at=datetime.now(timezone.utc).isoformat(),
+                metadata={
+                    "title": source.title,
+                    "link": source.link,
+                    "type": "web_search",
+                    "favicon": f"https://www.google.com/s2/favicons?domain={source.link}&sz=32" if source.link else ""
+                }
+            )
+            rag_sources.append(rag_source)
+        
+        log.debug("%s === END CITATION MAPPING ===", log_identifier)
+        log.debug("%s Valid citation IDs for this search: %s", log_identifier, valid_citation_ids)
+        
+        for i, image in enumerate(result.images):
+            image_citation_id = f"img{search_turn}r{i}"
+            image_source = create_rag_source(
+                citation_id=image_citation_id,
+                file_id=f"web_search_image_{search_turn}_{i}",
+                filename=image.title or f"Image {i+1}",
+                title=image.title,
+                source_url=image.link,
+                url=image.link,
+                content_preview=image.title or "",
+                relevance_score=1.0,
+                source_type="image",
+                retrieved_at=datetime.now(timezone.utc).isoformat(),
+                metadata={
+                    "title": image.title,
+                    "link": image.link,
+                    "imageUrl": image.imageUrl,
+                    "type": "image",
+                }
+            )
+            rag_sources.append(image_source)
+        
+        rag_metadata = create_rag_search_result(
+            query=query,
+            search_type="web_search",
+            timestamp=datetime.now(timezone.utc).isoformat(),
+            sources=rag_sources
+        )
+        
+        # Build a formatted result string that clearly associates each citation ID with its content
+        # This helps the LLM correctly match citations to facts
+        formatted_results = []
+        formatted_results.append(f"=== SEARCH RESULTS (Turn {search_turn}) ===")
+        formatted_results.append(f"Query: {query}")
+        formatted_results.append(f"Valid citation IDs: {', '.join(valid_citation_ids)}")
+        formatted_results.append("")
+        
+        for i, source in enumerate(result.organic):
+            citation_id = f"{citation_prefix}{i}"
+            formatted_results.append(f"--- RESULT {i+1} ---")
+            formatted_results.append(f"CITATION ID: [[cite:{citation_id}]]")
+            formatted_results.append(f"TITLE: {source.title}")
+            formatted_results.append(f"URL: {source.link}")
+            formatted_results.append(f"CONTENT: {source.snippet}")
+            formatted_results.append(f"USE [[cite:{citation_id}]] to cite facts from THIS result only")
+            formatted_results.append("")
+        
+        formatted_results.append("=== END SEARCH RESULTS ===")
+        formatted_results.append("")
+        formatted_results.append("IMPORTANT: Each citation ID is UNIQUE to its result.")
+        formatted_results.append("Only use a citation ID for facts that appear in THAT specific result's CONTENT.")
+        
+        return {
+            "result": result.model_dump_json(),
+            "formatted_results": "\n".join(formatted_results),
+            "rag_metadata": rag_metadata,
+            "valid_citation_ids": valid_citation_ids,
+            "num_results": len(result.organic),
+            "search_turn": search_turn
+        }
+        
+    except Exception as e:
+        log.exception("%s Unexpected error in Google search: %s", log_identifier, e)
+        return f"Error executing Google search: {str(e)}"
+
+
+web_search_google_tool_def = BuiltinTool(
+    name="web_search_google",
+    implementation=web_search_google,
+    description=(
+        "Search the web using Google Custom Search API. "
+        "Use this when you need up-to-date information from Google. "
+        "Always cite text sources using the citation format provided in your instructions. "
+        "IMPORTANT: Image results will be displayed automatically in the UI - do NOT cite images, do NOT mention image URLs, and do NOT use citation markers like [[cite:imageX]] for images in your response text."
+    ),
+    category=CATEGORY_NAME,
+    category_description=CATEGORY_DESCRIPTION,
+    required_scopes=["tool:web_search:execute"],
+    parameters={
+        "type": "object",
+        "properties": {
+            "query": {
+                "type": "string",
+                "description": "The search query"
+            },
+            "max_results": {
+                "type": "integer",
+                "description": "Maximum number of results (1-10)",
+                "minimum": 1,
+                "maximum": 10,
+                "default": 5
+            },
+            "search_type": {
+                "type": "string",
+                "enum": ["image"],
+                "description": "Set to 'image' for image search"
+            },
+            "date_restrict": {
+                "type": "string",
+                "description": "Restrict results by recency (e.g., 'd7' for last 7 days)"
+            },
+            "safe_search": {
+                "type": "string",
+                "enum": ["off", "medium", "high"],
+                "description": "Safe search level"
+            }
+        },
+        "required": ["query"]
+    },
+)
+
+tool_registry.register(web_search_google_tool_def)
+
+log.info("Web search tools registered: web_search_google")
+log.info("Note: For Exa, Brave, and Tavily search, use plugins from solace-agent-mesh-plugins")