Русский
Меню документации

Документация Agent Sandboxes · Задачи

Computer use: Chrome на рабочем столе в песочнице

Обновлено · 5 мин чтения

В каждой песочнице есть рабочий стол 1280×800 с Google Chrome, который запускается, когда вы впервые к нему обращаетесь. Один вызов выполняет пачку кликов, нажатий клавиш и прокруток и отвечает скриншотом — это и есть цикл агента с computer use. Ссылка показывает экран вживую в браузере, чтобы человек мог смотреть или взять управление на себя.

Коротко
  • ControlDesktop: действия по порядку (клик, перемещение, перетаскивание, прокрутка, ввод текста, нажатие клавиш, ожидание), затем один скриншот PNG с положением курсора.
  • Бесплатно, пока не нужен: рабочий стол и Chrome запускаются при первом ControlDesktop или первой ссылке на рабочий стол, за несколько секунд, и до этого ничего не стоят.
  • Живой вид: CreateLink с desktop или с view_only, чтобы смотреть, ничего не трогая; вкладка «Рабочий стол» в панели тоже его показывает.
  • Chrome для агентов: никаких экранов первого запуска, входа, синхронизации, менеджера паролей или предложений перевести страницу.

Step 1: Сделайте скриншот

ControlDesktop без действий отвечает одним скриншотом. Первый вызов запускает рабочий стол, на это уходит несколько секунд; следующие отвечают сразу.

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: Откройте страницу и поработайте с ней

Отправьте действия, которые сделал бы человек. Они выполняются по порядку, а скриншот в ответе показывает экран после них; wait_ms дает странице время загрузиться перед скриншотом.

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: Смотрите вживую или передайте человеку

CreateLink с desktop дает страницу, которая показывает экран вживую и где человек может кликать и печатать; с view_only — только смотреть. Ссылка истекает через час, если ttl_seconds не говорит иначе.

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.

Действия

ДействиеЧто делает
clickВ точке x, y: button LEFT (по умолчанию), RIGHT или MIDDLE, count 2 для двойного клика, hold_keys — клавиши, зажатые на это время, например shift или ctrl+alt.
move_mouseПеремещает указатель в точку.
dragОт первой точки path до последней с зажатой левой кнопкой.
scrollВ точке: down щелчков колеса (отрицательное число прокручивает вверх) и right (отрицательное — влево).
type_textВводит текст.
press_keysКлавиши, нажатые вместе: Return, ctrl+c, ctrl+shift+t.
wait_msЖдет загрузки страницы или анимации.

Координаты — пиксели экрана от левого верхнего угла, как на скриншоте, а Sandbox.desktop дает размер экрана. Действия останавливаются на первом неудавшемся, а ответ говорит, сколько выполнено (done_count) и почему не удалось следующее: OFF_SCREEN — точка за пределами экрана, UNKNOWN_KEY — незнакомое имя клавиши, с failure_message словами. Скриншот приходит в любом случае.

Рабочий стол и его Chrome

Ничего из рабочего стола не работает, пока его не попросят: первый ControlDesktop, первая ссылка на рабочий стол или заход на вкладку «Рабочий стол» в панели запускают X-сервер, оконный менеджер, панель и Google Chrome за несколько секунд. Дальше он работает, встает на паузу и останавливается вместе с песочницей, как любой процесс. Рабочий стол, который не может запуститься, отвечает FAILED_PRECONDITION и говорит почему.

Chrome настроен для агента: никаких экранов первого запуска, без GPU, а политика выключает вход, синхронизацию, менеджер паролей, автозаполнение, перевод и метрики. Это Chrome базового образа песочницы, который мы пересобираем каждый месяц и сразу же ради исправления уязвимости; песочница сохраняет свой базовый образ всю свою жизнь. Шаблон, сохраненный из песочницы, сохраняет профиль Chrome вместе с другими файлами, включая cookie, поэтому сохраняйте шаблон из песочницы, где никто не вошел.

Цикл computer use

Модель, которая действует по скриншотам, крутит один цикл: отправить ей скриншот, взять действия из ее ответа, отправить их одним ControlDesktop и дать ей новый скриншот. Один вызов выполняет всю пачку, поэтому шаг стоит одного обращения к серверу песочницы и никогда — к панели. Пока цикл идет, песочница не засыпает; когда модель останавливается, песочница встает на паузу после своего времени простоя вместе с рабочим столом и Chrome, а следующий вызов будит их там, где они были.

Скриншот — это то, что веб-страница вывела на экран: читайте его как данные. Страница может показать текст, написанный, чтобы управлять агентом, поэтому не давайте песочнице, которая ходит по сайтам, больше секретов и более широкий исходящий трафик, чем нужно для задачи (секреты и исходящий трафик).

Если не работает

  • Первый вызов идет несколько секунд: он запускал рабочий стол. Следующие отвечают сразу.
  • failure — OFF_SCREEN: точка за пределами 1280×800. Берите координаты из последнего скриншота.
  • failure — UNKNOWN_KEY: пишите клавиши их именами в X, соединяя через +: Return, Escape, ctrl+l.
  • FAILED_PRECONDITION: рабочий стол не запустился; в тексте сказано почему. Обычная причина — песочнице не хватает памяти или диска: поможет размер побольше.
  • RESOURCE_EXHAUSTED без LimitReached: ControlDesktop считается за 16 из 64 одновременных вызовов песочницы. Отправляйте меньше одновременно.

Вопросы

Есть ли рабочий стол в каждой песочнице?

Да: экран 1280×800 с Chrome, в base. Он запускается при первом использовании и до тех пор ничего не стоит.

Как сделать скриншот песочницы?

ControlDesktop без действий отвечает скриншотом PNG с положением курсора.

Может ли человек смотреть, что делает агент?

Да: ссылка на рабочий стол с view_only показывает экран вживую в браузере, и вкладка «Рабочий стол» в панели тоже.

Какой браузер в песочнице?

Google Chrome, стабильный, с политиками, которые выключают вход, синхронизацию, менеджер паролей, автозаполнение и перевод.

Попробуйте Pethost Agent Sandboxes

Пробный период на 7 дней: 1 $ использования и 4 vCPU, нужна карта. Затем тариф от 20 $ в месяц, в который входит столько же использования.

Начать пробный период