# Message threadsで長い会話の送信量を減らす設計

> Claude APIのMessage threads(beta)は2回目以降に新規メッセージとprevious_message_idだけを送る。5分で失効する前提のリプレイ設計とZDR対象外の注意点を整理する。

- Canonical: https://kuucorp.com/blog/claude-message-threads-incremental-request-replay-design/
- Date: 2026-11-03
- Last modified: 2026-11-03
- Publisher: Kuu株式会社 (https://kuucorp.com)

---
長いエージェントループでは、ターンごとに会話全体を送り直すため、リクエストが膨らみ、検証とトークナイズの負荷も毎回かかる。2026年11月2日にbetaで公開されたMessage threadsは、この「全量再送」をAPI側の保持に置き換える仕組みだ。ただし保持は最大1時間のベストエフォートで、設計の中心は失効時の復旧に置くことになる。エージェント基盤の考え方は[エージェントハーネス](/glossary/agent-harness/)の用語解説も参照してほしい。

## Message threadsとは何か

> Message threadsは、会話をサーバー側に短時間保持し、2回目以降は新規メッセージと直前のレスポンスidだけを送るMessages APIの拡張だ。

使い方は、Messages APIのリクエストに`thread`パラメータを1つ足すだけだ。最初のリクエストでは全会話・`system`・`tools`を送り、`"thread": {"type": "create"}`を付ける。API は Claude の返信を含む会話を、レスポンスの`id`に紐づけて保存する。次のターンは`"thread": {"type": "continue", "previous_message_id": "<前回のid>"}`と新しいメッセージだけを送る。betaヘッダーは`message-threads-2026-08-12`で、全リクエストに付ける。SDKには`client.beta.messages.thread()`のヘルパーがあり、送信内容の出し分けとヘッダー付与を肩代わりする。

## 何をいつ送るべきか

> フィールドは3種類に分かれる。`system`と`tools`は作成時のみ、`model`や`thinking`は毎回同値、`max_tokens`などは自由に変えられる。

- **作成時のみ**: `system`と`tools`。continueで送ると、`null`でも400エラーになる。
- **固定**: `model`、`tool_choice`、`thinking`、`context_management`、`output_config`、トップレベルの`cache_control`、betaヘッダーの集合など。値が違うと`thread_fingerprint_mismatch`で400になる。
- **自由**: `max_tokens`、`stop_sequences`、`stream`、`metadata`、`service_tier`。

スレッドは追記専用で、各レスポンスidから続けられるのは1回だけだ。過去メッセージの編集や分岐、要約への置き換えは、新しいスレッドをcreateで作り直す。プロンプトキャッシュは自動では効かない。トップレベルの`cache_control`を毎回付けるか、ブレークポイントを自分で置く必要がある（1リクエスト最大4個）。キャッシュ設計は[プロンプトキャッシュの設計記事](/blog/prompt-caching-agent-design-context-reuse/)と、ミス原因の特定は[Cache Diagnostics](/blog/claude-cache-diagnostics-api-design/)を参照してほしい。

## スレッドが失われたらどう復旧するか

> スレッドは最後のリクエストから5分で失効し、最長でも1時間以内に削除される。continueが404になる前提で、全会話のリプレイ経路を最初から作る。

continueが`thread_not_found`（404）を返す原因は複数ある。失効、`max_tokens`で切れたツール呼び出しの未保存、別ワークスペースや別ユーザーからの要求、フォールバックモデルが書いた応答などだ。APIは理由を教えず、保存されたかどうかもレスポンスでは分からない。次のcontinueで初めて判明する。

したがって会話の正本はアプリケーション側が持ち、404なら自前の履歴から`system`・`tools`付きのcreateで再開する。このとき過去メッセージに置いた`cache_control`は外す。ストリーミングは`message_stop`を受け取ってからcontinueする。`stop_reason`が`refusal`のスレッドは続けず、新規スレッドで作り直す。サーバー側フォールバックを使う場合は、`fallbacks`を全リクエストに付けるか全く付けないかのどちらかにする。フォールバックモデルが書いたターンは保存されず、そのidからは続けられない。

## 統制面ではどこに注意すべきか

> Message threadsはZDR対象外で、HIPAA対応設定とInference hooksを有効にした組織では使えない。導入前に組織設定との整合を確認する。

公式ドキュメントによると、スレッドの内容は暗号化されたメモリ上にのみ保持され、永続ストレージには書かれず、最終利用から最長1時間で削除される。それでもZDR対象外であり、他のZDR対象機能の利用には影響しない。Message Batches、トークンカウント、Compaction、コンテキスト編集（`clear_thinking_20251015`の`keep: "all"`を除く）も非対応だ。スレッドの一覧・参照・削除のAPIもない。料金とレート制限はスレッド利用で変わらない。

### 規模別の留意点（SMB / エンタープライズ）

SMBはSDKのヘルパーで始め、失効時の自動リプレイに任せるのが現実的だ。まず自社の履歴保存先を決める。エンタープライズはInference hooksやHIPAA対応を有効にした組織でスレッドが拒否されるため、`thread_unsupported_request`を検知した時点でスレッドなしの全量送信へ切り替える経路を標準化する。導入はAIエージェント運用の[伴走支援](https://kuucorp.com/services/ai-ops/)で設計から支援できる。大規模な統制設計は[RDE](https://kuucorp.com/services/rde/)の対象だ。

## 参考

- [Message threads（Claude Docs）](https://platform.claude.com/docs/en/build-with-claude/message-threads)
- [Release notes（Claude Docs）](https://platform.claude.com/docs/en/release-notes/overview)
- [Prompt caching（Claude Docs）](https://platform.claude.com/docs/en/build-with-claude/prompt-caching)
- [API and data retention（Claude Docs）](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention)

## まとめ

Message threadsは、長いループの送信量とTTFTを下げるbeta機能だ。ただし保持は最大1時間で、会話の正本は自社側に置く。固定フィールドの一致、リプレイ経路、非対応機能の検知を先に設計するのが要点になる。導入や統制設計のご相談は、Kuu株式会社までお問い合わせください。
