Claude APIのMessage Threadsとは？使い方と注意点

【PR】この記事には、アフィリエイトを含む案内があります。

こんにちは。AIあれこれ散歩道、運営者のもっちゃんです。

Claude APIのMessage Threadsは、長い会話で毎回すべての履歴を送り直す代わりに、初回の会話を短時間サーバー側へ保持し、次のリクエストから新しいメッセージだけを送れるベータ機能です。通信するリクエストを小さくし、会話が長くなったときの最初の応答までの時間を安定させる目的があります。ただし、処理される会話全体が消えるわけではなく、トークン料金が自動で大幅に下がる機能と断定してはいけません。

この仕組みは、ClaudeのWeb版で会話を保存する機能や、Claude Codeのセッション引き継ぎとは別です。対象はMessages APIを使う開発者向けで、ベータヘッダーとthreadフィールドを指定します。スレッドは最終利用から5分で失効し、削除は最長1時間以内です。アプリ側が会話履歴の正本を持ち、404になったら全文を再送して作り直す設計が必要になります。

Claude APIのMessage Threadsの仕組み

通常のMessages APIで会話を続ける場合、アプリは過去のuserとassistantのメッセージを含む会話履歴を毎回送ります。会話が長くなるほど、HTTPリクエストの本文が大きくなり、サーバーは届いた内容を検証してトークン化します。Message Threadsでは初回だけ全文、system、toolsを送り、以降は前回応答のIDと新しいメッセージだけを送ります。API側が保存した短期会話を組み直してモデルへ渡します。

初回は全文を送る

最初のリクエストは、これまでのMessages APIとほぼ同じです。モデル、最大出力、system、tools、messagesを指定し、threadへcreateを加えます。ベータ機能なので、各リクエストでmessage-threads-2026-08-12のベータ指定も必要です。応答は通常のMessageとして返り、そのidが次のリクエストで使う接続点になります。初回の送信量はMessage Threadsを使わない場合と同程度です。

ここで大切なのは、APIの応答IDを会話そのものの永続的な保存場所として扱わないことです。IDは短期スレッドを続けるための参照で、アプリのデータベースを置き換えません。利用者が後日会話を開き直す機能、監査ログ、メッセージ検索、削除要求への対応などは、アプリ側の要件に合わせて実装します。短時間の通信効率と長期保存は別の責務です。

次回は新規分だけ送る

2回目以降はthreadのtypeをcontinueにし、previous_message_idへ直前の応答IDを入れます。messagesには直前の応答後に追加された新しいメッセージだけを含めます。systemとtoolsは初回から引き継がれるため、continueで送ってはいけません。nullを入れただけでも400エラーになると公式文書に記載されています。設定を共通関数へまとめるときは、createとcontinueの送信項目を明確に分けてください。

応答を受け取ったら、新しいidを次回のprevious_message_idとして保存します。常に一つ前の応答へつなぐ形です。古いIDへ戻したり、別の会話のIDを混ぜたりすると、意図した文脈になりません。複数の利用者や複数タブが同じ会話を同時に更新するアプリでは、最後に確定したIDを比較し、競合したリクエストを再構築する仕組みが必要です。

thread={"type":"create"}

thread={
  "type":"continue",
  "previous_message_id":"直前の応答ID"
}

5分失効と削除時間

スレッドは最終リクエストから5分で失効します。APIが保存した応答ごとに、この5分が再び数え直されます。会話の途中で利用者が長く考えたり、外部ツールの処理に時間がかかったりすると、次のcontinueは404になる可能性があります。失効は異常ではなく、ベストエフォートの短期機能として想定された動作です。

公式文書には、最終利用から最長1時間以内に削除されるともあります。5分と1時間は同じ意味ではありません。5分はcontinueできる期間、1時間は保存データが削除される上限です。5分を過ぎたから直ちに物理削除されたと断定せず、1時間残るからcontinueできるとも考えません。アプリの再送判断は404応答を基準にします。

SDKヘルパーの動き

公式SDKには、thread helperが用意されています。ヘルパーを作る時点ではリクエストを送らず、最初のsendでcreate、次のsendからcontinueを組み立てます。404になった場合に全文を再送するreplayもヘルパーが行います。自分でthreadフィールドを組み立てるより実装量を減らせますが、ヘルパーが保持する会話はプロセスのメモリ内だけです。

アプリを再起動した後も会話を続けたい場合は、SDKヘルパーへ任せきりにできません。過去のメッセージ、system、tools、モデル設定をアプリ側で保存し、再びcreateできる形へ戻します。複数台で動くWebサービスでは、一つのプロセスのメモリにしか会話がないと、別のサーバーへ振り分けられたときに復元できません。永続データと短期のヘルパー状態を分けましょう。

Claude APIのMessage Threadsを実装する手順

導入では、速くなりそうだから既存の会話送信を丸ごと置き換えるのではなく、再送できる履歴、5分を越える処理、並行更新、データ保持条件を先に確認します。小さな検証環境で、create、continue、失効、404からのreplayを順番に試してください。この記事ではAPIを有料で実行した実測値は示さず、公式仕様から設計上の確認点をまとめます。

