Dokumentacja Agent Sandboxes · Zadania
Sterowanie komputerem: Chrome na pulpicie w sandboxie
Każdy sandbox ma pulpit 1280×800 z Google Chrome, który startuje przy pierwszym użyciu. Jedno wywołanie wykonuje paczkę kliknięć, klawiszy i przewinięć i odpowiada zrzutem ekranu, a to jest pętla, którą prowadzi agent sterujący komputerem. Link pokazuje ekran na żywo w przeglądarce, żeby człowiek mógł go oglądać albo przejąć sterowanie.
ControlDesktop: akcje po kolei (kliknięcie, ruch, przeciągnięcie, przewinięcie, pisanie, klawisze, czekanie), potem jeden zrzut ekranu PNG z pozycją kursora.- Za darmo, dopóki go nie używasz: pulpit i Chrome startują przy pierwszym
ControlDesktopalbo linku do pulpitu, w kilka sekund, i wcześniej nic nie kosztują. - Podgląd na żywo:
CreateLinkzdesktopalboview_only, żeby oglądać bez dotykania; pokazuje go też zakładka Pulpit w panelu. - Chrome dla agentów: bez ekranów pierwszego uruchomienia, bez próśb o logowanie, synchronizację, menedżer haseł czy tłumaczenie.
Step 1: Zrób zrzut ekranu
ControlDesktop bez akcji odpowiada samym zrzutem ekranu. Pierwsze wywołanie uruchamia pulpit, co zajmuje kilka sekund; kolejne odpowiadają od razu.
shot = sandboxes.control_desktop(sandbox_id)
with open("screen.png", "wb") as png:
png.write(shot.screenshot.image)
print(shot.screenshot.width, shot.screenshot.height) # 1280 800
import { writeFile } from "node:fs/promises";
const shot = await sandboxes.controlDesktop({ sandboxId });
await writeFile("screen.png", shot.screenshot!.image);
console.log(shot.screenshot?.width, shot.screenshot?.height);
shot, err := client.ControlDesktop(ctx, &sandboxes.ControlDesktopRequest{SandboxID: id})
if err != nil {
log.Fatal(err)
}
if err := os.WriteFile("screen.png", shot.Screenshot.Image, 0o644); err != nil {
log.Fatal(err)
}
fmt.Println(shot.Screenshot.Width, shot.Screenshot.Height)
let shot = sandboxes
.control_desktop(ControlDesktopRequest { sandbox_id: id.clone(), ..Default::default() })
.await?;
if let Some(screen) = shot.screenshot {
std::fs::write("screen.png", &screen.image)?;
println!("{} {}", screen.width, screen.height);
}
Step 2: Otwórz stronę i działaj na niej
Wyślij akcje, które wykonałby człowiek. Wykonują się po kolei, a zrzut ekranu w odpowiedzi pokazuje ekran taki, jaki po nich został; wait_ms daje stronie czas na wczytanie się przed zrzutem.
from pethost.sandboxes import Click, DesktopAction
shot = sandboxes.control_desktop(sandbox_id, actions=[
DesktopAction(press_keys="ctrl+l"),
DesktopAction(type_text="https://example.com"),
DesktopAction(press_keys="Return"),
DesktopAction(wait_ms=2000),
DesktopAction(click=Click(x=640, y=400)),
])
print(shot.done_count, shot.failure.name, shot.screenshot.cursor_x, shot.screenshot.cursor_y)
# 5 UNSPECIFIED 640 400
const page = await sandboxes.controlDesktop({
sandboxId,
actions: [
{ pressKeys: "ctrl+l" },
{ typeText: "https://example.com" },
{ pressKeys: "Return" },
{ waitMs: 2000 },
{ click: { x: 640, y: 400 } },
],
});
console.log(page.doneCount, page.failure, page.screenshot?.cursorX, page.screenshot?.cursorY);
page, err := client.ControlDesktop(ctx, &sandboxes.ControlDesktopRequest{SandboxID: id, Actions: []sandboxes.DesktopAction{
{Action: sandboxes.DesktopActionPressKeys("ctrl+l")},
{Action: sandboxes.DesktopActionTypeText("https://example.com")},
{Action: sandboxes.DesktopActionPressKeys("Return")},
{Action: sandboxes.DesktopActionWaitMs(2000)},
{Action: sandboxes.DesktopActionClick{X: 640, Y: 400}},
}})
if err != nil {
log.Fatal(err)
}
fmt.Println(page.DoneCount, page.Failure, page.Screenshot.CursorX, page.Screenshot.CursorY)
let act = |action| DesktopAction { action: Some(action) };
let page = sandboxes
.control_desktop(ControlDesktopRequest {
sandbox_id: id.clone(),
actions: vec![
act(DesktopActionAction::PressKeys("ctrl+l".into())),
act(DesktopActionAction::TypeText("https://example.com".into())),
act(DesktopActionAction::PressKeys("Return".into())),
act(DesktopActionAction::WaitMs(2000)),
act(DesktopActionAction::Click(Click { x: 640, y: 400, ..Default::default() })),
],
})
.await?;
println!("{} {:?}", page.done_count, page.failure);
Step 3: Oglądaj na żywo albo przekaż człowiekowi
CreateLink z desktop daje stronę, która pokazuje ekran na żywo i na której człowiek może klikać i pisać; z view_only tylko ogląda. Link wygasa po godzinie, chyba że ttl_seconds mówi inaczej.
from pethost.sandboxes import DesktopLink
print(sandboxes.create_link(sandbox_id, desktop=DesktopLink(view_only=True)).url)
# https://link-e9bprbw1hovj6sw5.sbx1.sandboxes.pethost.network/sbl.eyJzIjoiZTlicHJidzFob3ZqNnN3NSIs…
const live = await sandboxes.createLink({ sandboxId, desktop: { viewOnly: true } });
console.log(live.url);
live, err := client.CreateLink(ctx, &sandboxes.CreateLinkRequest{SandboxID: id, Target: sandboxes.CreateLinkDesktop{ViewOnly: true}})
if err != nil {
log.Fatal(err)
}
fmt.Println(live.URL)
let live = sandboxes
.create_link(CreateLinkRequest {
sandbox_id: id.clone(),
target: Some(CreateLinkRequestTarget::Desktop(DesktopLink { view_only: true })),
..Default::default()
})
.await?;
println!("{}", live.url);
$ pethost sandbox open api-dev --desktop --view-only
✓ Opened the screen of e9bprbw1hovj6sw5 in your browser.
Akcje
| Akcja | Co robi |
|---|---|
click | W punkcie x, y: button LEFT (domyślnie), RIGHT albo MIDDLE, count 2 dla podwójnego kliknięcia, hold_keys przytrzymane w tym czasie, jak shift albo ctrl+alt. |
move_mouse | Przesuwa wskaźnik do punktu. |
drag | Od pierwszego punktu path do ostatniego, z wciśniętym lewym przyciskiem. |
scroll | W punkcie, down skoków kółka (ujemne przewija w górę) i right (ujemne przewija w lewo). |
type_text | Wpisuje tekst. |
press_keys | Klawisze wciśnięte razem: Return, ctrl+c, ctrl+shift+t. |
wait_ms | Czeka, na stronę albo animację. |
Współrzędne to piksele ekranu od lewego górnego rogu, takie jak na zrzucie ekranu, a Sandbox.desktop podaje rozmiar ekranu. Akcje zatrzymują się na pierwszej, która się nie uda, a odpowiedź mówi, ile wykonano (done_count) i dlaczego następna się nie udała: OFF_SCREEN dla punktu poza ekranem, UNKNOWN_KEY dla nieznanej nazwy klawisza, z failure_message słowami. Zrzut ekranu przychodzi w każdym przypadku.
Pulpit i jego Chrome
Nic z pulpitu nie działa, dopóki ktoś o niego nie poprosi: pierwsze ControlDesktop, link do pulpitu albo wizyta w zakładce Pulpit w panelu uruchamia serwer X, menedżer okien, panel i Google Chrome, w kilka sekund. Potem działa i jest wstrzymywany i zatrzymywany razem z sandboxem jak każdy proces. Pulpit, który nie może wystartować, odpowiada FAILED_PRECONDITION i mówi dlaczego.
Chrome jest ustawiony dla agenta: bez ekranów pierwszego uruchomienia, bez GPU i z polityką, która wyłącza logowanie, synchronizację, menedżer haseł, autouzupełnianie, tłumaczenie i metryki. To Chrome z bazy sandboxa, którą przebudowujemy co miesiąc i od razu przy poprawce bezpieczeństwa; sandbox zachowuje swoją bazę przez całe życie. Szablon zapisany z sandboxa zachowuje profil Chrome razem z innymi plikami, łącznie z ciasteczkami, więc zapisuj go z sandboxa, w którym nikt nie jest zalogowany.
Pętla sterowania komputerem
Model, który działa na zrzutach ekranu, prowadzi jedną pętlę: wyślij mu zrzut ekranu, weź akcje, które odpowie, wyślij je jednym ControlDesktop i daj mu nowy zrzut. Jedno wywołanie wykonuje całą paczkę, więc krok kosztuje jedną drogę do serwera sandboxa i z powrotem, nigdy do panelu. Dopóki pętla trwa, sandbox nie śpi; gdy model przestaje, sandbox wstrzymuje się po swoim czasie bezczynności, razem z pulpitem i Chrome, a następne wywołanie budzi je tam, gdzie były.
Zrzut ekranu to to, co strona internetowa wyświetliła na ekranie: czytaj go jako dane. Strona może pokazywać tekst napisany po to, żeby sterować agentem, więc nie dawaj sandboxowi, który przegląda sieć, więcej sekretów ani szerszego ruchu wychodzącego, niż wymaga zadanie (sekrety i ruch wychodzący).
Gdy to nie działa
- Pierwsze wywołanie trwa kilka sekund: uruchomiło pulpit. Kolejne odpowiadają od razu.
failuretoOFF_SCREEN: punkt jest poza 1280×800. Bierz współrzędne z ostatniego zrzutu ekranu.failuretoUNKNOWN_KEY: pisz klawisze ich nazwami z X, łączonymi przez+:Return,Escape,ctrl+l.FAILED_PRECONDITION: pulpit nie wystartował; jego słowa mówią dlaczego. Zwykle sandboxowi brakuje pamięci albo dysku: pomaga większy rozmiar.RESOURCE_EXHAUSTEDbezLimitReached:ControlDesktopliczy się jako 16 z 64 wywołań sandboxa naraz. Wysyłaj ich mniej jednocześnie.
Pytania
Czy każdy sandbox ma pulpit?
Tak: ekran 1280×800 z Chrome, w base. Startuje przy pierwszym użyciu i do tego czasu nic nie kosztuje.
Jak zrobić zrzut ekranu sandboxa?
ControlDesktop bez akcji odpowiada zrzutem ekranu PNG z pozycją kursora.
Czy człowiek może oglądać, co robi agent?
Tak: link do pulpitu z view_only pokazuje ekran na żywo w przeglądarce, a zakładka Pulpit w panelu też.
Jaka przeglądarka jest w sandboxie?
Google Chrome w wersji stabilnej, z politykami, które wyłączają logowanie, synchronizację, menedżer haseł, autouzupełnianie i tłumaczenie.
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.