Drive Storage Tools

📦 Persistent Cloud Storage for Agents

Drive Storage Tools provide agents with persistent, cloud-based file system capabilities that survive across all agent sessions and turns. Unlike temporary code execution sandboxes, Drive storage maintains files indefinitely until explicitly deleted.

Key Features

Persistent Storage: Files remain available across all agent sessions
Workspace Isolation: Each agent has private, isolated storage within its project
Working Directory Scoping: Optionally restrict operations to specific subfolders
Cloud-Based: All files are stored in secure cloud storage
Full CRUD Operations: Create, read, update, delete, rename, and organize files
URL Upload: Download files from internet URLs directly to Drive storage
Binary File Support: Handle images, PDFs, and other binary formats with download URLs

⚙️ Configuration Options

Enable Drive Storage

Toggle to activate Drive storage tools for your agent:

Enabled: Agent can create, read, modify, and organize files in Drive storage
Disabled: Agent has no access to persistent file storage

Working Directory (Optional)

Restrict all file operations to a specific subfolder:

Example Configuration:

Working Directory: "agent-workspace"

Behavior:

Agent can only access files within agent-workspace/
Paths are automatically scoped (e.g., data.csv becomes agent-workspace/data.csv)
Prevents agents from accessing files outside their designated folder
Empty path operates on the working directory itself

Use Cases:

Multi-agent systems where each agent needs isolated storage
Security isolation to prevent cross-contamination
Organized project structure with dedicated agent folders

Individual Tool Permissions

Control which specific file operations the agent can perform:

Tool

Description

Default

View

Read file contents or list directory contents

Enabled

Create

Create new files or overwrite existing files

Enabled

String Replace

Replace exact string matches in files

Enabled

Insert

Insert content at specific line numbers

Enabled

Delete

Delete files or directories

Enabled

Rename

Rename or move files/directories

Enabled

Upload from URL

Download files from URLs to Drive storage

Enabled

Permission Settings:

Allowed: Tool is available to the agent
Not Allowed: Tool is hidden and cannot be used

Security Considerations:

Disable Delete for read-only agents
Disable Create and String Replace for analysis-only agents
Disable Upload from URL if external downloads are not needed

🔧 Available Drive Tools

1. View (_drive_view)

Purpose: Read file contents or list directory contents

Parameters:

file_path (string, required): Path to file or directory
start_line (integer, optional): First line to display (1-indexed, for text files)
end_line (integer, optional): Last line to display (inclusive, for text files)

Behavior:

Text Files: Returns content with line numbers (max 500 lines per view)
Binary Files: Returns download URL (images, PDFs, archives, etc.)
Directories: Lists all files and subdirectories, one per line
Empty Directories: Returns "(empty directory)"

Examples:

# List root directory
_drive_view(file_path="")

# Read entire text file
_drive_view(file_path="notes.txt")

# View specific line range
_drive_view(file_path="data.csv", start_line=1, end_line=100)

# Get download URL for binary file
_drive_view(file_path="report.pdf")

# List subdirectory
_drive_view(file_path="documents")

2. Create (_drive_create)

Purpose: Create new files or overwrite existing files

Parameters:

file_path (string, required): Path where file should be created
content (string, required): Content to write to the file
replace (boolean, optional, default: False): Allow overwriting existing files

Behavior:

Automatically creates parent directories if they don't exist
Fails if file exists and replace=False (prevents accidental overwrites)
Supports any text-based content (JSON, CSV, TXT, code files, etc.)

Examples:

# Create simple text file
_drive_create(file_path="notes.txt", content="Meeting notes here")

# Create JSON configuration
_drive_create(
    file_path="config.json",
    content='{"api_key": "value", "timeout": 30}'
)

# Create file in nested directory (auto-creates "data" folder)
_drive_create(file_path="data/results.csv", content="Name,Score\nAlice,95\nBob,87")

# Overwrite existing file
_drive_create(file_path="notes.txt", content="Updated notes", replace=True)

3. String Replace (_drive_str_replace)

Purpose: Replace an exact string match in a file

Parameters:

file_path (string, required): Path to the file to edit
old_str (string, required): Exact string to find (must appear exactly once)
new_str (string, required): Replacement string

Behavior:

Searches for exact match of old_str
Fails if old_str appears 0 times (not found)
Fails if old_str appears 2+ times (ambiguous match)
Use \n for newlines in multi-line replacements
Only replaces first occurrence (enforced uniqueness)

Examples:

# Simple text replacement
_drive_str_replace(
    file_path="config.json",
    old_str='"timeout": 30',
    new_str='"timeout": 60'
)

# Multi-line replacement
_drive_str_replace(
    file_path="readme.md",
    old_str="## Old Section\nOld content here",
    new_str="## New Section\nUpdated content here"
)

# Replace variable in code
_drive_str_replace(
    file_path="script.py",
    old_str='API_KEY = "old_key"',
    new_str='API_KEY = "new_key"'
)

4. Insert (_drive_insert)

Purpose: Insert content at a specific line number

Parameters:

file_path (string, required): Path to the file to edit
line (integer, required): Line number where content should be inserted (1-indexed)
content (string, required): Text to insert

Behavior:

Line numbers are 1-indexed (line 1 is the first line)
Content is inserted before the specified line
Use line=1 to insert at the beginning
Automatically adds newline if inserting in the middle of the file

Examples:

# Insert at beginning of file
_drive_insert(file_path="script.py", line=1, content="#!/usr/bin/env python3\n")

# Insert after line 5
_drive_insert(
    file_path="data.txt",
    line=6,
    content="New line inserted here\n"
)

# Add section header
_drive_insert(
    file_path="readme.md",
    line=10,
    content="## New Section\nDescription here\n"
)

5. Delete (_drive_delete)

Purpose: Delete files or directories

Parameters:

file_path (string, required): Path to file or directory to delete

Behavior:

Files: Deleted immediately
Directories: Recursively deletes all contents
Permanent for agent: Agent cannot recover deleted items

Examples:

# Delete single file
_drive_delete(file_path="old_notes.txt")

# Delete entire directory and all contents
_drive_delete(file_path="old_data")

# Delete nested file
_drive_delete(file_path="archive/2023/report.pdf")

6. Rename (_drive_rename)

Purpose: Rename files/directories or move them to different locations

Parameters:

old_path (string, required): Current path of the file or directory
new_path (string, required): New path (can be in a different directory)

Behavior:

Can rename in place: notes.txt → readme.txt
Can move to different directory: notes.txt → docs/notes.txt
Can move and rename: old/file.txt → new/renamed.txt
Automatically creates parent directories if needed

Examples:

# Simple rename
_drive_rename(old_path="notes.txt", new_path="readme.txt")

# Move to different directory
_drive_rename(old_path="report.pdf", new_path="archive/report.pdf")

# Move and rename
_drive_rename(old_path="temp/data.csv", new_path="processed/clean_data.csv")

# Rename directory
_drive_rename(old_path="old_folder", new_path="new_folder")

7. Upload from URL (_drive_upload_from_url)

Purpose: Download files from internet URLs and save to Drive storage

Parameters:

url (string, required): HTTP/HTTPS URL to download from
file_path (string, required): Where to save the downloaded file in Drive
replace (boolean, optional, default: False): Allow overwriting existing files

Behavior:

Supports HTTP and HTTPS URLs only
SSRF Prevention: Blocks private IP addresses and localhost
Maximum download timeout: 60 seconds
Preserves original MIME type from download
Fails if file exists and replace=False

Examples:

# Download CSV dataset
_drive_upload_from_url(
    url="https://example.com/data.csv",
    file_path="datasets/raw_data.csv"
)

# Download image
_drive_upload_from_url(
    url="https://example.com/logo.png",
    file_path="images/logo.png"
)

# Download and overwrite
_drive_upload_from_url(
    url="https://api.example.com/latest.json",
    file_path="cache/api_response.json",
    replace=True
)

# Download PDF report
_drive_upload_from_url(
    url="https://example.com/report.pdf",
    file_path="reports/monthly.pdf"
)

