Hub documentation
Formato de trazas de sesión
Formato de trazas de sesión
Las trazas de agentes de Claude Code, Codex, Pi, Hermes Agent y Factory Droid son compatibles de forma nativa (consulte Agent Traces). Si construye su propio harness, puede hacer que sus sesiones se rendericen en el mismo visor escribiéndolas en el Session Trace Simple Format (STS-Format) descrito a continuación.
El Session Trace Simple Format (STS-Format) es un archivo JSONL (un objeto JSON por línea) que el Hugging Face Hub detecta y renderiza en su visor de trazas. Captura una única sesión de agente/chat como una línea de encabezado seguida de líneas de mensajes.
1. Encabezado de sesión (primera línea)
{ "type": "session", "harness": "my-agent", "id": "b1a2c3", "name": "Implementing a new API" }| campo | obligatorio | notas |
|---|---|---|
type | sí | debe ser "session" |
harness | sí | el id del harness que produjo la traza |
id | sí | identificador de sesión único |
name | no | título legible por humanos |
| … | no | se permite y se ignora cualquier metadato adicional |
harness es el campo clave: es el id del harness y le indica al Hub qué renderizador, icono y etiqueta usar para la sesión. Los ids reconocidos actualmente son: llama.app. Es muy fácil añadir un nuevo identificador de harness aquí.
¿Estás construyendo un harness propio? Escríbenos y añadiremos un icono y una etiqueta para que tus sesiones se muestren con tu marca.
2. Mensajes (cada línea siguiente)
Cada línea es un mensaje en un sobre:
{ "type": "message", "message": { "role": "assistant", "content": "…" } }El objeto message:
| campo | obligatorio | notas |
|---|---|---|
role | sí | "user" · "assistant" · "system" · "tool" |
content | sí | texto (puede estar vacío) |
reasoningContent | no | razonamiento del modelo, mostrado como un bloque de pensamiento separado |
toolCalls | no | Llamadas a herramientas del asistente: [{ "id", "function": { "name", "arguments" } }] (arguments es una cadena JSON) |
toolCallId | no | en un mensaje role: "tool", vincula el resultado con el toolCalls[].id al que responde |
timestamp | no | milisegundos de epoch |
model | no | nombre del modelo |
Los resultados de las herramientas son mensajes con role: "tool" que incluyen un toolCallId; el visor coloca cada resultado junto a la llamada que lo generó.
Ejemplo
{"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"}}Sube el .jsonl resultante a un Dataset o a un Storage Bucket para abrirlo en el visor de trazas.
Alternativa: formato de sesión de Pi
Si prefiere no adoptar la forma anterior, puede emitir el formato de sesión de Pi (session-format.md), que el Hub ya admite. En ese caso, añada también un campo harness: "..." a la línea de encabezado de sesión de Pi, para que el Hub pueda atribuir la traza a su harness.