Claude APIのmessage threadsがベータ開始 — 新規メッセージだけで会話を続ける

2026年11月2日、Claude APIのMessages APIにmessage threads(メッセージスレッド)がベータで追加されました。会話の履歴をAPI側が短時間だけ保持し、2回目以降のリクエストでは新しいメッセージだけを送れる仕組みです。長い会話やエージェントループで、リクエストが小さくなり、最初のトークンが返るまでの時間(time to first token)も短くなります。

利用するにはベータヘッダー message-threads-2026-08-12 と、リクエストへの thread パラメーターの追加が必要です。

要点

提供先はClaude API、Claude Platform on AWS、Claude Models on Google Cloud(Anthropic managed)、Claude in Microsoft Foundryの4つです。ベータの段階ですが、対応はモデルを限りません。

利用フローはどう変わるか

毎ターン全履歴を送る形が、新規分だけの形になる

threadなしの場合、エージェントは1ターンごとに会話全体をアップロードし直し、APIはそのたびに全体を検証してトークン化し直します。threadありでは、この作業の大半が新しい1ターンの分だけになります。効果が出やすいのは、長いエージェントループです。

流れは3段階です。

最初の2リクエスト

SDKを使う場合はthreadヘルパーがこの流れを代行します。次は公式ドキュメントの例に沿ったPythonの形で、1ターン目にcreate、2ターン目にcontinueを送ります。ベータヘッダーもヘルパーが付けます。

import anthropic
 
client = anthropic.Anthropic()
 
# ヘルパーの作成。この時点ではリクエストを送らない
thread = client.beta.messages.thread(
    model="claude-opus-5-5",
    max_tokens=1024,
    cache_control={"type": "ephemeral"},
    system="You are a support agent for Acme. Keep replies short.",
)
 
# 1ターン目: 会話全体を送ってスレッドを作る
thread.send({"role": "user", "content": "Hi! I have a question about an order."})
 
# 2ターン目: 新しいメッセージだけを送る
second = thread.send(
    {"role": "user", "content": "How long does standard shipping usually take?"}
)

cURLなどで thread フィールドを自分で組み立てる場合は、スレッドの全リクエストに message-threads-2026-08-12 ヘッダーを付けます。

続きのリクエストで何を送るか

送る項目は3グループに分かれます。ここを間違えると400になります。

ストリーミングの応答idは message_start イベントで届きますが、continueしてよいのは message_stop を受け取った後です。それより前に送ると404になることがあります。message_stop の前にストリームが切れたら、同じcontinueをもう一度送ります。その再送が thread_already_continued か thread_continue_in_flight を返したら、createでやり直します。

SDKのヘルパーはストリームが message_stop に達した時点で応答を記録するため、途中でやめるときは、ストリームを明示的に閉じてスレッドを次のターンに空けます(Pythonは with ブロックを抜ける、Goは Close を呼ぶ、など)。

mcp_servers と container はAPI側に保存されません。使うリクエストでは毎回送ります。MCPの認可トークンだけは、リクエストごとに変えても構いません。

system や tools、固定フィールドを変えたいときは、新しいスレッドを作ります。Claude Fable 5.1・Claude Mythos 5.1・Claude Opus 5.5・Claude Sonnet 5.5・Claude Haiku 5.5では、system か tools を変えると、会話に残っている thinking / redacted_thinking ブロックが無効になります。createが400になることがあるため、その場合は思考ブロックを会話から外して送ります。

切れたとき(404)とrefusal

スレッドを続けられないとき、continueは404を返し、error.details.error_code は thread_not_found になります。期限切れ以外にも、直前の応答が保存されなかった場合(max_tokens で切れたツール呼び出しなど)、直前の応答がまだ生成中の場合、別の組織・ワークスペース・ユーザーから送った場合などが含まれ、応答は理由を区別しません。どの場合も対処は同じで、手元の会話全体を新しいcreateで送ります。存在しないモデルを指定した場合も404になるため、再送の前に error.details.error_code を確かめます。

1つの応答idからcontinueできるのは1回だけです。同じidからの2回目は thread_already_continued(400)になるので、スレッドの最新の応答idから続けます。その応答を受け取れていないなら、createでやり直します。同じidへのcontinueがまだ処理中のときは thread_continue_in_flight(400)で、多くは自分の前回の送信が残っています。

stop_reason が "pause_turn" で止まった応答は、そのidから "messages": [] のcontinueで再開します。404なら、止まった応答を含む会話全体を新しいcreateで送り直します。止まっている間に新しいユーザーメッセージを送ってはいけません。

