# Pi Durable: архитектура отказоустойчивых агентов с локальными нейросетями

Источник: https://www.youtube.com/watch?v=ti3vVYwzW4A
Канал: Hugging Face
Опубликовано: 19.10.2026

---

Фреймворк Pi Durable представляет собой специализированный примитив для создания непрерывно работающих автономных агентов, способных корректно переживать сбои хост-процесса и системные перезагрузки. Ведущий канала Hugging Face Алехандро АО подробно разбирает архитектурные отличия новой библиотеки от стандартного интерфейса Pi coding agent, объясняет механику сохранения контрольных точек и демонстрирует развёртывание отказоустойчивого агента на локальной модели Qwen3.5-0.8B через llama.cpp с персистентным хранилищем SQLite.

## 🛠 Что такое Pi Durable: защита от сбоев и контрольные точки
[[JUMP:01:48]]

Главная задача Pi Durable — предоставить среду исполнения (agent harness), спроектированную для выживания при внезапных падениях и аварийных остановках [02:15]. Как правило, подобные агенты запускаются в виде фонового демона на сервере или локальной машине [02:15]. Если процесс аварийно завершается в момент выполнения длительной операции или чувствительного вызова внешнего инструмента, система перезапускается и продолжает работу ровно с того места, где произошёл сбой [02:36].

Чтобы продемонстрировать проблему классических агентов, Алехандро АО приводит пример с пакетной отправкой клиентских писем [03:16]:

*   Пользователь передаёт агенту задачу: отправить пять электронных писем через системный инструмент (`send email` или bash-скрипт) [03:32].
*   Агент отправляет четыре письма, но на пятом процесс внезапно падает из-за аппаратного или программного сбоя [03:48].
*   В стандартном Pi coding agent состояние сессии сохраняется в древовидном формате JSONL [04:03]. Протокол взаимодействия с языковыми моделями строго требует, чтобы за каждым сообщением с вызовом инструмента (tool call) обязательно следовал ответ инструмента (tool response) [05:00].
*   Поскольку операция прервалась, валидного ответа нет. Традиционные агенты при перезапуске вынуждены передавать фиктивный ответ об ошибке, после чего пользователь должен вручную оценивать ущерб и отправлять команду продолжения (`continue`) [05:46].

В Pi Durable этот сценарий обрабатывается автоматически [06:18]. Каждая входящая инструкция фиксируется как персистентная задача, внутри которой создаются гранулярные контрольные точки (checkpoints) [06:32]. Фреймворк сохраняет запись о старте вызова инструмента и промежуточных результатах в надёжное хранилище [07:03]. После аварийного перезапуска фонового процесса среда считывает актуальный срез данных и возобновляет прерванное действие без вмешательства человека [07:50].

## 🧩 Архитектура Pi: место Pi Durable в экосистеме
[[JUMP:08:38]]

После анонса новой библиотеки многие разработчики ошибочно предположили, что появился новый консольный агент, запускаемый командой `pi-durable` взамен стандартного интерфейса [08:23]. Поясняя позиционирование продукта, Алехандро АО подчеркнул, что Pi Durable не является готовым пользовательским приложением — это строительный блок (building block) для конструирования собственных систем [09:08].

Классическая архитектура Pi состоит из трёх уровней [10:31]:

1.  **Pi AI** — базовый интерфейс интеграции с моделями, берущий на себя кэширование промптов и унификацию API различных провайдеров [11:01].
2.  **Pi Harness** — промежуточный уровень, реализующий цикл выполнения агента (agent loop), работу с сессиями и вызов зарегистрированных инструментов [10:45].
3.  **Pi Coding Agent** — конечное пользовательское приложение, включающее терминальный интерфейс (TUI), базовые системные промпты и слой расширений [11:25].

В этой цепочке Pi Durable выступает прямой альтернативой пакету Pi Harness [11:55]. Он опирается на тот же слой взаимодействия с нейросетями Pi AI, но предоставляет специализированный класс `Harness` с интерфейсом для управления персистентными сессиями и фоновыми задачами [12:30]. Если разработчик создаёт интерактивного ассистента для парного программирования, ему достаточно стандартного Pi Harness SDK [13:04]. Однако для долгоживущих автономных агентов, работающих без постоянного контроля перед экраном, Алехандро АО рекомендует использовать именно Pi Durable [13:33].

## 🏗 Проектирование приложений: шлюзы, сессии и хранилище
[[JUMP:13:46]]

Архитектура продакшен-решения на базе Pi Durable строится вокруг внешнего связующего звена — шлюза (gateway), принимающего запросы из различных каналов, таких как мессенджеры (Telegram, Slack) или электронная почта [14:23]. Сам хост-сервис обычно пишется на платформе Node.js, поскольку библиотека реализована на TypeScript [15:06].

При проектировании прикладного кода Алехандро АО советует учитывать специфику внутренней абстракции бесед (conversations) [15:32]:

*   Понятие «беседа» (conversation) в Pi Durable функционально соответствует сессии (session) в Pi coding agent [16:26].
*   Каждая беседа обладает собственным системным промптом, изолированной рабочей директорией и уникальным набором подключённых инструментов [16:43].
*   В отличие от CLI-агента, Pi Durable по умолчанию не считывает конфигурационные файлы из папки `.pi` и игнорирует файл инструкций `AGENTS.md` — все параметры должны конфигурироваться в коде явно [17:17].
*   Поскольку внутренний API бесед в Pi Durable ещё активно развивается и пока не предоставляет полного набора CRUD-методов, Алехандро АО советует разработчикам управлять высокоуровневой логикой пользователей на уровне своего сервиса [15:46].

Ключевым фактором обеспечения отказоустойчивости выступает слой персистентности, который поддерживает три типа бэкендов:

*   **SQLite** — рекомендуемое Алехандро АО решение для большинства рабочих проектов, автоматически управляющее реляционной таблицей локально [18:14].
*   **JSONL-хранилище** — набор структурированных файлов на диске, схема которых отличается от единичных логов сессий классического Pi coding agent [18:40].
*   **In-Memory** — хранение данных в оперативной памяти исключительно для отладки и юнит-тестирования, так как все состояния стираются при закрытии процесса [18:27].

## 📋 Шесть шагов инициализации Durable Harness
[[JUMP:19:30]]

Процесс подготовки рабочего экземпляра среды в прикладном скрипте разбит на последовательные этапы [20:06]:

1.  **Конфигурация моделей.** Подключение адаптеров нейросетей через модуль Pi AI с указанием параметров эндпоинта и ключей доступа [20:19].
2.  **Инициализация реестра инструментов (Registry).** Создание объекта реестра и регистрация необходимых расширений [20:31]. В частности, через пакет расширений `coding agent tools` можно подключить стандартный инструментарий Pi: чтение, редактирование файлов, поиск и исполнение терминальных команд bash [20:45].
3.  **Настройка бэкенда хранилища (Storage).** Инициализация адаптера базы данных — например, инстанса `Node SQLite Storage` от Earendil [20:58].
4.  **Открытие среды (Harness).** Создание экземпляра `Harness`, куда передаются хранилище, реестр инструментов, провайдер моделей и путь к рабочей директории [21:25].
5.  **Создание или получение беседы (Conversation).** Определение новой сессии с указанием системных инструкций, модели и прав владения [21:38].
6.  **Отправка запросов (Submission).** Передача задачи агенту через метод `submit()` [21:38].

При отправке запроса возвращается уникальный идентификатор `submission_id` [22:33]. В зависимости от архитектуры задачи приложение может выбрать один из двух подходов к обработке:

*   **Асинхронное ожидание (Await).** Оптимально для тяжелых пакетных задач, длящихся часами или сутками, когда вызывающий код проверяет статус по идентификатору и забирает итоговый результат по готовности [22:18].
*   **Потоковая передача событий (Streaming).** Используется в интерактивных чат-интерфейсах для отображения промежуточных рассуждений, индикации вызовов инструментов и генерации текста в реальном времени [22:47].

## 💻 Практика: запуск Qwen3.5-0.8B через llama.cpp и восстановление после сбоя
[[JUMP:23:11]]

В практической части Алехандро АО развернул демонстрационный стенд с локальным сервером llama.cpp, на котором была запущена компактная модель Qwen3.5-0.8B [23:30]. Использование столь легковесной сети позволило наглядно продемонстрировать высокую скорость генерации и способность вызывать инструменты даже при скромных вычислительных ресурсах [23:43].

В первом сценарии агент получил задачу найти секретную контрольную фразу, спрятанную внутри файла `README.md` [23:56]. Модель корректно обратилась к инструменту `read`, извлекла содержимое документа и вывела фразу в консоль, попутно зафиксировав факт вызова в базе данных SQLite [24:10]. При проверке доступного инструментария агент подтвердил наличие прав на чтение, запись и редактирование файлов [25:43].

Второй сценарий (`ChatResume`) продемонстрировал непосредственно восстановление после аварии [27:52]. Агенту была отправлена команда прочитать проектную документацию и подготовить саммари [28:42]. В момент, когда модель сгенерировала вызов функции чтения файла, Алехандро АО принудительно прервал исполнение процесса через терминал [28:54].

После повторного запуска скрипта командой `npm run chat resume` среда автоматически обратилась к локальной базе SQLite [29:06]. Агент не стал заново генерировать начальный промпт и не потребовал подсказок: считав сохранённую контрольную точку незавершённого вызова `read`, он мгновенно обработал результат инструмента и вернул лаконичный ответ по документации [29:19].

Как отмечает Алехандро АО, разработчикам следует помнить о текущем статусе проекта: API Pi Durable остаётся экспериментальным и может меняться [15:46]. При этом ответственность за идемпотентность внешних инструментов (защиту от повторного выполнения недетерминированных действий при рестарте) и перезапуск самого родительского процесса операционной системой целиком лежит на авторе конечного приложения.