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.createtrong SDK) nhận một tác vụ bằng lời thông thường và mộturlđể bắt đầu. Jet làm việc trong một trình duyệt hosted và trả về JSON.- Thêm một
schemavà dữ liệu bạn yêu cầu sẽ trả về trongresult.output, đã được kiểm tra theo schema đó. - Một lượt chạy thực hiện tối đa
maxStepsbướ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à
succeededkhi Jet kết thúc vớidonevà đầ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"])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:
- 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.
- 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 độ.
- 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.
- 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ường | Kiểu | Ý nghĩa |
|---|---|---|
task | string | Bắ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. |
url | http(s) URL | Trang 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. |
schema | object | Mộ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. |
secrets | object | Cá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. |
maxSteps | integer | Từ 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). |
handoff | boolean | Mặ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. |
handoffTimeoutSec | integer | Từ 60 đến 3600, mặc định 600. Thời gian một lần bàn giao chờ người đó. |
record | boolean | Mặc định false. Ghi hình lượt chạy thành MP4. Xem bản ghi hình. |
urllà 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ácfalse) 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.timeoutSecmặc định là 900 với một lượt chạy.maxGb,idleTimeoutSecvà 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,handoffhoặcrecord), lệnh tạo trả về503 NO_CAPACITYvà 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í:
{
"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. |
running | Trì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_human | Tạm dừng để bàn giao (handoff: true). handoff.liveUrl là liên kết cần gửi. |
succeeded | Jet đã kết thúc với done và outputError là null (khi có schema: đầu ra hợp lệ). |
failed | Kế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. |
cancelled | Bạn đã dừng nó: DELETE /api/v1/runs/<id>, hoặc dừng phiên của nó. |
expired | Khô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")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:
{
"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 |
|---|---|
done | Jet đá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. |
blocked | Khô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_input | Tá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. |
error | Có 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.urlvà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.outputvà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).estimatedUsdlà ướ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ặcnullnế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ácstepscuối, và sau cùngoutputthànhnullkèm mộtoutputError(nên lượt chạy làfailed).
Mỗi mục trong steps:
| Trường | Ý nghĩa |
|---|---|
step | 1, 2, 3, … |
kind | Nó đã 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 đó. |
text | Nội dung nó đã gõ, secret hiển thị dưới dạng {{name}}; null với các bước không gõ gì. |
probability | Mứ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. |
decideMs | Thời gian đưa ra quyết định, hoặc null. |
atMs | Thờ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. |
url | Trang nơi bước diễn ra. |
ledTo | Địa chỉ trang sau bước đó, hoặc null. |
pageChanged | Trang 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àoutputErrorlànull. - Nếu vẫn không khớp,
outputlànull,outputErrorcho biết lý do, và lượt chạy làfailedngay cả khi Jet đã báodone. - Không có
schemathì không có trích xuất: câu trả lời nằm trongmarkdownvà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:
{
"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
urlsâ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
maxStepscho các tác vụ ngắn để một lượt chạy đi vòng quanh sẽ dừng sớm, và đặtmaxGb.
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ó.
# 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 theoeurPerMTokTextInvà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.
agent = decision.inputTokens × eurPerMTok / 1,000,000
+ (text.inputTokens + extract.inputTokens) × eurPerMTokTextIn / 1,000,000
+ (text.outputTokens + extract.outputTokens) × eurPerMTokTextOut / 1,000,000Mứ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.