Pular para o conteúdo

Execuções de agente: entra uma tarefa, sai JSON

Envie uma tarefa em linguagem natural, uma página inicial e, se quiser, um JSON Schema. Um navegador hospedado do Clearcote roda o Clearcote Jet nela e você recebe JSON de volta: o que aconteceu, cada passo dado e os dados que você pediu, validados contra o seu schema.

Em resumo

  • POST /api/v1/runs (cloud.runs.create no SDK) recebe uma tarefa em linguagem natural e uma url para começar. O Jet trabalha em um navegador hospedado e devolve JSON.
  • Adicione um schema e os dados que você pediu voltam em result.output, validados contra ele.
  • Uma execução dá no máximo maxSteps passos (padrão 40, no máximo 100) e para após 900 segundos por padrão.
  • Uma execução fica succeeded quando o Jet terminou com done e a saída é válida. Qualquer outro fim é failed, a menos que você a tenha cancelado ou ela tenha expirado na fila.
  • Você paga o navegador por GB e o agente por milhão de tokens, do seu saldo pré-pago.

Início rápido

Com uma chave de API em CLEARCOTE_API_KEY (da página API keys) e o SDK 0.34.0 ou mais recente:

from clearcote.cloud import Cloud

cloud = Cloud()   # reads CLEARCOTE_API_KEY

run = cloud.runs.create(
    "Find the date of the next bank holiday in England and Wales.",
    url="https://www.gov.uk/",
    schema={
        "type": "object",
        "properties": {
            "name": {"type": "string"},
            "date": {"type": "string", "description": "YYYY-MM-DD"},
        },
        "required": ["name", "date"],
    },
    country="gb",
)   # wait=True (the default): returns when the run has finished

print(run["status"])            # succeeded
print(run["result"]["output"])  # {'name': 'Christmas Day', 'date': '2026-12-25'}
print(run["costEur"]["total"])
Esta aba roda na sua máquina.

Quem executa: Clearcote Jet

O Clearcote Jet é o nosso agente de navegador open source (MIT). Ele trabalha em um loop, um passo de cada vez:

  1. Olhar. Ele lista os controles que uma pessoa poderia usar naquele momento: visíveis, habilitados, não escondidos atrás de um pop-up, incluindo os que estão dentro de iframes. Campos de senha nunca são lidos.
  2. Decidir. Uma única requisição a um modelo de decisão rápido escolhe juntos o tipo de passo e o controle, com uma probabilidade para cada opção, normalmente em algumas centenas de milissegundos. O modelo só escolhe dessa lista; ele nunca escreve código nem coordenadas.
  3. Agir. Ele confere se a página não mudou, depois move um mouse de verdade por um caminho curvo, clica e digita tecla por tecla, como uma pessoa faz.
  4. Responder. Quando a tarefa está concluída, as partes da página final que a respondem são convertidas em markdown e, com um schema, no seu JSON.

Não há código por site: o mesmo loop olha a página de novo depois de cada passo. O Jet não segue links que abrem uma nova aba e não lida com CAPTCHAs, uploads de arquivos, apps em canvas nem shadow roots fechados. Para esses casos, use uma transferência.

Sempre o Jet atual

Cada servidor acompanha por conta própria o branch main do Jet. Quando sai uma versão nova, o servidor a instala ao lado da atual, roda um autoteste e só troca para ela quando o teste passa; as próximas execuções passam a usá-la. Uma execução em andamento mantém a versão com que começou, e uma atualização que falha deixa a versão anterior no lugar. Cada resultado informa a versão em que rodou em result.jet (version e commit), assim como o evento run.started da execução, então uma mudança de comportamento pode ser rastreada até o commit exato.

A requisição

POST /api/v1/runs aceita estes campos, além de todas as opções de POST /api/v1/browsers: persona, proxy e local de saída, identity, profile, version, adblock, solveSliders, solveCheckboxes, solvePressHold, challengeService, os limites, note e worker.

