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

solace_agent_mesh/agent/adk/adk_llm.txt

@@ -1,4 +1,4 @@
-Here is the comprehensive developer guide for the `adk` directory.
+# DEVELOPER GUIDE for adk directory
 
 ## Quick Summary
 The `adk` directory serves as the core integration layer between the Solace AI Connector framework and Google's Agent Development Kit (ADK). It provides the essential components for building, configuring, and running sophisticated AI agents within a Solace messaging environment.
@@ -9,18 +9,22 @@ Once initialized, the `AppLlmAgent` (a custom agent class) is managed by the `ru
 
 ## Files and Subdirectories Overview
 - **Direct files:**
-  - `__init__.py`: Standard Python package initializer.
-  - `app_llm_agent.py`: Defines a custom `LlmAgent` subclass that holds a reference to its host component.
-  - `callbacks.py`: Provides a rich set of ADK callback functions for dynamic instructions, metadata injection, and Solace integration.
-  - `filesystem_artifact_service.py`: A local filesystem-based implementation of ADK's `BaseArtifactService`.
-  - `invocation_monitor.py`: A utility for monitoring and logging agent invocations to YAML files for debugging.
-  - `runner.py`: Manages the asynchronous execution of ADK agent tasks, including cancellation support.
-  - `services.py`: Contains factory functions for initializing ADK services (session, artifact, memory) based on configuration.
-  - `setup.py`: Handles the high-level initialization of the ADK agent, tools, and runner.
-  - `stream_parser.py`: An internal utility for parsing fenced artifact blocks from an LLM's streaming response.
-  - `tool_wrapper.py`: A wrapper for Python functions to make them compatible with ADK, handling embed resolution and config injection.
+  - `__init__.py`: Standard Python package initializer
+  - `app_llm_agent.py`: Defines a custom `LlmAgent` subclass that holds a reference to its host component
+  - `callbacks.py`: Provides a rich set of ADK callback functions for dynamic instructions, metadata injection, and Solace integration
+  - `embed_resolving_mcp_toolset.py`: Custom MCPToolset that resolves embeds in tool parameters before calling MCP tools
+  - `filesystem_artifact_service.py`: A local filesystem-based implementation of ADK's `BaseArtifactService`
+  - `intelligent_mcp_callbacks.py`: Intelligent MCP callback functions for processing and saving MCP tool responses as typed artifacts
+  - `invocation_monitor.py`: A utility for monitoring and logging agent invocations to YAML files for debugging
+  - `mcp_content_processor.py`: Intelligent processing of MCP tool responses, converting raw content into appropriately typed artifacts
+  - `runner.py`: Manages the asynchronous execution of ADK agent tasks, including cancellation support
+  - `services.py`: Contains factory functions for initializing ADK services (session, artifact, memory) based on configuration
+  - `setup.py`: Handles the high-level initialization of the ADK agent, tools, and runner
+  - `stream_parser.py`: An internal utility for parsing fenced artifact blocks from an LLM's streaming response
+  - `tool_wrapper.py`: A wrapper for Python functions to make them compatible with ADK, handling embed resolution and config injection
 - **Subdirectories:**
-  - `models/`: Contains concrete `BaseLlm` implementations for interfacing with various LLM providers.
+  - `artifacts/`: Contains filesystem and S3-compatible artifact storage implementations
+  - `models/`: Contains concrete `BaseLlm` implementations for interfacing with various LLM providers
 
 ## Developer API Reference
 
@@ -28,66 +32,202 @@ Once initialized, the `AppLlmAgent` (a custom agent class) is managed by the `ru
 
 #### app_llm_agent.py
 **Purpose:** A custom `LlmAgent` subclass that includes a reference to its hosting component, allowing callbacks and tools to access host-level configurations and services.
-**Import:** `from agent.adk.app_llm_agent import AppLlmAgent`
+**Import:** `from solace_agent_mesh.agent.adk.app_llm_agent import AppLlmAgent`
 
 **Classes/Functions/Constants:**
 - `AppLlmAgent(host_component: Any = None, **kwargs)`: A custom `LlmAgent` that can be linked to a host component. The `host_component` is set post-initialization and is excluded from serialization.
 
 #### callbacks.py
 **Purpose:** Provides a suite of ADK callback functions that hook into the agent's lifecycle to inject custom logic. These are typically not called directly but are assigned to the agent during setup.
-**Import:** `from agent.adk import callbacks`
+**Import:** `from solace_agent_mesh.agent.adk import callbacks`
 
 **Classes/Functions/Constants:**
