Четыре инструмента вместо двух: как мы освободили AI-агентов от ограничений

От изоляции к открытости: как мы расширили доступ к файловой системе в AI-агентах

Работал я над проектом ai-agents — платформой для создания интеллектуальных помощников на Python. И вот в какой-то момент нас настигла настоящая боль роста: агенты работали в тесной клетке ограничений.

Проблема: узкие границы доступа

Представь ситуацию. У нас была виртуальная файловая система — и звучит круто, пока не начнёшь с ней работать. Агенты могли читать только три папки: plugins/, data/, config/. Писать вообще не могли. Нужно было создать конфиг? Нет. Сохранить результат работы? Нет. Отредактировать существующий файл? Снова нет.

Это было словно программировать с одной рукой, привязанной за спину. Функциональность file_read и directory_list — хорошо, но недостаточно. Проект рос, требования расширялись, а система стояла на месте.

Решение: четыре инструмента вместо двух

Первым делом я понял, что нужно идти не путём костылей, а переписать модуль filesystem.py целиком. Вместо двух полуслепых инструментов создал четыре полнофункциональных:

• file_read — теперь читает что угодно в проекте, до 200 килобайт
• file_write — создаёт и перезаписывает файлы, автоматически создаёт директории
• file_edit — тонкая работа: находит точную подстроку через find-and-replace и заменяет
• directory_list — гибкий листинг: поддерживает glob-паттерны и рекурсию

Но тут появилась вторая проблема: как дать свободу, но не потерять контроль?

Безопасность: ограничения, которые действительно работают

Всё звучит опасно, пока не посмотришь на механизм защиты. Я добавил несколько слоёв:

Все пути привязаны к корню проекта через Path.cwd(). Выбраться наружу невозможно — система просто не позволит обратиться к файлам выше по дереву директорий. Плюс чёрный список: система блокирует доступ к .env, ключам, секретам, паролям — ко всему, что может быть опасно. А для дополнительной уверенности я добавил проверку path traversal через resolve() и relative_to().

Получилась архитектура, где агент может свободно работать внутри своей песочницы, но не может ей повредить.

Интересный момент: почему это важно

Знаешь, в истории компьютерной безопасности есть забавный парадокс. Чем больше ты запрещаешь, тем больше люди ищут обходные пути. А чем правильнее ты даёшь разрешения — с умными ограничениями — тем спокойнее всем. Unix-философия в действии: дай инструменту ровно столько мощи, сколько нужно, но убедись, что он не сможет что-то сломать.

Итого

Переписал модуль, обновил константы в constants.py, экспортировал новые классы в __init__.py, подключил всё в core.py и handlers.py. Проверил сборку — зелёная лампочка. Теперь агенты могут полноценно работать с проектом, не боясь случайно удалить что-то важное.

Дальше планировали тестировать на реальных сценариях: создание логов, сохранение состояния, динамическая генерация конфигов. А пока что у нас есть полнофункциональная и безопасная система для работы с файлами.

Мораль истории: не выбирай между свободой и безопасностью — выбирай правильную архитектуру, которая обеспечивает оба.