Claudeのmessage threads|速いが安くない

Claudeのmessage threads|速いが安くない

Claude の Messages API に、message threads という機能が加わりました。

2026 年 11 月 2 日付の公開ベータで、長い会話の 2 回目以降は新しいメッセージと前の応答の ID だけを送ればよくなります。

最初の応答までの時間は短くなりますが、トークンの消費量と単価は変わりません。

送る量が減るのに安くならない理由と、失効したときの送り直し、使えない条件が分かると、自分の用途で有効にするかどうかを決められます。

長い会話で要求が大きくなる問題

Messages API は、これまでの会話を毎回まるごと送る作りです。

1 回の要求に入るのは、過去のメッセージとツールの実行結果の全部です。

公式の記事は、コーディングエージェントが 1 つのセッションで数百回の要求を出すこともあると説明しています。

API 側でも、受け取った会話全体の検証とトークン化を毎回やり直します。

会話が数十万トークンに育つと、この送り直しの分だけ Claude が答え始めるまでの時間が延びます。

この待ち時間は TTFT(time to first token)と呼ばれ、message threads が縮めるのはここです。

参考: Make long-running agents faster with message threads(Claude 公式の記事)

message threads の仕組み

message threads の有無で要求の中身を比べた図。thread なしは毎回会話全体を送り、回を追うごとに大きくなる。thread ありは1回目だけ会話全体で、2回目以降は新しい分と前の応答のIDだけを送る。Claude が読む会話の長さはどちらも同じ。

会話をサーバー側に短い時間だけ置いておき、以後は差分だけを受け取るのが message threads です。

Messages API の要求に thread というパラメーターを 1 つ足して使い、応答は通常のメッセージと同じ形で返ります。

図のように、thread なしでは 1 回目、2 回目、3 回目と回を追うごとに送る量が増えていきます。

thread ありで会話全体を送るのは 1 回目だけで、以後は差分だけになります。

流れは次の 3 つです。

  • 作成: 最初の要求で会話全体と system・tools を送り、"thread": {"type": "create"} を足す
  • 継続: 次からは前の応答より後のメッセージだけを送り、"thread": {"type": "continue", "previous_message_id": "前の応答の id"} を足す
  • 送り直し: スレッドを続けられなくなったら、会話全体を新しい作成の要求で送る

API は作成の要求で、Claude の応答まで含めた会話を応答の id にひも付けて保存します。

モデルを呼ぶ前に、保存してある分と新しい分をつなげて会話を組み立て直す仕組みです。

system と tools は作成の要求に入れた値が保たれるので、継続の要求には入れません。

継続の要求に入れると、値が null でも 400 エラーになります。

名前は似ていますが、Claude Managed Agents の session threads とは別の機能です。

参考: Message threads(Claude Docs)

Message threads

コードで見る送り方

公式ドキュメントの Python の例から、キャッシュの指定を省いて短くしたものを載せます。

私は API キーを用意していないので、このコードは実行していません。

1 回目は、いつもの要求に thread とベータヘッダーの指定を足します。

# import と API キーの設定は省略
client = anthropic.Anthropic()

# 1 回目: 会話全体を送ってスレッドを作る
first = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    system="You are a support agent for Acme. Keep replies short.",
    messages=[{"role": "user", "content": "Hi! I have a question about an order."}],
    thread={"type": "create"},
    betas=["message-threads-2026-08-12"],
)

2 回目は、新しいメッセージと前の応答の ID だけを送ります。

# 2 回目: system と tools は送らない
second = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "How long does standard shipping usually take?"}
    ],
    thread={"type": "continue", "previous_message_id": first.id},
    betas=["message-threads-2026-08-12"],
)

ベータヘッダー message-threads-2026-08-12 は、スレッドのすべての要求に付けます。

model や thinking、トップレベルの cache_control などは、作成時と同じ値を毎回送る決まりです。

値が違うと、thread_fingerprint_mismatch の 400 エラーが返ります。

一方で max_tokens や stream は、回ごとに変えてかまいません。

自分で組まなくても、SDK には同じことをするヘルパーがあります。

# thread() の時点では要求を送らない
thread = client.beta.messages.thread(
    model="claude-opus-5-5",
    max_tokens=1024,
    system="You are a support agent for Acme. Keep replies short.",
)

thread.send({"role": "user", "content": "Hi! I have a question about an order."})
second = thread.send(
    {"role": "user", "content": "How long does standard shipping usually take?"}
)

ヘルパーはベータヘッダーを自動で付け、thread_not_found などが返ると会話全体を 1 回送り直します。

SDK のベータ版ツールランナーも、既定でスレッドを使います。

速くなるのに節約にならない理由

要求が小さくなっても、Claude が毎回読む会話の長さは同じです。

API が全体を組み立て直してからモデルを呼ぶので、モデルが読む入力は thread なしのときと変わりません。

公式の記事も、要求は小さくなるがトークンの使用量は同じだと書いています。

料金とレート制限が変わらないことも、ドキュメントに明記されています。

減るのは、通信の量と、API 側で検証とトークン化をやり直す手間です。

その差が表れるのは請求額ではなく、最初の応答までの時間です。

速さについて公式が出している数字は、500k〜1M トークンの要求で TTFT の中央値が約 35% 下がるというものです。

同じ文で、大半の Claude Code 利用者には既定で有効になっていると書かれています。

Claude Code で既定で有効という情報の根拠は、公式の記事のこの一文です。

もっと短い会話でどれだけ縮むかの数字は、公式の記事にもドキュメントにも出ていません。

