指南

会话管理

了解 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-sonnet-4-5"
  }
})

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-sonnet-4-5",
    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-sonnet-4-5" }
})

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-sonnet-4-5"
  }
})

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

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-sonnet-4-5",
    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-sonnet-4-5" }
})

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-sonnet-4-5"
  }
})

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-sonnet-4-5"
  }
})