Українська
Меню документації

Документація 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

Серверу розробки треба трохи часу, щоб почати слухати порт, а опитувати його ззовні — марнувати виклики. Запускайте його з wait_for_port: RunCommand відповідає, щойно щось слухає цей порт, а команда працює далі, тож один виклик запускає сервер і каже, що він піднявся. Потім відкрийте порт публічно або дайте своїй сторінці токен для нього: порти й прев’ю.

Копіюйте пісочницю для паралельних спроб

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

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

Вартість

Дайте пісочниці агента ставати на паузу, а не зупинятися

Пісочниця агента здебільшого чекає, а зупинка завершує її процеси: сервер розробки, 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 з новим розміром перезапускає пісочницю RUNNING у ВМ цього розміру, зі збереженими файлами, приблизно за 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 — щоб звертатися до однієї: унікальна в робочому просторі, з a-z, 0-9 і «-», не довша за 63 символи, а ListSandboxes з name знаходить її id.

Запитання

Пісочницю в простої краще зупинити чи поставити на паузу?

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

Як зробити, щоб пісочниці стартували швидше?

Збережіть своє середовище як шаблон, щоб під час запуску нічого не встановлювалося: пісочниця з нього запускається приблизно за 0,22 с з вашими пакетами й образами Docker.

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

Збережіть кожен ключ як секрет робочого простору з його хостами й прив’яжіть до нього змінну середовища. Пісочниця бачить заглушку, а проксі вихідного трафіку додає справжній ключ до запитів до цих хостів.

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

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

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

Пробний період на 7 днів із використанням на 1 $ і 4 vCPU, потрібна картка. Далі — тариф від 20 $ на місяць, який включає стільки ж використання.

Почати пробний період