約 3 分で読めます

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

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

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個)。キャッシュ設計はプロンプトキャッシュの設計記事と、ミス原因の特定はCache Diagnosticsを参照してほしい。

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

スレッドは最後のリクエストから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エージェント運用の伴走支援で設計から支援できる。大規模な統制設計はRDEの対象だ。

参考

まとめ

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

関連記事

Claude Fable 5.1のappend-only会話設計プロンプトキャッシュ設計——ブレークポイントとTTL選択Claude Codeサブエージェント設計——権限を絞る書き方Managed Agentsのスケジュール実行設計