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

solace_agent_mesh/shared/exceptions/__init__.py

@@ -0,0 +1,36 @@
+"""
+Exception types and handlers for consistent error handling.
+
+Provides:
+- Business exception types (ValidationError, EntityNotFoundError, etc.)
+- FastAPI exception handlers
+- Error DTOs for API responses
+"""
+
+from .exceptions import (
+    WebUIBackendException,
+    ValidationError,
+    EntityNotFoundError,
+    EntityAlreadyExistsError,
+    BusinessRuleViolationError,
+    ConfigurationError,
+    DataIntegrityError,
+    ExternalServiceError,
+    EntityOperation,
+)
+from .exception_handlers import register_exception_handlers
+from .error_dto import EventErrorDTO
+
+__all__ = [
+    "WebUIBackendException",
+    "ValidationError",
+    "EntityNotFoundError",
+    "EntityAlreadyExistsError",
+    "BusinessRuleViolationError",
+    "ConfigurationError",
+    "DataIntegrityError",
+    "ExternalServiceError",
+    "EntityOperation",
+    "register_exception_handlers",
+    "EventErrorDTO",
+]

solace_agent_mesh/{gateway/http_sse/shared → shared/exceptions}/exception_handlers.py

@@ -193,7 +193,7 @@ def register_exception_handlers(app):
 
     Example:
         from fastapi import FastAPI
-        from solace_agent_mesh.gateway.http_sse.shared.exception_handlers import register_exception_handlers
+        from solace_agent_mesh.shared.exceptions.exception_handlers import register_exception_handlers
 
         app = FastAPI()
         register_exception_handlers(app)

solace_agent_mesh/shared/utils/__init__.py

@@ -0,0 +1,21 @@
+"""
+General utilities for common operations.
+
+Provides:
+- Timestamp utilities (epoch conversions, ISO8601 formatting)
+- Enums
+- Type definitions
+- Generic helper functions
+"""
+
+from .timestamp_utils import (
+    now_epoch_ms,
+    epoch_ms_to_iso8601,
+    iso8601_to_epoch_ms,
+)
+
+__all__ = [
+    "now_epoch_ms",
+    "epoch_ms_to_iso8601",
+    "iso8601_to_epoch_ms",
+]

solace_agent_mesh/templates/logging_config_template.yaml

@@ -0,0 +1,48 @@
+version: 1
+disable_existing_loggers: false
+
+formatters:
+  simpleFormatter:
+    format: "%(asctime)s | %(levelname)-5s | %(threadName)s | %(name)s | %(message)s"
+
+  coloredFormatter:
+    class: solace_ai_connector.logging.ColoredFormatter
+    format: "%(asctime)s | %(levelname)-5s | %(threadName)s | %(name)s | %(message)s"
+
+  jsonFormatter:
+    "()": pythonjsonlogger.json.JsonFormatter
+    format: "%(timestamp)s %(levelname)s %(threadName)s %(name)s %(message)s"
+    timestamp: "timestamp"
+
+handlers:
+  streamHandler:
+    class: logging.StreamHandler
+    formatter: coloredFormatter
+    stream: ext://sys.stdout
+
+  rotatingFileHandler:
+    class: logging.handlers.RotatingFileHandler
+    formatter: simpleFormatter
+    filename: ${LOGGING_FILE_NAME, sam.log}
+    mode: a
+    maxBytes: 52428800
+    backupCount: 10
+
+loggers:
+  solace_ai_connector:
+    level: ${LOGGING_SAC_LEVEL, INFO}
+    handlers: []
+
+  solace_agent_mesh:
+    level: ${LOGGING_SAM_LEVEL, INFO}
+    handlers: []
+
+  sam_trace:
+    level: ${LOGGING_SAM_TRACE_LEVEL, INFO}
+    handlers: []
+
+root:
+  level: ${LOGGING_ROOT_LEVEL, WARNING}
+  handlers:
+    - streamHandler
+    - rotatingFileHandler

solace_agent_mesh/templates/main_orchestrator.yaml

@@ -43,7 +43,18 @@ apps:
         description: "__AGENT_CARD_DESCRIPTION__"
         defaultInputModes: __DEFAULT_INPUT_MODES__
         defaultOutputModes: __DEFAULT_OUTPUT_MODES__