-- `inject_dynamic_instructions_callback(...)`: Injects instructions into the prompt based on host configuration, active tools, and peer agents.
-- `manage_large_mcp_tool_responses_callback(...)`: Intercepts large tool responses, saves them as artifacts, and returns a truncated summary to the LLM.
-- `after_tool_callback_inject_metadata(...)`: After a tool creates an artifact, this loads its metadata and injects it into the tool response.
-- `process_artifact_blocks_callback(...)`: Processes streaming text to identify and save fenced artifact blocks (e.g., `«««save_artifact:...»»»`).
-- `auto_continue_on_max_tokens_callback(...)`: Automatically continues a conversation if the LLM response was interrupted due to token limits.
-- `notify_tool_invocation_start_callback(...)`: Sends a status update over Solace when a tool is about to be invoked.
-- `solace_llm_invocation_callback(...)`: Sends a status update over Solace when the agent calls the LLM.
+- `inject_dynamic_instructions_callback(...)`: Injects instructions into the prompt based on host configuration, active tools, and peer agents
+- `manage_large_mcp_tool_responses_callback(...)`: Intercepts large tool responses, saves them as artifacts, and returns a truncated summary to the LLM
+- `after_tool_callback_inject_metadata(...)`: After a tool creates an artifact, this loads its metadata and injects it into the tool response
+- `process_artifact_blocks_callback(...)`: Processes streaming text to identify and save fenced artifact blocks (e.g., `«««save_artifact:...»»»`)
+- `auto_continue_on_max_tokens_callback(...)`: Automatically continues a conversation if the LLM response was interrupted due to token limits
+- `notify_tool_invocation_start_callback(...)`: Sends a status update over Solace when a tool is about to be invoked
+- `solace_llm_invocation_callback(...)`: Sends a status update over Solace when the agent calls the LLM
+- `repair_history_callback(...)`: Proactively checks for and repairs dangling tool calls in conversation history
+
+#### embed_resolving_mcp_toolset.py
+**Purpose:** Custom MCPToolset that resolves embeds in tool parameters before calling MCP tools, enabling dynamic content injection.
+**Import:** `from solace_agent_mesh.agent.adk.embed_resolving_mcp_toolset import EmbedResolvingMCPToolset, EmbedResolvingMCPTool`
+
+**Classes/Functions/Constants:**
+- `EmbedResolvingMCPToolset(connection_params, tool_filter=None, auth_scheme=None, auth_credential=None, tool_config=None)`: Custom MCPToolset that creates EmbedResolvingMCPTool instances
+- `EmbedResolvingMCPTool(original_mcp_tool, tool_config=None)`: Custom MCPTool that resolves embeds in parameters before calling the actual MCP tool
 
 #### filesystem_artifact_service.py
 **Purpose:** An implementation of `BaseArtifactService` that stores artifacts on the local filesystem, organized by scope, user, and session.
-**Import:** `from agent.adk.filesystem_artifact_service import FilesystemArtifactService`
+**Import:** `from solace_agent_mesh.agent.adk.filesystem_artifact_service import FilesystemArtifactService`
 
 **Classes/Functions/Constants:**
-- `FilesystemArtifactService(base_path: str, scope_identifier: str)`: A service for managing artifacts on the local disk.
-  - `async save_artifact(...) -> int`: Saves an artifact and returns its version number.
-  - `async load_artifact(...) -> Optional[adk_types.Part]`: Loads a specific version of an artifact, or the latest if unspecified.
-  - `async list_artifact_keys(...) -> List[str]`: Lists the names of all artifacts for a given user/session.
-  - `async delete_artifact(...)`: Deletes an artifact and all its versions.
+- `FilesystemArtifactService(base_path: str)`: A service for managing artifacts on the local disk
+  - `async save_artifact(...) -> int`: Saves an artifact and returns its version number
+  - `async load_artifact(...) -> Optional[adk_types.Part]`: Loads a specific version of an artifact, or the latest if unspecified
+  - `async list_artifact_keys(...) -> List[str]`: Lists the names of all artifacts for a given user/session
+  - `async delete_artifact(...)`: Deletes an artifact and all its versions
+  - `async list_versions(...) -> List[int]`: Lists all version numbers for a specific artifact
+
+#### intelligent_mcp_callbacks.py
+**Purpose:** Intelligent MCP callback functions that use intelligent content processing to save MCP tool responses as appropriately typed artifacts.
+**Import:** `from solace_agent_mesh.agent.adk.intelligent_mcp_callbacks import save_mcp_response_as_artifact_intelligent, McpSaveResult, McpSaveStatus`
+
+**Classes/Functions/Constants:**
+- `save_mcp_response_as_artifact_intelligent(tool, tool_context, host_component, mcp_response_dict, original_tool_args) -> McpSaveResult`: Intelligently processes and saves MCP tool response content as typed artifacts
+- `McpSaveStatus`: Enumeration for the status of an MCP save operation (SUCCESS, PARTIAL_SUCCESS, ERROR)
+- `McpSaveResult`: The definitive result of an MCP response save operation with status, message, and artifact details
 
 #### invocation_monitor.py
 **Purpose:** A debugging utility that logs the entire lifecycle of an agent invocation, from the initial request to the final response, into a structured YAML file.