会話履歴を正本にする

アプリは、利用者が送ったメッセージとClaudeの応答を順番に保存します。ツール呼び出しを使う場合は、tool_useとtool_resultの対応も失わないようにします。Message Threadsが有効な間は新規分だけ送信しても、404時には最初から全文を作り直せる必要があります。保存したデータからMessages APIのmessages配列を決定的に再構成できるかをテストしてください。

会話の正本には、表示用テキストだけでなくrole、content blockの種類、ツール名、ツール入力、結果、順序を保持します。表示画面では省略していても、再送には必要な場合があります。逆に、認証情報や不要な個人情報を会話履歴へ混ぜない設計も重要です。保存期間、暗号化、アクセス権、削除方法はアプリの方針として決めます。

createとcontinueを分ける

リクエスト生成は、create用とcontinue用の二つに分けると安全です。createではsystem、tools、全文messages、thread createを含めます。continueでは新規messages、thread continue、previous_message_idだけを含め、systemとtoolsを入れません。モデル、max_tokens、ベータ指定など共通項目は公式SDKの型に従います。空のsystemを付ける実装も400の原因になるため注意してください。

previous_message_idは、会話ごとの最新成功応答として保存します。API呼び出しがタイムアウトし、応答を受け取ったか不明な場合に同じ送信を無条件で繰り返すと、利用者の発言を二重処理するおそれがあります。アプリ側でリクエストIDと状態を記録し、再送前に結果を照合できるようにします。Message Threadsだけで重複実行が自動防止されるとは考えません。

404から全文を再送

continueが404になったら、保存している会話全文を使って新しいcreateを送ります。成功した応答のidを新しい接続点にし、以降は再び新規メッセージだけを送ります。利用者には「会話が消えた」と見せる必要はありません。裏側で再構築できれば、同じ画面のまま続けられます。ただし、再送時はリクエスト本文が大きくなり、最初の応答までの時間も増える可能性があります。

失効テストは、5分を越えて待つ方法だけでなく、保存済みIDへ意図的に無効なcontinueを送るテスト環境も用意するとよいでしょう。本番のIDを使い回さず、検証専用の会話で行います。replay後にsystemとtoolsが重複していないか、ツール結果の順序が保たれているか、最新の利用者メッセージが二重に入っていないかを確認します。

料金と速度を測る

Message Threadsが小さくするのは、主にネットワークで送るリクエストと、その内容を毎回検証・トークン化する負担です。APIはモデルを呼ぶ前に会話全体を再構成するため、過去の会話が存在しなくなるわけではありません。公式文書は、入力トークンの料金が自動で無料になるとは説明していません。通信量、最初の応答までの時間、入力トークン、キャッシュの利用を別々に計測してください。

prompt cachingを併用する場合は、トップレベルのcache_controlやキャッシュ境界を設計します。Message Threadsだけでも新規メッセージのみ送信できますが、キャッシュは別の仕組みです。通信量が減ったことを、そのまま処理トークンや請求額の減少と読み替えないでください。検証では同じモデル、同じ会話、同じ出力上限で、通常送信とスレッド送信を比較します。

データ保持を確認する

導入前に、スレッドへ何を送るかを見直します。公式ページではNot ZDR eligible、Not HIPAA eligibleと明記されています。厳しい保持要件がある環境では、Message Threadsを使わない判断が必要かもしれません。会話内容に個人情報、医療情報、顧客秘密、認証情報が入る可能性を洗い出し、契約と組織ポリシーに合うかを確認します。

短期保持だから何を送ってもよい、ということではありません。API側の保持時間と、アプリ側の長期保存、ログ、バックアップは別です。デバッグログに全文を残すと、スレッドより長くデータが保存される場合があります。ログへ必要なIDと状態だけを残し、本文を記録する場合はマスキングと保存期限を決めてください。

よくある質問

バージョン管理も忘れないでください。Message Threadsはベータ機能で、ベータヘッダーには日付が含まれています。SDKの更新でヘルパーの動作や型が変わる可能性があるため、利用するSDKバージョン、ベータ指定、確認した公式文書の日付を記録します。新しい版へ上げるときは、create、continue、404 replay、systemとtoolsの扱いを回帰テストし、以前の結果だけで互換性を保証しません。

利用者へ表示するエラーは、API内部の言葉をそのまま見せるより、会話を復旧中なのか、少し待って再試行できるのか、入力内容の見直しが必要なのかを分けます。404からのreplayが成功した場合は、利用者へ余計な操作を求めず続行できます。保存履歴が欠けて復元できない場合は、失った範囲を隠さず、新しい会話を始める選択肢を示します。技術上の失敗を成功扱いしない姿勢が信頼につながります。

