Claude Opus 5.5 chạy tác vụ 18 giờ: Cách thiết kế API cho agent chạy dài hạn

Mọi timeout trong stack của bạn đều ngầm giả định rằng client rồi sẽ từ bỏ. Một tab trình duyệt bị đóng. Một job CI chạm giới hạn thời gian. Một con người bỏ đi. Các mặc định bạn thừa hưởng từ load balancer, gateway và thư viện HTTP của mình đều được tinh chỉnh cho một caller có mức kiên nhẫn đo bằng giây.

Dùng thử Apidog ngay hôm nay

Anthropic cho biết Claude Opus 5.5 duy trì nhiệm vụ trong 18 giờ hoặc lâu hơn.

Đó không phải là tuyên bố về một yêu cầu HTTP rất dài. Đó là tuyên bố về tính mạch lạc: mô hình theo đuổi một mục tiêu duy nhất xuyên suốt một phiên dài hơn nhiều so với bất cứ thứ gì API của bạn từng phục vụ. Khi một trong những phiên đó trỏ vào endpoint của bạn, nó tồn tại lâu hơn access token, cửa sổ idempotency, chu kỳ deploy và hầu hết ngân sách thử lại của bạn. Và khác với con người, nó sẽ không tự nhận ra rằng mình nên dừng lại.

Đây là vấn đề thiết kế API, không phải vấn đề mô hình. Dưới đây là những gì sẽ hỏng, và những gì cần thay đổi.

Anthropic thực sự đã công bố những gì

Các số liệu từ nhà cung cấp cho mô hình mới, để chúng ta cùng tranh luận từ một bảng dữ liệu:

Thuộc tính	Claude Opus 5.5
ID mô hình API	claude-opus-5-5
Đầu vào / đầu ra	$4 / $20 mỗi triệu token
Đọc đầu vào đã cache	$0,20 mỗi triệu (ghi cache $5)
Cửa sổ ngữ cảnh	1M
Đầu ra tối đa	128k
Chế độ nhanh	$8 / $40 mỗi triệu
Chi phí chạy so với Opus 5	ít hơn 40%
Tốc độ đầu ra so với Opus 5	nhanh hơn 30%
Thời lượng duy trì nhiệm vụ	18+ giờ
Khả dụng	Claude Platform, AWS, GCP, Azure

Các benchmark từ cùng thông báo: Terminal-Bench 4.0 66,4%, OSWorld 2.0 81,8%, AutomationBench 40,0%, FrontierCode v1.1 54,4%, CursorBench 4.0 57,8%, Humanity's Last Exam 67,7% với công cụ, Chartography 89,0%, GDPval-AA v2.1 ở 1846 Elo, và ít hơn 85% số lần vượt ranh giới thành công.

Con số 18 giờ là con số đáp xuống hạ tầng của bạn. Điểm benchmark thay đổi mô hình bạn chọn. Thời lượng duy trì thay đổi những gì API của bạn phải chịu đựng.

Sáu giả định không còn đúng nữa

Giả định	Tại sao trước đây nó đúng	Điều một agent 18 giờ làm với nó
Một cuộc gọi hoàn thành hoặc thất bại trong một timeout	Người gọi mang tính tương tác	Công việc dài hơn bất kỳ idle timeout nào bạn có thể đặt an toàn
Thử lại là rẻ vì cửa sổ ngắn	Các bản trùng lặp đến cách nhau vài giây	Các bản trùng lặp đến cách nhau hàng giờ, sau khi cửa sổ khử trùng lặp của bạn đã đóng
Thông tin xác thực lúc bắt đầu còn hiệu lực lúc kết thúc	Các phiên ngắn hơn TTL của token	Token xoay vòng hai hoặc ba lần trong một nhiệm vụ
Một stream là một kết nối	Các stream kéo dài một phản hồi	Kết nối sẽ rớt, còn công việc thì chưa
Client nhớ những gì nó đang làm	Trạng thái nằm trong một tiến trình	Agent nén ngữ cảnh, khởi động lại, và cần bạn nhắc nó
Client có thể biết nó đang tiến triển	Một con người nhìn một vòng xoay	Không có tiến độ, agent hoặc khởi động lại công việc hoặc chờ mãi mãi

