How to Add File Storage to Smolagents

Smolagents is a lightweight library from Hugging Face that focuses on logic and code rather than complex infrastructure. But in the real world, agents need to handle files that last longer than a single script execution. Without external storage, an agent that makes a chart or writes a report has nowhere to put it except the local disk. This is a problem in production because local disks are usually temporary (like in a Docker container or a serverless function) and users can't easily reach those files anyway. If the container restarts, that data is gone. You've wasted tokens and time, and debugging becomes a nightmare because you can't see the intermediate files or logs the agent made before it crashed or finished. Adding a cloud storage layer lets your agents:

• Save artifacts: Keep images, CSVs, and reports in a cloud space that stays alive even if the agent container stops.
• Share with humans: Give users a link they can actually click, rather than a local file path they can't reach.
• Work together: Let multiple agents read and write to the same shared folder so they can pass data back and forth and keep track of project state.

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

The easiest way to add storage is via the Model Context Protocol (MCP). Smolagents supports MCP, so you can use pre-built tool servers without writing new code. Fastio hosts an MCP server with 19 named-mode tools, including storage, upload, download, find, and ai.

Prerequisites:

1. A Fastio account and an API key from Settings > Devices & Agents > API Keys. 2. The smolagents Python library installed. Point the agent at Streamable HTTP https://mcp.fast.io/mcp/key with Authorization: Bearer {api_key} (legacy SSE is at https://mcp.fast.io/sse). POST JSON-RPC tools/call payloads from a @tool wrapper.

from smolagents import CodeAgent, HfApiModel, tool
import requests

MCP_URL = "https://mcp.fast.io/mcp/key"
HEADERS = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
}

@tool
def list_workspace(workspace_id: str) -> str:
    """List files in a Fastio workspace."""
    payload = {
        "jsonrpc": "2.0",
        "id": 1,
        "method": "tools/call",
        "params": {
            "name": "storage",
            "arguments": {
                "action": "list",
                "profile_type": "workspace",
                "profile_id": workspace_id,
            },
        },
    }
    response = requests.post(MCP_URL, headers=HEADERS, json=payload)
    return response.text

@tool
def import_file(url: str, workspace_id: str) -> str:
    """Import a file from a URL into the Fastio workspace."""
    payload = {
        "jsonrpc": "2.0",
        "id": 1,
        "method": "tools/call",
        "params": {
            "name": "upload",
            "arguments": {
                "action": "web-import",
                "url": url,
                "profile_type": "workspace",
                "profile_id": workspace_id,
            },
        },
    }
    response = requests.post(MCP_URL, headers=HEADERS, json=payload)
    return response.text

agent = CodeAgent(
    tools=[list_workspace, import_file],
    model=HfApiModel()
)

agent.run(
    "Import https://example.com/sales.csv into workspace 1234567890123456789 and list the files"
)

In this setup, the agent lists the workspace with MCP storage (list) and imports a file with MCP upload (web-import). The files show up in your web dashboard. For a local artifact the agent just wrote, stage the bytes at the MCP POST /blob sidecar (100 MB cap, five-minute expiry, single use), then pass the returned blob_id to upload. This approach means you don't have to write boilerplate code for S3 buckets, IAM roles, or local folders. The MCP server handles the communication between the agent and the storage, so you can scale across different environments without making the codebase messy.

Give Your AI Agents Persistent Storage

Stop losing agent artifacts. Connect your smolagents to persistent cloud storage with built-in RAG and sharing.

Get Agent Storage

If you want more control or want to limit the agent to specific actions (like "save only"), wrap a single Fastio MCP tool. This is useful if you need to add custom logic, like checking a file's format before importing. You can also add your own error handling, then hand the result to teammates through a branded Send, Receive, or Exchange share. Confirm the write in the workspace activity log.

from smolagents import tool, CodeAgent, HfApiModel
import requests

MCP_URL = "https://mcp.fast.io/mcp/key"
HEADERS = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
}

@tool
def save_artifact(source_url: str) -> str:
    """
    Imports a file from a URL into cloud storage.
    Args:
        source_url: Public URL of the file (e.g., https://example.com/report.md)
    """
    payload = {
        "jsonrpc": "2.0",
        "id": 1,
        "method": "tools/call",
        "params": {
            "name": "upload",
            "arguments": {
                "action": "web-import",
                "url": source_url,
                "profile_type": "workspace",
                "profile_id": "1234567890123456789",
            },
        },
    }
    response = requests.post(MCP_URL, headers=HEADERS, json=payload)
    return response.text

agent = CodeAgent(tools=[save_artifact], model=HfApiModel())

Storage isn't just about saving output; it's about reading input. When you connect smolagents to a Fastio workspace with Intelligence Mode enabled, Ripley (the built-in RAG agent) becomes part of the workflow. Instead of just reading raw bytes, your agent can ask questions about the files. This is helpful when dealing with large datasets or long documents that are too big for the model's context window. This "chat with your files" capability means the agent only grabs the info it needs for the current task.

How it works:

1. Auto-Indexing: Any file uploaded to the workspace (PDFs, docs, spreadsheets) is automatically indexed.

Semantic Search: The agent calls MCP ai with action ask for a cited answer, or MCP find to search across the workspace. 3.

Citation: Ripley returns a cited answer, so the agent can show where it got its information. This gives your agent long-term memory without a separate vector database like Pinecone. The storage handles the indexing, which keeps your setup simple and costs down for your team.

The right storage depends on where you're deploying your agent.

For local prototypes, the filesystem works fine. For production agents that need to work with humans or other agents, a cloud storage service designed for agents is usually the easiest way to go.