Zum Inhalt springen

Agent-Runs: eine Aufgabe rein, JSON raus

Schicken Sie eine Aufgabe in normalen Worten, eine Startseite und, wenn Sie möchten, ein JSON Schema. Ein gehosteter Clearcote-Browser führt darauf Clearcote Jet aus, und Sie bekommen JSON zurück: was passiert ist, jeden Schritt und die angefragten Daten, geprüft gegen Ihr Schema.

Kurz gesagt

  • POST /api/v1/runs (im SDK cloud.runs.create) nimmt eine Aufgabe in normalen Worten und eine url als Startpunkt. Jet arbeitet in einem gehosteten Browser und liefert JSON.
  • Mit einem schema kommen die angefragten Daten in result.output zurück, geprüft gegen das Schema.
  • Ein Run macht höchstens maxSteps Schritte (Standard 40, maximal 100) und stoppt standardmäßig nach 900 Sekunden.
  • Ein Run ist succeeded, wenn Jet mit done abgeschlossen hat und die Ausgabe gültig ist. Jedes andere Ende ist failed, es sei denn, Sie haben ihn abgebrochen oder er ist in der Warteschlange abgelaufen.
  • Sie zahlen für den Browser pro GB und für den Agent pro Million Tokens, aus Ihrem Prepaid-Guthaben.

Schnellstart

Mit einem API-Schlüssel in CLEARCOTE_API_KEY (von der Seite API keys) und SDK 0.34.0 oder neuer:

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"])
Dieser Tab läuft auf Ihrem Rechner.

Was ihn ausführt: Clearcote Jet

Clearcote Jet ist unser Open-Source-Browser-Agent (MIT). Er arbeitet in einer Schleife, einen Schritt nach dem anderen:

  1. Hinsehen. Er listet die Bedienelemente auf, die eine Person gerade benutzen könnte: sichtbar, aktiviert, nicht von einem Pop-up verdeckt, auch solche in iframes. Passwortfelder werden nie gelesen.
  2. Entscheiden. Eine einzige Anfrage an ein schnelles Entscheidungsmodell wählt die Art des Schritts und das Bedienelement zusammen aus, mit einer Wahrscheinlichkeit für jede Option, meist in wenigen hundert Millisekunden. Das Modell wählt nur aus dieser Liste; es schreibt nie Code oder Koordinaten.
  3. Handeln. Er prüft, dass sich die Seite nicht verändert hat, bewegt dann eine echte Maus auf einer gekrümmten Bahn, klickt und tippt Taste für Taste, so wie ein Mensch.
  4. Antworten. Ist die Aufgabe erledigt, werden die Teile der letzten Seite, die sie beantworten, in Markdown umgewandelt und, mit einem schema, in Ihr JSON.

Es gibt keinen Code pro Site: Dieselbe Schleife sieht sich die Seite nach jedem Schritt neu an. Jet folgt keinen Links, die einen neuen Tab öffnen, und kann keine CAPTCHAs, Datei-Uploads, Canvas-Apps oder geschlossenen Shadow Roots bedienen. Dafür gibt es die Übergabe.

Immer das aktuelle Jet

Jeder Server verfolgt selbstständig den main-Branch von Jet. Kommt eine neue Version, installiert der Server sie neben der aktuellen, führt einen Selbsttest aus und wechselt erst, wenn dieser bestanden ist; die nächsten Runs nutzen dann die neue Version. Ein laufender Run behält die Version, mit der er gestartet ist, und ein fehlgeschlagenes Update lässt die vorherige Version bestehen. Jedes Ergebnis nennt in result.jet (version und commit) die Version, mit der es lief, ebenso das Ereignis run.started des Runs. So lässt sich eine Verhaltensänderung auf den genauen Commit zurückführen.

Die Anfrage

POST /api/v1/runs nimmt diese Felder, dazu jede Option von POST /api/v1/browsers: Persona, Proxy und Exit-Standort, identity, profile, version, adblock, solveSliders, solveCheckboxes, solvePressHold, challengeService, die Limits, note und worker.

