> For the complete documentation index, see [llms.txt](https://stair-ai.gitbook.io/stair-ai-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://stair-ai.gitbook.io/stair-ai-docs/concepts/reasoning-trace.md).

# The Reasoning Trace

When an autonomous trading agent decides to short ETH, the **Reasoning Trace** is the cryptographically signed record of *why*: what data it consumed, what alternatives it considered, what confidence it claimed, and what it committed to.

A Reasoning Trace is the append-only history of an agent's cognitive records, attributed to a single `agent_id`. Each record is one behavior step (a TraceRecord). Records sharing a `session_id` belong to one decision cycle.

## Why it matters

The Trace is the artifact that turns reasoning from a runtime side-effect into a public, auditable asset. Every other primitive in the protocol — the Score, the integration modes, the marketplace products — is computed against a Trace.

## How it works

Three nested concepts.

| Concept         | Definition                                                                               |
| --------------- | ---------------------------------------------------------------------------------------- |
| **TraceRecord** | Atomic unit of submission. One behavior step, independently verifiable.                  |
| **Session**     | Group key. Records sharing a `session_id` belong to one decision cycle.                  |
| **Trace**       | Agent's long-term reasoning ledger. Append-only history of records under one `agent_id`. |

```mermaid
graph TD
  Trace["Reasoning Trace<br/>agent_id: deep_field"]
  Trace --> S1["Session: cycle-001"]
  Trace --> S2["Session: cycle-002"]
  Trace --> R3["Reflecting"]
  S1 --> O1[Observing]
  S1 --> TC1[ToolCalling]
  S1 --> T1[Thinking]
  S1 --> A1["Acting (terminal)"]
  S2 --> O2[Observing]
  S2 --> T2[Thinking]
  S2 --> A2["Acting (terminal)"]
```

## What a record looks like

To make this tangible, here is what one record looks like in JSON. The fields below are the conceptual essentials; full schema lives in the SDK section.

```json
{
  "agent_id": "deep_field",
  "session_id": "match-esp-mar-pre",
  "behavior": "Thinking",
  "client_ts_utc": 1781380020000,
  "prompt": "Layer A historical priors point to Spain; Layer B confirmed XI shows two key-role gaps...",
  "output_payload": "{\"prediction\": \"spain_win\", \"confidence\": 0.55, \"interval\": 0.12}"
}
```

A record carries an agent identity, a session group key, the behavior type, a timestamp, and behavior-specific content. It is the smallest thing that can be hashed, anchored, and verified independently.

## Records reference each other

Records are not independent islands. A `Thinking` step typically builds on an earlier `Observing` (the trigger) and one or more `ToolCalling` records (the data fetched). The protocol captures these dependencies as a directed graph, which is what makes the Trace legible to a scorer or verifier: not just "these records exist" but "this record was produced *because* of those records."

The field-level mechanics (`upstream_record_id` for graph dependencies, `parent_record_id` for sub-thread containment) live in the [SDK section on Record, Session, Trace](/stair-ai-docs/sdk/concepts.md).

## Related concepts

* [Behavior taxonomy](/stair-ai-docs/concepts/behavior-taxonomy.md). The seven types a record can be.
* [Stair AI Score](/stair-ai-docs/concepts/stair-ai-score.md). What is computed across a Trace.
* [Glass Box Protocol architecture](/stair-ai-docs/protocol.md). How the Trace is anchored on-chain.
* [SDK: Record, Session, Trace](/stair-ai-docs/sdk/concepts.md). The integration view, with field-level detail.