Messages API が会話をサーバー側に保持します

2026 年 11 月 2 日、Claude Platform のリリースノートに、Messages API の message threads が beta として加わりました。会話をサーバー側に短時間だけ保持し、2 回目以降のリクエストでは新しいメッセージだけを送れる機能です。beta ヘッダーは message-threads-2026-08-12 です。

公式のドキュメントは、長い会話やエージェントループで、リクエストの大きさを減らし、最初のトークンが出るまでの時間 (TTFT) を低く安定させる機能だと説明しています。Claude API のほか、Claude Platform on AWS、Claude Models on Google Cloud (Anthropic managed)、Microsoft Foundry で使えます。

この記事は、リリースノートと公式ドキュメントに基づき、ZDR の条件を 2026 年 11 月 13 日に再確認しています。ZDR の対象外であることなど、実装前に知っておきたい条件も先に整理します。

FIXITFIXIT

毎回会話を全部送らなくてよくなるなら、全部これに替えていいの?

DodaiDodai

まだ早いです。5 分で切れる前提の beta で、ZDR も対象外です。

何が変わるか

従来の Messages API は、毎ターン会話全体を送ります。API はそのたびに全体を検証し、トークン化します。thread を使うと、その作業の大半は、新しい 1 ターン分です。

項目thread なしthread あり
最初のリクエスト会話全体、system、tools同じ内容に thread: {"type": "create"} を足す
2 回目以降に送るもの会話全体、system、tools新しいメッセージと、直前の応答の id だけ
会話の保持場所自分の側だけ短時間だけサーバー側にも置かれる
応答通常のメッセージ通常のメッセージ (追加するパラメーターは thread のみ)

公式は、会話履歴の管理主体は引き続きアプリだとしています。すべてのメッセージを自分の側にも持っておく設計が前提です。

書き方

SDK の thread ヘルパーを使う

SDK には thread ヘルパーがあります。リクエストのフィールドを渡してヘルパーを作り、1 ターンずつ send を呼ぶ形です。beta ヘッダーの付与、create と continue の切り替え、continue で system と tools を外す処理は、ヘルパーが担います。

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 を create する
thread.send({"role": "user", "content": "Hi! I have a question about an order."})
 
# 2 ターン目: 新しいメッセージだけを送り、thread を continue する
second = thread.send(
    {"role": "user", "content": "How long does standard shipping usually take?"}
)

これは公式ドキュメントの例に沿ったものです。最上位の cache_control は省略できます。付けると、毎ターン prompt caching を依頼します。

thread フィールドを自分で送る

cURL や、SDK の通常の create を使うときは、thread フィールドを自分で付けます。すべてのリクエストに message-threads-2026-08-12 の beta ヘッダーが必要になります。

# 1 ターン目: 会話全体を送り、thread を create する
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 ターン目: 新しいメッセージと、1 ターン目の応答の id だけを送る
# system と tools は付けない。thread が create 時の値を保持している
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"],
)

公式の例では、各ターンに最上位の cache_control も付けています。ここでは、thread の部分が見えるように外しました。

continue で送る新しいメッセージは、多くの場合、次の user メッセージか、直前の tool_use に答える tool_result です。すでにある内容を送り直すと、会話に二重に入ることがあります。新しいメッセージとして直前の応答を送った場合は、エラーです。応答が stop_reason: "pause_turn" で止まったときは、その応答の id から、messages を空にした continue で再開します。

毎回送るもの、送らないもの

continue で何を送るかは、フィールドごとに決まっています。

区分フィールド決まり
create のみsystem、toolscreate だけに付ける。continue に付けると、null でも 400 エラー
固定model、tool_choice、thinking、context_management、output_config、最上位の cache_control ほか全リクエストで create と同じ値にする。違うと thread_fingerprint_mismatch の 400
自由max_tokens、stop_sequences、stream、metadata、service_tier ほかターンごとに変えてよい

system や tools を変えたいときは、同じ thread では変えられません。新しい会話全体を create で送り直します。API は、MCP サーバーの URL や認可トークン、container の id も保存しません。これらは該当するリクエストのたびに送ります。

また、continue は 1 つの応答 id から 1 回しかできません。分岐や、前のメッセージの編集もできません。常に最新の応答の id から続けます。

5 分で切れたときの扱い

thread の期限は、最後のリクエストから 5 分です。API は、最後の利用から 1 時間以内に削除します。API が応答を保存するたびに、5 分の数え直しが始まります。