-**Import:** `from agent.adk.invocation_monitor import InvocationMonitor`
+**Import:** `from solace_agent_mesh.agent.adk.invocation_monitor import InvocationMonitor`
+
+**Classes/Functions/Constants:**
+- `InvocationMonitor()`: A class that monitors and logs agent message flows
+  - `log_message_event(direction: str, topic: str, payload: any, ...)`: Logs a single message event
+  - `cleanup()`: Finalizes any active logging sessions
+
+#### mcp_content_processor.py
+**Purpose:** Intelligent processing of MCP tool responses, converting raw MCP content into appropriately typed and formatted artifacts based on the MCP specification content types.
+**Import:** `from solace_agent_mesh.agent.adk.mcp_content_processor import MCPContentProcessor, MCPContentItem, MCPContentProcessorConfig`
 
 **Classes/Functions/Constants:**
-- `InvocationMonitor()`: A class that monitors and logs agent message flows.
-  - `log_message_event(direction: str, topic: str, payload: any, ...)`: Logs a single message event. The monitor automatically starts and stops logging based on topic patterns.
-  - `cleanup()`: Finalizes any active logging sessions.
+- `MCPContentProcessor(tool_name: str, tool_args: Dict[str, Any])`: Main processor for MCP tool response content
+  - `process_mcp_response(mcp_response_dict) -> List[MCPContentItem]`: Process an MCP tool response and extract content items
+- `MCPContentItem`: Represents a processed MCP content item with metadata
+- `MCPContentProcessorConfig`: Configuration for MCP content processing
 
 #### runner.py
 **Purpose:** Provides the core asynchronous task execution logic for the ADK agent, including robust cancellation handling.
-**Import:** `from agent.adk.runner import run_adk_async_task_thread_wrapper, TaskCancelledError`
+**Import:** `from solace_agent_mesh.agent.adk.runner import run_adk_async_task_thread_wrapper, TaskCancelledError`
 
 **Classes/Functions/Constants:**
-- `run_adk_async_task_thread_wrapper(component, adk_session, adk_content, ...)`: A high-level wrapper that runs an ADK task in a separate thread and handles all cleanup and error finalization.
-- `TaskCancelledError(Exception)`: Custom exception raised when an agent task is cancelled externally.
+- `run_adk_async_task_thread_wrapper(component, adk_session, adk_content, ...)`: A high-level wrapper that runs an ADK task in a separate thread and handles all cleanup and error finalization
+- `run_adk_async_task(component, task_context, adk_session, adk_content, run_config, a2a_context) -> bool`: Runs the ADK Runner asynchronously and processes intermediate events
+- `TaskCancelledError(Exception)`: Custom exception raised when an agent task is cancelled externally
 
 #### services.py
 **Purpose:** Provides factory functions to initialize the various ADK services based on the agent's configuration file.
-**Import:** `from agent.adk.services import initialize_session_service, initialize_artifact_service, initialize_memory_service`
+**Import:** `from solace_agent_mesh.agent.adk.services import initialize_session_service, initialize_artifact_service, initialize_memory_service, ScopedArtifactServiceWrapper`
 
 **Classes/Functions/Constants:**
-- `initialize_session_service(component) -> BaseSessionService`: Creates a session service (e.g., `InMemorySessionService`).
-- `initialize_artifact_service(component) -> BaseArtifactService`: Creates an artifact service (e.g., `FilesystemArtifactService`, `GcsArtifactService`).
-- `initialize_memory_service(component) -> BaseMemoryService`: Creates a memory service (e.g., `InMemoryMemoryService`).
+- `initialize_session_service(component) -> BaseSessionService`: Creates a session service (e.g., `InMemorySessionService`)
+- `initialize_artifact_service(component) -> BaseArtifactService`: Creates an artifact service (e.g., `FilesystemArtifactService`, `GcsArtifactService`)
+- `initialize_memory_service(component) -> BaseMemoryService`: Creates a memory service (e.g., `InMemoryMemoryService`)
+- `ScopedArtifactServiceWrapper`: A wrapper that transparently applies configured scope to artifact operations
 
 #### setup.py
 **Purpose:** The main entry point for configuring and instantiating the ADK agent and its dependencies. These functions tie all the other modules together.
