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

solace_agent_mesh/common/a2a_spec/schemas/agent_progress_update.json

@@ -0,0 +1,18 @@
+{
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "title": "AgentProgressUpdateData",
+    "description": "Schema for the data part of an agent progress update signal.",
+    "type": "object",
+    "properties": {
+        "type": {
+            "type": "string",
+            "const": "agent_progress_update",
+            "description": "The constant type for this data part."
+        },
+        "status_text": {
+            "type": "string",
+            "description": "A human-readable progress message (e.g., 'Analyzing the report...')."
+        }
+    },
+    "required": ["type", "status_text"]
+}

solace_agent_mesh/common/a2a_spec/schemas/artifact_creation_progress.json

@@ -0,0 +1,48 @@
+{
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "title": "ArtifactCreationProgressData",
+    "description": "Schema for the data part of an artifact creation progress signal.",
+    "type": "object",
+    "properties": {
+        "type": {
+            "type": "string",
+            "const": "artifact_creation_progress",
+            "description": "The constant type for this data part."
+        },
+        "filename": {
+            "type": "string",
+            "description": "The name of the artifact being created."
+        },
+        "description": {
+            "type": "string",
+            "description": "An optional description of the artifact being created."
+        },
+        "status": {
+            "type": "string",
+            "enum": ["in-progress", "completed", "failed"],
+            "description": "The status of the artifact creation."
+        },
+        "bytes_transferred": {
+            "type": "integer",
+            "description": "The number of bytes transferred so far."
+        },
+        "artifact_chunk": {
+            "type": "string",
+            "description": "The chunk of artifact data that was transferred in this progress update. Only present for 'in-progress' status."
+        },
+        "mime_type": {
+            "type": "string",
+            "description": "The MIME type of the artifact. Only present for 'completed' status."
+        },
+        "version": {
+            "type": "integer",
+            "description": "The version number of the artifact being created or updated."
+        }
+    },
+    "required": [
+        "type",
+        "filename",
+        "status",
+        "bytes_transferred"
+    ]
+}

solace_agent_mesh/common/a2a_spec/schemas/feedback_event.json

@@ -0,0 +1,51 @@
+{
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "title": "FeedbackEvent",
+    "description": "Schema for a user feedback event published by a gateway.",
+    "type": "object",
+    "properties": {
+        "id": {
+            "type": "string",
+            "description": "A unique identifier for this feedback submission."
+        },
+        "session_id": {
+            "type": "string",
+            "description": "The A2A session ID associated with the task."
+        },
+        "task_id": {
+            "type": "string",
+            "description": "The ID of the task this feedback is for."
+        },
+        "user_id": {
+            "type": "string",
+            "description": "The identifier of the user who provided the feedback."
+        },
+        "rating": {
+            "type": "string",
+            "enum": ["up", "down"],
+            "description": "The rating provided by the user."
+        },
+        "comment": {
+            "type": ["string", "null"],
+            "description": "Optional text comment provided by the user."
+        },
+        "created_time": {
+            "type": "string",
+            "format": "date-time",
+            "description": "The ISO 8601 timestamp (UTC) when the feedback was submitted."
+        },
+        "gateway_id": {
+            "type": "string",
+            "description": "The ID of the gateway that collected the feedback."
+        }
+    },
+    "required": [
+        "id",
+        "session_id",
+        "task_id",
+        "user_id",
+        "rating",
+        "created_time",
+        "gateway_id"
+    ]
+}

solace_agent_mesh/common/a2a_spec/schemas/llm_invocation.json

@@ -0,0 +1,41 @@
+{
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "title": "LlmInvocationData",
+    "description": "Schema for the data part of an LLM invocation signal.",
+    "type": "object",
+    "properties": {
+        "type": {
+            "type": "string",
+            "const": "llm_invocation",
+            "description": "The constant type for this data part."
+        },
+        "request": {
+            "type": "object",
+            "description": "A sanitized representation of the LlmRequest object sent to the model."
+        },
+        "usage": {
+            "type": "object",
+            "description": "Token usage information for this LLM call.",
+            "properties": {
+                "input_tokens": {
+                    "type": "integer",
+                    "description": "Number of input/prompt tokens."
+                },
+                "output_tokens": {
+                    "type": "integer",
+                    "description": "Number of output/completion tokens."
+                },
+                "cached_input_tokens": {
+                    "type": "integer",
+                    "description": "Number of cached input tokens (optional)."
+                },
+                "model": {
+                    "type": "string",
+                    "description": "Model identifier used for this call."
+                }
+            },
+            "required": ["input_tokens", "output_tokens", "model"]
+        }
+    },
+    "required": ["type", "request"]
+}

