> ## Documentation Index
> Fetch the complete documentation index at: https://docs.decimal.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Execution Model

> How DecimalAI captures and organizes agent activity — traces, spans, LLM calls, sessions.

This is how DecimalAI captures and organizes your agent's activity. Understanding this hierarchy is essential — every other feature operates on these structures.

## How Executions Nest

```mermaid theme={null}
%%{init: {'theme':'base','themeVariables':{'primaryColor':'#f5f5f4','primaryBorderColor':'#a8a29e','primaryTextColor':'#44403c','lineColor':'#a8a29e'}}}%%
graph TD
    S["Session (multi-turn conversation)"] --> T1["Trace — Turn 1"]
    S --> T2["Trace — Turn 2"]
    S --> T3["Trace — Turn 3"]

    T2 --> SP1["Span: agent_planning"]
    T2 --> SP2["Span: tool_execution"]
    T2 --> SP3["Span: synthesis"]

    SP1 --> L1["LLM Call (GPT-4o)"]
    SP2 --> TC1["Tool Call: search_docs"]
    SP2 --> TC2["Tool Call: calculator"]
    SP3 --> L2["LLM Call (GPT-4o)"]

    style S fill:#44403c,stroke:#292524,color:#fafaf9
    style T1 fill:#a8a29e,stroke:#57534e,color:#1c1917
    style T2 fill:#a8a29e,stroke:#57534e,color:#1c1917
    style T3 fill:#a8a29e,stroke:#57534e,color:#1c1917
    style SP1 fill:#d6d3d1,stroke:#78716c,color:#1c1917
    style SP2 fill:#d6d3d1,stroke:#78716c,color:#1c1917
    style SP3 fill:#d6d3d1,stroke:#78716c,color:#1c1917
    style L1 fill:#e7e5e4,stroke:#a8a29e,color:#1c1917
    style L2 fill:#e7e5e4,stroke:#a8a29e,color:#1c1917
    style TC1 fill:#f5f5f4,stroke:#a8a29e,color:#1c1917,stroke-dasharray:3 3
    style TC2 fill:#f5f5f4,stroke:#a8a29e,color:#1c1917,stroke-dasharray:3 3
```

## Trace

A **trace** is a single, complete agent execution — everything from input to output. It is the atomic unit of the platform. Every feature (evaluation, compatibility scoring, dataset building) operates on traces.

A trace captures:

* **LLM calls** — model, prompt, completion, tokens, latency, cost
* **Tool calls** — function name, arguments, results
* **Active skills** — which skills were loaded for this run
* **Metadata** — agent name, status, timing, tags

Each trace belongs to exactly one agent (identified by `agent_name`) and optionally links to one manifest version (`manifest_id`).

<Note>
  **Trace vs Episode:** The compatibility engine sometimes calls traces "episodes" (as in "classify this episode"). They mean the same thing — a `RunTrace` database row. If you see "episode" in the API or logs, think "trace."
</Note>

<Note>
  **Trace vs Trajectory (ML context):** In reinforcement learning, a "trajectory" is a full sequence of (state, action, reward) tuples. A DecimalAI trace is similar — it captures a sequence of decisions — but it doesn't carry an explicit reward signal. Instead, eval scores serve as the quality signal, and traces are used for SFT/DPO training rather than RLHF.
</Note>

## Span

A **span** is a timed segment within a trace representing a discrete operation. Spans nest via `parent_span_id` to form a tree.

| Span Type   | What It Captures                                 |
| ----------- | ------------------------------------------------ |
| `llm`       | A model invocation — prompt, completion, tokens  |
| `tool`      | A tool/function call — name, arguments, result   |
| `retriever` | A RAG retrieval step — query, documents returned |
| `other`     | Custom application logic                         |

## LLM Call

An **LLM call** is a single model invocation stored at full fidelity. It contains the rendered prompt messages, model output, token counts, latency, cost, and any tool calls the model requested.

LLM calls are the most important artifact for fine-tuning — they become the input→output pairs in SFT datasets.

## Session

A **session** groups related traces into a multi-turn conversation. Traces within a session share a `session_id` and are ordered by `turn_index`.

Sessions enable:

* History-aware replay (re-running a full conversation, not just one message)
* Multi-turn evaluation (judging coherence across turns)
* Conversation-level analytics

## Source Type

Every trace carries a `source_type` indicating where it came from:

| Source        | Meaning                                                 |
| ------------- | ------------------------------------------------------- |
| `production`  | Real user traffic (default)                             |
| `sandbox`     | Manual testing via the [Playground](/guides/playground) |
| `test`        | Automated test suite                                    |
| `eval_replay` | Re-execution of a historical trace during evaluation    |

Other accepted values include `evaluation`, `sdk`, `manual`, `synthetic`, `development`, `sample`, and `demo`. Ingest rejects any value outside this allowlist with a `422`.

## Next

<CardGroup cols={2}>
  <Card title="Versioning & Compatibility" icon="layer-group" href="/concepts/versioning">
    How agent versions are tracked and what happens when they change.
  </Card>

  <Card title="Tracing Guide" icon="route" href="/guides/tracing">
    How to instrument your agent across frameworks.
  </Card>
</CardGroup>