-**Import:** `from agent.adk.setup import load_adk_tools, initialize_adk_agent, initialize_adk_runner`
+**Import:** `from solace_agent_mesh.agent.adk.setup import load_adk_tools, initialize_adk_agent, initialize_adk_runner`
+
+**Classes/Functions/Constants:**
+- `async load_adk_tools(component) -> Tuple[List[Union[BaseTool, Callable]], List[BuiltinTool]]`: Loads all configured tools, including Python functions, MCP tools, and built-ins, wrapping them with `ADKToolWrapper`
+- `initialize_adk_agent(component, loaded_explicit_tools, enabled_builtin_tools) -> AppLlmAgent`: Creates an `AppLlmAgent` instance, assigns all the necessary callbacks from `callbacks.py`, and attaches the tools
+- `initialize_adk_runner(component) -> Runner`: Initializes the ADK Runner with the agent and services
+
+#### stream_parser.py
+**Purpose:** A stateful stream parser for identifying and extracting fenced artifact blocks from an LLM's text stream.
+**Import:** `from solace_agent_mesh.agent.adk.stream_parser import FencedBlockStreamParser, BlockStartedEvent, BlockCompletedEvent`
+
+**Classes/Functions/Constants:**
+- `FencedBlockStreamParser(progress_update_interval_bytes=4096)`: Processes a stream of text chunks to identify and extract fenced artifact blocks
+  - `process_chunk(text_chunk: str) -> ParserResult`: Processes the next chunk of text from the stream
+  - `finalize() -> ParserResult`: Call at the end of an LLM turn to handle any unterminated blocks
+- `BlockStartedEvent`, `BlockCompletedEvent`, `BlockProgressedEvent`, `BlockInvalidatedEvent`: Events emitted by the parser
+
+#### tool_wrapper.py
+**Purpose:** A wrapper for Python functions to make them compatible with ADK, handling embed resolution and config injection.
+**Import:** `from solace_agent_mesh.agent.adk.tool_wrapper import ADKToolWrapper`
 
 **Classes/Functions/Constants:**
