訊息串

使用「message thread」（訊息串）時，請求會更小，而且隨著對話增長，「time to first token」（首個權杖時間）會維持較低且更穩定。訊息串在長時間的代理迴圈中最有幫助。沒有訊息串時，每一輪都會重新上傳整個對話，而 API 也會重新驗證並將其全部進行 tokenize。使用訊息串時，大部分的工作只涵蓋新的一輪。

「Message thread」（訊息串）會將對話在伺服器上保留一小段時間。您只需傳送一次完整的對話，連同您的系統提示和工具。在之後的每一輪中，您只需傳送新的訊息以及前一個回應的 id。API 會在呼叫模型之前重建對話。您只需在 Messages API 請求中加入一個參數 thread。回應則是一般的訊息。

訊息串的運作方式

• 建立。 像您現在一樣傳送第一個請求，包含完整對話、system 和 tools，並加上 "thread": {"type": "create"}。API 會將對話（包括 Claude 的回覆）儲存在回應的 id 之下。
• 繼續。 只傳送自上一個回應以來的訊息，並加上 "thread": {"type": "continue", "previous_message_id": "<previous id>"}。請勿在請求中包含 system 和 tools。訊息串會保留建立請求中的值。每個新回應的 id 用於下一輪。
• 重播。 訊息串採盡力而為（best-effort）方式。訊息串會在最後一次請求後 5 分鐘過期，且 API 會在最後一次使用後不超過 1 小時內將其刪除。API 儲存的每個回應都會重新開始計算這 5 分鐘。如果 API 無法再繼續該訊息串，繼續請求會傳回 404 錯誤。請在新的建立請求中再次傳送完整對話，並從該回應的 id 繼續。SDK 訊息串輔助工具會為您執行此重播（請參閱SDK 輔助工具的運作方式）。在收到來自備援模型的回應之後，請參閱搭配訊息串使用備援。

您的應用程式仍是對話的唯一事實來源（source of truth）。請保留每則訊息的自有副本，並從一開始就建立重播路徑。無論是對建立請求還是繼續請求的回應，都不會告訴您 API 是否儲存了該輪對話。您要到下一次繼續請求時才會得知。SDK 的訊息串輔助工具會在輔助物件存在期間將此副本保留在記憶體中，且不會將其儲存到其他任何地方。如果對話必須在您的程序結束後繼續存在，請保留您自己的副本。

透過 SDK 使用訊息串

SDK 提供一個訊息串輔助工具，可為您建構訊息串請求。使用與 Messages 請求相同的欄位建立它，然後一次傳送一輪。輔助工具會將完整對話保存在記憶體中。

此範例有兩輪。輔助工具會在第一輪建立訊息串，並在第二輪繼續它，同時為您加入 beta 標頭。頂層的 cache_control 是選用的。它會要求在每一輪進行提示快取（請參閱訊息串上的提示快取）。若沒有它，之後的每一輪仍然只會傳送新的訊息，但除非您自行加入快取中斷點，否則不會快取任何內容。

client = anthropic.Anthropic()

# 建立 helper。此呼叫不會傳送任何請求。
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 輪：helper 建立一個 thread 並傳送完整對話
thread.send({"role": "user", "content": "Hi! I have a question about an order."})

# 第 2 輪：helper 延續該 thread，僅傳送新訊息
second = thread.send(
    {"role": "user", "content": "How long does standard shipping usually take?"}
)

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

自行傳送 thread 欄位

若要自行建構訊息串請求，例如使用 cURL、CLI 或 SDK 一般的 create 方法，請在每個請求中加入 thread 欄位。

在訊息串的每個請求中傳送 message-threads-2026-08-12 beta 標頭。

此範例在第一輪建立訊息串，並在第二輪繼續它。頂層的 cache_control 會要求在每一輪進行提示快取。一旦對話長度超過最小可快取長度，它就會生效。

client = anthropic.Anthropic()

