solace-agent-mesh 1.0.8__py3-none-any.whl → 1.1.0__py3-none-any.whl

solace_agent_mesh/common/a2a/a2a_llm.txt

@@ -0,0 +1,182 @@
+# DEVELOPER GUIDE: a2a
+
+## Quick Summary
+The `a2a` directory provides a comprehensive abstraction layer for the A2A (Agent-to-Agent) protocol, offering helper functions for creating, consuming, and translating A2A protocol objects. It acts as a facade that insulates applications from the specifics of the underlying a2a-sdk, providing simplified interfaces for messages, artifacts, tasks, events, and protocol-level operations.
+
+## Files Overview
+- `__init__.py` - Main entry point exposing all commonly used A2A helpers
+- `artifact.py` - Helpers for creating and consuming A2A Artifact objects
+- `events.py` - Helpers for creating and consuming A2A asynchronous event objects
+- `message.py` - Helpers for creating and consuming A2A Message and Part objects
+- `protocol.py` - Helpers for A2A protocol-level concerns like topic construction and JSON-RPC
+- `task.py` - Helpers for creating and consuming A2A Task objects
+- `translation.py` - Helpers for translating between A2A protocol objects and other domains
+- `types.py` - Custom type aliases and models for the A2A helper layer
+
+## Developer API Reference
+
+### __init__.py
+**Purpose:** Main entry point that exposes all commonly used A2A helpers for easy access
+**Import:** `from solace_agent_mesh.common.a2a import *`
+
+This file re-exports all public functions from the other modules, allowing developers to import everything from the main package.
+
+### artifact.py
+**Purpose:** Provides helpers for creating and consuming A2A Artifact objects
+**Import:** `from solace_agent_mesh.common.a2a.artifact import create_text_artifact, create_data_artifact, get_artifact_id`
+
+**Functions:**
+- `create_text_artifact(name: str, text: str, description: str = "", artifact_id: Optional[str] = None) -> Artifact` - Creates a new Artifact containing a single TextPart
+- `create_data_artifact(name: str, data: dict[str, Any], description: str = "", artifact_id: Optional[str] = None) -> Artifact` - Creates a new Artifact containing a single DataPart
+- `update_artifact_parts(artifact: Artifact, new_parts: List[ContentPart]) -> Artifact` - Returns a new Artifact with replaced parts
+- `prepare_file_part_for_publishing(part: FilePart, mode: str, artifact_service: "BaseArtifactService", user_id: str, session_id: str, target_agent_name: str, log_identifier: str) -> Optional[FilePart]` - Prepares a FilePart for publishing based on the artifact handling mode
+- `resolve_file_part_uri(part: FilePart, artifact_service: "BaseArtifactService", log_identifier: str) -> FilePart` - Resolves an artifact URI within a FilePart into embedded bytes
+- `get_artifact_id(artifact: Artifact) -> str` - Safely retrieves the ID from an Artifact
+- `get_artifact_name(artifact: Artifact) -> Optional[str]` - Safely retrieves the name from an Artifact
+- `get_parts_from_artifact(artifact: Artifact) -> List[ContentPart]` - Extracts unwrapped content parts from an Artifact
+
+**Usage Examples:**
+```python
+from solace_agent_mesh.common.a2a.artifact import create_text_artifact, get_artifact_id
+
+# Create a text artifact
+artifact = create_text_artifact(
+    name="My Document",
+    text="This is the content of my document",
+    description="A sample text document"
+)
+
+# Get artifact ID
+artifact_id = get_artifact_id(artifact)
+```
+
+### events.py
+**Purpose:** Provides helpers for creating and consuming A2A asynchronous event objects
+**Import:** `from solace_agent_mesh.common.a2a.events import create_status_update, create_artifact_update`
+
+**Functions:**
+- `create_data_signal_event(task_id: str, context_id: str, signal_data: SignalData, agent_name: str, part_metadata: Optional[Dict[str, Any]] = None) -> TaskStatusUpdateEvent` - Creates a TaskStatusUpdateEvent from signal data
+- `create_status_update(task_id: str, context_id: str, message: Message, is_final: bool = False, metadata: Optional[Dict[str, Any]] = None) -> TaskStatusUpdateEvent` - Creates a new TaskStatusUpdateEvent
+- `create_artifact_update(task_id: str, context_id: str, artifact: Artifact, append: bool = False, last_chunk: bool = False, metadata: Optional[Dict[str, Any]] = None) -> TaskArtifactUpdateEvent` - Creates a new TaskArtifactUpdateEvent
+- `get_message_from_status_update(event: TaskStatusUpdateEvent) -> Optional[Message]` - Extracts Message from TaskStatusUpdateEvent
+- `get_data_parts_from_status_update(event: TaskStatusUpdateEvent) -> List[DataPart]` - Extracts DataPart objects from status update
+- `get_artifact_from_artifact_update(event: TaskArtifactUpdateEvent) -> Optional[Artifact]` - Extracts Artifact from TaskArtifactUpdateEvent
+
+**Usage Examples:**
+```python
+from solace_agent_mesh.common.a2a.events import create_status_update
+from solace_agent_mesh.common.a2a.message import create_agent_text_message
+
+# Create a status update event
+message = create_agent_text_message("Processing your request...")
+status_event = create_status_update(
+    task_id="task-123",
+    context_id="context-456",
+    message=message,
+    is_final=False
+)
+```
+
+### message.py
+**Purpose:** Provides helpers for creating and consuming A2A Message and Part objects
+**Import:** `from solace_agent_mesh.common.a2a.message import create_agent_text_message, create_text_part, get_text_from_message`
+
+**Functions:**
+- `create_agent_text_message(text: str, task_id: Optional[str] = None, context_id: Optional[str] = None, message_id: Optional[str] = None) -> Message` - Creates agent message with TextPart
+- `create_agent_data_message(data: dict[str, Any], task_id: Optional[str] = None, context_id: Optional[str] = None, message_id: Optional[str] = None, part_metadata: Optional[Dict[str, Any]] = None) -> Message` - Creates agent message with DataPart
+- `create_agent_parts_message(parts: List[ContentPart], task_id: Optional[str] = None, context_id: Optional[str] = None, message_id: Optional[str] = None, metadata: Optional[Dict[str, Any]] = None) -> Message` - Creates agent message with multiple parts
+- `create_user_message(parts: List[ContentPart], task_id: Optional[str] = None, context_id: Optional[str] = None, message_id: Optional[str] = None, metadata: Optional[Dict[str, Any]] = None) -> Message` - Creates user message with multiple parts
+- `create_text_part(text: str, metadata: Optional[Dict[str, Any]] = None) -> TextPart` - Creates a TextPart object
+- `create_file_part_from_uri(uri: str, name: Optional[str] = None, mime_type: Optional[str] = None, metadata: Optional[Dict[str, Any]] = None) -> FilePart` - Creates FilePart from URI
+- `create_file_part_from_bytes(content_bytes: bytes, name: Optional[str] = None, mime_type: Optional[str] = None, metadata: Optional[Dict[str, Any]] = None) -> FilePart` - Creates FilePart from bytes
+- `create_data_part(data: Dict[str, Any], metadata: Optional[Dict[str, Any]] = None) -> DataPart` - Creates a DataPart object
+- `update_message_parts(message: Message, new_parts: List[ContentPart]) -> Message` - Returns a new Message with replaced parts
+- `get_text_from_message(message: Message, delimiter: str = "\n") -> str` - Extracts and joins all text content from Message
+- `get_data_parts_from_message(message: Message) -> List[DataPart]` - Extracts DataPart objects from Message
+- `get_file_parts_from_message(message: Message) -> List[FilePart]` - Extracts FilePart objects from Message
+- `get_message_id(message: Message) -> str` - Gets message ID
+- `get_context_id(message: Message) -> Optional[str]` - Gets context ID
+- `get_task_id(message: Message) -> Optional[str]` - Gets task ID
+- `get_parts_from_message(message: Message) -> List[ContentPart]` - Extracts unwrapped content parts from Message
+- `get_text_from_text_part(part: TextPart) -> str` - Gets text from TextPart
+- `get_data_from_data_part(part: DataPart) -> Dict[str, Any]` - Gets data from DataPart
+- `get_metadata_from_part(part: ContentPart) -> Optional[Dict[str, Any]]` - Gets metadata from any Part
+- `get_file_from_file_part(part: FilePart) -> Optional[Union[FileWithUri, FileWithBytes]]` - Gets File object from FilePart
+- `get_uri_from_file_part(part: FilePart) -> Optional[str]` - Gets URI from FilePart
+- `get_bytes_from_file_part(part: FilePart) -> Optional[bytes]` - Gets decoded bytes from FilePart
+- `get_filename_from_file_part(part: FilePart) -> Optional[str]` - Gets filename from FilePart
+- `get_mimetype_from_file_part(part: FilePart) -> Optional[str]` - Gets MIME type from FilePart
+
+**Usage Examples:**
+```python
+from solace_agent_mesh.common.a2a.message import create_agent_text_message, create_text_part, create_user_message
+
+# Create a simple text message
+message = create_agent_text_message(
+    text="Hello, how can I help you?",
+    task_id="task-123",
+    context_id="context-456"
+)
+
+# Create a user message with multiple parts
+text_part = create_text_part("Please analyze this data:")
+data_part = create_data_part({"values": [1, 2, 3, 4, 5]})
+user_message = create_user_message(
+    parts=[text_part, data_part],
+    task_id="task-123"
+)
+```
+
+### protocol.py
+**Purpose:** Provides helpers for A2A protocol-level concerns like topic construction and JSON-RPC
+**Import:** `from solace_agent_mesh.common.a2a.protocol import get_agent_request_topic, create_send_message_request`
+
+**Constants/Variables:**
+- `A2A_VERSION: str` - Current A2A protocol version ("v1")
+- `A2A_BASE_PATH: str` - Base path for A2A topics ("a2a/v1")
+
+**Functions:**
+- `get_a2a_base_topic(namespace: str) -> str` - Returns base topic prefix for A2A communication
+- `get_discovery_topic(namespace: str) -> str` - Returns topic for agent card discovery
+- `get_agent_request_topic(namespace: str, agent_name: str) -> str` - Returns topic for sending requests to specific agent
+- `get_gateway_status_topic(namespace: str, gateway_id: str, task_id: str) -> str` - Returns topic for publishing status updates to gateway
+- `get_gateway_response_topic(namespace: str, gateway_id: str, task_id: str) -> str` - Returns topic for publishing final response to gateway
+- `get_gateway_status_subscription_topic(namespace: str, self_gateway_id: str) -> str` - Returns wildcard topic for gateway to receive status updates
+- `get_gateway_response_subscription_topic(namespace: str, self_gateway_id: str) -> str` - Returns wildcard topic for gateway to receive responses
+- `get_peer_agent_status_topic(namespace: str, delegating_agent_name: str, sub_task_id: str) -> str` - Returns topic for publishing status to delegating agent
+- `get_agent_response_topic(namespace: str, delegating_agent_name: str, sub_task_id: str) -> str` - Returns topic for publishing response to delegating agent
+- `get_agent_response_subscription_topic(namespace: str, self_agent_name: str) -> str` - Returns wildcard topic for agent to receive responses
+- `get_agent_status_subscription_topic(namespace: str, self_agent_name: str) -> str` - Returns wildcard topic for agent to receive status updates
+- `get_client_response_topic(namespace: str, client_id: str) -> str` - Returns topic for publishing response to client
+- `get_client_status_topic(namespace: str, client_id: str, task_id: str) -> str` - Returns topic for publishing status to client
+- `get_client_status_subscription_topic(namespace: str, client_id: str) -> str` - Returns wildcard topic for client to receive status
+- `create_send_message_request(message: Message, task_id: str, metadata: Optional[Dict[str, Any]] = None) -> SendMessageRequest` - Creates SendMessageRequest object
+- `create_send_streaming_message_request(message: Message, task_id: str, metadata: Optional[Dict[str, Any]] = None) -> SendStreamingMessageRequest` - Creates SendStreamingMessageRequest object
+- `create_success_response(result: Any, request_id: Optional[Union[str, int]]) -> JSONRPCResponse` - Creates successful JSON-RPC response
+- `create_internal_error_response(message: str, request_id: Optional[Union[str, int]], data: Optional[Dict[str, Any]] = None) -> JSONRPCResponse` - Creates internal error response
+- `create_invalid_request_error_response(message: str, request_id: Optional[Union[str, int]], data: Optional[Any] = None) -> JSONRPCResponse` - Creates invalid request error response
+- `create_cancel_task_request(task_id: str) -> CancelTaskRequest` - Creates CancelTaskRequest object
+- `get_request_id(request: A2ARequest) -> str | int` - Gets JSON-RPC request ID
+- `get_request_method(request: A2ARequest) -> str` - Gets JSON-RPC method name
+- `get_message_from_send_request(request: A2ARequest) -> Optional[Message]` - Gets Message from send request
+- `get_task_id_from_cancel_request(request: A2ARequest) -> Optional[str]` - Gets task ID from cancel request
+- `get_response_id(response: JSONRPCResponse) -> Optional[Union[str, int]]` - Gets response ID
+- `get_response_result(response: JSONRPCResponse) -> Optional[Any]` - Gets response result
+- `get_response_error(response: JSONRPCResponse) -> Optional[JSONRPCError]` - Gets response error
+- `topic_matches_subscription(topic: str, subscription: str) -> bool` - Checks if topic matches Solace subscription pattern
+- `subscription_to_regex(subscription: str) -> str` - Converts Solace subscription to regex
+- `extract_task_id_from_topic(topic: str, subscription_pattern: str, log_identifier: str) -> Optional[str]` - Extracts task ID from topic
+
+**Usage Examples:**
+```python
+from solace_agent_mesh.common.a2a.protocol import get_agent_request_topic, create_send_message_request
+from solace_agent_mesh.common.a2a.message import create_agent_text_message
+
+# Get topic for sending request to an agent
+topic = get_agent_request_topic("my-namespace", "my-agent")
+
+# Create a send message request
+message = create_agent_text_message("Hello agent!")
+request = create_sen
+
+# content_hash: b894ad5028b63e8ee25dcae4edbefa55a29be08dbece2fd4666ab2f0f0b7d740

solace_agent_mesh/common/a2a/artifact.py

@@ -0,0 +1,328 @@
+"""
+Helpers for creating and consuming A2A Artifact objects.
+"""
+
+import uuid
+import base64
+from datetime import datetime, timezone
+from typing import Any, List, Optional, TYPE_CHECKING
+from urllib.parse import urlparse, parse_qs
+
+from .types import ContentPart
+from a2a.types import (
+    Artifact,
+    DataPart,
+    FilePart,
+    FileWithBytes,
+    FileWithUri,
+    Part,
+    TextPart,
+)
+from solace_ai_connector.common.log import log
+from .. import a2a
+
+if TYPE_CHECKING:
+    from google.adk.artifacts import BaseArtifactService
+
+
+# --- Creation Helpers ---
+
+
+def create_text_artifact(
+    name: str,
+    text: str,
+    description: str = "",
+    artifact_id: Optional[str] = None,
+) -> Artifact:
+    """
+    Creates a new Artifact object containing only a single TextPart.
+
+    Args:
+        name: The human-readable name of the artifact.
+        text: The text content of the artifact.
+        description: An optional description of the artifact.
+        artifact_id: The artifact ID. If None, a new UUID is generated.
+
+    Returns:
+        A new `Artifact` object.
+    """
+    text_part = TextPart(text=text)
+    return Artifact(
+        artifact_id=artifact_id or str(uuid.uuid4().hex),
+        parts=[Part(root=text_part)],
+        name=name,
+        description=description,
+    )
+
+
+def create_data_artifact(
+    name: str,
+    data: dict[str, Any],
+    description: str = "",
+    artifact_id: Optional[str] = None,
+) -> Artifact:
+    """
+    Creates a new Artifact object containing only a single DataPart.
+
+    Args:
+        name: The human-readable name of the artifact.
+        data: The structured data content of the artifact.
+        description: An optional description of the artifact.
+        artifact_id: The artifact ID. If None, a new UUID is generated.
+
+    Returns:
+        A new `Artifact` object.
+    """
+    data_part = DataPart(data=data)
+    return Artifact(
+        artifact_id=artifact_id or str(uuid.uuid4().hex),
+        parts=[Part(root=data_part)],
+        name=name,
+        description=description,
+    )
+
+
+def update_artifact_parts(artifact: Artifact, new_parts: List[ContentPart]) -> Artifact:
+    """Returns a new Artifact with its parts replaced."""
+    wrapped_parts = [Part(root=p) for p in new_parts]
+    return artifact.model_copy(update={"parts": wrapped_parts})
+
+
+async def prepare_file_part_for_publishing(
+    part: FilePart,
+    mode: str,
+    artifact_service: "BaseArtifactService",
+    user_id: str,
+    session_id: str,
+    target_agent_name: str,
+    log_identifier: str,
+) -> Optional[FilePart]:
+    """
+    Prepares a FilePart for publishing based on the artifact handling mode.
+
+    - 'ignore': Returns None.
+    - 'embed': Ensures the part contains bytes, resolving a URI if necessary.
+    - 'reference': Ensures the part contains a URI, saving bytes if necessary.
+    - 'passthrough': Returns the part as-is.
+
+    Args:
+        part: The input FilePart, which may contain raw bytes or a URI.
+        mode: The artifact handling mode ('ignore', 'embed', 'reference', 'passthrough').
+        artifact_service: The ADK artifact service instance.
+        user_id: The user ID for the artifact context.
+        session_id: The session ID for the artifact context.
+        target_agent_name: The name of the agent the artifact will be associated with.
+        log_identifier: The logging identifier for log messages.
+
+    Returns:
+        The processed FilePart, or None if ignored.
+    """
+    log_id = f"{log_identifier}[PrepareFilePart]"
+
+    if mode == "ignore":
+        log.debug("%s Mode is 'ignore', filtering out FilePart.", log_id)
+        return None
+
+    if mode == "passthrough":
+        log.debug("%s Mode is 'passthrough', returning original FilePart.", log_id)
+        return part
+
+    if mode == "embed":
+        if isinstance(part.file, FileWithUri):
+            log.debug("%s Mode is 'embed', resolving URI for FilePart.", log_id)
+            return await resolve_file_part_uri(part, artifact_service, log_identifier)
+        return part  # It's already bytes, so it's embedded.
+
+    if mode == "reference":
+        if isinstance(part.file, FileWithBytes):
+            if not artifact_service:
+                log.warning(
+                    "%s Mode is 'reference' but no artifact_service is configured. Ignoring FilePart '%s'.",
+                    log_id,
+                    part.file.name,
+                )
+                return None
+
+            try:
+                filename = part.file.name or f"upload-{uuid.uuid4().hex}"
+                content_bytes = base64.b64decode(part.file.bytes)
+                mime_type = part.file.mime_type or "application/octet-stream"
+
+                # Create a concise and accurate metadata dictionary.
+                metadata_to_save = {
+                    "source": log_identifier,
+                    "description": "This artifact was uploaded via the gateway",
+                }
+
+                # Call the helper with the new, simpler metadata.
+                from ...agent.utils.artifact_helpers import save_artifact_with_metadata
+
+                save_result = await save_artifact_with_metadata(
+                    artifact_service=artifact_service,
+                    app_name=target_agent_name,
+                    user_id=user_id,
+                    session_id=session_id,
+                    filename=filename,
+                    content_bytes=content_bytes,
+                    mime_type=mime_type,
+                    metadata_dict=metadata_to_save,
+                    timestamp=datetime.now(timezone.utc),
+                )
+
+                if save_result["status"] == "success":
+                    saved_version = save_result.get("data_version")
+                    from ...agent.utils.artifact_helpers import format_artifact_uri
+
+                    artifact_uri = format_artifact_uri(
+                        app_name=target_agent_name,
+                        user_id=user_id,
+                        session_id=session_id,
+                        filename=filename,
+                        version=saved_version,
+                    )
+                    ref_part = a2a.create_file_part_from_uri(
+                        uri=artifact_uri,
+                        name=filename,
+                        mime_type=mime_type,
+                        metadata=part.metadata,
+                    )
+                    log.info(
+                        "%s Converted embedded file '%s' to reference: %s",
+                        log_id,
+                        filename,
+                        artifact_uri,
+                    )
+                    return ref_part
+                else:
+                    log.error(
+                        "%s Failed to save artifact via helper: %s. Skipping FilePart.",
+                        log_id,
+                        save_result.get("message"),
+                    )
+                    return None
+
+            except Exception as e:
+                log.exception(
+                    "%s Failed to save artifact for reference mode: %s. Skipping FilePart.",
+                    log_id,
+                    e,
+                )
+                return None
+        return part  # It's already a reference (URI)
+
+    # Default case if mode is unrecognized
+    log.warning(
+        "%s Unrecognized artifact_handling_mode '%s'. Ignoring FilePart.", log_id, mode
+    )
+    return None
+
+
+async def resolve_file_part_uri(
+    part: FilePart, artifact_service: "BaseArtifactService", log_identifier: str
+) -> FilePart:
+    """
+    Resolves an artifact URI within a FilePart into embedded bytes.
+
+    If the FilePart does not contain a resolvable `artifact://` URI, it is
+    returned unchanged.
+
+    Args:
+        part: The FilePart to resolve.
+        artifact_service: The ADK artifact service instance.
+        log_identifier: The logging identifier for log messages.
+
+    Returns:
+        A FilePart, either with embedded bytes if resolved, or the original part.
+    """
+    if not (
+        isinstance(part.file, FileWithUri)
+        and part.file.uri
+        and part.file.uri.startswith("artifact://")
+    ):
+        return part
+
+    if not artifact_service:
+        log.warning(
+            "%s Cannot resolve artifact URI, artifact_service is not configured.",
+            log_identifier,
+        )
+        return part
+
+    uri = part.file.uri
+    log_id_prefix = f"{log_identifier}[ResolveURI]"
+    try:
+        log.info("%s Found artifact URI to resolve: %s", log_id_prefix, uri)
+        parsed_uri = urlparse(uri)
+        app_name = parsed_uri.netloc
+        path_parts = parsed_uri.path.strip("/").split("/")
+
+        if not app_name or len(path_parts) != 3:
+            raise ValueError(
+                "Invalid URI structure. Expected artifact://app_name/user_id/session_id/filename"
+            )
+
+        user_id, session_id, filename = path_parts
+        version_str = parse_qs(parsed_uri.query).get("version", [None])[0]
+        version = int(version_str) if version_str else None
+
+        from ...agent.utils.artifact_helpers import load_artifact_content_or_metadata
+
+        loaded_artifact = await load_artifact_content_or_metadata(
+            artifact_service=artifact_service,
+            app_name=app_name,
+            user_id=user_id,
+            session_id=session_id,
+            filename=filename,
+            version=version,
+            return_raw_bytes=True,
+        )
+
+        if loaded_artifact.get("status") == "success":
+            content_bytes = loaded_artifact.get("raw_bytes")
+            new_file_content = FileWithBytes(
+                bytes=base64.b64encode(content_bytes).decode("utf-8"),
+                mime_type=part.file.mime_type,
+                name=part.file.name,
+            )
+            part.file = new_file_content
+            log.info(
+                "%s Successfully resolved and embedded artifact: %s",
+                log_id_prefix,
+                uri,
+            )
+        else:
+            log.error(
+                "%s Failed to resolve artifact URI '%s': %s",
+                log_id_prefix,
+                uri,
+                loaded_artifact.get("message"),
+            )
+    except Exception as e:
+        log.exception("%s Error resolving artifact URI '%s': %s", log_id_prefix, uri, e)
+    return part
+
+
+# --- Consumption Helpers ---
+
+
+def get_artifact_id(artifact: Artifact) -> str:
+    """Safely retrieves the ID from an Artifact object."""
+    return artifact.artifact_id
+
+
+def get_artifact_name(artifact: Artifact) -> Optional[str]:
+    """Safely retrieves the name from an Artifact object."""
+    return artifact.name
+
+
+def get_parts_from_artifact(artifact: Artifact) -> List[ContentPart]:
+    """
+    Extracts the raw, unwrapped Part objects (TextPart, DataPart, etc.) from an Artifact.
+
+    Args:
+        artifact: The `Artifact` object.
+
+    Returns:
+        A list of the unwrapped content parts.
+    """
+    return [part.root for part in artifact.parts]

solace_agent_mesh/common/a2a/events.py

@@ -0,0 +1,183 @@
+"""
+Helpers for creating and consuming A2A asynchronous event objects, such as
+TaskStatusUpdateEvent and TaskArtifactUpdateEvent.
+"""
+
+from typing import Any, Dict, List, Optional
+
+from a2a.types import (
+    Artifact,
+    DataPart,
+    Message,
+    TaskArtifactUpdateEvent,
+    TaskState,
+    TaskStatusUpdateEvent,
+)
+
+from . import message as message_helpers
+from . import task as task_helpers
+from ...common.data_parts import SignalData
+
+
+# --- Creation Helpers ---
+
+
+def create_data_signal_event(
+    task_id: str,
+    context_id: str,
+    signal_data: SignalData,
+    agent_name: str,
+    part_metadata: Optional[Dict[str, Any]] = None,
+) -> TaskStatusUpdateEvent:
+    """
+    Creates a TaskStatusUpdateEvent from a specific signal data model.
+
+    This is a generalized helper that takes any of the defined SignalData
+    types and wraps it in the full A2A event structure.
+
+    Args:
+        task_id: The ID of the task being updated.
+        context_id: The context ID for the task.
+        signal_data: The Pydantic model for the signal (e.g., ToolInvocationStartData).
+        agent_name: The name of the agent sending the signal.
+        part_metadata: Optional metadata for the DataPart.
+
+    Returns:
+        A new `TaskStatusUpdateEvent` object containing the signal.
+    """
+    a2a_message = message_helpers.create_agent_data_message(
+        data=signal_data.model_dump(),
+        task_id=task_id,
+        context_id=context_id,
+        part_metadata=part_metadata,
+    )
+    return create_status_update(
+        task_id=task_id,
+        context_id=context_id,
+        message=a2a_message,
+        is_final=False,
+        metadata={"agent_name": agent_name},
+    )
+
+
+def create_status_update(
+    task_id: str,
+    context_id: str,
+    message: Message,
+    is_final: bool = False,
+    metadata: Optional[Dict[str, Any]] = None,
+) -> TaskStatusUpdateEvent:
+    """
+    Creates a new TaskStatusUpdateEvent.
+
+    Args:
+        task_id: The ID of the task being updated.
+        context_id: The context ID for the task.
+        message: The A2AMessage object containing the status details.
+        is_final: Whether this is the final update for the task.
+        metadata: Optional metadata for the event.
+
+    Returns:
+        A new `TaskStatusUpdateEvent` object.
+    """
+    task_status = task_helpers.create_task_status(
+        state=TaskState.working,
+        message=message,
+    )
+    return TaskStatusUpdateEvent(
+        task_id=task_id,
+        context_id=context_id,
+        status=task_status,
+        final=is_final,
+        metadata=metadata,
+        kind="status-update",
+    )
+
+
+def create_artifact_update(
+    task_id: str,
+    context_id: str,
+    artifact: Artifact,
+    append: bool = False,
+    last_chunk: bool = False,
+    metadata: Optional[Dict[str, Any]] = None,
+) -> TaskArtifactUpdateEvent:
+    """
+    Creates a new TaskArtifactUpdateEvent.
+
+    Args:
+        task_id: The ID of the task this artifact belongs to.
+        context_id: The context ID for the task.
+        artifact: The Artifact object being sent.
+        append: If true, the content should be appended to a previous artifact.
+        last_chunk: If true, this is the final chunk of the artifact.
+        metadata: Optional metadata for the event.
+
+    Returns:
+        A new `TaskArtifactUpdateEvent` object.
+    """
+    return TaskArtifactUpdateEvent(
+        task_id=task_id,
+        context_id=context_id,
+        artifact=artifact,
+        append=append,
+        last_chunk=last_chunk,
+        metadata=metadata,
+        kind="artifact-update",
+    )
+
+
+# --- Consumption Helpers ---
+
+
+def get_message_from_status_update(
+    event: TaskStatusUpdateEvent,
+) -> Optional[Message]:
+    """
+    Safely extracts the Message object from a TaskStatusUpdateEvent.
+
+    Args:
+        event: The TaskStatusUpdateEvent object.
+
+    Returns:
+        The `Message` object if present, otherwise None.
+    """
+    if event and event.status:
+        return event.status.message
+    return None
+
+
+def get_data_parts_from_status_update(
+    event: TaskStatusUpdateEvent,
+) -> List[DataPart]:
+    """
+    Safely extracts all DataPart objects from a TaskStatusUpdateEvent's message.
+
+    Args:
+        event: The TaskStatusUpdateEvent object.
+
+    Returns:
+        A list of `DataPart` objects found, or an empty list.
+    """
+    message = get_message_from_status_update(event)
+    if not message:
+        return []
+
+    return message_helpers.get_data_parts_from_message(message)
+
+
+def get_artifact_from_artifact_update(
+    event: TaskArtifactUpdateEvent,
+) -> Optional[Artifact]:
+    """
+    Safely extracts the Artifact object from a TaskArtifactUpdateEvent.
+
+    Args:
+        event: The TaskArtifactUpdateEvent object.
+
+    Returns:
+        The `Artifact` object if present, otherwise None.
+    """
+    if event:
+        return event.artifact
+    return None