How to Add File Storage to OpenAI Agents SDK Projects

OpenAI released the Agents SDK as the production successor to Swarm. It keeps Swarm's lightweight design (agents, tools, handoffs) and adds guardrails, tracing, and multi-model support. If you've worked with Swarm before, the upgrade is smooth. The SDK handles orchestration well. You define agents with instructions and tools, wire up handoffs between them, and the framework manages the execution loop. But it deliberately leaves infrastructure concerns to you, and file storage is one of them. Here's what the SDK provides out of the box:

• Function tools: Wrap any Python function as an agent tool with automatic schema generation
• Hosted tools: FileSearchTool (vector stores), CodeInterpreterTool (sandboxed execution), WebSearchTool
• Handoffs: Transfer control between specialized agents
• Guardrails: Input and output validation
• Tracing: Built-in observability for debugging agent runs
• Sessions: SQLite-backed conversation persistence (added in later releases)

Notice what's missing: persistent file storage. The SDK's FileSearchTool queries OpenAI's vector stores, which are designed for RAG retrieval, not general-purpose file management. There's no built-in way for an agent to save a report, store processed data, or maintain a library of working documents between sessions. This gap shows up the moment you build anything beyond a chatbot. Research agents need to save findings. Data processing agents produce output files. Multi-agent systems need a shared workspace. You need external storage, and the SDK's function tool system makes it easy to add.

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

Without persistent storage, your agents are stateless workers that forget everything between runs. This limits them to single-session tasks. Consider a research agent built with the OpenAI Agents SDK. It searches the web, analyzes documents, and produces a summary. Without file storage, that summary exists only in the conversation context. Close the session and it's gone. Run the agent again tomorrow and it starts from scratch. Persistent file storage changes what agents can do:

• Multi-session workflows: An agent generates a draft today, receives feedback tomorrow, and revises next week. Each version is stored and accessible.
• Multi-agent collaboration: Agent A produces a dataset. Agent B picks it up for analysis. Agent C formats the results. They share files through a common workspace.
• Human-agent handoffs: An agent builds a client deliverable and stores it in a shared folder. The human reviews, adds comments, and the agent incorporates feedback.
• Audit trails: Every file version is preserved. You can trace what the agent produced, when, and what changed. The OpenAI Agents SDK's session system (SQLiteSession, SQLAlchemySession) handles conversation state, but conversation state is not the same as file state. Sessions remember what was said. File storage preserves what was produced.

Give Your AI Agents Persistent Storage

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

Get started with the trial

The Agents SDK's function tool system turns any Python function into a callable tool. You write a function, add a docstring, and the SDK auto-generates the JSON schema for the LLM. For agent integrations, prefer Fastio's MCP server. Point the client at Streamable HTTP on https://mcp.fast.io/mcp, or https://mcp.fast.io/mcp/key when it sends a Bearer token. Legacy SSE is at https://mcp.fast.io/sse.

A tools/call that imports a source document into the workspace looks like this:

{"jsonrpc":"2.0","id":1,"method":"tools/call",
 "params":{"name":"upload","arguments":{"action":"web-import","url":"https://example.com/report.pdf",
 "profile_type":"workspace","profile_id":"1234567890123456789"}}}

You can wrap that same MCP call (and the documented REST routes for writing and reading bytes) as custom function tools.

Step 1: Define the Storage Functions

Start with the core operations your agents need. At minimum: upload, download, and list files.

import os
import httpx
from agents import Agent, function_tool

FASTIO_TOKEN = os.environ["FASTIO_API_KEY"]
WORKSPACE_ID = os.environ["FASTIO_WORKSPACE_ID"]
AUTH = {"Authorization": f"Bearer {FASTIO_TOKEN}"}
MCP_URL = "https://mcp.fast.io/mcp/key"

@function_tool
def upload_file(filename: str, content: str) -> str:
    """Upload a text file to the agent's workspace."""
    data = content.encode("utf-8")
    response = httpx.post(
        "https://api.fast.io/current/upload/",
        headers=AUTH,
        data={
            "name": filename,
            "size": str(len(data)),
            "action": "create",
            "instance_id": WORKSPACE_ID,
            "folder_id": "root",
        },
        files={"chunk": data},
    )
    return response.text

@function_tool
def list_files() -> str:
    """List files in the agent's workspace."""
    payload = {
        "jsonrpc": "2.0",
        "id": 1,
        "method": "tools/call",
        "params": {
            "name": "storage",
            "arguments": {
                "action": "list",
                "profile_type": "workspace",
                "profile_id": WORKSPACE_ID,
            },
        },
    }
    response = httpx.post(
        MCP_URL,
        headers={**AUTH, "Content-Type": "application/json"},
        json=payload,
    )
    return response.text

@function_tool
def download_file(node_id: str) -> str:
    """Read a file from the workspace by node ID."""
    response = httpx.get(
        f"https://api.fast.io/current/workspace/{WORKSPACE_ID}/storage/{node_id}/read/",
        headers=AUTH,
    )
    return response.text

Step 2: Attach Tools to Your Agent

Wire the storage functions into your agent definition:

research_agent = Agent(
    name="Research Agent",
    instructions="""You are a research agent with file storage. Save your findings using upload_file. Check for previous work using list_files before starting. Resume from stored files using download_file.""",
    tools=[upload_file, list_files, download_file]
)

