跳到正文

智能体任务:输入一个任务,输出 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)。它在一个循环中工作,每次一步:

  1. 观察。列出一个人此刻能用的控件:可见、已启用、没有被弹窗遮挡,包括 iframe 里的控件。从不读取密码字段。
  2. 决策。向一个快速决策模型发送一次请求,同时选出步骤类型和控件,并给出每个选项的概率,通常只需几百毫秒。模型只从这份列表中选择,从不编写代码或坐标。
  3. 执行。先确认页面没有变化,然后沿曲线路径移动真实鼠标、点击,并像人一样逐键输入。
  4. 作答。任务完成后,最终页面中回答任务的部分会被转换成 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。

字段类型含义
taskstring必填。用自然语言写明要做什么:1 到 4000 个字符。可以包含换行和制表符,其他控制字符不行。
urlhttp(s) URL运行开始时所在的页面。Jet 通过页面上的控件来操作,所以几乎每个任务都需要它。
schemaobject用于 result.output 的 JSON Schema(draft-07)。最大 16 KB,嵌套最多 20 层,顶层的 type 必须是 "object" 或 "array"。见结构化输出。
secretsobject运行可以输入、但模型始终看不到的值,包括 TOTP 验证码。最多 20 个。见密钥与 2FA。
maxStepsinteger1 到 100,默认 40。Jet 以 budget 停止之前最多可执行的步数(此时运行为 failed)。
handoffboolean默认 false。Jet 以 needs_input 或 blocked 停止时,暂停并把浏览器交给人处理。见人工交接。
handoffTimeoutSecinteger60 到 3600,默认 600。一次交接等待人处理的时长。
recordboolean默认 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 是这次运行的计费单价:

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 列出已被接受但看起来有问题的内容,例如任务从未用到的密钥。

状态

status含义
queued已创建,正在等待它的服务器接手。
running浏览器已启动,Jet 正在工作。服务器暂时没有上报时也处于此状态,此时 session.status 为 lost。如果服务器再也没有上报,运行会在会话最长时长之后一小时以 failed 结束(session.endReason 为 worker_silent,result 为 null);如果服务器重启了,则在它恢复后立即结束(worker_restarted)。
waiting_for_human因人工交接而暂停(handoff: true)。handoff.liveUrl 就是要发出去的链接。
succeededJet 以 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:

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.status含义
doneJet 判断任务已完成。这是模型的判断:请核对关键内容,例如在 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 中的每一项:

字段含义
step1, 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,而不是一次失败的运行:

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

如何编写任务

  • 说明怎样算完成。“打开价格页面,读出最便宜的套餐”会停在有答案的页面上;“看看他们的价格”则不会。
  • 把值写进任务。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 是它唯一的操控者。

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>

在列表中,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。
text
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 是两者之和。启动一次运行所需的最低余额与启动一个浏览器相同。

更新于 2026年11月22日 · SDK 0.70.5 · 浏览器 r63

这个页面有帮助吗?