Skip to content
BranchesTags

Repository files navigation

Deep Agents Virtual Filesystem Example (Python)

This example demonstrates how to use Deep Agents with multiple storage backends, showcasing the power of virtual filesystems for AI agents.

Overview

The agent acts as a sales assistant that can:

  • Read company documentation from S3
  • Access customer profiles and conversation history from SQLite
  • Generate personalized proposals to the local filesystem

This AI sales assistant powered by langchain Deep Agents SDK that reads from multiple storage backends through a unified virtual filesystem.

Refactored from christian-bromann/deepagents-filesystem-example (TypeScript) to Python.

Detail explaination: The Secret to Scalable AI Agents: Virtual Filesystems with Deep Agents

Architecture

┌─────────────────────────────────────────────────────────────┐
│                      Deep Agent                             │
│                  (AI Sales Assistant)                       │
└───────────────────────┬─────────────────────────────────────┘
                        │
                        ▼
┌─────────────────────────────────────────────────────────────┐
│                   CompositeBackend                          │
│                    (Path Router)                            │
└───────────────────────┬─────────────────────────────────────┘
                        │
        ┌───────────────┼───────────────┐
        │               │               │
        ▼               ▼               ▼
┌───────────────┐ ┌───────────────┐ ┌───────────────┐
│ /docs/        │ │ /memories/    │ │ /workspace/   │
│               │ │               │ │               │
│ S3 Backend    │ │ SQLite        │ │ Filesystem    │
│               │ │ Backend       │ │ Backend       │
│               │ │               │ │               │
│ Company docs  │ │ User profiles │ │ Generated     │
│ Pricing info  │ │ Conv history  │ │ proposals     │
└───────────────┘ └───────────────┘ └───────────────┘

The agent uses a CompositeBackend to route filesystem operations to specialized backends based on path prefixes:

Path Backend Storage
/docs/ S3Backend AWS S3 / S3-compatible (company documentation)
/memories/ SQLiteBackend SQLite database (customer profiles & conversations)
/workspace/ FilesystemBackend Local filesystem (agent output)

The agent has access to filesystem tools (ls, read_file, write_file, edit_file, glob, grep) and navigates these data sources seamlessly to generate personalized sales proposals.

Seed Data

Company Documentation (./s3/)

Company Files
Acme Corp company-info.md, pricing.md, integrations.md
Nexus Health company-info.md, pricing.md, compliance.md
GreenLeaf Analytics company-info.md, pricing.md
EduTech Pro company-info.md, pricing.md

Customer Data (SQLite Database)

Customer data is stored in a proper relational database with users and conversations tables. The SQLiteBackend synthesizes a virtual filesystem from the database:

Customer Role Company Industry Conversations
Sarah Chen Engineering Manager TechStartup Inc SaaS 4
Marcus Johnson CTO City General Hospital Healthcare 4
Elena Rodriguez Sustainability Director SustainableCo Manufacturing 4
David Kim Director of Online Learning West Coast CC Education 4
Priya Sharma VP of Engineering FinTech Innovations Finance 5

Virtual file mapping:

  • /memories/users/{name}.json → Generated from users table
  • /memories/history/{name}.md → Generated from conversations table

Prerequisites

  • Python 3.13+
  • uv package manager
  • AWS S3 bucket (or S3-compatible storage like MinIO)
  • Anthropic API key or OpenAI API key (or any OpenAI-compatible endpoint)

Environment Variables

Create a .env file:

ANTHROPIC_API_KEY=your-anthropic-key