Mỗi giả định đều có một cách khắc phục nhàm chán, được hiểu rõ, và thường bị bỏ qua vì chẳng có gì buộc phải giải quyết. Giờ đây đã có thứ đang buộc phải giải quyết.

Trả về handle, không phải công việc

Thay đổi có giá trị cao nhất: bất kỳ thao tác nào có thể vượt quá vài giây đều trả về ngay một tài nguyên job thay vì giữ kết nối.

POST /v1/reports HTTP/1.1
Host: api.example.com
Idempotency-Key: 01J9Z4KCQ7M3XN2YB8V6H0
Content-Type: application/json

{"dataset": "orders_2026_q3", "format": "parquet"}

HTTP/1.1 202 Accepted
Location: /v1/jobs/job_01J9Z4KD
Retry-After: 5
Content-Type: application/json

{
  "id": "job_01J9Z4KD",
  "status": "queued",
  "created_at": "2026-09-23T04:12:09Z",
  "api_version": "2026-08-01"
}

Sau đó, tài nguyên trạng thái mang mọi thứ agent cần để quyết định làm gì tiếp theo:

{
  "id": "job_01J9Z4KD",
  "status": "running",
  "progress": { "completed": 41200, "total": 180000, "unit": "rows" },
  "started_at": "2026-09-23T04:12:11Z",
  "updated_at": "2026-09-23T05:47:02Z",
  "expires_at": "2026-09-24T04:12:09Z",
  "retry_after_seconds": 15,
  "result_url": null,
  "error": null
}

Bốn trường làm công việc thực sự. progress với unit rõ ràng cho phép mô hình lý luận liệu việc chờ đợi có hợp lý hay không, thay vì đoán từ thời gian trôi qua. retry_after_seconds đặt nhịp polling dưới sự kiểm soát của server — điều này quan trọng khi caller không có bản năng lịch sự. expires_at cho agent biết handle còn hiệu lực bao lâu, để nó có thể checkpoint trước khi mất handle. api_version ghim job vào hợp đồng mà nó được tạo ra, thứ duy nhất đứng giữa deploy lúc 3 giờ chiều của bạn và một lượt chạy bắt đầu từ lúc bình minh.

Webhook là tín hiệu hoàn thành tốt hơn khi bạn có thể cung cấp chúng, và polling là phương án dự phòng khi agent không có địa chỉ có thể gọi được. Hướng dẫn của chúng tôi về polling so với webhook cho các cuộc gọi agent chạy dài bao quát sự đánh đổi này. Điều thay đổi ở tầm nhìn 18 giờ là bạn cần cả hai, bởi vì một webhook được gửi ở giờ thứ ba đến một agent đã nén ngữ cảnh từ đó sẽ chạm đến một caller không còn nhớ mình đã yêu cầu gì.

Làm cho idempotency sống lâu hơn nhiệm vụ

Hầu hết các triển khai idempotency lưu key trong một ngày hoặc ít hơn, và như thế luôn là đủ. Một agent thử lại một cuộc gọi provisioning thất bại muộn trong một lượt chạy dài sẽ rơi ra ngoài cửa sổ khử trùng lặp ban đầu, và tại thời điểm đó API của bạn vui vẻ làm công việc hai lần.

Ba thay đổi tốn rất ít:

1. Công bố cửa sổ. Trả về thời điểm hết hạn trong phản hồi để caller có thể lý luận về nó, thay vì ghi tài liệu một lần rồi hy vọng.
2. Nói khi bạn phát lại. Một header Idempotency-Replayed: true biến một no-op im lặng thành thứ agent có thể hành động dựa trên đó.
3. Từ chối sai lệch một cách ồn ào. Cùng key, khác body nghĩa là caller đã mất dấu trạng thái của chính nó. Trả về 409 kèm dấu vân tay yêu cầu gốc thay vì phục vụ một kết quả cũ.

HTTP/1.1 200 OK
Idempotency-Replayed: true
Idempotency-Expires: 2026-09-24T04:12:09Z

