Chuyển đến nội dung

Lượt chạy agent: đưa vào một tác vụ, nhận về JSON

Gửi một tác vụ bằng lời thông thường, một trang để bắt đầu và, nếu muốn, một JSON Schema. Một trình duyệt Clearcote hosted chạy Clearcote Jet trên đó và bạn nhận lại JSON: chuyện gì đã xảy ra, từng bước nó đã làm, và dữ liệu bạn yêu cầu, đã được kiểm tra theo schema của bạn.

Tóm tắt

  • POST /api/v1/runs (cloud.runs.create trong SDK) nhận một tác vụ bằng lời thông thường và một url để bắt đầu. Jet làm việc trong một trình duyệt hosted và trả về JSON.
  • Thêm một schema và dữ liệu bạn yêu cầu sẽ trả về trong result.output, đã được kiểm tra theo schema đó.
  • Một lượt chạy thực hiện tối đa maxSteps bước (mặc định 40, tối đa 100) và mặc định dừng sau 900 giây.
  • Một lượt chạy là succeeded khi Jet kết thúc với done và đầu ra hợp lệ. Mọi kết thúc khác đều là failed, trừ khi bạn đã hủy nó hoặc nó hết hạn trong hàng đợi.
  • Bạn trả tiền trình duyệt theo GB và agent theo triệu token, từ số dư trả trước của bạn.

Bắt đầu nhanh

Với một API key trong CLEARCOTE_API_KEY (lấy từ trang API keys) và SDK 0.34.0 trở lên:

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"])
Tab này chạy trên máy của bạn.

Thứ chạy nó: Clearcote Jet

Clearcote Jet là browser agent mã nguồn mở (MIT) của chúng tôi. Nó làm việc theo một vòng lặp, mỗi lần một bước:

  1. Quan sát. Nó liệt kê các điều khiển mà một người có thể dùng ngay lúc đó: hiển thị, đang bật, không bị pop-up che, kể cả những điều khiển nằm trong iframe. Các trường mật khẩu không bao giờ được đọc.
  2. Quyết định. Một yêu cầu duy nhất tới một model quyết định nhanh sẽ chọn cùng lúc loại bước và điều khiển, kèm xác suất cho từng lựa chọn, thường trong vài trăm mili giây. Model chỉ chọn từ danh sách đó; nó không bao giờ viết code hay tọa độ.
  3. Hành động. Nó kiểm tra rằng trang chưa thay đổi, rồi di chuyển một con chuột thật theo đường cong, nhấp chuột và gõ từng phím, như cách một người làm.
  4. Trả lời. Khi tác vụ xong, các phần của trang cuối cùng trả lời cho tác vụ được chuyển thành markdown và, khi có schema, thành JSON của bạn.

Không có code riêng cho từng site: cùng một vòng lặp nhìn lại trang sau mỗi bước. Jet không theo các liên kết mở tab mới, và không xử lý CAPTCHA, tải tệp lên, ứng dụng canvas hay shadow root đóng. Với những trường hợp đó, hãy dùng bàn giao.

Luôn là Jet mới nhất

Mỗi server tự theo dõi nhánh main của Jet. Khi có phiên bản mới, server cài nó bên cạnh phiên bản hiện tại, chạy một bài tự kiểm tra, và chỉ chuyển sang khi bài kiểm tra đạt; các lượt chạy tiếp theo sẽ dùng phiên bản mới. Một lượt chạy đang diễn ra giữ nguyên phiên bản mà nó bắt đầu, và một bản cập nhật thất bại sẽ giữ lại phiên bản trước. Mỗi kết quả cho biết phiên bản đã chạy trong result.jet (version và commit), sự kiện run.started của lượt chạy cũng vậy, nên một thay đổi về hành vi có thể truy ngược đến đúng commit.

Yêu cầu

POST /api/v1/runs nhận các trường này, cộng với mọi tùy chọn của POST /api/v1/browsers: persona, proxy và vị trí exit, identity, profile, version, adblock, solveSliders, solveCheckboxes, solvePressHold, challengeService, các giới hạn, note và worker.

TrườngKiểuÝ nghĩa
taskstringBắt buộc. Việc cần làm, viết bằng lời thông thường: từ 1 đến 4000 ký tự. Được dùng xuống dòng và tab, các ký tự điều khiển khác thì không.
urlhttp(s) URLTrang mà lượt chạy bắt đầu. Jet làm việc với các điều khiển trên trang, nên gần như tác vụ nào cũng cần một trang.
schemaobjectMột JSON Schema cho result.output (draft-07). Tối đa 16 KB, lồng tối đa 20 cấp, và type ở cấp cao nhất phải là "object" hoặc "array". Xem Đầu ra có cấu trúc.
secretsobjectCác giá trị mà lượt chạy có thể gõ vào mà model không bao giờ nhìn thấy, kể cả mã TOTP. Tối đa 20. Xem secret và 2FA.
maxStepsintegerTừ 1 đến 100, mặc định 40. Số bước tối đa Jet được thực hiện trước khi dừng với budget (khi đó lượt chạy là failed).
handoffbooleanMặc định false. Khi Jet dừng với needs_input hoặc blocked, tạm dừng và bàn giao trình duyệt cho một người. Xem bàn giao.
handoffTimeoutSecintegerTừ 60 đến 3600, mặc định 600. Thời gian một lần bàn giao chờ người đó.
recordbooleanMặc định false. Ghi hình lượt chạy thành MP4. Xem bản ghi hình.
  • url là nơi lượt chạy bắt đầu: Jet tự mở nó, thay vì trang được tải sẵn trước khi bạn kết nối.
  • keepAlive (bất kỳ giá trị nào khác false) trả về 400: một lượt chạy không có client để kết nối lại, và kết thúc khi Jet xong việc.
  • timeoutSec mặc định là 900 với một lượt chạy. maxGb, idleTimeoutSec và số dư của bạn áp dụng như với mọi phiên.
  • Một lượt chạy được gán cho một server có Jet ngay khi bạn tạo nó. Nếu không server nào còn chỗ, hoặc không server nào hỗ trợ những gì nó yêu cầu (schema, secrets, handoff hoặc record), lệnh tạo trả về 503 NO_CAPACITY và không có gì được đưa vào hàng đợi. Sau đó lượt chạy chờ server đó nhận; nếu server không nhận trong vòng năm phút, nó kết thúc là expired.
  • Một lượt chạy có tác vụ, schema và secret khiến phần thiết lập lớn hơn 60 KB sẽ trả về 400 TOO_LARGE.

Phản hồi là 201 kèm lượt chạy mới. pricing của nó chứa các mức giá mà lượt chạy này được tính phí:

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 liệt kê những gì được chấp nhận nhưng có vẻ sai, ví dụ một secret mà tác vụ không bao giờ dùng đến.

Trạng thái

statusÝ nghĩa
queuedĐã tạo, đang chờ server của nó nhận.
runningTrình duyệt đang chạy và Jet đang làm việc. Kể cả khi server của nó không báo cáo: lúc đó session.status là lost. Nếu server không bao giờ báo cáo lại, lượt chạy kết thúc là failed (session.endReason worker_silent, result null) một giờ sau thời lượng tối đa của một phiên; nếu server đã khởi động lại, thì ngay khi nó hoạt động trở lại (worker_restarted).
waiting_for_humanTạm dừng để bàn giao (handoff: true). handoff.liveUrl là liên kết cần gửi.
succeededJet đã kết thúc với done và outputError là null (khi có schema: đầu ra hợp lệ).
failedKết thúc theo bất kỳ cách nào khác: blocked, needs_input, budget hoặc error, đầu ra không khớp schema hoặc lớn hơn 1 MB, một giới hạn, trình duyệt không khởi động được, không có kết quả nào, hoặc một vấn đề server phát hiện khi nhận lượt chạy: secret không còn mở được (secrets_unreadable), số dư đã hết (insufficient_balance) hoặc tài khoản bị tạm ngưng (suspended). result và session.endReason cho biết là trường hợp nào.
cancelledBạn đã dừng nó: DELETE /api/v1/runs/<id>, hoặc dừng phiên của nó.
expiredKhông server nào nhận nó kịp thời (năm phút). Không bao giờ bị tính phí.

queued, running và waiting_for_human là những trạng thái duy nhất có thể thay đổi; các trạng thái còn lại là cuối cùng. Hãy gọi GET /api/v1/runs/<id> mỗi một hoặc hai giây, để SDK chờ thay bạn, hoặc nhận run.finished qua webhook. Một lượt chạy bị hủy hoặc hết hạn trước khi server nhận nó sẽ không gửi run.finished (hay session.ended): với những lượt đó, hãy poll.

Chờ trong SDK

runs.create mặc định sẽ chờ: nó poll mỗi 1,5 giây không giới hạn thời gian và trả về lượt chạy đã xong. timeout (tính bằng giây) giới hạn thời gian chờ; quá thời gian đó, SDK ném ra CloudTimeoutError, với last là lượt chạy như lần cuối SDK thấy, và lượt chạy vẫn tiếp tục. wait=False (Node: { wait: false }) trả về ngay phản hồi của lệnh tạo, và runs.wait(id) chờ nó sau. waiting_for_human chưa phải là kết thúc, nên việc chờ vẫn tiếp tục qua một lần bàn giao: on_update (Node: onUpdate) được gọi với lượt chạy mỗi khi trạng thái hoặc việc bàn giao của nó thay đổi, và nếu không có nó, SDK in liên kết trực tiếp của lần bàn giao ra 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")
Tab này chạy trên máy của bạn.

Kết quả

GET /api/v1/runs/<id> trả về lượt chạy. result là null cho đến khi lượt chạy xong, và vẫn là null với một lượt chạy chưa từng chạy:

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Ý nghĩa
doneJet đánh giá tác vụ đã hoàn tất. Đây là đánh giá của model: hãy kiểm tra những gì quan trọng, ví dụ bằng các trường required trong schema.
blockedKhông có gì trên trang giúp nó tiến thêm, hoặc nó đã cuộn 12 lần liên tiếp.
needs_inputTác vụ thiếu một giá trị mà một trường cần, hoặc một secret bị yêu cầu trên một site không được phép dùng nó. Hãy đưa giá trị vào tác vụ, hoặc dùng secret.
budgetĐã chạm maxSteps.
errorCó gì đó bị hỏng: trình duyệt, một lệnh gọi model hoặc runner. detail cho biết cái gì.
  • detail: lý do nó dừng, bằng lời, khi nó chưa hoàn tất. url và title: trang mà nó dừng lại.
  • markdown: các phần của trang cuối cùng trả lời cho tác vụ; với lượt chạy chưa hoàn tất, là những gì có trên màn hình.
  • output và outputError: JSON của bạn, hoặc lý do không có (xem bên dưới).
  • usage: token và số yêu cầu theo từng model: decision (model chọn bước), text (model viết các giá trị cần gõ, khi được dùng) và extract (đầu ra có cấu trúc). estimatedUsd là ước tính riêng của Jet về chi phí model, không phải số tiền bạn bị tính; số đó là costEur.
  • handoffs: số lần lượt chạy được bàn giao cho một người. elapsedMs: Jet đã làm việc bao lâu. jet: phiên bản đã chạy, hoặc null nếu không xác định được.
  • Một kết quả tối đa 1 MB. Kết quả lớn hơn sẽ bị cắt bớt thay vì bị từ chối: trước tiên là markdown, sau đó là các steps cuối, và sau cùng output thành null kèm một outputError (nên lượt chạy là failed).

Mỗi mục trong steps:

TrườngÝ nghĩa
step1, 2, 3, …
kindNó đã làm gì: click, fill, select, scroll, wait.
actionĐiều khiển nó đã dùng, theo nhãn của điều khiển đó.
textNội dung nó đã gõ, secret hiển thị dưới dạng {{name}}; null với các bước không gõ gì.
probabilityMức độ chắc chắn của model quyết định về bước này, từ 0 đến 1, hoặc null. Giá trị thấp đánh dấu một bước thiếu chắc chắn.
decideMsThời gian đưa ra quyết định, hoặc null.
atMsThời điểm bước diễn ra, tính bằng mili giây từ lúc lượt chạy bắt đầu, hoặc null.
urlTrang nơi bước diễn ra.
ledToĐịa chỉ trang sau bước đó, hoặc null.
pageChangedTrang có thay đổi sau bước đó hay không.

Đầu ra có cấu trúc

Khi có schema, một model trích xuất riêng đọc trang mà lượt chạy dừng lại (tác vụ, địa chỉ và tiêu đề của trang, cùng nội dung văn bản) và viết JSON theo schema của bạn. JSON được kiểm tra theo schema; nếu không khớp, model được thử thêm một lần với lỗi kiểm tra. Văn bản trên trang được đưa cho model dưới dạng dữ liệu không tin cậy, không bao giờ là chỉ dẫn, nên một trang không thể thuyết phục nó đưa ra câu trả lời khác.

  • JSON hợp lệ nằm trong result.output, và outputError là null.
  • Nếu vẫn không khớp, output là null, outputError cho biết lý do, và lượt chạy là failed ngay cả khi Jet đã báo done.
  • Không có schema thì không có trích xuất: câu trả lời nằm trong markdown và detail.

Giữ schema nhỏ gọn và viết đúng điều bạn muốn. Model có đọc các trường description, nên hãy dùng chúng cho định dạng (“YYYY-MM-DD”, “giá bằng euro, một con số”). Cho phép null với những giá trị mà trang có thể không có, để một giá bị thiếu là null thay vì một lượt chạy thất bại:

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

Viết một tác vụ

  • Nói rõ thế nào là xong. “Mở trang bảng giá và đọc gói rẻ nhất” kết thúc trên một trang có câu trả lời; “xem bảng giá của họ” thì không.
  • Viết các giá trị vào tác vụ. Jet gõ những từ có trong tác vụ: “tìm giày chạy bộ màu xanh size 44”, không phải “tìm giày”. Mật khẩu và mã đặt trong secret, không bao giờ trong nội dung tác vụ.
  • Bắt đầu ở nơi có việc cần làm. Đưa ra url sâu nhất mà bạn biết thay vì trang chủ. Mỗi bước đều tốn thời gian và token.
  • Đăng nhập một lần. Chạy trên một profile đã đăng nhập sẵn thay vì đăng nhập lại ở mỗi lượt chạy.
  • Đặt giới hạn. Giảm maxSteps cho các tác vụ ngắn để một lượt chạy đi vòng quanh sẽ dừng sớm, và đặt maxGb.

Bước, thời gian và giới hạn

maxSteps (mặc định 40, tối đa 100) giới hạn số bước; khi chạm mức đó, lượt chạy dừng với budget. Jet cũng tự dừng sau 12 lần cuộn liên tiếp, với blocked. Các giới hạn của phiên vẫn áp dụng thêm: timeoutSec (mặc định 900 giây với một lượt chạy), maxGb, idleTimeoutSec và số dư của bạn. Khi một trong số đó kết thúc lượt chạy, nó là failed và session.endReason nêu tên giới hạn.

Một lượt chạy là một phiên

Một lượt chạy là một phiên trình duyệt có gắn agent, dùng cùng một id. GET /api/v1/browsers/<id> hiển thị lưu lượng và mức sử dụng của nó, dashboard hiển thị nó cùng chế độ xem trực tiếp, và dòng thời gian sự kiện liệt kê từng bước ngay khi bước đó diễn ra. Bạn không thể kết nối vào một lượt chạy qua CDP (sẽ trả về 409): Jet là thứ duy nhất điều khiển nó.

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>

Trong danh sách, limit từ 1 đến 100 (mặc định 20) và before là một ngày ISO; task được cắt còn 200 ký tự, resultStatus là result.status và costEur là cùng một object như trên lượt chạy. SDK có các lệnh gọi tương tự: runs.get, runs.list, runs.cancel, và runs.wait cho một lượt chạy bạn đã tạo với wait=False.

Bàn giao và ghi hình

Với handoff: true, một lượt chạy bị kẹt (needs_input hoặc blocked) sẽ không thất bại ngay. Nó tạm dừng ở trạng thái waiting_for_human với một liên kết trực tiếp trong handoff.liveUrl; một người mở liên kết đó, đăng nhập hoặc hoàn tất bước kiểm tra, rồi nhấn “I'm done”. Sau đó Jet bắt đầu lại trên cùng trang với cùng tác vụ. Một lượt chạy có thể được bàn giao tối đa ba lần; nếu không ai hoàn tất trong handoffTimeoutSec, nó kết thúc ở trạng thái hiện có. Chi tiết tại Bàn giao & webhook.

Với record: true, bạn còn nhận được một tệp MP4 của lượt chạy, có thể tải xuống hoặc chia sẻ. Xem Bản ghi hình & sự kiện.

Tính phí

Một lượt chạy được tính phí thành hai phần, từ cùng số dư trả trước với các trình duyệt của bạn:

  • Trình duyệt, giống hệt mọi phiên hosted: theo GB lưu lượng, đã gồm proxy dân cư.
  • Agent, theo triệu token: token đầu vào của model quyết định tính theo eurPerMTok (token đầu ra của nó không tính phí), và token đầu vào, đầu ra của model văn bản và model trích xuất tính theo eurPerMTokTextIn và eurPerMTokTextOut. Khoản này được tính một lần, khi lượt chạy kết thúc, làm tròn lên đến một phần triệu euro.
  • Thử thách, chỉ khi lượt chạy dùng dịch vụ giải thử thách với key của chúng tôi: theo mỗi thử thách đã giải, tính vào 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

Mức giá được chốt khi lượt chạy được tạo và không thay đổi trong lúc nó chạy. Mức giá hiện tại nằm trong pricing của mọi phản hồi tạo. Một lượt chạy cho thấy chi phí của nó trong costEur ngay từ đầu: browser tăng dần trong lúc chạy, agent được cộng một lần ở cuối, và total là tổng của cả hai. Bắt đầu một lượt chạy cần số dư tối thiểu giống như khi khởi động một trình duyệt.

Cập nhật 22 thg 11, 2026 · SDK 0.70.5 · trình duyệt r63

Trang này có hữu ích không?