运行自动化

任务

用大白话告诉手机目标，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。