Hub documentation
Định dạng Traces Phiên
Định dạng Traces Phiên
Agent traces từ Claude Code, Codex, Pi, Hermes Agent và Factory Droid được hỗ trợ ngay từ đầu (xem Agent Traces). Nếu bạn tự xây dựng harness của riêng mình, bạn có thể hiển thị các phiên của nó trong cùng một trình xem bằng cách viết chúng theo Session Trace Simple Format (STS-Format) được mô tả bên dưới.
Định dạng Trace Phiên Bản Đơn Giản (STS-Format) là một tệp JSONL (một đối tượng JSON trên mỗi dòng) được Hugging Face Hub phát hiện và hiển thị trong trình xem trace. Định dạng này ghi lại một phiên agent/chat duy nhất dưới dạng một dòng tiêu đề theo sau là các dòng tin nhắn.
1. Tiêu đề phiên (dòng đầu tiên)
{ "type": "session", "harness": "my-agent", "id": "b1a2c3", "name": "Implementing a new API" }| trường | bắt buộc | ghi chú |
|---|---|---|
type | yes | phải là "session" |
harness | yes | id của harness đã tạo ra trace |
id | yes | id phiên duy nhất |
name | không | tiêu đề dễ đọc |
| … | không | bất kỳ metadata bổ sung nào đều được cho phép và bị bỏ qua |
harness là trường chính: đây là id của harness, và nó cho Hub biết trình render, icon và nhãn nào cần dùng cho phiên. Các id được công nhận hiện tại: llama.app. Việc thêm một định danh harness mới tại đây rất dễ dàng.
Bạn đang xây dựng một harness của riêng mình? Hãy liên hệ với chúng tôi và chúng tôi sẽ thêm một biểu tượng và nhãn cho nó để các phiên của bạn hiển thị với thương hiệu của bạn.
2. Tin nhắn (mọi dòng tiếp theo)
Mỗi dòng là một tin nhắn trong một phong bì:
{ "type": "message", "message": { "role": "assistant", "content": "…" } }Đối tượng message:
| trường | bắt buộc | ghi chú |
|---|---|---|
role | yes | "user" · "assistant" · "system" · "tool" |
content | yes | văn bản (có thể để trống) |
reasoningContent | không | quy trình suy luận của mô hình, hiển thị dưới dạng khối suy nghĩ riêng biệt |
toolCalls | không | lời gọi công cụ của trợ lý: [{ "id", "function": { "name", "arguments" } }] (arguments là một chuỗi JSON) |
toolCallId | không | trên một thông báo role: "tool", liên kết kết quả với toolCalls[].id mà nó trả lời |
timestamp | không | epoch milliseconds |
model | không | tên model |
Kết quả công cụ là các tin nhắn có role: "tool" kèm theo toolCallId; trình xem ghép mỗi kết quả ngay cạnh cuộc gọi đã tạo ra nó.
Ví dụ
{"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"}}Tải tệp .jsonl đã tạo lên Dataset hoặc Storage Bucket để mở trong trình xem trace.
Phương án thay thế: Định dạng phiên của Pi
Nếu bạn không muốn áp dụng định dạng ở trên, bạn có thể xuất định dạng phiên của Pi (session-format.md), vốn đã được Hub hỗ trợ. Trong trường hợp đó, hãy thêm trường harness: "..." vào dòng session-header của Pi, để Hub có thể gán trace cho harness của bạn.