0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

Claude APIのmessage threads解説——差分だけ送って長い会話を速くする、単発呼び出しには効かない

0
Posted at

3 行まとめ

  • 2026年11月2日、Claude の Messages API に message threads(ベータ)が入った。会話をサーバー側に保持し(最後のリクエストから5分で失効)、2ターン目以降は 新しいメッセージと直前の応答 id だけ を送る方式で、長い会話やエージェントループの「最初のトークンが返るまでの時間(TTFT)」を短くする
  • 料金とレート制限は変わらない。プロンプトキャッシュも自動ではかからない。スレッドはベストエフォートで5分で失効するので、会話の正本は自分で持ち、thread_not_found の 404 なら全文を送り直す(replay)前提 で組む必要がある
  • 自作の投資分析ツールの Claude 呼び出し2か所を見直したら、どちらも1往復で終わる単発呼び出しだった。スレッドで省けるものがないので、今は入れないと判断した

何が発表されたか

Claude Platform のリリースノート、11月2日の項目にこうある。

Long conversations and agent loops on the Messages API can now send smaller requests and get a lower time to first token with message threads, in beta with the message-threads-2026-08-12 beta header.

これまでの Messages API はステートレスで、毎ターン会話の全履歴を送り直していた。50ターン続くエージェントループなら、50回目のリクエストには1〜49ターン目がまるごと入っている。API 側も、毎回その全体を検証し、トークン化し直していた。message threads は、この再送と再処理を省くための仕組みだ。

ドキュメントの冒頭にもこう書かれている。

Without a thread, every turn uploads the whole conversation again, and the API validates and tokenizes all of it again. With a thread, most of that work covers only the new turn.

Claude API のほか、Claude Platform on AWS、Claude Models on Google Cloud(Anthropic managed)、Microsoft Foundry でもベータで使える。対応モデルは Fable / Mythos 系から Opus 5.5・Sonnet 5.5・Haiku 5.5、さらに 4.5 世代まで含む。ドキュメントには「in beta on every model」とある。

仕組み:create → continue → replay

リクエストに thread パラメータを1つ足すだけで、レスポンスは普段どおりのメッセージが返る。

  1. create: 最初のリクエストは、いつもどおり会話の全体と system・tools を送り、"thread": {"type": "create"} を付ける。API は Claude の返答を含めた会話を、レスポンスの id をキーにして保存する
  2. continue: 次からは、前回の応答以降に増えたメッセージだけを送り、"thread": {"type": "continue", "previous_message_id": "<前回のid>"} を付ける。system と tools は送らない(スレッドが create 時の値を覚えている)
  3. replay: スレッドは最後のリクエストから5分で失効し(API が応答を保存するたびに5分がリセットされる)、最後に使ってから1時間以内に削除される。続けられなくなった continue は 404(thread_not_found)を返すので、手元の会話全体を新しい create として送り直し、その応答の id から続ける

Python で手書きするとこうなる(ドキュメントの例から)。

client = anthropic.Anthropic()

# Turn 1: 全体を送ってスレッドを作る
first = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    cache_control={"type": "ephemeral"},
    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"],
)

# Turn 2: 新しいメッセージと turn 1 の id だけを送る
# system と tools は送らない(スレッドが保持している)
second = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    cache_control={"type": "ephemeral"},
    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"],
)

ドキュメントで強調されているのは、会話の正本はアプリ側が持つ という点だ。

Your application stays the source of truth for the conversation. Keep your own copy of every message, and build the replay path from the start.

create にも continue にも「このターンを保存したかどうか」は返ってこない。保存されていなかったことは、次の continue が 404 になって初めて分かる。だから「スレッドがあるから履歴を捨てていい」にはならない。むしろ、手元の履歴と replay の経路が必須になる。

SDK のヘルパーを使う場合

SDK には、create / continue / replay を肩代わりする thread ヘルパーがある。

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ターン目は continue で、新しいメッセージだけを送る
second = thread.send(
    {"role": "user", "content": "How long does standard shipping usually take?"}
)

