aip-agents-binary 0.5.20__py3-none-manylinux_2_31_x86_64.whl

aip_agents/a2a/server/langgraph_executor.py

@@ -0,0 +1,270 @@
+"""Base executor class for LangChain-based A2A executors.
+
+This module provides a common base class for executors that work with LangChain-based
+agents, such as LangChainAgent and LangGraphAgent. It implements shared functionality
+for handling streaming responses and managing agent execution.
+
+Authors:
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+    Putu Ravindra Wiguna (putu.r.wiguna@gdplabs.id)
+"""
+
+import asyncio
+from abc import ABC
+from typing import Any
+
+from a2a.server.agent_execution import RequestContext
+from a2a.server.events.event_queue import EventQueue
+from a2a.server.tasks import TaskUpdater
+from a2a.types import TaskState
+from a2a.utils import new_agent_text_message
+
+from aip_agents.a2a.server.base_executor import BaseA2AExecutor, StatusUpdateParams
+from aip_agents.agent.interfaces import LangGraphAgentProtocol
+from aip_agents.schema.step_limit import StepLimitConfig
+from aip_agents.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+class LangGraphA2AExecutor(BaseA2AExecutor, ABC):
+    """Base class for LangChain-based A2A executors.
+
+    This class extends BaseA2AExecutor to provide common functionality for executors
+    that work with LangChain-based agents (LangChainAgent and LangGraphAgent).
+    It implements shared methods for handling streaming responses and managing
+    agent execution, while leaving agent-specific initialization to subclasses.
+
+    Attributes:
+        agent (LangGraphAgentProtocol): The LangChain-based agent instance to be executed.
+    """
+
+    agent: LangGraphAgentProtocol
+
+    def __init__(self, langgraph_agent_instance: LangGraphAgentProtocol) -> None:
+        """Initializes the LangGraphA2AExecutor.
+
+        Args:
+            langgraph_agent_instance: Component implementing `LangGraphAgentProtocol`.
+
+        Raises:
+            TypeError: If the provided agent does not satisfy `LangGraphAgentProtocol`.
+        """
+        super().__init__()
+
+        if not isinstance(langgraph_agent_instance, LangGraphAgentProtocol):
+            _type_name = type(langgraph_agent_instance).__name__
+            raise TypeError(
+                f"LangGraphA2AExecutor expected an agent implementing LangGraphAgentProtocol, got {_type_name}"
+            )
+        self.agent = langgraph_agent_instance
+
+    async def execute(
+        self,
+        context: RequestContext,
+        event_queue: EventQueue,
+    ) -> None:
+        """Processes an incoming agent request using a LangChain-based agent.
+
+        This method first performs initial checks using _handle_initial_execute_checks.
+        If successful, it prepares the _process_stream coroutine and passes it to
+        _execute_agent_processing from the base class to manage its lifecycle.
+        The _process_stream method is responsible for calling the agent's
+        arun_a2a_stream and handling its output.
+
+        Args:
+            context (RequestContext): The A2A request context containing message details,
+                task ID, and context ID.
+            event_queue (EventQueue): The queue for sending A2A events (task status,
+                artifacts) back to the server.
+        """
+        updater, query, metadata = await self._handle_initial_execute_checks(context, event_queue)
+        if not updater or query is None:  # Checks failed, status already sent
+            return
+
+        agent_processing_coro = self._process_stream(
+            query=query,
+            updater=updater,
+            task_id=context.task_id,
+            context_id=context.context_id,
+            event_queue=event_queue,
+            metadata=metadata,
+        )
+
+        await self._execute_agent_processing(
+            agent_processing_coro=agent_processing_coro,
+            updater=updater,
+            task_id=context.task_id,
+            context_id=context.context_id,
+        )
+
+    def _get_configurable_kwargs(self, task_id: str) -> dict[str, Any]:
+        """Get configurable kwargs for agent delegation.
+
+        Args:
+            task_id: The A2A task ID.
+
+        Returns:
+            dict[str, Any]: A dictionary with 'configurable' key if the agent
+                            has 'thread_id_key', otherwise an empty dictionary.
+        """
+        if hasattr(self.agent, "thread_id_key"):
+            return {"configurable": {self.agent.thread_id_key: task_id}}
+        return {}
+
+    def _build_agent_kwargs(
+        self,
+        task_id: str,
+        metadata: dict[str, Any] | None,
+    ) -> dict[str, Any]:
+        """Build kwargs for agent stream execution from task and metadata.
+
+        Args:
+            task_id: The A2A task ID for configurable threading settings.
+            metadata: Optional request metadata, including files and overrides.
+
+        Returns:
+            dict[str, Any]: Keyword arguments to pass to the agent's stream method.
+        """
+        kwargs = self._get_configurable_kwargs(task_id)
+
+        files: list[str | dict[str, Any]] = self._extract_files_from_metadata(metadata)
+        if metadata is not None:
+            kwargs["metadata"] = metadata
+            if isinstance(metadata, dict):
+                raw_user_id = metadata.get("memory_user_id") or metadata.get("user_id")
+                if raw_user_id:
+                    kwargs["memory_user_id"] = str(raw_user_id)
+
+                raw_pii_mapping = metadata.get("pii_mapping")
+                if isinstance(raw_pii_mapping, dict) and raw_pii_mapping:
+                    kwargs["pii_mapping"] = dict(raw_pii_mapping)
+
+                # Extract invocation-level step limit overrides (Docs-1)
+                raw_step_limit_config = metadata.get("step_limit_config")
+                if isinstance(raw_step_limit_config, dict | StepLimitConfig):
+                    kwargs["step_limit_config"] = raw_step_limit_config
+        if files:
+            kwargs["files"] = files
+
+        return kwargs
+
+    async def _process_stream(  # noqa: PLR0913
+        self,
+        query: str,
+        updater: TaskUpdater,
+        task_id: str,
+        context_id: str,
+        event_queue: EventQueue,
+        metadata: dict[str, Any] | None = None,
+    ) -> None:
+        """Processes the streaming response from a LangChain-based agent.
+
+        This coroutine invokes the agent.arun_a2a_stream method with the given query and metadata.
+        It then iterates over the asynchronous stream of dictionary chunks yielded by
+        the agent. Each chunk is passed to _handle_stream_event from the base class
+        to interpret common A2A statuses (working, completed, failed, etc.) and update
+        the A2A task accordingly.
+
+        If asyncio.CancelledError is raised (typically from the task managed by
+        _execute_agent_processing), it is re-raised to be handled by the base class.
+        Other exceptions during streaming are caught, logged, an A2A 'failed' status
+        is sent, and the exception is re-raised.
+
+        Args:
+            query (str): The query string to be processed by the agent.
+            updater (TaskUpdater): The TaskUpdater instance for sending status updates.
+            task_id (str): The A2A task ID.
+            context_id (str): The A2A context ID.
+            event_queue (EventQueue): The A2A event queue for sending artifact events.
+            metadata (dict[str, Any] | None): Optional metadata from the A2A request.
+
+        Raises:
+            asyncio.CancelledError: If the task is cancelled externally.
+            Exception: If any other error occurs during the agent's stream processing.
+        """
+        stream = None
+        try:
+            kwargs = self._build_agent_kwargs(task_id=task_id, metadata=metadata)
+
+            stream = self.agent.arun_a2a_stream(query=query, **kwargs)
+
+            current_metadata: dict[str, Any] = metadata.copy() if metadata else {}
+
+            async for chunk in stream:
+                chunk_metadata = chunk.get("metadata")
+                if chunk_metadata is not None:
+                    try:
+                        current_metadata.update(chunk_metadata)
+                    except Exception as e:
+                        logger.warning(f"Invalid metadata payload from chunk: {chunk_metadata}, error: {e}")
+
+                should_terminate = await self._handle_stream_event(
+                    chunk=chunk,
+                    updater=updater,
+                    task_id=task_id,
+                    context_id=context_id,
+                    event_queue=event_queue,
+                    metadata=current_metadata if current_metadata else None,
+                )
+                if should_terminate:
+                    return
+
+        except asyncio.CancelledError:
+            logger.info(f"LangChain stream processing for task {task_id} was cancelled.")
+            raise
+        except Exception as e:
+            logger.error(
+                f"Error during LangChain agent streaming for task {task_id}: {e}",
+                exc_info=True,
+            )
+            await self._update_status(
+                updater,
+                TaskState.failed,
+                message=new_agent_text_message(
+                    f"Error during streaming: {str(e)}",
+                    context_id=context_id,
+                    task_id=task_id,
+                ),
+                params=StatusUpdateParams(final=True, task_id=task_id, context_id=context_id),
+            )
+            raise
+
+    @staticmethod
+    def _extract_files_from_metadata(metadata: dict[str, Any] | None) -> list[str | dict[str, Any]]:
+        """Extract file paths from metadata, removing them since they are passed via kwargs.
+
+        Args:
+            metadata: Metadata dict from the request, potentially containing files.
+
+        Returns:
+            List of non-empty file path strings or file metadata dictionaries.
+        """
+        if not isinstance(metadata, dict):
+            return []
+
+        try:
+            raw_files = metadata.pop("files", None)
+        except AttributeError:
+            return []
+        if raw_files is None:
+            return []
+
+        if not isinstance(raw_files, list):
+            logger.warning("Invalid 'files' metadata received; expected list of strings or dicts.")
+            return []
+
+        normalized_files: list[str | dict[str, Any]] = []
+        invalid_entry_logged = False
+        for entry in raw_files:
+            if isinstance(entry, str) and entry:
+                normalized_files.append(entry)
+                continue
+            if isinstance(entry, dict):
+                normalized_files.append(entry)
+                continue
+            if not invalid_entry_logged:
+                logger.warning("Invalid file metadata entry received; expected string or dict.")
+                invalid_entry_logged = True
+
+        return normalized_files

