對話中途的系統訊息與工具變更

系統指令通常位於頂層的 system 欄位中，排在對話中所有訊息之前。這個位置對於提示快取非常有利：系統提示是穩定前綴的一部分，因此後續的回合都能命中快取。但對於您在工作階段進行到一半才發現需要的指令來說，這是一個不理想的位置，因為編輯頂層的 system 欄位會改變提示的最開頭，並使其後所有內容的快取失效。

對話中途的系統訊息填補了這個缺口。您可以在對話中新指令變得相關的位置附加一個 {"role": "system"} 訊息，而不是編輯頂層的 system 欄位。已快取的前綴保持不變，因此下一個請求仍然可以從快取中讀取它，而新指令仍然會作為系統指令套用，而不是作為一般的使用者文字。

本頁涵蓋兩項功能：對話中途的系統訊息（已正式推出），以及對話中途的工具變更（隨 Claude Opus 5 推出的測試版功能，將相同的方法套用到 tools 陣列）。



對話中途的工具變更

tools 陣列在雜湊的請求前綴中的位置甚至比頂層的 system 欄位更前面，因此編輯它會使整個對話的提示快取失效。對話中途的工具變更是隨 Claude Opus 5 推出的測試版功能，是對話中途系統訊息在工具方面的對應功能。您不必在對話的整個生命週期中固定工具清單，而是可以在回合之間變更提供給模型的工具：預先在 tools 中宣告完整的工具集，然後使用 tool_addition 和 tool_removal 區塊，從對話中的特定位置開始向模型提供某個工具或撤回它。tools 陣列本身永遠不會改變，因此已快取的前綴保持完整。

tool_addition 和 tool_removal 是 role: "system" 訊息的 content 陣列中的內容區塊，它們可以與同一訊息中的 text 區塊混合使用。該訊息遵循與任何對話中途系統訊息相同的放置規則（請參閱限制），且變更從對話中的該位置開始生效。每個區塊的 tool 欄位參照一個工具而不是定義一個工具：{"type": "tool_reference", "name": "..."} 指名請求的 tools 陣列中宣告的工具，而 MCP connector 工具可以使用 mcp_tool_reference（server_name 和 name）個別參照，或使用 mcp_toolset_reference（server_name）參照整個工具集。參照未在 tools 中宣告的名稱會回傳 400 錯誤。

在 tools 中宣告的每個工具從對話開始就會提供給模型，除非它以 defer_loading: true 宣告，這會使其保持隱藏，直到 tool_addition 區塊將其顯現。tool_addition 也可以重新提供先前被 tool_removal 撤回的工具。

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    betas=["mid-conversation-tool-changes-2026-07-01"],
    # 完整的工具集在一開始就宣告且永不變更，因此
    # 快取的前綴保持完整。
    tools=[
        {
            "name": "get_weather",
            "description": "Get the current weather for a location.",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {"type": "string", "description": "City name"},
                },
                "required": ["location"],
            },
        },
    ],
    messages=[
        {
            "role": "user",
            "content": "Say OK.",
        },
        # 從此處開始撤回 get_weather。此區塊以名稱參照
        # 工具，而非編輯 `tools`，因此先前的回合保持
        # 位元組完全相同，快取仍然命中。
        {
            "role": "system",
            "content": [
                {
                    "type": "tool_removal",
                    "tool": {"type": "tool_reference", "name": "get_weather"},
                },
            ],
        },
    ],
)

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

對話中途的工具變更處於測試階段。若要使用它們，請在您的請求中包含 beta 標頭 mid-conversation-tool-changes-2026-07-01。它們可在 Claude Fable 5、Claude Mythos 5、Claude Opus 4.8 和 Claude Opus 5 上使用，支援 Claude API、Amazon Bedrock 和 Google Cloud。



何時使用對話中途的系統訊息

提示快取會依序對請求前綴進行雜湊：先是 tools，然後是 system，最後是 messages。快取命中要求前綴與最近的請求完全相符，逐位元組一致，直到快取斷點為止。

這種順序意味著頂層的 system 欄位位於雜湊前綴的最開頭附近。對它的任何變更，即使只是附加一個句子，都會產生不同的雜湊值，導致請求無法命中系統提示及其後所有已快取訊息的快取。

