Automatización

Tareas

Dale a un teléfono el objetivo en palabras simples. El agente de Clousd hace los pasos y responde.

Una tarea

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

Escribe la tarea como se la escribirías a una persona: qué abrir, qué hacer y qué informar. El agente mira la pantalla, toca y escribe hasta lograr el objetivo, y termina con una respuesta en answer. Un teléfono hace una tarea a la vez; otra ejecución en el mismo teléfono espera en su cola.

Estados: queued, running, paused (te pregunta algo), completed, failed, cancelled. Envía un encabezado Idempotency-Key para que reintentar sea seguro: la misma clave y el mismo cuerpo devuelven la misma ejecución.

Muchos teléfonos

Pasa devices en lugar de device (hasta 32): cada teléfono recibe la misma tarea, todos a la vez. La respuesta es una ejecución principal con una ejecución hija por teléfono; GET /v1/runs?since=… las lista con sus propias respuestas.

Seguirla en vivo

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

Eventos: status, plan, step, card, answer, message, end. Si se corta la conexión, retoma con ?since=N. Cada paso se guarda: GET /v1/runs/{id}/trajectory los lista y /steps/{n}.jpg es la pantalla antes de cada uno. En el panel, la misma ejecución es una repetición que puedes recorrer paso a paso.

Preguntas y permisos

Con "options": {"mode": "ask"} el agente se detiene antes de los pasos delicados (enviar, pagar, borrar) y cuando necesita algo que solo tú sabes. La ejecución queda en paused y lleva una card: una pregunta con opciones o un permiso para una acción.

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

Accesos guardados

Guarda un acceso una sola vez —en el panel (la línea Acceso de una tarea) o con POST /v1/credentials {"package", "name", "fields": {"username", "password", "totp"}}— y pásalo a una ejecución por paquete y nombre. El agente escribe los valores en el teléfono; nunca llegan al modelo, a los pasos de la ejecución ni a la respuesta de la API, y GET /v1/credentials solo indica qué campos están definidos.

{
  "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"}]
}

Salida estructurada

Agrega un JSON Schema en options.output_schema y la respuesta también llega como structured_output con esa forma, lista para tu código.

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

Con horario

Un horario inicia la misma ejecución por sí solo: POST /v1/schedules con name, phones, task, at ("HH:MM"), tz (una zona horaria como Europe/Berlin), days (de 1 a 7, el lunes es 1; vacío significa todos los días) y credentials opcional. every: "hour" la ejecuta cada hora en el minuto de at; more: [{"at": "18:00", "days": [6, 7]}] agrega otros horarios a la misma tarea; trigger: "api" la ejecuta solo cuando llamas a POST /v1/schedules/{id}/run, que además inicia cualquier horario en ese momento. Pausa un horario con /toggle y elimínalo con /delete. Para saber cuándo termina una ejecución, agrega un webhook.