CampoTipoSignificado
taskstringObrigatório. O que fazer, em linguagem natural: de 1 a 4000 caracteres. Quebras de linha e tabulações são aceitas, outros caracteres de controle não.
urlhttp(s) URLA página em que a execução começa. O Jet trabalha com os controles da página, então quase toda tarefa precisa de uma.
schemaobjectUm JSON Schema para result.output (draft-07). No máximo 16 KB, com no máximo 20 níveis de aninhamento, e o type de nível superior precisa ser "object" ou "array". Veja Saída estruturada.
secretsobjectValores que a execução pode digitar sem que o modelo jamais os veja, incluindo códigos TOTP. No máximo 20. Veja segredos e 2FA.
maxStepsintegerDe 1 a 100, padrão 40. O máximo de passos que o Jet pode dar antes de parar com budget (a execução fica então failed).
handoffbooleanPadrão false. Quando o Jet para com needs_input ou blocked, pausa e entrega o navegador a uma pessoa. Veja transferência.
handoffTimeoutSecintegerDe 60 a 3600, padrão 600. Quanto tempo uma transferência espera pela pessoa.
recordbooleanPadrão false. Grava a execução como MP4. Veja gravações.
  • url é onde a execução começa: o Jet a abre sozinho, em vez de ela já estar carregada antes de você se conectar.
  • keepAlive (qualquer valor diferente de false) dá um 400: uma execução não tem cliente para se reconectar e termina quando o Jet acaba.
  • timeoutSec tem padrão 900 em uma execução. maxGb, idleTimeoutSec e o seu saldo valem como em qualquer sessão.
  • Uma execução é alocada a um servidor com Jet quando você a cria. Se nenhum tiver espaço, ou nenhum suportar o que ela pede (schema, secrets, handoff ou record), a criação responde 503 NO_CAPACITY e nada entra na fila. A execução então espera que esse servidor a assuma; se isso não acontecer em cinco minutos, ela termina como expired.
  • Uma execução cuja tarefa, schema e segredos deixam suas configurações maiores que 60 KB dá um 400 TOO_LARGE.

A resposta é um 201 com a nova execução. O pricing dela traz as tarifas pelas quais essa execução é cobrada:

json
{
  "id": "bs_…",                 // GET /api/v1/runs/<id>
  "status": "queued",
  "worker": "w_…",
  "createdAt": "…",
  "expiresAt": "…",             // a server picks it up before this, or it expires
  "pricing": { "eurPerGb": …, "eurPerHour": …, "eurPerMTok": …, "eurPerMTokTextIn": …, "eurPerMTokTextOut": … },
  "limits": { "maxSeconds": 900, "idleSeconds": …, "maxBytes": … },
  "engine": { "version": …, "revision": …, "pinned": false },   // the Clearcote release it runs on
  "note": "…", "profile": { "name": "…", "persist": true },      // only when you set them
  "warnings": []
}

warnings lista o que foi aceito mas parece errado, por exemplo um segredo que a tarefa nunca usa.

Status

statusSignificado
queuedCriada, esperando que seu servidor a assuma.
runningO navegador está no ar e o Jet está trabalhando. Também enquanto seu servidor não está reportando: session.status fica então lost. Se o servidor nunca mais reportar, a execução termina como failed (session.endReason worker_silent, result null) uma hora depois da duração máxima de uma sessão; se o servidor reiniciou, assim que ele voltar (worker_restarted).
waiting_for_humanPausada para uma transferência (handoff: true). handoff.liveUrl é o link a enviar.
succeededO Jet terminou com done e outputError é null (com um schema: a saída era válida).
failedTerminou de qualquer outra forma: blocked, needs_input, budget ou error, uma saída que não batia com o schema ou passava de 1 MB, um limite, um navegador que não iniciou, nenhum resultado, ou algo que seu servidor encontrou ao assumir a execução: segredos que não podiam mais ser abertos (secrets_unreadable), um saldo esgotado (insufficient_balance) ou uma conta suspensa (suspended). result e session.endReason dizem qual.
cancelledVocê a parou: DELETE /api/v1/runs/<id>, ou parando a sessão dela.
expiredNenhum servidor a assumiu a tempo (cinco minutos). Nunca é cobrada.