aip_agents/a2a/server/langgraph_executor.pyi

@@ -0,0 +1,47 @@
+from _typeshed import Incomplete
+from a2a.server.agent_execution import RequestContext
+from a2a.server.events.event_queue import EventQueue
+from abc import ABC
+from aip_agents.a2a.server.base_executor import BaseA2AExecutor as BaseA2AExecutor, StatusUpdateParams as StatusUpdateParams
+from aip_agents.agent.interfaces import LangGraphAgentProtocol as LangGraphAgentProtocol
+from aip_agents.schema.step_limit import StepLimitConfig as StepLimitConfig
+from aip_agents.utils.logger import get_logger as get_logger
+
+logger: Incomplete
+
+class LangGraphA2AExecutor(BaseA2AExecutor, ABC):
+    """Base class for LangChain-based A2A executors.
+
+    This class extends BaseA2AExecutor to provide common functionality for executors
+    that work with LangChain-based agents (LangChainAgent and LangGraphAgent).
+    It implements shared methods for handling streaming responses and managing
+    agent execution, while leaving agent-specific initialization to subclasses.
+
+    Attributes:
+        agent (LangGraphAgentProtocol): The LangChain-based agent instance to be executed.
+    """
+    agent: LangGraphAgentProtocol
+    def __init__(self, langgraph_agent_instance: LangGraphAgentProtocol) -> None:
+        """Initializes the LangGraphA2AExecutor.
+
+        Args:
+            langgraph_agent_instance: Component implementing `LangGraphAgentProtocol`.
+
+        Raises:
+            TypeError: If the provided agent does not satisfy `LangGraphAgentProtocol`.
+        """
+    async def execute(self, context: RequestContext, event_queue: EventQueue) -> None:
+        """Processes an incoming agent request using a LangChain-based agent.
+
+        This method first performs initial checks using _handle_initial_execute_checks.
+        If successful, it prepares the _process_stream coroutine and passes it to
+        _execute_agent_processing from the base class to manage its lifecycle.
+        The _process_stream method is responsible for calling the agent's
+        arun_a2a_stream and handling its output.
+
+        Args:
+            context (RequestContext): The A2A request context containing message details,
+                task ID, and context ID.
+            event_queue (EventQueue): The queue for sending A2A events (task status,
+                artifacts) back to the server.
+        """

