# 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](./agent-traces)). 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](https://jsonlines.org) (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)

```json
{ "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:

```json
{ "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

```jsonl
{"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](https://huggingface.co/datasets) ou um [Storage Bucket](./storage-buckets) 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](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/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.