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

# Concepts

> How bryel models agent runs as traces, interactions, and sessions.

bryel is agent-first. Three units structure everything you see.

<CardGroup cols={3}>
  <Card title="Trace" icon="workflow">
    One agent run (turn) — the root span plus all its model steps and tool calls.
  </Card>

  <Card title="Interaction" icon="message-square">
    The turn itself — one user → agent exchange, summarized.
  </Card>

  <Card title="Session" icon="messages-square">
    A conversation — multiple turns grouped by `sessionId`.
  </Card>
</CardGroup>

## Grouping keys

These telemetry keys connect runs into conversations and tie feedback back to a turn.

| Key         | Set via                        | Purpose                                                                                                 |
| ----------- | ------------------------------ | ------------------------------------------------------------------------------------------------------- |
| `sessionId` | telemetry `metadata.sessionId` | Groups turns into a conversation.                                                                       |
| `userId`    | telemetry `metadata.userId`    | The end-user behind the run.                                                                            |
| `messageId` | telemetry `metadata.messageId` | A per-turn handle, stamped as `bryel.interaction.id` so [feedback](/guides/feedback) joins to the turn. |

## Span kinds

Every span carries an OpenInference span kind (`openinference.span.kind`) so bryel knows what it is. The adapters set this for you; a custom [`SpanMapper`](/sdk/typescript) sets it from [`OpenInferenceSpanKind`](/sdk/typescript).

| Kind                                   | What it represents                                                       |
| -------------------------------------- | ------------------------------------------------------------------------ |
| `LLM`                                  | A model generation — `generateText` / `streamText` / a provider request. |
| `TOOL`                                 | A tool or function call inside a run.                                    |
| `CHAIN`                                | A composite step that wraps other spans, such as an agent loop.          |
| `AGENT`                                | An agent run.                                                            |
| `RETRIEVER` · `EMBEDDING` · `RERANKER` | Retrieval-augmented steps.                                               |
| `GUARDRAIL` · `EVALUATOR`              | Safety checks and scoring steps.                                         |

## Tokens and cost

Token counts live on the leaf model spans (the actual provider request); the outer operation span repeats them as a roll-up. bryel sums tokens and cost over the whole trace and prices them at ingest, so you see cost per turn, per session, and per project.

Pricing is recorded as `bryel.cost.usd` with a `bryel.cost.status` (`provider_reported`, `priced`, `unknown_model`, or `no_tokens`), so you always know whether a number is exact, estimated, or unavailable.

<Note>
  Span kinds and the `bryel.*` attributes are defined in [`@bryel/semconv`](/sdk/typescript).
</Note>