How to Run an AI S3 File Storage Agent with OE Runtime

Audit, analyse, and manage your S3-compatible storage with AI. OE Runtime connects to any S3 bucket, inventories your files, identifies the largest objects, and recommends cleanup and archiving actions — all locally, no third-party tool required.

The Agent YAML

Create a file called agent.yaml inside a file-storage/ directory:

name: File Storage Agent
description: Upload, list, download, and manage files in S3-compatible storage
instructions: |
  You are a file management agent with access to S3-compatible storage.
  List, inspect, and report on stored files. Confirm before any delete operations.
  Complete all steps fully before writing your report.
steps:
  - name: List Bucket Contents
    content: |
      List all files in the configured S3 bucket.
      For each file note: key (path), size in KB/MB, last modified date, and storage class.
  - name: Analyze Storage
    content: |
      From the listed files:
      - Calculate total storage used
      - Identify the 5 largest files
      - Group files by extension type (images, documents, archives, other)
      - Flag any files older than 90 days that may be candidates for archiving
  - name: Report
    content: |
      Produce a storage summary:
      - Total files and total size
      - Breakdown by file type
      - Top 5 largest files
      - Files flagged for archiving
      - Recommended cleanup or archiving actions
connectors:
  - connection_name: My S3 Bucket
    connection_type: s3

The Config File

Create oe-config.json in the same directory:

{
  "llm": {
    "provider": "openai",
    "model": "gpt-4o",
    "apiKey": "YOUR_OPENAI_API_KEY"
  },
  "server": {
    "enabled": false,
    "port": 3333,
    "apiKey": "your-secret-api-key"
  },
  "connectors": [
    {
      "connection_name": "My S3 Bucket",
      "connection_type": "s3",
      "accessKeyId": "YOUR_AWS_ACCESS_KEY",
      "secretAccessKey": "YOUR_AWS_SECRET_KEY",
      "region": "us-east-1",
      "bucket": "my-bucket"
    }
  ]
}

Create an IAM user with AmazonS3ReadOnlyAccess (or scoped bucket permissions) and generate an access key at console.aws.amazon.com/iam. The agent works with any S3-compatible storage including MinIO, Backblaze B2, and Cloudflare R2 — just update the endpoint URL.

Download OE Runtime

Run the Agent

Windows

# Run the agent
oe-runtime-win.exe file-storage/agent.yaml --config file-storage/oe-config.json

macOS

# Make executable (first time only)
chmod +x oe-runtime-macos

# Run the agent
oe-runtime-macos file-storage/agent.yaml --config file-storage/oe-config.json

Linux

# Make executable (first time only)
chmod +x oe-runtime-linux

# Run the agent
oe-runtime-linux file-storage/agent.yaml --config file-storage/oe-config.json

Running as an API Server

Add --serve to start OE Runtime as an HTTP server on port 3333:

oe-runtime-win.exe --serve --config file-storage/oe-config.json

Then send a request:

curl -X POST http://localhost:3333/run \
  -H "Content-Type: application/json" \
  -d '{"yaml": "file-storage/agent.yaml", "params": {}}'

Or import the Postman collection (download above) to test all endpoints visually.

Use Cases

• Storage cost auditing — Identify which files are consuming the most storage in your S3 bucket and whether they are in the correct storage class. Files that have not been accessed in over 90 days are prime candidates for moving to S3 Glacier or Intelligent-Tiering to reduce costs significantly.
• Backup verification — Confirm that expected backup files are present in a designated S3 folder and that they are recent enough to meet your recovery point objectives. The agent flags missing or outdated backups so you can address gaps before they become a recovery risk.
• Media asset management — Inventory a bucket containing images, videos, or audio files to understand what assets exist, their sizes, and when they were uploaded. Useful for content teams managing large libraries without a dedicated DAM system.
• Data pipeline monitoring — Monitor an S3 bucket used as a staging area in your data pipeline to ensure files are arriving on schedule and being processed correctly. The agent can flag files that have been sitting in the bucket for longer than expected, indicating a downstream processing failure.
• Compliance and data retention — Audit S3 buckets to identify files that should have been deleted under your data retention policy but are still present. The agent produces a report of files older than a specified threshold so your compliance team can action deletions with confidence.
• Multi-bucket comparison — Compare the contents of two S3 buckets — for example a source and a replication target — to verify that all files are present and up to date in both locations. Useful for validating cross-region replication configurations.
• Log file analysis preparation — List and categorise application log files stored in S3 before running analysis queries. The agent can identify which log files are relevant to a specific date range or service and prepare a manifest for downstream processing.
• Orphaned file cleanup — Identify files in S3 that are no longer referenced by your application database or CDN configuration. The agent compares the bucket contents against a known list of active assets and flags any objects that appear to be orphaned and safe to delete.