# File Storage

## Overview <a href="#overview" id="overview"></a>

File Storage allows you to upload files to a session and download files that agents retrieve during their tasks. Uploaded files become available to agents in that session. When agents download files from websites, you can access them later.

File Storage is session-scoped—agents within the same session share the same storage bucket. Files persist beyond the session lifecycle, so downloads can be retrieved afterwards.

## ​How It Works <a href="#how-it-works" id="how-it-works"></a>

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 <a href="#basic-usage" id="basic-usage"></a>

```python
from lumiteh_sdk import LumiTehClient

client = LumiTehClient()
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://lumiteh.io/pg/file/io"
    )

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

# List and download files that the agent downloaded from websites
downloaded_files = storage.list_downloaded_files()
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 <a href="#upload-files" id="upload-files"></a>

Upload files before running your agents

```python
from lumiteh_sdk import LumiTehClient

client = LumiTehClient()
storage = client.FileStorage()

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

# List all uploaded files
uploaded_files = storage.list_uploaded_files()
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 <a href="#download-files" id="download-files"></a>

After agents complete their work, download files they retrieved

```python
from lumiteh_sdk import LumiTehClient

client = LumiTehClient()
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_downloaded_files()
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 Persistence <a href="#file-persistence" id="file-persistence"></a>

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.lumiteh.com/session-features/file-storage.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.