queued, running e waiting_for_human são os únicos estados que mudam; os demais são finais. Consulte GET /api/v1/runs/<id> a cada um ou dois segundos, deixe o SDK esperar por você, ou receba um run.finished por webhook. Uma execução cancelada ou expirada antes de um servidor assumi-la não envia run.finished (nem session.ended): para essas, consulte o status.

Esperando no SDK

runs.create espera por padrão: ele consulta a cada 1,5 segundo, sem limite de tempo, e devolve a execução concluída. timeout (em segundos) limita a espera; passado esse tempo, o SDK lança CloudTimeoutError, cujo last é a execução como ele a viu pela última vez, e a execução continua. wait=False (Node: { wait: false }) devolve na hora a resposta da criação, e runs.wait(id) espera por ela depois. waiting_for_human não é um fim, então uma espera continua durante uma transferência: on_update (Node: onUpdate) é chamado com a execução sempre que o status ou a transferência dela mudam e, sem ele, o SDK imprime no stderr o link ao vivo da transferência.

from clearcote.cloud import Cloud, CloudTimeoutError

cloud = Cloud()
run = cloud.runs.create("Open Orders and read the latest order number",
                        url="https://shop.example.com/orders", handoff=True, wait=False)
print(run["id"], run["status"])   # queued

def show(r):
    print(r["status"], (r.get("handoff") or {}).get("liveUrl") or "")

try:
    run = cloud.runs.wait(run["id"], timeout=1800, on_update=show)
except CloudTimeoutError as e:
    print("still", (e.last or {}).get("status"), "after 30 minutes; it carries on")
Esta aba roda na sua máquina.

O resultado

GET /api/v1/runs/<id> responde com a execução. result é null até ela terminar, e continua null para uma execução que nunca rodou:

json
{
  "id": "bs_…",
  "status": "succeeded",
  "task": "Find the date of the next bank holiday in England and Wales.",
  "url": "https://www.gov.uk/",
  "hasSchema": true,
  "createdAt": "2026-10-02T09:14:03.120Z",
  "startedAt": "2026-10-02T09:14:05.410Z",
  "endedAt": "2026-10-02T09:14:21.006Z",
  "result": {
    "status": "done",
    "detail": null,
    "url": "https://www.gov.uk/bank-holidays",
    "title": "UK bank holidays - GOV.UK",
    "output": { "name": "Christmas Day", "date": "2026-12-25" },
    "outputError": null,
    "markdown": "## England and Wales\n\nThe next bank holiday in England and Wales is Christmas Day, 25 December …",
    "steps": [
      { "step": 1, "kind": "click", "action": "Reject additional cookies", "text": null, "probability": 0.85,
        "decideMs": 361, "atMs": 1200, "url": "https://www.gov.uk/", "ledTo": "https://www.gov.uk/", "pageChanged": true },
      { "step": 2, "kind": "fill", "action": "Search", "text": "next bank holiday", "probability": 1,
        "decideMs": 284, "atMs": 3410, "url": "https://www.gov.uk/", "ledTo": "https://www.gov.uk/", "pageChanged": true },
      …
    ],
    "usage": {
      "decision": { "inputTokens": 13654, "outputTokens": 120, "requests": 5 },
      "text":     { "inputTokens": 0, "outputTokens": 0, "requests": 0 },
      "extract":  { "inputTokens": 2210, "outputTokens": 26, "requests": 1 },
      "estimatedUsd": 0.0006
    },
    "handoffs": 0,
    "elapsedMs": 14800,
    "jet": { "version": "0.1.0", "commit": "cd7011c…" }
  },
  "handoff": null,              // see Hand-off
  "session": { … },             // the full GET /api/v1/browsers/<id> view: traffic, usage, endReason, recording
                                //   (its costEur is one number: the total)
  "costEur": { "browser": …, "agent": …, "total": … }
}
result.statusSignificado
doneO Jet julgou a tarefa concluída. É o julgamento do modelo: confira o que importa, por exemplo com campos required em um schema.
blockedNada na página permitia avançar, ou ele rolou 12 vezes seguidas.
needs_inputFalta na tarefa um valor de que um campo precisa, ou um segredo foi pedido em um site onde ele não é permitido. Coloque o valor na tarefa ou use um segredo.
budgetAtingiu maxSteps.
errorAlgo quebrou: o navegador, uma chamada ao modelo ou o runner. detail diz o quê.
  • detail: por que parou, em palavras, quando não terminou. url e title: a página em que terminou.
  • markdown: as partes da página final que respondem à tarefa; para uma execução que não terminou, o que estava na tela.
  • output e outputError: o seu JSON, ou por que ele não existe (veja abaixo).
  • usage: tokens e requisições por modelo: decision (o que escolhe os passos), text (o modelo que escreve os valores a digitar, quando usado) e extract (saída estruturada). estimatedUsd é a estimativa do próprio Jet para o custo dos modelos, não o que você paga; isso é o costEur.
  • handoffs: quantas vezes a execução foi entregue a uma pessoa. elapsedMs: quanto tempo o Jet trabalhou. jet: a versão que rodou, ou null se ela não for conhecida.
  • Um resultado tem no máximo 1 MB. Um maior é cortado em vez de recusado: primeiro o markdown, depois os últimos steps e, por último, output vira null com um outputError (e a execução fica failed).

