twimco.Let’s talk ↗︎
Menu
Field notes / Product & engineering

Claude's message threads make long agent sessions faster. Build the replay path before you turn them on

Anthropic's new message threads let an agent send only the latest turn instead of the whole conversation, and Anthropic says that cuts waiting time on very long sessions. The catch is in the docs: a thread can vanish after five quiet minutes, and your code has to notice and rebuild it.

Editorial engraving of a bright engineering atrium where one engineer starts a kitchen timer, another watches a log on a laptop and a manager draws a loop on a glass wall.

Claude's message threads, in public beta since November 2, 2026, let long-running agents send only new messages plus the previous response ID, which Anthropic says cut median time to first token by about 35% on 500k to 1M-token Claude Code requests. Threads are best-effort: they expire five minutes after the last request, return a 404 thread_not_found when gone, and aren't eligible for zero data retention or HIPAA. Keep your own full copy of every conversation, and test the replay path before you rely on threads.

What message threads change

On November 2, 2026, Anthropic released message threads in public beta for the Claude Messages API. It's available on the Claude Platform, Claude Platform on AWS, Claude in Microsoft Foundry, and Claude models on Google Cloud.

The idea is simple. Normally, every request to Claude carries the whole conversation: system prompt, tools, every earlier message and every tool result. An agent that has been working for an hour might resend hundreds of thousands of tokens just to add one new line. With a thread, you send the full conversation once. After that, each request carries only the new messages and the ID of the previous response, and the API rebuilds the rest before calling the model.

Anthropic says that with threads on by default for most Claude Code users, requests between 500,000 and 1 million tokens saw median time to first token drop by about 35%. Token usage doesn't change, because Claude still reads the whole conversation each turn. Standard token rates and rate limits apply.

If you run long coding agents, computer-use agents that pile up screenshots, or document-heavy workflows, that's a real gain. But the documentation is unusually frank about how threads fail. So here's a drill: four ways a thread goes away, and what your code should do each time.

How the work moves

A threaded turn, and the replay path

  1. Create

    Full conversation, system and tools.

  2. Continue

    New messages plus previous response ID.

  3. Save every turn

    Your copy stays the source of truth.

  4. On 404 thread_not_found

    Replay into a new create request.

  5. Continue from the new ID

    The user never notices.

Illustrative decision framework based on Anthropic's documentation.

Drill one: the coffee break

Threads are best-effort. A thread expires five minutes after its last request, and the API deletes it no more than an hour after its last use. Each stored response restarts the five minutes.

So picture an agent that pauses for a human approval. The reviewer steps away for ten minutes. When the agent sends its next continue request, it gets a 404 with the error code thread_not_found.

What should happen: your code catches that specific code and replays the full conversation in a new create request, with system prompt and tools, from its own copy. Then it continues from the new response ID. The user should never notice.

The docs put it plainly: "Your application stays the source of truth for the conversation." No response tells you whether the API stored that turn. You only find out on the next continue request. So keep your own record of every message from the start. A thread is a cache you don't control. Treat the 404 as a normal Tuesday, not an outage.

One detail: a request for a model that doesn't exist also returns a 404. Check the error code before you replay, or you'll replay into the same wall.

A thread is a cache you don't control. Treat the 404 as a normal Tuesday, not an outage.

Drill two: the config change

When a thread is created, some fields become fixed: the model, tool_choice, thinking settings, MCP servers (apart from each server's authorization token), context management, output config, the skills in your container, the top-level cache_control and the set of beta headers. Every continue request must send them with the same values. A different value returns a 400 error, thread_fingerprint_mismatch, naming the fields that differ.

System prompt and tools go the other way. They're sent on the create request only. Sending either on a continue request, even as null, returns a 400.

What should happen: if your agent changes models mid-session, switches thinking on for a hard step, or adds a tool, that's a new thread. Build the conversation request in one place so the fixed fields can't drift between turns, and treat a deliberate change as "replay into a new create request."

Fallbacks follow the same rule. If you use server-side fallback to another model, decide when you create the thread, because adding or dropping fallbacks later is a fingerprint mismatch. And if a fallback model writes a response, the docs describe a separate replay path.

Drill three: the branch

A thread is append-only, and each response ID can be continued only once. There's no API to list, read back or delete a thread's contents.

Picture a coding agent that wants to retry a step from three turns ago with a different approach. Or a support agent where a human edits a message before it goes out.

What should happen: start a new thread from your own copy, edited the way you want. Always continue from the latest response ID. If two parts of your system might continue the same thread, make sure only one of them actually does.

Streaming adds one more trap. The response ID arrives in the message_start event, but you should only continue from it after message_stop. A continue request sent earlier can return a 404.

Drill four: the conversation that won't fit

Sometimes, the docs say, a continue request still returns a 404 right after you replay. The API might be unable to store that conversation, for example a very large one.

What should happen: send that request without a thread. The SDK's thread helper can do this for you when you set unsupported_request_behavior to continue_unthreaded. Otherwise it will replay on every turn and you lose the benefit.

Prompt caching also needs care. Threads don't cache for you, and a threaded request can carry at most four cache_control breakpoints. Breakpoints on the create request's system and tools count again on every continue request. One too many returns a 400, thread_unsupported_request. When you replay, strip breakpoints from earlier messages and keep one on the last block.

Decision guide

Four failures and the right response

ConsiderationWhat happensWhat your code does
Idle over five minutes404 thread_not_found.Replay full conversation from your copy
Fixed field changed400 thread_fingerprint_mismatch.Start a new thread on purpose
Need to edit or branchAppend-only, one continue per ID.New thread from your edited copy
Too large to store404 again after replay.Send without a thread
Decision framework from Anthropic's Message threads documentation, November 2026.

Before you turn it on

Check your data rules first. Message threads aren't eligible for zero data retention or HIPAA. Anthropic says threads are held in memory, encrypted and not written to disk, but if your contract or your customers require ZDR, threads aren't for that workload.

Keep the full conversation yourself. In a database if the session has to outlive the process. The SDK helper keeps a copy only in memory.

Write the replay path first, then test it. Force each failure on purpose: wait six minutes, change a fixed field, continue a response ID twice, continue mid-stream. Confirm the agent recovers without the user seeing anything.

Use the same API key and workspace for every request in a thread. On Claude Platform on AWS, sign every request with the same IAM role or user.

Measure your own latency. Anthropic's 35% figure is for very long Claude Code sessions. Short conversations will gain less.

If you're building a long-running agent and want the session handling done properly, our AI applications and agents team does this work. Get in touch and tell us how long your agent's sessions run.

Related work: Spin Market.

twimco.

We build alongside the people doing the work.
Bring us the problem you’re thinking about.

Related work

Spin:Market ↗︎