Agent SDK 세션 외부 저장소
공식 기준: https://code.claude.com/docs/en/agent-sdk/session-storage
기준일: 2026-07-26 · CLI 기준 2.1.220
개요
기본 로컬 세션 파일 대신 외부 저장소에 transcript를 유지하려면 SessionStore 어댑터를 구현합니다. 멀티 인스턴스 앱, 중앙 검색, 규정 보관, 호스트 로컬 디스크에 의존하지 않는 resume에 사용합니다.
핵심 개념
- SessionStore: 세션 메타·메시지 append/read·목록·이름/태그·fork 등 계약
- Dual-write: 로컬 엔진 경로와 외부 mirror를 함께 쓰는 구조
- Best-effort mirror: 외부 쓰기 실패가 메인 세션을 항상 막지는 않을 수 있음
- post-compaction chain:
getSessionMessages는 compaction 이후 체인 반환 - forkSession: 바이트 단위 파일 복사가 아닐 수 있음 — API 의미론 준수
- 서브에이전트 transcript는 부모와 별도 수명
상세
인터페이스 역할
어댑터는 최소한:
- 세션 생성/조회/목록
- 메시지 추가 및 순서 보장 읽기
- (지원 시) rename, tag, fork
- resume에 필요한 id·메타 반환
정확한 메서드 시그니처는 공식 TypeScript/Python 페이지의 SessionStore 정의를 기준으로 구현하세요.
Quick start
- 인터페이스를 만족하는 클래스 작성 (Postgres, S3+DB, Redis 스트림 등)
- SDK 옵션에 store 주입 (언어별 옵션 이름 공식 문서 확인)
- 세션 생성 → 메시지 기록 → 프로세스 재시작 → 동일 id resume 검증
- list/get/rename/tag/fork round-trip 테스트
자체 어댑터 작성 가이드
- 원자성: 부분 transcript 기록 방지 (트랜잭션 또는 immutable append)
- 동시성: 동일 session 동시 resume 정책 명시
- 대용량 tool result: 별도 blob 스토리지 + 포인터
- 암호화·ACL: 테넌트 격리 키
- 관측: mirror 실패 메트릭·알람
참조 구현·검증
공식 reference implementations를 템플릿으로 사용하고, adapter validation 절차로 호환성을 확인합니다.
동작 노트
| 주제 | 내용 |
|---|---|
| Dual-write | 로컬+외부; mirror 실패 시 메인 경로 계속 가능(best-effort) |
| getSessionMessages | compaction 이후 체인 — pre-compact 전문은 별도 아카이브 필요할 수 있음 |
| forkSession | 새 세션 분기, 단순 파일 복사 가정 금지 |
| Subagent transcripts | 별도 경로; 부모 삭제 정책과 정렬 |
| Retention | TTL/GDPR/DSAR는 애플리케이션 책임 |
지원 언어·SDK 버전은 공식 "Supported on" 표를 확인하세요.
체크리스트
- SessionStore 필수 메서드 구현
- resume round-trip 테스트
- dual-write 실패 관측 가능
- compaction·fork·subagent 의미론 반영
- 보존·삭제 정책 문서화