FeldTypBedeutung
taskstringPflichtfeld. Was zu tun ist, in normalen Worten: 1 bis 4000 Zeichen. Zeilenumbrüche und Tabs sind erlaubt, andere Steuerzeichen nicht.
urlhttp(s) URLDie Seite, auf der der Run startet. Jet arbeitet mit den Bedienelementen der Seite, daher braucht fast jede Aufgabe eine.
schemaobjectEin JSON Schema für result.output (draft-07). Höchstens 16 KB, höchstens 20 Ebenen tief verschachtelt, und sein type auf oberster Ebene muss "object" oder "array" sein. Siehe Strukturierte Ausgabe.
secretsobjectWerte, die der Run eintippen darf, ohne dass das Modell sie je zu sehen bekommt, auch TOTP-Codes. Höchstens 20. Siehe Secrets und 2FA.
maxStepsinteger1 bis 100, Standard 40. Die maximale Zahl an Schritten, bevor Jet mit budget stoppt (der Run ist dann failed).
handoffbooleanStandard false. Wenn Jet mit needs_input oder blocked stoppt, pausieren und den Browser an eine Person übergeben. Siehe Übergabe.
handoffTimeoutSecinteger60 bis 3600, Standard 600. Wie lange eine Übergabe auf die Person wartet.
recordbooleanStandard false. Den Run als MP4 aufzeichnen. Siehe Aufzeichnungen.
  • url ist der Startpunkt des Runs: Jet öffnet sie selbst, statt sie vor Ihrer Verbindung laden zu lassen.
  • keepAlive (alles außer false) ergibt einen 400: Ein Run hat keinen Client, der sich neu verbinden könnte, und endet, wenn Jet fertig ist.
  • timeoutSec ist bei einem Run standardmäßig 900. maxGb, idleTimeoutSec und Ihr Guthaben gelten wie bei jeder Session.
  • Ein Run wird beim Erstellen einem Server mit Jet zugewiesen. Hat keiner Platz oder unterstützt keiner, was er verlangt (schema, secrets, handoff oder record), antwortet das Erstellen mit 503 NO_CAPACITY und nichts wird eingereiht. Danach wartet der Run darauf, dass dieser Server ihn übernimmt; geschieht das nicht innerhalb von fünf Minuten, endet er als expired.
  • Ein Run, dessen Aufgabe, Schema und Secrets seine Einstellungen größer als 60 KB machen, ergibt einen 400 TOO_LARGE.

Die Antwort ist ein 201 mit dem neuen Run. Sein pricing enthält die Tarife, zu denen dieser Run abgerechnet wird:

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 listet auf, was angenommen wurde, aber falsch aussieht, zum Beispiel ein Secret, das die Aufgabe nie verwendet.

Status

statusBedeutung
queuedErstellt, wartet darauf, dass sein Server ihn übernimmt.
runningDer Browser läuft und Jet arbeitet. Auch, solange sein Server sich nicht meldet: session.status ist dann lost. Meldet sich der Server nie wieder, endet der Run eine Stunde nach der maximalen Dauer einer Session als failed (session.endReason worker_silent, result null); wurde der Server neu gestartet, sobald er wieder da ist (worker_restarted).
waiting_for_humanPausiert für eine Übergabe (handoff: true). handoff.liveUrl ist der Link, den Sie weitergeben.
succeededJet hat mit done abgeschlossen und outputError ist null (mit einem schema: die Ausgabe war gültig).
failedEr endete auf jede andere Weise: blocked, needs_input, budget oder error, eine Ausgabe, die nicht zum Schema passte oder größer als 1 MB war, ein Limit, ein Browser, der nicht startete, gar kein Ergebnis oder etwas, das sein Server beim Übernehmen des Runs feststellte: Secrets, die sich nicht mehr öffnen ließen (secrets_unreadable), ein aufgebrauchtes Guthaben (insufficient_balance) oder ein gesperrter Account (suspended). result und session.endReason sagen, was davon.
cancelledSie haben ihn gestoppt: DELETE /api/v1/runs/<id> oder ein Stopp seiner Session.
expiredKein Server hat ihn rechtzeitig übernommen (fünf Minuten). Wird nie abgerechnet.

queued, running und waiting_for_human sind die einzigen Zustände, die sich ändern; alle anderen sind endgültig. Fragen Sie GET /api/v1/runs/<id> alle ein bis zwei Sekunden ab, lassen Sie das SDK für Sie warten, oder lassen Sie sich per Webhook ein run.finished schicken. Ein Run, der abgebrochen wurde oder abgelaufen ist, bevor ein Server ihn übernommen hat, sendet kein run.finished (und kein session.ended): Fragen Sie diese ab.

Warten im SDK

runs.create wartet standardmäßig: Es fragt alle 1,5 Sekunden ohne Zeitlimit ab und gibt den fertigen Run zurück. timeout (in Sekunden) begrenzt das Warten; danach wirft das SDK CloudTimeoutError, dessen last der Run in seinem zuletzt gesehenen Zustand ist, und der Run läuft weiter. wait=False (Node: { wait: false }) gibt sofort die Antwort des Erstellens zurück, und runs.wait(id) wartet später darauf. waiting_for_human ist nicht fertig, also wartet ein Wait auch über eine Übergabe hinweg: on_update (Node: onUpdate) wird jedes Mal mit dem Run aufgerufen, wenn sich sein Status oder seine Übergabe ändert, und ohne diesen Callback gibt das SDK den Live-Link der Übergabe auf stderr aus.

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")
Dieser Tab läuft auf Ihrem Rechner.

