Claude Opus 5.5 meistert 18-Stunden-Aufgaben: So entwerfen Sie APIs für Langzeit-Agenten

Jeder Timeout in deinem Stack geht davon aus, dass ein Client irgendwann aufgibt. Ein Browser-Tab wird geschlossen. Ein CI-Job erreicht seine maximale Laufzeit. Ein Mensch geht. Die Standardwerte, die du von deinem Load Balancer, deinem Gateway und deiner HTTP-Bibliothek geerbt hast, waren für einen Aufrufer optimiert, dessen Geduld auf Sekunden gemessen wird.

Anthropic sagt, Claude Opus 5.5 bleibt 18 oder mehr Stunden an der Aufgabe.

Das ist keine Behauptung über eine sehr lange HTTP-Anfrage. Es ist eine Behauptung über Kohärenz: Das Modell bearbeitet über eine Sitzung hinweg ein einziges Ziel weitaus länger, als irgendetwas, das deine API jemals bedient hat. Wenn eine dieser Sitzungen auf deine Endpunkte zeigt, überlebt sie deine Zugriffstokens, dein Idempotency Window, deinen Deployment-Zyklus und fast alle deine Retry-Budgets. Und anders als ein Mensch bemerkt es nicht, dass es aufhören sollte.

Dies ist ein API-Design-Problem, kein Modellproblem. Hier ist, was zusammenbricht und was du ändern musst.

Was Anthropic tatsächlich veröffentlicht hat

Die Vendor-Zahlen für das neue Modell, damit wir von derselben Tabelle argumentieren:

Benchmarks aus der gleichen Ankündigung: 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 % mit Tools, Chartography 89,0 %, GDPval-AA v2.1 bei 1846 Elo und 85 % weniger erfolgreiche Boundary-Circumvention-Versuche.

Die Zahl von 18 Stunden ist diejenige, die auf deine Infrastruktur trifft. Benchmark-Scores ändern, welches Modell du wählst. Die anhaltende Dauer ändert, was deine API überleben muss.

Sechs Annahmen, die nicht mehr halten

Jede dieser Annahmen hat eine Lösung, die langweilig ist, gut verstanden wird und normalerweise übersprungen wird, weil nichts das Problem erzwingt hat. Jetzt erzwingt etwas das Problem.

Gib Handles zurück, keine Arbeit

Die wertvollste Änderung: Jede Operation, die länger als wenige Sekunden dauern kann, gibt sofort eine Job-Ressource zurück anstatt die Verbindung aufrechtzuerhalten.

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

Anschließend trägt die Status-Ressource alles in sich, was der Agent benötigt, um zu entscheiden, was er als Nächstes tun soll:

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

Vier Felder leisten die eigentliche Arbeit. progress mit einem expliziten unit lässt das Modell überlegen, ob Warten rational ist, anstatt nur aus elapsed time zu raten. retry_after_seconds stellt die Polling-Frequenz unter die Server-Kontrolle, was wichtig ist, wenn der Aufrufer keinen Instinkt für Höflichkeit hat. expires_at teilt dem Agenten mit, wie lange das Handle gültig ist, damit er sich vor dem Verstreichen sich speichern kann. api_version sperrt den Job an den Vertrag, nach dem er erstellt wurde, das einzige Hindernis zwischen deinem Deploy um 15 Uhr und einem Lauf, der bei Tagesanbruch begonnen hat.

Webhooks sind das bessere Abschluss-Signal, wenn du sie anbieten kannst, und Polling ist der Fallback, wenn der Agent keine aufrufbare Adresse hat. Unser Rundgang über Polling versus Webhooks für lang laufende Agenten-Aufrufe behandelt den Kompromiss. Was sich bei einem 18-stündigen Horizont ändert, ist, dass du beides brauchst, weil ein Webhook, der zur dritten Stunde an einen Agenten geliefert wird, der seinen Kontext seitdem komprimiert hat, einen Aufrufer erreicht, der sich nicht mehr erinnert, warum er fragte.

Mache Idempotency über die Aufgabe hinaus bestehen

Die meisten Idempotency-Implementierungen speichern den Schlüssel für einen Tag oder weniger, und das war immer genug. Ein Agent, der eine fehlgeschlagene Bereitstellungsanforderung spät in einem langen Lauf erneut versucht, landet außerhalb des ursprünglichen Deduplikat-Fensters, woraufhin deine API freundlich zweimal die Arbeit macht.

Drei Änderungen kosten sehr wenig:

1. Das Fenster veröffentlichen. Gib die Gültigkeit in der Antwort zurück, damit der Aufrufer daraus schließen kann, anstatt es einmal zu dokumentieren und zu hoffen.
2. Sag, wann du replayed hast. Ein Idempotency-Replayed: true Header verwandelt einen stillen No-Op in etwas, worauf der Agent reagieren kann.
3. Mismatches laut ablehnen. Gleicher Schlüssel, unterschiedlicher Körper bedeutet, dass der Aufrufer seine eigene Zustandsverfolgung verloren hat. Gib 409 mit dem ursprünglichen Request Fingerprint zurück, anstatt eine veraltete Antwort zu liefern.

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

Wo die Operation wirklich gefährlich ist, bevorzuge einen vom Kunden bereitgestellten natürlichen Schlüssel gegenüber einem undurchdringlichen. Ein transfer_id, der aus einem Geschäftsfakt abgeleitet ist, überlebt die Speicherkompression eines Agenten auf eine Weise, die eine zufällige UUID, die er vor elf Stunden generiert hat, nicht überlebt. Unser Primer zu Agenten-Idempotency-Schlüsseln beschreibt die Ausfallmodi.

Gehe davon aus, dass die Zugangsdaten mitten in der Aufgabe ablaufen

Ein 18-stündiger Lauf überlebt fast jedes kurzlebige Zugangstoken. Das ist die korrekte Sicherheitslage, aber nur, wenn deine API dies deutlich macht.

Gib bei Ablauf eines Tokens einen 401 mit einem WWW-Authenticate: Bearer error="invalid_token" Challenge zurück und reserviere 403 für einen Hauptbenutzer, dem die Berechtigung fehlt. Agenten behandeln diese sehr unterschiedlich: das eine bedeutet Neuausstellung und Fortsetzung, das andere bedeutet Stopp und Meldung. Wenn du sie zu einem generischen Fehler zusammenfasst, erhältst du einen Agenten, der vier Stunden damit verbringt, etwas erneut zu versuchen, wofür er niemals erlaubt sein wird.

Binde Jobs an den Hauptbenutzer (Principal), nicht an die Token-Instanz. Ein Job, der unter einem Token begonnen wurde, das seitdem rotiert hat, muss von derselben Identität lesbar bleiben, sonst verwaist jede Token-Erneuerung in Arbeit während der Ausführung.

Behandle einen Stream als wiederaufnehmbar, nicht als Verbindung

Lange Streams brechen ab. Gehe davon aus und gestalte die Wiederverbindung, nicht die Verbindung.

Bei Server-Sent Events bedeutet das, jedem Event eine monothonische id zuzuweisen, den Last-Event-ID Request-Header bei der Wiederverbindung zu respektieren und innerhalb eines Keepalive-Intervalls zu senden, das kürzer ist als der engste Idle Timeout zwischen dir und dem Client. Benenne die Konfigurationsschlüssel in deiner eigenen Dokumentation, denn der Leser muss sie ändern: idle_timeout.timeout_seconds in einem AWS Load Balancer, proxy_read_timeout in nginx, timeout in einem Cloud Run Service. Es geht nicht um einen spezifischen Wert. Es geht darum, dass dieser Wert existiert, kürzer ist als die Arbeit und seit der Erstellung des Dienstes niemand darauf geschaut hat. Unser SSE-Streaming-Leitfaden behandelt das Wire-Format; der Agent-spezifische Teil ist die Wiederaufnahme.

Rate Limit Header sind auch üblicher wichtiger. RateLimit-Limit, RateLimit-Remaining und RateLimit-Reset erlauben es einem Modell, sich über einen langen Lauf zu takten, und ein Retry-After bei jedem 429 beseitigt das Rätseln. Ein Agent, der eine Zahl erhält, respektiert sie. Ein Agent, dem nichts gegeben wird, erfindet ein Backoff und seine Erfindung wird nicht besser sein als deine.

Die Kosten sind eine Design-Entscheidung

Betrachte erneut die Preiszeile. Input kostet 4 $ pro Million Tokens und ein gecachter Lesevorgang kostet 0,20 $, ein zwanzigfaches für die Payload, die ein Agent am häufigsten erneut sendet, und bei einem 1M Kontextfenster werden die absoluten Zahlen schnell groß. Cache-Schreibvorgänge zu 5 $ bedeuten, dass der erste Durchlauf etwas mehr kostet als ein einfacher Read, daher zahlt Caching nur, wenn der Präfix wirklich wiederverwendet wird. Über achtzehn Stunden läuft er.