# S3 Configuration
AWS_S3_ENDPOINT=https://s3.us-west-2.amazonaws.com
AWS_S3_BUCKET=your-bucket-name
AWS_ACCESS_KEY_ID=your-access-key
AWS_SECRET_ACCESS_KEY=your-secret-key
Variable Description
MODEL Model spec in provider:model format (default: anthropic:claude-sonnet-4-6)
ANTHROPIC_API_KEY Anthropic API key (required for anthropic: models)
OPENAI_API_KEY OpenAI API key (required for openai: models)
OPENAI_BASE_URL Custom base URL for OpenAI-compatible APIs (optional)
AWS_S3_BUCKET S3 bucket name
AWS_S3_ENDPOINT S3 endpoint URL (for MinIO: http://localhost:9000)
AWS_ACCESS_KEY_ID AWS / MinIO access key
AWS_SECRET_ACCESS_KEY AWS / MinIO secret key
AWS_DEFAULT_REGION AWS region (default: us-west-2)
AWS_S3_FORCE_PATH_STYLE Set true for MinIO / path-style S3 endpoints

Supported Model Providers

Provider MODEL example Requirements
Anthropic anthropic:claude-sonnet-4-6 ANTHROPIC_API_KEY
OpenAI openai:gpt-4o OPENAI_API_KEY
Ollama openai:llama3 OPENAI_API_KEY=ollama, OPENAI_BASE_URL=http://localhost:11434/v1
vLLM openai:my-model OPENAI_API_KEY, OPENAI_BASE_URL=http://localhost:8000/v1
LiteLLM openai:my-model OPENAI_API_KEY, OPENAI_BASE_URL=http://localhost:4000/v1

Quick Start (with MinIO)

The easiest way to get started is with the included MinIO setup:

# 1. Start MinIO (S3-compatible storage)
docker compose up -d

# 2. Install dependencies
uv sync
source .venv/bin/activate

# 3. Configure environment
cp .env.example .env
# Edit .env: set your ANTHROPIC_API_KEY (MinIO defaults are pre-configured)

# 4. Seed data and run
python seed.py

# 5. There are two way to run this agent

# 5.1 Simple way (just run one-time and check the result in "worksapce/" folder)
python main.py

# 5.2 Via Agent Terminal UI (you can ask more question interactively)
python agent_cli.py

MinIO console is available at http://localhost:9001 (login: minioadmin/minioadmin).

Setup (AWS S3)

uv sync
source .venv/bin/activate

cp .env.example .env
# Edit .env: set API keys and AWS S3 configuration

Usage

# 1. Seed the data (S3 + SQLite)
python seed.py

# 2. Run the agent (uses MODEL from .env, default: anthropic:claude-sonnet-4-6)
python main.py

# Or specify a model inline:
MODEL=openai:gpt-4o python main.py

# Use an OpenAI-compatible endpoint (Ollama, vLLM, LiteLLM, etc.):
MODEL=openai:llama3 OPENAI_BASE_URL=http://localhost:11434/v1 OPENAI_API_KEY=ollama python main.py

The agent will:

  1. Explore available data in /docs/ and /memories/
  2. Read the customer profile and conversation history
  3. Find matching company documentation
  4. Generate a personalized sales proposal
  5. Write the output to /workspace/

Project Structure

.
├── main.py                  # Agent entry point
├── agent_cli.py             # Agent entry point via terminal UI
├── seed.py                  # Seed data initialization
├── backends/
│   ├── sqlite_backend.py    # SQLite -> virtual filesystem backend
│   └── s3_backend.py        # S3 object storage backend
├── s3/                      # Seed data: company docs (uploaded to S3)
│   ├── acme-corp/
│   ├── nexus-health/
│   ├── greenleaf-analytics/
│   └── edutech-pro/
├── data/                    # SQLite database (created by seed.py)
├── workspace/               # Agent output directory
├── docker-compose.yml       # MinIO (S3-compatible) local setup
├── pyproject.toml
├── .env.example
├── CLAUDE.md                # Project architecture details
└── PLAN.md                  # Refactor implementation plan

Custom Backends

Both custom backends implement the BackendProtocol interface from deepagents:

  • SQLiteBackend - Maps SQLite tables to virtual files: /users/{slug}.json and /history/{slug}.md. Read-only for the agent; data is populated via seed.py.
  • S3Backend - Full read/write access to S3-compatible object storage using boto3.

Customization

Add a New Company

  1. Create a folder in ./s3/your-company/
  2. Add markdown files (company-info.md, pricing.md, etc.)
  3. Run python seed.py

Add a New Customer

Add a new user object to the USERS array in seed.py:

{
  "slug": "new-customer",
  "name": "New Customer",
  "email": "new@example.com",
  "role": "CTO",
  "company": "Example Corp",
  "industry": "Tech",
  "team_size": 20,
  "interests": ["automation"],
  "current_tools": ["GitHub"],
  "budget": "enterprise",
  "decision_timeline": "Q1 2025",
  "requirements": null,
  "conversations": [
    {
      "date": "2024-03-01",
      "title": "Initial Call",
      "notes": ["Discussed requirements", "Very interested"],
    },
  ],
}

Then run python seed.py.

License

MIT

About

Deep Agents example showcasing virtual filesystem backends

Resources

Readme
MIT license
Activity

Stars

2 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages