Dokumentacja Agent Sandboxes · Referencja
Błędy API sandboxów i co z nimi zrobić
Co oznacza każda odmowa API i co zrobić dalej, według jej kodu i typowanego szczegółu: dla gałęzi w programie i następnego kroku agenta. Rozgałęziaj po kodzie i szczególe, nigdy po komunikacie, który jest zdaniem dla ludzi i może się zmienić.
Odczytywanie błędu w każdym SDK
Nieudane wywołanie rzuca wyjątek, odrzuca obietnicę albo zwraca błąd z kodem, komunikatem API i, jeśli jest, typowanym szczegółem. Python rzuca podklasę SandboxesError dla każdego kodu (AlreadyExistsError, FailedPreconditionError…) ze szczegółem w detail; TypeScript odrzuca z SandboxesError, którego szczegół jest osobnym polem (error.nameTaken); Go zwraca *sandboxes.Error z polem na każdy szczegół; Error w Rust ma code() i details(). Tutaj zajęta nazwa oznacza ponowne użycie sandboxa, który ją ma, a zatrzymany sandbox zostaje wznowiony:
from pethost.sandboxes import AlreadyExistsError, FailedPreconditionError, NameTaken, Stopped
try:
sandbox = sandboxes.create_sandbox("base", name="api-dev")
except AlreadyExistsError as error:
if not isinstance(error.detail, NameTaken):
raise
sandbox = sandboxes.get_sandbox(error.detail.sandbox_id) # the sandbox that has the name
try:
command = sandboxes.run_command(sandbox.sandbox_id, command="make test")
except FailedPreconditionError as error:
if not isinstance(error.detail, Stopped):
raise
sandboxes.resume_sandbox(sandbox.sandbox_id)
command = sandboxes.run_command(sandbox.sandbox_id, command="make test")
const created = await sandboxes.createSandbox({ template: "base", name: "api-dev" }).catch(async (error) => {
if (!(error instanceof SandboxesError) || !error.nameTaken) throw error;
return sandboxes.getSandbox({ sandboxId: error.nameTaken.sandboxId }); // the sandbox that has the name
});
const test = { sandboxId: created.sandboxId, command: "make test" };
const command = await sandboxes.runCommand(test).catch(async (error) => {
if (!(error instanceof SandboxesError) || !error.stopped) throw error;
await sandboxes.resumeSandbox({ sandboxId: created.sandboxId });
return sandboxes.runCommand(test);
});
created, err := client.CreateSandbox(ctx, &sandboxes.CreateSandboxRequest{Template: "base", Name: "api-dev"})
if e, ok := errors.AsType[*sandboxes.Error](err); ok && e.NameTaken != nil {
created, err = client.GetSandbox(ctx, &sandboxes.GetSandboxRequest{SandboxID: e.NameTaken.SandboxID})
}
if err != nil {
log.Fatal(err)
}
test := &sandboxes.RunCommandRequest{SandboxID: created.SandboxID, Command: "make test"}
command, err := client.RunCommand(ctx, test)
if e, ok := errors.AsType[*sandboxes.Error](err); ok && e.Stopped != nil {
if _, err = client.ResumeSandbox(ctx, &sandboxes.ResumeSandboxRequest{SandboxID: created.SandboxID}); err == nil {
command, err = client.RunCommand(ctx, test)
}
}
if err != nil {
log.Fatal(err)
}
fmt.Println(command.State)
use pethost::sandboxes::ErrorDetail;
let request = CreateSandboxRequest { template: "base".into(), name: "api-dev".into(), ..Default::default() };
let created = match sandboxes.create_sandbox(request).await {
Ok(sandbox) => sandbox,
Err(error) => match error.details().iter().find_map(|detail| match detail {
ErrorDetail::NameTaken(taken) => Some(taken.sandbox_id.clone()),
_ => None,
}) {
Some(sandbox_id) => sandboxes.get_sandbox(GetSandboxRequest { sandbox_id, ..Default::default() }).await?,
None => return Err(error.into()),
},
};
let test = RunCommandRequest { sandbox_id: created.sandbox_id.clone(), command: "make test".into(), ..Default::default() };
let command = match sandboxes.run_command(test.clone()).await {
Err(error) if error.details().iter().any(|detail| matches!(detail, ErrorDetail::Stopped(_))) => {
let resume = ResumeSandboxRequest { sandbox_id: created.sandbox_id.clone(), ..Default::default() };
sandboxes.resume_sandbox(resume).await?;
sandboxes.run_command(test).await?
}
other => other?,
};
println!("{:?}", command.state);
Odmowy z typowanym szczegółem
| Kod i szczegół | Co oznacza | Co zrobić |
|---|---|---|
FAILED_PRECONDITION + Stopped | Wywołanie do sandboxa STOPPED, logowanie SSH albo żądanie do portu, a jego cykl życia nie ma wake_when_stopped. | ResumeSandbox, a potem powtórz wywołanie. |
UNAVAILABLE + Restoring | Jego dysk jest pobierany z magazynu obiektów na potrzeby startu; dotąd fetched_bytes z total_bytes, ok. 10 s na GiB. | Poczekaj, a potem powtórz. |
UNAVAILABLE + NoCapacity | Żaden serwer nie ma teraz dla niego miejsca; bound mówi, czego zabrakło ostatniemu, a fork_count przy forku, ile kopii się zmieści. | Spróbuj później albo zrób fork na fork_count kopii lub mniej. |
RESOURCE_EXHAUSTED + LimitReached | Limit planu, nazwany przez limit razem z max: vcpus, largest_size, volume_gib, template_versions, template_gib albo secrets. | Usuń albo zatrzymaj to, co go zajmuje, albo wybierz większy plan. vCPU zajmują działające i wstrzymane sandboxy. |
RESOURCE_EXHAUSTED + LimitReached, starts_per_minute, _hour, _day | Za dużo startów w tym przesuwnym oknie: utworzeń, kopii z forków i startów zatrzymanych sandboxów. Starty są darmowe i ograniczone. | Powtórz o retry_time. Bez niego wywołanie prosi o więcej, niż pozwala okno: podziel je. |
FAILED_PRECONDITION + UsageUnpaid | Nic teraz nie płaci za przestrzeń roboczą: zużycie w planie się skończyło, a saldo jest puste. Działające i wstrzymane sandboxy zostały zatrzymane. | Właściciel doładowuje saldo albo zaczyna plan zamiast okresu próbnego, w panelu. Blokada znika w ciągu kilku sekund. |
FAILED_PRECONDITION + AgentSignIn | Agent kodujący nie może dotrzeć do swojego modelu: variable nazywa zmienną do powiązania, sign_in_command polecenie do uruchomienia zamiast tego. | Powiąż sekret z variable, poproś człowieka o uruchomienie sign_in_command w terminalu albo użyj OpenCode. |
FAILED_PRECONDITION + WorkspaceChoice | Wywołanie nie wskazuje przestrzeni roboczej, a token sięga kilku; workspaces je wymienia. | Wyślij workspace, jej id albo nazwę, w wywołaniu albo w kliencie. |
ALREADY_EXISTS + NameTaken | Tę nazwę ma inny nieusunięty sandbox przestrzeni roboczej; sandbox_id to ten sandbox. | Użyj tego sandboxa albo wybierz inną nazwę. |
Odmowy z samym kodem
| Kod | Co oznacza | Co zrobić |
|---|---|---|
INVALID_ARGUMENT | Pole jest błędne, a komunikat je nazywa i mówi, co przyjmuje; albo request_id przyszło ponownie z innymi polami. | Popraw pole. Nie ponawiaj bez zmian. |
NOT_FOUND | Nie ma takiego sandboxa, szablonu, wolumenu ani sekretu albo token do niego nie sięga. Od serwera sandboxa: sandbox przeniósł się na inny. | Sprawdź id. SDK same łączą się ponownie, gdy sandbox się przeniósł. |
FAILED_PRECONDITION | Stan nie pozwala na wywołanie, jak mówi komunikat: nowy rozmiar dla sandboxa PAUSED, sekret wciąż powiązany, wolumen wciąż zamontowany, szablon wciąż zapisywany, pulpit, który nie wystartował. | Najpierw zrób to, co mówi komunikat, a potem powtórz. |
ABORTED | Ustawienia sandboxa zmieniły się, odkąd je odczytano (if_revision). | Odczytaj go ponownie i wprowadź zmianę jeszcze raz. |
RESOURCE_EXHAUSTED | Bez LimitReached: sandbox obsługuje już 64 wywołań naraz albo wiadomość przekroczyła swój limit (1 MiB na żądanie, 17 MiB na WriteFiles). | Zakończ jakieś wywołanie albo poczekaj; duży plik przenieś przez link. |
UNAVAILABLE | Bez szczegółu: żaden serwer teraz nie odpowiada albo sandbox przenosi się na inny serwer. | Powtórz za chwilę. |
PERMISSION_DENIED | Token API nie ma dostępu do przestrzeni roboczej albo token zatwierdzony dla serwera MCP Agent Sandboxes wywołał inne API. Od serwera sandboxa: token dla innego serwera, po przeprowadzce. | Daj tokenowi dostęp do przestrzeni roboczej w Ustawieniach. SDK same łączą się ponownie po przeprowadzce. |
UNAUTHENTICATED | Tokena brakuje, ma literówkę, wygasł albo został unieważniony. Od serwera sandboxa: token połączenia, który wygasł albo został unieważniony (revoke_tokens). | Sprawdź PETHOST_TOKEN. SDK same proszą o nowy token połączenia. |
Wywołanie środowiska uruchomieniowego odrzucone przez serwer sandboxa z UNAUTHENTICATED, PERMISSION_DENIED albo NOT_FOUND niczego nie zrobiło. SDK i CLI raz ponownie wywołują ConnectSandbox i je powtarzają; twój własny program przez HTTP robi to samo.
Odpowiedzi, które mówią, że coś się nie udało
Niektóre wywołania się udają, a w odpowiedzi mówią, że część pracy się nie powiodła: wywołanie zrobiło, co mogło, a odpowiedź mówi, gdzie się zatrzymało.
| Odpowiedź | Wartości | Co zrobić |
|---|---|---|
WriteFilesResponse.failure | NOT_FOUND, PERMISSION_DENIED, NOT_A_DIRECTORY, IS_A_DIRECTORY, NO_SPACE, EDIT_NOT_FOUND, EDIT_AMBIGUOUS | Wykonano done_count zmian; popraw następną i wyślij resztę. |
ControlDesktopResponse.failure | OFF_SCREEN, UNKNOWN_KEY | Wykonano done_count akcji; zrzut ekranu pokazuje ekran po nich. |
Command.state | TIMED_OUT, STOPPED, LOST | LOST: sandbox stracił pamięć w trakcie działania polecenia; uruchom je ponownie. |
AgentTurn.state | FAILED, STOPPED, LOST | FAILED: failure_message mówi dlaczego. LOST: wyślij prompt ponownie. |
Sandbox.state_reason | CRASH, UNPAID, IDLE, MAINTENANCE | CRASH: state_message mówi dlaczego; uruchamia go tylko ResumeSandbox. |
Przez MCP WriteFiles albo ControlDesktop, które nie doszły do końca, są błędem narzędzia, z JSON-em takim, jakim odpowiada API.
Na porcie, przy linku i przez SSH
| Odpowiedź | Co oznacza | Co zrobić |
|---|---|---|
| 401 z portu | Port prywatny, a żądanie nie miało Pethost-Token, miało wygasły albo token innego portu. | Udostępnij port publicznie albo wyślij świeży token z CreateLink. |
| 503 „stopped: resume it” | Sandbox jest zatrzymany i nie budzi się na żądanie. SSH mówi te same słowa. | ResumeSandbox albo włącz wake_when_stopped. |
| 503 w trakcie przywracania | Jego dysk wraca z magazynu obiektów. | Poczekaj, a potem powtórz. |
| 403 od proxy ruchu wychodzącego | W sandboxie: jego lista ruchu wychodzącego nie dopuszcza hosta albo portu, a odpowiedź mówi, co odmówiło. | Dodaj host do egress.allow. |
| 421 Misdirected Request | W sandboxie: zwykłe żądanie HTTP do innego hosta niż ten, do którego otwarto połączenie. | Nic: klient otwiera nowe połączenie do tego hosta. |
Bezpieczne ponawianie
Wywołanie, które coś tworzy, przyjmuje request_id: CreateSandbox, ForkSandbox, CreateTemplate, CreateVolume, RunCommand i PromptAgent. Wyślij to samo id ponownie po przekroczeniu czasu albo zgubionej odpowiedzi, a ponowienie odpowie tym, co zrobiło pierwsze wywołanie, przez 24 h. Pozostałe wywołania, które coś zmieniają, są idempotentne same w sobie: wstrzymanie wstrzymanego sandboxa albo usunięcie usuniętego odpowiada jego obecnym stanem. Jedno zastrzeżenie: sandbox trzyma id swoich poleceń i tur na dysku, więc taki, który stracił pamięć, mógł stracić te z ostatnich sekund, a ponowienie takiego polecenia uruchomi je jeszcze raz.
Pytania
Co znaczy „stopped: resume it”?
Sandbox jest zatrzymany, a jego cykl życia nie budzi go przy wywołaniu. ResumeSandbox go uruchamia, z plikami takimi, jakie zostawił.
Dlaczego mój sandbox jest odrzucany z LimitReached?
Przestrzeń robocza osiągnęła limit swojego planu, który nazywa limit: zwykle vcpus, zajęte przez działające i wstrzymane sandboxy, albo okno startów, z retry_time.
Czy ponawiać UNAVAILABLE?
Tak, po chwili. Z NoCapacity trochę później; z Restoring, gdy dysk wróci.
Czy mogę parsować komunikat błędu?
Nie: rozgałęziaj po kodzie i typowanym szczególe. Komunikat to zdanie dla ludzi i może się zmienić.
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.