公式の記事は、抱える文脈が多いほど縮む幅が大きくなるとだけ説明しています。

Claude Code の週の上限との関係についても、公式の記事とドキュメントは触れていません。

5 分で失効したら送り直す

スレッドはベストエフォートで、必ず残るものとして扱えません。

最後の要求から 5 分で失効し、最後に使ってから 1 時間以内に削除されます。

応答が保存されるたびに、5 分の計測はやり直しになります。

続けられないときは、継続の要求に 404 エラーと thread_not_found が返ります。

エラーに理由は書かれておらず、失効のほかに考えられる原因の例は次のとおりです。

  • 前の応答が max_tokens で切れたツール呼び出しで終わり、保存されなかった
  • 画像のなかった会話に最初の画像を足すなど、保存済みの会話に載せられないものを送った
  • 前の応答をフォールバックモデルが書いた
  • 前の応答がまだ生成中だった
  • 作成時と別の組織やワークスペース、別のユーザーやサービスアカウントから送った

このため、会話の控えはアプリ側に全部残しておく必要があります。

応答を見ても保存されたかどうかは分からず、次の継続の要求で初めて分かるからです。

SDK のヘルパーも控えをメモリに持つだけなので、プロセスをまたいで続けるなら自分で保存してください。

送り直すときは、控えの全文を system・tools と一緒に新しい作成の要求で送り、返ってきた応答の id から続けます。

スレッドは追記専用で、同じ応答の id から続けられるのは 1 回だけです。

途中のメッセージを直したり分岐させたりするには、新しいスレッドを作ります。

stop_reason が refusal の応答の後も、続けずに新しいスレッドを作る決まりです。

使えない条件

スレッドの中身はサーバーに置かれるので、データの扱いに決まりがある組織では先に確かめておくと手戻りを防げます。

対象外になる条件と機能は次のとおりです。

  • ZDR(ゼロデータ保持)の対象外: 中身はサーバー管理の鍵で暗号化してメモリに置き、ディスクには書かない
  • HIPAA の対象外: HIPAA readiness を有効にした組織では使えない
  • Inference hooks を有効にした組織では使えない
  • Message Batches では使えない
  • トークン数の計測の要求に thread を付けると 400 エラーになる
  • Compaction on demand は使えず、context editing も一部を除いて使えない

ZDR の対象外といっても、ZDR の対象である他の機能が使えなくなるわけではありません。

提供先は Claude API、Claude Platform on AWS、Claude Models on Google Cloud(Anthropic managed)、Claude in Microsoft Foundry の 4 つです。

プロンプトキャッシュが対応している Amazon Bedrock は、この 4 つに入っていません。

スレッドを一覧・読み取り・削除する API もありません。

system や tools、モデルを途中で変えたいときは、新しいスレッドを作ることになります。

会話を要約で短くしたいときも同じで、要約を自分のコードで作り、新しいスレッドの最初の要求に入れます。

会話を要約して続けるという考え方そのものは、コンパクションの記事で説明しました。

コンパクションとは?長い会話をAIが要約して続ける仕組み

プロンプトキャッシュとの違い

どちらも長い会話を速くする機能ですが、減らすものが違います。

プロンプトキャッシュは、入力の前半を処理した結果を使い回して、料金と処理時間を減らします。

message threads は送る量を減らすだけで、スレッドを使っても自動ではキャッシュされません。

項目message threadsプロンプトキャッシュ
主な効果要求を小さくして最初の応答を速くする処理を省いて料金と時間を減らす
料金変わらない読み出しは安く、書き込みは割増
毎回送るもの新しい分だけ会話全体
持続時間最後の要求から 5 分既定で 5 分(1 時間も選べる)
ZDR対象外対象(一部のモデルを除く)
提供状況公開ベータ正式提供

2 つは併用できます。

トップレベルの cache_control をすべての要求に同じ値で付けると、各回が前の分をキャッシュから読み、新しい分を書き込みます。

cache_control の区切りは 1 要求あたり 4 個までで、超えると thread_unsupported_request の 400 エラーになります。

料金を下げたいときに効くのはこちらなので、単価と損益分岐はプロンプトキャッシュの記事で確かめてください。

プロンプトキャッシュとは?API料金を下げる仕組みを整理

参考: Prompt caching(Claude Docs)

Prompt caching

いつ使うか

公式の記事が向いている場面に挙げるのは、待ち時間が気になる稼働中のセッションです。

  • 長時間動くコーディングエージェント: ツールの結果やファイルの編集のたびに会話が伸びる
  • コンピューター操作のエージェント: スクリーンショットを毎回アップロードし直さずに済む
  • 文書や画像の多い処理: 1 回の要求が小さくなる

ドキュメントも、最も効くのは長いエージェントのループだと書いています。

反対に、返事の間隔が 5 分を超える会話では、そのたびに失効して全体の送り直しになります。

料金を下げることが目的なら、先に試すのはプロンプトキャッシュです。

ここまでの提供状況は 2026 年 11 月 4 日に公式の文書で確かめたもので、ベータの間に変わることがあります。

参考: Claude Platform release notes(公式のリリースノート)

Claude Platform release notes

最後に

message threads は、長い会話の通信と前処理を減らして、最初の応答を速くする機能です。

トークンの消費量も単価も変わらないので、速さのために使う機能と考えると、有効にするかどうかを決めやすくなります。

失効に備えて会話の控えを手元に残すことが前提で、料金を下げる役はプロンプトキャッシュが担います。

以上です。

コメントを残す

メールアドレスが公開されることはありません。 ※ が付いている欄は必須項目です

CAPTCHA