Claude APIのMessage Threads（ベータ）で長いエージェント会話を扱う

Claude Messages APIで長いエージェントループを回すと、system、ツール定義、tool結果、多数のやり取りで会話が膨らみます。message threadsがない場合、新しいリクエストは多くの場合その履歴全体を再びアップロードします。2026年11月2日に初めて文書化されたベータ機能のmessage threadsは、createのあと会話をサーバー側に保持し、以降のcontinueでは新しいメッセージだけを送れます。

これはMessages APIのthreadフィールド向けの接続ガイドです。Managed Agentsのsession threadsとは別物で、message threadはプロンプトキャッシュの代わりにもなりません。キャッシュが必要なら、自分でcache_controlを設定します。以下の例はAnthropicのドキュメントからの転記で、ここでは未実行と明記する。

createとcontinueで何が変わるか

createは通常のMessagesリクエストに近い形です。それまでの会話全体と、使う場合はsystemとtoolsを送り、次を加えます。

"thread": {"type": "create"}

APIはClaudeの返答も含め、その応答のidの下に会話を保存します。保存成功を示す専用フィールドはありません。使えるかどうかは次のcontinueで分かります。

continueは直前の応答以降に増えたメッセージだけを送り、次を加えます。

"thread": {
  "type": "continue",
  "previous_message_id": "<id of the previous response>"
}

continueではsystemとtoolsを送らないでください。スレッドがcreate時の値を保持します。nullでも再度送ると400になります。

スレッド内のすべてのリクエストにベータヘッダーmessage-threads-2026-08-12が必要です（cURLではanthropic-beta: message-threads-2026-08-12、Python SDK例ではbetas=["message-threads-2026-08-12"]）。

固定するフィールドと変えられるフィールド

Anthropicはフィールドをcreate専用・固定・自由に分けています。

APIはMCPサーバーURL、MCP認可トークン、containerのidを保存しません。使うなら、必要な各リクエストでmcp_serversとcontainerを再度送ってください。create専用や固定フィールドを変えるときは、全文会話と新しい値で新しいcreateを始めます。

スレッドは追記のみです。各応答idは一度だけcontinueできます。常に最新の応答idから続けてください。過去を編集・分岐するなら、新しいスレッドをcreateします。

履歴の正本はアプリ側

スレッドが有効なあいだ、continueは新しいメッセージだけを送り、毎回の全文履歴ではありません。新しいメッセージは通常、次のuserターンか、直前応答のtool_useに答えるtool_resultから始まります。APIが既に持っているメッセージを再送しないでください。重複したりエラーになったりします。応答がstop_reason: "pause_turn"で止まった場合は、その応答のidからmessagesを空（"messages": []）にしたcontinueで再開します。404なら、一時停止中の応答を含む全文を新しいcreateで再生します。

アプリが会話の正本です。すべてのメッセージの完全なコピーを持ち、最初から再生パスを用意してください。プロセスをまたぐなら、自分で永続化します。AnthropicのSDK thread helperは、ヘルパーオブジェクトがあるあいだメモリ上のコピーを保ち、失敗時に再生できますが、プロセス外の永続化の代わりにはなりません。

スレッド消失などでcontinueが失敗したとき（典型は404 thread_not_found）は、system／toolsを含む全文を新しいcreateで送り直し、新しい応答idからcontinueします。

期限、削除、一覧できないこと

• アイドル期限：最後のリクエストから5分。APIが正常に保存した各応答で、この5分は再開されます。
• 削除：最後の使用から最大1時間以内に削除されます。
• スレッドをlist／read／deleteするAPIはありません。

スレッドはサーバー管理鍵で暗号化されたメモリ上に置かれ、永続ストレージには書かれません。ZDR対象外です。threadsを使うこと自体が、他のZDR対象機能の利用可否を変えるわけではありません。組織向けの保持方針はAnthropicのドキュメントを確認してください。

