Saltar al contenido

Ejecuciones de agente: entra una tarea, sale JSON

Envía una tarea en lenguaje natural, una página de inicio y, si quieres, un JSON Schema. Un navegador alojado de Clearcote ejecuta Clearcote Jet sobre ella y recibes JSON: qué pasó, cada paso que dio y los datos que pediste, validados contra tu schema.

En resumen

  • POST /api/v1/runs (cloud.runs.create en el SDK) recibe una tarea en lenguaje natural y una url donde empezar. Jet trabaja en un navegador alojado y devuelve JSON.
  • Añade un schema y los datos que pediste vuelven en result.output, validados contra él.
  • Una ejecución da como máximo maxSteps pasos (40 por defecto, 100 como máximo) y se detiene tras 900 segundos por defecto.
  • Una ejecución queda succeeded cuando Jet terminó con done y la salida es válida. Cualquier otro final es failed, salvo que la hayas cancelado o haya expirado en la cola.
  • Pagas el navegador por GB y el agente por millón de tokens, desde tu saldo prepago.

Inicio rápido

Con una clave de API en CLEARCOTE_API_KEY (de la página API keys) y el SDK 0.34.0 o posterior:

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 pestaña se ejecuta en tu máquina.

Quién la ejecuta: Clearcote Jet

Clearcote Jet es nuestro agente de navegador de código abierto (MIT). Trabaja en un bucle, un paso a la vez:

  1. Mirar. Lista los controles que una persona podría usar en ese momento: visibles, habilitados, no tapados por un pop-up, incluidos los que están dentro de iframes. Los campos de contraseña nunca se leen.
  2. Decidir. Una sola petición a un modelo de decisión rápido elige a la vez el tipo de paso y el control, con una probabilidad para cada opción, normalmente en unos cientos de milisegundos. El modelo solo elige de esa lista; nunca escribe código ni coordenadas.
  3. Actuar. Comprueba que la página no haya cambiado, luego mueve un ratón real por una trayectoria curva, hace clic y escribe tecla por tecla, como lo hace una persona.
  4. Responder. Cuando la tarea está hecha, las partes de la página final que la responden se convierten en markdown y, con un schema, en tu JSON.

No hay código por sitio: el mismo bucle vuelve a mirar la página después de cada paso. Jet no sigue enlaces que abren una pestaña nueva, y no gestiona CAPTCHAs, subidas de archivos, apps de canvas ni shadow roots cerrados. Para eso, usa un traspaso.

Siempre el Jet actual

Cada servidor sigue por su cuenta la rama main de Jet. Cuando llega una versión nueva, el servidor la instala junto a la actual, ejecuta una autoprueba y solo cambia a ella si la supera; las siguientes ejecuciones la usan. Una ejecución en curso conserva la versión con la que empezó, y una actualización que falla deja la versión anterior en su sitio. Cada resultado indica la versión con la que se ejecutó en result.jet (version y commit), y también el evento run.started de la ejecución, así que un cambio de comportamiento se puede rastrear hasta el commit exacto.

La petición

POST /api/v1/runs acepta estos campos, además de todas las opciones de POST /api/v1/browsers: persona, proxy y ubicación de salida, identity, profile, version, adblock, solveSliders, solveCheckboxes, solvePressHold, challengeService, los límites, note y worker.

CampoTipoSignificado
taskstringObligatorio. Qué hacer, en lenguaje natural: de 1 a 4000 caracteres. Se permiten saltos de línea y tabulaciones, pero no otros caracteres de control.
urlhttp(s) URLLa página en la que empieza la ejecución. Jet trabaja con los controles de la página, así que casi todas las tareas necesitan una.
schemaobjectUn JSON Schema para result.output (draft-07). Como máximo 16 KB, con un anidamiento de 20 niveles como máximo, y su type de nivel superior debe ser "object" o "array". Consulta Salida estructurada.
secretsobjectValores que la ejecución puede escribir sin que el modelo los vea nunca, incluidos códigos TOTP. Como máximo 20. Consulta secretos y 2FA.
maxStepsintegerDe 1 a 100, 40 por defecto. El máximo de pasos que Jet puede dar antes de detenerse con budget (la ejecución queda entonces failed).
handoffbooleanfalse por defecto. Cuando Jet se detiene con needs_input o blocked, pausa la ejecución y entrega el navegador a una persona. Consulta traspaso.
handoffTimeoutSecintegerDe 60 a 3600, 600 por defecto. Cuánto tiempo espera un traspaso a la persona.
recordbooleanfalse por defecto. Graba la ejecución como MP4. Consulta grabaciones.
  • url es donde empieza la ejecución: Jet la abre por sí mismo, en lugar de tenerla cargada antes de que te conectes.
  • keepAlive (cualquier valor que no sea false) da un 400: una ejecución no tiene un cliente que se vuelva a conectar, y termina cuando Jet acaba.
  • timeoutSec vale 900 por defecto en una ejecución. maxGb, idleTimeoutSec y tu saldo se aplican como en cualquier sesión.
  • Una ejecución se asigna a un servidor con Jet al crearla. Si ninguno tiene espacio, o ninguno admite lo que pide (schema, secrets, handoff o record), la creación responde 503 NO_CAPACITY y no se encola nada. Después, la ejecución espera a que ese servidor la tome; si no lo hace en cinco minutos, termina como expired.
  • Una ejecución cuya tarea, schema y secretos hacen que su configuración supere 60 KB da un 400 TOO_LARGE.

