가이드

세션 관리

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-opus-4-6"
  }
})

for await (const message of response) {
  // 첫 번째 메시지는 세션 ID가 포함된 시스템 초기화 메시지입니다
  if (message.type === 'system' && message.subtype === 'init') {
    sessionId = message.session_id
    console.log(`Session started with ID: ${sessionId}`)
    // 나중에 재개하기 위해 이 ID를 저장할 수 있습니다
  }

  // 다른 메시지 처리...
  console.log(message)
}

// 나중에 저장된 sessionId를 사용하여 재개할 수 있습니다
if (sessionId) {
  const resumedResponse = query({
    prompt: "Continue where we left off",
    options: {
      resume: sessionId
    }
  })
}

세션 재개

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

import { query } from "@anthropic-ai/claude-agent-sdk"

// 세션 ID를 사용하여 이전 세션 재개
const response = query({
  prompt: "Continue implementing the authentication system from where we left off",
  options: {
    resume: "session-xyz", // 이전 대화의 세션 ID
    model: "claude-opus-4-6",
    allowedTools: ["Read", "Edit", "Write", "Glob", "Grep", "Bash"]
  }
})

// 이전 세션의 전체 컨텍스트와 함께 대화가 계속됩니다
for await (const message of response) {
  console.log(message)
}

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

세션 간 파일 변경 사항을 추적하고 되돌리려면 파일 체크포인팅을 참조하세요.

세션 포크

세션을 재개할 때 원래 세션을 계속하거나 새 브랜치로 포크할 수 있습니다. 기본적으로 재개하면 원래 세션이 계속됩니다. 재개된 상태에서 시작하는 새 세션 ID를 생성하려면 forkSession 옵션(TypeScript) 또는 fork_session 옵션(Python)을 사용하세요.

세션을 포크해야 하는 경우

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

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

포크 vs 계속

동작	`forkSession: false` (기본값)	`forkSession: true`
세션 ID	원본과 동일	새 세션 ID 생성
기록	원래 세션에 추가	재개 지점에서 새 브랜치 생성
원래 세션	수정됨	변경 없이 보존
사용 사례	선형 대화 계속	대안 탐색을 위한 브랜치

예시: 세션 포크하기

import { query } from "@anthropic-ai/claude-agent-sdk"

// 먼저 세션 ID를 캡처합니다
let sessionId: string | undefined

const response = query({
  prompt: "Help me design a REST API",
  options: { model: "claude-opus-4-6" }
})

for await (const message of response) {
  if (message.type === 'system' && message.subtype === 'init') {
    sessionId = message.session_id
    console.log(`Original session: ${sessionId}`)
  }
}

// 다른 접근 방식을 시도하기 위해 세션을 포크합니다
const forkedResponse = query({
  prompt: "Now let's redesign this as a GraphQL API instead",
  options: {
    resume: sessionId,
    forkSession: true,  // 새 세션 ID를 생성합니다
    model: "claude-opus-4-6"
  }
})

for await (const message of forkedResponse) {
  if (message.type === 'system' && message.subtype === 'init') {
    console.log(`Forked session: ${message.session_id}`)
    // 이것은 다른 세션 ID가 됩니다
  }
}

// 원래 세션은 변경되지 않으며 여전히 재개할 수 있습니다
const originalContinued = query({
  prompt: "Add authentication to the REST API",
  options: {
    resume: sessionId,
    forkSession: false,  // 원래 세션 계속 (기본값)
    model: "claude-opus-4-6"
  }
})

Was this page helpful?

가이드

세션 관리

Claude Agent SDK가 세션과 세션 재개를 처리하는 방법 이해하기

세션 관리

세션 작동 방식

세션 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-opus-4-6"
  }
})

for await (const message of response) {
  // 첫 번째 메시지는 세션 ID가 포함된 시스템 초기화 메시지입니다
  if (message.type === 'system' && message.subtype === 'init') {
    sessionId = message.session_id
    console.log(`Session started with ID: ${sessionId}`)
    // 나중에 재개하기 위해 이 ID를 저장할 수 있습니다
  }

  // 다른 메시지 처리...
  console.log(message)
}

// 나중에 저장된 sessionId를 사용하여 재개할 수 있습니다
if (sessionId) {
  const resumedResponse = query({
    prompt: "Continue where we left off",
    options: {
      resume: sessionId
    }
  })
}

세션 재개

import { query } from "@anthropic-ai/claude-agent-sdk"

// 세션 ID를 사용하여 이전 세션 재개
const response = query({
  prompt: "Continue implementing the authentication system from where we left off",
  options: {
    resume: "session-xyz", // 이전 대화의 세션 ID
    model: "claude-opus-4-6",
    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: "Help me design a REST API",
  options: { model: "claude-opus-4-6" }
})

for await (const message of response) {
  if (message.type === 'system' && message.subtype === 'init') {
    sessionId = message.session_id
    console.log(`Original session: ${sessionId}`)
  }
}

// 다른 접근 방식을 시도하기 위해 세션을 포크합니다
const forkedResponse = query({
  prompt: "Now let's redesign this as a GraphQL API instead",
  options: {
    resume: sessionId,
    forkSession: true,  // 새 세션 ID를 생성합니다
    model: "claude-opus-4-6"
  }
})

for await (const message of forkedResponse) {
  if (message.type === 'system' && message.subtype === 'init') {
    console.log(`Forked session: ${message.session_id}`)
    // 이것은 다른 세션 ID가 됩니다
  }
}

// 원래 세션은 변경되지 않으며 여전히 재개할 수 있습니다
const originalContinued = query({
  prompt: "Add authentication to the REST API",
  options: {
    resume: sessionId,
    forkSession: false,  // 원래 세션 계속 (기본값)
    model: "claude-opus-4-6"
  }
})

Was this page helpful?