Das Ergebnis

GET /api/v1/runs/<id> antwortet mit dem Run. result ist null, bis er fertig ist, und bleibt null bei einem Run, der nie gelaufen ist:

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.statusBedeutung
doneJet hat die Aufgabe als erledigt beurteilt. Das ist das Urteil des Modells: Prüfen Sie, worauf es ankommt, zum Beispiel mit required-Feldern in einem Schema.
blockedNichts auf der Seite brachte Jet weiter, oder Jet hat 12-mal hintereinander gescrollt.
needs_inputDer Aufgabe fehlt ein Wert, den ein Feld braucht, oder ein Secret wurde auf einer Site verlangt, auf der es nicht erlaubt ist. Schreiben Sie den Wert in die Aufgabe oder verwenden Sie ein Secret.
budgetmaxSteps wurde erreicht.
errorEtwas ist kaputtgegangen: der Browser, ein Modellaufruf oder der Runner. detail sagt, was.
  • detail: warum er gestoppt hat, in Worten, wenn er nicht fertig wurde. url und title: die Seite, auf der er endete.
  • markdown: die Teile der letzten Seite, die die Aufgabe beantworten; bei einem Run, der nicht fertig wurde, das, was auf dem Bildschirm zu sehen war.
  • output und outputError: Ihr JSON oder der Grund, warum es keines gibt (siehe unten).
  • usage: Tokens und Anfragen pro Modell: decision (der Schrittwähler), text (das Modell, das einzutippende Werte schreibt, falls genutzt) und extract (strukturierte Ausgabe). estimatedUsd ist Jets eigene Schätzung seiner Modellkosten, nicht das, was Ihnen berechnet wird; das ist costEur.
  • handoffs: wie oft der Run an eine Person übergeben wurde. elapsedMs: wie lange Jet gearbeitet hat. jet: die Version, die lief, oder null, wenn sie nicht bekannt ist.
  • Ein Ergebnis ist höchstens 1 MB groß. Ein größeres wird gekürzt statt abgelehnt: zuerst markdown, dann die letzten steps, und zuallerletzt wird output zu null mit einem outputError (der Run ist dann also failed).

Jeder Eintrag in steps:

FeldBedeutung
step1, 2, 3, …
kindWas Jet getan hat: click, fill, select, scroll, wait.
actionDas verwendete Bedienelement, nach seiner Beschriftung.
textWas getippt wurde, Secrets als {{name}} dargestellt; null bei Schritten, die nichts tippen.
probabilityWie sicher sich das Entscheidungsmodell bei diesem Schritt war, 0 bis 1, oder null. Ein niedriger Wert kennzeichnet einen wackligen Schritt.
decideMsWie lange die Entscheidung gedauert hat, oder null.
atMsWann der Schritt stattfand, in Millisekunden seit dem Start des Runs, oder null.
urlDie Seite, auf der der Schritt stattfand.
ledToDie Seitenadresse nach dem Schritt, oder null.
pageChangedOb sich die Seite nach dem Schritt geändert hat.

Strukturierte Ausgabe

Mit einem schema liest ein separates Extraktionsmodell die Seite, auf der der Run endete (die Aufgabe, Adresse und Titel der Seite sowie ihren Text), und schreibt JSON für Ihr Schema. Das JSON wird gegen das Schema validiert; passt es nicht, bekommt das Modell mit dem Validierungsfehler einen weiteren Versuch. Der Seitentext wird ihm als nicht vertrauenswürdige Daten übergeben, nie als Anweisungen, sodass eine Seite es nicht zu einer anderen Antwort überreden kann.

  • Gültiges JSON landet in result.output, und outputError ist null.
  • Passt es auch dann nicht, ist output null, outputError nennt den Grund, und der Run ist failed, selbst wenn Jet done gemeldet hat.
  • Ohne schema gibt es keine Extraktion: Die Antwort steht in markdown und detail.

Halten Sie Schemas klein und sagen Sie, was Sie meinen. description-Felder liest das Modell, also nutzen Sie sie für Formate („YYYY-MM-DD“, „Preis in Euro, eine Zahl“). Erlauben Sie null für Werte, die eine Seite vielleicht nicht hat, damit ein fehlender Preis null ist statt eines fehlgeschlagenen Runs:

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

