Français
Menu de la documentation

Documentation Agent Sandboxes · Tâches

Computer use : Chrome sur un bureau dans une sandbox

Mis à jour le · 6 min de lecture

Chaque sandbox a un bureau 1280×800 avec Google Chrome, qui démarre la première fois que vous l’utilisez. Un appel fait une série de clics, de touches et de défilements, et répond avec une capture d’écran : c’est la boucle d’un agent de computer use. Un lien montre l’écran en direct dans un navigateur, pour qu’une personne le regarde ou prenne la main.

En bref
  • ControlDesktop : des actions dans l’ordre (cliquer, déplacer, glisser, faire défiler, taper, appuyer sur des touches, attendre), puis une capture d’écran PNG avec la position du pointeur.
  • Gratuit tant qu’il ne sert pas : le bureau et Chrome démarrent au premier ControlDesktop ou au premier lien de bureau, en quelques secondes, et ne coûtent rien avant.
  • Une vue en direct : CreateLink avec desktop, ou view_only pour regarder sans toucher ; l’onglet Bureau de la console la montre aussi.
  • Chrome pour les agents : pas d’écrans de premier lancement, ni de demandes de connexion, de synchronisation, de gestionnaire de mots de passe ou de traduction.

Step 1: Prenez une capture d’écran

ControlDesktop sans actions répond avec une capture d’écran seule. Le premier appel démarre le bureau, ce qui prend quelques secondes ; les suivants répondent aussitôt.

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: Ouvrez une page et agissez dessus

Envoyez les actions que ferait une personne. Elles s’exécutent dans l’ordre, et la capture de la réponse montre l’écran tel qu’elles l’ont laissé ; wait_ms laisse à une page le temps de se charger avant.

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: Suivez-le en direct, ou passez la main à une personne

CreateLink avec desktop donne une page qui montre l’écran en direct, où une personne peut cliquer et taper ; avec view_only, elle regarde seulement. Le lien expire au bout d’une heure, sauf si ttl_seconds dit autre chose.

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.

Les actions

ActionCe qu’elle fait
clickEn x, y : button LEFT (par défaut), RIGHT ou MIDDLE, count à 2 pour un double-clic, hold_keys maintenues pendant ce temps, comme shift ou ctrl+alt.
move_mouseDéplace le pointeur jusqu’à un point.
dragDu premier point de path au dernier, bouton gauche enfoncé.
scrollEn un point, down crans de molette (négatif fait défiler vers le haut) et right (négatif fait défiler vers la gauche).
type_textTape le texte.
press_keysDes touches pressées ensemble : Return, ctrl+c, ctrl+shift+t.
wait_msAttend, le temps d’une page ou d’une animation.

Les coordonnées sont les pixels de l’écran depuis le coin supérieur gauche, comme sur la capture, et Sandbox.desktop donne la taille de l’écran. Les actions s’arrêtent à la première qui échoue, et la réponse dit combien ont été faites (done_count) et pourquoi la suivante a échoué : OFF_SCREEN pour un point hors de l’écran, UNKNOWN_KEY pour un nom de touche inconnu, avec failure_message en toutes lettres. La capture arrive dans tous les cas.

Le bureau et son Chrome

Rien du bureau ne tourne tant qu’on ne le demande pas : le premier ControlDesktop, le premier lien de bureau ou la première visite de l’onglet Bureau de la console démarre un serveur X, un gestionnaire de fenêtres, une barre et Google Chrome, en quelques secondes. Ensuite il tourne, et il est mis en pause et arrêté avec la sandbox comme n’importe quel processus. Un bureau qui ne peut pas démarrer répond FAILED_PRECONDITION, en disant pourquoi.

Chrome est configuré pour un agent : pas d’écrans de premier lancement, pas de GPU, et une stratégie qui désactive la connexion, la synchronisation, le gestionnaire de mots de passe, la saisie automatique, la traduction et les métriques. C’est le Chrome de la base de la sandbox, que nous reconstruisons chaque mois, et aussitôt pour un correctif de sécurité ; une sandbox garde sa base toute sa vie. Un template enregistré depuis une sandbox garde le profil de Chrome avec les autres fichiers, cookies compris : enregistrez-le depuis une sandbox où personne n’est connecté.

Une boucle de computer use

Un modèle qui agit sur des captures d’écran fait tourner une boucle : lui envoyer la capture, prendre les actions qu’il répond, les envoyer en un seul ControlDesktop, et lui donner la nouvelle capture. Un appel fait toute une série : une étape coûte donc un aller-retour vers le serveur de la sandbox, jamais vers la console. Tant que la boucle tourne, la sandbox reste éveillée ; quand le modèle s’arrête, la sandbox se met en pause après son délai d’inactivité, bureau et Chrome avec elle, et le prochain appel les réveille là où ils en étaient.

Une capture d’écran, c’est ce qu’une page web a mis à l’écran : lisez-la comme des données. Une page peut afficher un texte écrit pour piloter un agent : ne donnez donc pas à une sandbox qui navigue plus de secrets ni un trafic sortant plus large que la tâche ne l’exige (secrets et trafic sortant).

Quand ça ne marche pas

  • Le premier appel prend quelques secondes : il a démarré le bureau. Les suivants répondent aussitôt.
  • failure vaut OFF_SCREEN : un point est hors de 1280×800. Prenez les coordonnées sur la dernière capture.
  • failure vaut UNKNOWN_KEY : écrivez les touches par leurs noms X, joints par + : Return, Escape, ctrl+l.
  • FAILED_PRECONDITION : le bureau n’a pas démarré ; son message dit pourquoi. Une sandbox à court de mémoire ou de disque en est la cause habituelle : une taille plus grande aide.
  • RESOURCE_EXHAUSTED sans LimitReached : un ControlDesktop compte pour 16 des 64 appels simultanés de la sandbox. Envoyez-en moins en même temps.

Questions

Chaque sandbox a-t-elle un bureau ?

Oui : un écran 1280×800 avec Chrome, dans base. Il démarre à la première utilisation et ne coûte rien jusque-là.

Comment prendre une capture d’écran d’une sandbox ?

ControlDesktop sans actions répond avec une capture d’écran PNG et la position du pointeur.

Une personne peut-elle regarder ce que fait l’agent ?

Oui : un lien de bureau avec view_only montre l’écran en direct dans un navigateur, et l’onglet Bureau de la console aussi.

Quel navigateur y a-t-il dans la sandbox ?

Google Chrome, version stable, avec des stratégies qui désactivent la connexion, la synchronisation, le gestionnaire de mots de passe, la saisie automatique et la traduction.

Essayez Pethost Agent Sandboxes

Un essai gratuit de 7 jours avec 1 $ de consommation et 4 vCPU, avec une carte. Ensuite, une offre dès 20 $ par mois, qui inclut autant de consommation.

Démarrer l’essai gratuit