Deutsch
Menü der Doku

Doku zu Agent Sandboxes · Aufgaben

Computer Use: Chrome auf einem Desktop in einer Sandbox

Aktualisiert · 5 Min. Lesezeit

Jede Sandbox hat einen Desktop mit 1280×800 und Google Chrome, der bei der ersten Nutzung startet. Ein Aufruf erledigt einen Stapel aus Klicks, Tasten und Scrollen und antwortet mit einem Screenshot, genau die Schleife, die ein Computer-Use-Agent ausführt. Ein Link zeigt den Bildschirm live im Browser, damit eine Person zusieht oder übernimmt.

Kurz gesagt
  • ControlDesktop: Aktionen der Reihe nach (klicken, bewegen, ziehen, scrollen, tippen, Tasten drücken, warten), dann ein PNG-Screenshot mit der Position des Cursors.
  • Kostenlos bis zur Nutzung: Desktop und Chrome starten beim ersten ControlDesktop oder Desktop-Link, in einigen Sekunden, und kosten vorher nichts.
  • Eine Live-Ansicht: CreateLink mit desktop, oder view_only, um nur zuzusehen; der Tab „Desktop“ der Konsole zeigt sie auch.
  • Chrome für Agenten: keine Begrüßungsseiten, keine Fragen nach Anmeldung, Sync, Passwortmanager oder Übersetzung.

Step 1: Screenshot machen

ControlDesktop ohne Aktionen antwortet nur mit einem Screenshot. Der erste Aufruf startet den Desktop, was einige Sekunden dauert; die nächsten antworten sofort.

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: Seite öffnen und darauf handeln

Schick die Aktionen, die eine Person machen würde. Sie laufen der Reihe nach, und der Screenshot der Antwort zeigt den Bildschirm, wie sie ihn verlassen haben; wait_ms gibt einer Seite vorher Zeit zum Laden.

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: Live zusehen oder an eine Person übergeben

CreateLink mit desktop gibt eine Seite, die den Bildschirm live zeigt und auf der eine Person klicken und tippen kann; mit view_only sieht sie nur zu. Er läuft nach einer Stunde ab, außer ttl_seconds sagt etwas anderes.

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.

Die Aktionen

AktionWas sie tut
clickBei x, y: button LEFT (der Standard), RIGHT oder MIDDLE, count 2 für einen Doppelklick, hold_keys währenddessen gehalten, etwa shift oder ctrl+alt.
move_mouseBewegt den Zeiger zu einem Punkt.
dragVom ersten Punkt von path bis zum letzten, mit gedrückter linker Taste.
scrollAn einem Punkt, down Klicks des Mausrads (negativ scrollt nach oben) und right (negativ scrollt nach links).
type_textTippt den Text.
press_keysTasten, zusammen gedrückt: Return, ctrl+c, ctrl+shift+t.
wait_msWartet, auf eine Seite oder eine Animation.

Koordinaten sind die Pixel des Bildschirms von oben links, wie der Screenshot sie hat, und Sandbox.desktop gibt die Größe des Bildschirms. Die Aktionen halten bei der ersten an, die scheitert, und die Antwort sagt, wie viele erledigt wurden (done_count) und warum die nächste scheiterte: OFF_SCREEN für einen Punkt außerhalb des Bildschirms, UNKNOWN_KEY für einen Tastennamen, den sie nicht kennt, mit failure_message in Worten. Der Screenshot kommt in jedem Fall.

Der Desktop und sein Chrome

Nichts vom Desktop läuft, bis er gebraucht wird: Das erste ControlDesktop, der erste Desktop-Link oder Besuch im Tab „Desktop“ der Konsole startet einen X-Server, einen Fenstermanager, eine Leiste und Google Chrome, in einigen Sekunden. Danach läuft er und wird mit der Sandbox pausiert und gestoppt wie jeder Prozess. Ein Desktop, der nicht starten kann, antwortet FAILED_PRECONDITION und sagt, warum.

Chrome ist für einen Agenten eingerichtet: keine Begrüßungsseiten, keine GPU und eine Richtlinie, die Anmeldung, Sync, den Passwortmanager, Autofill, Übersetzung und Metriken abschaltet. Es ist das Chrome der Basis der Sandbox, die wir monatlich neu bauen und sofort bei einem Sicherheitsfix; eine Sandbox behält ihre Basis, solange sie lebt. Eine Vorlage, die aus einer Sandbox gespeichert wird, behält das Profil von Chrome mit den anderen Dateien, Cookies eingeschlossen, also speichere sie aus einer Sandbox, in der niemand angemeldet ist.

Eine Computer-Use-Schleife

Ein Modell, das auf Screenshots handelt, führt eine Schleife aus: Schick ihm den Screenshot, nimm die Aktionen, mit denen es antwortet, schick sie in einem ControlDesktop und gib ihm den neuen Screenshot. Ein Aufruf erledigt einen ganzen Stapel, also kostet ein Schritt einen Weg zum Server der Sandbox und zurück, nie zum Panel. Solange die Schleife läuft, bleibt die Sandbox wach; hört das Modell auf, pausiert die Sandbox nach ihrer Leerlaufzeit, Desktop und Chrome mit ihr, und der nächste Aufruf weckt sie dort, wo sie waren.

Ein Screenshot ist, was eine Webseite auf den Bildschirm gebracht hat: Lies ihn als Daten. Eine Seite kann Text zeigen, der geschrieben wurde, um einen Agenten zu lenken, also gib einer Sandbox, die surft, nicht mehr Secrets und keinen weiteren Egress, als die Aufgabe braucht (Secrets und Egress).

Wenn es nicht funktioniert

  • Der erste Aufruf dauert Sekunden: Er hat den Desktop gestartet. Die nächsten antworten sofort.
  • failure ist OFF_SCREEN: Ein Punkt liegt außerhalb von 1280×800. Nimm die Koordinaten aus dem letzten Screenshot.
  • failure ist UNKNOWN_KEY: Schreib Tasten mit ihren X-Namen, verbunden mit +: Return, Escape, ctrl+l.
  • FAILED_PRECONDITION: Der Desktop ist nicht gestartet; seine Worte sagen, warum. Meist fehlt der Sandbox RAM oder Disk: Eine größere Größe hilft.
  • RESOURCE_EXHAUSTED ohne LimitReached: Ein ControlDesktop zählt als 16 der 64 Aufrufe, die die Sandbox gleichzeitig bedient. Schick weniger zur selben Zeit.

Fragen

Hat jede Sandbox einen Desktop?

Ja: einen Bildschirm mit 1280×800 und Chrome, in base. Er startet bei der ersten Nutzung und kostet bis dahin nichts.

Wie mache ich einen Screenshot einer Sandbox?

ControlDesktop ohne Aktionen antwortet mit einem PNG-Screenshot samt Position des Cursors.

Kann eine Person zusehen, was der Agent tut?

Ja: Ein Desktop-Link mit view_only zeigt den Bildschirm live im Browser, und der Tab „Desktop“ der Konsole auch.

Welcher Browser ist in der Sandbox?

Google Chrome, stabil, mit Richtlinien, die Anmeldung, Sync, den Passwortmanager, Autofill und Übersetzung abschalten.

Pethost Agent Sandboxes ausprobieren

Eine Testphase von 7 Tagen mit 1 $ Verbrauch und 4 vCPUs, mit Karte. Danach ein Tarif ab 20 $ im Monat, der genauso viel Verbrauch enthält.

Testphase starten