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 SDKcloud.runs.create) nimmt eine Aufgabe in normalen Worten und eineurlals Startpunkt. Jet arbeitet in einem gehosteten Browser und liefert JSON.- Mit einem
schemakommen die angefragten Daten inresult.outputzurück, geprüft gegen das Schema. - Ein Run macht höchstens
maxStepsSchritte (Standard 40, maximal 100) und stoppt standardmäßig nach 900 Sekunden. - Ein Run ist
succeeded, wenn Jet mitdoneabgeschlossen hat und die Ausgabe gültig ist. Jedes andere Ende istfailed, 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"])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:
- 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.
- 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.
- 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.
- 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.
| Feld | Typ | Bedeutung |
|---|---|---|
task | string | Pflichtfeld. Was zu tun ist, in normalen Worten: 1 bis 4000 Zeichen. Zeilenumbrüche und Tabs sind erlaubt, andere Steuerzeichen nicht. |
url | http(s) URL | Die Seite, auf der der Run startet. Jet arbeitet mit den Bedienelementen der Seite, daher braucht fast jede Aufgabe eine. |
schema | object | Ein 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. |
secrets | object | Werte, die der Run eintippen darf, ohne dass das Modell sie je zu sehen bekommt, auch TOTP-Codes. Höchstens 20. Siehe Secrets und 2FA. |
maxSteps | integer | 1 bis 100, Standard 40. Die maximale Zahl an Schritten, bevor Jet mit budget stoppt (der Run ist dann failed). |
handoff | boolean | Standard false. Wenn Jet mit needs_input oder blocked stoppt, pausieren und den Browser an eine Person übergeben. Siehe Übergabe. |
handoffTimeoutSec | integer | 60 bis 3600, Standard 600. Wie lange eine Übergabe auf die Person wartet. |
record | boolean | Standard false. Den Run als MP4 aufzeichnen. Siehe Aufzeichnungen. |
urlist der Startpunkt des Runs: Jet öffnet sie selbst, statt sie vor Ihrer Verbindung laden zu lassen.keepAlive(alles außerfalse) ergibt einen400: Ein Run hat keinen Client, der sich neu verbinden könnte, und endet, wenn Jet fertig ist.timeoutSecist bei einem Run standardmäßig 900.maxGb,idleTimeoutSecund 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,handoffoderrecord), antwortet das Erstellen mit503 NO_CAPACITYund nichts wird eingereiht. Danach wartet der Run darauf, dass dieser Server ihn übernimmt; geschieht das nicht innerhalb von fünf Minuten, endet er alsexpired. - 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:
{
"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
| status | Bedeutung |
|---|---|
queued | Erstellt, wartet darauf, dass sein Server ihn übernimmt. |
running | Der 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_human | Pausiert für eine Übergabe (handoff: true). handoff.liveUrl ist der Link, den Sie weitergeben. |
succeeded | Jet hat mit done abgeschlossen und outputError ist null (mit einem schema: die Ausgabe war gültig). |
failed | Er 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. |
cancelled | Sie haben ihn gestoppt: DELETE /api/v1/runs/<id> oder ein Stopp seiner Session. |
expired | Kein 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")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:
{
"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 | Bedeutung |
|---|---|
done | Jet 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. |
blocked | Nichts auf der Seite brachte Jet weiter, oder Jet hat 12-mal hintereinander gescrollt. |
needs_input | Der 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. |
budget | maxSteps wurde erreicht. |
error | Etwas ist kaputtgegangen: der Browser, ein Modellaufruf oder der Runner. detail sagt, was. |
detail: warum er gestoppt hat, in Worten, wenn er nicht fertig wurde.urlundtitle: 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.outputundoutputError: 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) undextract(strukturierte Ausgabe).estimatedUsdist Jets eigene Schätzung seiner Modellkosten, nicht das, was Ihnen berechnet wird; das istcostEur.handoffs: wie oft der Run an eine Person übergeben wurde.elapsedMs: wie lange Jet gearbeitet hat.jet: die Version, die lief, odernull, 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 letztensteps, und zuallerletzt wirdoutputzunullmit einemoutputError(der Run ist dann alsofailed).
Jeder Eintrag in steps:
| Feld | Bedeutung |
|---|---|
step | 1, 2, 3, … |
kind | Was Jet getan hat: click, fill, select, scroll, wait. |
action | Das verwendete Bedienelement, nach seiner Beschriftung. |
text | Was getippt wurde, Secrets als {{name}} dargestellt; null bei Schritten, die nichts tippen. |
probability | Wie sicher sich das Entscheidungsmodell bei diesem Schritt war, 0 bis 1, oder null. Ein niedriger Wert kennzeichnet einen wackligen Schritt. |
decideMs | Wie lange die Entscheidung gedauert hat, oder null. |
atMs | Wann der Schritt stattfand, in Millisekunden seit dem Start des Runs, oder null. |
url | Die Seite, auf der der Schritt stattfand. |
ledTo | Die Seitenadresse nach dem Schritt, oder null. |
pageChanged | Ob 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, undoutputErroristnull. - Passt es auch dann nicht, ist
outputnull,outputErrornennt den Grund, und der Run istfailed, selbst wenn Jetdonegemeldet hat. - Ohne
schemagibt es keine Extraktion: Die Antwort steht inmarkdownunddetail.
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:
{
"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
urlan, 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
maxStepsbei kurzen Aufgaben, damit ein Run, der sich im Kreis dreht, früh stoppt, und setzen SiemaxGb.
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.
# 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 zueurPerMTokTextInundeurPerMTokTextOut. 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.
agent = decision.inputTokens × eurPerMTok / 1,000,000
+ (text.inputTokens + extract.inputTokens) × eurPerMTokTextIn / 1,000,000
+ (text.outputTokens + extract.outputTokens) × eurPerMTokTextOut / 1,000,000Die 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.