Español
Menú de la documentación

Documentación de Agent Sandboxes · Tareas

Computer use: Chrome en un escritorio dentro de un sandbox

Actualizado · 6 min de lectura

Cada sandbox tiene un escritorio de 1280×800 con Google Chrome, que se inicia la primera vez que lo usas. Una llamada hace un lote de clics, teclas y desplazamientos y responde con una captura de pantalla, que es el bucle que ejecuta un agente de computer use. Un enlace muestra la pantalla en tiempo real en un navegador, para que una persona la mire o tome el control.

En resumen
  • ControlDesktop: acciones en orden (clic, mover, arrastrar, desplazar, escribir, pulsar teclas, esperar), y después una captura de pantalla PNG con la posición del cursor.
  • Gratis hasta que se usa: el escritorio y Chrome se inician con el primer ControlDesktop o el primer enlace al escritorio, en unos segundos, y antes no cuestan nada.
  • Una vista en tiempo real: CreateLink con desktop, o view_only para mirar sin tocar; la pestaña Escritorio del panel también la muestra.
  • Chrome para agentes: sin pantallas de primer uso, sin avisos de inicio de sesión, sincronización, administrador de contraseñas ni traducción.

Step 1: Toma una captura de pantalla

ControlDesktop sin acciones responde solo con una captura de pantalla. La primera llamada inicia el escritorio, lo que tarda unos segundos; las siguientes responden al momento.

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: Abre una página y actúa en ella

Envía las acciones que haría una persona. Se ejecutan en orden, y la captura de pantalla de la respuesta muestra la pantalla tal como la dejaron; wait_ms le da tiempo a una página para cargar antes.

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: Míralo en tiempo real, o pásaselo a una persona

CreateLink con desktop da una página que muestra la pantalla en tiempo real, donde una persona puede hacer clic y escribir; con view_only solo mira. Caduca tras una hora salvo que ttl_seconds diga otra cosa.

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.

Las acciones

AcciónQué hace
clickEn x, y: button LEFT (el valor por defecto), RIGHT o MIDDLE, count 2 para un doble clic, hold_keys pulsadas mientras tanto, como shift o ctrl+alt.
move_mouseMueve el puntero a un punto.
dragDesde el primer punto de path hasta el último, con el botón izquierdo pulsado.
scrollEn un punto, down clics de rueda (un número negativo desplaza hacia arriba) y right (un número negativo desplaza a la izquierda).
type_textEscribe el texto.
press_keysTeclas pulsadas a la vez: Return, ctrl+c, ctrl+shift+t.
wait_msEspera, a una página o a una animación.

Las coordenadas son los píxeles de la pantalla desde arriba a la izquierda, como los tiene la captura, y Sandbox.desktop da el tamaño de la pantalla. Las acciones se detienen en la primera que falla, y la respuesta dice cuántas se hicieron (done_count) y por qué falló la siguiente: OFF_SCREEN para un punto fuera de la pantalla, UNKNOWN_KEY para un nombre de tecla que no conoce, con failure_message en palabras. La captura llega en cualquier caso.

El escritorio y su Chrome

Nada del escritorio se ejecuta hasta que se pide: el primer ControlDesktop, enlace al escritorio o visita a la pestaña Escritorio del panel inicia un servidor X, un administrador de ventanas, un panel y Google Chrome, en unos segundos. A partir de ahí se ejecuta, y se pausa y se detiene con el sandbox como cualquier proceso. Un escritorio que no puede iniciarse responde FAILED_PRECONDITION, y dice por qué.

Chrome viene preparado para un agente: sin pantallas de primer uso, sin GPU, y con una política que desactiva el inicio de sesión, la sincronización, el administrador de contraseñas, el autocompletado, la traducción y las métricas. Es el Chrome de la base del sandbox, que reconstruimos cada mes y al momento ante un arreglo de seguridad; un sandbox conserva su base mientras vive. Una plantilla guardada desde un sandbox conserva el perfil de Chrome con los demás archivos, cookies incluidas, así que guárdala desde un sandbox en el que nadie haya iniciado sesión.

Un bucle de computer use

Un modelo que actúa sobre capturas de pantalla ejecuta un bucle: le envías la captura, tomas las acciones que responde, las envías en un solo ControlDesktop y le das la captura nueva. Una llamada hace un lote entero, así que un paso cuesta un viaje de ida y vuelta al servidor del sandbox, nunca al panel. Mientras el bucle se ejecuta, el sandbox sigue despierto; cuando el modelo para, el sandbox se pausa tras su tiempo de inactividad, con el escritorio y Chrome, y la siguiente llamada los despierta donde estaban.

Una captura de pantalla es lo que una página web puso en la pantalla: léela como datos. Una página puede mostrar texto escrito para dirigir a un agente, así que no le des a un sandbox que navega más secretos ni una salida más amplia de lo que necesita la tarea (secretos y salida).

Cuando no funciona

  • La primera llamada tarda unos segundos: inició el escritorio. Las siguientes responden al momento.
  • failure es OFF_SCREEN: un punto está fuera de 1280×800. Toma las coordenadas de la última captura.
  • failure es UNKNOWN_KEY: escribe las teclas por sus nombres de X, unidas con +: Return, Escape, ctrl+l.
  • FAILED_PRECONDITION: el escritorio no se inició; sus palabras dicen por qué. La causa habitual es un sandbox con poca memoria o poco disco: un tamaño mayor ayuda.
  • RESOURCE_EXHAUSTED sin LimitReached: un ControlDesktop cuenta como 16 de las 64 llamadas a la vez del sandbox. Envía menos al mismo tiempo.

Preguntas

¿Todos los sandboxes tienen escritorio?

Sí: una pantalla de 1280×800 con Chrome, en base. Se inicia con el primer uso y no cuesta nada hasta entonces.

¿Cómo tomo una captura de pantalla de un sandbox?

ControlDesktop sin acciones responde una captura de pantalla PNG con la posición del cursor.

¿Puede una persona mirar lo que hace el agente?

Sí: un enlace al escritorio con view_only muestra la pantalla en tiempo real en un navegador, y la pestaña Escritorio del panel también.

¿Qué navegador hay en el sandbox?

Google Chrome, estable, con políticas que desactivan el inicio de sesión, la sincronización, el administrador de contraseñas, el autocompletado y la traducción.

Prueba Pethost Agent Sandboxes

Una prueba gratis de 7 días con 1 US$ de uso y 4 vCPU, con tarjeta. Después, un plan desde 20 US$ al mes, que incluye ese mismo importe en uso.

Empezar la prueba gratis