solace_agent_mesh/common/a2a_spec/schemas/schemas_llm.txt

@@ -0,0 +1,330 @@
+# DEVELOPER GUIDE: schemas
+
+## Quick Summary
+This directory contains JSON Schema definitions for various agent-to-agent (A2A) communication signals in the Solace Agent Mesh. These schemas define the structure and validation rules for different types of progress updates, tool invocations, and LLM interactions that agents can send to each other.
+
+## Files Overview
+- `agent_progress_update.json` - Schema for general agent progress status messages
+- `artifact_creation_progress.json` - Schema for tracking file/artifact creation progress with chunked data
+- `llm_invocation.json` - Schema for LLM model invocation signals with usage tracking
+- `tool_invocation_start.json` - Schema for tool execution start notifications
+- `tool_result.json` - Schema for tool execution completion results with optional LLM usage
+
+## Developer API Reference
+
+### agent_progress_update.json
+**Purpose:** Defines the schema for agent progress update signals that communicate human-readable status messages between agents.
+
+**Import:** Load as JSON schema for validation
+```python
+import json
+from jsonschema import validate
+```
+
+**Schema Structure:**
+```json
+{
+  "type": "agent_progress_update",
+  "status_text": "string"
+}
+```
+
+**Properties:**
+- `type: "agent_progress_update"` - Constant identifier for this signal type (required)
+- `status_text: string` - Human-readable progress message (required)
+
+**Usage Examples:**
+```python
+import json
+from jsonschema import validate
+
+# Load and use schema
+with open('solace_agent_mesh/common/a2a_spec/schemas/agent_progress_update.json') as f:
+    schema = json.load(f)
+
+# Valid data example
+data = {
+    "type": "agent_progress_update",
+    "status_text": "Analyzing the report..."
+}
+validate(instance=data, schema=schema)
+```
+
+### artifact_creation_progress.json
+**Purpose:** Defines the schema for tracking progress during file or artifact creation operations with status tracking and chunked data transfer.
+
+**Import:** Load as JSON schema for validation
+```python
+import json
+from jsonschema import validate
+```
+
+**Schema Structure:**
+```json
+{
+  "type": "artifact_creation_progress",
+  "filename": "string",
+  "description": "string",
+  "status": "in-progress|completed|failed",
+  "bytes_transferred": "integer",
+  "artifact_chunk": "string",
+  "mime_type": "string"
+}
+```
+
+**Properties:**
+- `type: "artifact_creation_progress"` - Constant identifier for this signal type (required)
+- `filename: string` - Name of the artifact being created (required)
+- `description: string` - Optional description of the artifact being created (optional)
+- `status: string` - Status of artifact creation: "in-progress", "completed", or "failed" (required)
+- `bytes_transferred: integer` - Number of bytes transferred so far (required)
+- `artifact_chunk: string` - Chunk of artifact data transferred in this update (optional, only for 'in-progress')
+- `mime_type: string` - MIME type of the artifact (optional, only for 'completed')
+
+**Usage Examples:**
+```python
+import json
+from jsonschema import validate
+
+# Load and use schema
+with open('solace_agent_mesh/common/a2a_spec/schemas/artifact_creation_progress.json') as f:
+    schema = json.load(f)
+
+# In-progress example
+data = {
+    "type": "artifact_creation_progress",
+    "filename": "report.pdf",
+    "description": "Monthly sales report",
+    "status": "in-progress",
+    "bytes_transferred": 1024,
+    "artifact_chunk": "JVBERi0xLjQKJcOkw7zDtsO..."
+}
+validate(instance=data, schema=schema)
+
+# Completed example
+completed_data = {
+    "type": "artifact_creation_progress",
+    "filename": "report.pdf",
+    "status": "completed",
+    "bytes_transferred": 5120,
+    "mime_type": "application/pdf"
+}
+validate(instance=completed_data, schema=schema)
+```
+
+### llm_invocation.json
+**Purpose:** Defines the schema for LLM invocation signals that communicate when an agent is calling a language model, including token usage tracking.
+
+**Import:** Load as JSON schema for validation
+```python
+import json
+from jsonschema import validate
+```
+
+**Schema Structure:**
+```json
+{
+  "type": "llm_invocation",
+  "request": "object",
+  "usage": {
+    "input_tokens": "integer",
+    "output_tokens": "integer",
+    "cached_input_tokens": "integer",
+    "model": "string"
+  }
+}
+```
+
+**Properties:**
+- `type: "llm_invocation"` - Constant identifier for this signal type (required)
+- `request: object` - Sanitized representation of the LlmRequest object sent to the model (required)
+- `usage: object` - Token usage information for this LLM call (optional)
+  - `input_tokens: integer` - Number of input/prompt tokens (required in usage)
+  - `output_tokens: integer` - Number of output/completion tokens (required in usage)
+  - `cached_input_tokens: integer` - Number of cached input tokens (optional)
+  - `model: string` - Model identifier used for this call (required in usage)
+
+**Usage Examples:**
+```python
+import json
+from jsonschema import validate
+
+# Load and use schema
+with open('solace_agent_mesh/common/a2a_spec/schemas/llm_invocation.json') as f:
+    schema = json.load(f)
+
+# Valid data example with usage tracking
+data = {
+    "type": "llm_invocation",
+    "request": {
+        "model": "gpt-4",
+        "messages": [{"role": "user", "content": "Analyze this data"}],
+        "temperature": 0.7
+    },
+    "usage": {
+        "input_tokens": 150,
+        "output_tokens": 75,
+        "cached_input_tokens": 50,
+        "model": "gpt-4"
+    }
+}
+validate(instance=data, schema=schema)
+```
+
+### tool_invocation_start.json
+**Purpose:** Defines the schema for tool invocation start signals that notify when an agent begins executing a tool.
+
+**Import:** Load as JSON schema for validation
+```python
+import json
+from jsonschema import validate
+```
+
+**Schema Structure:**
+```json
+{
+  "type": "tool_invocation_start",
+  "tool_name": "string",
+  "tool_args": "object",
+  "function_call_id": "string"
+}
+```
+
+**Properties:**
+- `type: "tool_invocation_start"` - Constant identifier for this signal type (required)
+- `tool_name: string` - Name of the tool being called (required)
+- `tool_args: object` - Arguments passed to the tool (required)
+- `function_call_id: string` - ID from the LLM's function call (required)
+
+**Usage Examples:**
+```python
+import json
+from jsonschema import validate
+
+# Load and use schema
+with open('solace_agent_mesh/common/a2a_spec/schemas/tool_invocation_start.json') as f:
+    schema = json.load(f)
+
+# Valid data example
+data = {
+    "type": "tool_invocation_start",
+    "tool_name": "file_reader",
+    "tool_args": {
+        "filepath": "/path/to/file.txt",
+        "encoding": "utf-8"
+    },
+    "function_call_id": "call_abc123"
+}
+validate(instance=data, schema=schema)
+```
+
+### tool_result.json
+**Purpose:** Defines the schema for tool execution result signals that communicate the completion and results of tool invocations, with optional LLM usage tracking.
+
+**Import:** Load as JSON schema for validation
+```python
+import json
+from jsonschema import validate
+```
+
+**Schema Structure:**
+```json
+{
+  "type": "tool_result",
+  "tool_name": "string",
+  "result_data": "any",
+  "function_call_id": "string",
+  "llm_usage": {
+    "input_tokens": "integer",
+    "output_tokens": "integer",
+    "cached_input_tokens": "integer",
+    "model": "string"
+  }
+}
+```
+
+**Properties:**
+- `type: "tool_result"` - Constant identifier for this signal type (required)
+- `tool_name: string` - Name of the tool that was called (required)
+- `result_data: any` - The data returned by the tool (required, can be any type)
+- `function_call_id: string` - ID from the LLM's function call that this result corresponds to (required)
+- `llm_usage: object` - Token usage if this tool made LLM calls (optional)
+  - `input_tokens: integer` - Total input tokens used by tool's LLM calls (required in llm_usage)
+  - `output_tokens: integer` - Total output tokens used by tool's LLM calls (required in llm_usage)
+  - `cached_input_tokens: integer` - Number of cached input tokens (optional)
+  - `model: string` - Model identifier(s) used by the tool (required in llm_usage)
+
+**Usage Examples:**
+```python
+import json
+from jsonschema import validate
+
+# Load and use schema
+with open('solace_agent_mesh/common/a2a_spec/schemas/tool_result.json') as f:
+    schema = json.load(f)
+
+# Valid data example with LLM usage
+data = {
+    "type": "tool_result",
+    "tool_name": "web_search",
+    "result_data": {
+        "results": ["Result 1", "Result 2"],
+        "count": 2
+    },
+    "function_call_id": "call_abc123",
+    "llm_usage": {
+        "input_tokens": 200,
+        "output_tokens": 100,
+        "model": "gpt-4"
+    }
+}
+validate(instance=data, schema=schema)
+```
+
+**Common Usage Pattern:**
+```python
+import json
+from jsonschema import validate
+from pathlib import Path
+from typing import Dict, Any
+
+def validate_a2a_signal(signal_data: Dict[str, Any], schema_name: str) -> bool:
+    """Validate A2A signal data against its schema."""
+    schema_path = Path(f"solace_agent_mesh/common/a2a_spec/schemas/{schema_name}.json")
+    
+    with open(schema_path) as f:
+        schema = json.load(f)
+    
+    try:
+        validate(instance=signal_data, schema=schema)
+        return True
+    except Exception as e:
+        print(f"Validation failed: {e}")
+        return False
+
+def load_schema(schema_name: str) -> Dict[str, Any]:
+    """Load a specific A2A signal schema."""
+    schema_path = Path(f"solace_agent_mesh/common/a2a_spec/schemas/{schema_name}.json")
+    with open(schema_path) as f:
+        return json.load(f)
+
+# Example usage
+progress_data = {
+    "type": "agent_progress_update",
+    "status_text": "Processing request..."
+}
+
+if validate_a2a_signal(progress_data, "agent_progress_update"):
+    print("Signal is valid!")
+
+# Load all schemas for batch validation
+schemas = {
+    "agent_progress": load_schema("agent_progress_update"),
+    "artifact_progress": load_schema("artifact_creation_progress"),
+    "llm_invocation": load_schema("llm_invocation"),
+    "tool_start": load_schema("tool_invocation_start"),
+    "tool_result": load_schema("tool_result")
+}
+```
+
+# content_hash: 9b18c2ba0e0aa3d52a27ecd90f45376713fe2738cee386219f988fd84da93a51

