Mid-conversation system messages

キャッシュ済みの接頭部分は変わらないため、次のリクエストでもキャッシュから読み取られ、追加した指示は通常のユーザーの文章ではなく system の指示として扱われます。長時間のセッションの途中で、アプリケーション側から指示を変える場面に関わる機能です。

user メッセージはエンドユーザーからのもの、system メッセージはアプリケーションの運用者からのものとして扱われ、両者が食い違うときは system の指示が優先されます。会話途中の system メッセージは、この運用者レベルの優先度を保ちながら、トップレベルの system フィールドを編集した場合のキャッシュミスのコストを避けられます。

指示の優先順位は次のとおりです。

• 指示が食い違う場合、後の system メッセージが前の system メッセージより優先されます。
• 会話途中の system メッセージは、その後のターンについてトップレベルの system フィールドより優先されます。

Managed Agents では、system.message イベントを送ると、そのターンと以降のすべてのターンに適用されます。エージェント自身の system フィールドはセッション中に変更できません。

• 内容 (text、tool_addition、tool_removal のブロック) を持つ system メッセージは、user ターン (tool_result ブロックを含むものを含む) か、サーバーツールの結果で終わる assistant ターンの直後に置き、assistant ターンの前に置くか配列の末尾にします。tool_use ブロックとその tool_result の間には置けません。それ以外の位置では 400 エラーが返ります。
• 内容を持つ system メッセージは messages の最初の要素にできません。最初から適用する指示はトップレベルの system フィールドを使います。
• 連続する system メッセージは受け付けられ、1 つの system セクションとして扱われます。配置のルールはそのまとまり全体に適用されます。
• 会話に入った system メッセージは安定した履歴の一部になり、それ自体もキャッシュの対象です。送信済みのものを編集・削除すると、その位置から後のキャッシュが無効になります。
• 生のツール出力、取得した文書、Web のコンテンツなど、会話の外から来た文章を system メッセージに直接入れないでください。その文章に運用者レベルの権限を与えることになります。
• Claude Sonnet 5.5 と Claude Haiku 5.5 では、ツールの結果の直後に置いた system メッセージが信頼できない文章として扱われ、無視される場合があります。これらのモデルでは、ユーザーの言葉は user ターンで渡します。

Turn-scoped system messages (ターン限定の system メッセージ) は beta として提供されており、mid-conversation-system-clear-at-2026-08-21 ヘッダーを使います。

• role: "system" のメッセージの clear_at フィールドに "next_user_message" を設定すると、現在のターンに限定できます。SDK では messages 内の role: "system" の要素に clear_at (csharp・go は ClearAt、java は .clearAt()、php は clearAt) を設定し、beta ヘッダーを送ります。
• 文章が反映されるのは、後ろに role: "user" のメッセージが無い間だけです。tool_result ブロックだけを持つ user メッセージも user メッセージに数えます。後に user メッセージが来るとクリアされ、配列には残りますが何も反映されず、そのリクエスト以降は入力トークンもかかりません。
• clear_at の既定値は "never" で、その場合はメッセージを含むすべてのリクエストでその位置に反映されます。
• ターン限定のメッセージの内容は text だけです。tool_addition・tool_removal のブロックや output_config を付けると 400 エラーが返ります。
• ツールのループでリマインダーを見せたいときは、そのたびに tool_result メッセージの後に追加し、それまでのコピーはそのまま残します。
• クリアされたメッセージも会話履歴の一部です。現在の状態から作り直す (新しいトークン数やタイムスタンプを入れる)、不要とみなして削除する、clear_at の値を変える、といった操作は前のメッセージの編集にあたるため、送信済みの内容をそのまま送り直します。

提供開始時点では、Claude Opus 4.8 でユーザーターンの後に role: "system" のメッセージを送れる機能として案内されました。その後、Claude Fable 5、Claude Mythos 5、Claude Opus 4.8 で、Claude API、Claude in Amazon Bedrock、Google Cloud 上で利用でき、beta ヘッダーは不要という内容に訂正されています。ターン限定の system メッセージは beta で、専用のヘッダーが必要です。対象プランについては、公式のリリースノートには記載がありません。

会話途中の system メッセージは Claude Fable 5、Claude Mythos 5、Claude Opus 4.8 で使え、beta ヘッダーは不要です。

1. リクエストに cache_control を含めて、キャッシュを明示的に有効にします。トップレベルの自動キャッシュのフィールドか、content block への明示的なブレークポイントのどちらかを使います。
2. cache_control は、リクエスト間で変わらない最後のブロックに置きます。
3. messages 配列に "role": "system" のメッセージを追加します。content には、user や assistant のターンと同じく、文字列か content blocks を使います。
4. 追加する system メッセージは、キャッシュのブレークポイントより後に置きます。接頭部分のハッシュが変わらないため、キャッシュはヒットします。