Polski
Menu dokumentacji

Dokumentacja Agent Sandboxes · Pojęcia

Dobre praktyki Pethost Agent Sandboxes

Zaktualizowano · 8 min czytania

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.

W skrócie
  • Szybkość: zapisz swoje środowisko jako szablon, uruchamiaj serwery z wait_for_port i 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 z request_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

  1. działa
  2. wstrzymany
  3. działa
  4. wstrzymany

Sandbox użytkownika w twojej aplikacjiWstrzymuje się, a po pół godzinie zatrzymuje

  1. działa
  2. wstrzymany
  3. zatrzymany

Podgląd, który zasypiaBudzi się przy każdej wizycie

  1. wstrzymany
  2. działa
  3. wstrzymany
  4. działa
  5. wstrzymany

Zadanie wsadoweDziała, a potem jest usuwane

  1. działa
  2. zatrzymany
  3. usunięty
  • RUNNING
  • PAUSED
  • STOPPED
  • DELETED
Cztery zadania w ciągu doby, każde z własnym cyklem życia. Wartości są w cyklu życia i bezczynności.

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.

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"}'

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.

Zacznij okres próbny