solace_agent_mesh/common/a2a_spec/schemas/tool_invocation_start.json

@@ -0,0 +1,26 @@
+{
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "title": "ToolInvocationStartData",
+    "description": "Schema for the data part of a tool invocation start signal.",
+    "type": "object",
+    "properties": {
+        "type": {
+            "type": "string",
+            "const": "tool_invocation_start",
+            "description": "The constant type for this data part."
+        },
+        "tool_name": {
+            "type": "string",
+            "description": "The name of the tool being called."
+        },
+        "tool_args": {
+            "type": "object",
+            "description": "The arguments passed to the tool."
+        },
+        "function_call_id": {
+            "type": "string",
+            "description": "The ID from the LLM's function call."
+        }
+    },
+    "required": ["type", "tool_name", "tool_args", "function_call_id"]
+}

solace_agent_mesh/common/a2a_spec/schemas/tool_result.json

@@ -0,0 +1,48 @@
+{
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "title": "ToolResultData",
+    "description": "Schema for the data part of a tool execution result signal.",
+    "type": "object",
+    "properties": {
+        "type": {
+            "type": "string",
+            "const": "tool_result",
+            "description": "The constant type for this data part."
+        },
+        "tool_name": {
+            "type": "string",
+            "description": "The name of the tool that was called."
+        },
+        "result_data": {
+            "description": "The data returned by the tool."
+        },
+        "function_call_id": {
+            "type": "string",
+            "description": "The ID from the LLM's function call that this result corresponds to."
+        },
+        "llm_usage": {
+            "type": "object",
+            "description": "Token usage if this tool made LLM calls.",
+            "properties": {
+                "input_tokens": {
+                    "type": "integer",
+                    "description": "Total input tokens used by tool's LLM calls."
+                },
+                "output_tokens": {
+                    "type": "integer",
+                    "description": "Total output tokens used by tool's LLM calls."
+                },
+                "cached_input_tokens": {
+                    "type": "integer",
+                    "description": "Number of cached input tokens (optional)."
+                },
+                "model": {
+                    "type": "string",
+                    "description": "Model identifier(s) used by the tool."
+                }
+            },
+            "required": ["input_tokens", "output_tokens", "model"]
+        }
+    },
+    "required": ["type", "tool_name", "result_data", "function_call_id"]
+}

