​
세션 관리

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는 이전 대화 상태에서 세션을 재개하는 것을 지원하여 지속적인 개발 워크플로우를 가능하게 합니다. 이전 대화를 계속하려면 세션 ID와 함께 resume 옵션을 사용하세요. 
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를 생성하세요.

​
세션을 포킹해야 하는 경우

포킹은 다음과 같은 경우에 유용합니다:
  • 같은 시작점에서 다른 접근 방식을 탐색하고 싶을 때
  • 원본을 수정하지 않고 여러 대화 브랜치를 생성하고 싶을 때
  • 원래 세션 기록에 영향을 주지 않고 변경사항을 테스트하고 싶을 때
  • 다른 실험을 위해 별도의 대화 경로를 유지하고 싶을 때

​
포킹 vs 계속하기

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