File Operations
UtilsRead, write, list, upload, and manage files on the device
Access file operations through agent.utils.files. Comprehensive file system access for automations. For uploading files to the server, use agent.utils.uploadTempFile.
interface AgentFiles { exists(path: string): boolean; getSize(filePath: string): number; readFullFileBase64(filePath: string): string; readFullFile(filePath: string): string; openStream(filePath: string): string; readChunk(streamId: string, chunkSize: number): number[]; closeStream(streamId: string): void; list(dirPath: string): FileInfo[]; getPathInfo(path: string): DirectoryInfo | FilePathInfo | PathNotFoundInfo; getStorageRoot(): string; getHashes(filePath: string): FileHashes | FileHashError; deleteFile(path: string): boolean; // Since 2.138 deleteDir(path: string): boolean; // Since 2.138 rename(oldPath: string, newPath: string): boolean; // Since 2.138 getDirPath(type: string): string; // Since 2.138 startDownload(url: string, localPath: string, options?: DownloadRequestOptions): string; // Since 2.138 getDownloadStatus(id: string): DownloadStatusInfo; // Since 2.138 retryDownload(id: string): boolean; // Since 2.138 base64ToBytes(base64: string): Uint8Array; bytesToBlob(bytes: number[] | Uint8Array, mimeType?: string): Blob | null; readFileAsBlob(filePath: string, mimeType?: string): Blob | null;}
// On agent.utils (for file upload)interface AgentUtils { uploadTempFile(filename: string, base64Data: string): Promise<UploadTempFileResult | { success: false; error: string }>; uploadTempFile(localFilePath: string): Promise<UploadTempFileResult | { success: false; error: string }>;}Basic Operations
exists()
exists(path: string): booleanChecks if a file or directory exists at the specified path.
Parameters
| Name | Type | Description |
|---|---|---|
path | string | Path to check |
Returns
booleantrue if the path exists
Examples
if (agent.utils.files.exists("/sdcard/Download/data.json")) { const content = agent.utils.files.readFullFile("/sdcard/Download/data.json");}getSize()
getSize(filePath: string): numberGets the size of a file in bytes.
Parameters
| Name | Type | Description |
|---|---|---|
filePath | string | Path to the file |
Returns
numberFile size in bytes, or -1 if not found
Examples
const size = agent.utils.files.getSize("/sdcard/video.mp4");getStorageRoot()
getStorageRoot(): stringGets the root storage path for the device (typically '/sdcard' or '/storage/emulated/0').
Returns
stringStorage root path
Examples
const root = agent.utils.files.getStorageRoot();const downloadPath = root + "/Download";Reading Files
readFullFile()
readFullFile(filePath: string): stringReads the entire file content as UTF-8 text.
Parameters
| Name | Type | Description |
|---|---|---|
filePath | string | Path to the file |
Returns
stringFile content as text
Examples
const config = agent.utils.files.readFullFile("/sdcard/config.json");const data = JSON.parse(config);readFullFileBase64()
readFullFileBase64(filePath: string): stringReads the entire file content as a Base64-encoded string. Useful for binary files.
Parameters
| Name | Type | Description |
|---|---|---|
filePath | string | Path to the file |
Returns
stringBase64-encoded file content
Examples
const imageBase64 = agent.utils.files.readFullFileBase64("/sdcard/DCIM/photo.jpg");const ocrResult = await agent.actions.recognizeText(imageBase64);readFileAsBlob()
readFileAsBlob(filePath: string, mimeType?: string): Blob | nullReads a file directly as a Blob object.
Parameters
| Name | Type | Description |
|---|---|---|
filePath | string | Path to the file |
mimeType? | string | MIME type for the blob |
Returns
Blob | nullBlob object or null on failure
Examples
const imageBlob = agent.utils.files.readFileAsBlob("/sdcard/image.png", "image/png");Streaming Large Files
openStream()
openStream(filePath: string): stringOpens a file stream for reading large files in chunks.
Parameters
| Name | Type | Description |
|---|---|---|
filePath | string | Path to the file |
Returns
stringStream ID for use with readChunk and closeStream
Examples
const streamId = agent.utils.files.openStream("/sdcard/large_file.bin");let chunk;while ((chunk = agent.utils.files.readChunk(streamId, 1024 * 1024)).length > 0) { // Process chunk...}agent.utils.files.closeStream(streamId);readChunk()
readChunk(streamId: string, chunkSize: number): number[]Reads a chunk of data from an open file stream.
Parameters
| Name | Type | Description |
|---|---|---|
streamId | string | Stream ID from openStream() |
chunkSize | number | Maximum bytes to read |
Returns
number[]Array of byte values (empty if end of file)
closeStream()
closeStream(streamId: string): voidCloses an open file stream.
Parameters
| Name | Type | Description |
|---|---|---|
streamId | string | Stream ID from openStream() |
Directory Operations
list()
list(dirPath: string): FileInfo[]Lists all files and directories in the specified directory.
Parameters
| Name | Type | Description |
|---|---|---|
dirPath | string | Directory path |
Returns
FileInfo[]Array of file/directory information
Examples
const files = agent.utils.files.list("/sdcard/Download");for (const file of files) { console.log(file.name, file.isDirectory ? "(dir)" : file.size + " bytes");}getPathInfo()
getPathInfo(path: string): DirectoryInfo | FilePathInfo | PathNotFoundInfoGets detailed information about a path, including whether it's a file or directory.
Parameters
| Name | Type | Description |
|---|---|---|
path | string | Path to check |
Returns
DirectoryInfo | FilePathInfo | PathNotFoundInfoDetailed path information based on path type
Examples
const info = agent.utils.files.getPathInfo("/sdcard/Download");if (info.exists && info.isDirectory) { console.log("Contains", info.totalItems, "items");}File Management
deleteFile()
deleteFile(path: string): booleanDeletes a file at the specified path. Only works on files, not directories. Returns false if the path doesn't exist, is a directory, or deletion fails.Since 2.138 (150)
Parameters
| Name | Type | Description |
|---|---|---|
path | string | Path to the file to delete |
Returns
booleantrue if the file was deleted successfully
Examples
const deleted = agent.utils.files.deleteFile("/sdcard/Download/temp.txt");if (deleted) { console.log("File deleted");}deleteDir()
deleteDir(path: string): booleanDeletes a directory and all its contents recursively. Only works on directories, not files. Returns false if the path doesn't exist, is a file, or deletion fails.Since 2.138 (150)
Parameters
| Name | Type | Description |
|---|---|---|
path | string | Path to the directory to delete |
Returns
booleantrue if the directory was deleted successfully
Examples
const deleted = agent.utils.files.deleteDir("/sdcard/Download/temp_folder");if (deleted) { console.log("Directory and all contents deleted");}rename()
rename(oldPath: string, newPath: string): booleanRenames or moves a file or directory from oldPath to newPath. Parent directories for the new path are created automatically. Fails if the source doesn't exist or destination already exists.Since 2.138 (150)
Parameters
| Name | Type | Description |
|---|---|---|
oldPath | string | Current path (file or directory) |
newPath | string | New path |
Returns
booleantrue if renamed/moved successfully
Examples
// Rename a fileagent.utils.files.rename("/sdcard/Download/old.txt", "/sdcard/Download/new.txt");
// Move a file to another directoryagent.utils.files.rename("/sdcard/Download/photo.jpg", "/sdcard/Pictures/photo.jpg");
// Rename a directoryagent.utils.files.rename("/sdcard/Download/old_folder", "/sdcard/Download/new_folder");getDirPath()
getDirPath(type: "Download" | "Movies" | "Music" | "Pictures" | "DCIM" | "Documents" | "Ringtones" | "Alarms" | "Notifications" | "Podcasts"): stringGets the external public directory path for a given type.Since 2.138 (150)
Parameters
| Name | Type | Description |
|---|---|---|
type | string | Directory type: "Download", "Movies", "Music", "Pictures", "DCIM", "Documents", "Ringtones", "Alarms", "Notifications", "Podcasts" |
Returns
stringAbsolute path (e.g., "/storage/emulated/0/Download")
Examples
const downloadDir = agent.utils.files.getDirPath("Download");const files = agent.utils.files.list(downloadDir);console.log("Downloads:", files.length, "files");
const musicDir = agent.utils.files.getDirPath("Music");File Download
startDownload()
startDownload(url: string, localPath: string, options?: DownloadRequestOptions): stringStarts downloading a file from a URL to a local path on the device. Returns a unique download ID that can be used to track progress with getDownloadStatus. Parent directories are created automatically. Supports resume on retry. Optionally specify HTTP method, headers, and body.Since 2.138 (150)
Parameters
| Name | Type | Description |
|---|---|---|
url | string | The URL to download from |
localPath | string | The local file path to save the downloaded file to |
options? | DownloadRequestOptions | Optional HTTP request options (method, headers, body) |
Returns
stringA unique download ID for tracking progress
Examples
const downloadDir = agent.utils.files.getDirPath("Download");const id = agent.utils.files.startDownload( "https://example.com/large-file.zip", downloadDir + "/large-file.zip");
// Poll for progresslet status;do { await sleep(1000); status = agent.utils.files.getDownloadStatus(id); if (status.totalBytes > 0) { const percent = Math.round((status.bytesDownloaded / status.totalBytes) * 100); console.log("Progress:", percent + "%"); }} while (status.status === "downloading");
if (status.status === "success") { console.log("Downloaded to:", status.filePath, "Size:", status.fileSize);} else { console.error("Failed:", status.error);}const id = agent.utils.files.startDownload( "https://api.example.com/export", "/sdcard/Download/export.csv", { method: "POST", headers: { "Authorization": "Bearer my-token", "Content-Type": "application/json", }, body: JSON.stringify({ format: "csv", dateRange: "last30days" }), });getDownloadStatus()
getDownloadStatus(id: string): DownloadStatusInfoReturns the current status of a download. Status can be "downloading", "success", or "failed". Includes progress info (bytesDownloaded, totalBytes) and result info (filePath, fileSize) on success.Since 2.138 (150)
Parameters
| Name | Type | Description |
|---|---|---|
id | string | The download ID returned by startDownload |
Returns
DownloadStatusInfoObject with download status, progress, and result info
Examples
const status = agent.utils.files.getDownloadStatus(downloadId);console.log("Status:", status.status);console.log("Progress:", status.bytesDownloaded, "/", status.totalBytes);retryDownload()
retryDownload(id: string): booleanRetries a failed download. Only works if the download is in failed state. The download resumes from where it left off if the server supports Range requests.Since 2.138 (150)
Parameters
| Name | Type | Description |
|---|---|---|
id | string | The download ID returned by startDownload |
Returns
booleantrue if retry was started, false if download not found or not in failed state
Examples
const status = agent.utils.files.getDownloadStatus(downloadId);if (status.status === "failed") { console.log("Download failed:", status.error); const retried = agent.utils.files.retryDownload(downloadId); if (retried) console.log("Retrying...");}DownloadStatusInfo
Status information for a file download.
interface DownloadStatusInfo { id: string; // Unique download ID status: "downloading" | "success" | "failed"; error: string | null; // Error message if failed bytesDownloaded: number; // Bytes downloaded so far totalBytes: number; // Total size (-1 if unknown) fileSize: number; // Final file size on success (-1 otherwise) filePath: string | null; // Absolute path on success}DownloadRequestOptions
Optional HTTP request options for startDownload.
interface DownloadRequestOptions { method?: string; // HTTP method (default: "GET") headers?: Record<string, string>; // HTTP headers body?: string; // Request body (for POST, PUT, etc.)}Download & Read
fetch2()
fetch2(url: string, options?: Fetch2Options): Promise<{ success: true; content: string | Blob | Uint8Array; size: number } | { success: false; error: string }>Downloads a file from a URL and returns its content directly. Internally downloads to a temporary file, reads the content, then deletes the temp file. On failure, automatically retries using resume-capable retryDownload.
Parameters
| Name | Type | Description |
|---|---|---|
url | string | The URL to download from |
options? | Fetch2Options | Download options |
Returns
Promise<{ success: true; content: string | Blob | Uint8Array; size: number } | { success: false; error: string }>File content on success, or error on failure
Examples
const result = await agent.utils.fetch2("https://example.com/data.json");if (result.success) { const data = JSON.parse(result.content as string); console.log("Downloaded", result.size, "bytes");}const result = await agent.utils.fetch2("https://example.com/image.png", { readAs: "base64",});if (result.success) { await agent.utils.uploadTempFile("image.png", result.content as string);}const result = await agent.utils.fetch2("https://api.example.com/export", { readAs: "text", method: "POST", headers: { "Authorization": "Bearer my-token" }, body: JSON.stringify({ format: "csv" }), timeoutMs: 60_000, maxRetries: 3,});if (!result.success) { console.error("Download failed:", result.error);}Fetch2Options
Options for the fetch2 utility method.
interface Fetch2Options { readAs?: "text" | "base64" | "blob" | "bytes"; // Default: "text" (UTF-8) timeoutMs?: number; // Max wait time in ms (default: 120000) maxRetries?: number; // Retry attempts on failure (default: 2) method?: string; // HTTP method (default: "GET") headers?: Record<string, string>; // HTTP headers body?: string; // Request body (for POST, PUT, etc.)}File Integrity
getHashes()
getHashes(filePath: string): FileHashes | FileHashErrorCalculates MD5, SHA-1, and SHA-256 hashes for a file.
Parameters
| Name | Type | Description |
|---|---|---|
filePath | string | Path to the file |
Returns
FileHashes | FileHashErrorHash values or error
Examples
const hashes = agent.utils.files.getHashes("/sdcard/download.apk");if (!("error" in hashes)) { console.log("MD5:", hashes.md5); console.log("SHA-256:", hashes.sha256);}File Upload
uploadTempFile()
uploadTempFile(filename: string, base64Data: string): Promise<UploadTempFileResult | { success: false; error: string }>Uploads a file to the server as a temporary file. The file will be automatically deleted after 15 minutes. This overload accepts base64-encoded file data.
Parameters
| Name | Type | Description |
|---|---|---|
filename | string | Name for the uploaded file (including extension) |
base64Data | string | Base64-encoded file content |
Returns
UploadTempFileResult | { success: false; error: string }Upload result with file URL on success, or error on failure
Examples
const screenshot = await agent.actions.screenshot(1080, 1920, 80);if (screenshot.screenshot) { const result = await agent.utils.uploadTempFile( "screenshot.jpg", screenshot.screenshot );
if (result.success) { console.log("File URL:", result.data.url); console.log("Expires at:", result.data.expiresAt); } else { console.error("Upload failed:", result.error); }}const jsonData = JSON.stringify({ results: [1, 2, 3] });const base64 = btoa(jsonData);
const result = await agent.utils.uploadTempFile("results.json", base64);if (result.success) { console.log("Uploaded to:", result.data.url);}uploadTempFile (local file)()
uploadTempFile(localFilePath: string): Promise<UploadTempFileResult | { success: false; error: string }>Uploads a local file from the device to the server as a temporary file. The file will be automatically deleted after 15 minutes. This overload reads the file in chunks to handle large files efficiently.
Parameters
| Name | Type | Description |
|---|---|---|
localFilePath | string | Absolute path to the file on the device |
Returns
UploadTempFileResult | { success: false; error: string }Upload result with file URL on success, or error on failure
Examples
const result = await agent.utils.uploadTempFile("/sdcard/Download/report.pdf");
if (result.success) { console.log("Uploaded:", result.data.originalName); console.log("Size:", result.data.size, "bytes"); console.log("URL:", result.data.url);} else { console.error("Upload failed:", result.error);}const imagePath = "/sdcard/DCIM/Camera/photo.jpg";
if (agent.utils.files.exists(imagePath)) { const result = await agent.utils.uploadTempFile(imagePath); if (result.success) { // Use the URL (valid for 15 minutes) await agent.utils.job.submitTask("success", { imageUrl: result.data.url }, true, []); }}Data Conversion
base64ToBytes()
base64ToBytes(base64: string): Uint8ArrayConverts a Base64-encoded string to a Uint8Array.
Parameters
| Name | Type | Description |
|---|---|---|
base64 | string | Base64-encoded string |
Returns
Uint8ArrayDecoded byte array
bytesToBlob()
bytesToBlob(bytes: number[] | Uint8Array, mimeType?: string): Blob | nullConverts a byte array to a Blob object.
Parameters
| Name | Type | Description |
|---|---|---|
bytes | number[] | Uint8Array | Byte array |
mimeType? | string | MIME type for the blob |
Returns
Blob | nullBlob object or null on failure
Types
FileInfo
interface FileInfo { name: string; // File or directory name path: string; // Full path isDirectory: boolean; isFile: boolean; size: number; // Size in bytes (0 for directories) lastModified: number; // Timestamp}DirectoryInfo
interface DirectoryInfo { exists: true; path: string; name: string; isDirectory: true; isFile: false; lastModified: number; canRead: boolean; canWrite: boolean; fileCount: number; // Number of files directoryCount: number; // Number of subdirectories totalItems: number; // Total items}FilePathInfo
interface FilePathInfo { exists: true; path: string; name: string; isDirectory: false; isFile: true; lastModified: number; canRead: boolean; canWrite: boolean; size: number;}PathNotFoundInfo
interface PathNotFoundInfo { exists: false; error?: string;}FileHashes
interface FileHashes { md5: string; sha1: string; sha256: string; size: number;}UploadTempFileResult
Result returned when a file is successfully uploaded.
interface UploadTempFileResult { success: true; message: string; // "File uploaded successfully" data: { filename: string; // Server-assigned filename (e.g., "1234567890_example.pdf") originalName: string; // Original filename provided size: number; // File size in bytes url: string; // Full URL to access the file expiresAt: string; // ISO 8601 expiration timestamp (15 minutes from upload) };}