Skip to main content
V2 세션 API는 더 이상 지원되지 않습니다. TypeScript Agent SDK 0.3.142는 unstable_v2_createSession, unstable_v2_resumeSession, unstable_v2_prompt 및 SDKSession과 SDKSessionOptions 타입을 제거합니다.마이그레이션하려면 query() API와 이를 허용하는 세션 옵션을 사용하십시오. 다중 턴 대화의 경우 AsyncIterable<SDKUserMessage>를 전달하거나 저장된 세션을 계속하려면 options.resume을 사용하십시오. 이 페이지는 Agent SDK 0.2.x 이전 버전의 코드를 유지 관리하는 경우 참조용으로 유지됩니다.
V2는 비동기 생성기와 yield 조정의 필요성을 제거한 실험적 세션 API였습니다. 턴 전체에서 생성기 상태를 관리하는 대신 각 턴은 별도의 send()/stream() 사이클이었습니다. API 표면은 세 가지 개념으로 축소되었습니다:
  • createSession() / resumeSession(): 대화 시작 또는 계속
  • session.send(): 메시지 전송
  • session.stream(): 응답 받기

설치

Agent SDK 0.2.x는 V2 인터페이스를 포함하는 마지막 버전입니다. 패키지 버전은 0.2.x에서 0.3.142로 직접 점프했으므로, 위의 제거 버전과 아래의 설치 핀은 동일한 경계를 설명합니다. 마지막 V2 호환 릴리스를 설치하려면 주 버전과 부 버전을 고정하십시오:
SDK는 선택적 종속성으로 플랫폼용 네이티브 Claude Code 바이너리를 번들로 제공하므로 대부분의 설치에서 Claude Code를 별도로 설치할 필요가 없습니다. 설치가 필요한 경우는 빠른 시작의 설치 참고를 참조하십시오.

빠른 시작

일회성 프롬프트

세션을 유지할 필요가 없는 간단한 단일 턴 쿼리의 경우 unstable_v2_prompt()를 사용합니다. 이 예제는 수학 질문을 보내고 답변을 기록합니다:

기본 세션

단일 프롬프트를 넘어서는 상호작용의 경우 세션을 생성합니다. V2는 전송과 스트리밍을 별개의 단계로 분리합니다:
  • send()는 메시지를 전달합니다
  • stream()은 응답을 스트리밍합니다
이러한 명시적 분리를 통해 턴 사이에 로직을 추가하기가 더 쉬워집니다(예: 후속 메시지를 보내기 전에 응답 처리). 아래 예제는 세션을 생성하고, Claude에 “Hello!”를 보내고, 텍스트 응답을 출력합니다. 블록이 종료될 때 세션을 자동으로 닫기 위해 await using(TypeScript 5.2+)을 사용합니다. session.close()를 수동으로 호출할 수도 있습니다.

다중 턴 대화

세션은 여러 교환 전체에서 컨텍스트를 유지합니다. 대화를 계속하려면 동일한 세션에서 send()를 다시 호출합니다. Claude는 이전 턴을 기억합니다. 이 예제는 수학 질문을 한 다음 이전 답변을 참조하는 후속 질문을 합니다:

세션 재개

이전 상호작용에서 세션 ID가 있는 경우 나중에 재개할 수 있습니다. 이는 장기 실행 워크플로우나 애플리케이션 재시작 전체에서 대화를 유지해야 할 때 유용합니다. 이 예제는 세션을 생성하고, ID를 저장하고, 닫은 다음 대화를 재개합니다:

정리

세션은 수동으로 닫거나 await using을 사용하여 자동으로 닫을 수 있습니다. 이는 자동 리소스 정리를 위한 TypeScript 5.2+ 기능입니다. 이전 TypeScript 버전을 사용 중이거나 호환성 문제가 발생하면 대신 수동 정리를 사용합니다. 아래 예제는 정리 패턴만 보여주며 메시지를 보내지 않으므로 실행해도 출력이 없습니다. 자동 정리 (TypeScript 5.2+):
수동 정리:

API 참조

unstable_v2_createSession()

다중 턴 대화를 위한 새 세션을 생성합니다.

unstable_v2_resumeSession()

ID로 기존 세션을 재개합니다.

unstable_v2_prompt()

단일 턴 쿼리를 위한 일회성 편의 함수입니다.

SDKSession 인터페이스

기능 가용성

V2 세션 API는 모든 V1 기능을 지원하지 않습니다. 다음은 V1 SDK가 필요합니다:
  • 세션 포킹 (forkSession 옵션)
  • 일부 고급 스트리밍 입력 패턴

참고 항목