How to Add Persistent Cloud Storage to SuperAGI Agents

SuperAGI is a great framework for building autonomous agents. It includes a "Resource Manager" to handle files while an agent runs. However, this internal system is mostly for temporary, local scratch space. While this works for quick tests or single runs, it creates problems in production.

The Ephemeral Storage Problem

When you deploy agents, they often run inside Docker containers or on temporary cloud instances (like AWS Lambda or ephemeral pods). When these sessions end, the local file system is wiped clean. Any reports, code, or datasets the agent made are lost unless you saved them somewhere else before the shutdown.

Collaboration Barriers

Even if your agent runs on a permanent server, sharing its output is hard. The "Resource Manager" keeps files locally, meaning a human or another agent can't easily access them without direct SSH access to the server. To share a generated PDF report with a client, you would usually need to build complex manual pipelines to move the file from the agent's disk to a public bucket. External cloud storage solves both issues by separating the data from the compute environment. When an agent saves to Fastio, the file lives independently of the agent. It gets a permanent URL, is instantly shareable, and stays safe even if the agent crashes or the container is destroyed.

Helpful references: Fastio Workspaces, Fastio Collaboration, and Fastio AI.

Fastio meets the specific needs of AI agents. It handles more than a standard S3 bucket by treating agents as first-class users. Each agent gets its own secure account, workspace, and credentials. The platform offers a dedicated AI Agent Free Tier that includes 50GB of storage and 5,000 monthly credits without requiring a credit card. This makes it a perfect sandbox for testing SuperAGI fleets without paying infrastructure costs. Key features for SuperAGI developers include:

• Persistent Storage: Files are stored securely in the cloud, so they last longer than the agent's runtime.
• Standard API: A simple REST API lets you manage files (upload, list, delete) easily.
• Human Handoff: Agents can create workspaces and transfer ownership to humans, making review workflows easier.
• Intelligence Mode: Fastio's built-in RAG automatically indexes documents, so agents can query content later without setting up a separate vector database.
• Webhooks: Trigger external workflows or notifications instantly when an agent uploads a file.

Give Your AI Agents Persistent Storage

Fastio gives teams shared workspaces, MCP tools, and searchable file context to run superagi file storage workflows with reliable agent and human handoffs.

Get Agent Storage

We will build a Custom Tool to connect SuperAGI and Fastio. SuperAGI requires a specific directory structure for its tools to load correctly. Start by creating a root directory for your toolkit, for example, fastio_toolkit. Inside this directory, create the following file structure:

fastio_toolkit/
├── __init__.py          # Marks the directory as a Python package
├── fastio_toolkit.py    # Defines the toolkit class and tool registration
├── tools/
│   ├── __init__.py
│   └── upload_file.py   # The logic for the file upload tool
└── requirements.txt     # Dependencies for your toolkit

You need to specify the dependencies your tool will use. Add requests to your requirements.txt file to enable HTTP communication with the Fastio API:

requests
superagi-tools

This structure keeps your code modular and makes it easy to add more tools (like list_files.py or delete_file.py) later on.

The main logic is in tools/upload_file.py. We will create a class that inherits from BaseTool and uses the Fastio API to upload files. You will need a Fastio API key, which you can generate in your agent's account settings on the Fastio dashboard. Here is the complete code for the upload tool:

from superagi.tools.base_tool import BaseTool
from pydantic import BaseModel, Field
from typing import Type
import requests
import os

### Define the input schema for the tool
class FastIOUploadInput(BaseModel):
    file_path: str = Field(..., description="The local path of the file to upload relative to the agent's workspace")
    file_name: str = Field(..., description="The name to save the file as in Fastio cloud storage")

### Define the tool class
class FastIOUploadTool(BaseTool):
    name: str = "FastIO Upload"
    args_schema: Type[BaseModel] = FastIOUploadInput
    description: str = "Uploads a file to Fastio cloud storage for persistent access and sharing."

def _execute(self, file_path: str, file_name: str):
        ### Retrieve the API key from the environment
        api_key = os.getenv("FASTIO_API_KEY")
        if not api_key:
            return "Error: FASTIO_API_KEY not found in environment variables."

