指南
會話管理
了解 Claude Agent SDK 如何處理會話和會話恢復
會話管理
會話管理
Claude Agent SDK 提供會話管理功能，用於處理對話狀態和恢復。會話允許您在多次互動中繼續對話，同時保持完整的上下文。
會話如何運作
會話如何運作
當您開始新的查詢時，SDK 會自動創建一個會話，並在初始系統消息中返回會話 ID。您可以捕獲此 ID 以便稍後恢復會話。
獲取會話 ID
獲取會話 ID
TypeScript
import { query } from "@anthropic-ai/claude-agent-sdk"
let sessionId: string | undefined
const response = query({
prompt: "幫我建立一個網頁應用程式",
options: {
model: "claude-sonnet-4-5"
}
})
for await (const message of response) {
// 第一條消息是包含會話 ID 的系統初始化消息
if (message.type === 'system' && message.subtype === 'init') {
sessionId = message.session_id
console.log(`會話已開始，ID：${sessionId}`)
// 您可以保存此 ID 以供稍後恢復
}
// 處理其他消息...
console.log(message)
}
// 稍後，您可以使用保存的 sessionId 來恢復
if (sessionId) {
const resumedResponse = query({
prompt: "從我們停下的地方繼續",
options: {
resume: sessionId
}
})
}Python
from claude_agent_sdk import query, ClaudeAgentOptions
session_id = None
async for message in query(
prompt="幫我建立一個網頁應用程式",
options=ClaudeAgentOptions(
model="claude-sonnet-4-5"
)
):
# 第一條消息是包含會話 ID 的系統初始化消息
if hasattr(message, 'subtype') and message.subtype == 'init':
session_id = message.data.get('session_id')
print(f"會話已開始，ID：{session_id}")
# 您可以保存此 ID 以供稍後恢復
# 處理其他消息...
print(message)
# 稍後，您可以使用保存的 session_id 來恢復
if session_id:
async for message in query(
prompt="從我們停下的地方繼續",
options=ClaudeAgentOptions(
resume=session_id
)
):
print(message)恢復會話
恢復會話
SDK 支援從先前的對話狀態恢復會話，實現連續的開發工作流程。使用 resume 選項配合會話 ID 來繼續先前的對話。
import { query } from "@anthropic-ai/claude-agent-sdk"
// 使用會話 ID 恢復先前的會話
const response = query({
prompt: "從我們停下的地方繼續實作身份驗證系統",
options: {
resume: "session-xyz", // 來自先前對話的會話 ID
model: "claude-sonnet-4-5",
allowedTools: ["Read", "Edit", "Write", "Glob", "Grep", "Bash"]
}
})
// 對話會繼續，並保持先前會話的完整上下文
for await (const message of response) {
console.log(message)
}當您恢復會話時，SDK 會自動處理載入對話歷史和上下文，讓 Claude 能夠從停下的地方完全繼續。
分叉會話
分叉會話
當恢復會話時，您可以選擇繼續原始會話或將其分叉為新的分支。預設情況下，恢復會繼續原始會話。使用 forkSession 選項（TypeScript）或 fork_session 選項（Python）來創建一個從恢復狀態開始的新會話 ID。
何時分叉會話
何時分叉會話
分叉在以下情況下很有用：
- 從同一起點探索不同的方法
- 創建多個對話分支而不修改原始對話
- 測試更改而不影響原始會話歷史
- 為不同實驗維護獨立的對話路徑
分叉與繼續
分叉與繼續
| 行為 | forkSession: false（預設） | forkSession: true |
|---|---|---|
| 會話 ID | 與原始相同 | 生成新的會話 ID |
| 歷史 | 附加到原始會話 | 從恢復點創建新分支 |
| 原始會話 | 被修改 | 保持不變 |
| 使用情況 | 繼續線性對話 | 分支探索替代方案 |
範例：分叉會話
範例：分叉會話
import { query } from "@anthropic-ai/claude-agent-sdk"
// 首先，捕獲會話 ID
let sessionId: string | undefined
const response = query({
prompt: "幫我設計一個 REST API",
options: { model: "claude-sonnet-4-5" }
})
for await (const message of response) {
if (message.type === 'system' && message.subtype === 'init') {
sessionId = message.session_id
console.log(`原始會話：${sessionId}`)
}
}
// 分叉會話以嘗試不同的方法
const forkedResponse = query({
prompt: "現在讓我們將其重新設計為 GraphQL API",
options: {
resume: sessionId,
forkSession: true, // 創建新的會話 ID
model: "claude-sonnet-4-5"
}
})
for await (const message of forkedResponse) {
if (message.type === 'system' && message.subtype === 'init') {
console.log(`分叉會話：${message.session_id}`)
// 這將是不同的會話 ID
}
}
// 原始會話保持不變，仍可恢復
const originalContinued = query({
prompt: "為 REST API 添加身份驗證",
options: {
resume: sessionId,
forkSession: false, // 繼續原始會話（預設）
model: "claude-sonnet-4-5"
}
})