​
會話管理

Claude Agent SDK 提供會話管理功能，用於處理對話狀態和恢復。會話允許您在多次互動中繼續對話，同時保持完整的上下文。

​
會話如何運作

當您開始新的查詢時，SDK 會自動創建一個會話，並在初始系統消息中返回會話 ID。您可以捕獲此 ID 以便稍後恢復會話。

​
獲取會話 ID

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
    }
  })
}

​
恢復會話

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"
  }
})