Документація Agent Sandboxes · Завдання
Керування комп’ютером: Chrome на робочому столі в пісочниці
Кожна пісочниця має робочий стіл 1280×800 із Google Chrome, що запускається, коли ви вперше ним скористаєтеся. Один виклик виконує пакет клацань, клавіш і прокручувань і відповідає скриншотом — саме такий цикл виконує агент, що керує комп’ютером. Посилання показує екран наживо в браузері, щоб людина могла дивитися або перехопити керування.
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 разом з іншими файлами, зокрема cookies, тож зберігайте його з пісочниці, у якій ніхто не ввійшов.
Цикл керування комп’ютером
Модель, що діє за скриншотами, виконує один цикл: надіслати їй скриншот, узяти дії, якими вона відповідає, надіслати їх одним 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 $ на місяць, який включає стільки ж використання.