Message threads（メッセージスレッド）

API が会話を保持するため、以降のリクエストでは新しいメッセージだけを送ります。リクエストが小さくなり、会話が長くなっても最初のトークンまでの時間（time to first token）が短く安定します。特に長いエージェントループに向いた機能です。

Messages API のリクエストに thread というパラメーターを 1 つ追加して使います。レスポンスは通常のメッセージと同じ形で返ります。2 回目以降のリクエストでは、新しいメッセージと前回レスポンスの id を送り、会話の組み立て直しは API 側で行います。

• スレッドは追記のみ（append-only）で、各レスポンスの id から継続できるのは 1 回だけです。
• ストリーミングに対応しています。レスポンスの id は message_start イベントで届きますが、継続するのは message_stop イベントを受け取った後にします。
• スレッドはプロンプトをキャッシュしません。プロンプトキャッシュはスレッドを使わない場合と同じ動作で、キャッシュのブレークポイントの位置は利用者が決めます。
• API がスレッドを継続できなくなった場合、continue リクエストは 404 エラーを返します。このときは会話全体を新しい create リクエストで送り直し、そのレスポンスの id から続けます。

SDK の thread ヘルパーを使う場合は、Messages リクエストと同じフィールドでヘルパーを作成し、1 ターンずつ送信します。ヘルパーはスレッド用のリクエストを組み立て、会話全体をメモリに保持します。

continue リクエストが thread_not_found、thread_already_continued、thread_continue_in_flight のいずれかを返した場合、ヘルパーは会話全体を新しい create リクエストで 1 回送り直します。SDK の beta tool runner も既定でスレッドを使い、runner の作成時にオフにできます。

Message threads はベータとして提供されており、スレッドのすべてのリクエストに message-threads-2026-08-12 ベータヘッダーを付けて送ります。対象プランについては、公式のリリースノートには記載がありません。

• スレッドは最後のリクエストから 5 分で期限切れになり、最後の使用から 1 時間以内に API が削除します。
• スレッドを一覧・参照・削除する API はありません。保存された会話をあとから取り出す用途には使えないため、会話全体は利用者側で保持する前提で設計します。

ベータ機能のため、message-threads-2026-08-12 ベータヘッダーを付けて使います。

1. 最初のリクエストは、これまでどおり会話全体と system、tools を送り、"thread": {"type": "create"} を追加します。API は Claude の返答を含む会話を、レスポンスの id の下に保存します。
2. 以降のターンでは、前回のレスポンス以降のメッセージだけを送り、"thread": {"type": "continue", "previous_message_id": "<previous id>"} を追加します。system と tools はリクエストに含めません。
3. 次のターンには、毎回新しく返ったレスポンスの id を使います。