Hub documentation
Формат трассировок сессий
Формат трассировок сессий
Трассировки агентов из Claude Code, Codex, Pi, Hermes Agent и Factory Droid поддерживаются из коробки (см. Трассировки агентов). Если вы разрабатываете собственный harness, вы можете обеспечить отображение его сессий в том же просмотрщике, записывая их в формате Session Trace Simple Format (STS-Format), описанном ниже.
Формат Session Trace Simple Format (STS-Format) представляет собой файл JSONL (один объект JSON на строку), который Hugging Face Hub определяет и отображает в своем просмотрщике трассировок. Он фиксирует одну сессию агента/чата в виде заголовочной строки, за которой следуют строки с сообщениями.
1. Заголовок сессии (первая строка)
{ "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. Сообщения (каждая следующая строка)
Каждая строка представляет собой одно сообщение в конверте:
{ "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; просмотрщик размещает каждый результат рядом с вызовом, который его сгенерировал.
Пример
{"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
Если вы не хотите использовать описанную выше структуру, вы можете выводить формат сессий Pi (session-format.md), который уже поддерживается Hub. В этом случае также добавьте поле harness: "..." в строку заголовка сессии Pi, чтобы Hub мог атрибутировать трассировку вашему harness.