Khi thao tác thực sự nguy hiểm, hãy ưu tiên natural key do client cung cấp hơn là một key mờ. Một transfer_id bắt nguồn từ sự kiện nghiệp vụ tồn tại qua quá trình nén bộ nhớ của agent theo cách mà một UUID ngẫu nhiên nó tạo ra mười một giờ trước không thể. Bài giới thiệu về idempotency cho agent của chúng tôi có các chế độ thất bại.

Giả định thông tin xác thực hết hạn giữa nhiệm vụ

Một lượt chạy 18 giờ sống lâu hơn gần như mọi access token ngắn hạn. Đó là tư thế bảo mật đúng đắn, nhưng chỉ khi API của bạn làm cho sự phân biệt trở nên dễ đọc.

Trả về 401 kèm thách thức WWW-Authenticate: Bearer [REDACTED]="invalid_token" khi token đã hết hạn, và dành 403 cho một principal thiếu quyền. Các agent xử lý hai điều này rất khác nhau: một cái nghĩa là làm mới và tiếp tục, cái kia nghĩa là dừng và báo cáo. Gộp chúng thành một lỗi chung chung là cách bạn tạo ra một agent đốt bốn giờ để thử lại thứ mà nó sẽ không bao giờ được phép làm.

Gắn job với principal, không phải với thực thể token. Một job bắt đầu dưới một token đã xoay vòng từ đó phải vẫn đọc được bởi cùng một danh tính, nếu không mỗi lần làm mới thông tin xác thực sẽ làm mồ côi công việc đang chạy.

Coi một stream là có thể tiếp tục, không phải một kết nối

Các stream dài sẽ rớt. Hãy giả định điều đó, và thiết kế cho việc kết nối lại thay vì cho kết nối.

Với server-sent events, điều đó nghĩa là cho mỗi event một id đơn điệu, tôn trọng header yêu cầu Last-Event-ID khi kết nối lại, và phát một bình luận keepalive trong khoảng thời gian ngắn hơn idle timeout chặt nhất giữa bạn và client. Hãy nêu tên các config key trong chính tài liệu của bạn, vì người đọc phải đi thay đổi chúng: idle_timeout.timeout_seconds trên load balancer AWS, proxy_read_timeout trong nginx, timeout trên dịch vụ Cloud Run. Vấn đề không phải là một giá trị cụ thể. Mà là giá trị đó tồn tại, ngắn hơn công việc, và không ai nhìn vào nó kể từ khi dịch vụ được tạo. Hướng dẫn streaming SSE của chúng tôi bao quát định dạng truyền; phần dành riêng cho agent là việc tiếp tục.

Các header giới hạn tốc độ cũng quan trọng hơn bình thường. RateLimit-Limit, RateLimit-Remaining và RateLimit-Reset cho phép mô hình tự điều chỉnh nhịp độ trong một lượt chạy dài, và một Retry-After trên mỗi 429 loại bỏ việc phỏng đoán. Một agent được cho một con số sẽ tôn trọng nó. Một agent không được cho gì sẽ tự phát minh một backoff, và phát minh của nó sẽ không tốt hơn của bạn.

Khía cạnh chi phí là một quyết định thiết kế

Hãy nhìn lại bảng giá. Đầu vào tốn $4 mỗi triệu token và một lần đọc đã cache tốn $0,20 — chênh lệch gấp hai mươi lần ở chính phần payload mà agent gửi lại thường xuyên nhất, và trên cửa sổ ngữ cảnh 1M, các con số tuyệt đối trở nên lớn rất nhanh. Ghi cache ở $5 nghĩa là lần chạy đầu tốn nhiều hơn một chút so với đọc thường, nên cache chỉ có lợi khi prefix thực sự được tái sử dụng. Trong mười tám giờ, nó được tái sử dụng.

