Окружение и шаблоны песочниц
Шаблон определяет, какие программы и файлы доступны агенту. Подготовьте шаблон в своём проекте AgentBox с Codex, CLI, навыками и конфигурацией MCP нужных систем. Orpheus регистрирует шаблоны проекта, которому принадлежит его ключ AgentBox.
- Опишите и соберите окружение по инструкции AgentBox.
- Добавьте Codex CLI и инструменты для ваших workflow. Для Mattermost также нужны Linux и Python 3.9 или новее. Скрипты работы с вложениями коннектор устанавливает сам.
- Зарегистрируйте шаблон в Orpheus по инструкции ниже.
- Укажите точное имя из каталога в
configuration.sandbox.template, полеsandbox_templateworkflow Mattermost или задании Space. - Создайте новую сессию и проверьте доступность инструментов.
Регистрация шаблона
В 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-ключом:
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 принимает:
| Параметр | Значение |
|---|---|
active | true или 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 файлы и контекст сохраняются между запусками при паузе песочницы. В режиме по умолчанию песочница удаляется после единственного запуска. Храните опубликованный результат в целевой системе.