# 第 1 輪：傳送完整對話並建立 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"],
)

# 第 2 輪：僅傳送新訊息及第 1 輪回應的 id。
# 省略 system 與 tools：thread 會保留它們。
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)

每個請求要傳送的內容

API 不會儲存 MCP 伺服器 URL、MCP 授權權杖或容器 id。請在每個使用它們的請求中傳送 mcp_servers 和 container。MCP 授權權杖可以在請求之間變更。

SDK 訊息串輔助工具會為您在繼續請求中省略 system 和 tools，並在每一輪再次傳送固定欄位。

如果您使用伺服器端備援，請在訊息串的每個請求中都傳送 fallbacks 欄位，或全都不傳送。請參閱搭配訊息串使用備援。

若要變更僅限建立或固定的欄位，請開始新的訊息串：在建立請求中以新的值傳送完整的對話。

在 Claude Fable 5.1、Claude Mythos 5.1、Claude Opus 5.5、Claude Sonnet 5.5 和 Claude Haiku 5.5 上，變更 system 或 tools 會使對話中已有的 thinking 和 redacted_thinking 區塊失效，且建立請求可能會傳回 400 錯誤。若要避免這種情況，請在您傳送的對話中省略所有 thinking 和 redacted_thinking 區塊。模型隨後會在沒有先前推理的情況下作答。請參閱哪些變更算是編輯、未設定 prefix_mismatch_behavior 時和API 如何處理無效區塊。

在繼續請求中只傳送新的訊息。API 不會將它們與已有的訊息進行比對。您再次傳送的訊息可能會在對話中出現兩次，或者請求可能會傳回錯誤。例如，以前一個回應開頭的繼續請求會傳回錯誤。

新訊息通常以 user 訊息開頭：您的下一個使用者輪次，或回應上一個回應中 tool_use 的 tool_result 區塊。如果回應以 stop_reason: "pause_turn" 停止，請使用從該回應的 id 發出、且 messages 清單為空（"messages": []）的繼續請求來恢復它。如果該請求傳回 404 錯誤，請在新的建立請求中重播完整對話，包括已暫停的回應。在該輪暫停期間，請勿傳送新的 user 訊息：API 會拒絕它。使用 SDK 訊息串輔助工具時，請在不帶任何訊息的情況下呼叫 send()：輔助工具會傳送此請求，並在發生 404 錯誤時重播。

訊息串是僅能附加的，且每個回應 id 只能被繼續一次。請一律從訊息串的最新回應 id 繼續。若要編輯或分支較早的訊息，請使用建立請求開始新的訊息串。若要以摘要取代較早的輪次，請參閱壓縮對話。

訊息串上的提示快取

訊息串不會為您快取提示。提示快取的運作方式與沒有訊息串時相同：由您選擇快取中斷點的位置。

若要快取每一輪，請在訊息串的每個請求中傳送頂層的 cache_control，如前面的範例所示。API 會將其套用到每個請求 messages 中最後一個可快取的區塊。接著，每一輪都會從快取讀取較早的對話，並將新的一輪寫入快取。頂層的 cache_control 是固定欄位：請在每個請求中傳送相同的值。

您也可以自行在區塊上放置 cache_control 中斷點：

• 您在建立請求中傳送的中斷點，如果位於 tools、system 上，或位於最後一個訊息區塊之前的訊息區塊上，則在之後的每一輪中都會持續生效。位於請求 messages 最後一個區塊上的中斷點，會在該請求上寫入快取。若要快取每個新的輪次，請在每個請求上傳送中斷點。沒有中斷點的請求仍可能從快取中讀取部分對話。
• 中斷點傳送後便無法移動或移除，因為繼續請求無法再次傳送較早的訊息。
• 帶有 thread 的請求最多可攜帶 4 個 cache_control 中斷點。頂層的 cache_control 算作一個。建立請求中 system 和 tools 上的中斷點，在每次繼續請求時都會再次計入。較早已儲存訊息上的中斷點不計入。多出一個中斷點就會傳回代碼為 thread_unsupported_request 的 400 錯誤。
• 如果您自行在訊息區塊上放置中斷點，當您在新的建立請求中重播對話時，請將其從較早的訊息中移除，並在最後一個區塊上保留一個，讓請求維持在 4 個的限制之內。

