add agent traces docs

Author: cfahlgren1

docs/hub/_toctree.yml

@@ -292,6 +292,8 @@
     sections:
       - local: datasets-cell-editing
         title: Editing Datasets
+      - local: datasets-agent-traces
+        title: Agent Traces
       - local: datasets-viewer-configure
         title: Configure the Dataset Viewer
         sections:

docs/hub/data-studio.md

@@ -27,14 +27,14 @@ You can search for a word in the dataset by typing it in the search bar at the t
 
 ## Run SQL queries on the dataset
 
-You can run SQL queries on the dataset in the browser using the SQL Console. This feature also leverages our [auto-conversion to Parquet](data-studio#access-the-parquet-files). 
+You can run SQL queries on the dataset in the browser using the SQL Console. This feature also leverages our [auto-conversion to Parquet](data-studio#access-the-parquet-files).
 
 <div class="flex justify-center">
 <img class="block dark:hidden" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/hub/sql-ai.png" />
 <img class="hidden dark:block" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/hub/sql-ai-dark.png"/>
 </div>
 
-For more information see our guide on [SQL Console](./datasets-viewer-sql-console). 
+For more information see our guide on [SQL Console](./datasets-viewer-sql-console).
 
 ## Share a specific row
 
@@ -45,6 +45,10 @@ You can share a specific row by clicking on it, and then copying the URL in the
 <img class="hidden dark:block" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/hub/datastudio-row-dark.png"/>
 </div>
 
+## Agent traces
+
+Drop raw JSONL traces from tools like Claude Code, Codex, or Pi into a dataset (or a [Storage Bucket](./storage-buckets)), and Data Studio swaps the default table view for a dedicated trace viewer for stepping through sessions, turns, tool calls, and model responses. See [Agent Traces](./datasets-agent-traces) for supported agents and viewing traces.
+
 ## Large scale datasets
 
 The Dataset Viewer supports large scale datasets, but depending on the data format it may only show the first 5GB of the dataset:
@@ -101,12 +105,12 @@ You can specify which files to display in the Dataset Viewer by adding a YAML co
 ```yaml
 ---
 configs:
-- config_name: default
-  data_files:
-  - split: train
-    path: "data.csv"
-  - split: test
-    path: "holdout.csv"
+  - config_name: default
+    data_files:
+      - split: train
+        path: "data.csv"
+      - split: test
+        path: "holdout.csv"
 ---
 ```
 
@@ -115,14 +119,14 @@ You can also select multiple files per split or use glob patterns:
 ```yaml
 ---
 configs:
-- config_name: default
-  data_files:
-  - split: train
-    path:
-    - "data/train_part1.csv"
-    - "data/train_part2.csv"
-  - split: test
-    path: "data/*.csv"
+  - config_name: default
+    data_files:
+      - split: train
+        path:
+          - "data/train_part1.csv"
+          - "data/train_part2.csv"
+      - split: test
+        path: "data/*.csv"
 ---
 ```
 

docs/hub/datasets-agent-traces.md

@@ -0,0 +1,38 @@
+# Agent traces
+
+<div class="flex justify-center">
+<img class="block dark:hidden" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/datasets/agent-traces-preview-light.webp" alt="Agent trace preview on a dataset page in light mode."/>
+<img class="hidden dark:block" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/datasets/agent-traces-preview-dark.webp" alt="Agent trace preview on a dataset page in dark mode."/>
+</div>
+
+Agent traces from Claude Code, Codex, and Pi Agent are natively supported on the Hugging Face Hub. Upload the raw JSONL sessions to a dataset or a [Storage Bucket](./storage-buckets) and Data Studio opens them in a dedicated trace viewer.
+
+## Find your traces
+
+Each supported agent writes JSONL sessions to a known directory:
+
+| Agent       | Local session directory |
+| ----------- | ----------------------- |
+| Claude Code | `~/.claude/projects`    |
+| Codex       | `~/.codex/sessions`     |
+| Pi          | `~/.pi/agent/sessions`  |
+
+These trace files are supported out of the box, so you can upload them without modifying or converting them first.
+
+<Tip>
+
+The easiest way to upload is to ask your agent itself: point it at the directory above and tell it to upload the `.jsonl` files to a Hub dataset or bucket.
+
+Buckets are especially useful if you want to keep syncing traces as new sessions land.
+
+</Tip>
+
+## View your traces
+
+Once you have traces in a dataset or bucket, open them in Data Studio and click a row. The trace viewer shows the session timeline, prompts, assistant messages, tool calls, and results.
+
+<div class="flex justify-center">
+<img src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/datasets/agent-traces-session.webp" alt="Agent trace session viewer showing user and assistant turns with expanded tool calls."/>
+</div>
+
+For a public example, open [`TeichAI/DeepSeek-v4-Pro-Agent`](https://huggingface.co/datasets/TeichAI/DeepSeek-v4-Pro-Agent). You can also browse more datasets tagged as [`traces`](https://huggingface.co/datasets?format=format%3Aagent-traces).

docs/hub/datasets.md

@@ -13,4 +13,5 @@ This documentation focuses on the datasets functionality in the Hugging Face Hub
 - [Downloading Datasets](./datasets-downloading)
 - [Libraries](./datasets-libraries)
 - [Dataset Viewer](./datasets-viewer)
+- [Agent Traces](./datasets-agent-traces)
 - [Data files Configuration](./datasets-data-files-configuration)