# Формат трассировок сессий

Трассировки агентов из Claude Code, Codex, Pi, Hermes Agent и Factory Droid поддерживаются из коробки (см. [Трассировки агентов](./agent-traces)). Если вы разрабатываете собственный harness, вы можете обеспечить отображение его сессий в том же просмотрщике, записывая их в формате **Session Trace Simple Format (STS-Format)**, описанном ниже.

Формат **Session Trace Simple Format (STS-Format)** представляет собой файл [JSONL](https://jsonlines.org) (один объект JSON на строку), который Hugging Face Hub определяет и отображает в своем просмотрщике трассировок. Он фиксирует одну сессию агента/чата в виде заголовочной строки, за которой следуют строки с сообщениями.

## 1. Заголовок сессии (первая строка)

```json
{ "type": "session", "harness": "my-agent", "id": "b1a2c3", "name": "Implementing a new API" }
```

| поле     | обязательный | заметки                                             |
| --------- | -------- | ------------------------------------------------- |
| `type`    | да      | должен быть `"session"`                               |
| `harness` | да      | **идентификатор обвязки**, создавшей трассировку |
| `id`      | да      | уникальный идентификатор сессии                                 |
| `name`    | нет       | читаемое человеком название                              |
| …         | нет       | допускается и игнорируется любая дополнительная метаданные         |

`harness` — ключевое поле: это **идентификатор harness**, который сообщает Hub, какой рендерер, иконку и метку использовать для сессии. В настоящее время распознаются следующие идентификаторы: `llama.app`. Добавить новый идентификатор harness здесь очень просто.

> Создаёте собственный harness? Напишите нам, и мы добавим для него иконку и подпись, чтобы ваши сессии отображались с вашим брендом.

## 2. Сообщения (каждая следующая строка)

Каждая строка представляет собой одно сообщение в конверте:

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

Объект `message`:

| поле              | обязательный | заметки                                                                                                  |
| ------------------ | -------- | ------------------------------------------------------------------------------------------------------ |
| `role`             | да      | `"user"` · `"assistant"` · `"system"` · `"tool"`                                                       |
| `content`          | да      | текст (может быть пустым)                                                                                    |
| `reasoningContent` | нет       | рассуждения модели, отображаемые в отдельном блоке размышлений                                                    |
| `toolCalls`        | нет       | вызовы инструментов ассистента: `[{ "id", "function": { "name", "arguments" } }]` (`arguments` — это строка JSON) |
| `toolCallId`       | нет       | в сообщении `role: "tool"`, связывает результат с `toolCalls[].id`, на который он отвечает                       |
| `timestamp`        | нет       | миллисекунды эпохи                                                                                     |
| `model`            | нет       | имя модели                                                                                             |

Результаты инструментов — это сообщения с `role: "tool"`, содержащие `toolCallId`; просмотрщик размещает каждый результат рядом с вызовом, который его сгенерировал.

### Пример

```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), чтобы открыть его в трассировщике.

## Альтернатива: формат сессий Pi

Если вы не хотите использовать описанную выше структуру, вы можете выводить **формат сессий Pi** ([session-format.md](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/session-format.md)), который уже поддерживается Hub. В этом случае также добавьте поле `harness: "..."` в строку заголовка сессии Pi, чтобы Hub мог атрибутировать трассировку вашему harness.