-- `async load_adk_tools(component) -> Tuple[...]`: Loads all configured tools, including Python functions, MCP tools, and built-ins, wrapping them with `ADKToolWrapper`.
-- `initialize_adk_agent(component, loaded_explicit_tools, ...)`: Creates an `AppLlmAgent` instance, assigns all the necessary callbacks from `callbacks.py`, and attaches the tools.
-- `initialize_adk_
+- `ADKToolWrapper(original_func, tool_config, tool_name, origin, raw_string_args=None)`: A consolidated wrapper for ADK tools that handles metadata preservation, embed resolution, config injection, and error handling
+
+### Subdirectory APIs
+
+#### artifacts/
+**Purpose:** Contains filesystem and S3-compatible artifact storage implementations for managing artifacts with versioning, user namespacing, and session-based organization
+**Key Exports:** `FilesystemArtifactService`, `S3ArtifactService` classes for local and cloud artifact storage
+**Import Examples:**
+```python
+from solace_agent_mesh.agent.adk.artifacts.filesystem_artifact_service import FilesystemArtifactService
+from solace_agent_mesh.agent.adk.artifacts.s3_artifact_service import S3ArtifactService
+```
+
+#### models/
+**Purpose:** Contains concrete `BaseLlm` implementations for interfacing with various LLM providers
+**Key Exports:** `LiteLlm` class for broad model provider compatibility
+**Import Examples:**
+```python
+from solace_agent_mesh.agent.adk.models.lite_llm import LiteLlm
+```
+
+## Complete Usage Guide
+
+### 1. Basic ADK Agent Setup
+
+```python
+from solace_agent_mesh.agent.adk.setup import load_adk_tools, initialize_adk_agent, initialize_adk_runner
+from solace_agent_mesh.agent.adk.services import initialize_session_service, initialize_artifact_service, initialize_memory_service
+from solace_agent_mesh.agent.adk.models.lite_llm import LiteLlm
+
+# Initialize services
+session_service = initialize_session_service(component)
+artifact_service = initialize_artifact_service(component)
+memory_service = initialize_memory_service(component)
+
+# Load tools
+loaded_tools, builtin_tools = await load_adk_tools(component)
+
+# Initialize agent
+agent = initialize_adk_agent(component, loaded_tools, builtin_tools)
+
+# Initialize runner
+runner = initialize_adk_runner(component)
+```
+
+### 2. Custom LLM Model Configuration
+
+```python
+from solace_agent_mesh.agent.adk.models.lite_llm import LiteLlm
+
+# Configure LiteLlm for different providers
+# OpenAI
+llm = LiteLlm(
+    model="gpt-4-turbo",
+    temperature=0.7,
+    max_completion_tokens=1000
+)
+
+# Anthropic
+llm = LiteLlm(
+    model="claude-3-sonnet-20240229",
+    temperature=0.5
+)
+
+# Vertex AI
+llm = LiteLlm(
+    model="gemini-pro",
+    temperature=0.3
+)
+```
+
+### 3. Artifact Service Usage
+
+```python
+from solace_agent_mesh.agent.adk.artifacts.filesystem_artifact_service import FilesystemArtifactService
+from solace_agent_mesh.agent.adk.artifacts.s3_artifact_service import S3ArtifactService
+from google.genai import types as adk_types
+
+# Initialize filesystem artifact service
+artifact_service = FilesystemArtifactService(base_path="/tmp/artifacts")
+
+# Or initialize S3 artifact service
+artifact_service = S3ArtifactService(bucket_name="my-artifacts-bucket")
+
+# Save an artifact
+content = "Hello, world!"
+artifact = adk_types.Part.from_text(content
+
+# content_hash: bdaeea265906dddb9e33e2ae4476cd77b2db58d735ff6afbc222b7815736f601

solace_agent_mesh/agent/adk/artifacts/artifacts_llm.txt

@@ -0,0 +1,171 @@
+# DEVELOPER GUIDE: artifacts
+
+## Quick Summary
+The artifacts directory provides ADK ArtifactService implementations for the Solace Agent Mesh. It includes filesystem and S3-compatible storage backends for managing artifacts with versioning, user namespacing, and session-based organization.
+
+## Files Overview
+- `__init__.py` - Package initialization for artifact service implementations
+- `filesystem_artifact_service.py` - Local filesystem-based artifact storage implementation
+- `s3_artifact_service.py` - Amazon S3 compatible storage implementation for artifacts
+
+## Developer API Reference
+
+### filesystem_artifact_service.py
+**Purpose:** Provides local filesystem storage for artifacts with structured directory organization and metadata management.
+
+**Import:** `from solace_agent_mesh.agent.adk.artifacts.filesystem_artifact_service import FilesystemArtifactService`
+
+**Classes:**
+- `FilesystemArtifactService(base_path: str)` - Filesystem-based artifact service implementation
+  - `save_artifact(*, app_name: str, user_id: str, session_id: str, filename: str, artifact: adk_types.Part) -> int` - Saves an artifact and returns version number
+  - `load_artifact(*, app_name: str, user_id: str, session_id: str, filename: str, version: int | None = None) -> adk_types.Part | None` - Loads an artifact by version (latest if None)
+  - `list_artifact_keys(*, app_name: str, user_id: str, session_id: str) -> list[str]` - Lists all artifact filenames for a scope
+  - `delete_artifact(*, app_name: str, user_id: str, session_id: str, filename: str) -> None` - Deletes all versions of an artifact
+  - `list_versions(*, app_name: str, user_id: str, session_id: str, filename: str) -> list[int]` - Lists all version numbers for an artifact
+  - `base_path: str` - Root directory for artifact storage
+
+**Constants/Variables:**
+- `METADATA_FILE_SUFFIX: str` - File suffix for metadata files (".meta")
+
+**Usage Examples:**
+```python
+from solace_agent_mesh.agent.adk.artifacts.filesystem_artifact_service import FilesystemArtifactService
+from google.genai import types as adk_types
+
+# Initialize the service
+artifact_service = FilesystemArtifactService(base_path="/path/to/artifacts")
+
+# Save an artifact
+artifact_data = b"Hello, World!"
+artifact_part = adk_types.Part.from_bytes(data=artifact_data, mime_type="text/plain")
+version = await artifact_service.save_artifact(
+    app_name="my_app",
+    user_id="user123",
+    session_id="session456",
+    filename="greeting.txt",
+    artifact=artifact_part
+)
+
+# Load the latest version
+loaded_artifact = await artifact_service.load_artifact(
+    app_name="my_app",
+    user_id="user123", 
+    session_id="session456",
+    filename="greeting.txt"
+)
+
+# Load a specific version
+specific_version = await artifact_service.load_artifact(
+    app_name="my_app",
+    user_id="user123",
+    session_id="session456", 
+    filename="greeting.txt",
+    version=1
+)
+
+# List all artifacts
+artifact_keys = await artifact_service.list_artifact_keys(
+    app_name="my_app",
+    user_id="user123",
+    session_id="session456"
+)
+
+# List versions of an artifact
+versions = await artifact_service.list_versions(
+    app_name="my_app",
+    user_id="user123",
+    session_id="session456",
+    filename="greeting.txt"
+)
+
+# Delete an artifact
+await artifact_service.delete_artifact(
+    app_name="my_app",
+    user_id="user123",
+    session_id="session456",
+    filename="greeting.txt"
+)
+```
+
+### s3_artifact_service.py
+**Purpose:** Provides S3-compatible storage for artifacts with structured key organization and AWS integration.
+
+**Import:** `from solace_agent_mesh.agent.adk.artifacts.s3_artifact_service import S3ArtifactService`
+
+**Classes:**
+- `S3ArtifactService(bucket_name: str, s3_client: BaseClient | None = None, **kwargs)` - S3-based artifact service implementation
+  - `save_artifact(*, app_name: str, user_id: str, session_id: str, filename: str, artifact: adk_types.Part) -> int` - Saves an artifact to S3 and returns version number
+  - `load_artifact(*, app_name: str, user_id: str, session_id: str, filename: str, version: int | None = None) -> adk_types.Part | None` - Loads an artifact from S3 by version (latest if None)
+  - `list_artifact_keys(*, app_name: str, user_id: str, session_id: str) -> list[str]` - Lists all artifact filenames for a scope
+  - `delete_artifact(*, app_name: str, user_id: str, session_id: str, filename: str) -> None` - Deletes all versions of an artifact from S3
+  - `list_versions(*, app_name: str, user_id: str, session_id: str, filename: str) -> list[int]` - Lists all version numbers for an artifact
+  - `bucket_name: str` - S3 bucket name for storage
+  - `s3: BaseClient` - Boto3 S3 client instance
+
+**Usage Examples:**
+```python
+from solace_agent_mesh.agent.adk.artifacts.s3_artifact_service import S3ArtifactService
+from google.genai import types as adk_types
+import boto3
+
+# Initialize with default credentials
+artifact_service = S3ArtifactService(bucket_name="my-artifacts-bucket")
+
+# Initialize with custom S3 client
+s3_client = boto3.client(
+    's3',
+    endpoint_url='https://minio.example.com',
+    aws_access_key_id='access_key',
+    aws_secret_access_key='secret_key'
+)
+artifact_service = S3ArtifactService(
+    bucket_name="my-artifacts-bucket",
+    s3_client=s3_client
+)
+
+# Save an artifact
+artifact_data = b"Hello, S3!"
+artifact_part = adk_types.Part.from_bytes(data=artifact_data, mime_type="text/plain")
+version = await artifact_service.save_artifact(
+    app_name="my_app",
+    user_id="user123",
+    session_id="session456", 
+    filename="greeting.txt",
+    artifact=artifact_part
+)
+
+# Load the latest version
+loaded_artifact = await artifact_service.load_artifact(
+    app_name="my_app",
+    user_id="user123",
+    session_id="session456",
+    filename="greeting.txt"
+)
+
+# Save user-scoped artifact (persists across sessions)
+user_artifact = adk_types.Part.from_bytes(data=b"User data", mime_type="text/plain")
+await artifact_service.save_artifact(
+    app_name="my_app", 
+    user_id="user123",
+    session_id="session456",
+    filename="user:profile.json",  # user: prefix for user-scoped storage
+    artifact=user_artifact
+)
+
+# List all artifacts (includes both session and user-scoped)
+artifact_keys = await artifact_service.list_artifact_keys(
+    app_name="my_app",
+    user_id="user123", 
+    session_id="session456"
+)
+
+# Delete an artifact
+await artifact_service.delete_artifact(
+    app_name="my_app",
+    user_id="user123",
+    session_id="session456",
+    filename="greeting.txt"
+)
+```
+
+# content_hash: bc2a538c503d0082a1ea06c7bfd9c69450f53d5aa958ca1f3c19819c676eb183