Руководства

Управление сессиями

Понимание того, как 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 обрабатывает сессии и возобновление сессий

Управление сессиями

Как работают сессии

Получение 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
    }
  })
}

Возобновление сессий

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

Разветвление сессий

Когда разветвлять сессию

Разветвление полезно, когда вы хотите:

Исследовать различные подходы с одной и той же отправной точки
Создать множественные ветки разговора без изменения оригинала
Тестировать изменения без влияния на историю оригинальной сессии
Поддерживать отдельные пути разговора для различных экспериментов

Разветвление против продолжения

Поведение	`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"
  }
})