Hub documentation
Format des traces de session
Format des traces de session
Les traces d’agents issues de Claude Code, Codex, Pi, Hermes Agent et Factory Droid sont prises en charge nativement (voir Traces d’agents). Si vous développez votre propre harnais, vous pouvez faire afficher ses sessions dans le même visualiseur en les écrivant au format Session Trace Simple Format (STS-Format) décrit ci-dessous.
Le Session Trace Simple Format (STS-Format) est un fichier JSONL (un objet JSON par ligne) que le Hugging Face Hub détecte et affiche dans son visualiseur de traces. Il capture une session unique d'agent/de chat sous forme d'une ligne d'en-tête suivie de lignes de messages.
1. En-tête de session (première ligne)
{ "type": "session", "harness": "my-agent", "id": "b1a2c3", "name": "Implementing a new API" }| champ | requis | notes |
|---|---|---|
type | oui | doit être "session" |
harness | oui | l’identifiant du harnais ayant produit la trace |
id | oui | identifiant de session unique |
name | non | titre lisible |
| … | non | toute métadonnée supplémentaire est autorisée et ignorée |
harness est le champ clé : il s’agit de l’identifiant du harness, et il indique au Hub quel rendu, quelle icône et quel libellé utiliser pour la session. Les identifiants actuellement reconnus : llama.app. Il est très facile d’ajouter un nouvel identifiant de harness ici.
Vous construisez votre propre harnais ? Contactez-nous et nous ajouterons une icône et un libellé pour que vos sessions s’affichent avec votre habillage.
2. Messages (chaque ligne suivante)
Chaque ligne est un message dans une enveloppe :
{ "type": "message", "message": { "role": "assistant", "content": "…" } }L'objet message :
| champ | requis | notes |
|---|---|---|
role | oui | "user" · "assistant" · "system" · "tool" |
content | oui | texte (peut être vide) |
reasoningContent | non | le raisonnement du modèle, affiché sous forme de bloc de réflexion distinct |
toolCalls | non | appels d’outils de l’assistant : [{ "id", "function": { "name", "arguments" } }] (arguments est une chaîne JSON) |
toolCallId | non | un message role: "tool", qui associe le résultat à l'toolCalls[].id auquel il répond |
timestamp | non | millisecondes epoch |
model | non | nom du modèle |
Les résultats d’outils sont des messages avec role: "tool" portant un toolCallId ; le visualiseur associe chaque résultat à l’appel qui l’a généré.
Exemple
{"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éléchargez le fichier .jsonl résultant dans un Dataset ou un Storage Bucket pour l’ouvrir dans le trace viewer.
Alternative : format de session de Pi
Si vous préférez ne pas adopter la structure ci-dessus, vous pouvez émettre le format de session de Pi (session-format.md), que le Hub prend déjà en charge. Dans ce cas, ajoutez également un champ harness: "..." à la ligne d’en-tête de session de Pi, afin que le Hub puisse attribuer la trace à votre harness.