Документация Agent Sandboxes · Задачи
Computer use: Chrome на рабочем столе в песочнице
В каждой песочнице есть рабочий стол 1280×800 с Google Chrome, который запускается, когда вы впервые к нему обращаетесь. Один вызов выполняет пачку кликов, нажатий клавиш и прокруток и отвечает скриншотом — это и есть цикл агента с computer use. Ссылка показывает экран вживую в браузере, чтобы человек мог смотреть или взять управление на себя.
ControlDesktop: действия по порядку (клик, перемещение, перетаскивание, прокрутка, ввод текста, нажатие клавиш, ожидание), затем один скриншот PNG с положением курсора.- Бесплатно, пока не нужен: рабочий стол и Chrome запускаются при первом
ControlDesktopили первой ссылке на рабочий стол, за несколько секунд, и до этого ничего не стоят. - Живой вид:
CreateLinkсdesktopили сview_only, чтобы смотреть, ничего не трогая; вкладка «Рабочий стол» в панели тоже его показывает. - Chrome для агентов: никаких экранов первого запуска, входа, синхронизации, менеджера паролей или предложений перевести страницу.
Step 1: Сделайте скриншот
ControlDesktop без действий отвечает одним скриншотом. Первый вызов запускает рабочий стол, на это уходит несколько секунд; следующие отвечают сразу.
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: Откройте страницу и поработайте с ней
Отправьте действия, которые сделал бы человек. Они выполняются по порядку, а скриншот в ответе показывает экран после них; wait_ms дает странице время загрузиться перед скриншотом.
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: Смотрите вживую или передайте человеку
CreateLink с desktop дает страницу, которая показывает экран вживую и где человек может кликать и печатать; с view_only — только смотреть. Ссылка истекает через час, если ttl_seconds не говорит иначе.
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.
Действия
| Действие | Что делает |
|---|---|
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 $ в месяц, в который входит столько же использования.