Automação

Tarefas

Diga ao celular o objetivo em palavras simples. O agente da Clousd faz os passos e responde.

Uma tarefa

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

Escreva a tarefa como escreveria para uma pessoa: o que abrir, o que fazer, o que relatar. O agente olha a tela, toca e digita até atingir o objetivo, e termina com uma resposta em answer. Um celular faz uma tarefa por vez; outra execução no mesmo celular espera na fila dele.

Status: queued, running, paused (ele pergunta algo a você), completed, failed, cancelled. Envie um cabeçalho Idempotency-Key para tornar a nova tentativa segura: a mesma chave e o mesmo corpo retornam a mesma execução.

Vários celulares

Passe devices em vez de device (até 32): todos os celulares recebem a mesma tarefa, ao mesmo tempo. A resposta é uma execução principal com uma execução filha por celular; GET /v1/runs?since=… lista todas com as respostas de cada uma.

Acompanhar ao 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. Retome depois de uma queda de conexão com ?since=N. Cada passo fica guardado: GET /v1/runs/{id}/trajectory lista os passos e /steps/{n}.jpg é a tela antes de cada um. No painel, a mesma execução vira um replay que você percorre passo a passo.

Perguntas e permissões

Com "options": {"mode": "ask"} o agente para antes de passos arriscados (enviar, pagar, excluir) e quando precisa de algo que só você sabe. A execução fica paused e traz um card: uma pergunta com opções ou uma permissão para uma ação.

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

Logins salvos

Salve um login uma vez — no painel (a linha Login de uma tarefa) ou com POST /v1/credentials {"package", "name", "fields": {"username", "password", "totp"}} — e passe-o para uma execução pelo pacote e pelo nome. O agente digita os valores no celular; eles nunca chegam ao modelo, aos passos da execução nem à resposta da API, e GET /v1/credentials mostra só quais campos estão preenchidos.

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

Saída estruturada

Adicione um JSON Schema em options.output_schema e a resposta também volta como structured_output nesse formato, pronta para o seu código.

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

Por agenda

Uma agenda inicia a mesma execução sozinha: POST /v1/schedules com name, phones, task, at ("HH:MM"), tz (um fuso horário como Europe/Berlin), days (de 1 a 7, segunda é 1; vazio significa todos os dias) e credentials opcional. every: "hour" executa a tarefa de hora em hora no minuto de at; more: [{"at": "18:00", "days": [6, 7]}] adiciona outros horários à mesma tarefa; trigger: "api" executa só quando você chama POST /v1/schedules/{id}/run, que também inicia qualquer agenda na hora. Pause com /toggle e remova com /delete. Para saber quando uma execução termina, adicione um webhook.