Claude Opus 5.5 18 Saatlik Görevleri Çalıştırıyor: Uzun Süre Çalışan Ajanlar İçin API'ler Nasıl Tasarlanır?

Yığınınızdaki her zaman aşımı, sonunda pes eden bir istemci varsayar. Bir tarayıcı sekmesi kapatılır. Bir CI işi duvar saatine çarpar. Bir insan çekip gider. Yük dengeleyicinizden, ağ geçidinizden ve HTTP kitaplığınızdan devraldığınız varsayılanlar, sabrı saniyelerle ölçülen bir çağıran için ayarlanmıştı.

Anthropic, Claude Opus 5.5'in görev başında 18 saat veya daha fazla kaldığını söylüyor.

Bu, tek bir çok uzun HTTP isteğine dair bir iddia değil. Tutarlılığa dair bir iddia: model, API'nizin sunduğu her şeyden çok daha uzun bir oturum boyunca tek bir hedef üzerinde çalışır. Bu oturumlardan biri uç noktalarınıza yöneldiğinde, erişim belirteçlerinizden, idempotency pencerenizden, dağıtım döngünüzden ve yeniden deneme bütçelerinizin çoğundan daha uzun yaşar. Ve bir insandan farklı olarak, durması gerektiğini fark etmez.

Bu bir API tasarımı sorunu, model sorunu değil. Neyin bozulduğu ve neyin değişmesi gerektiği burada.

Anthropic'in gerçekte yayımladıkları

Yeni modelin satıcı rakamları; aynı sayfadan tartışalım:

Aynı duyurudaki kıyaslamalar: Terminal-Bench 4.0 %66.4, OSWorld 2.0 %81.8, AutomationBench %40.0, FrontierCode v1.1 %54.4, CursorBench 4.0 %57.8, araçlarla Humanity’s Last Exam %67.7, Chartography %89.0, GDPval-AA v2.1 1846 Elo ve başarılı sınır atlatma girişimlerinde %85 daha az.

Altyapınıza düşen rakam 18 saatlik olan. Kıyaslama puanları hangi modeli seçeceğinizi değiştirir. Sürdürülen süre, API'nizin neye dayanması gerektiğini değiştirir.

Geçerliliğini yitiren altı varsayım

Her birinin sıkıcı, iyi anlaşılmış ve genellikle sorun zorlamadığı için atlanan bir çözümü var. Artık bir şey bunu zorluyor.

İşi değil, tanıtıcıları döndürün

En değerli değişiklik: birkaç saniyeyi aşabilecek her işlem, bağlantıyı tutmak yerine hemen bir iş kaynağı döndürür.

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

Ardından durum kaynağı, ajanın sırada ne yapacağına karar vermek için ihtiyaç duyduğu her şeyi taşır:

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

Asıl işi dört alan yapar. progress ve açık bir unit, modelin geçen zamandan tahmin yürütmek yerine beklemenin mantıklı olup olmadığını akıl yürütmesini sağlar. retry_after_seconds, yoklama sıklığını sunucu denetimine verir; bu, çağıranın nezaket içgüdüsü olmadığında önemlidir. expires_at, ajana tanıtıcının ne kadar geçerli olduğunu söyler, böylece onu kaybetmeden önce kontrol noktası oluşturabilir. api_version, işi oluşturulduğu sözleşmeye sabitler; öğleden sonra 3'teki dağıtımınız ile şafakta başlamış bir çalışma arasında duran tek şey budur.

Webhook'lar sunabildiğinizde daha iyi tamamlanma sinyalidir; ajanın çağrılabilir bir adresi yoksa yoklama yedektir. uzun süreli ajan çağrıları için yoklama ile webhook karşılaştırması yazımız bu dengeyi ele alıyor. 18 saatlik ufukta değişen şey, her ikisine de ihtiyacınız olmasıdır; çünkü üçüncü saatte, o zamana kadar bağlamını sıkıştırmış bir ajana teslim edilen bir webhook, artık sorduğunu hatırlamayan bir çağırana ulaşır.

Idempotency'yi görevden daha uzun ömürlü yapın

Çoğu idempotency uygulaması anahtarı bir gün veya daha kısa süre saklar ve bu her zaman yeterliydi. Uzun bir çalışmanın sonlarında başarısız bir sağlama çağrısını yeniden deneyen ajan, orijinal tekilleştirme penceresinin dışına düşer; o noktada API'niz neşeyle işi iki kez yapar.

Üç değişikliğin maliyeti çok azdır:

1. Pencereyi yayımlayın. Bitişi yanıtta döndürün ki çağıran bunun üzerine akıl yürütebilsin; bir kez belgeleyip ummak yerine.
2. Yeniden oynattığınızda söyleyin. Idempotency-Replayed: true başlığı, sessiz bir işlemsizliği ajanın üzerine hareket edebileceği bir şeye dönüştürür.
3. Uyuşmazlıkları yüksek sesle reddedin. Aynı anahtar, farklı gövde, çağıranın kendi durumunu kaybettiği anlamına gelir. Eskimiş bir sonuç sunmak yerine orijinal istek parmak iziyle 409 döndürün.

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

İşlem gerçekten tehlikeliyse, opak bir anahtar yerine istemci tarafından sağlanan doğal bir anahtarı tercih edin. İş olgusundan türetilen bir transfer_id, ajanın bellek sıkıştırmasından, on bir saat önce ürettiği rastgele bir UUID'nin dayanamayacağı şekilde ayakta kalır. ajan idempotency'sine dair temel yazımız hata modlarını içeriyor.

Kimlik bilgisinin görev ortasında süresinin dolacağını varsayın

18 saatlik bir çalışma neredeyse tüm kısa ömürlü erişim belirteçlerinden daha uzun yaşar. Bu doğru güvenlik duruşudur, ancak yalnızca API'niz ayrımı okunabilir kılıyorsa.

Belirtecin süresi dolduğunda WWW-Authenticate: Bearer error="invalid_token" meydan okumasıyla 401 döndürün ve izni olmayan bir asıl için 403 ayırın. Ajanlar bunları çok farklı ele alır: biri yenile ve devam et demektir, diğeri dur ve bildir. Bunları genel bir hataya indirgemek, asla izin verilmeyecek bir şeyi dört saat boyunca yeniden deneyen bir ajan elde etme şeklinizdir.

İşleri token örneğine değil, asıla bağlayın. O zamandan beri döndürülmüş bir token altında başlatılan bir iş, aynı kimlik tarafından okunabilir kalmalıdır; yoksa her kimlik bilgisi yenilemesi uçuştaki işi sahipsiz bırakır.

Akışı bir bağlantı değil, devam ettirilebilir bir şey olarak ele alın

Uzun akışlar düşer. Bunu varsayın ve bağlantıyı değil, yeniden bağlanmayı tasarlayın.

Sunucudan gönderilen olaylar için bu, her olaya monoton bir id vermek, yeniden bağlanmada Last-Event-ID istek başlığına uymak ve sizinle istemci arasındaki en sıkı boşta kalma zaman aşımından daha kısa aralıklarla bir keepalive yorumu yaymak anlamına gelir. Yapılandırma anahtarlarını kendi belgelerinizde adlandırın, çünkü okuyucunun gidip bunları değiştirmesi gerekir: bir AWS yük dengeleyicide idle_timeout.timeout_seconds, nginx'te proxy_read_timeout, bir Cloud Run hizmetinde timeout. Mesele belirli bir değer değil. Mesele, değerin var olması, işten kısa olması ve hizmet oluşturulduğundan beri kimsenin ona bakmamış olmasıdır. SSE akış kılavuzumuz tel formatını ele alıyor; ajana özgü kısım devam ettirmedir.

Hız sınırı başlıkları da normalden daha önemlidir. RateLimit-Limit, RateLimit-Remaining ve RateLimit-Reset, bir modelin uzun bir çalışma boyunca kendi hızını ayarlamasını sağlar ve her 429 üzerindeki bir Retry-After tahmin yürütmeyi ortadan kaldırır. Bir sayı verilen ajan ona uyar. Hiçbir şey verilmeyen ajan bir geri çekilme icat eder ve onun icadı sizinkinden daha iyi olmayacaktır.

Maliyet tarafı bir tasarım kararıdır

Fiyatlandırma satırına tekrar bakın. Girdi milyon token başına $4, önbelleğe alınmış okuma $0.20; bu, bir ajanın en sık yeniden gönderdiği yük kısmında yirmi kat fark demektir ve 1M bağlam penceresinde mutlak sayılar hızla büyür. $5'lik önbellek yazmaları, ilk geçişin düz bir okumadan biraz daha pahalı olduğu anlamına gelir; bu yüzden önbellekleme yalnızca önek gerçekten yeniden kullanıldığında kâr eder. On sekiz saat boyunca, öyledir.

