세션 관리와 상태 지속성

에이전트가 한 번의 작업으로 끝나지 않고 어제 하던 대화를 오늘 이어 가거나, 같은 출발점에서 여러 갈래로 실험하려면 세션을 다룰 줄 알아야 한다. Agent SDK에서 세션은 대화 이력과 상태를 담는 단위이며, ClaudeAgentOptions의 몇몇 필드가 그 생명 주기를 결정한다. CCA-F 시험은 이 필드들의 상호 배타 규칙을 끈질기게 묻는다. 문법보다 "어떤 조합이 허용되고 어떤 조합이 충돌하는가"가 핵심이다.

세션을 이어 가는 방법은 두 가지다. 첫째, resume에 세션 ID를 주면 그 세션의 대화 이력을 불러와 정확히 그 지점부터 이어 간다. 둘째, continue_conversation을 True로 두면 현재 작업 디렉터리에서 가장 최근 대화를 자동으로 이어 간다. 여기서 가장 중요한 규칙은 이 둘이 상호 배타라는 점이다. resume과 continue_conversation을 동시에 쓸 수 없다. 특정 세션을 콕 집어 재개하려면 resume을, 마지막 대화를 별다른 ID 없이 이어 가려면 continue_conversation을 쓴다.

# examples/resume_session.pyfrom claude_agent_sdk import query, ClaudeAgentOptionsoptions = ClaudeAgentOptions(    resume="550e8400-e29b-41d4-a716-446655440000",    model="claude-opus-4-8",)async for message in query(prompt="아까 만들던 작업을 마저 진행해 줘", options=options):    print(message)

session_id는 자동 생성되는 ID 대신 직접 지정한 UUID를 세션 식별자로 쓰게 한다. 다만 제약이 있다. session_id는 continue_conversation이나 resume과 함께 쓸 수 없으며, 예외는 fork_session을 함께 켰을 때뿐이다. 이 조건을 뒤집어 놓고 정상 동작한다고 주장하는 보기가 전형적인 함정이다.

fork_session은 세션을 분기시킨다. resume과 함께 fork_session을 True로 두면, 기존 세션을 이어 가는 대신 그 이력을 물려받은 새로운 세션 ID로 갈라져 나온다. 같은 출발점에서 서로 다른 방향으로 여러 실험을 돌리되 원본 세션을 더럽히지 않으려는 상황이 정답 시나리오다. 분기 후에는 원본과 분기본이 독립적으로 진행되므로, A안과 B안을 비교하는 워크플로우에 적합하다.

# examples/fork_session.pyfrom claude_agent_sdk import query, ClaudeAgentOptionsoptions = ClaudeAgentOptions(    resume="previous-session-id",    fork_session=True,    model="claude-opus-4-8",)async for message in query(prompt="이 시점에서 다른 접근을 시도해 보자", options=options):    print(message)

대화 이력을 프로세스 바깥에 오래 보관하려면 session_store를 쓴다. 기본적으로 세션은 로컬에 저장되지만, S3 같은 외부 저장소를 session_store로 연결하면 서버 재시작이나 인스턴스 교체 후에도 resume으로 같은 대화를 복원할 수 있다. 저장 시점은 session_store_flush로 조절하며, 기본값인 배치 방식은 성능을 위해 묶어서 기록하고 필요하면 더 즉시적인 방식으로 바꿀 수 있다. 분산 환경이나 무상태 서버에서 대화 연속성을 보장해야 하는 시나리오가 session_store의 출제 포인트다. 외부 저장소를 쓸 때도 재개의 진입점은 여전히 resume에 세션 ID를 넘기는 동일한 방식임을 기억해야 한다.

정리하면, 세션 전략은 네 가지 의도로 나뉜다. 마지막 대화를 그냥 이어 가면 continue_conversation, 특정 세션을 지정 재개하면 resume, 같은 출발점에서 갈라져 실험하면 resume과 fork_session, 프로세스 밖에 영속 보관하면 session_store다. 시험은 이 의도와 필드를 짝짓되 상호 배타 규칙을 위반한 보기를 섞어 출제한다.

정리

• resume은 세션 ID로 특정 세션을 재개하고, continue_conversation은 현재 디렉터리의 최근 대화를 이어 간다. 이 둘은 상호 배타다.
• session_id는 직접 지정한 UUID를 쓰게 하며, continue_conversation이나 resume과는 fork_session을 함께 켤 때만 병행할 수 있다.
• fork_session은 resume과 함께 쓰면 이력을 물려받은 새 세션 ID로 분기해, 원본을 보존한 채 여러 갈래 실험을 가능하게 한다.
• session_store는 S3 같은 외부 저장소에 대화 이력을 영속 보관해 무상태 서버에서도 resume으로 복원하게 하며, session_store_flush로 기록 시점을 조절한다.
• 세션 의도는 최근 대화 이어가기, 지정 세션 재개, 분기 실험, 외부 영속화 네 가지로 나뉘며 시험은 상호 배타 규칙 위반을 함정으로 낸다.