使い捨ての venv に最新の Python SDK(2.6.0)を入れて確認すると、client.beta.messages.thread は実在した。名前付きの引数は max_tokens, model, messages, tools, output_format, unsupported_request_behavior などで、例にある system や cache_control は **params 経由で受け取る形だった。ヘルパーは次のことを自動でやってくれる。

  • ベータヘッダーの付与
  • 2ターン目以降、system と tools を外した continue を送る
  • thread_not_found・thread_already_continued・thread_continue_in_flight のときに一度だけ replay する(thread_fingerprint_mismatch と thread_unsupported_request はアプリ側に上がってくる)
  • refusal(拒否応答)のターンは捨て、次のターンで新しいスレッドを始める

ただしヘルパーが会話を持つのはメモリ上だけだ。プロセスをまたいで会話を続けたいなら、結局は自分で保存する必要がある。

送るフィールドの3分類

いちばん間違えやすいのがここだ。thread を使うリクエストのフィールドは3種類に分かれる。

分類 フィールド ルール
create 専用 system, tools create のときだけ送る。continue で送ると、null でも 400
固定 model, tool_choice, thinking, mcp_servers, context_management, output_config, container の skills, トップレベルの cache_control, anthropic-beta の組み合わせ 毎回、create と同じ値で送る。違うと 400 thread_fingerprint_mismatch
自由 max_tokens, stop_sequences, stream, metadata, service_tier など ターンごとに変えてよい

mcp_servers は、各サーバーの認可トークンだけはリクエストごとに変えてよい。server-side fallback の fallbacks も、スレッドの全リクエストに付けるか一度も付けないかのどちらかで、途中の付け外しは thread_fingerprint_mismatch になる。

「system は送ってはいけない」のに、「model や thinking は毎回同じ値で送らなければいけない」。この非対称さが罠になりやすい。途中でモデルを切り替えたい、ツールを足したい、という場合は、新しいスレッドを create し直すしかない。

ほかにも細かい制約がある。

  • スレッドは追記専用で、各応答の id から continue できるのは1回だけ。過去のメッセージを編集したり分岐させたりするなら、create し直す
  • continue で送ったメッセージは、既存の会話と照合されない。再送したメッセージは重複するか、エラーになる(直前の応答から始まる continue はエラー)
  • stop_reason: "pause_turn" で止まったターンは、空の messages([])で continue して再開する

プロンプトキャッシュは自動ではない

スレッドを使っても、キャッシュは勝手にはかからない。

A thread does not cache your prompt for you.

ターンごとにキャッシュしたいなら、トップレベルの cache_control を毎回送る。そうすると、各リクエストの messages の中でキャッシュできる最後のブロックに、ブレークポイントが自動で置かれる。トップレベルの cache_control は「固定」フィールドなので、途中で付けたり外したりはできない。

手動でブレークポイントを置く場合は、上限に注意する。

  • thread 付きのリクエストに置けるブレークポイントは最大4つ。トップレベルの cache_control も1つと数える
  • create 時に system と tools に置いたブレークポイントは、continue のたびに数え直される
  • 4つを超えると 400 thread_unsupported_request(unsupported: ["cache_control"])になる

ここで勘違いしやすいのが、スレッドとキャッシュの役割の違いだ。ドキュメントの説明から読む限り、スレッドで短くなるのは リクエストの転送と、API 側の検証・トークン化の時間 だ。モデルが入力を処理するコストは、引き続きキャッシュで下げるものと読める。料金とレート制限は変わらないので、スレッドを使ったからといって請求額が下がるわけではない。

エラーと replay

thread 固有のエラーは、どれもモデルが動く前に返り、トークンは消費されない。

ステータス error_code 意味 対処
404 thread_not_found スレッドを続けられない 全体を create で送り直す
400 thread_fingerprint_mismatch 固定フィールドの値が違う 値を揃えるか、create し直す
400 thread_already_continued その id はもう continue 済み 最新の id から続ける。応答を受け取れていないなら replay
400 thread_continue_in_flight 同じ id からの continue が実行中 終わるのを待つか、replay
400 thread_unsupported_request スレッド非対応の機能・設定を使っている その機能を外すか、thread なしで送る