solace_agent_mesh/common/agent_registry.py

@@ -0,0 +1,122 @@
+"""
+Manages discovered A2A agents.
+Consolidated from src/tools/common/agent_registry.py and src/tools/a2a_cli_client/agent_registry.py.
+"""
+
+import threading
+import time
+from typing import Dict, List, Optional, Tuple
+import logging
+
+from a2a.types import AgentCard
+
+log = logging.getLogger(__name__)
+
+class AgentRegistry:
+    """Stores and manages discovered AgentCards with health tracking."""
+
+    def __init__(self):
+        self._agents: Dict[str, AgentCard] = {}
+        self._last_seen: Dict[str, float] = {}  # Timestamp of last agent card received
+        self._lock = threading.Lock()
+
+    def add_or_update_agent(self, agent_card: AgentCard):
+        """Adds a new agent or updates an existing one."""
+        
+        if not agent_card or not agent_card.name:
+            log.warning("Attempted to register agent with invalid agent card or missing name")
+            return False
+
+        with self._lock:
+            is_new = agent_card.name not in self._agents
+            current_time = time.time()
+            
+            # Store the agent information
+            self._agents[agent_card.name] = agent_card
+            self._last_seen[agent_card.name] = current_time
+                    
+            return is_new
+
+    def get_agent(self, agent_name: str) -> Optional[AgentCard]:
+        """Retrieves an agent card by name."""
+        with self._lock:
+            return self._agents.get(agent_name)
+
+    def get_agent_names(self) -> List[str]:
+        """Returns a sorted list of discovered agent names."""
+        with self._lock:
+            return sorted(list(self._agents.keys()))
+            
+    def get_last_seen(self, agent_name: str) -> Optional[float]:
+        """Returns the timestamp when the agent was last seen."""
+        with self._lock:
+            return self._last_seen.get(agent_name)
+            
+    def check_ttl_expired(self, agent_name: str, ttl_seconds: int) -> Tuple[bool, int]:
+        """
+        Checks if an agent's TTL has expired.
+        
+        Args:
+            agent_name: The name of the agent to check
+            ttl_seconds: The TTL in seconds
+            
+        Returns:
+            A tuple of (is_expired, seconds_since_last_seen)
+        """
+        
+        with self._lock:
+            if agent_name not in self._last_seen:
+                log.debug("Attempted to check TTL for non-existent agent '%s'", agent_name)
+                return False, 0
+                
+            last_seen_time = self._last_seen.get(agent_name)
+            current_time = time.time()
+            time_since_last_seen = int(current_time - last_seen_time) if last_seen_time else 0
+            
+            is_expired = time_since_last_seen > ttl_seconds
+            
+            if is_expired:
+                log.warning(
+                    "AGENT HEALTH CRITICAL: Agent '%s' TTL expired. "
+                    "Last seen: %s seconds ago, TTL: %d seconds",
+                    agent_name,
+                    time_since_last_seen,
+                    ttl_seconds
+                )
+            
+            return is_expired, time_since_last_seen
+            
+    def remove_agent(self, agent_name: str) -> bool:
+        """Removes an agent from the registry."""
+        
+        with self._lock:
+            if agent_name in self._agents:
+                # Get agent details before removal for logging
+                last_seen_time = self._last_seen.get(agent_name)
+                current_time = time.time()
+                time_since_last_seen = int(current_time - last_seen_time) if last_seen_time else "unknown"
+                
+                # Log detailed information about the agent being removed
+                log.warning(
+                    "AGENT DE-REGISTRATION: Removing agent '%s' from registry. "
+                    "Last seen: %s seconds ago",
+                    agent_name,
+                    time_since_last_seen
+                )
+                
+                # Remove the agent from all tracking dictionaries
+                del self._agents[agent_name]
+                if agent_name in self._last_seen:
+                    del self._last_seen[agent_name]
+                
+                log.info("Agent '%s' successfully removed from registry", agent_name)
+                return True
+            else:
+                log.debug("Attempted to remove non-existent agent '%s' from registry", agent_name)
+                return False
+
+    def clear(self):
+        """Clears all registered agents."""
+        with self._lock:
+            self._agents.clear()
+            self._last_seen.clear()