AI Agent Development with Filesystem Access

AI Agent Development with Filesystem Access

An AI agent with filesystem access can read, create, modify, and organize files. This opens up a wide range of tasks: automatic document processing, log analysis, report generation, code refactoring. The key challenge is security: the agent must work strictly within an isolated directory.

Safe Filesystem Toolkit

import os
from pathlib import Path
from typing import Optional

class SafeFilesystemTool:
    """Filesystem tools with sandbox constraints"""

    def __init__(self, sandbox_dir: str):
        self.sandbox = Path(sandbox_dir).resolve()
        self.sandbox.mkdir(parents=True, exist_ok=True)

    def _safe_path(self, relative_path: str) -> Path:
        """Check that path remains inside sandbox"""
        target = (self.sandbox / relative_path).resolve()
        if not str(target).startswith(str(self.sandbox)):
            raise PermissionError(f"Access denied: {relative_path} is outside sandbox")
        return target

    def read_file(self, path: str, encoding: str = "utf-8") -> str:
        target = self._safe_path(path)
        if not target.exists():
            return f"Error: File {path} not found"
        if target.stat().st_size > 10 * 1024 * 1024:  # 10MB limit
            return f"Error: File too large (>10MB)"
        return target.read_text(encoding=encoding)

    def write_file(self, path: str, content: str) -> str:
        target = self._safe_path(path)
        target.parent.mkdir(parents=True, exist_ok=True)
        target.write_text(content, encoding="utf-8")
        return f"Successfully written {len(content)} characters to {path}"

    def list_directory(self, path: str = ".") -> str:
        target = self._safe_path(path)
        if not target.is_dir():
            return f"Error: {path} is not a directory"

        items = []
        for item in sorted(target.iterdir()):
            size = item.stat().st_size if item.is_file() else "-"
            type_char = "d" if item.is_dir() else "f"
            items.append(f"{type_char} {item.name} ({size} bytes)")

        return "\n".join(items) or "Empty directory"

    def search_files(self, pattern: str, directory: str = ".") -> str:
        target = self._safe_path(directory)
        import glob
        matches = glob.glob(str(target / "**" / pattern), recursive=True)
        relative_matches = [str(Path(m).relative_to(self.sandbox)) for m in matches[:50]]
        return "\n".join(relative_matches) or "No files found"

    def move_file(self, source: str, destination: str) -> str:
        src = self._safe_path(source)
        dst = self._safe_path(destination)
        src.rename(dst)
        return f"Moved {source} to {destination}"

Agent for Document Processing

from openai import OpenAI
import json

client = OpenAI()
fs_tool = SafeFilesystemTool(sandbox_dir="/data/agent_workspace")

# OpenAI tools definition
fs_tools = [
    {
        "type": "function",
        "function": {
            "name": "read_file",
            "description": "Read file contents",
            "parameters": {"type": "object", "properties": {
                "path": {"type": "string", "description": "Relative path to file"}
            }, "required": ["path"]}
        }
    },
    {
        "type": "function",
        "function": {
            "name": "write_file",
            "description": "Create or overwrite file",
            "parameters": {"type": "object", "properties": {
                "path": {"type": "string"},
                "content": {"type": "string"},
            }, "required": ["path", "content"]}
        }
    },
    {
        "type": "function",
        "function": {
            "name": "list_directory",
            "description": "List files in directory",
            "parameters": {"type": "object", "properties": {
                "path": {"type": "string", "default": "."}
            }}
        }
    },
    {
        "type": "function",
        "function": {
            "name": "search_files",
            "description": "Search files by pattern (glob)",
            "parameters": {"type": "object", "properties": {
                "pattern": {"type": "string", "description": "Glob pattern, e.g. *.pdf"},
                "directory": {"type": "string", "default": "."}
            }, "required": ["pattern"]}
        }
    },
]

FS_FUNCTIONS = {
    "read_file": fs_tool.read_file,
    "write_file": fs_tool.write_file,
    "list_directory": fs_tool.list_directory,
    "search_files": fs_tool.search_files,
}

Practical Case: Agent for Processing Incoming Documents

Task: automatic processing of incoming correspondence — agent scans PDF folder, extracts key information, classifies documents, creates structured registry.

Trajectory:

1. list_directory("incoming/") → finds 45 PDF files
2. Loop through files: read_file("incoming/doc_001.txt") (converted text)
3. Extracts: document type, sender, date, amount (if financial), response deadline
4. write_file("registry/2026-03-28.json", classified_data) — registry
5. move_file("incoming/doc_001.pdf", "processed/contracts/doc_001.pdf") — archive

Metrics:

• Documents processed per hour: 3–5 (manual) → 180–200 (agent)
• Classification accuracy: 91%
• Requisite extraction accuracy: 87%

Docker Sandbox for Complete Isolation

For production deployment — run agent in Docker container with limited mounting:

FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY agent.py .

# Create workspace without system directory access
RUN mkdir /workspace && chmod 755 /workspace
USER nobody
VOLUME ["/workspace"]
CMD ["python", "agent.py"]

docker run \
  -v /host/documents:/workspace/documents:ro \   # Documents - read only
  -v /host/output:/workspace/output:rw \         # Output - read-write
  --memory=512m --cpus=1 \                        # Resource limits
  document-agent

Timeline

• Develop filesystem tools with sandbox: 3–5 days
• Agent for specific workflow: 1–2 weeks
• Security testing: 3–5 days
• Total: 2–4 weeks