Docs do Agent Sandboxes · Tarefas
Uso do computador: Chrome em um desktop dentro de um sandbox
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.
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
ControlDesktopou link do desktop, em alguns segundos, e não custam nada antes. - Uma visão ao vivo:
CreateLinkcomdesktop, ouview_onlypara 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.
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: 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.
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: 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.
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.
As ações
| Ação | O que faz |
|---|---|
click | Em 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_mouse | Move o ponteiro até um ponto. |
drag | Do primeiro ponto de path até o último, com o botão esquerdo pressionado. |
scroll | Em um ponto, down cliques da roda (negativo rola para cima) e right (negativo rola para a esquerda). |
type_text | Digita o texto. |
press_keys | Teclas pressionadas juntas: Return, ctrl+c, ctrl+shift+t. |
wait_ms | Espera, 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_EXHAUSTEDsemLimitReached: umControlDesktopconta 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.