串流

訊息串可搭配串流使用。回應 id 會在 message_start 事件中送達，但請在收到 message_stop 事件之後才從它繼續。較早送出的繼續請求可能會傳回 404 錯誤。

如果繼續請求的串流在 message_stop 之前中斷，請再次傳送相同的繼續請求。如果該請求傳回 thread_already_continued 或 thread_continue_in_flight 錯誤，請在新的建立請求中重播完整的對話。

您的連線可能在伺服器仍在生成回應時中斷，或在伺服器儲存回應之後中斷。這就是 API 可能拒絕重試的原因。重播永遠是安全的。

SDK 訊息串輔助工具在串流中斷後不會重試繼續請求。請參閱SDK 輔助工具的運作方式。

當訊息串無法繼續時進行復原

當 API 無法繼續訊息串時，繼續請求會傳回 404 錯誤，且 error.details.error_code 設為 thread_not_found。回應不會說明原因。原因包括以下幾種：

• 訊息串已過期。
• API 提供了前一輪，但沒有儲存它。例如，API 不會儲存以被 max_tokens 截斷的工具呼叫結尾的回應。
• 前一個回應是由備援模型撰寫的。請參閱搭配訊息串使用備援。
• 前一個回應仍在生成中。
• 請求來自不同的組織或工作區。
• 請求來自與建立訊息串者不同的使用者或服務帳戶。使用工作區金鑰（舊版）建立的訊息串會綁定該金鑰，因此請在整個訊息串中使用相同的金鑰。
• 新的訊息加入了已儲存的對話無法接受的內容。例如，在原本沒有圖片的對話中加入第一張圖片可能會傳回此錯誤。

若要復原，請從您自己的副本中，在新的建立請求中傳送完整對話，並附上 system 和 tools。SDK 訊息串輔助工具會自行傳送一次此建立請求，並在傳送時省略先前輪次的 cache_control 中斷點。如果您副本中的先前訊息帶有 cache_control 中斷點，請先將其移除（請參閱訊息串上的提示快取）。然後從新回應的 id 繼續。如果先前的回應是由備援模型撰寫的，請參閱搭配訊息串使用備援。若要排除擁有權方面的原因，請對訊息串的每個請求使用相同的 API 金鑰和工作區。在 Claude Platform on AWS 上，請使用建立該訊息串的 IAM 角色或 IAM 使用者的憑證，為該訊息串的每個請求簽署。

對不存在之模型的請求也會傳回 404 錯誤，因此請在重播之前檢查 error.details.error_code。

如果在您重播後，繼續請求仍立即傳回 404 錯誤，API 可能無法儲存該對話，例如非常大的對話。請在不使用 thread 的情況下傳送。當您在建立 SDK 訊息串輔助工具時將 unsupported_request_behavior 設為 continue_unthreaded 時，它就會這麼做。否則它會在每一輪都進行重播。

拒絕之後

當回應帶有 stop_reason: "refusal" 時，請勿繼續該訊息串。API 可能已經保存了被拒絕的那一輪，而繼續請求無法將其移除。請使用省略或改寫導致拒絕之那一輪的建立請求來開始新的訊息串。請參閱拒絕與備援。SDK 訊息串輔助工具會為您執行此操作：它不會保留被拒絕的那一輪，且其下一輪會開始新的訊息串。

搭配訊息串使用備援

