執行自動化

任務

用白話把目標交給手機，Clousd 的 Agent 會完成各個步驟並回覆結果。

一個任務

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}}

像交代同事一樣寫任務：要開什麼、做什麼、回報什麼。Agent 會看畫面、點擊和輸入，直到達成目標，最後回傳 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"} 後，Agent 會在有風險的步驟（傳送、付款、刪除）之前，以及需要只有你知道的資訊時停下來。這時執行狀態為 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"}}。之後依套件名稱和名稱傳給執行即可。Agent 會在手機上輸入這些值；它們絕不會傳到模型，也不會出現在執行步驟或 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"}]
}

結構化輸出

在 options.output_schema 加上 JSON 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 移除。想在執行結束時收到通知，請加上 Webhook。