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

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