伺服器端備援可在 Claude API 上搭配訊息串使用。請在建立訊息串時決定：在訊息串的每個請求中都傳送 fallbacks，或全都不傳送。fallbacks 的值可以在請求之間變更。新增或移除 fallbacks 的繼續請求會傳回代碼為 thread_fingerprint_mismatch 的 400 錯誤。

訊息串只保留一個模型，因此 API 不會儲存由備援模型撰寫的輪次。您會照常收到回應，但無法從其 id 繼續。在每個回應之後，請遵循以下步驟：

1. 如果 stop_reason 為 "refusal"，請依照拒絕之後的說明進行。
2. 否則，請在 usage.iterations 中尋找 fallback_message 項目。在串流中，請從最後的 message_delta 事件讀取。如果沒有該項目，請照常繼續該訊息串。
3. 如果有，表示該回應是由備援模型撰寫的。請在新的建立請求中傳送完整對話，包括該回應以及您的下一則訊息。請在該請求上保留 server-side-fallback-2026-07-01 beta 標頭。從以下兩種請求中擇一：
   • 再次傳送相同的請求。 保持 model、fallbacks 及其他參數不變。如果由您請求的模型回答，API 會儲存新的訊息串。如果由備援模型回答，回應中會再次出現 fallback_message 項目，且 API 不會儲存它，因此請在下一輪重複此步驟。黏性路由可能會將這些請求直接傳送至備援模型，因此每一輪都可能需要傳送完整對話。SDK 訊息串輔助工具即以此方式運作。
   • 在備援模型上開始新的訊息串。 將 model 設為該 fallback_message 項目中的 model，省略 fallbacks，並使用此模型接受的參數。API 會立即儲存此訊息串，且它會持續使用備援模型。備援嘗試執行時所用的設定可能與您傳送的不同，因此 API 可能會拒絕從您第一個請求複製過來的值。
4. 使用該請求的回應回到步驟 1。當回應沒有 fallback_message 項目時，從其 id 繼續新的訊息串。

黏性路由會在請求發生備援後開始（建立請求，或不含 thread 的請求）。在大約一小時內，它可能會將同一對話中後續包含 fallbacks 的建立請求直接傳送至備援模型，而不嘗試您請求的模型。API 不會儲存這些輪次中的任何一輪，且每一輪獲得回答都會重新開始計算這一小時。繼續請求永遠不會啟動此路由，也永遠不會使用它。如果您的組織或工作區使用零資料保留或客戶管理的加密金鑰，則黏性路由不適用。

壓縮對話

訊息串是僅能附加的，因此您無法以摘要取代其較早的輪次。若要壓縮對話，請從摘要開始新的訊息串。請在您的程式碼中撰寫摘要，並在新的建立請求中將其作為一般訊息傳送，連同 system 和 tools。隨需壓縮無法搭配訊息串使用（請參閱訊息串不支援的功能）。

SDK 輔助工具的運作方式

輔助工具為您做的事：

• 在每個使用該訊息串的請求中加入 message-threads-2026-08-12 beta 標頭。
• 在第一輪建立訊息串，之後繼續該訊息串，只傳送新訊息，並省略 system 和 tools。
• 當繼續請求傳回 thread_not_found、thread_already_continued 或 thread_continue_in_flight 時，在新的建立請求中重播一次完整對話。
• 當您不帶任何訊息呼叫 send() 時，恢復 pause_turn 回應。
• 在拒絕之後開始新的訊息串。您會照常收到 stop_reason: "refusal" 回應，但輔助工具不會保留該輪：它會收回您提供給該次呼叫的訊息。您透過 thread.append(...) 加入的訊息，或在建立輔助工具時提供的訊息，會保持暫存狀態。您的下一輪會在新的建立請求中，將它們連同被拒絕那一輪之前的對話一起傳送。請傳送改寫過的訊息；或者，如果是某則暫存訊息導致了拒絕，請從不含該訊息的 params 開始新的訊息串。
• 在收到來自備援模型的回應後傳送新的建立請求。當回應在 usage.iterations 中有 fallback_message 項目時，輔助工具會保留該回應，並在下一輪於新的建立請求中傳送完整對話。它不會等待 404 錯誤。該請求會保留您設定的 model 和 fallbacks。
• 每當再次傳送先前各輪時（例如在重播中或在分支的第一輪中），省略其 cache_control 中斷點。您最新的訊息、system、tools 以及頂層的 cache_control 會依您提供的內容送出。

