К содержимому

Окружение и шаблоны песочниц ​

Шаблон определяет, какие программы и файлы доступны агенту. Подготовьте шаблон в своём проекте AgentBox с Codex, CLI, навыками и конфигурацией MCP нужных систем. Orpheus регистрирует шаблоны проекта, которому принадлежит его ключ AgentBox.

  1. Опишите и соберите окружение по инструкции AgentBox.
  2. Добавьте Codex CLI и инструменты для ваших workflow. Для Mattermost также нужны Linux и Python 3.9 или новее. Скрипты работы с вложениями коннектор устанавливает сам.
  3. Зарегистрируйте шаблон в Orpheus по инструкции ниже.
  4. Укажите точное имя из каталога в configuration.sandbox.template, поле sandbox_template workflow Mattermost или задании Space.
  5. Создайте новую сессию и проверьте доступность инструментов.

Регистрация шаблона ​

В Orpheus Web откройте Настройки → Шаблоны и нажмите Добавить шаблон. Введите alias из своего проекта AgentBox, например company-agent или team/company-agent. Необязательный тег задаётся в отдельном поле. Добавьте описание, которое поможет пользователям выбрать окружение. Новый шаблон активен по умолчанию.

Orpheus проверяет наличие шаблона и тега в вашем проекте AgentBox. Регистрация не собирает шаблон, не запускает песочницу и не проверяет готовность сборки. Передайте API и worker одинаковые ключ и настройки адреса AgentBox. Без ключа или при недоступном AgentBox регистрация возвращает HTTP 503. Чтение, редактирование и удаление записей каталога не обращаются в AgentBox.

При регистрации имя и тег приводятся к нижнему регистру. В поле тега нельзя передавать UUID сборки. Если тег пропущен, проверяется наличие default, а имя сохраняется без суффикса. Новые песочницы используют этот default без закрепления сборки. Явный :default остаётся отдельной записью каталога.

Каталог хранится в PostgreSQL. Изменения действуют сразу, без перезапуска API и worker. Новая установка запускается с пустым каталогом.

Через API ​

Отправьте запрос регистрации с Bearer-ключом:

python
import json
import os
from urllib.request import Request, urlopen

request = Request(
    os.environ["ORPHEUS_URL"] + "/api/v1/templates",
    data=json.dumps({
        "template_name": "team/company-agent",
        "tag": "stable",
        "description": "Корпоративные инструменты и навыки",
    }).encode(),
    headers={
        "Authorization": "Bearer " + os.environ["ORPHEUS_API_KEY"],
        "Content-Type": "application/json",
    },
    method="POST",
)
with urlopen(request, timeout=20) as response:
    template = json.load(response)
print(template["id"], template["name"])

Поле active по умолчанию равно true. Повтор имени или сочетания шаблона AgentBox и тега возвращает 409, даже если существующая запись неактивна. Не храните секреты в описании.

Поиск и редактирование ​

Список в Web по умолчанию показывает активные шаблоны. Доступны фильтры по активности и вхождению в имя. Переход между страницами и число записей на странице находятся внизу.

Откройте шаблон, чтобы изменить описание или активность. Выключение и удаление требуют подтверждения. Имя и тег не редактируются. Для другого имени зарегистрируйте новую запись. Удаление убирает запись только из Orpheus, сам шаблон AgentBox сохраняется.

Списковый метод API принимает:

ПараметрЗначение
activetrue или false. Без фильтра возвращаются оба состояния
nameТочное имя в каталоге с учётом регистра, включая team slug и тег, если они есть
name_containsБуквальное вхождение в имя без учёта регистра
limitРазмер страницы, 1–200. По умолчанию 50
cursorПолученный next_cursor или prev_cursor с прежними фильтрами

Фильтры по имени нельзя совмещать. Ответ содержит items, next_cursor и prev_cursor. Каждая страница упорядочена по имени. При смене фильтра начинайте с первой страницы. Чтобы проверить сохранённый выбор, используйте name без фильтра активности.

Управлять шаблонами могут все SAML-пользователи и локальные анонимные пользователи. Браузерные изменения подчиняются общим правилам Origin и CSRF. Управление также доступно по API-ключу.

Как активность влияет на сессии ​

Для новой сессии нужна активная запись с точным запрошенным именем. Если в каталоге сохранено team/company-agent:stable, имена company-agent:stable и team/company-agent её не выбирают. Отсутствующая или неактивная запись возвращает HTTP 422 unknown_template с кодом детали template_not_found или template_inactive.

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

Space оставляет неактивный или удалённый шаблон видимым в задании. Для сохранения других изменений или возобновления нужен активный шаблон. Пауза и удаление задания остаются доступны.

Изменения окружения ​

Обновление образа не изменяет уже созданные песочницы. Новые песочницы получают сборку, выбранную именем шаблона и тегом. Если существующим беседам Mattermost нужно новое окружение, увеличьте revision и примените workflow. Следующий запрос начнёт новую сессию. Само обновление шаблона или инструментов не требует смены ревизии. В своей интеграции создайте новую сессию, когда нужно заменить существующую песочницу.

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

Имена шаблонов · Теги и версии