指南

會話管理

了解 Claude Agent SDK 如何處理會話和會話恢復

會話管理

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

指南

會話管理

了解 Claude Agent SDK 如何處理會話和會話恢復

會話管理

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