세션

세션 (Sessions)

Docker Agent가 대화를 저장하고, 실행 전반에 걸쳐 재개하며, 토큰 비용을 추적하는 방법을 알아봐요.

출처: 문서

본문

세션이란 무엇인가? (What a Session Is)

모든 docker agent run 은 세션을 만들거나 재개해요: 그것은 대화의 기록이며, 모든 메시지, 도구 호출, 하위 에이전트 실행, 비용을 포함해요. 세션은 /undo, /sessions, --session <id>, 비용 추적을 가능하게 만드는 것이에요 — 에이전트 자체는 실행 간에 무상태(stateless)지만 세션은 그렇지 않아요.

세션은 콘텐츠(첫 메시지가 추가될 때)를 가진 뒤에만 디스크에 유지되므로, 아무것도 보내기 전에 취소한 실행은 빈 세션을 남기지 않아요.

세션이 저장되는 위치 (Where Sessions Are Stored)

세션은 데이터 디렉터리(기본 ~/.cagent) 아래의 SQLite 데이터베이스 session.db 에 살아요:

$ ls ~/.cagent/session.db

위치를 -s / --session-db 로, 또는 데이터 디렉터리 자체를 --data-dir 로 재정의해요:

# Use a project-local session database instead of the global one
$ docker agent run agent.yaml --session-db ./sessions.db

세션 재개 (Resuming a Session)

새 대화를 시작하는 대신 이전 대화를 계속하려면 --session <id> 를 전달해요:

# Resume by explicit session ID
$ docker agent run agent.yaml --session 3f9c1e2a-...

# Resume the most recently created session
$ docker agent run agent.yaml --session -1

# Resume the session created before that one
$ docker agent run agent.yaml --session -2

--session 은 두 종류의 참조를 받아요:

상대 오프셋(-1, -2, …): 세션은 생성 시간 순으로 정렬되며, 가장 최근 것이 처음 — -1 은 가장 최근에 생성된 세션, -2 는 그 이전 것, 이런 식이에요. 이것은 생성 순서이지 마지막 사용 순서가 아니에요: --session <id> 로 이전 세션을 재개해도 그것이 새로운 -1 이 되지 않아요; 다음 -1 은 여전히 가장 최근에 생성된 세션으로 해석돼요. 일치하는 세션이 없는 상대 오프셋(예: 빈 데이터베이스에서 -1)은 에러예요.
명시적 ID: 그 ID의 세션이 이미 있으면 재개돼요. 아직 없으면 Docker Agent가 실패 대신 그 ID로 세션을 만들어요. 이렇게 하면 슈퍼바이저(예: 보드나 스크립트)가 세션 ID를 미리 선택해 실행 전반에 걸쳐 재사용할 수 있어요 — 첫 실행이 세션을 만들고 이후 실행이 재개해요.

읽기 전용 세션 (Read-Only Sessions)

--session-read-only 를 추가하면 새 메시지를 보내지 않고 세션을 열어 보기만 해요 — 지난 대화를 실수로 계속하지 않고 검토하는 데 유용해요:

$ docker agent run agent.yaml --session -1 --session-read-only

--session-read-only 는 TUI가 필요해요: --exec 와는 결합할 수 없어요, 하나 없이는 표시할 것이 없기 때문이에요.

TUI에서 세션 탐색 (Browsing Sessions in the TUI)

/sessions 를 눌러 세션 브라우저를 열어요: 지난 대화를 검색·필터링하고, 현재 작업 디렉터리에서 시작된 것("This workspace")과 다른 곳에서 시작된 것("Other locations")을 구분하고, Enter로 하나를 복원해요. 세션을 복원하면 원래 작업 디렉터리에서 다시 열려요. 전체 세션 브라우저 및 세션 제목 기능(별표, 과거 메시지 편집으로 분기 등)은 Terminal UI 문서의 Session Management 참고.

탭 (Tabs)

Ctrl+T 는 현재 세션 옆에 추가 에이전트 세션을 실행하는 새 탭을 열고, Ctrl+N / Ctrl+P 는 탭 사이를 순환하며 Ctrl+W 는 현재 탭을 닫아요. 기본적으로 탭은 다음에 TUI를 실행할 때 복원되지 않아요. 사용자 구성에서 restore_tabs: true 를 설정하면 다음 실행에서 같은 탭(및 세션)을 다시 엽니다:

