Hub documentation
세션 추적 형식
세션 추적 형식
Claude Code, Codex, Pi, Hermes Agent, Factory Droid의 Agent traces는 기본적으로 지원됩니다(Agent Traces 참고). 자체적으로 harness를 구축한 경우, 아래에서 설명하는 Session Trace Simple Format (STS-Format)으로 세션을 작성하면 동일한 뷰어에서 렌더링할 수 있습니다.
Session Trace Simple Format (STS-Format)은 Hugging Face Hub가 감지하여 트레이스 뷰어에서 렌더링하는 JSONL 파일(1줄에 JSON 객체 1개)입니다. 헤더 줄을 시작으로 메시지 줄들이 이어지는 단일 에이전트/채팅 세션을 캡처합니다.
1. 세션 헤더 (첫 번째 줄)
{ "type": "session", "harness": "my-agent", "id": "b1a2c3", "name": "Implementing a new API" }| 필드 | 필수 | 노트 |
|---|---|---|
type | 네 | "session"이어야 합니다 |
harness | 네 | 를 생성한 하네스의 ID |
id | 네 | 고유한 세션 ID |
name | 아니요 | 사람이 읽을 수 있는 제목 |
| … | 아니요 | 추가 메타데이터는 허용되며 무시됩니다 |
harness는 핵심 필드입니다. harness의 id이며, Hub가 세션에 사용할 렌더러, 아이콘, 라벨을 결정합니다. 현재 인식되는 id: llama.app. 여기서 새로운 harness 식별자를 추가하는 것은 매우 쉽습니다.
직접 harness를 구축하고 계신가요? 알려주시면 해당 harness의 아이콘과 라벨을 추가하여 세션이 브랜드에 맞게 렌더링되도록 하겠습니다.
2. 메시지(그 후의 모든 줄)
각 줄은 봉투의 메시지 하나입니다:
{ "type": "message", "message": { "role": "assistant", "content": "…" } }message 객체:
| 필드 | 필수 | 노트 |
|---|---|---|
role | 네 | "user" · "assistant" · "system" · "tool" |
content | 네 | 텍스트 (비어 있을 수 있음) |
reasoningContent | 아니요 | model reasoning, 별도의 thinking 블록으로 표시 |
toolCalls | 아니요 | assistant tool calls: [{ "id", "function": { "name", "arguments" } }] (arguments은 JSON 문자열입니다) |
toolCallId | 아니요 | role: "tool" 메시지에서 결과를 응답하는 toolCalls[].id에 연결합니다 |
timestamp | 아니요 | epoch 밀리초 |
model | 아니요 | 모델 이름 |
Tool results는 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에 업로드하여 trace viewer에서 열 수 있습니다.
대안: Pi의 세션 형식
위 형식을 채택하지 않으려면, Hub가 이미 지원하는 Pi의 세션 형식(session-format.md)을 출력할 수 있습니다. 이 경우, Hub가 트레이스를 해당 harness로 귀속할 수 있도록 Pi의 세션 헤더 줄에도 harness: "..." 필드를 추가하세요.