Hier wird deine API-Oberfläche zu einem Kosteninput in der Rechnung eines anderen. Wenn deine OpenAPI-Spezifikation, deine Tool-Definitionen oder dein Fehlerkatalog ganz vorne im Kontext eines Agenten stehen, ist Byte-Stabilität ein Feature. Serialisiere deterministisch. Behalte die Key-Reihenfolge stabil bei. Versionierte Tool-Definitionen, anstatt sie vor Ort zu bearbeiten. Eine kosmetische Neuanordnung deiner Spezifikation macht einen gecachten Präfix ungültig und verrechnet das Ganze zum vollen Input-Preis neu, und der Kunde, der dafür bezahlt, wird nie wissen, dass es du warst.

Die Größenordnung ist nicht hypothetisch. OpenAI gab zu, dass ihr Median-Forscher über 600 $ pro Tag für Coding-Agenten ausgibt, wobei der 90. Perzentil über 7.000 $ pro Tag liegt. Das ist das, was kontinuierliche agentische Arbeit kostet, wenn niemand für sie optimiert, und ein Teil des Grundes, warum drei Modell-Releases in zwei Tagen alle mit der Kosten pro Aufgabe und nicht mit der Kosten pro Token eingeleitet wurden. Die Arithmetik, wann Caching sich amortisiert, finden Sie in unserem Opus 5.5 Caching Cost Breakdown.

Teste den langen Pfad, bevor ein Agent ihn findet

Nichts davon ist durch einen Klick auf „send“ und das Lesen eines 200 überprüfbar. Die Fehler liegen in Stunde neun.

In Apidog modellierst du den gesamten Lebenszyklus als Testfall anstelle einer einzelnen Anfrage: Bestätige, dass der Create-Aufruf 202 mit einem Location und einem Retry-After zurückgibt, iterieren den Status-Endpunkt, bis ein Endzustand erreicht ist, und bestimme, dass progress.completed niemals rückwärts geht. Diese letzte Bestätigung fängt mehr reale Fehler ein als jede Statuscode-Prüfung, weil ein nicht-monotoner Fortschritt einen Agenten davon überzeugt, neu zu starten.

Brich es dann absichtlich mit einem Mock-Server. Serviere einen Job, der 20 Polls running bleibt und dann fehlschlägt. Serviere einen 429 ohne Retry-After und beobachte, was dein Client tut. Serviere einen 401 auf halbem Weg, um zu bestätigen, dass der Refresh-Pfad funktioniert, während ein Job in der Schwebe ist. Apidogs SSE-Tests halten eine Streaming-Verbindung offen und bestätigen individuelle Events, der einzige praktische Weg, zu überprüfen, ob die Last-Event-ID Wiederaufnahme den richtigen Cursor anstatt von null wieder aufnimmt. Baue den Szenario in die CI ein, damit eine spätere Timeout-Änderung einen Test fehlschlagen lässt, anstatt einen nächtlichen Lauf eines Kunden zu beeinflussen. Apidog ist kostenlos starten, und das Szenario, das du einmal erstellst, deckt jeden von dir eigenen langlaufenden Endpunkt ab.

Die kurze Checkliste

• Langlaufende Operationen geben 202 mit einem Job-Handle zurück, niemals eine gehaltene Verbindung
• Statusantworten führen Fortschritt, eine Einheit, ein vom Server gewählter Poll-Intervall und eine Gültigkeit
• Jobs binden an die API-Version, mit der sie erstellt wurden
• Idempotency-Fenster werden veröffentlicht, Replays sind beschriftet, Schlüsselwiederverwendung mit geändertem Körper gibt 409 zurück
• 401 für abgelaufene Tokens ist von 403 für abgelehnte zu unterscheiden
• Jobs gehören zu einem Hauptbenutzer, nicht zu einer Token-Instanz
• Streams tragen Event-IDs, respektieren Last-Event-ID und senden Keepalives innerhalb des kürzesten Idle Timeouts im Pfad
• Jeder 429 trägt Retry-After und Rate-Limit-Header sind immer vorhanden
• Spezifikationen und Tool-Definitionen serialisieren byte-stabil, damit Client-seitige Caches warm bleiben

Opus 5.5 hat keine dieser Anforderungen erfunden. Es beseitigte die letzte Entschuldigung, sie zu überspringen, weil der Client, der früher aufgegeben hat, bevor er die Risse fand, jetzt sie für achtzehn Stunden durchgeht.