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.createno SDK) recebe uma tarefa em linguagem natural e umaurlpara começar. O Jet trabalha em um navegador hospedado e devolve JSON.- Adicione um
schemae os dados que você pediu voltam emresult.output, validados contra ele. - Uma execução dá no máximo
maxStepspassos (padrão 40, no máximo 100) e para após 900 segundos por padrão. - Uma execução fica
succeededquando o Jet terminou comdonee 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"])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:
- 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.
- 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.
- 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.
- 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.
| Campo | Tipo | Significado |
|---|---|---|
task | string | Obrigató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. |
url | http(s) URL | A 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. |
schema | object | Um 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. |
secrets | object | Valores 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. |
maxSteps | integer | De 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). |
handoff | boolean | Padrão false. Quando o Jet para com needs_input ou blocked, pausa e entrega o navegador a uma pessoa. Veja transferência. |
handoffTimeoutSec | integer | De 60 a 3600, padrão 600. Quanto tempo uma transferência espera pela pessoa. |
record | boolean | Padrã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 defalse) dá um400: uma execução não tem cliente para se reconectar e termina quando o Jet acaba.timeoutSectem padrão 900 em uma execução.maxGb,idleTimeoutSece 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,handoffourecord), a criação responde503 NO_CAPACITYe 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 comoexpired. - 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:
{
"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
| status | Significado |
|---|---|
queued | Criada, esperando que seu servidor a assuma. |
running | O 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_human | Pausada para uma transferência (handoff: true). handoff.liveUrl é o link a enviar. |
succeeded | O Jet terminou com done e outputError é null (com um schema: a saída era válida). |
failed | Terminou 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. |
cancelled | Você a parou: DELETE /api/v1/runs/<id>, ou parando a sessão dela. |
expired | Nenhum 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")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:
{
"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.status | Significado |
|---|---|
done | O Jet julgou a tarefa concluída. É o julgamento do modelo: confira o que importa, por exemplo com campos required em um schema. |
blocked | Nada na página permitia avançar, ou ele rolou 12 vezes seguidas. |
needs_input | Falta 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. |
budget | Atingiu maxSteps. |
error | Algo quebrou: o navegador, uma chamada ao modelo ou o runner. detail diz o quê. |
detail: por que parou, em palavras, quando não terminou.urletitle: 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.outputeoutputError: 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) eextract(saída estruturada).estimatedUsdé a estimativa do próprio Jet para o custo dos modelos, não o que você paga; isso é ocostEur.handoffs: quantas vezes a execução foi entregue a uma pessoa.elapsedMs: quanto tempo o Jet trabalhou.jet: a versão que rodou, ounullse 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 últimosstepse, por último,outputviranullcom umoutputError(e a execução ficafailed).
Cada entrada em steps:
| Campo | Significado |
|---|---|
step | 1, 2, 3, … |
kind | O que ele fez: click, fill, select, scroll, wait. |
action | O controle usado, pelo seu rótulo. |
text | O que ele digitou, com os segredos mostrados como {{name}}; null nos passos que não digitam nada. |
probability | O quanto o modelo de decisão tinha certeza deste passo, de 0 a 1, ou null. Um valor baixo indica um passo duvidoso. |
decideMs | Quanto tempo a decisão levou, ou null. |
atMs | Quando o passo aconteceu, em milissegundos desde o início da execução, ou null. |
url | A página em que o passo aconteceu. |
ledTo | O endereço da página depois do passo, ou null. |
pageChanged | Se 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, eoutputErrorénull. - Se ainda não bater,
outputénull,outputErrordiz por quê, e a execução ficafailedmesmo que o Jet tenha reportadodone. - Sem
schemanão há extração: a resposta está emmarkdownedetail.
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:
{
"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
urlmais 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
maxStepsem tarefas curtas para que uma execução que anda em círculos pare cedo, e definamaxGb.
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.
# 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 aeurPerMTokTextIneeurPerMTokTextOut. 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.
agent = decision.inputTokens × eurPerMTok / 1,000,000
+ (text.inputTokens + extract.inputTokens) × eurPerMTokTextIn / 1,000,000
+ (text.outputTokens + extract.outputTokens) × eurPerMTokTextOut / 1,000,000As 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.