İşte burada API yüzeyiniz başkasının faturasında bir maliyet girdisi haline gelir. OpenAPI belirtiminiz, araç tanımlarınız veya hata kataloğunuz bir ajanın bağlamının önünde duruyorsa, bayt kararlılığı bir özelliktir. Belirlenimci biçimde serileştirin. Anahtar sıralamasını sabit tutun. Araç tanımlarını yerinde düzenlemek yerine sürümleyin. Belirtiminizde kozmetik bir yeniden sıralama, önbelleğe alınmış bir öneği geçersiz kılar ve her şeyi tam girdi fiyatından yeniden faturalandırır; bunun parasını ödeyen müşteri bunun siz olduğunuzu asla bilmez.

Ölçek varsayımsal değil. OpenAI, medyan araştırmacısının kodlama ajanlarına günde $600'den fazla harcadığını, 90. yüzdelik dilimin günde $7,000'in üzerinde olduğunu açıkladı. Kimse bunun için optimizasyon yapmadığında sürekli ajan çalışmasının maliyeti budur ve iki günde üç model lansmanının hepsinin token başına maliyet yerine görev başına maliyetle öne çıkmasının nedeni kısmen budur. Önbelleklemenin ne zaman geri ödediğinin aritmetiği Opus 5.5 önbellekleme maliyet dökümümüzde.

Bir ajan bulmadan önce uzun yolu test edin

Bunların hiçbiri bir kez gönder'e tıklayıp bir 200 okumakla doğrulanamaz. Hatalar dokuzuncu saatte yaşar.

Apidog içinde tüm yaşam döngüsünü tek bir istek yerine bir test senaryosu olarak modelleyin: oluşturma çağrısının bir Location ve bir Retry-After ile 202 döndürdüğünü doğrulayın, durum uç noktasını terminal bir duruma kadar döngüye alın ve progress.completed değerinin asla geriye gitmediğini doğrulayın. Bu son doğrulama, herhangi bir durum kodu kontrolünden daha fazla gerçek hatayı yakalar, çünkü monoton olmayan ilerleme bir ajanı baştan başlamaya ikna eden şeydir.

Ardından bir sahte sunucuyla onu kasıtlı olarak kırın. Yirmi yoklama boyunca running kalan ve sonra başarısız olan bir iş sunun. Retry-After olmadan bir 429 sunun ve istemcinizin ne yaptığını izleyin. Bir iş uçuştayken yenileme yolunun çalıştığını doğrulamak için yolun yarısında bir 401 sunun. Apidog'un SSE testi, akış bağlantısını açık tutar ve tek tek olaylar üzerinde doğrulama yapar; Last-Event-ID devam ettirmesinin sıfırdan yeniden oynatmak yerine doğru imleci döndürdüğünü kontrol etmenin tek pratik yolu budur. Senaryoyu CI'ya bağlayın ki gelecekteki bir zaman aşımı değişikliği bir müşterinin gece boyu çalışması yerine bir testi başarısız etsin. Apidog başlamak için ücretsizdir ve bir kez oluşturduğunuz senaryo sahip olduğunuz her uzun süreli uç noktayı kapsar.

Kısa kontrol listesi

• Uzun işlemler bir iş tanıtıcısıyla 202 döndürür, asla tutulan bir bağlantı döndürmez
• Durum yanıtları ilerleme, bir birim, sunucu tarafından seçilmiş bir yoklama aralığı ve bir bitiş taşır
• İşler, oluşturuldukları API sürümüne sabitlenir
• Idempotency pencereleri yayımlanır, yeniden oynatmalar etiketlenir, değişmiş gövdeyle anahtar yeniden kullanımı 409 döndürür
• Süresi dolmuş tokenlar için 401, reddedilenler için 403'ten ayırt edilebilir
• İşler bir token örneğine değil, bir asıla aittir
• Akışlar olay kimlikleri taşır, Last-Event-ID'ye uyar ve yol üzerindeki en kısa boşta kalma zaman aşımı içinde keepalive gönderir
• Her 429 Retry-After taşır ve hız sınırı başlıkları her zaman bulunur
• Belirtim ve araç tanımları, istemci tarafı önbellekler sıcak kalsın diye bayt kararlı serileştirilir

Opus 5.5 bu gereksinimlerin hiçbirini icat etmedi. Onları atlamak için son bahaneyi ortadan kaldırdı, çünkü eskiden çatlakları bulmadan pes eden istemci artık on sekiz saat boyunca doğrudan içlerinden geçerek çalışıyor.