Orchestra — функциональные характеристики, установка и эксплуатация

1. Назначение программного обеспечения

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

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

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

2. Перечень функциональных характеристик

2.1. Управление парком агентов

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

2.2. Иерархия и обмен сообщениями

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

2.3. Изоляция работ и сборка результата

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

2.4. Взаимная проверка результата моделями разных поставщиков

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

2.5. Ведение задач

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

2.6. Фоновые задания и расписания

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

2.7. Рабочие места оператора

• веб-интерфейс («дашборд») с потоковым обновлением: список агентов, их состояние, диалог, файлы рабочей копии, задачи, фоновые задания, коммиты;
• управление из мессенджера Telegram: текстовые сообщения, голосовые сообщения с автоматической расшифровкой, изображения и документы; отдельные темы группы под агентов;
• отправка оператору файлов, альбомов файлов и построенных платформой диаграмм;
• публикация защищённого от индексирования HTML-артефакта по ссылке с ограниченным сроком жизни.

2.8. Учёт ресурсов и ограничение расхода

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

2.9. Память и знания проекта

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

2.10. Расширение набора инструментов

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

2.11. Однократные параллельные сценарии

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

3. Требования к системе

4. Входные и выходные данные

Входные данные. Текст задания от оператора; голосовые сообщения, изображения и документы, поступающие из мессенджера; содержимое файлов рабочего репозитория; ответы внешних инструментов, подключённых по протоколу Model Context Protocol.

Выходные данные. Изменения в рабочем репозитории, оформленные коммитами и ветками; сообщения оператору и другим агентам; записи задач и их статусов; файлы-артефакты отчётов и вердиктов ревью; записи журнала работы и учёта израсходованных ресурсов.

5. Язык интерфейса

Графический пользовательский интерфейс программного обеспечения реализован на русском языке. Проверка 22.09.2026 охватила 41 экран; после исключения имён собственных, идентификаторов и путей, ответов моделей, служебных строк сервера и единиц измерения латинских надписей, требующих перевода, не обнаружено.

6. Ограничения

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

1. Требования к аппаратному и программному обеспечению

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

2. Состав поставляемого экземпляра

Экземпляр программного обеспечения представляет собой каталог с исходным текстом на языке Python и сопровождающими файлами:

Технические средства защиты авторских прав в экземпляре отсутствуют, лицензионные ключи не применяются, активация не требуется.

3. Установка на одном узле

3.1. Подготовка системы

sudo apt-get update
sudo apt-get install -y python3.12 python3.12-venv git nginx curl
curl -LsSf https://astral.sh/uv/install.sh | sh

uv — средство управления виртуальным окружением и зависимостями. Допускается любой иной способ создания виртуального окружения, воспроизводящий состав uv.lock.

3.2. Размещение исходного текста

sudo useradd --system --create-home --shell /bin/bash orchestra
sudo mkdir -p /opt/orchestra
sudo chown orchestra:orchestra /opt/orchestra
sudo -u orchestra git clone <адрес репозитория> /opt/orchestra

Адрес репозитория выдаётся правообладателем. Для экспертной проверки он передаётся в составе заявления.

3.3. Установка зависимостей

cd /opt/orchestra
sudo -u orchestra uv sync --frozen

Флаг --frozen требует точного соответствия зафиксированным в uv.lock версиям. Установка завершается созданием виртуального окружения /opt/orchestra/.venv.

3.4. Файл параметров

sudo -u orchestra cp .env.example .env
sudo -u orchestra chmod 600 .env

Обязательные к заполнению параметры:

Необязательные параметры (часовой пояс, символ валюты, пороги квот, путь к файлу базы данных, подключение мессенджера) описаны комментариями в самом файле .env.example.

3.5. Первый запуск в тестовом режиме

cd /opt/orchestra
sudo -u orchestra .venv/bin/uvicorn app.main:app --host 127.0.0.1 --port 8888

Успешный запуск подтверждается строкой Started server process в выводе и ответом 200 на запрос страницы входа:

curl -sL -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8888/

База данных SQLite создаётся автоматически при первом запуске в каталоге data/.

3.6. Регистрация службы

sudo cp deploy/orchestra.service.template /etc/systemd/system/orchestra.service
sudo systemctl daemon-reload
sudo systemctl enable --now orchestra
sudo systemctl status orchestra

Служба запускается от имени учётной записи orchestra, рабочий каталог /opt/orchestra, параметры читаются из /opt/orchestra/.env, перезапуск при сбое — автоматический.

3.7. Публикация через веб-сервер

Шаблон конфигурации — deploy/nginx.conf.template. Он проксирует запросы на 127.0.0.1:8888 и содержит параметры, необходимые для длительных соединений потока событий (Server-Sent Events): proxy_buffering off, proxy_read_timeout 600s, proxy_http_version 1.1 и заголовки Upgrade/Connection. Предельный размер загружаемого файла — 50 МБ (client_max_body_size 50M).

sudo cp deploy/nginx.conf.template /etc/nginx/sites-available/orchestra
sudo ln -s /etc/nginx/sites-available/orchestra /etc/nginx/sites-enabled/orchestra
sudo nginx -t && sudo systemctl reload nginx

3.8. Автоматизированная установка

Сценарий deploy/install.sh <учётная_запись>@<адрес> выполняет шаги 3.1–3.7 на удалённом узле по протоколу SSH. Сценарий требует прав суперпользователя на целевом узле.

4. Подключение поставщика языковых моделей

Программа не содержит собственной языковой модели и обращается к внешнему поставщику. Поддерживаются два способа подключения:

1. Через клиент командной строки поставщика. Клиент устанавливается отдельно средствами Node.js и настраивается по документации поставщика; Orchestra запускает его как внешний процесс.
2. Напрямую по протоколу HTTP, совместимому со спецификацией OpenAI Chat Completions. Адрес конечной точки задаётся параметром OPENROUTER_BASE_URL, ключ доступа — параметром OPENROUTER_API_KEY. Этот способ позволяет подключить любого поставщика, реализующего указанную спецификацию, в том числе размещённого на территории Российской Федерации.

5. Проверка работоспособности после установки

6. Обновление и удаление

Обновление: остановить службу, выполнить git pull и uv sync --frozen, запустить службу. Файл .env и каталог data/ при обновлении не затрагиваются.

Удаление: остановить и отключить службу, удалить файл описания службы, удалить каталог /opt/orchestra и учётную запись orchestra.

1. Доступ к экземпляру, предоставленному для экспертной проверки

Экземпляр развёрнут на сервере правообладателя в Российской Федерации и доступен удалённо по HTTPS. Адрес экземпляра и учётные данные для входа передаются эксперту в составе заявления — в подписанном электронной подписью документе «Руководство по эксплуатации». Контакт по развёртыванию: maxim@seedon.ru, +7 929 356-16-50.

2. Запуск, работа и завершение программы

2.1. Запуск

Программа работает как служба операционной системы и запускается автоматически при старте узла. Ручное управление:

sudo systemctl start orchestra     # запуск
sudo systemctl stop orchestra      # завершение
sudo systemctl restart orchestra   # перезапуск
sudo systemctl status orchestra    # состояние
journalctl -u orchestra -n 200     # журнал работы

При запуске программа открывает базу данных, восстанавливает сохранённые сессии агентов и начинает принимать подключения на локальном адресе 127.0.0.1:8888.

2.2. Вход в веб-интерфейс

Открыть адрес экземпляра в браузере и ввести учётные данные, заданные параметрами DASHBOARD_USER и DASHBOARD_PASSWORD. Завершение сеанса — кнопкой выхода в шапке интерфейса.

2.3. Основные операции оператора

2.4. Управление из мессенджера

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

2.5. Завершение работы

Корректное завершение — командой systemctl stop orchestra. Незавершённые ходы агентов прерываются, состояние сессий сохраняется в базе данных, при следующем запуске агенты восстанавливаются.

3. Формат команд оператора и ответы программы

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

Управляющие действия (создание агента, остановка, слияние ветки, закрытие задачи, отмена фонового задания) выполняются элементами графического интерфейса, перечисленными в пункте 2.3.

4. Хранение данных и резервное копирование

Резервная копия базы данных снимается средствами SQLite без остановки службы:

sqlite3 data/orchestra.db ".backup '/путь/к/резервной/копии.db'"

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

5. Типовые ситуации и действия оператора

6. Ограничения эксплуатации

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

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