​
Overview

File Storage allows you to upload files to a session and download files that agents retrieve during their work. When uploading a file, it becomes available to agents in that session. When agents download files from websites, you can retrieve those files later.

File Storage is session-scoped - all agents within a session share the same S3 bucket. Files persist beyond the session lifecycle so you can retrieve downloads later.

​
How It Works

  1. Upload files → Files are stored in the session’s S3 bucket
  2. Run agents → Agents can use uploaded files and download new ones
  3. Download results → Retrieve files that agents downloaded

Agents can only see filenames of uploaded files, not their content. Use descriptive names like resume_john_doe.pdf to make sure they get the right context!

​
Basic Usage

from notte_sdk import NotteClient

client = NotteClient()
storage = client.FileStorage()

# Upload files before agent execution
upload_response = storage.upload("/path/to/document.pdf")
print(f"Upload success: {upload_response.success}")

# Create session with storage attached
with client.Session(storage=storage) as session:
    agent = client.Agent(session=session, max_steps=5)

    # Agent can now use uploaded files in web interactions
    response = agent.run(
        task="""
            Upload the PDF document to the website
            and download the cat picture from site
        """,
        url="https://notte.cc/pg/file/io"
    )

    print(f"Agent task completed: {response.success}")

# List and download files that the agent downloaded from websites
downloaded_files = storage.list(type="downloads")
for file_name in downloaded_files:
    success = storage.download(
        file_name=file_name,
        local_dir="./results" # Save to "results" folder
    )
    print(f"Downloaded {file_name}: {success}")

​
Upload Files

Upload files before running your agents:

from notte_sdk import NotteClient

client = NotteClient()
storage = client.FileStorage()

# Upload a file
response = storage.upload("/path/to/document.pdf")
print(f"Upload successful: {response.success}")

# List all uploaded files
uploaded_files = storage.list(type="uploads")
print(f"Available files for agents: {uploaded_files}")

Best Practices:

  • Use descriptive filenames (agents only see the filename)
  • Large files are supported (AWS S3 limits apply)

​
Download Files

After agents complete their work, download files they retrieved:

from notte_sdk import NotteClient

client = NotteClient()
storage = client.FileStorage()

# Assuming you have a session with storage that has completed
with client.Session(storage=storage) as session:
    # ... agent execution happens here ...
    pass

# After agent execution, download created files
downloaded_files = storage.list(type="downloads")
print(f"Files downloaded by agent: {downloaded_files}")

# Download files to a directory on your computer
download_dir = "./downloads"  # This creates a "downloads" folder in your current directory
for file_name in downloaded_files:
    try:
        success = storage.download(
            file_name=file_name,
            local_dir=download_dir,
            force=False  # Don't overwrite existing files
        )
        if success:
            print(f"Downloaded {file_name} to {download_dir}")
    except ValueError as e:
        print(f"Download failed for {file_name}: {e}")

​
File Management

# List uploaded files (available to agents)
uploaded_files = storage.list(type="uploads")

# List downloaded files (retrieved by agents from websites)
downloaded_files = storage.list(type="downloads")

​
File Persistence

  • Session Duration: Files are available throughout the session and persist after it ends
  • Agent Sharing: Multiple agents in the same session share the same storage
  • Persistence: Files remain available for download even after the session closes