您需要自行處理的事：

• 備援。 當 API 持續由備援模型回答時，輔助工具會在每一輪都於新的建立請求中傳送完整對話，因為 API 不會儲存這些輪次中的任何一輪。在收到您所請求模型的回應後，它會回到使用繼續請求。若要改為將對話移至備援模型，請從 params 開始一個新的訊息串，使用該 model 且不含 fallbacks，如搭配訊息串使用備援中所述。
• 中斷的串流。 如果串流在回應途中結束，輔助工具會保留已完成的區塊以及任何已抵達的文字，而下一輪會在新的建立請求中傳送完整對話。輔助工具不會自行重試：若要改為重新傳送被中斷的那一輪，請不帶任何訊息呼叫 send()。如果保留的部分以工具呼叫結尾，請在您的下一則訊息中回應它們。如果您在串流顯示 stop_reason: "refusal" 之後停止讀取，輔助工具會將該輪視為拒絕。
• 其他錯誤。 thread_fingerprint_mismatch 和 thread_unsupported_request 錯誤會傳遞到您的程式碼。若要在發生 thread_unsupported_request 錯誤後不使用 thread 繼續進行，請在建立輔助工具時將 unsupported_request_behavior 設為 continue_unthreaded。使用該設定時，若重播後的第一個繼續請求再次傳回 thread_not_found，輔助工具也會停止使用 thread。API 可能無法儲存該對話。若未使用該設定，輔助工具會在每一輪都進行重播。自行建立訊息串的工具執行器預設會使用該設定。

SDK 的 beta 工具執行器預設也會使用訊息串，您可以在建立執行器時將其關閉。

其他輔助方法

串流。 輔助工具會在串流到達 message_stop 時記錄回應，因此請將串流讀取到結尾。如果您提早停止讀取，請結束串流，讓訊息串可供下一輪使用：

• Python：離開 with 區塊。
• TypeScript：離開迴圈或呼叫 abort()。
• Go：呼叫 Close。
• Java 和 Ruby：呼叫 close()。
• C#：處置列舉器。離開 await foreach 即會執行此操作。
• PHP：呼叫 close()。

在 C# 中，請求會在您開始讀取串流時送出。

在 C#、Go、Java 和 PHP 中，發生拒絕後，thread.LastMessage 仍會傳回上一輪的回應，若是第一輪則不傳回任何內容。請從串流的事件中讀取拒絕。

變更欄位。 更新不會傳送任何內容，並會套用到之後的每一輪。一旦訊息串有了回應，輔助工具就會拒絕變更 system 或 tools 的輪次，而 API 會拒絕對任何其他固定欄位的變更（請參閱每個請求要傳送的內容）。若要變更這些欄位之一，請從 params 開始新的訊息串，或分叉訊息串並在分叉的第一輪之前更新它。

分叉。 分叉會複製對話、欄位和請求選項，且不會傳送任何內容。它的第一輪會在新的建立請求中傳送完整的對話，之後兩個訊息串便彼此獨立。分叉一律從整個對話開始，而不是從較早的回應開始。

Params。 params 包含輔助工具的欄位以及完整對話。將它們傳遞給建立輔助工具的方法即可開始新的訊息串，例如使用不同的 system（請參閱每個請求要傳送的內容），或將 messages 截短以捨棄後續輪次。從 params 開始的訊息串會依您提供的方式傳送每則訊息，包括 cache_control 中斷點，因此請保持在 4 個的上限之內（請參閱訊息串上的提示快取）。除了 Ruby 之外，params 不包含請求選項，因此請再次傳遞這些選項。

