Hub documentation
Formato de Rastreamento de Sessões
Formato de Rastreamento de Sessões
Os rastros de agentes do Claude Code, Codex, Pi, Hermes Agent e Factory Droid são suportados nativamente (veja Rastros de Agentes). Se você criar seu próprio harness, pode fazer com que suas sessões sejam renderizadas no mesmo visualizador gravando-as no Session Trace Simple Format (STS-Format) descrito abaixo.
O Session Trace Simple Format (STS-Format) é um arquivo JSONL (um objeto JSON por linha) que o Hugging Face Hub detecta e renderiza em seu visualizador de rastreamento. Ele captura uma única sessão de agente/chat como uma linha de cabeçalho seguida por linhas de mensagem.
1. Cabeçalho da sessão (primeira linha)
{ "type": "session", "harness": "my-agent", "id": "b1a2c3", "name": "Implementing a new API" }| campo | obrigatório | observações |
|---|---|---|
type | sim | deve ser "session" |
harness | sim | o id do harness que gerou o trace |
id | sim | id de sessão único |
name | não | título legível por humanos |
| … | não | qualquer metadado extra é permitido e ignorado |
harness é o campo principal: trata-se de o id do harness, e informa ao Hub qual renderizador, ícone e rótulo usar para a sessão. Os ids atualmente reconhecidos: llama.app. É muito fácil adicionar um novo identificador de harness aqui.
Construindo um harness próprio? Fale conosco e adicionaremos um ícone e um rótulo para ele, para que suas sessões sejam renderizadas com sua marca.
2. Mensagens (todas as linhas seguintes)
Cada linha é uma mensagem em um envelope:
{ "type": "message", "message": { "role": "assistant", "content": "…" } }O objeto message:
| campo | obrigatório | observações |
|---|---|---|
role | sim | "user" · "assistant" · "system" · "tool" |
content | sim | texto (pode estar vazio) |
reasoningContent | não | raciocínio do modelo, exibido como um bloco de pensamento separado |
toolCalls | não | chamadas de ferramentas do assistente: [{ "id", "function": { "name", "arguments" } }] (arguments é uma string JSON) |
toolCallId | não | em uma mensagem role: "tool", vincula o resultado ao toolCalls[].id ao qual responde |
timestamp | não | milissegundos de epoch |
model | não | nome do modelo |
Os resultados de ferramentas são mensagens com role: "tool" que carregam um toolCallId; o visualizador posiciona cada resultado ao lado da chamada que o gerou.
Exemplo
{"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"}}Envie o .jsonl resultante para um Dataset ou um Storage Bucket para abri-lo no visualizador de rastreamento.
Alternativa: formato de sessão do Pi
Se você preferir não adotar o formato acima, pode emitir o formato de sessão do Pi (session-format.md), que o Hub já suporta. Nesse caso, adicione também um campo harness: "..." à linha de cabeçalho de sessão do Pi, para que o Hub possa atribuir o rastro ao seu harness.