Cada entrada em steps:

CampoSignificado
step1, 2, 3, …
kindO que ele fez: click, fill, select, scroll, wait.
actionO controle usado, pelo seu rótulo.
textO que ele digitou, com os segredos mostrados como {{name}}; null nos passos que não digitam nada.
probabilityO quanto o modelo de decisão tinha certeza deste passo, de 0 a 1, ou null. Um valor baixo indica um passo duvidoso.
decideMsQuanto tempo a decisão levou, ou null.
atMsQuando o passo aconteceu, em milissegundos desde o início da execução, ou null.
urlA página em que o passo aconteceu.
ledToO endereço da página depois do passo, ou null.
pageChangedSe a página mudou depois do passo.

Saída estruturada

Com um schema, um modelo de extração separado lê a página em que a execução terminou (a tarefa, o endereço e o título da página, e o texto dela) e escreve JSON para o seu schema. O JSON é validado contra o schema; se não bater, o modelo ganha mais uma tentativa com o erro de validação. O texto da página é passado a ele como dados não confiáveis, nunca como instruções, então uma página não consegue convencê-lo a dar outra resposta.

  • O JSON válido vai para result.output, e outputError é null.
  • Se ainda não bater, output é null, outputError diz por quê, e a execução fica failed mesmo que o Jet tenha reportado done.
  • Sem schema não há extração: a resposta está em markdown e detail.

Mantenha os schemas pequenos e diga o que você quer dizer. Os campos description são lidos pelo modelo, então use-os para formatos (“YYYY-MM-DD”, “preço em euros, um número”). Permita null para valores que uma página pode não ter, para que um preço ausente seja null em vez de uma execução com falha:

json
{
  "type": "object",
  "properties": {
    "plans": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "priceEur": { "type": ["number", "null"], "description": "monthly price in euros" }
        },
        "required": ["name", "priceEur"]
      }
    }
  },
  "required": ["plans"]
}

Como escrever uma tarefa

  • Diga como é o fim. “Abra a página de preços e leia o plano mais barato” termina em uma página com a resposta; “veja os preços deles” não.
  • Escreva os valores na tarefa. O Jet digita palavras que estão na tarefa: “pesquise tênis de corrida azul tamanho 44”, e não “pesquise tênis”. Senhas e códigos vão em segredos, nunca no texto da tarefa.
  • Comece onde está o trabalho. Informe a url mais profunda que você conhece em vez da página inicial. Cada passo custa tempo e tokens.
  • Faça login uma vez. Rode em um perfil que já esteja logado em vez de fazer login a cada execução.
  • Limite. Reduza maxSteps em tarefas curtas para que uma execução que anda em círculos pare cedo, e defina maxGb.

Passos, tempo e limites

