智能体任务:输入一个任务,输出 JSON
用自然语言发送一个任务、一个起始页面,如有需要再附上一个 JSON Schema。一个托管的 Clearcote 浏览器会在该页面上运行 Clearcote Jet,然后你会拿到 JSON:发生了什么、执行的每一步,以及你要的数据,并已按你的 schema 校验。
要点
POST /api/v1/runs(SDK 中为cloud.runs.create)接收一个用自然语言写的任务和一个起始url。Jet 在托管浏览器中工作并返回 JSON。- 加上
schema,你要的数据就会经其校验后出现在result.output中。 - 一次运行最多执行
maxSteps步(默认 40,最多 100),默认 900 秒后停止。 - 当 Jet 以
done结束且输出有效时,运行为succeeded。其他任何结束方式都是failed,除非是你取消了它,或它在队列中过期。 - 浏览器按 GB 计费,智能体按百万 token 计费,均从你的预付余额中扣除。
快速开始
在 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)。它在一个循环中工作,每次一步:
- 观察。列出一个人此刻能用的控件:可见、已启用、没有被弹窗遮挡,包括 iframe 里的控件。从不读取密码字段。
- 决策。向一个快速决策模型发送一次请求,同时选出步骤类型和控件,并给出每个选项的概率,通常只需几百毫秒。模型只从这份列表中选择,从不编写代码或坐标。
- 执行。先确认页面没有变化,然后沿曲线路径移动真实鼠标、点击,并像人一样逐键输入。
- 作答。任务完成后,最终页面中回答任务的部分会被转换成 Markdown,有
schema时还会转换成你的 JSON。
没有针对单个网站的代码:同一个循环在每一步之后重新查看页面。Jet 不会跟随在新标签页中打开的链接,也不处理 CAPTCHA、文件上传、canvas 应用或封闭的 shadow root。遇到这些情况,请使用人工交接。
始终是最新的 Jet
每台服务器都会自行跟踪 Jet 的 main 分支。新版本发布后,服务器会把它安装在当前版本旁边,运行自检,只有通过后才切换过去;之后的运行都使用新版本。正在进行的运行会保持开始时的版本,更新失败则保留之前的版本。每个结果都会在 result.jet(version 和 commit)中报告所用的版本,运行的 run.started 事件也一样,因此行为变化可以追溯到具体的提交。
请求
POST /api/v1/runs 接受下列字段,以及 POST /api/v1/browsers 的所有选项:身份画像(persona)、代理和出口位置、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,不会排队。之后运行会等待该服务器接手;如果五分钟内没有接手,就以expired结束。 - 如果任务、schema 和密钥使运行的设置超过 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。如果服务器再也没有上报,运行会在会话最长时长之后一小时以 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,输出不符合 schema 或超过 1 MB,触发某项限制,浏览器没能启动,根本没有结果,或者服务器在接手运行时发现了问题:密钥已无法打开(secrets_unreadable)、余额已用完(insufficient_balance)或账户被暂停(suspended)。具体是哪一种,看 result 和 session.endReason。 |
cancelled | 你停止了它:DELETE /api/v1/runs/<id>,或停止了它的会话。 |
expired | 没有服务器及时接手(五分钟内)。不会计费。 |
只有 queued、running 和 waiting_for_human 会变化,其余都是最终状态。每一两秒轮询一次 GET /api/v1/runs/<id>,让 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 判断任务已完成。这是模型的判断:请核对关键内容,例如在 schema 中使用 required 字段。 |
blocked | 页面上没有任何东西能让它继续推进,或者它连续滚动了 12 次。 |
needs_input | 任务缺少某个字段需要的值,或者在不允许使用某个密钥的网站上被要求输入该密钥。请把值写进任务,或使用密钥。 |
budget | 达到了 maxSteps。 |
error | 出了故障:浏览器、某次模型调用或运行器。detail 会说明是什么。 |
detail:没有完成时,用文字说明停止的原因。url和title:结束时所在的页面。markdown:最终页面中回答任务的部分;对于没有完成的运行,则是当时屏幕上的内容。output和outputError:你的 JSON,或没有 JSON 的原因(见下文)。usage:按模型统计的 token 和请求数: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 时,一个单独的提取模型会读取运行结束时所在的页面(任务、页面的地址和标题以及页面文本),并按你的 schema 编写 JSON。JSON 会根据 schema 校验;不符合时,模型会带着校验错误再试一次。页面文本作为不可信数据传给它,从不作为指令,因此页面无法诱导它给出别的答案。
- 有效的 JSON 会放进
result.output,outputError为null。 - 如果仍不符合,
output为null,outputError说明原因,即使 Jet 报告了done,运行也是failed。 - 没有
schema就不做提取:答案在markdown和detail中。
schema 要小,意思要写清楚。模型会读取 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,而不是首页。每一步都要花时间和 token。 - 只登录一次。在已经登录的 Profile 上运行,而不是每次运行都重新登录。
- 设上限。短任务调低
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 会在同一页面上用同一个任务重新开始。一次运行最多可交接三次;如果在 handoffTimeoutSec 内无人完成,运行会按当时的状态结束。详见人工交接与 Webhook。
设置 record: true 后,你还会得到运行的 MP4,可以下载或分享。见录像与事件。
计费
一次运行分两部分计费,与你的浏览器使用同一笔预付余额:
- 浏览器,与任何托管会话完全相同:按流量 GB 计费,含住宅代理。
- 智能体,按百万 token 计费:决策模型的输入 token 按
eurPerMTok计费(其输出 token 不计费),文本模型和提取模型的输入与输出 token 按eurPerMTokTextIn和eurPerMTokTextOut计费。在运行结束时一次性扣费,向上取整到百万分之一欧元。 - 验证,仅当运行使用我们密钥的验证求解服务时:按每个已解决的验证计费,计入
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 是两者之和。启动一次运行所需的最低余额与启动一个浏览器相同。