Step 3: Run with Persistence

Now your agent can store and retrieve files across sessions:

from agents import Runner

### Session 1: Agent does research and saves results
result = await Runner.run(
    research_agent,
    "Research cloud storage pricing and save a report"
)

### Session 2: Agent picks up where it left off
result = await Runner.run(
    research_agent,
    "Review your previous research and add competitor data"
)

The agent checks its workspace at the start of session 2, finds the report from session 1, and continues building on it.

The OpenAI Agents SDK's handoff system lets agents transfer control to specialized peers. When you combine handoffs with shared file storage, agents can pass work products along a pipeline. Here's a practical pattern: a research agent gathers data, hands off to an analysis agent, which hands off to a report writer.

from agents import Agent, function_tool, handoff

### All agents share the same workspace
shared_tools = [upload_file, list_files, download_file]

researcher = Agent(
    name="Researcher",
    instructions="""Gather information on the assigned topic. Save raw findings as 'research-notes.md' in the workspace. When done, hand off to the Analyst.""",
    tools=shared_tools,
    handoffs=[handoff(target="analyst")]
)

analyst = Agent(
    name="Analyst",
    instructions="""Read 'research-notes.md' from the workspace. Analyze the data and save 'analysis.md'. Hand off to the Writer when analysis is complete.""",
    tools=shared_tools,
    handoffs=[handoff(target="writer")]
)

writer = Agent(
    name="Writer",
    instructions="""Read 'analysis.md' from the workspace. Write a polished report and save as 'final-report.md'.""",
    tools=shared_tools
)

Each agent reads the previous agent's output from the shared workspace. The files persist regardless of which agent is active. This pattern works because:

• Files outlive sessions: Even if the pipeline crashes mid-run, completed work is preserved
• Agents can retry: If the analyst produces a poor analysis, you can re-run just that step without losing the researcher's work
• Humans can intervene: A human can review files between handoffs and provide guidance before the next agent runs
• Everything is auditable: The workspace contains a complete record of the pipeline's output at each stage

If your setup supports MCP (Model Context Protocol), you can skip writing custom HTTP tools. Fastio's MCP server exposes 19 named-mode tools (auth, user, org, workspace, share, fileshare, storage, metadata, find, upload, download, ai, comment, event, room, member, invitation, asset, how-to) that MCP-compatible agents can call directly. Point the SDK at Streamable HTTP on https://mcp.fast.io/mcp, or https://mcp.fast.io/mcp/key when the client sends a Bearer token.

from agents import Agent
from agents.mcp import MCPServerStreamableHTTP

### Connect to Fastio's MCP server
fastio_mcp = MCPServerStreamableHTTP(
    url="https://mcp.fast.io/mcp",
    name="fastio"
)

agent = Agent(
    name="File Manager",
    instructions="Manage files using the Fastio storage tools.",
    mcp_servers=[fastio_mcp]
)

With MCP, the agent gets access to file operations without you writing wrapper functions: upload (including web-import and stream-upload), storage (list, search, details), find, branded share and fileshare portals, and Ripley through the ai tool (ask).

When to Use MCP vs Custom Tools

Use MCP when:

• Your agent framework supports MCP natively
• You want the full 19-tool set without writing boilerplate
• You need operations beyond basic CRUD (search, sharing, RAG queries)

Use custom function tools when:

• You need fine-grained control over which operations are exposed
• You want to add business logic around storage calls (validation, logging)
• Your agent only needs 3-4 specific file operations
• You're working with a framework that doesn't support MCP

Before your agent can store files, it needs a Fastio account and an API key.

Create an Agent Account

Create an account, then generate an API key in Settings > Devices & Agents > API Keys, or with POST /current/user/auth/key/. Authenticated calls use Authorization: Bearer {api_key} against https://api.fast.io/current/. Keep the trailing slashes. Workspace and org IDs are 19-digit numeric strings.

Create a Workspace

Create an organization with POST /current/org/create/, then create a workspace with POST /current/org/{org_id}/create/workspace/. You can also create both from the Fastio UI.

Your agent now has persistent cloud storage. Files uploaded to this workspace survive between sessions, agent restarts, and server reboots.

Enable Intelligence Mode (Optional)

If you want your agent to query stored files using natural language, turn on Intelligence Mode with POST /current/workspace/{workspace_id}/update/.

With Intelligence Mode enabled, Fastio indexes uploaded files. Ripley, the built-in RAG agent, can then answer questions across those documents with source citations. From MCP, call the ai tool with action ask (it requires profile_type).

Storage is only half the problem. Agents produce work for people, and those people need access to the results. Fastio's sharing system lets agents create branded Send, Receive, or Exchange portals for delivering files to humans. Create a share with POST /current/workspace/{workspace_id}/create/share/. For a durable single-file link, use POST /current/workspace/{workspace_id}/create/fileshare/. Invite a teammate as a workspace member with POST /current/workspace/{workspace_id}/members/{email_or_user_id}/.

This pattern is especially useful for:

• Client deliverables: Agent researches, writes, and packages a report, then opens a branded Send portal
• Team reviews: Agent stores drafts in a workspace and invites specific team members for review
• Ownership transfer: Agent builds an entire workspace with organized folders and files, then transfers ownership to a human. The agent keeps admin access for future updates. The agent doesn't just produce files. It packages and delivers them in a format humans can actually use.