期限が切れた thread に continue を送ると、404 の thread_not_found になります。404 の応答は、原因を示しません。原因は、期限切れのほか、直前の応答が保存されなかった場合、直前の応答がまだ生成中の場合、別の組織や別のユーザーが作った thread の場合などです。

対処は 1 つです。手元の会話全体を、system と tools を付けて create し直し、新しい応答の id から続けます。SDK のヘルパーは、この再送を自動で行います。

FIXITFIXIT

応答が保存されたかどうかは、すぐ分かるの?

DodaiDodai

分かりません。公式も、次の continue で初めて分かると書いています。

ストリーミングでは、応答の id が message_start で届きます。ただし、その id から continue するのは message_stop を受け取ってからです。早く送ると 404 になることがあります。

prompt caching との関係

thread は、プロンプトを自動ではキャッシュしません。prompt caching は thread がない場合と同じで、キャッシュする範囲の区切りは自分で決めます。

毎ターンをキャッシュしたいときは、最上位の cache_control を全リクエストに同じ値で付けます。API は、各リクエストの messages のうちキャッシュできる最後のブロックに、その指定を適用します。

数え方に注意が必要になります。thread を付けたリクエストが持てる cache_control のブロックは最大 4 つです。最上位の cache_control も 1 つに数えます。create に付けた system と tools のブロックは、continue のたびに数え直されます。超えた場合の応答は、400 の thread_unsupported_request です。

料金について、公式は「スレッドは料金とレート制限を変えない」とだけ書いています。キャッシュの読み書きの単価は、prompt caching のページの扱いのままです。費用全般の考え方は LLM のコスト最適化の記事 にまとめています。

使えない条件

公式が挙げる、thread が使えない条件を 1 つの表にまとめます。

対象扱い
ゼロデータ保持 (ZDR)対象外
HIPAA readiness を有効にした組織使えない
Inference hooks を有効にした組織使えない
Message Batches使えない。thread を含む項目は invalid_request_error で終わる
token countingthread を含むと 400。system と tools を付けた会話全体で数える
compaction使えない。compaction パラメーターや compaction ブロックは 400
context editingclear_thinking_20251015 の keep: "all" を除いて使えない

ZDR について、公式によると、thread の内容 (会話、system プロンプト、tools) は、サーバー側が管理する鍵で暗号化してメモリー上に置きます。永続ストレージには書かれず、最後の利用から 1 時間以内に削除されます。この機能を使っても、ほかの ZDR 対象の機能の扱いは変わりません。

compaction が使えないため、会話を要約して縮めたいときは、要約を自分のコードで作り、新しい thread の最初のメッセージとして create に送ります。compaction そのものは Claude API の compaction on demand の記事 で扱っています。

また、サーバー側のフォールバックを使う場合は、fallbacks を thread の全リクエストに付けるか、まったく付けないかのどちらかです。フォールバックのモデルが書いた応答は保存されないため、次のターンでは create を再実行します。フォールバックの課金などは Claude API の拒否とフォールバックの記事 にあります。

確認できなかったこと

  • TTFT がどれだけ下がるか、リクエストがどれだけ小さくなるかの数値は、公式のドキュメントとリリースノートに載っていません。効果は自分のアプリで測る必要があります。
  • 同時に使える thread の数や、1 つの thread の大きさの上限は、確認した範囲に記載がありません。公式は、非常に大きな会話では保存できないことがあり、そのときは thread なしで送るとしています。
  • beta のため、仕様や条件が変わる可能性があります。導入前に公式ドキュメントを開き直してください。

FIXIT の運用

当社は AI 駆動開発のクリエイティブスタジオとして、Claude の API を組み込んだ社内ツールやプロダクトをクライアントワークで扱っています。サーバー側に会話を置く機能は、速くなる見込みだけで決めず、ZDR や個人情報の扱いといった顧客側の要件と照らしてから入れるかを決めるのが基本です。

API を組み込んだツールの設計や、運用ルールの整え方は、AI 開発ツール定着支援 で扱っています。

次の一歩は、自分の組織が ZDR か HIPAA readiness の対象かを確認することです。対象でなければ、会話の長いエージェントループ 1 本だけで thread を試し、TTFT とリクエストの大きさを前後で測ってください。Claude API の利用設計を相談したい場合は、お問い合わせ から状況を教えてください。