Eine Aufgabe schreiben

  • Sagen Sie, wie „fertig“ aussieht. „Öffne die Preisseite und lies den günstigsten Tarif“ endet auf einer Seite mit der Antwort; „schau dir ihre Preise an“ nicht.
  • Schreiben Sie die Werte in die Aufgabe. Jet tippt Wörter, die in der Aufgabe stehen: „suche nach blauen Laufschuhen Größe 44“, nicht „suche nach Schuhen“. Passwörter und Codes gehören in Secrets, nie in den Aufgabentext.
  • Starten Sie dort, wo die Arbeit ist. Geben Sie die tiefste url an, die Sie kennen, statt der Startseite. Jeder Schritt kostet Zeit und Tokens.
  • Einmal anmelden. Lassen Sie den Run auf einem Profil laufen, das bereits angemeldet ist, statt sich bei jedem Run neu einzuloggen.
  • Begrenzen Sie ihn. Senken Sie maxSteps bei kurzen Aufgaben, damit ein Run, der sich im Kreis dreht, früh stoppt, und setzen Sie maxGb.

Schritte, Zeit und Limits

maxSteps (Standard 40, maximal 100) begrenzt die Schritte; an der Grenze stoppt der Run mit budget. Jet stoppt außerdem von selbst nach 12 Scrollvorgängen in Folge, mit blocked. Die Session-Limits gelten zusätzlich: timeoutSec (bei einem Run standardmäßig 900 Sekunden), maxGb, idleTimeoutSec und Ihr Guthaben. Beendet eines davon den Run, ist er failed, und session.endReason nennt das Limit.

Ein Run ist eine Session

Ein Run ist eine Browser-Session mit angeschlossenem Agent, unter derselben id. GET /api/v1/browsers/<id> zeigt ihren Traffic und ihre Nutzung, das Dashboard zeigt sie mit ihrer Live-Ansicht, und die Ereignis-Timeline listet jeden Schritt in dem Moment, in dem er passiert. Mit einem Run können Sie sich nicht über CDP verbinden (das ergibt einen 409): Jet ist sein einziger Fahrer.

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>

In der Liste ist limit 1 bis 100 (Standard 20) und before ein ISO-Datum; task wird auf 200 Zeichen gekürzt, resultStatus ist result.status und costEur ist dasselbe Objekt wie beim Run. Das SDK hat dieselben Aufrufe: runs.get, runs.list, runs.cancel und runs.wait für einen Run, den Sie mit wait=False erstellt haben.

Übergabe und Aufzeichnung

Mit handoff: true schlägt ein Run, der feststeckt (needs_input oder blocked), nicht sofort fehl. Er pausiert als waiting_for_human mit einem Live-Link in handoff.liveUrl; eine Person öffnet ihn, meldet sich an oder erledigt die Prüfung und drückt „I'm done“. Jet beginnt dann erneut auf derselben Seite mit derselben Aufgabe. Ein Run kann bis zu drei Mal übergeben werden; wird er nicht innerhalb von handoffTimeoutSec abgeschlossen, endet er so, wie er war. Details unter Übergabe & Webhooks.

Mit record: true bekommen Sie zusätzlich ein MP4 des Runs, das Sie herunterladen oder teilen können. Siehe Aufzeichnungen & Ereignisse.

Abrechnung

Ein Run wird in zwei Teilen abgerechnet, aus demselben Prepaid-Guthaben wie Ihre Browser:

  • Der Browser, genau wie jede gehostete Session: pro GB Traffic, Residential-Proxy inklusive.
  • Der Agent, pro Million Tokens: die Input-Tokens des Entscheidungsmodells zu eurPerMTok (seine Output-Tokens werden nicht berechnet) sowie die Input- und Output-Tokens des Text- und des Extraktionsmodells zu eurPerMTokTextIn und eurPerMTokTextOut. Das wird einmal berechnet, wenn der Run endet, aufgerundet auf ein Millionstel Euro.
  • Challenges, nur wenn der Run den Challenge-Service mit unserem Schlüssel nutzt: pro gelöster Challenge, verbucht unter 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

Die Tarife werden beim Erstellen des Runs festgelegt und ändern sich nicht, während er läuft. Die aktuellen stehen im pricing jeder Antwort auf ein Erstellen. Ein Run zeigt von Anfang an in costEur, was er kostet: browser wächst, während er läuft, agent kommt einmal am Ende hinzu, und total ist die Summe aus beidem. Einen Run zu starten erfordert dasselbe Mindestguthaben wie einen Browser zu starten.

Aktualisiert am 22. Nov. 2026 · SDK 0.70.5 · Browser r63

War diese Seite hilfreich?