-        skills: [] 
+        skills:
+        - id: strategic_planning
+          name: Strategic Planning
+          description: Analyzes complex requests and creates structured execution plans, breaking down multi-step goals into logical sequences with clear checkpoints and progress tracking.
+
+        - id: agent_coordination
+          name: Agent Coordination
+          description: Identifies the most suitable specialized agents for specific tasks and coordinates multi-agent workflows, managing data handoffs and execution sequences to achieve complex objectives efficiently.
+
+        - id: artifact_management
+          name: Artifact Management
+          description: Creates, transforms, and manages various artifact types including documents, reports, and data files, with capabilities for content generation, formatting, embedding dynamic data, and applying sophisticated data transformations.
 
       agent_card_publishing: 
         interval_seconds: __AGENT_CARD_PUBLISHING_INTERVAL__

solace_agent_mesh/templates/platform.yaml

@@ -0,0 +1,49 @@
+# Platform Service Template for Solace Agent Mesh
+# Provides agent management, deployments, connectors, and toolsets
+
+log:
+  stdout_log_level: INFO
+  log_file_level: DEBUG
+  log_file: platform_service.log
+
+# Shared SAM config (broker, models, etc.)
+!include ../shared_config.yaml
+
+apps:
+  - name: platform_service_app
+    app_base_path: .
+    app_module: solace_agent_mesh.services.platform.app
+
+    broker:
+      <<: *broker_connection
+
+    app_config:
+      # --- Required ---
+      namespace: ${NAMESPACE}
+      database_url: "${PLATFORM_DATABASE_URL, sqlite:///platform.db}"
+
+      # --- FastAPI Server Configuration ---
+      fastapi_host: ${PLATFORM_API_HOST, localhost}
+      fastapi_port: ${PLATFORM_API_PORT, 8001}
+      cors_allowed_origins:
+        - "http://localhost:3000"
+        - "http://127.0.0.1:3000"
+        - "http://localhost:8000"
+
+      # --- Message Size Configuration ---
+      max_message_size_bytes: ${MAX_MESSAGE_SIZE_BYTES, 10000000}
+
+      # --- OAuth2 Authentication ---
+      # Community mode: frontend_use_authorization=false (dev user)
+      # Enterprise mode: frontend_use_authorization=true (OAuth validation)
+      external_auth_service_url: ${EXTERNAL_AUTH_SERVICE_URL}
+      external_auth_provider: ${EXTERNAL_AUTH_PROVIDER, generic}
+      frontend_use_authorization: ${FRONTEND_USE_AUTHORIZATION, false}
+
+      # --- Background Task Configuration ---
+      # Deployment monitoring (enterprise feature)
+      deployment_timeout_minutes: ${DEPLOYMENT_TIMEOUT_MINUTES, 5}
+      deployment_check_interval_seconds: ${DEPLOYMENT_CHECK_INTERVAL, 60}
+
+      # Deployer heartbeat monitoring (enterprise feature)
+      heartbeat_timeout_seconds: ${HEARTBEAT_TIMEOUT_SECONDS, 90}

solace_agent_mesh/templates/plugin_readme_template.md

@@ -1,34 +1,12 @@
-# __PLUGIN_KEBAB_CASE_NAME__ SAM Plugin
+# __PLUGIN_PASCAL_CASE_NAME__ SAM Plugin
 
 __PLUGIN_DESCRIPTION__
 
 This is a plugin for Solace Agent Mesh (SAM).
 