Đây là lúc bề mặt API của bạn trở thành một đầu vào chi phí trên hóa đơn của người khác. Nếu spec OpenAPI, định nghĩa công cụ hoặc danh mục lỗi của bạn nằm ở đầu ngữ cảnh của agent, thì tính ổn định byte là một tính năng. Hãy serialize một cách xác định. Giữ thứ tự key ổn định. Đánh phiên bản định nghĩa công cụ thay vì chỉnh sửa tại chỗ. Một sự sắp xếp lại mang tính thẩm mỹ trong spec của bạn sẽ vô hiệu hóa một prefix đã cache và tính phí lại toàn bộ ở giá đầu vào đầy đủ — và khách hàng trả tiền cho điều đó sẽ không bao giờ biết đó là bạn.

Quy mô này không phải giả thuyết. OpenAI tiết lộ rằng nhà nghiên cứu trung vị của họ chi hơn $600 mỗi ngày cho các coding agent, với phân vị thứ 90 trên $7.000 mỗi ngày. Đó là chi phí của công việc agentic liên tục khi không ai tối ưu cho nó, và là một phần lý do tại sao ba mô hình ra mắt trong hai ngày đều dẫn dắt bằng chi phí mỗi nhiệm vụ thay vì chi phí mỗi token. Số học về thời điểm cache hoàn vốn nằm trong phân tích chi phí cache Opus 5.5 của chúng tôi.

Kiểm tra đường dài trước khi một agent tìm ra nó

Không điều nào trong số này có thể xác minh bằng cách nhấn gửi một lần và đọc một 200. Các thất bại sống ở giờ thứ chín.

Trong Apidog, hãy mô hình hóa toàn bộ vòng đời như một kịch bản kiểm thử thay vì một yêu cầu đơn lẻ: khẳng định rằng cuộc gọi tạo trả về 202 kèm một Location và một Retry-After, lặp endpoint trạng thái cho đến trạng thái kết thúc, và khẳng định rằng progress.completed không bao giờ lùi lại. Khẳng định cuối cùng đó bắt được nhiều lỗi thực tế hơn bất kỳ kiểm tra mã trạng thái nào, vì tiến độ không đơn điệu là thứ thuyết phục một agent bắt đầu lại.

Sau đó phá vỡ nó một cách có chủ đích bằng một mock server. Phục vụ một job giữ trạng thái running trong hai mươi lần poll rồi thất bại. Phục vụ một 429 không có Retry-After và xem client của bạn làm gì. Phục vụ một 401 ở giữa để xác nhận đường làm mới hoạt động trong khi một job đang chạy. Kiểm thử SSE của Apidog giữ một kết nối streaming mở và khẳng định trên từng event — cách thực tế duy nhất để kiểm tra rằng việc tiếp tục bằng Last-Event-ID trả về đúng con trỏ thay vì phát lại từ đầu. Nối kịch bản vào CI để một thay đổi timeout trong tương lai làm hỏng một bài kiểm thử thay vì lượt chạy qua đêm của khách hàng. Apidog miễn phí để bắt đầu, và kịch bản bạn xây một lần sẽ bao quát mọi endpoint chạy dài bạn sở hữu.

Danh sách kiểm tra ngắn

• Các thao tác dài trả về 202 với một handle job, không bao giờ giữ kết nối
• Phản hồi trạng thái mang tiến độ, một đơn vị, khoảng poll do server chọn và thời điểm hết hạn
• Job ghim phiên bản API mà chúng được tạo ra
• Cửa sổ idempotency được công bố, các lần phát lại được dán nhãn, tái sử dụng key với body đã thay đổi trả về 409
• 401 cho token hết hạn phân biệt được với 403 cho token bị từ chối
• Job thuộc về một principal, không phải một thực thể token
• Stream mang id event, tôn trọng Last-Event-ID, và gửi keepalive trong idle timeout ngắn nhất trên đường đi
• Mọi 429 mang Retry-After, và các header giới hạn tốc độ luôn hiện diện
• Spec và định nghĩa công cụ serialize ổn định byte để cache phía client luôn ấm

Opus 5.5 không phát minh ra bất kỳ yêu cầu nào trong số này. Nó loại bỏ lý do cuối cùng để bỏ qua chúng, bởi vì client từng từ bỏ trước khi tìm thấy các vết nứt giờ đây làm việc xuyên qua chúng suốt mười tám giờ.