# 세션 추적 형식

Claude Code, Codex, Pi, Hermes Agent, Factory Droid의 Agent traces는 기본적으로 지원됩니다([Agent Traces](./agent-traces) 참고). 자체적으로 harness를 구축한 경우, 아래에서 설명하는 **Session Trace Simple Format (STS-Format)**으로 세션을 작성하면 동일한 뷰어에서 렌더링할 수 있습니다.

**Session Trace Simple Format (STS-Format)**은 Hugging Face Hub가 감지하여 트레이스 뷰어에서 렌더링하는 [JSONL](https://jsonlines.org) 파일(1줄에 JSON 객체 1개)입니다. 헤더 줄을 시작으로 메시지 줄들이 이어지는 단일 에이전트/채팅 세션을 캡처합니다.

## 1. 세션 헤더 (첫 번째 줄)

```json
{ "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. 메시지(그 후의 모든 줄)

각 줄은 봉투의 메시지 하나입니다:

```json
{ "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"`을 가진 메시지입니다. 뷰어는 각 결과를 해당 결과를 생성한 호출 옆에 배치합니다.

### 예시

```jsonl
{"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](https://huggingface.co/datasets) 또는 [Storage Bucket](./storage-buckets)에 업로드하여 trace viewer에서 열 수 있습니다.

## 대안: Pi의 세션 형식

위의 형식을 채택하지 않으려면, Hub가 이미 지원하는 **Pi의 세션 형식**([session-format.md](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/session-format.md))을 출력할 수 있습니다. 이 경우, Hub가 트레이스를 해당 harness로 귀속할 수 있도록 Pi의 세션 헤더 줄에도 `harness: "..."` 필드를 추가하세요.

