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()은 응답을 스트리밍합니다
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옵션) - 일부 고급 스트리밍 입력 패턴
참고 항목
- TypeScript SDK 참조 (V1) - 전체 V1 SDK 문서
- SDK 개요 - 일반 SDK 개념
- GitHub의 V2 예제 - 작동하는 코드 예제