Português
Menu da documentação

Docs do Agent Sandboxes · Tarefas

Uso do computador: Chrome em um desktop dentro de um sandbox

Atualizado em · 6 min de leitura

Todo sandbox tem um desktop de 1280×800 com Google Chrome, que inicia na primeira vez que você o usa. Uma chamada faz um lote de cliques, teclas e rolagens e responde com uma captura de tela, que é o ciclo que um agente de uso do computador roda. Um link mostra a tela ao vivo em um navegador, para uma pessoa assistir ou assumir o controle.

Em resumo
  • ControlDesktop: ações em ordem (clicar, mover, arrastar, rolar, digitar, pressionar teclas, esperar), depois uma captura de tela PNG com a posição do cursor.
  • Grátis até o uso: o desktop e o Chrome iniciam no primeiro ControlDesktop ou link do desktop, em alguns segundos, e não custam nada antes.
  • Uma visão ao vivo: CreateLink com desktop, ou view_only para assistir sem mexer; a aba Desktop do painel também a mostra.
  • Chrome para agentes: sem telas de primeira execução, sem pedidos de login, sincronização, gerenciador de senhas ou tradução.

Step 1: Tire uma captura de tela

ControlDesktop sem ações responde só com uma captura de tela. A primeira chamada inicia o desktop, o que leva alguns segundos; as seguintes respondem na hora.

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: Abra uma página e aja nela

Envie as ações que uma pessoa faria. Elas rodam em ordem, e a captura de tela da resposta mostra a tela como elas a deixaram; wait_ms dá tempo para uma página carregar antes disso.

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: Assista ao vivo, ou passe para uma pessoa

CreateLink com desktop dá uma página que mostra a tela ao vivo, onde uma pessoa pode clicar e digitar; com view_only, ela só assiste. Ele expira depois de uma hora, a não ser que ttl_seconds diga outra coisa.

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.

As ações

AçãoO que faz
clickEm x, y: button LEFT (o padrão), RIGHT ou MIDDLE, count 2 para um clique duplo, hold_keys segurados enquanto isso, como shift ou ctrl+alt.
move_mouseMove o ponteiro até um ponto.
dragDo primeiro ponto de path até o último, com o botão esquerdo pressionado.
scrollEm um ponto, down cliques da roda (negativo rola para cima) e right (negativo rola para a esquerda).
type_textDigita o texto.
press_keysTeclas pressionadas juntas: Return, ctrl+c, ctrl+shift+t.
wait_msEspera, por uma página ou uma animação.

As coordenadas são os pixels da tela a partir do canto superior esquerdo, como a captura de tela os tem, e Sandbox.desktop dá o tamanho da tela. As ações param na primeira que falha, e a resposta diz quantas foram feitas (done_count) e por que a seguinte falhou: OFF_SCREEN para um ponto fora da tela, UNKNOWN_KEY para um nome de tecla que ele não conhece, com failure_message em palavras. A captura de tela vem de qualquer forma.

O desktop e o Chrome dele

Nada do desktop roda até ser pedido: o primeiro ControlDesktop, link do desktop ou visita à aba Desktop do painel inicia um servidor X, um gerenciador de janelas, um painel e o Google Chrome, em alguns segundos. Depois ele roda, e é pausado e parado com o sandbox como qualquer processo. Um desktop que não consegue iniciar responde FAILED_PRECONDITION, dizendo por quê.

O Chrome é configurado para um agente: sem telas de primeira execução, sem GPU, e com uma política que desativa login, sincronização, gerenciador de senhas, preenchimento automático, tradução e métricas. É o Chrome da base do sandbox, que refazemos todo mês e na hora em caso de correção de segurança; um sandbox mantém a base dele por toda a vida. Um template salvo de um sandbox guarda o perfil do Chrome com os outros arquivos, cookies incluídos, então salve um a partir de um sandbox sem ninguém logado.

Um ciclo de uso do computador

Um modelo que age sobre capturas de tela roda um ciclo: envie a captura de tela a ele, pegue as ações que ele responde, envie-as em um ControlDesktop e dê a ele a nova captura de tela. Uma chamada faz um lote inteiro, então um passo custa uma ida e volta ao servidor do sandbox, nunca ao painel. Enquanto o ciclo roda, o sandbox fica acordado; quando o modelo para, o sandbox pausa depois do tempo ocioso, com desktop e Chrome junto, e a próxima chamada os acorda onde estavam.

Uma captura de tela é o que uma página web colocou na tela: leia-a como dados. Uma página pode mostrar texto escrito para conduzir um agente, então não dê a um sandbox que navega mais segredos nem uma saída mais ampla do que a tarefa precisa (segredos e saída).

Quando não funciona

  • A primeira chamada leva segundos: ela iniciou o desktop. As seguintes respondem na hora.
  • failure é OFF_SCREEN: um ponto está fora de 1280×800. Pegue as coordenadas da última captura de tela.
  • failure é UNKNOWN_KEY: escreva as teclas pelos nomes do X, unidos com +: Return, Escape, ctrl+l.
  • FAILED_PRECONDITION: o desktop não iniciou; as palavras dele dizem por quê. Um sandbox com pouca memória ou pouco disco é a causa mais comum: um tamanho maior ajuda.
  • RESOURCE_EXHAUSTED sem LimitReached: um ControlDesktop conta como 16 das 64 chamadas que o sandbox atende ao mesmo tempo. Envie menos ao mesmo tempo.

Perguntas

Todo sandbox tem um desktop?

Sim: uma tela de 1280×800 com Chrome, no base. Ele inicia no primeiro uso e não custa nada até lá.

Como tiro uma captura de tela de um sandbox?

ControlDesktop sem ações responde com uma captura de tela PNG com a posição do cursor.

Uma pessoa pode assistir ao que o agente faz?

Sim: um link do desktop com view_only mostra a tela ao vivo em um navegador, e a aba Desktop do painel também.

Qual navegador está no sandbox?

O Google Chrome, estável, com políticas que desativam login, sincronização, gerenciador de senhas, preenchimento automático e tradução.

Experimente o Pethost Agent Sandboxes

Um teste grátis de 7 dias com US$ 1 de uso e 4 vCPUs; é preciso um cartão. Depois, um plano a partir de US$ 20 por mês, que inclui esse mesmo valor em uso.

Começar o teste grátis