В проекте ScriptorDB вызовы Pydantic AI заняли лишь 73 строки кода, основная сложность оказалась в архитектуре

В открытом проекте ScriptorDB прямая интеграция с фреймворком Pydantic AI заняла всего 73 строки кода. При этом более 90% инженерной работы ушло на инфраструктуру вокруг системы. Сюда относятся изоляция рабочих пространств, управление секретами, выбор моделей, политики безопасности инструментов, хранение сессий, потоковая передача через SSE, отслеживание ошибок и аудит выполнения. Как пишет Towards AI, такой перекос довольно точно отражает реальность production‑систем: сам фреймворк отвечает за выполнение запросов к LLM, но не за архитектуру всего приложения.

В демонстрациях фреймворков всё выглядит намного проще. Достаточно объявить Agent, подключить инструменты и вызвать agent.run(). Но когда такой код пытаются перенести в рабочую среду, быстро всплывают вопросы, на которые фреймворк не отвечает. Например, как изолировать историю чатов между пользователями. Как работать с несовместимыми model ID у разных провайдеров вроде OpenAI и Claude. Где хранить источник истины для восстановления состояния. Как маршрутизировать HTTP‑трафик, если потоковый вывод смешивает текстовые фрагменты и события вызова инструментов.

В архитектуре ScriptorDB фреймворк используется как тонкое ядро выполнения. Файл agents/db_agent.py содержит 73 строки, которые решают четыре задачи: создают Agent[AppConfig] на основе текущей конфигурации, подключают три FunctionToolsets, добавляют audit‑hooks и оборачивают провайдеров слоем OpenAIProvider. Бизнес‑состояние при этом не помещается внутрь агента. Объект AppConfig передаётся через deps как конфигурация с подключением к базе данных текущего workspace. Такой подход изолирует управление состоянием от механизма выполнения.

Авторы проекта отдельно выносят слой инструментов и не смешивают его с определением агента. В Pydantic AI есть простой декоратор @agent.tool, однако в production‑сценариях инструменты требуют дополнительных политик и проверок перед запуском. Поэтому в ScriptorDB они реализованы как отдельные подсистемы, а не как функции внутри агента.