指南

工作階段管理

了解 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: "Help me build a web application",
  options: {
    model: "claude-opus-4-6"
  }
})

for await (const message of response) {
  // The first message is a system init message with the session ID
  if (message.type === 'system' && message.subtype === 'init') {
    sessionId = message.session_id
    console.log(`Session started with ID: ${sessionId}`)
    // You can save this ID for later resumption
  }

  // Process other messages...
  console.log(message)
}

// Later, you can use the saved sessionId to resume
if (sessionId) {
  const resumedResponse = query({
    prompt: "Continue where we left off",
    options: {
      resume: sessionId
    }
  })
}

恢復工作階段

SDK 支援從先前的對話狀態恢復工作階段，實現持續的開發工作流程。使用 resume 選項搭配工作階段 ID 來繼續先前的對話。

import { query } from "@anthropic-ai/claude-agent-sdk"

// Resume a previous session using its ID
const response = query({
  prompt: "Continue implementing the authentication system from where we left off",
  options: {
    resume: "session-xyz", // Session ID from previous conversation
    model: "claude-opus-4-6",
    allowedTools: ["Read", "Edit", "Write", "Glob", "Grep", "Bash"]
  }
})

// The conversation continues with full context from the previous session
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"

// First, capture the session ID
let sessionId: string | undefined

const response = query({
  prompt: "Help me design a REST API",
  options: { model: "claude-opus-4-6" }
})

for await (const message of response) {
  if (message.type === 'system' && message.subtype === 'init') {
    sessionId = message.session_id
    console.log(`Original session: ${sessionId}`)
  }
}

// Fork the session to try a different approach
const forkedResponse = query({
  prompt: "Now let's redesign this as a GraphQL API instead",
  options: {
    resume: sessionId,
    forkSession: true,  // Creates a new session ID
    model: "claude-opus-4-6"
  }
})

for await (const message of forkedResponse) {
  if (message.type === 'system' && message.subtype === 'init') {
    console.log(`Forked session: ${message.session_id}`)
    // This will be a different session ID
  }
}

// The original session remains unchanged and can still be resumed
const originalContinued = query({
  prompt: "Add authentication to the REST API",
  options: {
    resume: sessionId,
    forkSession: false,  // Continue original session (default)
    model: "claude-opus-4-6"
  }
})

Was this page helpful?

指南

工作階段管理

了解 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: "Help me build a web application",
  options: {
    model: "claude-opus-4-6"
  }
})

for await (const message of response) {
  // The first message is a system init message with the session ID
  if (message.type === 'system' && message.subtype === 'init') {
    sessionId = message.session_id
    console.log(`Session started with ID: ${sessionId}`)
    // You can save this ID for later resumption
  }

  // Process other messages...
  console.log(message)
}

// Later, you can use the saved sessionId to resume
if (sessionId) {
  const resumedResponse = query({
    prompt: "Continue where we left off",
    options: {
      resume: sessionId
    }
  })
}

恢復工作階段

SDK 支援從先前的對話狀態恢復工作階段，實現持續的開發工作流程。使用 resume 選項搭配工作階段 ID 來繼續先前的對話。

import { query } from "@anthropic-ai/claude-agent-sdk"

// Resume a previous session using its ID
const response = query({
  prompt: "Continue implementing the authentication system from where we left off",
  options: {
    resume: "session-xyz", // Session ID from previous conversation
    model: "claude-opus-4-6",
    allowedTools: ["Read", "Edit", "Write", "Glob", "Grep", "Bash"]
  }
})

// The conversation continues with full context from the previous session
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"

// First, capture the session ID
let sessionId: string | undefined

const response = query({
  prompt: "Help me design a REST API",
  options: { model: "claude-opus-4-6" }
})

for await (const message of response) {
  if (message.type === 'system' && message.subtype === 'init') {
    sessionId = message.session_id
    console.log(`Original session: ${sessionId}`)
  }
}

// Fork the session to try a different approach
const forkedResponse = query({
  prompt: "Now let's redesign this as a GraphQL API instead",
  options: {
    resume: sessionId,
    forkSession: true,  // Creates a new session ID
    model: "claude-opus-4-6"
  }
})

for await (const message of forkedResponse) {
  if (message.type === 'system' && message.subtype === 'init') {
    console.log(`Forked session: ${message.session_id}`)
    // This will be a different session ID
  }
}

// The original session remains unchanged and can still be resumed
const originalContinued = query({
  prompt: "Add authentication to the REST API",
  options: {
    resume: sessionId,
    forkSession: false,  // Continue original session (default)
    model: "claude-opus-4-6"
  }
})

Was this page helpful?