aip_agents/a2a/types.py

@@ -0,0 +1,232 @@
+"""Type definitions and constants for A2A artifact generation.
+
+This module provides common MIME types, artifact types, and other constants
+used in A2A artifact generation to ensure consistency across the codebase.
+
+Authors:
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+"""
+
+import base64
+from enum import StrEnum
+from typing import Any
+
+from pydantic import BaseModel, Field, field_validator
+
+
+class MimeType(StrEnum):
+    """Common MIME types for A2A artifacts.
+
+    This class provides constants for commonly used MIME types in artifact generation,
+    ensuring consistency and reducing typos across the codebase.
+    """
+
+    # Text formats
+    TEXT_PLAIN = "text/plain"
+    TEXT_HTML = "text/html"
+    TEXT_CSS = "text/css"
+    TEXT_JAVASCRIPT = "text/javascript"
+    TEXT_CSV = "text/csv"
+    TEXT_XML = "text/xml"
+    TEXT_MARKDOWN = "text/markdown"
+
+    # Application formats
+    APPLICATION_JSON = "application/json"
+    APPLICATION_XML = "application/xml"
+    APPLICATION_PDF = "application/pdf"
+    APPLICATION_ZIP = "application/zip"
+    APPLICATION_GZIP = "application/gzip"
+    APPLICATION_TAR = "application/x-tar"
+    APPLICATION_OCTET_STREAM = "application/octet-stream"
+
+    # Microsoft Office formats
+    APPLICATION_MSWORD = "application/msword"
+    APPLICATION_EXCEL = "application/vnd.ms-excel"
+    APPLICATION_POWERPOINT = "application/vnd.ms-powerpoint"
+    APPLICATION_DOCX = "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
+    APPLICATION_XLSX = "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
+    APPLICATION_PPTX = "application/vnd.openxmlformats-officedocument.presentationml.presentation"
+
+    # Image formats
+    IMAGE_JPEG = "image/jpeg"
+    IMAGE_PNG = "image/png"
+    IMAGE_GIF = "image/gif"
+    IMAGE_WEBP = "image/webp"
+    IMAGE_SVG = "image/svg+xml"
+    IMAGE_BMP = "image/bmp"
+    IMAGE_TIFF = "image/tiff"
+    IMAGE_ICO = "image/x-icon"
+
+    # Audio formats
+    AUDIO_MP3 = "audio/mpeg"
+    AUDIO_WAV = "audio/wav"
+    AUDIO_OGG = "audio/ogg"
+    AUDIO_AAC = "audio/aac"
+    AUDIO_FLAC = "audio/flac"
+
+    # Video formats
+    VIDEO_MP4 = "video/mp4"
+    VIDEO_AVI = "video/x-msvideo"
+    VIDEO_MOV = "video/quicktime"
+    VIDEO_WMV = "video/x-ms-wmv"
+    VIDEO_WEBM = "video/webm"
+    VIDEO_MKV = "video/x-matroska"
+
+    # Font formats
+    FONT_TTF = "font/ttf"
+    FONT_OTF = "font/otf"
+    FONT_WOFF = "font/woff"
+    FONT_WOFF2 = "font/woff2"
+
+
+class ArtifactType(StrEnum):
+    """Common artifact types for A2A artifacts.
+
+    This class provides constants for artifact types used in the A2A protocol.
+    """
+
+    FILE = "file"
+    DATA = "data"
+    TEXT = "text"
+
+
+# Common file extension to MIME type mappings
+EXTENSION_TO_MIME_TYPE = {
+    # Text files
+    ".txt": MimeType.TEXT_PLAIN,
+    ".html": MimeType.TEXT_HTML,
+    ".htm": MimeType.TEXT_HTML,
+    ".css": MimeType.TEXT_CSS,
+    ".js": MimeType.TEXT_JAVASCRIPT,
+    ".csv": MimeType.TEXT_CSV,
+    ".xml": MimeType.TEXT_XML,
+    ".md": MimeType.TEXT_MARKDOWN,
+    ".markdown": MimeType.TEXT_MARKDOWN,
+    # Application files
+    ".json": MimeType.APPLICATION_JSON,
+    ".pdf": MimeType.APPLICATION_PDF,
+    ".zip": MimeType.APPLICATION_ZIP,
+    ".gz": MimeType.APPLICATION_GZIP,
+    ".tar": MimeType.APPLICATION_TAR,
+    # Microsoft Office
+    ".doc": MimeType.APPLICATION_MSWORD,
+    ".xls": MimeType.APPLICATION_EXCEL,
+    ".ppt": MimeType.APPLICATION_POWERPOINT,
+    ".docx": MimeType.APPLICATION_DOCX,
+    ".xlsx": MimeType.APPLICATION_XLSX,
+    ".pptx": MimeType.APPLICATION_PPTX,
+    # Images
+    ".jpg": MimeType.IMAGE_JPEG,
+    ".jpeg": MimeType.IMAGE_JPEG,
+    ".png": MimeType.IMAGE_PNG,
+    ".gif": MimeType.IMAGE_GIF,
+    ".webp": MimeType.IMAGE_WEBP,
+    ".svg": MimeType.IMAGE_SVG,
+    ".bmp": MimeType.IMAGE_BMP,
+    ".tiff": MimeType.IMAGE_TIFF,
+    ".tif": MimeType.IMAGE_TIFF,
+    ".ico": MimeType.IMAGE_ICO,
+    # Audio
+    ".mp3": MimeType.AUDIO_MP3,
+    ".wav": MimeType.AUDIO_WAV,
+    ".ogg": MimeType.AUDIO_OGG,
+    ".aac": MimeType.AUDIO_AAC,
+    ".flac": MimeType.AUDIO_FLAC,
+    # Video
+    ".mp4": MimeType.VIDEO_MP4,
+    ".avi": MimeType.VIDEO_AVI,
+    ".mov": MimeType.VIDEO_MOV,
+    ".wmv": MimeType.VIDEO_WMV,
+    ".webm": MimeType.VIDEO_WEBM,
+    ".mkv": MimeType.VIDEO_MKV,
+    # Fonts
+    ".ttf": MimeType.FONT_TTF,
+    ".otf": MimeType.FONT_OTF,
+    ".woff": MimeType.FONT_WOFF,
+    ".woff2": MimeType.FONT_WOFF2,
+}
+MIME_TYPE_TO_EXTENSION = {v: k for k, v in EXTENSION_TO_MIME_TYPE.items()}
+
+
+def get_mime_type_from_filename(filename: str) -> str:
+    """Get MIME type from filename extension.
+
+    Args:
+        filename: The filename to get the MIME type for.
+
+    Returns:
+        The MIME type string, or application/octet-stream if unknown.
+
+    Example:
+        >>> get_mime_type_from_filename("data.csv")
+        'text/csv'
+        >>> get_mime_type_from_filename("image.png")
+        'image/png'
+        >>> get_mime_type_from_filename("unknown.xyz")
+        'application/octet-stream'
+    """
+    if "." not in filename:
+        return MimeType.APPLICATION_OCTET_STREAM
+
+    extension = "." + filename.split(".")[-1].lower()
+    return EXTENSION_TO_MIME_TYPE.get(extension, MimeType.APPLICATION_OCTET_STREAM)
+
+
+def get_extension_from_mime_type(mime_type: str) -> str | None:
+    """Get file extension from MIME type.
+
+    Args:
+        mime_type: The MIME type to get the extension for.
+
+    Returns:
+        The file extension (with dot) or None if not found.
+
+    Example:
+        >>> get_extension_from_mime_type("text/csv")
+        '.csv'
+        >>> get_extension_from_mime_type("image/png")
+        '.png'
+        >>> get_extension_from_mime_type("unknown/type")
+        None
+    """
+    return MIME_TYPE_TO_EXTENSION.get(mime_type)
+
+
+class Artifact(BaseModel):
+    """Represents an artifact payload used by A2A helpers and executors.
+
+    This model standardizes the structure for artifacts generated by tools and
+    passed through the A2A pipeline.
+
+    Attributes:
+        artifact_type (ArtifactType): The type of artifact. Defaults to FILE.
+        data (str): Base64-encoded content of the artifact.
+        name (str): Display name or filename of the artifact.
+        description (str): Optional description for the artifact. Defaults to empty string.
+        mime_type (str): MIME type of the artifact content.
+        metadata (dict[str, Any] | None): Optional per-artifact metadata to pass through.
+    """
+
+    artifact_type: ArtifactType = Field(default=ArtifactType.FILE)
+    data: str
+    name: str
+    description: str = ""
+    mime_type: str
+    metadata: dict[str, Any] | None = None
+
+    @field_validator("data")
+    @classmethod
+    def validate_base64(cls, v: str) -> str:
+        """Validate that 'data' is a valid base64 string.
+
+        Args:
+            v (str): The base64 string to validate.
+
+        Returns:
+            str: The validated base64 string if valid.
+        """
+        try:
+            base64.b64decode(v, validate=True)
+        except Exception as exc:  # noqa: BLE001
+            raise ValueError("Artifact.data must be a valid base64-encoded string") from exc
+        return v