La respuesta es un 201 con la nueva ejecución. Su pricing contiene las tarifas con las que se cobra esta ejecución:

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 lo que se aceptó pero parece incorrecto, por ejemplo un secreto que la tarea nunca usa.

Estados

statusSignificado
queuedCreada, esperando a que su servidor la tome.
runningEl navegador está en marcha y Jet está trabajando. También mientras su servidor no reporta: session.status es entonces lost. Si el servidor no vuelve a reportar, la ejecución termina como failed (session.endReason worker_silent, result null) una hora después de la duración máxima de una sesión; si el servidor se reinició, en cuanto vuelve (worker_restarted).
waiting_for_humanEn pausa por un traspaso (handoff: true). handoff.liveUrl es el enlace que debes enviar.
succeededJet terminó con done y outputError es null (con un schema: la salida era válida).
failedTerminó de cualquier otra forma: blocked, needs_input, budget o error, una salida que no coincidía con el schema o superaba 1 MB, un límite, un navegador que no arrancó, ningún resultado, o algo que su servidor encontró al tomar la ejecución: secretos que ya no se podían abrir (secrets_unreadable), un saldo agotado (insufficient_balance) o una cuenta suspendida (suspended). result y session.endReason indican cuál.
cancelledLa detuviste tú: DELETE /api/v1/runs/<id>, o deteniendo su sesión.
expiredNingún servidor la tomó a tiempo (cinco minutos). Nunca se cobra.

queued, running y waiting_for_human son los únicos estados que cambian; el resto son finales. Consulta GET /api/v1/runs/<id> cada uno o dos segundos, deja que el SDK espere por ti, o recibe un run.finished por webhook. Una ejecución cancelada o expirada antes de que un servidor la tomara no envía run.finished (ni session.ended): para esas, consulta el estado.

Esperar en el SDK

runs.create espera por defecto: consulta cada 1,5 segundos sin límite de tiempo y devuelve la ejecución terminada. timeout (en segundos) limita la espera; pasado ese tiempo, el SDK lanza CloudTimeoutError, cuyo last es la ejecución tal como la vio por última vez, y la ejecución continúa. wait=False (Node: { wait: false }) devuelve de inmediato la respuesta de la creación, y runs.wait(id) espera por ella más tarde. waiting_for_human no es un final, así que una espera continúa durante un traspaso: on_update (Node: onUpdate) se llama con la ejecución cada vez que cambia su estado o su traspaso, y sin él el SDK imprime en stderr el enlace en vivo del traspaso.

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 pestaña se ejecuta en tu máquina.

El resultado

GET /api/v1/runs/<id> responde con la ejecución. result es null hasta que termina, y sigue siendo null en una ejecución que nunca llegó a correr:

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
doneJet consideró la tarea completada. Es el criterio del modelo: comprueba lo que importa, por ejemplo con campos required en un schema.
blockedNada en la página le permitía avanzar, o hizo scroll 12 veces seguidas.
needs_inputA la tarea le falta un valor que necesita un campo, o se pidió un secreto en un sitio donde no está permitido. Pon el valor en la tarea o usa un secreto.
budgetAlcanzó maxSteps.
errorAlgo falló: el navegador, una llamada al modelo o el runner. detail dice qué.
  • detail: por qué se detuvo, en palabras, cuando no terminó. url y title: la página en la que terminó.
  • markdown: las partes de la página final que responden a la tarea; en una ejecución que no terminó, lo que había en pantalla.
  • output y outputError: tu JSON, o por qué no lo hay (ver abajo).
  • usage: tokens y peticiones por modelo: decision (el que elige los pasos), text (el modelo que escribe los valores a teclear, cuando se usa) y extract (salida estructurada). estimatedUsd es la estimación propia de Jet de su costo de modelo, no lo que se te cobra; eso es costEur.
  • handoffs: cuántas veces se entregó la ejecución a una persona. elapsedMs: cuánto tiempo trabajó Jet. jet: la versión que se ejecutó, o null si no se conoce.
  • Un resultado ocupa como máximo 1 MB. Uno más grande se recorta en lugar de rechazarse: primero markdown, después los últimos steps, y por último output pasa a null con un outputError (así que la ejecución queda failed).

Cada entrada de steps:

CampoSignificado
step1, 2, 3, …
kindQué hizo: click, fill, select, scroll, wait.
actionEl control que usó, por su etiqueta.
textLo que escribió, con los secretos mostrados como {{name}}; null en los pasos que no escriben nada.
probabilityQué tan seguro estaba el modelo de decisión de este paso, de 0 a 1, o null. Un valor bajo señala un paso dudoso.
decideMsCuánto tardó la decisión, o null.
atMsCuándo ocurrió el paso, en milisegundos desde el inicio de la ejecución, o null.
urlLa página en la que ocurrió el paso.
ledToLa dirección de la página después del paso, o null.
pageChangedSi la página cambió después del paso.

