Разработка AI-агента с доступом к файловой системе

Разработка AI-агента с доступом к файловой системе

AI-агент с доступом к файловой системе может читать, создавать, изменять и организовывать файлы. Это открывает широкий класс задач: автоматическая обработка документов, анализ логов, генерация отчётов, рефакторинг кода. Ключевой вызов — безопасность: агент должен работать строго в изолированной директории.

Безопасный filesystem инструментарий

import os
from pathlib import Path
from typing import Optional

class SafeFilesystemTool:
    """Инструменты файловой системы с sandbox-ограничениями"""

    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:
        """Проверяет, что путь остаётся внутри 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 лимит
            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}"

Агент для обработки документов

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": "Прочитать содержимое файла",
            "parameters": {"type": "object", "properties": {
                "path": {"type": "string", "description": "Относительный путь к файлу"}
            }, "required": ["path"]}
        }
    },
    {
        "type": "function",
        "function": {
            "name": "write_file",
            "description": "Создать или перезаписать файл",
            "parameters": {"type": "object", "properties": {
                "path": {"type": "string"},
                "content": {"type": "string"},
            }, "required": ["path", "content"]}
        }
    },
    {
        "type": "function",
        "function": {
            "name": "list_directory",
            "description": "Список файлов в директории",
            "parameters": {"type": "object", "properties": {
                "path": {"type": "string", "default": "."}
            }}
        }
    },
    {
        "type": "function",
        "function": {
            "name": "search_files",
            "description": "Поиск файлов по паттерну (glob)",
            "parameters": {"type": "object", "properties": {
                "pattern": {"type": "string", "description": "Glob паттерн, например *.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,
}

Практический кейс: агент для обработки входящих документов

Задача: автоматическая обработка входящей корреспонденции — агент сканирует папку с PDF, извлекает ключевую информацию, классифицирует документы, создаёт структурированный реестр.

Траектория:

1. list_directory("incoming/") → находит 45 PDF файлов
2. Цикл по файлам: read_file("incoming/doc_001.txt") (конвертированный текст)
3. Извлекает: тип документа, отправитель, дата, сумма (если финансовый), срок ответа
4. write_file("registry/2026-03-28.json", classified_data) — реестр
5. move_file("incoming/doc_001.pdf", "processed/contracts/doc_001.pdf") — архивирование

Метрики:

• Документов обработано за час: 3–5 (вручную) → 180–200 (агент)
• Точность классификации: 91%
• Точность извлечения реквизитов: 87%

Docker Sandbox для полной изоляции

Для production-деплоя — запуск агента в Docker контейнере с ограниченным монтированием:

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

# Создаём workspace без прав на системные директории
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

Сроки

• Разработка filesystem инструментов с sandbox: 3–5 дней
• Агент для конкретного workflow: 1–2 недели
• Тестирование безопасности: 3–5 дней
• Итого: 2–4 недели