aip_agents/a2a/types.pyi

@@ -0,0 +1,132 @@
+from _typeshed import Incomplete
+from enum import StrEnum
+from pydantic import BaseModel
+from typing import Any
+
+class MimeType(StrEnum):
+    """Common MIME types for A2A artifacts.
+
+    This class provides constants for commonly used MIME types in artifact generation,
+    ensuring consistency and reducing typos across the codebase.
+    """
+    TEXT_PLAIN: str
+    TEXT_HTML: str
+    TEXT_CSS: str
+    TEXT_JAVASCRIPT: str
+    TEXT_CSV: str
+    TEXT_XML: str
+    TEXT_MARKDOWN: str
+    APPLICATION_JSON: str
+    APPLICATION_XML: str
+    APPLICATION_PDF: str
+    APPLICATION_ZIP: str
+    APPLICATION_GZIP: str
+    APPLICATION_TAR: str
+    APPLICATION_OCTET_STREAM: str
+    APPLICATION_MSWORD: str
+    APPLICATION_EXCEL: str
+    APPLICATION_POWERPOINT: str
+    APPLICATION_DOCX: str
+    APPLICATION_XLSX: str
+    APPLICATION_PPTX: str
+    IMAGE_JPEG: str
+    IMAGE_PNG: str
+    IMAGE_GIF: str
+    IMAGE_WEBP: str
+    IMAGE_SVG: str
+    IMAGE_BMP: str
+    IMAGE_TIFF: str
+    IMAGE_ICO: str
+    AUDIO_MP3: str
+    AUDIO_WAV: str
+    AUDIO_OGG: str
+    AUDIO_AAC: str
+    AUDIO_FLAC: str
+    VIDEO_MP4: str
+    VIDEO_AVI: str
+    VIDEO_MOV: str
+    VIDEO_WMV: str
+    VIDEO_WEBM: str
+    VIDEO_MKV: str
+    FONT_TTF: str
+    FONT_OTF: str
+    FONT_WOFF: str
+    FONT_WOFF2: str
+
+class ArtifactType(StrEnum):
+    """Common artifact types for A2A artifacts.
+
+    This class provides constants for artifact types used in the A2A protocol.
+    """
+    FILE: str
+    DATA: str
+    TEXT: str
+
+EXTENSION_TO_MIME_TYPE: Incomplete
+MIME_TYPE_TO_EXTENSION: Incomplete
+
+def get_mime_type_from_filename(filename: str) -> str:
+    '''Get MIME type from filename extension.
+
+    Args:
+        filename: The filename to get the MIME type for.
+
+    Returns:
+        The MIME type string, or application/octet-stream if unknown.
+
+    Example:
+        >>> get_mime_type_from_filename("data.csv")
+        \'text/csv\'
+        >>> get_mime_type_from_filename("image.png")
+        \'image/png\'
+        >>> get_mime_type_from_filename("unknown.xyz")
+        \'application/octet-stream\'
+    '''
+def get_extension_from_mime_type(mime_type: str) -> str | None:
+    '''Get file extension from MIME type.
+
+    Args:
+        mime_type: The MIME type to get the extension for.
+
+    Returns:
+        The file extension (with dot) or None if not found.
+
+    Example:
+        >>> get_extension_from_mime_type("text/csv")
+        \'.csv\'
+        >>> get_extension_from_mime_type("image/png")
+        \'.png\'
+        >>> get_extension_from_mime_type("unknown/type")
+        None
+    '''
+
+class Artifact(BaseModel):
+    """Represents an artifact payload used by A2A helpers and executors.
+
+    This model standardizes the structure for artifacts generated by tools and
+    passed through the A2A pipeline.
+
+    Attributes:
+        artifact_type (ArtifactType): The type of artifact. Defaults to FILE.
+        data (str): Base64-encoded content of the artifact.
+        name (str): Display name or filename of the artifact.
+        description (str): Optional description for the artifact. Defaults to empty string.
+        mime_type (str): MIME type of the artifact content.
+        metadata (dict[str, Any] | None): Optional per-artifact metadata to pass through.
+    """
+    artifact_type: ArtifactType
+    data: str
+    name: str
+    description: str
+    mime_type: str
+    metadata: dict[str, Any] | None
+    @classmethod
+    def validate_base64(cls, v: str) -> str:
+        """Validate that 'data' is a valid base64 string.
+
+        Args:
+            v (str): The base64 string to validate.
+
+        Returns:
+            str: The validated base64 string if valid.
+        """