maxSteps (padrão 40, no máximo 100) limita os passos; no limite, a execução para com budget. O Jet também para sozinho após 12 rolagens seguidas, com blocked. Os limites da sessão continuam valendo por cima: timeoutSec (900 segundos por padrão em uma execução), maxGb, idleTimeoutSec e o seu saldo. Quando um deles encerra a execução, ela fica failed e session.endReason informa o limite.

Uma execução é uma sessão

Uma execução é uma sessão de navegador com um agente acoplado, com o mesmo id. GET /api/v1/browsers/<id> mostra o tráfego e o uso dela, o painel a mostra com a visualização ao vivo, e a linha do tempo de eventos lista cada passo enquanto ele acontece. Não é possível se conectar a uma execução via CDP (isso dá um 409): o Jet é o único que a controla.

bash
# one run
curl -H "authorization: Bearer cc_live_..." https://www.clearcotelabs.com/api/v1/runs/<id>

# your runs, newest first: { runs: [{ id, status, task, createdAt, endedAt, resultStatus, costEur }] }
curl -H "authorization: Bearer cc_live_..." "https://www.clearcotelabs.com/api/v1/runs?limit=20"

# the page before that: before=<the createdAt of the last run you got>
curl -H "authorization: Bearer cc_live_..." "https://www.clearcotelabs.com/api/v1/runs?limit=20&before=2026-10-01T08:00:00.000Z"

# cancel: answers with the run. A queued run is cancelled at once; a running one
# stops within about 15 seconds (the answer may still say running)
curl -X DELETE -H "authorization: Bearer cc_live_..." https://www.clearcotelabs.com/api/v1/runs/<id>

Na lista, limit vai de 1 a 100 (padrão 20) e before é uma data ISO; task é cortado em 200 caracteres, resultStatus é result.status e costEur é o mesmo objeto da execução. O SDK tem as mesmas chamadas: runs.get, runs.list, runs.cancel, e runs.wait para uma execução que você criou com wait=False.

Transferência e gravação

Com handoff: true, uma execução que trava (needs_input ou blocked) não falha de imediato. Ela pausa como waiting_for_human com um link ao vivo em handoff.liveUrl; uma pessoa o abre, faz login ou conclui a verificação e clica em “I'm done”. O Jet então recomeça na mesma página com a mesma tarefa. Uma execução pode ser transferida até três vezes; se ninguém terminar dentro de handoffTimeoutSec, ela termina como estava. Detalhes em Transferência e webhooks.

Com record: true você também recebe um MP4 da execução, que pode baixar ou compartilhar. Veja Gravações e eventos.

Cobrança

Uma execução é cobrada em duas partes, do mesmo saldo pré-pago dos seus navegadores:

  • O navegador, exatamente como qualquer sessão hospedada: por GB de tráfego, proxy residencial incluído.
  • O agente, por milhão de tokens: os tokens de entrada do modelo de decisão a eurPerMTok (os tokens de saída dele não são cobrados), e os tokens de entrada e saída dos modelos de texto e de extração a eurPerMTokTextIn e eurPerMTokTextOut. Ele é cobrado uma única vez, quando a execução termina, arredondado para cima ao milionésimo de euro.
  • Desafios, só quando a execução usa o serviço de resolução de desafios com a nossa chave: por desafio resolvido, contabilizado em browser.
text
agent = decision.inputTokens × eurPerMTok / 1,000,000
      + (text.inputTokens + extract.inputTokens) × eurPerMTokTextIn / 1,000,000
      + (text.outputTokens + extract.outputTokens) × eurPerMTokTextOut / 1,000,000

As tarifas são fixadas quando a execução é criada e não mudam enquanto ela roda. As atuais estão no pricing de toda resposta de criação. Uma execução mostra quanto custa em costEur desde o início: browser cresce enquanto ela roda, agent é somado uma vez no fim, e total é a soma dos dois. Iniciar uma execução exige o mesmo saldo mínimo que iniciar um navegador.

Atualizado em 22 de nov. de 2026 · SDK 0.70.5 · navegador r63

Esta página foi útil?