stop_reason が "refusal" の応答の後は、そのスレッドを続けてはいけません。拒否されたターンはAPI側に残るおそれがあり、continueでは取り除けないためです。拒否されたターンを外すか言い換えたcreateで、新しいスレッドを始めます。

背景・文脈

キャッシュは自動では付かない

スレッドはプロンプトキャッシュの代わりではありません。キャッシュの置き方は従来どおり利用者が決めます。最上位の cache_control を全リクエストで同じ値で送ると、各ターンが直前までの会話をキャッシュから読み、新しいターンを書き込みます。最上位の cache_control も個別のブレークポイントも置かない場合、2回目以降の送信は新規分だけですが、キャッシュには何も書き込まれません。

守るべき制約が1つあります。thread 付きリクエストに置ける cache_control ブレークポイントは最大4つで、最上位の cache_control もその1つに数えます。createの system や tools に置いたブレークポイントは、continueのたびに数え直されます。超えると thread_unsupported_request(400)です。メッセージ上に自分でブレークポイントを置いている場合、会話を作り直すときは過去のブレークポイントを外し、最後のブロックに1つだけ残します。

キャッシュを壊す変更をどこで入れるかは、Claude APIのキャッシュが壊れる変更はcompactionの直後に入れるで扱っています。スレッドでも system と tools はcreate後に変えられないため、同じ考え方が当てはまります。

併用できない機能と条件

compactionの代わりに要約へ切り替える運用は、Claude APIのオンデマンドcompactionで好きな時点に要約させるの前提とぶつかります。スレッドを使う構成では、要約は自分のコードで作ることになります。

データの扱いも変わります。スレッドはZDRとHIPAAの対象外です。内容はメモリー上にサーバー管理の鍵で暗号化して置かれ、永続ストレージには書かれません。保持されるのは会話、createの system と tools、固定フィールドの指紋(fingerprint)です。ファイルは参照として保持されるので、スレッドを使っている間は、会話が使うファイルを利用可能にしておきます。

スレッドの一覧・読み取り・削除のAPIはありません。

フォールバックとの組み合わせ

サーバー側フォールバックは、Claude APIのスレッドで使えます。ただし、fallbacks はスレッドの全リクエストで送るか、全く送らないかのどちらかです。途中で足したり外したりすると thread_fingerprint_mismatch(400)になります。

スレッドは1つのモデルに固定されるため、フォールバック先のモデルが書いたターンは保存されません。usage.iterations に fallback_message があれば、次のターンはcreateでやり直します。フォールバックの設計そのものはOpus 5.5のreasoning_extraction拒否とfallback設計にあります。

message threadsでも会話の正本は手元に残る

Messages APIはこれまで、毎回全履歴を送る前提のAPIでした。message threadsはそこに「一時的な状態」を持ち込みます。ただし持ち込み方は控えめです。スレッドは最後の使用から遅くとも1時間で消え、保存されたかどうかはレスポンスに示されず、次のcontinueで初めて分かります。ドキュメントも、アプリが会話の正本を持ち続け、再送経路を最初から作るよう求めています。

つまり、導入コストは「スレッドを使う分岐」より「いつでもcreateに戻れる設計」にかかります。SDKのヘルパーは、404などでの再送(replay)を1回自動で行います。ただし会話の控えはヘルパーの存在中にメモリー上に持つだけで、プロセスをまたいで残す仕組みはありません。会話をプロセスより長く生かしたいなら、自前で保存することになります。

もう1つの注意は、速度とキャッシュを分けて考えることです。スレッドが減らすのは送信量と検証・トークン化の手間で、料金は変わりません。トークン単価を下げる手段は、これまでどおりキャッシュです。両方を効かせるには、最上位の cache_control を全ターンで同じ値で送るか、リクエストごとに自分でブレークポイントを置きます。

エージェントループを自作している場合は、tool useエージェントループを5段階で自作する手順のように履歴を1つのリストへ積む形から、新規メッセージだけを送る形へ移す部分が差分になります。SDKのベータ版tool runnerは、既定でスレッドを使います(runner作成時に無効にできます)。

まとめ

• 長いエージェントループを回している場合: 送信量とtime to first tokenを減らせる候補です。まずは1本の会話で、create・continue・404後のやり直しが動くかを確かめられます
• ZDR・HIPAA・Inference hooksの条件がある組織は対象外なので、従来どおり全履歴を送ります。バッチ処理・トークンカウント・オンデマンドcompactionを使う処理も、スレッドの外に置きます
• 料金を下げたい場合: スレッド自体は料金に影響しないため、cache_control の設計が別途必要です

ベータ機能なので、仕様の変更はベータヘッダーとあわせて追います。対象のヘッダーは message-threads-2026-08-12 です。