Doku zu Agent Sandboxes · Aufgaben
Computer Use: Chrome auf einem Desktop in einer Sandbox
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.
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
ControlDesktopoder Desktop-Link, in einigen Sekunden, und kosten vorher nichts. - Eine Live-Ansicht:
CreateLinkmitdesktop, oderview_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.
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: 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.
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: 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.
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.
Die Aktionen
| Aktion | Was sie tut |
|---|---|
click | Bei 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_mouse | Bewegt den Zeiger zu einem Punkt. |
drag | Vom ersten Punkt von path bis zum letzten, mit gedrückter linker Taste. |
scroll | An einem Punkt, down Klicks des Mausrads (negativ scrollt nach oben) und right (negativ scrollt nach links). |
type_text | Tippt den Text. |
press_keys | Tasten, zusammen gedrückt: Return, ctrl+c, ctrl+shift+t. |
wait_ms | Wartet, 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.
failureistOFF_SCREEN: Ein Punkt liegt außerhalb von 1280×800. Nimm die Koordinaten aus dem letzten Screenshot.failureistUNKNOWN_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_EXHAUSTEDohneLimitReached: EinControlDesktopzä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.