結構化輸出。 請在建立輔助工具時提供輸出格式。後續輪次無法變更它。取得解析結果的方式取決於 SDK：

• Python 和 TypeScript：呼叫 thread.parse(...)。
• C#：使用 client.Beta.Messages.Thread<T>(...) 建立輔助工具。
• Go：Send 會反序列化至 Params.OutputConfig.Format.Schema 所指向的結構。
• Java：使用 thread(...) 和 outputConfig(MyClass.class) 建立輔助工具。
• PHP：當 outputConfig 指定模型類別時，send() 會在文字區塊上設定 parsed。
• Ruby：將 output_config: {format: MyModel} 傳遞給 thread(...)，然後讀取 reply.parsed_output。

錯誤

API 會在模型執行之前傳回此表中的錯誤。請求不會使用任何權杖，且訊息串及其到期時間不會改變。400 錯誤的 error.type 為 invalid_request_error，404 錯誤的則為 not_found_error。

某些訊息串請求的 400 錯誤不帶有 error_code，例如沒有 previous_message_id 的繼續請求，或包含 system 或 tools 的繼續請求。

以下範例顯示錯誤主體：

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "thread: a maximum of 4 blocks with cache_control may be provided when `thread` is set. Found 5.",
    "details": {
      "error_code": "thread_unsupported_request",
      "unsupported": ["cache_control"]
    }
  },
  "request_id": "req_011CSHoEeqs5C35K2UUqR7Fy"
}

訊息串不支援的功能

訊息串不支援以下功能：

• Message Batches。包含 thread 的請求項目會在批次結果中以 invalid_request_error 結束。
• 權杖計數。包含 thread 的權杖計數請求會傳回 400 錯誤。請改為計算完整的對話，連同 system 和 tools。
• 壓縮。隨需壓縮無法搭配訊息串使用。包含 thread 的請求如果設定了 compaction 參數，或搭配 compact-2026-09-04 beta 標頭傳送 compaction 區塊，就會傳回 400 錯誤。請參閱壓縮對話。
• 上下文編輯，但搭配 keep: "all" 的 clear_thinking_20251015 除外。
• 已啟用 HIPAA 就緒的組織。
• 已開啟推論掛鉤的組織。

API 會以 400 錯誤和代碼 thread_unsupported_request 拒絕大多數訊息串不支援的請求。當 error.details.unsupported 存在時，它會包含以下其中一個值：

API 可能會在此清單中新增值。如果您收到無法辨識的值，請在不使用 thread 的情況下傳送完整的對話。符合其中多個條件的請求所收到的錯誤只會指出其中一個。

限制

• 沒有用於列出、讀取或刪除訊息串的 API。
• 訊息串可在 Claude API、Claude Platform on AWS、 Claude Models on Google Cloud (Anthropic managed)、以及 Claude in Microsoft Foundry 上使用。

定價與速率限制

訊息串不會改變定價或速率限制。

資料保留

訊息串不符合 ZDR 資格。使用此功能不會影響您使用其他符合 ZDR 資格的功能。API 會將訊息串保存在記憶體中，並以伺服器管理的金鑰加密，絕不會將其寫入持久性儲存空間，且會在最後一次使用後不超過 1 小時內將其刪除。

訊息串保存 API 傳送給模型的對話、建立請求中的 system 和 tools，以及固定欄位的指紋，用於檢查之後的請求。它以參照方式保存檔案，因此在您使用訊息串期間，請讓對話所使用的每個檔案保持可用。

如需所有功能的 ZDR 資格，請參閱 API 與資料保留。

另請參閱

• 提示快取
• 串流
• 錯誤

可用性

訊息串在所有模型上處於 Beta 階段。

API 支援

Beta 標頭可讓您在實驗性功能與新模型能力成為標準 API 的一部分之前搶先存取。