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

> ## Agent Instructions
> To act on Atlan objects, use the Atlan MCP server at https://api.atlan.com/mcp or the atlanai CLI; `atlanai --map json` prints its command map. Run a read-only identity check before any write.
> The docs MCP server at /mcp searches these docs only. It cannot read or change Atlan objects.
> SDK packages: Python `atlanai` (PyPI) and TypeScript `@atlanai/sdk` (npm). Show Python first, then TypeScript.

# How sessions and traces work

> How Agent Registry records each run as a session, captures its steps as a trace, and attributes them to agents and skills.

A session is the record of one run of an agent or harness. A trace is the
step-by-step evidence of what happened in that run: model calls, tool calls,
tokens, cost, latency, and errors. Together they let you answer what an agent
did, not only that it ran.

## Sessions

A session links one run to its subject, the agent or harness that ran it. It
holds the run's outcome and timestamps, its events, and its turns when a
transcript was uploaded.

A session is a record, not a command. Creating one does not start a run, and an
uploaded session is final once created: it cannot be edited or deleted.

## Traces

Traces are OpenTelemetry data. They reach Agent Registry from three sources:

* **Trace plugin for Claude Code**: turns each coding session into traces
  without code changes.
* **atlanai SDK**: traces your own agents and their model and tool calls.
* **OTLP exporter**: sends traces from any OpenTelemetry setup.

Every trace is stored in your organization, and is accepted only for a
workspace your credentials can reach.

## Attribution

Attribution connects a trace to agents, sessions, skills, and versions. What it
can connect depends on the identifiers the source sent. Explicit identifiers
are evidence. Missing identifiers mean the link is unknown.

For skills, the registry matches the skills recorded in a trace to the skill version
with the same content. Each match is an exact match, a `SKILL.md` match, or a
name match, from strongest to weakest.

## Where to read them

* **Agent page → Sessions**: the recorded runs for one agent.
* **Agent page → Usage → Recent runs**: open a run, start with
  **Highlights**, then select **Full trace** for each recorded step.
* **Skill page → Usage**: runs attributed to one skill, with their match
  confidence.

## Example

An engineer installs the trace plugin for Claude Code and fixes a bug with it.
The session reaches Agent Registry with its trace. The engineer opens the run
from **Recent runs** and reads **Highlights**: the prompt, key decisions,
errors, and response. **Full trace** shows each tool call in order.

## What sessions and traces do not prove

* **An accepted request is not a stored result.** A successful exporter or API
  response confirms one step. Find the matching trace in Agent Registry and
  compare its identifiers and timestamps.
* **Missing fields are unavailable, not empty.** A trace without a field is not
  proof that nothing happened.
* **A name is not a version.** Do not infer a skill version from its display
  name.

## See also

* [Send and verify traces](/registry/traces/how-tos/send-and-verify): Send execution evidence and confirm where it landed.
* [Trace attribution](/registry/traces/concepts/attribution): Read attribution fields safely.
* [Capture coding-agent sessions](/plugins/index): Install the trace plugin for Claude Code.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.