對話中途的系統訊息讓您可以改為在訊息歷史的末尾新增指令。新指令之前的所有內容都沒有改變，因此現有的快取項目仍然相符，只有新訊息會作為新的輸入被處理。

以下是幾種適用的情況：

• 工作階段中途的政策或角色變更。 一個長時間的代理式工作階段在數十個已快取的回合之後需要一個新的約束（「從現在開始，所有 SQL 都要寫成參數化查詢」）。將它加到頂層的 system 欄位會重新處理整個歷史記錄。
• 必須具有權威性的每回合上下文。 您想要以系統層級的權重注入新鮮度備註、工作階段截止時間或工具可用性變更，而它變化得太頻繁，無法放在已快取的前綴中。
• 您的應用程式觀察到的狀態變更。 您的應用程式注意到 Claude 應該視為操作者層級事實的事情：磁碟上的檔案發生變更、使用者切換了自動核准設定、可用工具發生變更，或剩餘的 token 預算降到閾值以下。
• 不應中斷代理式迴圈的使用者輸入。 使用者在 Claude 仍在為前一個請求執行工具時輸入了後續內容。在下一個工具結果之後將其作為系統訊息轉達，可以讓 Claude 將新輸入融入它正在進行的工作中，而不是將其視為需要切換過去的新請求。請參閱下方的工具結果之後的放置。
• 授予常設權限的模式切換。 工作階段層級的模式可以使用對話中途的系統訊息來授予對昂貴功能的常設同意，例如自動啟動多代理工作流程，並每隔幾個回合進行簡短的提醒，以及在模式關閉時發出退出通知。如需實際範例，請參閱建構協調模式。

在所有這些情況下，您都可以將指令放在一般的 user 訊息中，而 Claude 確實會遵循在使用者回合中出現的指令。差別在於優先順序：user 訊息被視為來自終端使用者，而 system 訊息被視為來自您，也就是應用程式操作者。當兩者衝突時，系統指令優先，因此請對操作者層級的事實和約束使用 system 角色，即使終端使用者要求不同的東西，這些約束也應該維持。對話中途的系統訊息保留了這種操作者層級的優先順序，而無需付出編輯頂層 system 欄位所造成的快取未命中代價。



運作方式

在 messages 陣列中新增一個 "role": "system" 的訊息。content 可以使用純字串或內容區塊，與 user 或 assistant 回合相同。該指令從對話中的該位置開始生效。當指令衝突時，較晚的系統訊息優先於較早的系統訊息，而對話中途的系統訊息在其後的回合中優先於頂層的 system 欄位。

您仍然可以為應該套用於整個對話的指令設定頂層的 system 欄位。將對話中途的系統訊息保留給那些稍後才變得相關的指令，或是您想要在不使已快取前綴失效的情況下新增的指令。

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    # 自動提示快取：每次請求都會快取到目前為止的對話內容，
    # 下一次請求則從快取讀取未變更的前綴。
    cache_control={"type": "ephemeral"},
    system="You are a code review assistant. Be concise.",
    messages=[
        {
            "role": "user",
            "content": "Review process() in utils.py for performance issues.",
        },
        {
            "role": "assistant",
            "content": "The list comprehension is fine for small inputs. For large inputs, consider a generator to avoid materializing the full list.",
        },
        {
            "role": "user",
            "content": "Now review the calling code that invokes process().",
        },
        # 審查者在工作階段中途發現，所有建議還必須
        # 符合團隊嚴格的型別規範。在此處附加
        # 指示可讓先前的回合保持位元組完全一致，因此
        # 前一次請求所快取的前綴仍可從快取中讀取。
        {
            "role": "system",
            "content": "From now on, every suggestion must include explicit type annotations.",
        },
    ],
)

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

此範例使用頂層的 cache_control 欄位啟用自動快取。提示快取是選擇性加入的：如果請求沒有 cache_control 欄位（自動或明確斷點），則不會快取任何內容，每個請求都要為整個對話支付一般的輸入 token 價格。啟用快取後，附加系統訊息不會改變已快取的回合，因此攜帶新指令的請求仍然可以從快取中讀取它們，而不是再次處理它們。快取還要求對話達到最小可快取提示長度；像這樣簡短的範例低於該長度，因此在對話增長之前，cache_creation_input_tokens 和 cache_read_input_tokens 會保持為 0。