-## Configuration (`config.yaml`)
-
-The `config.yaml` in this plugin serves as a template. When you use `sam plugin add <component_name> --plugin __PLUGIN_KEBAB_CASE_NAME__`, the following placeholders in the YAML structure will be replaced with variations of `<component_name>`:
-- `__COMPONENT_UPPER_SNAKE_CASE_NAME__`
-- `__COMPONENT_KEBAB_CASE_NAME__`
-- `__COMPONENT_PASCAL_CASE_NAME__`
-
-Customize the `config.yaml` in this plugin directory to define the base configuration for components created from it.
-
-## Source Code (`src/`)
-The `src/` directory contains the Python source code for your plugin.
-
-## Installation (as a developer of this plugin)
-
-To build and install this plugin locally for testing:
-```bash
-sam plugin build
-pip install dist/*.whl 
-```
-(Or `pip install .` if preferred, `sam plugin build` is for creating the distributable wheel)
-
-## Usage (as a user of this plugin)
+## Installation
 
 Once the plugin is installed (e.g., from PyPI or a local wheel file):
 ```bash
 sam plugin add <your-new-component-name> --plugin __PLUGIN_KEBAB_CASE_NAME__
-```
-This will create a new component configuration at `configs/plugins/<your-new-component-name-kebab-case>.yaml`.
+```

solace_agent_mesh/templates/plugin_tool_config_template.yaml

@@ -0,0 +1,109 @@
+# Plugin Metadata:
+# Name: __PLUGIN_KEBAB_CASE_NAME__
+# Version: __PLUGIN_VERSION__
+# Description: __PLUGIN_DESCRIPTION__
+# Author: __PLUGIN_AUTHOR_NAME__ <__PLUGIN_AUTHOR_EMAIL__>
+# 
+# --- Start of Agent Configuration Template ---
+# Solace Agent Mesh: Plugin Configuration Template
+#
+# This file serves as a template for creating new agent configurations from this plugin.
+# Use placeholders like __COMPONENT_KEBAB_CASE_NAME__, __COMPONENT_PASCAL_CASE_NAME__,
+# and __COMPONENT_UPPER_SNAKE_CASE_NAME__ where the specific component name should be inserted.
+
+log:
+  stdout_log_level: INFO
+  log_file_level: DEBUG
+  log_file: __COMPONENT_KEBAB_CASE_NAME__.log
+
+# To use the `shared_config.yaml` file, uncomment the following line and remove the `shared_config` section below.
+# !include ../shared_config.yaml
+shared_config:
+  - broker_connection: &broker_connection
+      dev_mode: ${SOLACE_DEV_MODE, false}
+      broker_url: ${SOLACE_BROKER_URL, ws://localhost:8008}
+      broker_username: ${SOLACE_BROKER_USERNAME, default}
+      broker_password: ${SOLACE_BROKER_PASSWORD, default}
+      broker_vpn: ${SOLACE_BROKER_VPN, default}
+      temporary_queue: ${USE_TEMPORARY_QUEUES, true}
+
+  - models:
+    general: &general_model
+      # This dictionary structure tells ADK to use the LiteLlm wrapper.
+      # 'model' uses the specific model identifier your endpoint expects.
+      model: ${LLM_SERVICE_GENERAL_MODEL_NAME} # Use env var for model name
+      # 'api_base' tells LiteLLM where to send the request.
+      api_base: ${LLM_SERVICE_ENDPOINT} # Use env var for endpoint URL
+      # 'api_key' provides authentication.
+      api_key: ${LLM_SERVICE_API_KEY} # Use env var for API key
+
+  - services:
+    # Default session service configuration
+    session_service: &default_session_service
+      type: "memory"
+      default_behavior: "PERSISTENT"
+    
+    # Default artifact service configuration
+    artifact_service: &default_artifact_service
+      type: "filesystem"
+      base_path: "/tmp/samv2"
+      artifact_scope: namespace # Or "namespace", "app", "custom"
+
+apps:
+  - name: __COMPONENT_KEBAB_CASE_NAME__-app
+    app_base_path: . 
+    app_module: solace_agent_mesh.agent.sac.app 
+    broker:
+      <<: *broker_connection
+
+    # App Level Config
+    app_config:
+      namespace: ${NAMESPACE} 
+      supports_streaming: true 
+      agent_name: "__COMPONENT_PASCAL_CASE_NAME__" 
+      display_name: "__COMPONENT_SPACED_CAPITALIZED_NAME__ Agent"
+      model: *general_model 
+
+      instruction: |
+        You're __COMPONENT_SPACED_CAPITALIZED_NAME__ agent.
+        Configure its specific instructions here.
+
+      tools:
+        - group_name: artifact_management
+          tool_type: builtin-group
+
+        # --- Example Python Tools (defined in tools.py) ---
+        # - tool_type: python
+        #   component_module: __PLUGIN_SNAKE_CASE_NAME__.tools
+        #   component_base_path: . # Relative to where the agent runs
+        #   function_name: example_text_processor_tool
+        #   tool_config:
+        #     prefix: "PluginProcessed: "
+        
+        # - tool_type: python
+        #   component_module: __PLUGIN_SNAKE_CASE_NAME__.tools
+        #   component_base_path: .
+        #   function_name: example_file_creator_tool
+        #   tool_config: {} # Add specific config if needed by the tool
+
+      session_service: *default_session_service
+      artifact_service: *default_artifact_service
+
+      artifact_handling_mode: "reference"
+      enable_embed_resolution: true
+      enable_artifact_content_instruction: true
+
+      agent_card:
+        description: "__PLUGIN_DESCRIPTION__"
+        defaultInputModes: ["text"]
+        defaultOutputModes: ["text"]
+        skills: [] # Remove brackets after adding entries
+          # - id: "example_tool"
+          #   name: "Example Tool"
+          #   description: "An example tool provided by the __PLUGIN_PASCAL_CASE_NAME__ plugin."
+
+      agent_card_publishing: { interval_seconds: 10 }
+      agent_discovery: { enabled: false }
+      inter_agent_communication:
+        allow_list: []
+        request_timeout_seconds: 30

solace_agent_mesh/templates/proxy_template.yaml

@@ -0,0 +1,62 @@
+# A2A Proxy Configuration File
+
+log:
+  stdout_log_level: INFO
+  log_file_level: DEBUG
+  log_file: a2a_proxy.log
+
+# Shared SAM config (includes broker connection details)
+!include ../shared_config.yaml
+
+apps:
+  - name: "__PROXY_NAME____app"
+    app_base_path: .
+    app_module: solace_agent_mesh.agent.proxies.a2a.app 
+    broker:
+      <<: *broker_connection
+
+    # --- App Level Config for the Proxy ---
+    app_config:
+      namespace: ${NAMESPACE}
+
+      # Configuration for the artifact service used by the proxy itself.
+      # When the proxy receives an artifact from a downstream agent, it will
+      # store it here before forwarding it on the Solace mesh.
+      artifact_service:
+        type: "filesystem"
+        base_path: "/tmp/samv2"
+        artifact_scope: namespace # Default scope, shares artifacts within the NAMESPACE
+
+      # How the proxy should handle artifacts it sends over Solace.
+      # 'reference': Sends an artifact:// URI.
+      # 'embed': Sends the full content base64 encoded.
+      artifact_handling_mode: "reference"
+
+      # Interval in seconds for the proxy to re-fetch agent cards from
+      # downstream agents. Set to 0 to disable periodic checks.
+      discovery_interval_seconds: 5
+      tools:
+        - group_name: artifact_management
+          tool_type: builtin-group
+
+      # --- List of Downstream Agents to Proxy ---
+      # A single proxy can manage multiple external agents.
+      # Each agent can have its own URL, authentication, and timeout settings.
+      proxied_agents:
+        # Example 1: A simple agent without authentication
+        - name: "HelloWorld" # The name this agent will have on the Solace mesh
+          url: "http://localhost:9999" # The real HTTP endpoint of the agent
+        
+        # Example 2: Another agent without authentication
+        - name: "AnalysisAgent"
+          url: "http://127.0.0.1:10001"
+        
+        # You can add more agents here with different configurations:
+        # - name: "SecureAgent"
+        #   url: "https://api.example.com/agent"
+        #   authentication:
+        #     type: "static_bearer"
+        #     token: "${SECURE_AGENT_TOKEN}"
+        #   request_timeout_seconds: 180
+        #   # use_agent_card_url: false  # If true (default), uses URL from agent card for tasks.
+        #                                # If false, uses configured URL directly for all calls.

solace_agent_mesh/templates/webui.yaml

@@ -20,15 +20,25 @@ apps:
       namespace: ${NAMESPACE}
       session_secret_key: "${SESSION_SECRET_KEY}"
 
+      model: *general_model
       artifact_service: *default_artifact_service
       session_service: __SESSION_SERVICE__
       gateway_id: ${WEBUI_GATEWAY_ID}
       fastapi_host: ${FASTAPI_HOST}
-      fastapi_port: ${FASTAPI_PORT}
-      cors_allowed_origins: 
-        - "http://localhost:3000" 
+      fastapi_port: ${FASTAPI_PORT, 8000}
+      cors_allowed_origins:
+        - "http://localhost:3000"
         - "http://127.0.0.1:3000"
 
+      # Platform Service Configuration (runs as second app in this template)
+      platform_service:
+        url: "${PLATFORM_SERVICE_URL, http://localhost:8001}"
+
+      # OAuth2 Authentication (Community: false, Enterprise: true)
+      external_auth_service_url: ${EXTERNAL_AUTH_SERVICE_URL}
+      external_auth_provider: ${EXTERNAL_AUTH_PROVIDER, generic}
+      frontend_use_authorization: ${FRONTEND_USE_AUTHORIZATION, false}
+
       enable_embed_resolution: ${ENABLE_EMBED_RESOLUTION} # Enable late-stage resolution
       gateway_artifact_content_limit_bytes: ${GATEWAY_ARTIFACT_LIMIT_BYTES, 10000000} # Max size for late-stage embeds
       sse_max_queue_size: ${SSE_MAX_QUEUE_SIZE, 200} # Max size of SSE connection queues
@@ -46,6 +56,138 @@ apps:
             Format responses to the user in Markdown using appropriate formatting.
 
       # --- Frontend Config Passthrough ---
-      frontend_welcome_message: ${FRONTEND_WELCOME_MESSAGE}
-      frontend_bot_name: ${FRONTEND_BOT_NAME}
-      frontend_collect_feedback: ${FRONTEND_COLLECT_FEEDBACK}
+      frontend_welcome_message: __FRONTEND_WELCOME_MESSAGE__
+      frontend_bot_name: __FRONTEND_BOT_NAME__
+      frontend_collect_feedback: __FRONTEND_COLLECT_FEEDBACK__
+      frontend_logo_url: __FRONTEND_LOGO_URL__
+
+      task_logging:
+        enabled: true
+        log_status_updates: true
+        log_artifact_events: true
+        log_file_parts: true
+        max_file_part_size_bytes: 10240
+      
+      # --- Frontend Feature Flags ---
+      # Uncomment to control speech features in the UI
+      frontend_feature_enablement:
+      #   speechToText: true   # Set to false to hide Speech-to-Text settings & microphone
+      #   textToSpeech: true   # Set to false to hide Text-to-Speech settings & speaker button
+      #   projects: true
+      #   promptLibrary: true
+        background_tasks: true  # NOTE: task_logging must also be enabled for background tasks to work
+
+      # --- Background Tasks Configuration ---
+      background_tasks:
+        default_timeout_ms: 3600000  # Default: 1 hour (3600000ms)
+
+      # --- Speech Configuration (STT/TTS) ---
+      speech:
+        # stt:
+        #   provider: openai
+        #   url: "https://api.openai.com/v1/audio/transcriptions"
+        #   api_key: "${OPENAI_API_KEY}"
+        #   model: "whisper-1"
+        stt:
+          provider: azure
+          azure:
+            api_key: "${AZURE_SPEECH_KEY}"
+            region: "${AZURE_SPEECH_REGION}"
+            language: en-US
+        
+        # Text-to-Speech Configuration
+        tts:
+          provider: ${TTS_PROVIDER, gemini}  # "gemini", "azure", or "polly" (can be overridden by UI)
+          
+          # Azure Neural Voices Configuration
+          azure:
+            api_key: "${AZURE_SPEECH_KEY}"
+            region: "${AZURE_SPEECH_REGION}"
+            default_voice: "en-US-Andrew:DragonHDLatestNeural"
+            voices:
+              # DragonHD Latest Neural Voices (Highest Quality)
+              - "en-US-Ava:DragonHDLatestNeural"
+              - "en-US-Ava3:DragonHDLatestNeural"
+              - "en-US-Adam:DragonHDLatestNeural"
+              - "en-US-Alloy:DragonHDLatestNeural"
+              - "en-US-Andrew:DragonHDLatestNeural"
+              - "en-US-Andrew2:DragonHDLatestNeural"
+              - "en-US-Andrew3:DragonHDLatestNeural"
+              - "en-US-Aria:DragonHDLatestNeural"
+              - "en-US-Brian:DragonHDLatestNeural"
+              - "en-US-Davis:DragonHDLatestNeural"
+              - "en-US-Emma:DragonHDLatestNeural"
+              - "en-US-Emma2:DragonHDLatestNeural"
+              - "en-US-Jenny:DragonHDLatestNeural"
+              - "en-US-MultiTalker-Ava-Andrew:DragonHDLatestNeural"
+              - "en-US-Nova:DragonHDLatestNeural"
+              - "en-US-Phoebe:DragonHDLatestNeural"
+              - "en-US-Serena:DragonHDLatestNeural"
+              - "en-US-Steffan:DragonHDLatestNeural"
+              # Standard Neural Voices
+              - "en-US-JennyNeural"
+              - "en-US-GuyNeural"
+              - "en-US-AriaNeural"
+              - "en-US-DavisNeural"
+              - "en-US-JaneNeural"
+              - "en-US-JasonNeural"
+              - "en-US-NancyNeural"
+              - "en-US-TonyNeural"
+              - "en-GB-LibbyNeural"
+              - "en-GB-RyanNeural"
+              - "en-GB-SoniaNeural"
+              - "en-AU-NatashaNeural"
+              - "en-AU-WilliamNeural"
+          
+          # Google Gemini Configuration
+          gemini:
+            api_key: "${GEMINI_API_KEY}"
+            model: "gemini-2.5-flash-preview-tts"
+            default_voice: "Kore"
+            language: "en-US"
+            voices:
+            - "Kore"
+            - "Puck"
+            - "Zephyr"
+            - "Charon"
+            - "Fenrir"
+            - "Leda"
+            - "Aoede"
+            - "Callirhoe"
+            - "Umbriel"
+            - "Enceladus"
+            - "Iapetus"
+            - "Erinome"
+            - "Algieba"
+            - "Despina"
+            - "Algenib"
+            - "Achernar"
+            - "Schedar"
+            - "Gacrux"
+            - "Pulcherrima"
+            - "Achird"
+            - "Zubenelgenubi"
+            - "Vindemiatrix"
+            - "Sadachbia"
+            - "Sadaltager"
+            - "Sulafat"
+            - "Autonoe"
+            - "Laomedeia"
+            - "Orus"
+            - "Rasalgethi"
+            - "Alnilam"
+        
+        # Frontend Speech Tab Default Settings (optional)
+        speechTab:
+          advancedMode: false
+          speechToText:
+            speechToText: true
+            engineSTT: "external"  # Use external for better quality
+            languageSTT: "en-US"
+          textToSpeech:
+            textToSpeech: true
+            engineTTS: "external"  # Use external for better quality
+            voice: "Kore"
+            playbackRate: 1.0
+            cacheTTS: true
+

solace_agent_mesh/tools/web_search/__init__.py

@@ -0,0 +1,18 @@
+"""Web search tools for Solace Agent Mesh.
+
+This module provides Google Search integration. For other search providers
+(Exa, Brave, Tavily), please use the corresponding plugins from
+solace-agent-mesh-plugins repository.
+"""
+
+from .models import SearchSource, SearchResult, ImageResult
+from .base import WebSearchTool
+from .google_search import GoogleSearchTool
+
+__all__ = [
+    "SearchSource",
+    "SearchResult",
+    "ImageResult",
+    "WebSearchTool",
+    "GoogleSearchTool",
+]

solace_agent_mesh/tools/web_search/base.py

@@ -0,0 +1,84 @@
+"""Base web search tool interface."""
+
+from abc import ABC, abstractmethod
+from typing import Literal, Optional
+from .models import SearchResult
+
+
+class WebSearchTool(ABC):
+    """Base class for web search tools."""
+    
+    def __init__(self, api_key: Optional[str] = None, **kwargs):
+        """Initialize the search tool.
+        
+        Args:
+            api_key: API key for the search provider (if required)
+            **kwargs: Additional provider-specific configuration
+        """
+        self.api_key = api_key
+        self.config = kwargs
+    
+    @abstractmethod
+    async def search(
+        self,
+        query: str,
+        max_results: int = 5,
+        search_depth: Literal["basic", "advanced"] = "basic",
+        **kwargs
+    ) -> SearchResult:
+        """Execute a search query.
+        
+        Args:
+            query: The search query string
+            max_results: Maximum number of results to return (1-10)
+            search_depth: Search depth - 'basic' for quick results, 'advanced' for comprehensive
+            **kwargs: Additional provider-specific parameters
+            
+        Returns:
+            SearchResult object containing the search results
+            
+        Raises:
+            Exception: If the search fails
+        """
+        raise NotImplementedError("Subclasses must implement search()")
+    
+    def get_tool_definition(self) -> dict:
+        """Get the tool definition for LLM function calling.
+        
+        Returns:
+            Dictionary containing the tool definition
+        """
+        return {
+            "type": "function",
+            "function": {
+                "name": "web_search",
+                "description": (
+                    "Search the web for current information. Use this when you need "
+                    "up-to-date information, facts, news, or data that may not be in "
+                    "your training data. Always cite sources using the citation format."
+                ),
+                "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_depth": {
+                            "type": "string",
+                            "enum": ["basic", "advanced"],
+                            "description": "Search depth: 'basic' for quick results, 'advanced' for comprehensive",
+                            "default": "basic"
+                        }
+                    },
+                    "required": ["query"]
+                }
+            }
+        }