Skip to main content
Session 是 SDK 在您的代理工作時累積的對話歷史。它包含您的提示、代理進行的每個工具呼叫、每個工具結果和每個回應。SDK 會自動將其寫入磁碟,以便您稍後可以返回它。 返回 session 意味著代理具有之前的完整上下文:它已經讀取的檔案、它已經執行的分析、它已經做出的決定。您可以提出後續問題、從中斷中恢復,或分支以嘗試不同的方法。
Sessions 保持對話,而不是檔案系統。要快照和還原代理所做的檔案更改,請使用檔案檢查點。
本指南涵蓋如何為您的應用選擇正確的方法、自動追蹤 sessions 的 SDK 介面、如何捕獲 session ID 並手動使用 resume 和 fork,以及關於跨主機恢復 sessions 的注意事項。

選擇一個方法

您需要多少 session 處理取決於您的應用程式的形狀。當您發送應該共享上下文的多個提示時,session 管理就會發揮作用。在單個 query() 呼叫中,代理已經根據需要進行了盡可能多的轉換,並且權限提示和 AskUserQuestion 是在迴圈中處理的(它們不會結束呼叫)。

Continue、resume 和 fork

Continue、resume 和 fork 是您在 query() 上設定的選項欄位(Python 中的 ClaudeAgentOptions,TypeScript 中的 Options)。 Continue 和 resume 都會拾取現有 session 並將其添加到其中。區別在於它們如何找到該 session:
  • Continue 在當前目錄中找到最近的 session。您無需追蹤任何內容。當您的應用一次運行一個對話時效果很好。
  • Resume 採用特定的 session ID。您追蹤 ID。當您有多個 sessions(例如,多使用者應用中每個使用者一個)或想要返回不是最近的 session 時需要。
Fork 不同:它創建一個新 session,從原始 session 的歷史副本開始。原始 session 保持不變。使用 fork 嘗試不同的方向,同時保持返回的選項。

自動工作階段管理

兩個 SDK 都提供了一個介面,可以為您跨呼叫追蹤工作階段狀態,因此您不需要手動傳遞 ID。將這些用於單一程序內的多輪對話。

Python:ClaudeSDKClient

ClaudeSDKClient 在內部處理工作階段 ID。每次呼叫 client.query() 都會自動繼續同一工作階段。呼叫 client.receive_response() 以逐一查看目前查詢的訊息。將用戶端用作非同步內容管理器,以便為您處理連線設定和清除,或手動呼叫 connect() 和 disconnect()。 此範例針對同一 client 執行兩個查詢。第一個要求代理程式分析一個模組;第二個要求它重構該模組。因為兩個呼叫都通過同一用戶端執行個體,第二個查詢具有來自第一個查詢的完整內容,無需任何明確的 resume 或工作階段 ID:
Python
每個查詢都會列印代理程式的文字回應,後面跟著結果訊息的狀態行,例如 [done: success, cost: $0.0042]。 如需有關何時使用 ClaudeSDKClient 與獨立 query() 函式的詳細資訊,請參閱 Python SDK 參考。

TypeScript:continue: true

TypeScript SDK 沒有像 Python 的 ClaudeSDKClient 這樣的工作階段保持用戶端物件。相反,在每個後續 query() 呼叫上傳遞 continue: true,SDK 會在目前目錄中選取最近的工作階段。無需 ID 追蹤。 此範例進行兩個單獨的 query() 呼叫。第一個建立新的工作階段;第二個設定 continue: true,這會告訴 SDK 在磁碟上尋找並繼續最近的工作階段。代理程式具有來自第一個呼叫的完整內容:
TypeScript