JYP Garden

에이전트 세션 아키텍처 (Agent Session Architecture)

Properties1
tagsconcept, agentic-architecture, knowledge

10 min read

에이전트 세션 아키텍처 (Agent Session Architecture)

AI 에이전트가 대화를 관리하는 구조. “채팅 컨텍스트 = 세션 1개” 원칙으로 채널별로 독립 세션이 운영되며, 컴팩션(자동 압축)으로 컨텍스트 윈도우 한계를 극복한다. 대화 맥락은 세션별로 분리되고, 워크스페이스 파일이 세션 사이의 다리 역할을 한다.

세션의 단위

원칙: 채팅 컨텍스트 = 세션 1개

채팅 컨텍스트세션
Slack 채널a세션 A
Slack 채널b세션 B
Slack 채널a의 스레드 1세션 A-1 (독립!)
Slack 채널a의 스레드 2세션 A-2 (독립!)
Slack DM(닿)메인 세션 (함정: 주제 섞임)
텔레그램 토픽 3세션 T-3
텔레그램 토픽 5세션 T-5
텔레그램 DM메인 세션 (함정: 주제 섞임)

실전 분리 방법: Slack 스레드마다, 텔레그램 토픽마다 독립 세션이 생성된다. “새 작업은 새 스레드/토픽에서”가 황금 규칙. (출처: bbojjak-openclaw-multichannel-session-lesson15)

이 원칙은 Slack·텔레그램·디스코드 등 플랫폼에 무관하게 동일하게 적용된다. (출처: bbojjak-openclaw-session-architecture-lesson06)

세션 컨텍스트 구조

한 번의 API 호출에서 에이전트가 받는 전체 컨텍스트:

시스템 프롬프트 (고정)
  └─ SOUL.md + AGENTS.md + TOOLS.md + USER.md + ...
  └─ 항상 원본 그대로 유지 (컴팩션 영향 없음)

+

세션 대화 히스토리
  └─ 압축된 과거 요약 (오래된 대화)
  └─ 최근 대화 원본 (최신 N턴)

+

현재 메시지

= 전체 컨텍스트 → LLM API 호출 → 응답

핵심: 시스템 프롬프트(에이전트 정체성·규칙)는 항상 원본으로 유지된다. 컨텍스트 압박을 받는 것은 대화 히스토리 부분뿐이다.

컴팩션 메커니즘

컨텍스트 윈도우가 일정 비율(~70%)에 도달하면 자동 발동:

[턴 1~50] → 컨텍스트 70% 도달
    ↓
[컴팩션] → 턴 1~30을 요약문으로 압축
    ↓
[요약 + 턴 31~50 원본] 유지 → 계속 대화 가능
    ↓
[턴 51~80] → 다시 70% 도달 → 재컴팩션
    ↓ 반복

중요: 컴팩션은 세션을 교체하지 않는다. 같은 세션이 유지되면서 내부적으로 오래된 대화를 요약으로 치환한다.

Claude Code auto compact와 비교

항목Claude Code 터미널OpenClaw/장기 세션
압축 원리거의 동일거의 동일
세션 수명터미널 닫으면 종료채널 바인딩으로 장기 유지
재시작 후새 세션 시작채널로 메시지 오면 동일 세션 이어짐
--continue수동 이어가기 가능자동 이어지기

Gateway — 세션 라우팅의 실제 주체

“채팅 컨텍스트 = 세션 1개” 원칙을 실제로 실행하는 주체가 gateway-architecture다. Gateway는 포트 하나에서 모든 채널 메시지를 수신하고, 채널별로 세션을 생성하거나 기존 세션으로 라우팅한다. (출처: bbojjak-openclaw-gateway-architecture-lesson14)

Slack 채널a 메시지 → Gateway → Slack 채널a 세션 / 텔레그램 메시지 → Gateway → 텔레그램 세션

채널 라우팅 — 의도된 분리 설계

┌─────────────────────────────────────┐
│          워크스페이스 (파일)            │
│  AGENTS.md  SOUL.md  memory/        │
│  → 모든 세션이 공유                   │
│                                     │
│  ┌──────┐  ┌──────┐  ┌──────┐      │
│  │세션 A │  │세션 B │  │세션 C │      │
│  │대화맥락│  │대화맥락│  │대화맥락│      │
│  │각각독립│  │각각독립│  │각각독립│      │
│  └──────┘  └──────┘  └──────┘      │
└─────────────────────────────────────┘

세션이 채널별로 분리되는 이유:

  1. 컨텍스트 집중: 다른 성격의 대화(운영 논의 vs 자동화 보고)가 뒤섞이면 컨텍스트가 빠르게 소비됨
  2. 보안·권한: DM 내용이 공개 채널 세션에 포함되면 안 됨
  3. 컴팩션 효율: 세션이 작을수록 컴팩션 발생 빈도가 낮고, 중요 맥락이 더 오래 원본으로 유지됨

파일이 세션 사이의 다리

세션이 분리되어 있어도 “조직의 기억”은 파일로 유지된다:

저장 위치내용접근 범위
memory/ 파일채널 간 공유할 중요 결정·컨텍스트전 세션
AGENTS.md절대 규칙·영구 절차전 세션 (시스템 프롬프트)
SOUL.md정체성·말투전 세션 (시스템 프롬프트)
세션 히스토리해당 채널의 대화 맥락해당 세션만

실전 운영 원칙:

  • 채널 간 공유할 중요 결정 → memory/ 파일에 기록 요청
  • 모든 세션에서 알아야 할 규칙 → AGENTS.md에 추가
  • 대화 맥락 이어가기 → 같은 채널에서 계속 대화

이 구조는 agent-workspace-structure의 파일 시스템과 직접 연결된다.

하트비트와 세션의 관계

heartbeat-mechanism에서 정의한 하트비트(크론잡 기반 주기적 에이전트 호출)도 특정 채널 세션에 바인딩된다. 하트비트가 발동될 때 에이전트는 해당 채널 세션의 히스토리를 컨텍스트로 받는다.

따라서 하트비트 기반 루틴과 채널 대화는 같은 세션 히스토리를 공유한다 — 이것이 하트비트 에이전트가 이전 대화 맥락을 “기억하는” 메커니즘이다.

실전 적용

Tip

세션 구조를 이해하면 에이전트를 더 효율적으로 사용할 수 있다.

  • 맥락 이어가기 → 같은 채널에서 대화
  • 채널 간 정보 공유 → “메모리에 기록해줘” 요청
  • 장기 유지 정보 → AGENTS.md에 추가 (시스템 프롬프트 → 압축 안 됨)

기억 3단계와 세션의 관계

agent-memory-architecture의 기억 3단계 구조와 세션 아키텍처는 직접 연결된다:

기억 단계세션 내 위치컴팩션 영향
1단계: 대화 맥락세션 히스토리컴팩션 대상 (압축 가능)
2단계: 메모리 파일워크스페이스 파일 시스템영향 없음 (파일로 독립)
3단계: 시스템 파일시스템 프롬프트 (고정)영향 없음 (컴팩션 대상 외)

컴팩션이 발동해도 2단계·3단계 기억은 안전하다. (출처: bbojjak-openclaw-memory-architecture-lesson08)

관련 개념

소스

그래프 뷰