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 stays in a shared workspace, is available to people and other agents, 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. Agents join the same workspaces people use, and you issue them credentials from Settings > Devices & Agents > API Keys. For SuperAGI, connect through the official Fastio MCP server rather than wrapping raw HTTP yourself. Point the client at https://mcp.fast.io/mcp (use https://mcp.fast.io/mcp/key when the client sends a Bearer token) and invoke tools with JSON-RPC tools/call.

Key features for SuperAGI developers include:

• Persistent Storage: Files live in a Fastio workspace, so they last longer than the agent's runtime.
• MCP tools: Named tools such as upload, storage, find, and ai let SuperAGI import files, list folders, search, and ask Ripley (the built-in RAG agent) for cited answers from workspace documents.
• Human Handoff: Agents can place files in a workspace, invite people as members, or create a Send, Receive, or Exchange share so a human can open the output in a branded portal.
• Workspace Intelligence: Fastio indexes documents in the workspace, so agents can query that content later through Ripley without standing up a separate vector database.
• Audit logs: Workspace activity is recorded, so you can see what an agent stored and when.

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 so the toolkit can POST JSON-RPC calls to the Fastio MCP server:

requests
superagi-tools

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

The main logic is in tools/upload_file.py. Create a class that inherits from BaseTool and calls the Fastio MCP upload tool. Generate an API key in Settings > Devices & Agents > API Keys, and keep the workspace id (a 19-digit profile id) in the environment. The sample below uses the verified web-import action, which pulls a file from an HTTPS URL into the workspace.

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

class FastIOUploadInput(BaseModel):
    source_url: str = Field(..., description="HTTPS URL of the file to import into the Fastio workspace")

class FastIOUploadTool(BaseTool):
    name: str = "FastIO Upload"
    args_schema: Type[BaseModel] = FastIOUploadInput
    description: str = "Imports a file from a URL into Fastio workspace storage through the MCP upload tool."

def _execute(self, source_url: str):
        api_key = os.getenv("FASTIO_API_KEY")
        workspace_id = os.getenv("FASTIO_WORKSPACE_ID")
        if not api_key:
            return "Error: FASTIO_API_KEY not found in environment variables."
        if not workspace_id:
            return "Error: FASTIO_WORKSPACE_ID not found in environment variables."

payload = {
            "jsonrpc": "2.0",
            "id": 1,
            "method": "tools/call",
            "params": {
                "name": "upload",
                "arguments": {
                    "action": "web-import",
                    "url": source_url,
                    "profile_type": "workspace",
                    "profile_id": workspace_id,
                },
            },
        }
        headers = {"Authorization": f"Bearer {api_key}"}

try:
            response = requests.post(
                "https://mcp.fast.io/mcp/key",
                headers=headers,
                json=payload,
            )
            return response.text
        except Exception as e:
            return f"Error importing file: {str(e)}"

This tool sends a tools/call to the MCP upload tool and returns the server response. The agent can then list the workspace, create a Send, Receive, or Exchange share for a human, or ask Ripley about the new document. For large local binaries, stage the bytes with the MCP blob sidecar (100 MB cap, five-minute expiry, single use), then pass the returned blob_id to upload.

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

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

class FastIOListInput(BaseModel):
    pass

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

def _execute(self):
        api_key = os.getenv("FASTIO_API_KEY")
        workspace_id = os.getenv("FASTIO_WORKSPACE_ID")
        if not api_key:
            return "Error: FASTIO_API_KEY not found in environment variables."
        if not workspace_id:
            return "Error: FASTIO_WORKSPACE_ID not found in environment variables."

payload = {
            "jsonrpc": "2.0",
            "id": 1,
            "method": "tools/call",
            "params": {
                "name": "storage",
                "arguments": {
                    "action": "list",
                    "profile_type": "workspace",
                    "profile_id": workspace_id,
                },
            },
        }
        headers = {"Authorization": f"Bearer {api_key}"}

try:
            response = requests.post(
                "https://mcp.fast.io/mcp/key",
                headers=headers,
                json=payload,
            )
            return response.text
        except Exception as e:
            return f"Error: {str(e)}"

This lets your agent see its long-term memory. It can check what is already in the workspace before importing another file, or find a dataset stored by a previous run. The storage tool also supports search, details, move, copy, and delete when you need those actions later.

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 List
from fastio_toolkit.tools.upload_file import FastIOUploadTool
from fastio_toolkit.tools.list_files import FastIOListTool

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

def get_tools(self) -> List[BaseTool]:
        return [FastIOUploadTool(), FastIOListTool()]

def get_env_keys(self) -> List[str]:
        return ["FASTIO_API_KEY", "FASTIO_WORKSPACE_ID"]

By defining get_env_keys, you ensure that SuperAGI prompts the user (or checks the environment) for the API key and workspace id when this toolkit is initialized.

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

1. 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 and the FASTIO_WORKSPACE_ID for the workspace the agent should use.

Once configured, your agent is ready. You can give it natural language instructions like: "Analyze the quarterly data at this URL, import the source file into Fastio, and summarize what is already in the workspace."

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 (for example, a Researcher and a Writer). Without shared storage, passing large datasets between them is hard. With Fastio, the Researcher agent can import raw data into a shared workspace with the MCP upload tool. The Writer agent can list that workspace with the storage tool and ask Ripley about the files with the ai tool (ask). The agents can run separately, even on different servers, and still share one workspace.

Human-in-the-Loop Review

Agents often produce work that a person should read before anything is sent to a client. Instead of leaving a draft only in a console log, the agent can import the draft into a shared workspace, invite the reviewer as a member, or create a Send, Receive, or Exchange share. The reviewer opens the file in the workspace or branded portal, edits it, or adds a follow-up note. The agent can list the folder again or read the note (workspace actions create-note, read-note, update-note) before it continues.