메인 콘텐츠로 건너뛰기
V2 세션 API는 더 이상 지원되지 않습니다. TypeScript Agent SDK 0.3.142는 unstable_v2_createSession, unstable_v2_resumeSession, unstable_v2_promptSDKSessionSDKSessionOptions 타입을 제거합니다.마이그레이션하려면 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 옵션)
  • 일부 고급 스트리밍 입력 패턴

참고 항목