가이드

세션 관리

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는 이전 대화 상태에서 세션을 재개하는 것을 지원하여 지속적인 개발 워크플로우를 가능하게 합니다. 이전 대화를 계속하려면 세션 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"
  }
})

가이드

세션 관리

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

SDK는 세션을 재개할 때 대화 기록과 컨텍스트를 자동으로 로드하여 Claude가 중단했던 곳에서 정확히 계속할 수 있도록 합니다.

세션 포킹

세션을 포킹해야 하는 경우

포킹은 다음과 같은 경우에 유용합니다:

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

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