對話中途的系統訊息必須緊接在 user 回合之後（或以伺服器工具結果結尾的 assistant 回合之後），並且必須是 messages 中的最後一個項目，或緊接著一個 assistant 回合。攜帶 tool_result 區塊的 user 訊息也算在內：在代理式迴圈中，您可以將系統訊息放在工具結果之後、Claude 的下一個回合之前。任何其他位置，包括在 assistant 的 tool_use 區塊與回應它的 tool_result 之間，都會回傳 400 錯誤。



工具結果之後的放置

在代理式迴圈中，系統訊息放在傳遞工具結果的 user 訊息之後。這也是您的應用程式可以轉達使用者在 Claude 工作時輸入的內容的位置，這樣新的上下文就能被吸收，而無需重新開始該回合：

[
  { "role": "user", "content": "Run the test suite and fix any failures." },
  {
    "role": "assistant",
    "content": [{ "type": "tool_use", "id": "toolu_01", "name": "run_tests", "input": {} }]
  },
  {
    "role": "user",
    "content": [
      { "type": "tool_result", "tool_use_id": "toolu_01", "content": "12 passed, 0 failed" }
    ]
  },
  {
    "role": "system",
    "content": "The user sent the following message while you were working: also update the changelog before you finish."
  }
]

將系統內容表述為上下文，而不是覆蓋使用者的命令。陳述事實（「使用者傳來了新輸入：X」、「剩餘的 token 預算現在是 Y」），然後讓 Claude 據此行動。Claude 經過訓練會抵制看起來與使用者作對的指令，而這種保護仍然適用於系統角色，因此像「忽略使用者所說的話」這樣的措辭，不如陳述發生了什麼變化來得有效。

此模式用於轉達來自對話本身終端使用者的輸入。請勿用它來傳遞工具輸出、檢索到的文件或其他第三方內容；請將這些內容保留在 tool_result 區塊中（請參閱限制）。



與提示快取結合使用

對話中途的系統訊息和提示快取是設計來一起使用的：

• 明確啟用快取。 只有當請求包含 cache_control 時才會進行快取，無論是頂層的自動快取欄位，還是內容區塊上的明確斷點。對話中途的系統訊息本身不會建立快取項目，而且如果沒有啟用快取，就沒有可以保留的節省。
• 照常快取穩定的前綴。 將 cache_control 放在跨請求保持不變的最後一個區塊上，無論那是頂層 system 欄位的結尾、工具定義的結尾，還是訊息歷史中的穩定位置。
• 在斷點之後附加系統訊息。 因為它位於已快取的前綴之後，所以不會改變前綴雜湊值，快取仍然會命中。
• 對話中途的系統訊息本身也是可快取的。 一旦它進入對話，就成為穩定歷史的一部分。在下一個回合，您可以將快取斷點移到它之後（或依靠自動快取來做到這一點），系統訊息就會像任何其他回合一樣從快取中讀取。

避免編輯或移除已經傳送的對話中途系統訊息。就像對較早訊息的任何其他變更一樣，這會使從該位置開始的快取失效。如果指令需要演進，請附加一個新的系統訊息，而不是重寫舊的。連續的系統訊息是被接受的，並被視為單一的系統區段，整體遵循相同的放置規則。



限制

• 不能作為第一個訊息。 system 訊息不能是 messages 中的第一個項目。對於從一開始就適用的指令，請使用頂層的 system 欄位。
• 放置位置受到限制。 system 訊息必須緊接在 user 回合之後（包括攜帶 tool_result 區塊的 user 回合）或以伺服器工具結果結尾的 assistant 回合之後，並且必須位於 assistant 回合之前或作為陣列的結尾。它不能位於 tool_use 區塊與其 tool_result 之間。將它放在其他位置會回傳 400 錯誤。
• 不是放置不受信任內容的地方。 Claude 將系統內容視為操作者指令並遵循它。請勿將來自對話之外的文字（例如原始工具輸出、檢索到的文件或網頁內容）直接放在系統訊息中；這樣做會賦予該文字操作者層級的權限。請將這些資料保留在 tool_result 區塊中，並繼續遵循緩解越獄和提示注入。



相關資源