solace-agent-mesh 1.0.9__py3-none-any.whl → 1.3.0__py3-none-any.whl

solace_agent_mesh/agent/protocol/protocol_llm.txt

@@ -1,21 +1,68 @@
+# DEVELOPER GUIDE: protocol
+
 ## Quick Summary
 The `protocol` directory implements the core logic for Agent-to-Agent (A2A) communication. It handles receiving and processing requests, responses, and discovery messages (Agent Cards) over the Solace event mesh. It acts as the bridge between the A2A protocol and the underlying Google ADK execution environment.
 
 ## Files Overview
-- `__init__.py` - An empty file that marks the directory as a Python package.
-- `event_handlers.py` - Contains the primary logic for handling all A2A protocol events, including routing incoming messages to the correct processors, managing task execution, and handling agent discovery.
+- `__init__.py` - Empty package initialization file
+- `event_handlers.py` - Contains the primary logic for handling all A2A protocol events, including routing incoming messages, managing task execution, and handling agent discovery
 
 ## Developer API Reference
 
 ### __init__.py
-**Purpose:** Standard Python package initialization file.
-**Import:** `from src.solace_agent_mesh.agent.protocol import *`
+**Purpose:** Standard Python package initialization file
+**Import:** `from solace_agent_mesh.agent.protocol import *`
 
 This is an empty package initialization file and has no public interfaces.
 
 ### event_handlers.py
-**Purpose:** This file is the central hub for processing all events related to the A2A protocol. It receives events from the Solace AI Connector framework, determines their type (e.g., new task request, peer agent response, discovery message, timer), and routes them to the appropriate handler function. It manages the lifecycle of tasks, from initiation and cancellation to handling responses from peer agents.
-**Import:** `from src.solace_agent_mesh.agent.protocol.event_handlers import process_event, handle_a2a_request, handle_agent_card_message, handle_a2a_response, publish_agent_card`
+**Purpose:** Central hub for processing all events related to the A2A protocol. Routes events to appropriate handlers and manages task lifecycle.
+**Import:** `from solace_agent_mesh.agent.protocol.event_handlers import process_event, handle_a2a_request, handle_agent_card_message, handle_a2a_response, publish_agent_card`
 
 **Functions:**
-- `process_event(component: "SamAgentComponent", event: Event
+- `process_event(component, event: Event) -> None` - Main event router that processes incoming events and delegates to specific handlers based on event type and topic
+- `handle_a2a_request(component, message: SolaceMessage) -> None` - Handles incoming A2A request messages, starts ADK runner for SendTask requests, and processes CancelTask requests
+- `handle_agent_card_message(component, message: SolaceMessage) -> None` - Processes incoming Agent Card discovery messages and updates peer agent registry
+- `handle_a2a_response(component, message: SolaceMessage) -> None` - Handles responses and status updates from peer agents, manages parallel task completion
+- `publish_agent_card(component) -> None` - Publishes the agent's capabilities and information to the discovery topic
+
+**Internal Helper Functions:**
+- `_register_peer_artifacts_in_parent_context(parent_task_context: "TaskExecutionContext", peer_task_object: Task, log_identifier: str) -> None` - Registers artifacts produced by peer agents in the parent task context
+- `_publish_peer_tool_result_notification(component: "SamAgentComponent", correlation_data: Dict[str, Any], payload_to_queue: Any, log_identifier: str) -> None` - Publishes a ToolResultData status update for a completed peer tool call
+
+**Usage Examples:**
+```python
+# Main event processing (typically called by the SAC framework)
+from solace_agent_mesh.agent.protocol.event_handlers import process_event
+from solace_ai_connector.common.event import Event, EventType
+
+# Process an incoming event
+await process_event(component, event)
+
+# Publish agent discovery card
+from solace_agent_mesh.agent.protocol.event_handlers import publish_agent_card
+
+publish_agent_card(component)
+
+# Handle specific message types (usually called internally by process_event)
+from solace_agent_mesh.agent.protocol.event_handlers import handle_a2a_request
+
+await handle_a2a_request(component, solace_message)
+```
+
+**Key Event Flow:**
+1. `process_event()` receives all events and routes based on type (MESSAGE, TIMER, CACHE_EXPIRY)
+2. For MESSAGE events, routes to specific handlers based on topic patterns:
+   - Agent request topics → `handle_a2a_request()`
+   - Discovery topics → `handle_agent_card_message()`
+   - Response/status topics → `handle_a2a_response()`
+3. For TIMER events, handles periodic agent card publishing
+4. For CACHE_EXPIRY events, delegates to component's cache handling
+
+**Dependencies:**
+- Requires `SamAgentComponent` instance with proper configuration
+- Uses A2A protocol types from `a2a.types`
+- Integrates with Google ADK for task execution
+- Manages task contexts through `TaskExecutionContext`
+
+# content_hash: 00fc98ca0832801776639518be8b53197c211ac407f79f9a40aa0dc35bf6b447

solace_agent_mesh/agent/sac/app.py

@@ -16,7 +16,7 @@ from typing import Any, Dict
 from solace_ai_connector.flow.app import App
 from solace_ai_connector.common.log import log
 
-from ...common.a2a_protocol import (
+from ...common.a2a import (
     get_agent_request_topic,
     get_discovery_topic,
     get_agent_response_subscription_topic,
@@ -714,4 +714,4 @@ class SamAgentApp(App):
         log.debug("Set broker_config.temporary_queue = True")
 
         super().__init__(app_info, **kwargs)
-        log.debug("A2A_ADK_App initialization complete.")
+        log.debug("A2A_ADK_App initialization complete.")