モデル実行前に返りやすいcontinue失敗には、thread_not_found（createで再生）、thread_fingerprint_mismatch（固定フィールド不一致）、thread_already_continued（そのidは既にcontinue済み）、thread_continue_in_flight（同じidからの別continueが実行中）、thread_unsupported_request（threads非対応の機能／組織設定）があります。

プラットフォーム、料金、非対応の組み合わせ

message threadsはClaude API、Claude Platform on AWS、Claude Models on Google Cloud（Anthropic managed）、Claude in Microsoft Foundryで利用できます。ドキュメントのAvailabilityは「すべてのモデルでベータ」と書いています。サンプルのmodel idはその日のドキュメント上の例であり、恒久の固定ではありません。

threadsは料金もレート制限も変えません。Anthropicはtoken usageも同じだと述べています。HTTPリクエストが小さくなっても、各ターンでClaudeは会話全体を読みます。

非対応の例には、thread付きのMessage Batches、threadを含むtoken counting、threadsとのon-demand compaction、大半のcontext editing、HIPAA readiness有効組織、Inference hooks有効組織があります。多くは400 thread_unsupported_requestになります。

公式のcreate／continue例

次のサンプルはClaude Platformのmessage threadsドキュメントからの転記です。実行にはAPIキーが必要で、クォータを消費する。ここでは未実行と明記する。文書化された例は、そのページどおりanthropic-version: 2026-10-21とmodel id claude-opus-5-5を使います。

cURL

# Turn 1: send the full conversation and create a thread
curl -sS --fail-with-body https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2026-10-21" \
  -H "anthropic-beta: message-threads-2026-08-12" \
  -H "content-type: application/json" \
  -d '{
    "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"}
  }'

# Turn 2: send only the new message. Set message_id to the id of the turn 1 response.
# Leave out system and tools: the thread keeps them.
curl -sS --fail-with-body https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2026-10-21" \
  -H "anthropic-beta: message-threads-2026-08-12" \
  -H "content-type: application/json" \
  -d '{
    "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": "'"$message_id"'"}
  }'

Python（beta Messages create）

client = anthropic.Anthropic()

# Turn 1: send the full conversation and create a thread
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: send only the new message and the id of the turn 1 response.
# Leave out system and tools: the thread keeps them.
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"],
)

for block in second.content:
    if block.type == "text":
        print(block.text)

同じページで案内されているAnthropic Python SDKのbeta Messages経路を使います。このガイドは「現行ドキュメントに従う」以上の最低SDK版は固定しません。

TTFTに関するベンダー条件

Anthropicの製品記事は、ほとんどのClaude Codeユーザーでmessage threadsが既定オンのとき、500k〜1Mトークンのリクエストでmedian TTFTが約35%下がると述べています。同じ記事でtoken usageは変わらないとも書いています。これは当該条件でのベンダー主張として扱い、支出削減の約束でも、あらゆる負荷への保証でもない。

関連記事

Messages APIのリクエストフィールド全般を調べるなら、Claude APIのtemperatureで400になる場合（2026-10-21）は別種の400（temperature／APIバージョン）であり、threadsではありません。価格と上限の一覧はClaude API料金（2026年10月）が別スナップショットです。threadsはその料金表を書き換えません。

実務チェックリスト

1. create／continueのすべてにmessage-threads-2026-08-12を付ける。
2. createでは全文messagesとsystem／toolsを送り、応答idを保存する。
3. continueでは新しいmessagesとprevious_message_idだけ。continueでsystem／toolsを再送しない。
4. 固定フィールドをスレッド全体で揃える。
5. 全文会話を自分で保持し、404なら新しいcreateで再生する。
6. 5分のアイドル期限と1時間以内の削除を想定する。list／read／delete APIはない。
7. Message Batchesやthread付きtoken countingなど非対応機能と混ぜない。

以降追加されたフィールドは、現行のClaude Platformドキュメントを確認してください。上記のベータヘッダーとcreate／continueの形が、毎回の全文再送なしで長いエージェントループを配線する出発点です。