Polski
Menu dokumentacji

Dokumentacja Agent Sandboxes · Zadania

Sterowanie komputerem: Chrome na pulpicie w sandboxie

Zaktualizowano · 5 min czytania

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.

W skrócie
  • 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 ControlDesktop albo linku do pulpitu, w kilka sekund, i wcześniej nic nie kosztują.
  • Podgląd na żywo: CreateLink z desktop albo view_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.

Python
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
TypeScript
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);
Go
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)
Rust
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.

Python
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
TypeScript
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);
Go
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)
Rust
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.

Python
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…
TypeScript
const live = await sandboxes.createLink({ sandboxId, desktop: { viewOnly: true } });
console.log(live.url);
Go
live, err := client.CreateLink(ctx, &sandboxes.CreateLinkRequest{SandboxID: id, Target: sandboxes.CreateLinkDesktop{ViewOnly: true}})
if err != nil {
	log.Fatal(err)
}
fmt.Println(live.URL)
Rust
let live = sandboxes
    .create_link(CreateLinkRequest {
        sandbox_id: id.clone(),
        target: Some(CreateLinkRequestTarget::Desktop(DesktopLink { view_only: true })),
        ..Default::default()
    })
    .await?;
println!("{}", live.url);
CLI
$ pethost sandbox open api-dev --desktop --view-only
✓ Opened the screen of e9bprbw1hovj6sw5 in your browser.

Akcje

AkcjaCo robi
clickW 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_mousePrzesuwa wskaźnik do punktu.
dragOd pierwszego punktu path do ostatniego, z wciśniętym lewym przyciskiem.
scrollW punkcie, down skoków kółka (ujemne przewija w górę) i right (ujemne przewija w lewo).
type_textWpisuje tekst.
press_keysKlawisze wciśnięte razem: Return, ctrl+c, ctrl+shift+t.
wait_msCzeka, 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.
  • failure to OFF_SCREEN: punkt jest poza 1280×800. Bierz współrzędne z ostatniego zrzutu ekranu.
  • failure to UNKNOWN_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_EXHAUSTED bez LimitReached: ControlDesktop liczy 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.

Zacznij okres próbny