Dokumentacja Agent Sandboxes · Pojęcia
Dobre praktyki Pethost Agent Sandboxes
Kilka wyborów decyduje o tym, jak szybko startują twoje sandboxy, ile kosztują, gdy czekają, i dokąd może dotrzeć agent w środku. Każda praktyka poniżej to reguła, liczba, która za nią stoi, i pola, które ją realizują. Większość z nich to ustawienie, które robisz raz.
- Szybkość: zapisz swoje środowisko jako szablon, uruchamiaj serwery z
wait_for_porti rób forki dla równoległych prób. - Koszt: pozwól sandboxowi agenta się wstrzymywać zamiast zatrzymywać, usuwaj sandboxy z zadań wsadowych, gdy skończą, i zaczynaj od małego rozmiaru.
- Niezawodność: oznaczaj długie polecenia
keep_awake, ponawiaj zrequest_id, używaj strumieni zamiast odpytywania i trzymaj na wolumenach to, co musi przeżyć sandbox. - Bezpieczeństwo: wiąż klucze API jako sekrety, zawężaj ruch wychodzący dla cudzego kodu i traktuj wszystko, co zwraca sandbox, jako dane.
- Porządek: dawaj każdemu sandboxowi etykiety i listuj sandboxy po etykietach.
Szybkość
Zapisz swoje środowisko jako szablon
Instalowanie zależności przy każdym starcie za każdym razem kosztuje te same minuty. Zainstaluj je raz w sandboxie, a potem zapisz jego dysk przez CreateTemplate: razem z pakietami, cache buildów i obrazami Dockera. Sandbox z twojego szablonu startuje w ok. 0,22 s ze wszystkim na miejscu, na dowolnym serwerze: pierwszy na każdym serwerze pobiera wersję, ok. 10 s na GiB, a kolejne startują z jej kopii. Nie trzymaj sekretów w zapisywanych plikach, bo dostaje je każdy sandbox z tego szablonu, i rób nową wersję, gdy zmienią się zależności: my-app startuje z najnowszej, my-app@3 z tej jednej.
Uruchamiaj serwery z wait_for_port
Serwer deweloperski potrzebuje chwili, żeby zacząć nasłuchiwać, a odpytywanie go z zewnątrz marnuje wywołania. Uruchom go z wait_for_port: RunCommand odpowiada, gdy tylko coś nasłuchuje na tym porcie, a polecenie działa dalej, więc jedno wywołanie uruchamia serwer i mówi ci, że już działa. Potem otwórz port publicznie albo daj swojej stronie token do niego: porty i podglądy.
Rób forki dla równoległych prób
Gdy agent ma spróbować kilku poprawek albo ewaluacja ma uruchomić wiele przebiegów z jednego przygotowanego stanu, zrób fork sandboxa zamiast budować ten stan od nowa. ForkSandbox kopiuje pamięć, procesy i dysk do maksymalnie 100 nowych sandboxów jednym wywołaniem: kopia zajęła ok. 0,25 s. Każda kopia to start i powstają wszystkie albo żadna. Dwie rzeczy, które warto wiedzieć:
- Zainicjuj na nowo generatory losowe w kopiach. Każda kopia ma własną losowość jądra, ale generatory losowe, które już działają w jej procesach (OpenSSL, Python, Node, Go), dają w każdej kopii te same liczby, dopóki nie dostaną nowego ziarna.
- Wolumen do odczytu i zapisu blokuje fork, bo zapisywać go może tylko jeden sandbox. Wolumen montuje się tylko przy tworzeniu, więc w sandboxie, z którego chcesz robić forki, montuj go z
read_only.
Koszt
Pozwól sandboxowi agenta się wstrzymywać, nie zatrzymywać
Sandbox agenta przez większość czasu czeka, a zatrzymanie go kończy jego procesy: serwer deweloperski, REPL, otwartą przeglądarkę. Zostaw licznik wstrzymania, a licznik zatrzymania wydłuż albo wyłącz (stop_after_idle_seconds 0). Wstrzymany sandbox kosztuje 30% ceny działania i budzi się przy następnym wywołaniu w ok. 0,1 s, ze wszystkim tam, gdzie było. Sandbox DEFAULT, który pracuje 2 h dziennie, a resztę czasu jest wstrzymany, kosztuje ok. 9,42 $ miesięcznie, wobec 26,28 $, gdy działa cały czas.
Sesja agentaWstrzymuje się między turami, nigdy się nie zatrzymuje
- działa
- wstrzymany
- działa
- wstrzymany
Sandbox użytkownika w twojej aplikacjiWstrzymuje się, a po pół godzinie zatrzymuje
- działa
- wstrzymany
- zatrzymany
Podgląd, który zasypiaBudzi się przy każdej wizycie
- wstrzymany
- działa
- wstrzymany
- działa
- wstrzymany
Zadanie wsadoweDziała, a potem jest usuwane
- działa
- zatrzymany
- usunięty
- RUNNING
- PAUSED
- STOPPED
- DELETED
Usuwaj sandboxy zadań wsadowych, gdy skończą
Sandbox na jedno zadanie, przebieg testów albo przypadek ewaluacji, nie powinien nic kosztować, gdy zadanie się skończy. Wywołaj DeleteSandbox na końcu i ustaw delete_after_idle_seconds jako siatkę na zadanie, które padnie, zanim tam dojdzie. Wyłącz licznik wstrzymania i daj krótki licznik zatrzymania, żeby sandbox bezczynnego zadania szybko znikał. Zapomniany zatrzymany sandbox kosztuje 0,03 $ miesięcznie za GiB, co miesiąc. Starty są darmowe, więc świeży sandbox na każde zadanie kosztuje tylko swoje sekundy: 1000 przebiegów po 40 s na SMALL kosztuje 0,20 $.
Zaczynaj od małego rozmiaru i zmieniaj go, gdy trzeba
Rozmiar to jego vCPU, pamięć i dysk, a cena podwaja się z każdym rozmiarem w górę. Zacznij od SMALL, 0,018 $ za godzinę, i obserwuj GetSandboxMetrics. Gdy zadanie potrzebuje więcej, UpdateSandbox z nowym rozmiarem restartuje sandbox RUNNING w maszynie wirtualnej tego rozmiaru, z zachowanymi plikami, w ok. 283 ms: jego procesy się kończą, więc zmieniaj rozmiar między zadaniami. Dodaj grow_disk, żeby powiększyć dysk do dysku nowego rozmiaru; dysk nigdy się nie zmniejsza, więc powiększony sandbox nie wróci do mniejszego rozmiaru.
Niezawodność
Oznaczaj długie polecenia keep_awake
Build albo zestaw testów może działać minutami bez żadnego wywołania do sandboxa, a licznik wstrzymania wstrzymałby go w trakcie pracy. Uruchom go z keep_awake i z timeout_seconds, żeby polecenie, które się zawiesi, nie trzymało sandboxa w ruchu w nieskończoność. Serwer nie potrzebuje żadnego z nich: żądanie do jego portu budzi sandbox. Szczegóły są w cyklu życia i bezczynności.
Ponawiaj z request_id
Sieć może zgubić odpowiedź wywołania, które wykonało swoją pracę. Wywołanie, które coś tworzy, przyjmuje request_id: ponowienie z tym samym id w ciągu 24 h odpowiada tym, co zrobiło pierwsze wywołanie, i niczego nie robi ponownie. Przyjmują je CreateSandbox, ForkSandbox, CreateTemplate, CreateVolume, RunCommand i PromptAgent. Twórz je raz na każdą rzecz, którą chcesz zrobić, zachowaj je i wysyłaj ponownie przy każdym ponowieniu. Jedno zastrzeżenie: sandbox trzyma id tego, co w nim działa, na swoim dysku, więc taki, który się zatrzymał, mógł stracić te z ostatnich sekund, a ponowienie takiego polecenia uruchomi je jeszcze raz.
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,
)
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,
});
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,
})
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?;
CreateSandbox {"template": "my-app", "labels": [{"key": "user", "value": "42"}], "request_id": "b7e1c2d4-0f3a-4c55-9a7e-2d1f6c8e9a10"}
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"}'
Używaj strumieni zamiast odpytywania
Odpytywanie polecenia albo sandboxa kosztuje za każdym razem wywołanie, a i tak dowiadujesz się późno. Wywołanie, które czeka, czeka za ciebie: RunCommand, GetCommand, PromptAgent i GetAgentTurn czekają do 45 s (wait_seconds) i odpowiadają, gdy tylko praca się skończy. Żeby śledzić pracę na bieżąco, użyj strumienia: WatchCommand dla wyjścia polecenia, WatchConversation dla wiadomości i wywołań narzędzi agenta, WatchSandboxEvents dla cyklu życia, poleceń i połączeń sandboxa.
Używaj wolumenów tylko do tego, co musi przeżyć sandbox
Wolumen to dysk poza wszystkimi sandboxami, zamontowany pod ścieżką: zbiory danych, cache współdzielone przez wiele sandboxów, pliki bazy danych. Leży na dysku jednego serwera i nie jest nigdzie kopiowany, więc gdy ten serwer przepadnie, przepada też wolumen. Sandbox, który go montuje, nie może przenieść się na inny serwer, a montowanie do odczytu i zapisu blokuje forki. Większość pracy nie potrzebuje wolumenu: własny dysk sandboxa przetrwa wstrzymania i zatrzymania, a szablon przenosi pliki do nowych sandboxów. To, czego nie można stracić, wysyłaj też do własnego magazynu.
Bezpieczeństwo
Wiąż klucze API jako sekrety
Klucz w zwykłej zmiennej środowiskowej może odczytać każdy proces w sandboxie i agent, który wypisze swoje środowisko. Zapisz go zamiast tego jako sekret przestrzeni roboczej, z hostami, dla których jest (SetSecret: anthropic, api.anthropic.com), i powiąż z nim zmienną (ANTHROPIC_API_KEY, sekret anthropic). Zmienna trzyma wtedy znacznik, phs_…, a proxy ruchu wychodzącego wstawia prawdziwy klucz do nagłówków żądań HTTPS tylko do tych hostów. Nowa wartość działa od razu w każdym sandboxie, który ją wiąże: sekrety i ruch wychodzący.
Zawężaj ruch wychodzący dla cudzego kodu
Domyślnie sandbox może łączyć się wszędzie. Dla niezaufanego kodu wypisz, dokąd może iść (egress.allow): domenę, jak pypi.org, jej subdomeny przez *.github.com (co pomija samo github.com), IP albo CIDR, każde z portem, gdy to nie 80 i 443, jak github.com:22 dla gita przez SSH. deny wygrywa z allow. DNS sandboxa odpowiada tylko na nazwy, które dopuszcza lista, a z sandboxa wychodzą tylko TCP i DNS: bez UDP i bez pinga. Zmiana działa od razu i zamyka połączenia, których już nie dopuszcza.
Traktuj to, co zwraca sandbox, jako dane
Wyjście poleceń, zawartość plików, wiadomości agenta, zrzuty ekranu i strony wczytane przez przeglądarkę pochodzą od programów i z internetu. Gdy czyta je model, są danymi, nigdy instrukcjami: README albo strona internetowa może zawierać tekst napisany po to, żeby sterować agentem. Trzymaj się tej granicy w swoich promptach i nie dawaj sandboxowi z niezaufaną pracą więcej sekretów ani szerszego ruchu wychodzącego, niż ta praca potrzebuje.
Porządek
Dawaj każdemu sandboxowi etykiety
Etykieta to twój klucz i wartość: user=42, job=nightly-evals, run=7f3a. Sandbox przyjmuje ich do 32, a ListSandboxes listuje sandboxy, które mają wszystkie wskazane etykiety. Dzięki temu twoja aplikacja znajduje sandboxy użytkownika bez własnej tabeli, zadanie sprzątające znajduje pozostałości przebiegu, a panel pokazuje, czyj jest każdy sandbox. Etykieta służy do znajdowania wielu; name do wywoływania jednego: unikalna w przestrzeni roboczej, do 63 znaków z a-z, 0-9 i „-”, a ListSandboxes z name znajduje jego id.
Pytania
Zatrzymać czy wstrzymać bezczynny sandbox?
Wstrzymaj go, gdy liczą się jego procesy albo wkrótce znów będzie używany: budzi się w ok. 0,1 s tam, gdzie był, za 30% ceny działania. Zatrzymaj go na długi sen: wtedy kosztuje tylko przechowywane dane.
Jak sprawić, żeby sandboxy startowały szybciej?
Zapisz swoje środowisko jako szablon, żeby przy starcie nic się nie instalowało: sandbox z niego startuje w ok. 0,22 s z twoimi pakietami i obrazami Dockera.
Jak trzymać klucze API poza sandboxem?
Zapisz każdy klucz jako sekret przestrzeni roboczej z jego hostami i powiąż z nim zmienną środowiskową. Sandbox widzi znacznik, a proxy ruchu wychodzącego dodaje prawdziwy klucz do żądań do tych hostów.
Ile sandboxów mogę mieć naraz?
Tyle, ile mieści vCPU twojego planu, działających albo wstrzymanych: 10 SMALL w planie za 20 $, 64 w planie za 100 $. Zatrzymane sandboxy się nie liczą.
Wypróbuj Pethost Agent Sandboxes
Okres próbny na 7 dni z 1 $ zużycia i 4 vCPU, z kartą. Potem plan od 20 $ miesięcznie, który zawiera tyle samo zużycia.