Aller au contenu

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.create dans le SDK) prend une tâche en langage courant et une url de départ. Jet travaille dans un navigateur hébergé et renvoie du JSON.
  • Ajoutez un schema et les données demandées reviennent dans result.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 succeeded quand Jet a terminé avec done et que la sortie est valide. Toute autre fin est failed, 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"])
Cet onglet s’exécute sur votre machine.

Le moteur : Clearcote Jet

Clearcote Jet est notre agent de navigateur open source (MIT). Il travaille en boucle, une étape à la fois :

  1. 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.
  2. 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.
  3. 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.
  4. 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.

ChampTypeSignification
taskstringObligatoire. 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.
urlhttp(s) URLLa 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.
schemaobjectUn 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.
secretsobjectDes 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.
maxStepsintegerDe 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).
handoffbooleanfalse 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.
handoffTimeoutSecintegerDe 60 à 3600, 600 par défaut. Combien de temps un passage de relais attend la personne.
recordbooleanfalse par défaut. Enregistrer l’exécution en MP4. Voir enregistrements.
  • url est 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 que false) donne un 400 : une exécution n’a pas de client qui se reconnecterait, et se termine quand Jet a fini.
  • timeoutSec vaut 900 par défaut pour une exécution. maxGb, idleTimeoutSec et 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, handoff ou record), la création répond 503 NO_CAPACITY et 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 en expired.
  • 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 :

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 liste ce qui a été accepté mais semble incorrect, par exemple un secret que la tâche n’utilise jamais.

Statuts

statusSignification
queuedCréée, en attente que son serveur la prenne en charge.
runningLe 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_humanEn pause pour un passage de relais (handoff: true). handoff.liveUrl est le lien à envoyer.
succeededJet a terminé avec done et outputError vaut null (avec un schema : la sortie était valide).
failedElle 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.
cancelledVous l’avez arrêtée : DELETE /api/v1/runs/<id>, ou un arrêt de sa session.
expiredAucun 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")
Cet onglet s’exécute sur votre machine.

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é :

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.statusSignification
doneJet 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.
blockedRien sur la page ne permettait d’avancer, ou Jet a défilé 12 fois de suite.
needs_inputIl 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.
budgetElle a atteint maxSteps.
errorQuelque 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. url et title : 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.
  • output et outputError : 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é) et extract (sortie structurée). estimatedUsd est l’estimation par Jet de son propre coût de modèle, pas ce qui vous est facturé ; ça, c’est costEur.
  • 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é, ou null si 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ères steps, et en tout dernier output devient null avec un outputError (l’exécution est donc failed).

Chaque entrée de steps :

ChampSignification
step1, 2, 3, …
kindCe que Jet a fait : click, fill, select, scroll, wait.
actionLe contrôle utilisé, par son libellé.
textCe qui a été saisi, les secrets affichés sous la forme {{name}} ; null pour les étapes qui ne saisissent rien.
probabilityLe degré de certitude du modèle de décision pour cette étape, de 0 à 1, ou null. Une valeur basse signale une étape fragile.
decideMsLe temps qu’a pris la décision, ou null.
atMsLe moment de l’étape, en millisecondes depuis le début de l’exécution, ou null.
urlLa page sur laquelle l’étape a eu lieu.
ledToL’adresse de la page après l’étape, ou null.
pageChangedSi 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, et outputError vaut null.
  • S’il ne correspond toujours pas, output vaut null, outputError dit pourquoi, et l’exécution est failed même si Jet a signalé done.
  • Sans schema, pas d’extraction : la réponse se trouve dans markdown et detail.

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 :

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

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’url la 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 maxSteps pour les tâches courtes, afin qu’une exécution qui tourne en rond s’arrête tôt, et définissez maxGb.

É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.

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>

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 à eurPerMTokTextIn et eurPerMTokTextOut. 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.
text
agent = decision.inputTokens × eurPerMTok / 1,000,000
      + (text.inputTokens + extract.inputTokens) × eurPerMTokTextIn / 1,000,000
      + (text.outputTokens + extract.outputTokens) × eurPerMTokTextOut / 1,000,000

Les 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.

Mis à jour le 22 nov. 2026 · SDK 0.70.5 · navigateur r63

Cette page vous a-t-elle été utile ?