Exécutions d’agent : une tâche en entrée, du JSON en sortie
Envoyez une tâche en langage courant, une page de départ et, si vous le souhaitez, un JSON Schema. Un navigateur Clearcote hébergé y exécute Clearcote Jet et vous recevez du JSON : ce qui s’est passé, chaque étape, et les données demandées, vérifiées par rapport à votre schéma.
En bref
POST /api/v1/runs(cloud.runs.createdans le SDK) prend une tâche en langage courant et uneurlde départ. Jet travaille dans un navigateur hébergé et renvoie du JSON.- Ajoutez un
schemaet les données demandées reviennent dansresult.output, vérifiées par rapport à celui-ci. - Une exécution fait au plus
maxStepsétapes (40 par défaut, 100 au maximum) et s’arrête par défaut au bout de 900 secondes. - Une exécution est
succeededquand Jet a terminé avecdoneet que la sortie est valide. Toute autre fin estfailed, sauf si vous l’avez annulée ou si elle a expiré dans la file d’attente. - Vous payez le navigateur au GB et l’agent au million de tokens, sur votre solde prépayé.
Démarrage rapide
Avec une clé d’API dans CLEARCOTE_API_KEY (depuis la page API keys) et le SDK 0.34.0 ou plus récent :
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"])Le moteur : Clearcote Jet
Clearcote Jet est notre agent de navigateur open source (MIT). Il travaille en boucle, une étape à la fois :
- Observer. Il liste les contrôles qu’une personne pourrait utiliser à cet instant : visibles, activés, non masqués par une pop-up, y compris ceux dans des iframes. Les champs de mot de passe ne sont jamais lus.
- Décider. Une seule requête à un modèle de décision rapide choisit à la fois le type d’étape et le contrôle, avec une probabilité pour chaque option, généralement en quelques centaines de millisecondes. Le modèle ne fait que choisir dans cette liste ; il n’écrit jamais de code ni de coordonnées.
- Agir. Il vérifie que la page n’a pas changé, puis déplace une vraie souris le long d’une trajectoire courbe, clique et tape touche par touche, comme le fait une personne.
- Répondre. Une fois la tâche accomplie, les parties de la page finale qui y répondent sont converties en markdown et, avec un
schema, en votre JSON.
Il n’y a pas de code propre à chaque site : la même boucle réexamine la page après chaque étape. Jet ne suit pas les liens qui ouvrent un nouvel onglet, et ne gère pas les CAPTCHA, les envois de fichiers, les applications canvas ni les shadow roots fermés. Pour ceux-là, utilisez un passage de relais.
Toujours le Jet actuel
Chaque serveur suit de lui-même la branche main de Jet. Quand une nouvelle version arrive, le serveur l’installe à côté de l’actuelle, lance un autotest et ne bascule dessus que s’il réussit ; les exécutions suivantes l’utilisent. Une exécution en cours garde la version avec laquelle elle a démarré, et une mise à jour qui échoue laisse la version précédente en place. Chaque résultat indique la version utilisée dans result.jet (version et commit), tout comme l’événement run.started de l’exécution : un changement de comportement peut ainsi être rattaché au commit exact.
La requête
POST /api/v1/runs accepte ces champs, plus toutes les options de POST /api/v1/browsers : persona, proxy et lieu de sortie, identity, profile, version, adblock, solveSliders, solveCheckboxes, solvePressHold, challengeService, les limites, note et worker.
| Champ | Type | Signification |
|---|---|---|
task | string | Obligatoire. Ce qu’il faut faire, en langage courant : de 1 à 4000 caractères. Les retours à la ligne et les tabulations sont acceptés, les autres caractères de contrôle non. |
url | http(s) URL | La page sur laquelle l’exécution démarre. Jet travaille avec les contrôles de la page, donc presque toutes les tâches en ont besoin. |
schema | object | Un JSON Schema pour result.output (draft-07). 16 KB au maximum, 20 niveaux d’imbrication au maximum, et son type de premier niveau doit être "object" ou "array". Voir Sortie structurée. |
secrets | object | Des valeurs que l’exécution peut saisir sans que le modèle les voie jamais, y compris des codes TOTP. 20 au maximum. Voir secrets et 2FA. |
maxSteps | integer | De 1 à 100, 40 par défaut. Le nombre maximal d’étapes que Jet peut faire avant de s’arrêter avec budget (l’exécution est alors failed). |
handoff | boolean | false par défaut. Quand Jet s’arrête avec needs_input ou blocked, mettre en pause et passer le navigateur à une personne. Voir passage de relais. |
handoffTimeoutSec | integer | De 60 à 3600, 600 par défaut. Combien de temps un passage de relais attend la personne. |
record | boolean | false par défaut. Enregistrer l’exécution en MP4. Voir enregistrements. |
urlest l’endroit où l’exécution démarre : Jet l’ouvre lui-même, au lieu qu’elle soit chargée avant votre connexion.keepAlive(toute valeur autre quefalse) donne un400: une exécution n’a pas de client qui se reconnecterait, et se termine quand Jet a fini.timeoutSecvaut 900 par défaut pour une exécution.maxGb,idleTimeoutSecet votre solde s’appliquent comme pour toute session.- Une exécution est placée sur un serveur doté de Jet dès sa création. Si aucun n’a de place, ou si aucun ne prend en charge ce qu’elle demande (
schema,secrets,handoffourecord), la création répond503 NO_CAPACITYet rien n’est mis en file d’attente. L’exécution attend ensuite que ce serveur la prenne en charge ; s’il ne le fait pas dans les cinq minutes, elle se termine enexpired. - Une exécution dont la tâche, le schéma et les secrets font dépasser 60 KB à ses paramètres donne un
400 TOO_LARGE.
La réponse est un 201 avec la nouvelle exécution. Son pricing contient les tarifs auxquels cette exécution est facturée :
{
"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 liste ce qui a été accepté mais semble incorrect, par exemple un secret que la tâche n’utilise jamais.
Statuts
| status | Signification |
|---|---|
queued | Créée, en attente que son serveur la prenne en charge. |
running | Le navigateur tourne et Jet travaille. Aussi tant que son serveur ne donne plus de nouvelles : session.status vaut alors lost. Si le serveur ne se manifeste plus jamais, l’exécution se termine en failed (session.endReason worker_silent, result null) une heure après la durée maximale d’une session ; si le serveur a redémarré, dès qu’il est de retour (worker_restarted). |
waiting_for_human | En pause pour un passage de relais (handoff: true). handoff.liveUrl est le lien à envoyer. |
succeeded | Jet a terminé avec done et outputError vaut null (avec un schema : la sortie était valide). |
failed | Elle s’est terminée de toute autre façon : blocked, needs_input, budget ou error, une sortie qui ne correspondait pas au schéma ou dépassait 1 MB, une limite, un navigateur qui n’a pas démarré, aucun résultat, ou un problème que son serveur a constaté en la prenant en charge : des secrets qui ne pouvaient plus être ouverts (secrets_unreadable), un solde épuisé (insufficient_balance) ou un compte suspendu (suspended). result et session.endReason indiquent lequel. |
cancelled | Vous l’avez arrêtée : DELETE /api/v1/runs/<id>, ou un arrêt de sa session. |
expired | Aucun serveur ne l’a prise en charge à temps (cinq minutes). Jamais facturée. |
queued, running et waiting_for_human sont les seuls états qui changent ; les autres sont définitifs. Interrogez GET /api/v1/runs/<id> toutes les une ou deux secondes, laissez le SDK attendre pour vous, ou recevez un run.finished par webhook. Une exécution annulée ou expirée avant qu’un serveur l’ait prise en charge n’envoie pas de run.finished (ni de session.ended) : pour celles-là, interrogez l’API.
Attendre dans le SDK
runs.create attend par défaut : il interroge toutes les 1,5 secondes sans limite de temps et renvoie l’exécution terminée. timeout (en secondes) plafonne l’attente ; au-delà, le SDK lève CloudTimeoutError, dont last est l’exécution telle qu’il l’a vue pour la dernière fois, et l’exécution continue. wait=False (Node : { wait: false }) renvoie tout de suite la réponse de création, et runs.wait(id) l’attend plus tard. waiting_for_human n’est pas une fin, donc une attente se poursuit pendant un passage de relais : on_update (Node : onUpdate) est appelé avec l’exécution à chaque changement de son statut ou de son passage de relais, et sans lui le SDK affiche sur stderr le lien en direct du passage de relais.
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")Le résultat
GET /api/v1/runs/<id> répond avec l’exécution. result vaut null jusqu’à ce qu’elle soit terminée, et reste null pour une exécution qui n’a jamais tourné :
{
"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 | Signification |
|---|---|
done | Jet a jugé la tâche terminée. C’est le jugement du modèle : vérifiez ce qui compte, par exemple avec des champs required dans un schéma. |
blocked | Rien sur la page ne permettait d’avancer, ou Jet a défilé 12 fois de suite. |
needs_input | Il manque à la tâche une valeur dont un champ a besoin, ou un secret a été demandé sur un site où il n’est pas autorisé. Mettez la valeur dans la tâche, ou utilisez un secret. |
budget | Elle a atteint maxSteps. |
error | Quelque chose a lâché : le navigateur, un appel au modèle ou le runner. detail dit quoi. |
detail: pourquoi elle s’est arrêtée, en toutes lettres, quand elle n’a pas abouti.urlettitle: la page sur laquelle elle s’est terminée.markdown: les parties de la page finale qui répondent à la tâche ; pour une exécution qui n’a pas abouti, ce qui était à l’écran.outputetoutputError: votre JSON, ou la raison de son absence (voir plus bas).usage: tokens et requêtes par modèle :decision(celui qui choisit les étapes),text(le modèle qui écrit les valeurs à saisir, s’il est utilisé) etextract(sortie structurée).estimatedUsdest l’estimation par Jet de son propre coût de modèle, pas ce qui vous est facturé ; ça, c’estcostEur.handoffs: combien de fois l’exécution a été passée à une personne.elapsedMs: combien de temps Jet a travaillé.jet: la version qui a tourné, ounullsi elle n’est pas connue.- Un résultat fait au plus 1 MB. Un résultat plus gros est tronqué plutôt que refusé : d’abord
markdown, puis les dernièressteps, et en tout dernieroutputdevientnullavec unoutputError(l’exécution est doncfailed).
Chaque entrée de steps :
| Champ | Signification |
|---|---|
step | 1, 2, 3, … |
kind | Ce que Jet a fait : click, fill, select, scroll, wait. |
action | Le contrôle utilisé, par son libellé. |
text | Ce qui a été saisi, les secrets affichés sous la forme {{name}} ; null pour les étapes qui ne saisissent rien. |
probability | Le degré de certitude du modèle de décision pour cette étape, de 0 à 1, ou null. Une valeur basse signale une étape fragile. |
decideMs | Le temps qu’a pris la décision, ou null. |
atMs | Le moment de l’étape, en millisecondes depuis le début de l’exécution, ou null. |
url | La page sur laquelle l’étape a eu lieu. |
ledTo | L’adresse de la page après l’étape, ou null. |
pageChanged | Si la page a changé après l’étape. |
Sortie structurée
Avec un schema, un modèle d’extraction distinct lit la page sur laquelle l’exécution s’est terminée (la tâche, l’adresse et le titre de la page, et son texte) et écrit du JSON pour votre schéma. Le JSON est validé par rapport au schéma ; s’il ne correspond pas, le modèle a droit à un essai de plus avec l’erreur de validation. Le texte de la page lui est transmis comme des données non fiables, jamais comme des instructions, si bien qu’une page ne peut pas l’amener à donner une autre réponse.
- Le JSON valide arrive dans
result.output, etoutputErrorvautnull. - S’il ne correspond toujours pas,
outputvautnull,outputErrordit pourquoi, et l’exécution estfailedmême si Jet a signalédone. - Sans
schema, pas d’extraction : la réponse se trouve dansmarkdownetdetail.
Gardez des schémas petits et dites ce que vous voulez dire. Les champs description sont lus par le modèle, alors servez-vous-en pour les formats (« YYYY-MM-DD », « prix en euros, un nombre »). Autorisez null pour les valeurs qu’une page peut ne pas avoir, afin qu’un prix manquant donne null plutôt qu’une exécution échouée :
{
"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"]
}Rédiger une tâche
- Dites à quoi ressemble la fin. « Ouvre la page des tarifs et lis l’offre la moins chère » se termine sur une page qui contient la réponse ; « regarde leurs tarifs » non.
- Écrivez les valeurs dans la tâche. Jet tape des mots qui figurent dans la tâche : « cherche des chaussures de running bleues pointure 44 », pas « cherche des chaussures ». Les mots de passe et les codes vont dans les secrets, jamais dans le texte de la tâche.
- Partez de là où se trouve le travail. Donnez l’
urlla plus profonde que vous connaissez plutôt que la page d’accueil. Chaque étape coûte du temps et des tokens. - Connectez-vous une seule fois. Lancez l’exécution sur un profil déjà connecté au lieu de vous reconnecter à chaque exécution.
- Plafonnez. Baissez
maxStepspour les tâches courtes, afin qu’une exécution qui tourne en rond s’arrête tôt, et définissezmaxGb.
Étapes, durée et limites
maxSteps (40 par défaut, 100 au maximum) plafonne les étapes ; au plafond, l’exécution s’arrête avec budget. Jet s’arrête aussi de lui-même après 12 défilements d’affilée, avec blocked. Les limites de la session s’appliquent en plus : timeoutSec (900 secondes par défaut pour une exécution), maxGb, idleTimeoutSec et votre solde. Quand l’une d’elles met fin à l’exécution, celle-ci est failed et session.endReason nomme la limite.
Une exécution est une session
Une exécution est une session de navigateur à laquelle un agent est rattaché, sous le même id. GET /api/v1/browsers/<id> montre son trafic et son utilisation, le tableau de bord l’affiche avec sa vue en direct, et la chronologie des événements liste chaque étape au moment où elle se produit. Vous ne pouvez pas vous connecter à une exécution via CDP (c’est un 409) : Jet en est le seul pilote.
# 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>Dans la liste, limit va de 1 à 100 (20 par défaut) et before est une date ISO ; task est coupé à 200 caractères, resultStatus est result.status et costEur est le même objet que sur l’exécution. Le SDK propose les mêmes appels : runs.get, runs.list, runs.cancel, et runs.wait pour une exécution créée avec wait=False.
Passage de relais et enregistrement
Avec handoff: true, une exécution bloquée (needs_input ou blocked) n’échoue pas tout de suite. Elle se met en pause en waiting_for_human avec un lien en direct dans handoff.liveUrl ; une personne l’ouvre, se connecte ou passe la vérification, puis appuie sur « I'm done ». Jet repart alors sur la même page avec la même tâche. Une exécution peut être passée à une personne jusqu’à trois fois ; si personne ne termine dans le délai handoffTimeoutSec, elle se termine telle quelle. Détails dans Passage de relais et webhooks.
Avec record: true, vous obtenez aussi un MP4 de l’exécution, que vous pouvez télécharger ou partager. Voir Enregistrements et événements.
Facturation
Une exécution est facturée en deux parties, sur le même solde prépayé que vos navigateurs :
- Le navigateur, exactement comme toute session hébergée : au GB de trafic, proxy résidentiel compris.
- L’agent, au million de tokens : les tokens d’entrée du modèle de décision à
eurPerMTok(ses tokens de sortie ne sont pas facturés), et les tokens d’entrée et de sortie des modèles de texte et d’extraction àeurPerMTokTextIneteurPerMTokTextOut. Il est débité une seule fois, à la fin de l’exécution, arrondi au millionième d’euro supérieur. - Les défis, uniquement quand l’exécution utilise le service de résolution de défis avec notre clé : par défi résolu, comptés dans
browser.
agent = decision.inputTokens × eurPerMTok / 1,000,000
+ (text.inputTokens + extract.inputTokens) × eurPerMTokTextIn / 1,000,000
+ (text.outputTokens + extract.outputTokens) × eurPerMTokTextOut / 1,000,000Les tarifs sont fixés à la création de l’exécution et ne changent pas pendant qu’elle tourne. Les tarifs actuels figurent dans le pricing de chaque réponse de création. Une exécution affiche son coût dans costEur dès le départ : browser augmente pendant qu’elle tourne, agent s’ajoute une fois à la fin, et total est la somme des deux. Lancer une exécution demande le même solde minimum que lancer un navigateur.