tos-file-access

Files (4)

• LICENSE.txt
• SKILL.md
• file_download.py · scripts/
• tos_upload.py · scripts/

SKILL.md (first lines)

# 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:

```bash
# 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:

```bash
# 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:**

```bash
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:**

```bash
# 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:**

```bash
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:

From bytedance/agentkit-samples, Apache-2.0.

More from bytedance/agentkit-samples