Автоматизация

Задачи

Опишите телефону цель обычными словами. Агент Clousd сам сделает шаги и ответит.

Задача

POST /v1/runs
{
  "task": "Open Settings and tell me the Android version",
  "device": "c3f9a41d2"
}
# → 201 {"run": {"id": "r_8f2c", "status": "queued", …}}

GET /v1/runs/r_8f2c
# → {"run": {"status": "completed", "answer": "Android 15", "steps": 4, "seconds": 21}}

Пишите задачу так, как написали бы человеку: что открыть, что сделать, о чём сообщить. Агент смотрит на экран, нажимает и печатает, пока не достигнет цели, и заканчивает ответом answer. Телефон выполняет одну задачу за раз; следующий запуск на том же телефоне ждёт в очереди.

Статусы: queued, running, paused (агент о чём-то спрашивает), completed, failed, cancelled. Передайте заголовок Idempotency-Key, чтобы повтор был безопасным: тот же ключ и то же тело вернут тот же запуск.

Много телефонов

Передайте devices вместо device (до 32): каждый телефон получит одну и ту же задачу, все сразу. В ответ придёт родительский запуск с дочерним запуском на каждый телефон; GET /v1/runs?since=… показывает их вместе с их ответами.

Следить в реальном времени

curl -N -H "Authorization: Bearer cl_live_…" https://api.clousd.com/v1/runs/r_8f2c/events

id: 3
event: step
data: {"n": 3, "tool": "tap", "target": "About phone", "result": "ok"}

id: 6
event: end
data: {"status": "completed"}

События: status, plan, step, card, answer, message, end. После обрыва соединения продолжайте с ?since=N. Каждый шаг сохраняется: GET /v1/runs/{id}/trajectory перечисляет их, а /steps/{n}.jpg — экран перед каждым шагом. В панели тот же запуск — это запись, которую можно пройти по шагам.

Вопросы и разрешения

С "options": {"mode": "ask"} агент останавливается перед рискованными шагами (отправка, оплата, удаление) и когда ему нужно то, что знаете только вы. Запуск переходит в paused и несёт card: вопрос с вариантами ответа или запрос разрешения на одно действие.

POST /v1/runs/r_8f2c/answer   {"card": "c1", "answer": "the first one"}
POST /v1/runs/r_8f2c/answer   {"card": "c2", "allow": true}
POST /v1/runs/r_8f2c/message  {"text": "use the work email"}
POST /v1/runs/r_8f2c/cancel

Сохранённые входы

Сохраните вход один раз — в панели (строка «Вход» в задаче) или через POST /v1/credentials {"package", "name", "fields": {"username", "password", "totp"}} — и передавайте его запуску по пакету и имени. Агент вводит значения на телефоне; они никогда не попадают ни к модели, ни в шаги запуска, ни в ответ API, а GET /v1/credentials показывает только, какие поля заполнены.

{
  "task": "Sign in to the app and tell me how many orders are on the Orders page",
  "device": "c3f9a41d2",
  "credentials": [{"package": "com.example.shop", "name": "work"}]
}

Структурированный ответ

Добавьте JSON Schema в options.output_schema, и ответ дополнительно придёт в поле structured_output в этой форме, готовый для вашего кода.

"options": {
  "output_schema": {"type": "object", "properties": {"orders": {"type": "integer"}}},
  "max_steps": 60,
  "timeout": 600
}
# → "structured_output": {"orders": 3}

По расписанию

Расписание само запускает одну и ту же задачу: POST /v1/schedules с name, phones, task, at ("HH:MM"), tz (часовой пояс, например Europe/Berlin), days (от 1 до 7, понедельник — 1; пусто — каждый день) и необязательным credentials. every: "hour" запускает задачу каждый час в минуту из at; more: [{"at": "18:00", "days": [6, 7]}] добавляет той же задаче другое время; trigger: "api" запускает её только по вызову POST /v1/schedules/{id}/run, который к тому же сразу запускает любое расписание. Приостановить расписание можно через /toggle, удалить — через /delete. Чтобы узнать, когда запуск закончится, добавьте вебхук.