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

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

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

```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"}}
```

Sube el `.jsonl` resultante a un [Dataset](https://huggingface.co/datasets) o a un [Storage Bucket](./storage-buckets) 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](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/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.