thread_not_found の原因はいろいろある。失効のほか、max_tokens で途中で切れたツール呼び出しで終わった応答(API が保存しない)、フォールバックモデルが書いた応答、スレッドを作ったのとは別の organization・workspace・ユーザーからのリクエストなどだ。レスポンスからは原因が分からない。なので、thread_not_found なら原因を問わず replay する作りにしておくのが正解になる。

ただし、存在しないモデルを指定した場合も 404 が返る。replay の前に error.details.error_code を確認したい。replay した直後の continue がまた thread_not_found になる場合は、非常に大きい会話など、API が保存できない会話の可能性がある。そのときは thread なしで送る(SDK なら unsupported_request_behavior="continue_unthreaded")。

ストリーミングでは、message_start で id が届いても、message_stop を受け取るまでは continue してはいけない。早すぎると 404 になる。

使えない機能と、データの扱い

次の機能とは併用できない。

  • Message Batches
  • Token counting(thread 付きのカウントは 400。全体を数える)
  • Compaction(要約で置き換えたいなら、要約を書いて新しいスレッドを create する)
  • Context editing(clear_thinking_20251015 の keep: "all" を除く)
  • HIPAA 対応や Inference hooks を有効にしている組織

データの扱いとして、message threads は ZDR(ゼロデータ保持)の対象外 だ。会話は暗号化した状態でメモリ上にだけ保持され、永続ストレージには書かれず、最後に使ってから1時間以内に削除される。ZDR 契約を前提にしたワークロードには使えない。

自作ツールに入れるか:入れない

自作の投資分析ツール(RakuScan)は、Anthropic API を2か所で呼んでいる。どちらも見直した。

1か所目は、日次スクリーニング結果の統合分析だ。

# src/notify/claude_analyzer.py(抜粋)
response = client.messages.create(
    model=cfg.claude_model_daily(),
    max_tokens=8192,
    system=[
        {
            "type": "text",
            "text": skill_content,
            "cache_control": {"type": "ephemeral"},
        }
    ],
    messages=[{"role": "user", "content": slim_json}],
)

2か所目は、Discord bot のコマンド応答だ。

# src/discord_bot/bot.py(抜粋)
response = client.messages.create(
    model=cfg.claude_model_tier2(),
    max_tokens=4096,
    messages=[{"role": "user", "content": content}],
)

どちらも messages には user メッセージが1つだけで、1往復で終わる。2ターン目が存在しない。スレッドが省くのは「2ターン目以降の再送」なので、単発呼び出しには省けるものがない。1ターン目は create として普通に全体を送るので、速くも安くもならない。

統合分析のほうは、SKILL.md を system に入れてキャッシュしている。毎日同じ system を送るこの形には、スレッドよりもプロンプトキャッシュのほうが合っている。そもそもスレッドは5分で失効するので、1日1回のバッチをまたいで会話を保持することもできない。

Discord bot は、将来「さっきの銘柄について、もう少し詳しく」のような追い質問に対応させるなら、スレッドが候補になる。人間同士の会話の間隔なら5分の失効にも収まりやすい。ただ、その場合でも履歴は bot 側で持つ必要がある。それに RakuScan の Python SDK はまだ 0.97.0 で、thread ヘルパーを使うには、2026-10-21 の破壊的変更の記事で検証した 2.x 系への移行が先になる。

まとめ

  • message threads は、2ターン目以降に 新しいメッセージと直前の id だけ を送る仕組み。長い会話やエージェントループで TTFT を短くする。料金・レート制限は変わらず、キャッシュも自動ではかからない
  • system / tools は create 時だけ送り、model や thinking などは毎回同じ値で送る。この3分類を間違えると 400 になる
  • スレッドは5分で失効するベストエフォートの仕組みなので、会話の正本は自分で持ち、thread_not_found なら全文を送り直す replay を最初から組み込んでおく
  • 効くのは、何十ターンも続くエージェントループやチャットだ。1往復で終わる単発呼び出しやバッチには、スレッドではなくプロンプトキャッシュを使う。自作ツールは後者だったので、入れないことにした

この記事は Zenn にも同じ内容を投稿しています。

0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?