Documentation Agent Sandboxes · Tâches
Computer use : Chrome sur un bureau dans une sandbox
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.
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
ControlDesktopou au premier lien de bureau, en quelques secondes, et ne coûtent rien avant. - Une vue en direct :
CreateLinkavecdesktop, ouview_onlypour 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.
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: 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.
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: 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.
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.
Les actions
| Action | Ce qu’elle fait |
|---|---|
click | En 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_mouse | Déplace le pointeur jusqu’à un point. |
drag | Du premier point de path au dernier, bouton gauche enfoncé. |
scroll | En 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_text | Tape le texte. |
press_keys | Des touches pressées ensemble : Return, ctrl+c, ctrl+shift+t. |
wait_ms | Attend, 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.
failurevautOFF_SCREEN: un point est hors de 1280×800. Prenez les coordonnées sur la dernière capture.failurevautUNKNOWN_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_EXHAUSTEDsansLimitReached: unControlDesktopcompte 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.