Salida estructurada

Con un schema, un modelo de extracción aparte lee la página en la que terminó la ejecución (la tarea, la dirección y el título de la página, y su texto) y escribe JSON para tu schema. El JSON se valida contra el schema; si no coincide, el modelo tiene un intento más con el error de validación. El texto de la página se le pasa como datos no confiables, nunca como instrucciones, así que una página no puede convencerlo de dar otra respuesta.

  • El JSON válido llega a result.output, y outputError es null.
  • Si sigue sin coincidir, output es null, outputError dice por qué, y la ejecución queda failed aunque Jet haya reportado done.
  • Sin un schema no hay extracción: la respuesta está en markdown y detail.

Mantén los schemas pequeños y di lo que quieres decir. El modelo lee los campos description, así que úsalos para los formatos (“YYYY-MM-DD”, “precio en euros, un número”). Permite null para los valores que una página puede no tener, de modo que un precio que falta sea null y no una ejecución fallida:

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

Cómo escribir una tarea

  • Di cómo se ve el final. “Abre la página de precios y lee el plan más barato” termina en una página con la respuesta; “mira sus precios” no.
  • Escribe los valores en la tarea. Jet teclea palabras que están en la tarea: “busca tenis azules para correr talla 44”, no “busca zapatos”. Las contraseñas y los códigos van en secretos, nunca en el texto de la tarea.
  • Empieza donde está el trabajo. Da la url más profunda que conozcas en lugar de la página de inicio. Cada paso cuesta tiempo y tokens.
  • Inicia sesión una sola vez. Ejecuta sobre un perfil que ya tenga la sesión iniciada en lugar de iniciar sesión en cada ejecución.
  • Ponle un límite. Baja maxSteps en tareas cortas para que una ejecución que da vueltas en círculos se detenga pronto, y define maxGb.

Pasos, tiempo y límites

maxSteps (40 por defecto, 100 como máximo) limita los pasos; al llegar al tope, la ejecución se detiene con budget. Jet también se detiene por sí mismo tras 12 scrolls seguidos, con blocked. Los límites de la sesión se siguen aplicando encima: timeoutSec (900 segundos por defecto en una ejecución), maxGb, idleTimeoutSec y tu saldo. Cuando uno de ellos termina la ejecución, esta queda failed y session.endReason nombra el límite.

Una ejecución es una sesión

Una ejecución es una sesión de navegador con un agente conectado, con el mismo id. GET /api/v1/browsers/<id> muestra su tráfico y su uso, el panel la muestra con su vista en vivo, y la línea de tiempo de eventos lista cada paso a medida que ocurre. No puedes conectarte a una ejecución por CDP (eso da un 409): Jet es quien la controla, y nadie más.

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>

En la lista, limit va de 1 a 100 (20 por defecto) y before es una fecha ISO; task se recorta a 200 caracteres, resultStatus es result.status y costEur es el mismo objeto que en la ejecución. El SDK tiene las mismas llamadas: runs.get, runs.list, runs.cancel, y runs.wait para una ejecución que creaste con wait=False.

Traspaso y grabación

Con handoff: true, una ejecución que se atasca (needs_input o blocked) no falla de inmediato. Se pausa como waiting_for_human con un enlace en vivo en handoff.liveUrl; una persona lo abre, inicia sesión o completa la verificación, y pulsa “I'm done”. Jet vuelve a empezar en la misma página con la misma tarea. Una ejecución se puede traspasar hasta tres veces; si nadie termina dentro de handoffTimeoutSec, termina tal como estaba. Más detalles en Traspaso y webhooks.

Con record: true también obtienes un MP4 de la ejecución, que puedes descargar o compartir. Consulta Grabaciones y eventos.

Facturación

Una ejecución se cobra en dos partes, del mismo saldo prepago que tus navegadores:

  • El navegador, exactamente igual que cualquier sesión alojada: por GB de tráfico, proxy residencial incluido.
  • El agente, por millón de tokens: los tokens de entrada del modelo de decisión a eurPerMTok (sus tokens de salida no se cobran), y los tokens de entrada y salida de los modelos de texto y de extracción a eurPerMTokTextIn y eurPerMTokTextOut. Se cobra una sola vez, cuando termina la ejecución, redondeado hacia arriba a la millonésima de euro.
  • Desafíos, solo cuando la ejecución usa el servicio de resolución de desafíos con nuestra clave: por desafío resuelto, contabilizado en 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

Las tarifas se fijan al crear la ejecución y no cambian mientras corre. Las actuales están en el pricing de cada respuesta de creación. Una ejecución muestra lo que cuesta en costEur desde el principio: browser crece mientras corre, agent se suma una vez al final, y total es la suma de los dos. Iniciar una ejecución requiere el mismo saldo mínimo que iniciar un navegador.

Actualizado el 22 nov 2026 · SDK 0.70.5 · navegador r63

¿Te resultó útil esta página?