세션 트레이스 형식

세션 트레이스 형식 (Session Traces Format)

Claude Code, Codex, Pi의 에이전트 트레이스는 기본으로 지원돼요 (Agent Traces 참고). 자체 하네스(harness)를 만들었다면 아래에 설명한 **Session Trace Simple Format (STS-Format)**으로 작성해서 그 세션을 같은 뷰어에서 렌더링할 수 있게 할 수 있어요.

**Session Trace Simple Format (STS-Format)**은 Hugging Face Hub가 감지해 트레이스 뷰어에서 렌더링하는 JSONL 파일(줄마다 JSON 객체 하나)이에요. 단일 에이전트/채팅 세션을 헤더 줄 한 줄과 메시지 줄들로 담아요.

출처: 문서

본문

1. 세션 헤더 (첫 줄)

{ "type": "session", "harness": "my-agent", "id": "b1a2c3", "name": "Implementing a new API" }
필드 필수 참고
type 예 "session"이어야 함
harness 예 트레이스를 만든 하네스의 id
id 예 고유 세션 id
name 아니오 사람이 읽을 수 있는 제목
… 아니오 추가 메타데이터는 허용되고 무시됨

harness가 핵심 필드예요: 하네스의 id이며, 세션에 어떤 렌더러, 아이콘, 라벨을 사용할지 Hub에 알려줘요. 현재 인식되는 id: llama.app. 여기에 새 하네스 식별자를 추가하는 건 아주 쉬워요.

나만의 하네스를 만드는 중? 우리에게 연락하면 아이콘과 라벨을 추가해 세션이 당신의 브랜딩으로 렌더링되게 해드려요.

2. 메시지 (이후 모든 줄)

각 줄은 봉투(envelope) 속의 메시지 하나예요:

{ "type": "message", "message": { "role": "assistant", "content": "…" } }

message 객체:

필드 필수 참고
role 예 "user" · "assistant" · "system" · "tool"
content 예 텍스트 (비어 있을 수 있음)
reasoningContent 아니오 모델 추론, 별도의 사고(thinking) 블록으로 표시됨
toolCalls 아니오 어시스턴트 도구 호출: [{ "id", "function": { "name", "arguments" } }] (arguments는 JSON 문자열)
toolCallId 아니오 role: "tool" 메시지에서 결과를 그것이 답하는 toolCalls[].id와 연결함
timestamp 아니오 epoch 밀리초
model 아니오 모델 이름

도구 결과는 toolCallId를 가진 role: "tool" 메시지예요; 뷰어는 각 결과를 그것을 만든 호출 옆에 이어 붙여요.

예시

{"type":"session","harness":"my-agent","id":"abc123","name":"what time is it"}
{"type":"message","message":{"role":"user","content":"what time is it?"}}
{"type":"message","message":{"role":"assistant","content":"","toolCalls":[{"id":"t1","function":{"name":"get_time","arguments":"{}"}}]}}
{"type":"message","message":{"role":"tool","toolCallId":"t1","content":"2026-07-01T15:00:00Z"}}
{"type":"message","message":{"role":"assistant","content":"it is 15:00 UTC"}}

결과 .jsonl을 Dataset이나 Storage Bucket에 업로드하면 트레이스 뷰어에서 열 수 있어요.

대안: Pi의 세션 형식

위 형태를 채택하고 싶지 않다면 Hub가 이미 지원하는 Pi의 세션 형식(session-format.md)을 만들 수 있어요. 그 경우 Pi의 세션 헤더 줄에도 harness: "..." 필드를 추가해서 Hub가 트레이스를 당신의 하네스에 귀속시킬 수 있게 해요.

더 알아보기 (Learn more)

  • STS-Format은 헤더 줄 + 메시지 줄로 된 JSONL 파일이에요.
  • harness id가 세션 렌더러·아이콘을 결정해요.
  • Agent Traces 문서에서 에이전트 트레이스 전반을 확인해 보세요.