> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/harbor-framework/harbor/llms.txt
> Use this file to discover all available pages before exploring further.
# harbor traces
> Export agent trajectories to datasets
The `harbor traces` command group provides utilities for exporting agent trajectories from trials to datasets for analysis, sharing, and training.
## Commands
### harbor traces export
Export agent trajectories from trial directories to a Hugging Face dataset.
```bash theme={null}
harbor traces export [OPTIONS]
```
#### Options
Path to a trial directory or a root containing trials recursively.
Search recursively for trials under path. Default: `--recursive`
Export all episodes or only the last episode per trial. Options: `all`, `last`. Default: `all`
Also emit ShareGPT-formatted conversations column. Default: `--no-sharegpt`
Push dataset to Hugging Face Hub after export. Default: `--no-push`
Target Hugging Face repo id (org/name) when `--push` is set. Required when using `--push`.
Print discovery details for debugging. Default: `--no-verbose`
Filter trials by result: `success`, `failure`, or `all`. Default: `all`
Export subagent traces. Default: `--subagents`
Include instruction text for each row when available. Default: `--no-instruction-metadata`
Include verifier stdout/stderr blobs when available. Default: `--no-verifier-metadata`
#### Examples
Export traces from a job directory:
```bash theme={null}
harbor traces export --path ~/.cache/harbor/jobs/my-job-20260303-120000
```
Export and push to Hugging Face:
```bash theme={null}
harbor traces export \
--path ~/.cache/harbor/jobs/my-job-20260303-120000 \
--push \
--repo myorg/my-traces
```
Export only successful trials:
```bash theme={null}
harbor traces export \
--path ~/.cache/harbor/jobs/my-job-20260303-120000 \
--filter success
```
Export only failed trials:
```bash theme={null}
harbor traces export \
--path ~/.cache/harbor/jobs/my-job-20260303-120000 \
--filter failure
```
Export only last episode per trial:
```bash theme={null}
harbor traces export \
--path ~/.cache/harbor/jobs/my-job-20260303-120000 \
--episodes last
```
Export with ShareGPT format:
```bash theme={null}
harbor traces export \
--path ~/.cache/harbor/jobs/my-job-20260303-120000 \
--sharegpt
```
Export with metadata:
```bash theme={null}
harbor traces export \
--path ~/.cache/harbor/jobs/my-job-20260303-120000 \
--instruction-metadata \
--verifier-metadata
```
Export from a single trial:
```bash theme={null}
harbor traces export \
--path ./trials/my-task__agent__attempt-1 \
--no-recursive
```
## Trajectory Format (ATIF)
Harbor uses the **Agent Trajectory Interchange Format (ATIF)** to represent agent executions. Trajectories are stored as `trajectory.json` in trial directories.
### ATIF Structure
```json theme={null}
{
"episodes": [
{
"episode_id": "episode-0",
"steps": [
{
"step_id": 0,
"role": "user",
"content": "Create a Python script that..."
},
{
"step_id": 1,
"role": "assistant",
"content": "I'll create that script...",
"tool_calls": [
{
"tool_name": "write_file",
"tool_input": {"path": "script.py", "content": "..."},
"tool_output": {"success": true}
}
]
}
],
"metadata": {
"started_at": "2026-03-03T12:00:00Z",
"finished_at": "2026-03-03T12:05:00Z",
"outcome": "success"
}
}
],
"metadata": {
"agent_name": "claude-code",
"model_name": "anthropic/claude-opus-4-1",
"task_name": "my-task"
}
}
```
### Agent Support
Agents that support ATIF export (set `SUPPORTS_ATIF = True`):
* **claude-code**
* **opencode**
* More agents being added...
Other agents may not generate trajectory files.
## Dataset Schema
Exported datasets include:
### Core Fields
* **trial\_name**: Unique trial identifier
* **task\_name**: Task identifier
* **agent\_name**: Agent used
* **model\_name**: Model used (if applicable)
* **episode\_id**: Episode identifier
* **trajectory**: ATIF-formatted trajectory
* **reward**: Trial reward (0.0-1.0)
* **success**: Boolean success indicator
### Optional Fields
* **conversation**: ShareGPT format (if `--sharegpt`)
* **instruction**: Task instruction text (if `--instruction-metadata`)
* **verifier\_stdout**: Verifier output (if `--verifier-metadata`)
* **verifier\_stderr**: Verifier errors (if `--verifier-metadata`)
### ShareGPT Format
When `--sharegpt` is enabled, each row includes a `conversation` column:
```json theme={null}
[
{
"from": "human",
"value": "Create a Python script that..."
},
{
"from": "gpt",
"value": "I'll create that script..."
}
]
```
This format is compatible with many fine-tuning pipelines.
## Subagent Traces
When `--subagents` is enabled (default), the export returns a dictionary with:
* **main**: Dataset of main agent traces
* **subagent\_name\_1**: Dataset of subagent 1 traces
* **subagent\_name\_2**: Dataset of subagent 2 traces
* etc.
When `--no-subagents`, only the main dataset is returned.
## Use Cases
### Training Data Collection
Collect successful agent traces for training:
```bash theme={null}
harbor traces export \
--path ~/.cache/harbor/jobs/my-job-20260303-120000 \
--filter success \
--sharegpt \
--push \
--repo myorg/training-data
```
### Failure Analysis
Analyze failed attempts:
```bash theme={null}
harbor traces export \
--path ~/.cache/harbor/jobs/my-job-20260303-120000 \
--filter failure \
--instruction-metadata \
--verifier-metadata
```
### Reinforcement Learning
Export all traces for RL:
```bash theme={null}
harbor traces export \
--path ~/.cache/harbor/jobs/my-job-20260303-120000 \
--episodes all \
--push \
--repo myorg/rl-rollouts
```
### Benchmark Sharing
Share evaluation results:
```bash theme={null}
harbor traces export \
--path ~/.cache/harbor/jobs/terminal-bench-evaluation \
--push \
--repo myorg/terminal-bench-results
```
## Integration with Jobs
You can export traces automatically after job completion:
```bash theme={null}
harbor run \
--dataset terminal-bench@2.0 \
--agent claude-code \
--model anthropic/claude-opus-4-1 \
--export-traces \
--export-push \
--export-repo myorg/my-traces
```
See [harbor run](/cli/run) for all trace export options.
## Examples
### Export from Multiple Jobs
```bash theme={null}
# Export traces from all jobs in a directory
for job in ~/.cache/harbor/jobs/*; do
harbor traces export --path "$job" --push --repo myorg/all-traces
done
```
### Filter and Export
```bash theme={null}
# Export only successful traces with metadata
harbor traces export \
--path ~/.cache/harbor/jobs/my-job \
--filter success \
--instruction-metadata \
--verifier-metadata \
--push \
--repo myorg/successes
```
### Export for Analysis
```python theme={null}
# Load exported dataset for analysis
from datasets import load_dataset
ds = load_dataset("myorg/my-traces")
# Analyze success rates
success_rate = sum(ds["success"]) / len(ds)
print(f"Success rate: {success_rate:.2%}")
# Filter by task
task_traces = ds.filter(lambda x: x["task_name"] == "my-task")
```
## See Also
* [harbor run](/cli/run) - Run jobs with trace export
* [harbor jobs](/cli/jobs) - Manage jobs
* [harbor view](/cli/view) - View trajectories interactively