Hub documentation
会话跟踪格式
会话跟踪格式
Claude Code、Codex、Pi、Hermes Agent 和 Factory Droid 的 Agent traces 开箱即用（参见 Agent Traces）。如果您自行构建 harness，可以按照下文描述的 Session Trace Simple Format (STS-Format) 编写其会话，使其在相同的查看器中渲染。
会话跟踪简单格式（STS-Format） 是一种 JSONL 文件（每行一个 JSON 对象），Hugging Face Hub 会检测该文件并在其跟踪查看器中渲染。它通过一个头部行后跟若干消息行来捕获单个智能体/聊天会话。
1. 会话标题（第一行）
{ "type": "session", "harness": "my-agent", "id": "b1a2c3", "name": "Implementing a new API" }| field | 必需 | notes |
|---|---|---|
type | 是的 | 必须为 "session" |
harness | 是的 | 生成该跟踪记录的harness 的 id |
id | 是的 | 唯一的会话 ID |
name | no | 人类可读的标题 |
| … | no | 任何额外的元数据都是允许的，但会被忽略 |
harness 是关键字段：它是 harness 的 id，用于告知 Hub 该为会话使用哪个渲染器、图标和标签。当前已识别的 id 为：llama.app。在此处添加新的 harness 标识符非常容易。
正在构建自己的测试框架？请通知我们，我们将为其添加图标和标签，以便您的会话以您的品牌样式呈现。
2. 消息（后续每一行）
每一行都是信封中的一条消息：
{ "type": "message", "message": { "role": "assistant", "content": "…" } }message 对象：
| field | 必需 | notes |
|---|---|---|
role | 是的 | "user" · "assistant" · "system" · "tool" |
content | 是的 | 文本（可以为空） |
reasoningContent | no | 模型推理，显示为独立的思考块 |
toolCalls | no | 助手工具调用：[{ "id", "function": { "name", "arguments" } }]（arguments 是一个 JSON 字符串） |
toolCallId | no | 在 role: "tool" 消息上，将结果与其所响应的 toolCalls[].id 关联起来 |
timestamp | no | epoch 毫秒 |
model | no | 模型名称 |
工具结果是带有 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，即可在 trace viewer 中打开。
替代方案：Pi 的会话格式
如果您不想采用上述格式，可以输出 Pi 的会话格式（session-format.md），Hub 已支持该格式。在这种情况下，请在 Pi 的会话头行中也添加一个 harness: "..." 字段，以便 Hub 能够将追踪记录归属到您的 harness。