Paperclip: руководство по Multi-Agent Workflow 2026

Вы видите десятки задач, но не понимаете, кто их создал, на каком этапе они застряли и какие права получил исполнитель.
Самый быстрый путь — использовать Paperclip как контрольный слой Multi-Agent Workflow: начать с одной небольшой компании, нескольких взаимно исключающих ролей и задачи, которую человек сможет проверить вручную.

Кому пригодится это руководство

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

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

Последнее обновление — 14 августа 2026 года. Данные сверены с официальным README, руководством по установке, описанием среды исполнения, моделью жизненного цикла задач и журналом релизов Paperclip. (официальное руководство по установке Paperclip)

До запуска определите место Paperclip в системе

Paperclip не является новой моделью, универсальным кодинг-агентом или заменой вашему runtime. В официальной архитектуре он выступает как control plane: здесь задаются компании, цели, организационная структура, задачи, комментарии, бюджеты, approvals и правила наблюдения, а фактическая работа выполняется подключённым агентом через адаптер. (описание архитектуры Paperclip)

Рабочую схему удобно разделить на четыре слоя:

Это разделение важно по трём причинам.

Во-первых, установка Paperclip сама по себе не создаёт автоматизацию. Если у вас нет рабочего Agent, модели, ключа доступа, рабочего каталога и понятного результата, вы получите интерфейс управления без исполнителя.

Во-вторых, Paperclip не отменяет ограничения самого Agent. Некачественный prompt, потеря контекста, неправильная команда или недоступный репозиторий не исправляются одной организационной схемой.

В-третьих, контрольный слой может расширить радиус ошибки. Если агенту выданы права на чтение всех проектов или запись в production, новая задача может превратить локальную ошибку в системную проблему. Поэтому сначала определите разрешения и границы проекта, а уже потом стройте оргструктуру.

Как работает Paperclip Multi-Agent Workflow?
Событие — например, назначение задачи, ручной запуск или расписание — пробуждает Agent. Paperclip вызывает его адаптер, передаёт контекст, фиксирует результат, статус, журналы и доступную информацию о расходах. После завершения Agent возвращается в неактивное состояние, а следующий участник просыпается через назначение, комментарий, зависимость, расписание или ручное действие. (спецификация среды исполнения Paperclip)

Это не постоянный чат между агентами. Важная единица работы — heartbeat, то есть отдельное окно исполнения. При повторном пробуждении для того же ключа задачи может использоваться сохраняемое состояние сессии; разные задачи сохраняют раздельный контекст.

Первый час: соберите минимальную организацию

Не импортируйте сразу большую «AI-компанию» с десятками ролей. Для первого теста достаточно:

1. одной цели компании;
2. одного координатора;
3. одного исполнителя;
4. одного проверяющего;
5. одной задачи с очевидным результатом.

Пример для разработки небольшого сервиса:

• координатор формулирует план и создаёт дочерние задачи;
• исполнитель изменяет код в отдельной рабочей области;
• проверяющий запускает тесты и возвращает задачу на доработку;
• человек утверждает изменения перед публикацией.

Роли должны быть взаимно исключающими. Если один Agent одновременно ставит задачу, меняет код, принимает результат и запускает публикацию, вы теряете смысл журнала и не сможете определить, на каком этапе возникла ошибка.

Цель задавайте так, чтобы её можно было проверить не по количеству созданных задач, а по результату: например, «подготовить изменение, пройти набор тестов и представить diff для ручного review». Количество агентов не является показателем производительности. Дополнительная роль полезна только тогда, когда она снимает конкретное ограничение — проверку, планирование, исследование или согласование.

На этом этапе не включайте все доступные шаблоны. Сначала убедитесь, что:

• у каждой роли есть собственный результат;
• у каждой задачи есть один ответственный;
• дочерняя задача связана с родительской целью;
• завершение действительно будит следующего участника;
• человек понимает, где остановить процесс.

Каких AI Agent можно подключить к Paperclip?
Официальная модель не ограничивает вас одним конкретным runtime: агент может быть локальным процессом, CLI, скриптом, внешним сервисом или адаптером, если он вызывается, получает контекст, выполняет работу и возвращает результат. Paperclip также предусматривает внешние адаптеры, загружаемые через плагинную систему.

Практический вывод: выбирать нужно не по названию Agent, а по контракту интеграции. Проверьте, умеет ли он принимать идентификатор задачи, читать назначение, оставлять комментарий, менять статус и безопасно работать в выделенном каталоге.

Первый рабочий процесс: от цели к проверяемому результату

Для пилота возьмите задачу, которую легко откатить: например, добавить небольшой endpoint, обновить документацию или подготовить отчёт без записи в production.

Последовательность может выглядеть так:

1. Координатор получает верхнеуровневую цель.
2. Он создаёт дочернюю задачу для исполнителя.
3. Исполнитель забирает задачу и переводит её в работу.
4. Результат сохраняется в комментарии, документе, артефакте или рабочем каталоге.
5. Исполнитель переводит задачу на review.
6. Проверяющий принимает результат или возвращает задачу в работу.
7. Координатор получает уведомление и решает, создавать ли следующий шаг.
8. Человек подтверждает действие, которое может затронуть внешний ресурс.

В официальной модели задачи проходят состояния вроде backlog, todo, in_progress, in_review, blocked, done и cancelled. Для них определены допустимые переходы, а зависимые задачи могут ждать завершения блокирующей задачи. (описание жизненного цикла задач Paperclip)

Проверьте не только успешную ветку. Создайте контролируемую ошибку:

• отключите тестовый инструмент;
• передайте недоступный путь;
• завершите Agent с ошибкой;
• оставьте задачу в blocked;
• вручную отмените зависимость.

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

День первый: подключите реальный Agent без лишних прав

После пилота подключайте настоящий runtime, но не переносите сразу весь проект.

Вам понадобятся:

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

Секреты не следует помещать в текст задачи, комментарий или общий документ. Если агенту нужен доступ к Git, API или хранилищу, выдайте отдельный токен с минимальным набором операций. Разделяйте как минимум тестовые и production-ресурсы, даже если оба процесса работают на одном сервере.

Перед включением проверьте четыре границы:

1. Может ли Agent создать задачу не в своём проекте?
2. Может ли он прочитать комментарии и документы другой команды?
3. Может ли он изменить статус чужой задачи?
4. Может ли он выполнить команду, которая меняет production?

В спецификации Paperclip по умолчанию описана видимость рабочих объектов внутри компании, поэтому организационная схема не равна полноценной изоляции данных. В чувствительной среде нужны отдельные компании, проекты, пользователи, рабочие каталоги и системные разрешения — в зависимости от вашей модели угроз.

Чем Paperclip отличается от CrewAI?
CrewAI обычно рассматривают как фреймворк, в котором вы описываете взаимодействие агентов и выполнение задач внутри приложения. Paperclip решает другую задачу: он организует работу как управляемую компанию с оргструктурой, целями, задачами, бюджетами, approvals и аудитом. Поэтому они могут дополнять друг друга: CrewAI может быть runtime или логикой конкретного процесса, а Paperclip — внешним слоем управления. Сравнивать их как два одинаковых workflow-конструктора некорректно.

Главный критерий выбора простой:

• если вам нужно программно описать один процесс внутри приложения, начните с фреймворка;
• если у вас уже есть несколько Agent, проектов, владельцев и ручных точек контроля, нужен контрольный слой;
• если требуются оба уровня, разделите orchestration внутри Agent и governance на уровне Paperclip.

Первая неделя: добавьте governance и наблюдаемость

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

Настройте следующие правила:

• ручное approval перед внешней публикацией;
• тайм-аут для каждой категории задач;
• бюджет или лимит выполнения для Agent;
• уведомление о переходе в blocked;
• обязательный комментарий с результатом и следующим действием;
• журнал запуска, ошибки и расход токенов, если адаптер их предоставляет;
• процедуру остановки зависшей сессии.

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

Особенно внимательно ищите три симптома:

Повторное делегирование. Координатор создаёт почти одинаковые задачи, потому что не видит результат предыдущей попытки.

Циклическое пробуждение. Проверяющий возвращает задачу исполнителю, исполнитель снова будит проверяющего, но ни один участник не меняет артефакт.

Потеря контекста. Новый heartbeat получает задачу, но не получает важное решение из предыдущего запуска. В таком случае фиксируйте итог в задаче или документе, а не рассчитывайте только на память сессии.

Как настроить ручное согласование в Multi-Agent Workflow?
Разделите «результат готов» и «действие разрешено». Agent может подготовить diff, отчёт или предложение, но публикация, удаление данных, изменение бюджета и доступ к внешнему ресурсу должны переводить задачу в review или approval. Paperclip поддерживает связанные с задачами approvals и многоэтапные политики review, однако конкретную схему нужно проверять по версии и конфигурации вашего экземпляра. (официальные заметки о релизах Paperclip)

Пошаговое развёртывание на сервере

Для локального эксперимента официальная инструкция предусматривает Node.js 20 или более новую версию, pnpm и команду onboarding. При стандартном запуске создаётся локальная конфигурация и встроенная база, а интерфейс доступен через локальный порт 3100. (руководство Paperclip по локальной установке)

Для постоянной работы используйте такой порядок:

1. Создайте отдельного системного пользователя paperclip, не запускайте сервис от root.
2. Подготовьте Linux-сервер, доменное имя и SSH-доступ.
3. Установите Node.js 20+ и pnpm.
4. Задайте режим authenticated и публичный адрес экземпляра.
5. Запустите onboarding от пользователя paperclip.
6. Проверьте конфигурацию диагностической командой до публикации сервиса.
7. Запустите Paperclip через systemd.
8. Поставьте reverse proxy перед приложением.
9. Включите HTTPS и проверьте перенаправление HTTP.
10. Создайте первую компанию и API-ключ для Agent.
11. Настройте резервное копирование базы, файлов и каталога плагинов.
12. Проверьте восстановление на отдельной копии, а не только наличие backup-файла.

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

Сравнение среды для Paperclip

Как развернуть Paperclip на сервере?
Для личного теста используйте локальный режим. Для команды, которой нужен доступ из разных мест, выбирайте серверный режим с аутентификацией, HTTPS, отдельным пользователем и резервным копированием. Не выставляйте локальный доверенный режим напрямую в интернет: это меняет модель угроз и может открыть контрольный слой без нужной защиты. Выбор между Linux и удалённым Mac определяйте не названием операционной системы, а требованиями Agent к инструментам, GUI, рабочему каталогу и длительности сессии.

Выбор постоянной среды: не путайте доступность с производительностью

Для серверной эксплуатации важны не только вычислительные ресурсы. У вас есть несколько независимых затрат и ограничений:

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

Локальный компьютер дешевле для пробного запуска, но плохо подходит как единственная точка исполнения: сон, обновление системы или закрытие VPN прерывают heartbeat. Linux-сервер удобнее для headless-процессов, однако не решает задачи, которым нужен macOS или графический интерфейс. Удалённый Mac полезен, если Agent должен работать в Apple-ориентированной среде, но его нельзя автоматически считать лучшим вариантом для тяжёлых постоянных задач.

Для конфигурации и проверки сценария сначала зафиксируйте требования в настройках заказа Mac, а не выбирайте машину только по названию процессора. Если проекту нужна длительная удалённая сессия, заранее определите, кто отвечает за доступ, перезапуск, сохранность файлов и передачу результата; общий канал связи с командой можно уточнить через контакты Macstripe.

Что считать готовым к постоянному запуску

Приёмка перед расширением команды Agent

Расширяйте число ролей только после прохождения этой проверки:

• [ ] Одна задача проходит путь от цели до результата без ручного редактирования каждого статуса.
• [ ] Координатор не создаёт дубликаты при повторном heartbeat.
• [ ] Ошибка исполнителя переводит задачу в понятное состояние.
• [ ] Повторный запуск не удаляет предыдущий результат.
• [ ] Проверяющий может вернуть задачу исполнителю с конкретной причиной.
• [ ] Внешнее действие останавливается на approval.
• [ ] Agent не видит каталоги и проекты, которые не нужны для его роли.
• [ ] Секрет можно отозвать без перестройки всей организации.
• [ ] Оператор может остановить Agent и освободить зависшую задачу.
• [ ] Восстановление из резервной копии проверено на тестовой копии.
• [ ] Команда знает, где смотреть журнал запуска и последнее решение.
• [ ] Переход на постоянную среду не зависит от ноутбука одного сотрудника.

Организация против простого списка инструментов

Итог для вашего сценария

Paperclip стоит внедрять не тогда, когда вы хотите «добавить больше агентов», а тогда, когда уже возникла проблема управления: задачи теряются, роли пересекаются, результаты нельзя проверить, а ручные approvals находятся в переписке. Его сильная сторона — связать цель, оргструктуру, задачу, heartbeat, бюджет и решение человека в один наблюдаемый контур.

Если ваш текущий вариант — личный ноутбук, он ограничен сном системы, обрывом сетевой сессии и зависимостью от присутствия конкретного разработчика. Если это общий Linux-сервер, добавляются проблемы с доступом к macOS-инструментам, GUI-сценариями и разделением рабочих каталогов. Если вы используете набор разрозненных скриптов, ошибки делегирования, повторные запуски и ручные согласования часто остаются без единого журнала.

Для короткого пилота локальная среда разумнее и дешевле по операционной сложности. Но если вам нужно постоянно держать Paperclip и несколько Agent доступными для удалённой команды, изолировать проекты и передавать результаты между рабочими сессиями, аренда удалённого Mac у Macstripe может оказаться более предсказуемым вариантом, чем превращать личный компьютер в круглосуточный сервер. При этом для длительной стабильной нагрузки, требующей постоянного физического доступа или особых аппаратных интерфейсов, собственная инфраструктура всё ещё может быть правильнее. Перед запуском такого сценария сопоставьте требования к среде с вариантами конфигурации Macstripe и заранее опишите процедуру приёмки: доступ, сохранность рабочих данных, перезапуск и передачу результата.