How to Export Agent Trajectories for Training Reinforcement Learning Models in Cua

You can export agent trajectories from Cua using the cua trajectory view CLI command to generate a zip file, or programmatically via the zip_trajectory() function in cua_cli/utils/trajectory_recorder.py, which packages screenshots and JSON responses into a format ready for RL training pipelines.

The trycua/cua framework automatically records every agent interaction as a trajectory during cua do executions. To export agent trajectories for training reinforcement learning models, you can leverage built-in CLI utilities or Python APIs that package the recorded session data—screenshots, tool calls, and timestamps—into standardized zip archives.

Where Trajectories Are Recorded

Every cua do interaction is recorded as a sequence of turn folders under ~/.cua/trajectories/<machine>/<timestamp>/. The recording logic in cua_cli/utils/trajectory_recorder.py handles session creation, while _maybe_record_turn in cua_cli/commands/do.py triggers the capture after each turn.

The directory structure follows this pattern:

~/.cua/trajectories/
  └─ <machine_name>/
       └─ 20241015-143210/
            ├─ turn_001/
            │    ├─ screenshot.png
            │    └─ turn_001_agent_response.json
            ├─ turn_002/
            │    ├─ screenshot.png
            │    └─ turn_002_agent_response.json
            └─ ...

Each turn_###_agent_response.json follows the TrajectoryViewer schema and contains the model name, timestamps, and the exact computer_call action the agent performed.

Export Methods

You have three primary options to export recorded trajectories: the CLI convenience command, manual session selection, or direct Python API access.

Using the CLI (cua trajectory view)

The cua trajectory view command is the fastest way to export agent trajectories. It automatically zips the session and launches a local CORS file server for immediate download.

# Export the most recent session (default)

cua trajectory view

# Export a specific session by machine and timestamp

cua trajectory view my-container 20241015-143210

The command outputs a zip file path and a local viewer URL. The zip file (e.g., 20241015-143210.zip) is created beside the session folder under ~/.cua/trajectories/. You can copy this file directly to your training infrastructure:

cp ~/.cua/trajectories/my-container/20241015-143210.zip /my/rl/data/

Stop the local server when finished with cua trajectory stop.

Using the Python API

For embedding export logic in training scripts or CI pipelines, import the recorder utilities directly from cua_cli/utils/trajectory_recorder.py.

from pathlib import Path
from cua_cli.utils.trajectory_recorder import list_trajectories, zip_trajectory

# List all sessions for a specific machine

sessions = list_trajectories(machine="my-container")
latest = sessions[-1]  # Most recent entry

session_path = Path(latest["path"])

# Create the zip archive (returns Path to the .zip file)

zip_path = zip_trajectory(session_path)
print(f"Trajectory ready at: {zip_path}")

The zip_trajectory() function creates a TrajectoryViewer-compatible archive next to the source directory, preserving the original turn structure.

Using Exported Data for RL Training

The exported zip contains precisely the data you need for reinforcement learning training loops:

• State: Load turn_###/screenshot.png to obtain the visual observation at each timestep.
• Action: Parse turn_###_agent_response.json; the JSON contains the tool call type and parameters representing the agent's action.
• Reward: Derive from outcome metrics, success flags in the response, or custom heuristics computed from the screenshot sequence.

Because the archive maintains the original turn_*/ directory structure, you can unzip and iterate over folders chronologically in your data loader.

Practical Code Examples

Recording Trajectories

Recording is enabled by default for every cua do execution via the _maybe_record_turn helper in cua_cli/commands/do.py.

# Standard execution records automatically

cua do my-agent "open notepad"

# Disable recording for a specific run

cua do --no-record my-agent "quick task"

Listing and Managing Sessions

The cua_cli/commands/trajectory.py module provides utilities to manage stored data.

# Display all sessions in a human-readable table

cua trajectory ls

# Remove sessions older than 30 days

cua trajectory clean --machine my-container --older-than 30 -y

These commands invoke list_trajectories() and clean_trajectories() from the recorder module.

Programmatic Export in Training Scripts

Embed trajectory export directly into your RL pipeline:

from pathlib import Path
from cua_cli.utils.trajectory_recorder import list_trajectories, zip_trajectory

def export_latest(machine: str) -> Path:
    sessions = list_trajectories(machine=machine)
    if not sessions:
        raise RuntimeError(f"No trajectories found for {machine}")
    latest_path = Path(sessions[-1]["path"])
    return zip_trajectory(latest_path)

# Integration example

zip_file = export_latest("my-container")

# Pass zip_file to torch.utils.data.Dataset or custom loader

Key Source Files

File	Role
cua_cli/utils/trajectory_recorder.py	Core recorder containing ensure_session, record_turn, zip_trajectory, and list_trajectories
cua_cli/commands/do.py	Command implementation with _maybe_record_turn logic and --no-record flag handling
cua_cli/commands/trajectory.py	CLI frontend for ls, view, clean, and stop subcommands

Summary

• Trajectories are stored under ~/.cua/trajectories/<machine>/<timestamp>/ with screenshots and JSON responses for each turn.
• Use cua trajectory view to quickly zip and serve the latest session, or specify a machine and timestamp for targeted exports.
• Import zip_trajectory and list_trajectories from cua_cli/utils/trajectory_recorder.py for programmatic access in Python training scripts.
• Each turn folder contains screenshot.png (state) and turn_###_agent_response.json (action data) compatible with standard RL training formats.
• Recording is enabled by default during cua do executions and can be disabled per-run with the --no-record flag.

Frequently Asked Questions

Where are trajectory files stored on disk?

Trajectory files are stored in ~/.cua/trajectories/<machine_name>/<timestamp>/, where each session folder contains sequentially numbered turn subdirectories with screenshots and JSON response files.

Can I disable trajectory recording for specific runs?

Yes. Pass the --no-record flag to any cua do command. The _maybe_record_turn function in cua_cli/commands/do.py checks this flag before invoking the recorder.

What data format is used for RL training?

Each turn provides a screenshot.png (visual state) and a turn_###_agent_response.json containing the agent's tool call action, model metadata, and timestamps. The TrajectoryViewer schema ensures consistent formatting for parsing state-action pairs.

How do I export trajectories programmatically in Python?

Import list_trajectories and zip_trajectory from cua_cli/utils/trajectory_recorder.py. Use list_trajectories(machine="name") to locate sessions, then pass the session path to zip_trajectory() to generate the archive file.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}