📋 Typical Agent Workflows

Workflow 1: Data Processing Pipeline

1. Download dataset from URL
   _drive_upload_from_url(url="https://...", file_path="data/raw.csv")

2. View dataset to understand structure
   _drive_view(file_path="data/raw.csv", start_line=1, end_line=10)

3. Process data (using code execution tools)
   _code_upload_to_session(uri="pmlfs://project_id/data/raw.csv")
   _code_execute_python(code="import pandas as pd; df = pd.read_csv('raw.csv')...")

4. Save processed results back to Drive
   _code_download_from_session(sandbox_path="processed.csv", uri="pmlfs://project_id/data/processed.csv")

5. Organize files
   _drive_rename(old_path="data/raw.csv", new_path="archive/raw_2024.csv")

Workflow 2: Configuration Management

1. Create initial configuration
   _drive_create(file_path="config.json", content='{"setting": "value"}')

2. Read configuration
   _drive_view(file_path="config.json")

3. Update specific setting
   _drive_str_replace(
       file_path="config.json",
       old_str='"setting": "value"',
       new_str='"setting": "new_value"'
   )

4. Verify changes
   _drive_view(file_path="config.json")

Workflow 3: Report Generation

1. Create report directory structure
   _drive_create(file_path="reports/2024/summary.md", content="# Monthly Report\n")

2. Add sections incrementally
   _drive_insert(file_path="reports/2024/summary.md", line=2, content="## Executive Summary\n")
   _drive_insert(file_path="reports/2024/summary.md", line=3, content="Key findings...\n")

3. Download supporting documents
   _drive_upload_from_url(url="https://...", file_path="reports/2024/chart.png")

4. Organize final structure
   _drive_rename(old_path="reports/2024/summary.md", new_path="reports/2024/final_report.md")

🔒 Security & Best Practices

Security Features

Path Validation
- No path traversal (..) allowed
- No backslashes (Windows-style paths) allowed
- No null bytes allowed
Working Directory Isolation
- Enforces subfolder restrictions
- Prevents access outside designated directory
- Automatically prefixes all paths

Best Practices

Use Working Directories for Multi-Agent Systems

Agent 1: working_dir = "agent1-workspace"
Agent 2: working_dir = "agent2-workspace"
Agent 3: working_dir = "agent3-workspace"

Organize Files in Logical Folders

data/raw/
data/processed/
configs/
reports/
archive/

Use Descriptive File Names

 customer_data_2024_q1.csv
 api_config_production.json
L data.csv
L config.json

Leverage replace=False to Prevent Overwrites

# Fail if file exists (safe default)
_drive_create(file_path="important.csv", content=data, replace=False)

# Only use replace=True when intentional
_drive_create(file_path="cache.json", content=data, replace=True)

Handle Large Files Efficiently

# View large files in chunks
_drive_view(file_path="huge.log", start_line=1, end_line=500)
_drive_view(file_path="huge.log", start_line=501, end_line=1000)

# Binary files use download URLs (no context overflow)
_drive_view(file_path="large_video.mp4")  # Returns URL

⚠️ Important Limitations

Drive vs Code Execution Sandbox

Drive storage is completely separate from the code execution sandbox:

Feature

Drive Storage

Code Sandbox

Persistence

Permanent (until deleted)

Temporary (deleted after turn)

Access Tools

_drive_* tools

_code_* tools

File Transfer

Requires explicit upload/download

Direct file system access

Survival

Survives all sessions

Cleared every turn

To Use Drive Files in Code Execution:

# 1. Upload from Drive to sandbox
_code_upload_to_session(uri="pmlfs://project_id/data.csv")

# 2. Process in sandbox
_code_execute_python(code="import pandas as pd; df = pd.read_csv('data.csv')")

# 3. Download results back to Drive
_code_download_from_session(sandbox_path="output.csv", uri="pmlfs://project_id/results.csv")

File Size Considerations

View Tool: 500-line limit per view operation (prevents context overflow)
Binary Files: Not loaded into context; download URLs provided instead
Large Text Files: Use start_line and end_line parameters to view in chunks