Skip to content

Add LocalFileArtifactService for local file system artifact storage #2410

@eduramirezh

Description

@eduramirezh

** Please make sure you read the contribution guide and file the issues in the right place. **
Contribution guide.

Is your feature request related to a problem? Please describe.
Currently, ADK Python only provides two artifact storage options: InMemoryArtifactService (for development/testing) and GcsArtifactService (for cloud production). There's no option for local file system
persistence, which creates a gap for:

  • Local development environments where developers want persistent artifact storage without cloud dependencies
  • Testing scenarios that need file persistence across test runs but don't require cloud storage
  • Self-hosted or air-gapped deployments where cloud storage isn't available or desired
  • CI/CD pipelines that need artifact persistence within build containers

Describe the solution you'd like
A new LocalFileArtifactService that implements the BaseArtifactService interface and stores artifacts on the local file system. This service should:

  • Store artifacts in a configurable local directory structure
  • Maintain the same namespace patterns as existing services (user/session scoping)
  • Support all existing artifact operations (save, load, delete, list, versioning)
  • Preserve MIME types and handle different content types
  • Provide async operations using proper thread handling for file I/O
  • Handle error conditions gracefully (corrupted metadata, missing files, etc.)
  • Follow ADK coding standards and patterns

Describe alternatives you've considered

  • Using InMemoryArtifactService: Doesn't provide persistence across application restarts
  • Using GcsArtifactService: Requires cloud setup and credentials, not suitable for local development
  • External storage solutions: Would require additional dependencies and complexity
  • Custom implementations: Each user implementing their own defeats the purpose of having a standard artifact service

Additional context
This feature would complete the artifact storage options by providing:

  1. InMemoryArtifactService - For ephemeral development/testing
  2. GcsArtifactService - For cloud production deployments
  3. LocalFileArtifactService - For local persistence needs

The implementation should be a drop-in replacement that maintains full API compatibility with existing artifact services, allowing developers to switch between storage backends easily based on their
deployment needs.

Expected file structure:

  {base_path}/
  ├── {app_name}/
  │   └── {user_id}/
  │       ├── {session_id}/
  │       │   └── {filename}/
  │       │       ├── 0              # artifact data
  │       │       ├── 0.metadata.json # MIME type info
  │       │       ├── 1              # next version
  │       │       └── 1.metadata.json
  │       └── user/                   # user-namespaced files
  │           └── {user:filename}/
  │               ├── 0
  │               └── 0.metadata.json

This would enable developers to use ADK in a wider range of deployment scenarios while maintaining consistency with the existing artifact service architecture.

Metadata

Metadata

Assignees

Labels

bot triaged[Bot] This issue is triaged by ADK botservices[Component] This issue is related to runtime services, e.g. sessions, memory, artifacts, etc

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions