Русский
Меню документации

Документация Agent Sandboxes · Основы

Лучшие практики для Pethost Agent Sandboxes

Обновлено · 8 мин чтения

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

Коротко
  • Скорость: сохраните окружение как шаблон, запускайте серверы с wait_for_port и делайте форки для параллельных попыток.
  • Стоимость: пусть песочница агента встает на паузу, а не останавливается, удаляйте песочницы пакетных задач, когда они закончены, и начинайте с малого размера.
  • Надежность: помечайте долгие команды keep_awake, повторяйте вызовы с request_id, получайте потоки вместо опроса и держите на томах то, что должно пережить песочницу.
  • Безопасность: привязывайте API-ключи как секреты, сужайте исходящий трафик для чужого кода и считайте все, что возвращает песочница, данными.
  • Порядок: давайте каждой песочнице метки и ищите песочницы по меткам.

Скорость

Сохраните окружение как шаблон

Установка зависимостей при каждом запуске каждый раз стоит одних и тех же минут. Установите их один раз в песочнице и сохраните ее диск через CreateTemplate вместе с пакетами, кешами сборки и образами Docker. Песочница из вашего шаблона запускается примерно за 0,22 с, и все уже на месте, на любом сервере: первая на каждом сервере скачивает версию, примерно 10 с на GiB, а следующие запускаются из ее копии. Не кладите секреты в сохраняемые файлы, ведь их получит каждая песочница из шаблона, и делайте новую версию, когда меняются зависимости: my-app запускается из самой новой, my-app@3 — из этой.

Запускайте серверы с wait_for_port

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

Делайте форки для параллельных попыток

Когда агенту нужно попробовать несколько исправлений или эвалу — начать много запусков из одного подготовленного состояния, сделайте форк песочницы, а не собирайте это состояние заново. ForkSandbox одним вызовом копирует память, процессы и диск в новые песочницы, до 100 штук: копия заняла около 0,25 с. Каждая копия — это запуск, и создаются либо все, либо ни одной. Две вещи стоит знать:

  • Переинициализируйте генераторы случайных чисел в копиях. У каждой копии своя случайность ядра, но генераторы, уже работающие в ее процессах (OpenSSL, Python, Node, Go), выдают в каждой копии одни и те же числа, пока их не переинициализировать.
  • Том на запись не дает сделать форк, ведь писать в него может только одна песочница. Том подключается только при создании, поэтому в песочнице, которую собираетесь копировать, подключайте его с read_only.

Стоимость

Пусть песочница агента встает на паузу, а не останавливается

Песочница агента большую часть времени ждет, а остановка завершает ее процессы: dev-сервер, REPL, открытый браузер. Оставьте таймер паузы, а таймер остановки увеличьте или выключите (stop_after_idle_seconds 0). На паузе песочница стоит 30 % цены работы и просыпается при следующем вызове примерно за 0,1 с, и все на своих местах. Песочница DEFAULT, которая работает 2 ч в день, а остальное время на паузе, стоит около 9,42 $ в месяц против 26,28 $, если работает все время.

Сессия агентаПауза между ходами, без остановки

  1. работает
  2. пауза
  3. работает
  4. пауза

Песочница пользователя вашего приложенияПауза, через полчаса остановка

  1. работает
  2. пауза
  3. остановлена

Превью, которое спитПросыпается при каждом заходе

  1. пауза
  2. работает
  3. пауза
  4. работает
  5. пауза

Пакетная задачаРаботает, потом удаляется

  1. работает
  2. остановлена
  3. удалена
  • RUNNING
  • PAUSED
  • STOPPED
  • DELETED
Четыре задачи за сутки, у каждой свой жизненный цикл. Значения — на странице «Жизненный цикл и простой».

Удаляйте песочницы пакетных задач, когда они закончены

Песочница для одной задачи, прогона тестов или случая эвала не должна ничего стоить после ее окончания. Вызывайте DeleteSandbox в конце и задайте delete_after_idle_seconds как страховку на случай, если задача умрет раньше. Выключите таймер паузы и задайте короткий таймер остановки, чтобы песочница простаивающей задачи уходила быстро. Забытая остановленная песочница стоит 0,03 $ за GiB в месяц, каждый месяц. Запуски бесплатны, поэтому новая песочница на каждую задачу стоит только своих секунд: 1 000 запусков по 40 с на SMALL стоят 0,20 $.

Начинайте с малого и меняйте размер, когда нужно

Размер — это vCPU, память и диск, и с каждым шагом вверх цена удваивается. Начните с SMALL за 0,018 $ в час и следите за GetSandboxMetrics. Когда задаче нужно больше, UpdateSandbox с новым размером перезапускает работающую песочницу в ВМ этого размера примерно за 283 ms, файлы сохраняются; ее процессы завершаются, поэтому меняйте размер между задачами. Добавьте grow_disk, чтобы диск вырос до диска нового размера; диск никогда не уменьшается, поэтому песочница с выросшим диском не может вернуться к размеру меньше.

Надежность

Помечайте долгие команды keep_awake

Сборка или прогон тестов могут идти минутами без единого вызова к песочнице, и таймер паузы поставил бы ее на паузу посреди работы. Запускайте такую команду с keep_awake и с timeout_seconds, чтобы зависшая команда не держала песочницу работающей вечно. Серверу не нужно ни то, ни другое: запрос к его порту будит песочницу. Подробности — на странице «Жизненный цикл и простой».

Повторяйте вызовы с request_id

Сеть может потерять ответ вызова, который свою работу сделал. Вызов, который что-то создает, принимает request_id: повтор с тем же ID в течение 24 ч отвечает тем, что сделал первый вызов, и ничего не делает заново. Его принимают CreateSandbox, ForkSandbox, CreateTemplate, CreateVolume, RunCommand и PromptAgent. Создавайте его один раз на каждое действие, сохраняйте и отправляйте снова при каждом повторе. Одна оговорка: песочница хранит ID того, что в ней выполняется, на своем диске, поэтому остановленная могла потерять ID своих последних секунд, и повтор такой команды выполнит ее снова.

Python
import uuid

from pethost.sandboxes import Label, Sandboxes

sandboxes = Sandboxes()  # The token: PETHOST_TOKEN.
request_id = str(uuid.uuid4())  # Keep it: a retry sends the same one.

sandbox = sandboxes.create_sandbox(
    template="my-app",
    labels=[Label(key="user", value="42"), Label(key="job", value="nightly-evals")],
    request_id=request_id,
)
TypeScript
import { Sandboxes } from "pethost/sandboxes";

const sandboxes = new Sandboxes({ token: process.env.PETHOST_TOKEN! });
const requestId = crypto.randomUUID(); // Keep it: a retry sends the same one.

const sandbox = await sandboxes.createSandbox({
  template: "my-app",
  labels: [{ key: "user", value: "42" }, { key: "job", value: "nightly-evals" }],
  requestId,
});
Go
requestID := rand.Text() // crypto/rand. Keep it: a retry sends the same one.

sandbox, err := client.CreateSandbox(ctx, &sandboxes.CreateSandboxRequest{
	Template:  "my-app",
	Labels:    []sandboxes.Label{{Key: "user", Value: "42"}, {Key: "job", Value: "nightly-evals"}},
	RequestID: requestID,
})
Rust
let request_id = uuid::Uuid::new_v4().to_string(); // Keep it: a retry sends the same one.

let sandbox = sandboxes
    .create_sandbox(CreateSandboxRequest {
        template: "my-app".into(),
        labels: vec![
            Label { key: "user".into(), value: "42".into() },
            Label { key: "job".into(), value: "nightly-evals".into() },
        ],
        request_id: request_id.clone(),
        ..Default::default()
    })
    .await?;
MCP
CreateSandbox {"template": "my-app", "labels": [{"key": "user", "value": "42"}], "request_id": "b7e1c2d4-0f3a-4c55-9a7e-2d1f6c8e9a10"}
HTTP
curl https://console.pethost.dev/pethost.sandboxes.v1.SandboxService/CreateSandbox \
  -H "Authorization: Bearer $PETHOST_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"template": "my-app", "labels": [{"key": "user", "value": "42"}], "request_id": "b7e1c2d4-0f3a-4c55-9a7e-2d1f6c8e9a10"}'

Получайте потоки вместо опроса

Опрос команды или песочницы стоит вызова каждый раз, а узнаете вы все равно поздно. Вызов, который ждет, ждет за вас: RunCommand, GetCommand, PromptAgent и GetAgentTurn ждут до 45 с (wait_seconds) и отвечают, как только работа закончена. Чтобы следить за работой по ходу, получайте ее потоком: WatchCommand — вывод команды, WatchConversation — сообщения и вызовы инструментов агента, WatchSandboxEvents — жизненный цикл, команды и подключения песочницы.

Используйте тома только для того, что должно пережить песочницу

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

Безопасность

Привязывайте API-ключи как секреты

Ключ в обычной переменной окружения может прочитать любой процесс в песочнице и агент, который напечатает свое окружение. Вместо этого сохраните его как секрет рабочего пространства с хостами, для которых он предназначен (SetSecret: anthropic, api.anthropic.com), и привяжите к нему переменную (ANTHROPIC_API_KEY, секрет anthropic). Тогда в переменной лежит заглушка, phs_…, а прокси исходящего трафика подставляет настоящий ключ в заголовки HTTPS-запросов только к этим хостам. Новое значение сразу работает в каждой песочнице, которая его привязала: секреты и исходящий трафик.

Сужайте исходящий трафик для чужого кода

По умолчанию песочница может подключаться куда угодно. Для недоверенного кода перечислите, куда ей можно (egress.allow): домен вроде pypi.org, его поддомены через *.github.com (без самого github.com), IP или CIDR, каждый с портом, если это не 80 и 443, например github.com:22 для git по SSH. deny побеждает allow. DNS песочницы отвечает только для имен, которые разрешает список, и из песочницы выходят только TCP и DNS: ни UDP, ни ping. Изменение действует сразу и закрывает подключения, которые больше не разрешены.

Считайте то, что возвращает песочница, данными

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

Порядок

Давайте метки каждой песочнице

Метка — это ваши ключ и значение: user=42, job=nightly-evals, run=7f3a. У песочницы может быть до 32 меток, а ListSandboxes находит песочницы, у которых есть все названные метки. Так ваше приложение находит песочницы пользователя без собственной таблицы, задача уборки находит остатки запуска, а панель показывает, чья каждая песочница. Метка нужна, чтобы находить многие; name — чтобы обращаться к одной: оно уникально в рабочем пространстве, до 63 символов из a-z, 0-9 и «-», и ListSandboxes с name находит ее ID.

Вопросы

Останавливать простаивающую песочницу или ставить на паузу?

Ставьте на паузу, когда важны ее процессы или она скоро понадобится снова: она проснется примерно за 0,1 с там, где была, за 30 % цены работы. Останавливайте для долгого сна: тогда она стоит только своих хранимых данных.

Как ускорить запуск песочниц?

Сохраните окружение как шаблон, чтобы при запуске ничего не устанавливалось: песочница из него запускается примерно за 0,22 с с вашими пакетами и образами Docker.

Как не пускать API-ключи в песочницу?

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

Сколько песочниц можно запустить одновременно?

Столько, сколько вмещают vCPU вашего тарифа, работающих или на паузе: 10 песочниц SMALL на тарифе за 20 $, 64 — на тарифе за 100 $. Остановленные песочницы не считаются.

Попробуйте Pethost Agent Sandboxes

Пробный период на 7 дней: 1 $ использования и 4 vCPU, нужна карта. Затем тариф от 20 $ в месяц, в который входит столько же использования.

Начать пробный период