エージェント実行:タスクを渡すと JSON が返る
普通の言葉で書いたタスク、開始ページ、必要なら JSON Schema を送ってください。ホスト型の Clearcote ブラウザがそのページで Clearcote Jet を実行し、JSON が返ってきます。何が起きたか、実行したすべてのステップ、そして求めたデータが、スキーマに照らして検証された形で含まれます。
要点
POST /api/v1/runs(SDK ではcloud.runs.create)は、普通の言葉で書いたタスクと開始地点のurlを受け取ります。Jet がホスト型ブラウザで作業し、JSON を返します。schemaを付けると、求めたデータがスキーマで検証されたうえでresult.outputに返ります。- 1 回の実行のステップ数は最大
maxSteps(デフォルト 40、上限 100)で、デフォルトでは 900 秒で停止します。 - Jet が
doneで終了し、出力が有効なら実行はsucceededです。それ以外の終わり方はすべてfailedになります。ただし、あなたがキャンセルした場合とキューで期限切れになった場合は除きます。 - 料金はプリペイド残高から支払います。ブラウザは GB 単位、エージェントは 100 万トークン単位です。
クイックスタート
CLEARCOTE_API_KEY に API キー(API keys ページで取得)を設定し、SDK 0.34.0 以降を使います。
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"])実行を担うもの:Clearcote Jet
Clearcote Jet は、私たちのオープンソースのブラウザエージェント(MIT)です。1 ステップずつ、次のループで作業します。
- 見る。人がいま使える操作要素を一覧にします。表示されていて、有効で、ポップアップに隠れていないもので、iframe 内の要素も含みます。パスワード欄は決して読み取りません。
- 決める。高速な判断モデルへの 1 回のリクエストで、ステップの種類と操作要素をまとめて選びます。選択肢ごとに確率が付き、通常は数百ミリ秒で終わります。モデルはその一覧から選ぶだけで、コードや座標を書くことはありません。
- 動かす。ページが変わっていないことを確認してから、本物のマウスを曲線の軌跡で動かし、クリックし、人と同じように 1 キーずつ入力します。
- 答える。タスクが終わると、最終ページのうちタスクに答える部分を Markdown に変換し、
schemaがあればあなたの JSON にします。
サイトごとのコードはありません。同じループが、ステップのたびにページを見直します。Jet は新しいタブを開くリンクはたどらず、CAPTCHA、ファイルのアップロード、canvas アプリ、closed な shadow root には対応しません。そうした場面では引き継ぎを使ってください。
常に最新の Jet
各サーバーは Jet の main ブランチを自動で追跡します。新しいバージョンが出ると、サーバーはそれを現行版と並べてインストールし、セルフテストを実行して、合格したときだけ切り替えます。以降の実行は新しいバージョンを使います。実行中のものは開始時のバージョンのまま進み、更新に失敗した場合は以前のバージョンがそのまま残ります。各結果は実行したバージョンを result.jet(version と commit)で報告し、実行の run.started イベントも同様です。そのため、挙動の変化を正確なコミットまでたどれます。
リクエスト
POST /api/v1/runs は以下のフィールドに加えて、POST /api/v1/browsers のすべてのオプションを受け付けます。ペルソナ、プロキシと出口の地域、identity、profile、version、adblock、solveSliders、solveCheckboxes、solvePressHold、challengeService、各種制限、note、worker です。
| フィールド | 型 | 意味 |
|---|---|---|
task | string | 必須。やってほしいことを普通の言葉で書きます。1〜4000 文字。改行とタブは使えますが、それ以外の制御文字は使えません。 |
url | http(s) URL | 実行を開始するページ。Jet はページ上の操作要素を使って作業するため、ほぼすべてのタスクで必要です。 |
schema | object | result.output 用の JSON Schema(draft-07)。最大 16 KB、ネストは最大 20 階層で、トップレベルの type は "object" または "array" でなければなりません。構造化出力を参照してください。 |
secrets | object | モデルに一度も見せずに実行が入力できる値。TOTP コードも含みます。最大 20 個。シークレットと 2FA を参照してください。 |
maxSteps | integer | 1〜100、デフォルトは 40。Jet が budget で停止するまでに実行できる最大ステップ数です(その場合、実行は failed になります)。 |
handoff | boolean | デフォルトは false。Jet が needs_input または blocked で止まったときに一時停止し、ブラウザを人に引き継ぎます。引き継ぎを参照してください。 |
handoffTimeoutSec | integer | 60〜3600、デフォルトは 600。引き継ぎで人を待つ時間です。 |
record | boolean | デフォルトは false。実行を MP4 で録画します。録画を参照してください。 |
urlは実行の開始地点です。接続前に読み込んでおくのではなく、Jet 自身が開きます。keepAlive(false以外の値)は400になります。実行には再接続するクライアントがなく、Jet が終われば終了するためです。- 実行では
timeoutSecのデフォルトが 900 です。maxGb、idleTimeoutSec、残高は通常のセッションと同じように適用されます。 - 実行は作成した時点で、Jet を備えたサーバーに割り当てられます。空きのあるサーバーがない場合や、要求された機能(
schema、secrets、handoff、record)に対応するサーバーがない場合、作成リクエストは503 NO_CAPACITYを返し、何もキューに入りません。その後、実行はそのサーバーが引き取るのを待ち、5 分以内に引き取られなければexpiredで終了します。 - タスク、スキーマ、シークレットによって設定が 60 KB を超える実行は
400 TOO_LARGEになります。
レスポンスは新しい実行を含む 201 です。その pricing には、この実行に適用される料金が入っています。
{
"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 には、受け付けたものの誤りの可能性があるものが並びます。たとえば、タスクで一度も使われないシークレットです。
ステータス
| status | 意味 |
|---|---|
queued | 作成済みで、担当サーバーが引き取るのを待っています。 |
running | ブラウザが起動し、Jet が作業中です。担当サーバーから報告が途絶えている間もこの状態で、そのとき session.status は lost になります。サーバーから二度と報告がなければ、セッションの最大継続時間の 1 時間後に実行は failed(session.endReason は worker_silent、result は null)で終了します。サーバーが再起動した場合は、復帰した時点で終了します(worker_restarted)。 |
waiting_for_human | 引き継ぎのため一時停止中です(handoff: true)。handoff.liveUrl が送るべきリンクです。 |
succeeded | Jet が done で終了し、outputError が null です(schema がある場合は、出力が有効だったことを意味します)。 |
failed | それ以外の形で終了しました。blocked、needs_input、budget、error、スキーマに合わない出力や 1 MB を超える出力、制限、起動しなかったブラウザ、結果がまったくない場合、または担当サーバーが実行を引き取ったときに見つけた問題です。開けなくなったシークレット(secrets_unreadable)、使い切った残高(insufficient_balance)、停止されたアカウント(suspended)などです。どれに当たるかは result と session.endReason でわかります。 |
cancelled | あなたが停止しました。DELETE /api/v1/runs/<id>、またはそのセッションの停止によるものです。 |
expired | 時間内(5 分)にどのサーバーも引き取りませんでした。料金は一切かかりません。 |
変化するのは queued、running、waiting_for_human だけで、それ以外は最終状態です。GET /api/v1/runs/<id> を 1〜2 秒ごとにポーリングするか、SDK に待たせるか、Webhook で run.finished を受け取ってください。サーバーが引き取る前にキャンセルされた実行や期限切れになった実行は、run.finished(および session.ended)を送りません。それらはポーリングで確認してください。
SDK での待機
runs.create はデフォルトで待機します。1.5 秒ごとに時間制限なしでポーリングし、終了した実行を返します。timeout(秒)で待ち時間に上限を設けられ、それを過ぎると SDK は CloudTimeoutError を送出します。その last は SDK が最後に見た時点の実行で、実行自体は続きます。wait=False(Node では { wait: false })は作成時のレスポンスをすぐに返し、あとから runs.wait(id) で待てます。waiting_for_human は終了ではないため、待機は引き継ぎの間も続きます。on_update(Node では onUpdate)は、ステータスや引き継ぎの状態が変わるたびに実行を引数に呼ばれます。指定しない場合、SDK は引き継ぎのライブリンクを stderr に出力します。
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")結果
GET /api/v1/runs/<id> は実行を返します。result は終了するまで null で、一度も動かなかった実行では null のままです。
{
"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 | 意味 |
|---|---|
done | Jet がタスク完了と判断しました。これはモデルの判断なので、重要な点は確認してください。たとえばスキーマの required フィールドを使います。 |
blocked | ページ上に先へ進めるものがなかったか、12 回続けてスクロールしました。 |
needs_input | フィールドに必要な値がタスクに書かれていないか、許可されていないサイトでシークレットを求められました。値をタスクに書くか、シークレットを使ってください。 |
budget | maxSteps に達しました。 |
error | ブラウザ、モデル呼び出し、またはランナーで問題が起きました。内容は detail に書かれます。 |
detail:完了しなかった場合に、止まった理由を言葉で示します。urlとtitle:最後にいたページです。markdown:最終ページのうちタスクに答える部分です。完了しなかった実行では、画面に表示されていた内容です。outputとoutputError:あなたの JSON、またはそれがない理由です(後述)。usage:モデルごとのトークン数とリクエスト数です。decision(ステップを選ぶモデル)、text(入力する値を書くモデル、使った場合)、extract(構造化出力)があります。estimatedUsdは Jet 自身によるモデルコストの見積もりで、請求額ではありません。請求額はcostEurです。handoffs:実行が人に引き継がれた回数です。elapsedMs:Jet が作業した時間です。jet:実行したバージョン、不明な場合はnullです。- 結果のサイズは最大 1 MB です。それを超える結果は拒否されず切り詰められます。まず
markdown、次に末尾のsteps、最後にoutputがnullになってoutputErrorが付きます(そのため実行はfailedになります)。
steps の各エントリ:
| フィールド | 意味 |
|---|---|
step | 1, 2, 3, … |
kind | 何をしたか:click、fill、select、scroll、wait。 |
action | 使った操作要素(ラベル名)。 |
text | 入力した内容。シークレットは {{name}} と表示されます。何も入力しないステップでは null。 |
probability | このステップに対する判断モデルの確信度(0〜1)、または null。低い値は不安定なステップの目印です。 |
decideMs | 判断にかかった時間、または null。 |
atMs | ステップが行われた時刻(実行開始からのミリ秒)、または null。 |
url | ステップが行われたページ。 |
ledTo | ステップ後のページのアドレス、または null。 |
pageChanged | ステップ後にページが変わったかどうか。 |
構造化出力
schema を指定すると、別の抽出モデルが実行の終わったページ(タスク、ページのアドレスとタイトル、本文)を読み、スキーマに沿った JSON を書きます。JSON はスキーマで検証され、合わなければ検証エラーを添えてモデルにもう一度だけ書き直させます。ページのテキストは指示ではなく信頼できないデータとして渡されるため、ページがモデルを言いくるめて別の答えを出させることはできません。
- 有効な JSON は
result.outputに入り、outputErrorはnullです。 - それでも合わない場合、
outputはnull、outputErrorに理由が入り、Jet がdoneを報告していても実行はfailedになります。 schemaがなければ抽出は行われず、答えはmarkdownとdetailにあります。
スキーマは小さく保ち、意図をはっきり書いてください。description フィールドはモデルが読むので、形式の指定に使います(「YYYY-MM-DD」「ユーロ建ての価格、数値」など)。ページにないかもしれない値には null を許可してください。そうすれば、価格がなくても実行が失敗にならず null になります。
{
"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"]
}タスクの書き方
- 完了の姿を書く。「料金ページを開いて、いちばん安いプランを読み取る」なら答えのあるページで終わりますが、「料金を見る」ではそうなりません。
- 値はタスクに書く。Jet はタスクに書かれた言葉を入力します。「靴を検索」ではなく「青いランニングシューズ 44 サイズを検索」と書いてください。パスワードやコードはタスクの本文ではなく、必ずシークレットに入れます。
- 作業のある場所から始める。トップページではなく、わかっているいちばん深い
urlを指定してください。ステップごとに時間とトークンがかかります。 - ログインは一度だけ。実行のたびにログインするのではなく、ログイン済みのプロファイルで実行します。
- 上限を設ける。短いタスクでは
maxStepsを下げて、堂々巡りする実行が早めに止まるようにし、maxGbも設定します。
ステップ、時間、制限
maxSteps(デフォルト 40、上限 100)はステップ数の上限で、達すると実行は budget で止まります。Jet は 12 回続けてスクロールした場合も、blocked で自ら止まります。これに加えてセッションの制限も適用されます。timeoutSec(実行ではデフォルト 900 秒)、maxGb、idleTimeoutSec、残高です。いずれかによって実行が終了した場合は failed となり、session.endReason にその制限が示されます。
実行はセッションでもある
実行とは、エージェントが付いたブラウザセッションで、ID も同じです。GET /api/v1/browsers/<id> でトラフィックと使用量を確認でき、ダッシュボードではライブビュー付きで表示され、イベントタイムラインには各ステップが発生と同時に記録されます。実行に CDP で接続することはできません(409 になります)。実行を操作するのは Jet だけです。
# 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>一覧では、limit は 1〜100(デフォルト 20)、before は ISO 形式の日時です。task は 200 文字で切り詰められ、resultStatus は result.status、costEur は実行のものと同じオブジェクトです。SDK にも同じ呼び出しがあります。runs.get、runs.list、runs.cancel、そして wait=False で作成した実行には runs.wait を使います。
引き継ぎと録画
handoff: true を指定すると、行き詰まった実行(needs_input または blocked)はすぐには失敗しません。waiting_for_human として一時停止し、handoff.liveUrl にライブリンクが入ります。人がそのリンクを開き、ログインしたりチェックを済ませたりしてから「I'm done」を押すと、Jet が同じページ、同じタスクで作業を再開します。引き継ぎは 1 回の実行につき最大 3 回までで、handoffTimeoutSec 以内に誰も終えなければ、実行はその時点の状態で終了します。詳しくは引き継ぎ & Webhookを参照してください。
record: true を指定すると、実行の MP4 も得られ、ダウンロードや共有ができます。録画 & イベントを参照してください。
課金
実行の料金は 2 つに分かれ、ブラウザと同じプリペイド残高から支払われます。
- ブラウザ:通常のホスト型セッションとまったく同じで、トラフィック 1 GB ごとに課金され、住宅用プロキシ込みです。
- エージェント:100 万トークン単位です。判断モデルの入力トークンは
eurPerMTokで課金され(出力トークンは課金されません)、テキストモデルと抽出モデルの入力・出力トークンはeurPerMTokTextInとeurPerMTokTextOutで課金されます。実行の終了時に一度だけ請求され、100 万分の 1 ユーロ単位で切り上げます。 - チャレンジ:実行が当社のキーでチャレンジ解決サービスを使った場合のみ、解決したチャレンジごとに課金され、
browserに計上されます。
agent = decision.inputTokens × eurPerMTok / 1,000,000
+ (text.inputTokens + extract.inputTokens) × eurPerMTokTextIn / 1,000,000
+ (text.outputTokens + extract.outputTokens) × eurPerMTokTextOut / 1,000,000料金は実行の作成時に確定し、実行中は変わりません。現在の料金は、作成時のレスポンスの pricing に毎回含まれています。実行は最初から costEur でコストを示します。browser は実行中に増えていき、agent は最後に一度だけ加算され、total はその合計です。実行を開始するには、ブラウザを起動するときと同じ最低残高が必要です。