url = "https://api.fast.io/v1/files/upload"
        headers = {"Authorization": f"Bearer {api_key}"}
        
        try:
            ### Open the file in binary mode
            with open(file_path, 'rb') as f:
                files = {'file': (file_name, f)}
                ### Send the POST request to Fastio
                response = requests.post(url, headers=headers, files=files)
                
            if response.status_code == 200:
                data = response.json()
                ### Return the public URL for the agent to use
                return f"File uploaded successfully. Public URL: {data.get('url')}"
            else:
                return f"Upload failed with status {response.status_code}: {response.text}"
        except FileNotFoundError:
            return f"Error: The file '{file_path}' was not found locally."
        except Exception as e:
            return f"Error uploading file: {str(e)}"

This tool takes a local file path, sends it to Fastio, and returns the URL. The agent can then use this URL later, such as sending it to a user via email or passing it to another tool.

To help your agent know what it has stored, it's useful to add a tool that lists files in the cloud. Create a new file tools/list_files.py:

from superagi.tools.base_tool import BaseTool
from pydantic import BaseModel
from typing import Type, Optional
import requests
import os

class FastIOListInput(BaseModel):
    folder_path: Optional[str] = Field("/", description="The folder path to list (defaults to root)")

class FastIOListTool(BaseTool):
    name: str = "FastIO List Files"
    args_schema: Type[BaseModel] = FastIOListInput
    description: str = "Lists files and folders in Fastio cloud storage."

def _execute(self, folder_path: str = "/"):
        api_key = os.getenv("FASTIO_API_KEY")
        url = "https://api.fast.io/v1/files/list"
        headers = {"Authorization": f"Bearer {api_key}"}
        params = {"path": folder_path}

try:
            response = requests.get(url, headers=headers, params=params)
            if response.status_code == 200:
                items = response.json().get('items', [])
                ### Format the output for the agent
                file_list = [f"{item['type']}: {item['name']}" for item in items]
                return "
".join(file_list) if file_list else "Folder is empty."
            return f"Error listing files: {response.text}"
        except Exception as e:
            return f"Error: {str(e)}"

This allows your agent to "see" its long-term memory. It can check if a file already exists before creating a new one, or find a dataset uploaded by a previous run.

Now, register both tools in your toolkit definition file fastio_toolkit.py. This class tells SuperAGI which tools belong to this package and what environment variables they need.

from superagi.tools.base_tool import BaseToolkit, BaseTool
from typing import Type, List
from fastio_toolkit.tools.upload_file import FastIOUploadTool
from fastio_toolkit.tools.list_files import FastIOListTool # Import the new tool

class FastIOToolkit(BaseToolkit):
    name: str = "FastIO Toolkit"
    description: str = "Toolkit for persistent file storage using Fastio"

def get_tools(self) -> List[BaseTool]:
        ### Register both tools here
        return [FastIOUploadTool(), FastIOListTool()]

def get_env_keys(self) -> List[str]:
        ### Define required environment variables
        return ["FASTIO_API_KEY"]

By defining get_env_keys, you ensure that SuperAGI prompts the user (or checks the environment) for the FASTIO_API_KEY when this toolkit is initialized.

With the code in place, the final step is to activate the toolkit within your SuperAGI instance.

Local Installation: If you are running SuperAGI locally, make sure your new fastio_toolkit folder is in the python path or installed as a package. You can often add the path to your config.yaml or mount the volume in Docker. 2.

Dashboard Configuration: * Go to the Toolkits section in the SuperAGI dashboard. * Click Add Custom Tool. * Link it to the GitHub repository where you pushed your toolkit code. 3.

Agent Configuration: * Create a new Agent or edit an existing one. * In the "Tools" selection step, enable FastIO Toolkit. * In the environment variables section, add your FASTIO_API_KEY (starts with sk_...). Once configured, your agent is ready. You can give it natural language instructions like: "Analyze the quarterly data, generate a summary PDF, and upload the final report to Fastio."

Adding persistent storage opens up new ways for your autonomous agents to work. Here are two advanced patterns you can try:

Multi-Agent Handoffs

In complex systems, you often have specialized agents (e.g., a "Researcher" and a "Writer"). Without shared storage, passing large datasets between them is hard. With Fastio, the "Researcher" agent can upload raw data to a shared folder, and the "Writer" agent can read that file using the FastIOListTool and download it. This allows agents to run separately and even on different servers.

Human-in-the-Loop Review

Agents often produce work that requires human approval. Instead of the agent outputting text to a console log, it can upload a draft to a specific "For Review" folder in Fastio. Because Fastio workspaces can be shared with humans, you get an instant notification. You can review the file, make edits, or approve it. The agent can be programmed to wait for a "status" file to change (e.g., approved.txt) before proceeding to the next step, creating a smooth collaborative loop between human and AI.