세션

세션 (Sessions)

AI 에이전트나 복잡한 워크플로는 한 작업을 끝내기 위해 여러 번의 LLM 호출, 벡터 DB 질의, 툴 호출을 이어서 하곤 해요. 세션은 이런 관련 요청들을 하나로 묶어, 최초 사용자 입력부터 최종 응답까지 에이전트 전체 흐름을 한 화면에서 추적할 수 있게 해 줘요. 개별 요청 단위가 아니라 상호작용 시퀀스 전체를 보고 싶을 때 유용해요.

출처: Helicone 공식 문서 — Sessions

왜 세션인가요

AI 에이전트 흐름 디버깅 — 요청부터 최종 응답까지 전체 워크플로를 한 화면에서 보아요.
다단계 대화 추적 — 챗봇 상호작용과 복잡한 작업의 완전한 흐름을 재구성해요.
성능 분석 — 개별 요청이 아니라 전체 상호작용 시퀀스의 결과물을 측정해요.

시작하기

세션 헤더 추가 — LLM 요청에 다음 세 헤더를 포함해요.

{
  "Helicone-Session-Id": "unique-session-id",
  "Helicone-Session-Path": "/trace-path", 
  "Helicone-Session-Name": "Session Name"
}

경로 구조화 — 경로 문법으로 부모-자식 관계를 표현해요.

"/abstract"                    // Top-level trace
"/abstract/outline"           // Child trace
"/abstract/outline/lesson-1"  // Grandchild trace

요청 실행 — 세션 헤더를 포함해 요청을 보내요.

const response = await client.chat.completions.create(
  { 
    messages: [{ role: "user", content: "Hello" }], 
    model: "gpt-4o-mini" 
  },
  {
    headers: {
      "Helicone-Session-Id": sessionId,
      "Helicone-Session-Path": "/greeting",
      "Helicone-Session-Name": "User Conversation"
    }
  }
);

세션이 추적할 수 있는 것

세션은 AI 워크플로의 모든 요청 유형을 묶을 수 있어요.

LLM 호출 — OpenAI, Anthropic 등 모델 요청
벡터 DB 질의 — 임베딩, 유사도 검색, 검색
툴 호출 — 함수 실행, API 호출, 커스텀 툴
로깅된 모든 요청 — Helicone 로깅을 통과하는 모든 것

이렇게 하면 LLM 상호작용뿐 아니라 AI 에이전트의 전체 행동을 볼 수 있어요.

세션 ID

세션 ID는 관련 요청을 모두 묶는 고유 식별자예요. 대화 스레드 ID라고 생각하면 돼요.

권장: UUID — 예: 550e8400-e29b-41d4-a716-446655440000
고유 문자열 — 예: user_123_conversation_456

ID가 같으면 대시보드에서 요청이 한 세션으로 묶이고, 다르면 별도 세션으로 분리돼요. 관련된 요청이라도 ID를 재사용하면 서로 다른 워크플로의 요청이 섞일 수 있으니, 대화별로 고유 UUID를 쓰는 걸 권장해요.

세션 경로

경로는 세션 안에서 요청들의 계층 구조를 만들고, 요청들이 서로 어떻게 관련되는지 보여줘요.

경로 이름 구분 철학: 세션 경로는 시간 순서가 아니라 개념적 그룹으로 생각하는 게 좋아요. 같은 경로를 가진 요청들은 발생 시점이 달라도 같은 '유형'의 작업이에요. 예를 들어 코드 리뷰 에이전트에서 모든 "보안 검사" 요청은 분석 초반이든 후반이든 같은 경로(/review/security)를 쓰게 해요. 그러면 지속 시간 분포 차트에서 같은 색으로 표시돼, 보안 검사가 보통 언제 일어나고 얼마나 걸리는지 패턴을 볼 수 있어요.

경로 구조 규칙:

/(슬래시)로 시작해요.
/로 레벨을 구분해요: /parent/child/grandchild
이름은 설명적으로: /analyze_request/fetch_data/process_results
시간이 아니라 기능별로 그룹화 — 같은 개념 작업 = 같은 경로

계층 예시:

"/conversation"                    // Root level
"/conversation/initial_question"   // Child of conversation  
"/conversation/followup"          // Another child of conversation
"/conversation/followup/clarify"  // Child of followup

경로 디자인 패턴:

워크플로 패턴(AI 에이전트): /task, /task/research, /task/research/web_search, /task/generate
대화 패턴(챗봇): /session, /session/question_1, /session/answer_1, /session/question_2
파이프라인 패턴(데이터 처리): /process, /process/extract, /process/transform, /process/load

세션 이름

세션 이름은 대시보드에서 비슷한 유형의 세션을 쉽게 필터·정리하게 해 주는 상위 그룹이에요. 예를 들어 "Customer Support", "Content Generation", "Trip Planning Agent"처럼. 용도는 빠른 필터링, 상위 조직화, 같은 세션 유형 간 메트릭 비교예요.

설정 참고 — 필수 헤더

헤더	설명
`Helicone-Session-Id`	세션의 고유 식별자. 충돌 방지를 위해 UUID 사용 권장. 예: `"550e8400-e29b-41d4-a716-446655440000"`
`Helicone-Session-Path`	`/` 문법으로 추적 계층을 나타내는 경로. 부모-자식 관계 표현. 예: `"/abstract"` 또는 `"/parent/child"`
`Helicone-Session-Name`	세션 유형의 사람이 읽을 수 있는 이름. 비슷한 워크플로를 그룹화. 예: `"Course Plan"` 또는 `"Customer Support"`

일반 패턴

코드 생성 어시스턴트 — 하나의 세션 ID를 공유하면서 경로를 세분화해 흐름을 추적해요. 초기 기능 요청(/request) → 검증·오류 처리 요청(/request/validation) → TypeScript 변환(/request/validation/typescript)으로 경로가 깊어져요. Python에서는 extra_headers에 같은 세션 헤더를 실어 보내면 돼요.

PR 리뷰 — PR 분석(/analysis) → 보안 검사(/analysis/security) → 리뷰 코멘트 생성(/analysis/security/comments)처럼 분석 단계별로 경로를 나눠요.

API 문서 생성기 — 엔드포인트 분석(/analyze) → OpenAPI 스펙 생성(/analyze/openapi) → 사용 예시 작성(/analyze/openapi/examples) 순으로 경로를 확장해요.

전체 구현 예시는 Helicone GitHub 저장소의 세션 예제에서 확인할 수 있어요.

더 알아보기

벡터 DB 로깅 — LLM 호출과 함께 벡터 DB 질의 추적
툴 호출 로깅 — 에이전트 워크플로 내 툴·함수 실행 모니터링
커스텀 프로퍼티 — 세션 내 개별 요청에 메타데이터 추가