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 예제 - 작동하는 코드 예제