# ~/.config/cagent/config.yaml
settings:
  restore_tabs: true

세션 제목 (Session Titles)

Docker Agent는 첫 메시지에서 각 세션의 짧은 제목을 자동 생성하며, 에이전트 자신의 모델에 대한 일회성 호출을 사용해요. 모델 정의에서 title_model 로 그 호출을 더 작고 저렴한 모델에 지정할 수 있어요:

# examples/title_model.yaml
models:
  primary:
    provider: anthropic
    model: claude-sonnet-4-5
    # Generate session titles with the cheaper Haiku model instead of Sonnet.
    title_model: fast
  fast:
    provider: anthropic
    model: claude-haiku-4-5

agents:
  root:
    model: primary
    description: An assistant that generates session titles with a cheaper model.
    instruction: You are a helpful assistant.

title_model 이 생략되면 제목 생성은 에이전트 자신의 모델을 재사용해요. TUI 안에서 /title 로 제목을 설정하거나 재생성해요(재생성은 처음뿐 아니라 세션의 모든 사용자 메시지를 보내요 — Session Title Editing 참고), 또는 세션을 시작하지 않고 명령줄에서 생성해요:

$ docker agent debug title agent.yaml "How do I configure a fallback model?"

자세한 내용은 docker agent debug title 참고.

사용량 및 비용 추적 (Usage & Cost Tracking)

모든 추적된 모델 호출 — 메인 대화 턴과 압축 호출 — 은 세션의 누적 입력/출력 토큰 수와 비용을 갱신해요. TUI에서 /cost 로 언제든 확인하거나, 모델의 호출이 세지 않길 원하면(예: 무료 로컬 모델) 모델별로 track_usage: false 로 추적을 비활성화해요. 자동 세션 제목 생성 같은 런타임이 당신 대신 만드는 보조 일회성 호출은 모델을 직접 호출하며 이 총액에 포함되지 않아요.

비용은 기본적으로 models.dev 가격 카탈로그에서 계산돼요. 카탈로그가 모르는 커스텀 엔드포인트, 비공개 배포, 협상된 엔터프라이즈 요율의 경우 모델의 cost: 블록으로 가격을 명시적으로 선언해요:

# examples/custom-pricing.yaml
models:
  internal-gpt:
    provider: internal-llm
    model: gpt-4o
    cost:
      input: 1.25 # USD per 1M input tokens
      output: 5.00 # USD per 1M output tokens
      cache_read: 0.125 # USD per 1M cached input tokens
      cache_write: 1.5625 # USD per 1M cache-write tokens

모두 0인 cost: 테이블은 "가격 매겨졌고 무료"를 뜻해요 — 아예 cost: 가 없는 모델(카탈로그로 폴백하며, 카탈로그가 모르는 모델은 $0 청구)과는 구별돼요.

Note 비용은 절대 감소하지 않음 (Cost never decreases) 세션의 누적 비용은 추적된 모델 호출마다 갱신되는 실행 총액이에요 — 위에서 설명한 메인 대화 턴과 압축 호출과 같아요. 대화를 압축하면(수동 /compact 또는 자동 — Agent Config 참조의 session_compaction / compaction_threshold 필드 참고) 모델로 다시 보내는 메시지 기록이 재구성되지만, 이 실행 총액에는 절대 닿지 않아요. 자동 세션 제목 생성 같은 보조 일회성 호출은 추적되지 않으며 이 총액에 반영되지 않아요: /cost 는 세션의 추적된 호출이 쓴 모든 것을 다루지, 런타임이 당신 대신 만드는 말 그대로의 모든 모델 호출은 다루지 않아요.

Worktree로 재개 (Resuming Into a Worktree)

--worktree 실행 중에 만든 세션은 사용한 worktree를 기억해요. --session 으로 재개하면 같은 worktree 디렉터리와 브랜치에 자동으로 다시 연결돼요 — --worktree 를 다시 전달할 필요가 없어요. 전체 worktree 수명 주기는 CLI reference의 --worktree 참고.

세션