/tos-file-access

name: tos-file-access
description: Upload files or directories to TOS-compatible object storage for Volcano Engine or BytePlus and download files from URLs. Use this skill when (1) Upload Agent-generated files or directories for sharing, (2) Download files from URLs before Agent processing.
license: Complete terms in LICENSE.txt

TOS File Access

This skill provides utilities for uploading files and directories to TOS-compatible object storage for Volcano Engine or BytePlus, and downloading files from URLs.

Overview

**TOS-compatible object storage** is used by Volcano Engine and BytePlus, similar to AWS S3. This skill enables:

• **Upload**: Upload Agent-generated files or entire directories to TOS and get shareable signed URLs (for files) or TOS paths (for directories)
• **Download**: Download files from URLs to local storage for Agent processing

Typical Workflows

Pre-Agent Execution: Download User Files

When users provide file URLs (TOS or external), download them before processing:

# Download single file
python scripts/file_download.py https://example.com/data.csv

# Download multiple files
python scripts/file_download.py https://example.com/data.csv https://example.com/config.json

# Specify save directory and filenames
python scripts/file_download.py https://example.com/data.csv --save-dir /workspace --filenames dataset.csv

Post-Agent Execution: Upload Output Files or Directories

After generating files or directories (videos, charts, reports, output folders, etc.), upload them to TOS for user access:

# Upload single file (auto-detected)
python scripts/tos_upload.py /path/to/output.mp4 --bucket my-bucket

# Upload entire directory (auto-detected)
python scripts/tos_upload.py /path/to/output_folder --bucket my-bucket

# Upload to BytePlus with custom expiration
TOS_REGION=ap-southeast-1 python scripts/tos_upload.py /path/to/report.pdf --bucket my-bucket --expires 86400

Scripts

`scripts/file_download.py`

Download files from URLs to local storage.

**Usage:**

python scripts/file_download.py <url1> [url2 ...] [--save-dir DIR] [--filenames NAME1 NAME2 ...]

**Arguments:**

• `urls`: One or more URLs to download (positional, required)
• `--save-dir`: Save directory (optional, defaults to `/tmp`)
• `--filenames`: Custom filenames for downloaded files (optional, must match number of URLs)

**Examples:**

# Download single file to /tmp
python scripts/file_download.py https://tos-cn-beijing.volces.com/bucket/file.pdf

# Download to specific directory
python scripts/file_download.py https://example.com/data.json --save-dir /workspace/data

# Download multiple files with custom names
python scripts/file_download.py \
  https://example.com/file1.pdf \
  https://example.com/file2.jpg \
  --save-dir /workspace \
  --filenames document.pdf image.jpg

**Returns:** Prints absolute paths of downloaded files (one per line)

`scripts/tos_upload.py`

Upload files or directories to TOS and generate signed access URLs (for files) or TOS paths (for directories).

**Key Features:**

• **Auto-detection**: Automatically detects whether the path is a file or directory
• **Session-based paths**: Uses `TOOL_USER_SESSION_ID` environment variable to organize uploads
• **Preserves structure**: For directories, maintains the full directory structure in TOS
• **Automatic bucket creation**: Creates bucket if it doesn't exist (with private ACL)

**Usage:**

python scripts/tos_upload.py <path> --bucket BUCKET [--region REGION] [--expires SECONDS]

**Arguments:**

• `path`: Local file or directory path to upload (positional, required)
• `--bucket`: TOS bucket name (required)
• `--region`: TOS region (optional, defaults to `TOS_REGION`, `DATABASE_TOS_REGION`, or provider default: `ap-southeast-1` for BytePlus, `cn-beijing` for Volcano Engine)
• `--expires`: Signed URL expiration in seconds (optional, defaults to 604800 = 7 days, only applies to file uploads)

**Upload Structure:**

• **File**: `upload/{session_prefix}/{filename}`
• Example: `upload/skill_agent_veadk_default_user_tmp-session-20251210150057/video.mp4`
• **Directory**: `upload/{session_prefix}/{directory_name}/{relative_path}`
• Example: `upload/skill_agent_veadk_default_user_tmp-session-20251210150057/output_folder/file1.txt`

**Session Prefix:**

• If `TOOL_USER_SESSION_ID` is set, uses that value as prefix
• Otherwise, falls back to timestamp format `YYYYMMDD_HHMMSS`

**Cloud provider and authentication:** Requires one of:

• `TOS_REGION=ap-southeast-1` selects BytePlus endpoint first
• `CLOUD_PROVIDER=byteplus` selects BytePlus endpoint when `TOS_REGION` is not `ap-southeast-1`
• Environment variables: `VOLCENGINE_ACCESS_KEY` and `VOLCENGINE_SECRET_KEY`
• VeFaaS IAM Role (automatic credential retrieval)

**Examples:**

# Upload single file (auto-detected)
python scripts/tos_upload.py /workspace/output.mp4 --bucket my-bucket

# Upload entire directory (auto-detected)
python scripts/tos_upload.py /workspace/results_folder --bucket my-bucket

# Upload to BytePlus with 1-day expiration
TOS_REGION=ap-southeast-1 python scripts/tos_upload.py /workspace/report.pdf \
  --bucket my-reports \
  --expires 86400

# Upload directory with all options
python scripts/tos_upload.py /workspace/output_dir \
  --bucket data-storage \
  --region cn-beijing

**Returns:**

• **For files**: Prints a signed URL that can be shared with users (valid for specified duration)
• **For directories**: Prints a TOS path in format `tos://bucket-name/path/to/directory`

**Output Examples:**

# File upload output
============================================================
✅ Upload Successful!
============================================================
Signed URL:
https://my-bucket.tos-cn-beijing.volces.com/upload/skill_agent_xxx/video.mp4?X-Tos-Signature=...
============================================================

# Directory upload output
================