実装を監視するログには、会話ID、createかcontinueか、previous_message_id、HTTP状態、所要時間、入力と出力の利用量、replayの有無を記録します。本文をそのままログへ残さなくても、どの経路で失敗したかを追える形です。404は想定内の失効、400は送信項目の誤り、429は利用制限など、状態ごとに対応を分けます。すべてを同じ再試行へ流すと、直らないリクエストを繰り返す原因になります。

continueでsystemやtoolsを送って400になった場合は、回数を増やしても成功しません。リクエスト生成をcreateとcontinueへ分離し、テストで禁止項目が混ざらないことを確認します。404は会話全文を新しいcreateへ戻せますが、直前の利用者メッセージを二重に含めないよう注意が必要です。失敗した送信がAPI側で処理されたか不明な場合は、アプリの状態と応答IDを照合してから次を決めます。

長時間動くツール呼び出しがあるエージェントでは、5分の失効が起きやすくなります。外部処理を待っている間にスレッドが切れても、ツール結果をアプリ側へ保存していればreplayできます。ツールの実行結果を会話へ戻す前に、同じ外部操作をもう一度実行しない設計も必要です。決済、メール送信、ファイル削除のような副作用を持つ操作は、API会話の再送と業務操作の再実行を分けてください。

並行更新を安全に扱う

一つの会話を複数タブで開けるサービスでは、両方が同じprevious_message_idからcontinueする場合があります。片方の応答を保存した後にもう片方が成功すると、会話の枝が分かれます。利用者へ分岐を見せる設計でなければ、会話ごとに更新番号を持ち、送信前に最新IDと一致するかを確認します。競合した側は、最新履歴を再取得して新しいcreateへ組み直す方が分かりやすいです。

サーバーを複数台で動かす場合も同様です。最新の応答IDを各プロセスのメモリだけへ置くと、次のリクエストが別のサーバーへ届いたときにcontinueできません。共有データストアへ会話の版、最新ID、未確定リクエストを保存します。SDKヘルパーを使う場合は、同じプロセスへ振り分ける間だけ便利に使い、再起動や分散環境では正本から復元できるようにします。

ストリーミング応答では、最後まで受信できなかった場合の扱いを決めます。利用者の画面へ途中まで文字が表示されても、完全な応答IDとcontentが保存できなければ次のcontinueへ使えません。接続断を成功として確定せず、API応答とアプリの保存状態を分けて記録します。必要なら未完了表示を出し、同じ利用者入力を無条件で再送しないようにします。

本番導入の判断基準

検証では、短い会話、長い会話、5分以内の連続利用、5分を越える休止、ツール利用、プロセス再起動を試します。通常の全文送信と比較し、最初の応答までの時間、失敗率、再送回数、入力トークン、運用の複雑さを記録してください。速度が少し向上しても、会話履歴を正しく保存できず復旧が難しいなら、本番では通常方式を維持する判断もあります。

データ保持要件は性能より先に確認します。ZDRやHIPAAの条件が必要なシステムでは、公式ページの対象外表示が重要です。組織の契約、利用地域、クラウド提供元によって条件が異なる可能性があるため、対象の公式契約資料と管理画面を見ます。技術的に動いたことを、法務やセキュリティ要件へ適合した証明にしないでください。

本番へ進める場合は、段階的に利用者を増やします。まず内部の低リスクな会話、次に長いエージェント処理、最後に重要な業務という順番です。404のreplay率が高い場合は、利用者の間隔やツール処理時間に対して5分が短すぎる可能性があります。その場合は、Message Threadsへ無理に合わせず、通常送信やprompt cachingを含む別の構成を比較します。

Message ThreadsはClaudeのチャット履歴機能ですか？

いいえ。Messages APIで長い会話の新規メッセージだけを送るための開発者向けベータ機能です。Web版の履歴やClaude Codeのセッションとは別です。

過去の入力トークン料金は無料になりますか？

公式文書は通信するリクエストを小さくし、最初の応答までの時間を安定させる効果を説明しています。料金が自動で無料になるとは示していないため、実際の利用量で確認します。

5分を過ぎると会話データはすぐ削除されますか？

5分はスレッドが失効する時間です。削除は最終利用から最長1時間以内とされており、同じ意味ではありません。

404になったら会話は続けられませんか？

アプリ側の履歴から全文を新しいcreateへ再送すれば続けられます。SDKヘルパーはこのreplayを支援します。

Zero Data Retention環境で使えますか？

公式ページではMessage ThreadsはZDR対象外と表示されています。保持要件がある場合は導入前に適合性を確認してください。

Claude APIのMessage Threadsまとめ

Claude APIのMessage Threadsは、長いエージェント会話で毎回全文をアップロードする負担を減らす仕組みです。初回に全文をcreateし、次回から新規メッセージと直前の応答IDをcontinueします。5分で失効するため、アプリは履歴を正本として保持し、404時に全文を再送できなければなりません。短期スレッドへ永続保存の責任を預けないことが最重要です。

まずは個人情報を含まない検証会話で、create、continue、404、replayを通してください。速さだけでなく、会話の再現性とデータ保持条件まで確認できれば、本番へ導入する判断がしやすくなります。

参照した一次情報