Batch Processing (Reference)

fast-agent batch run processes row-oriented inputs and writes one JSONL envelope per row.

Inputs

Use --input with a local .jsonl, .csv, or .parquet file, or with an hf:// URI for a Hugging Face dataset:

uv run fast-agent batch run \
  --input hf://datasets/evalstate/my-dataset/data/train.jsonl \
  --output out.jsonl \
  --model passthrough

Use --prompt for a short inline row prompt template:

uv run fast-agent batch run \
  --input rows.jsonl \
  --prompt "Classify this {{product}} into A, B, or C." \
  --output out.jsonl \
  --model passthrough

--prompt and --template are mutually exclusive. Use --template when the row prompt is easier to maintain in a file or URI. --template, --instruction, and --json-schema accept local paths, HTTP(S) URLs, file:// URIs, and hf:// URIs.

Supported input formats:

Dataset-level Hugging Face parquet inputs can be filtered by config and split:

uv run fast-agent batch run \
  --input 'hf://datasets/evalstate/my-dataset?config=default&split=train' \
  --output out.jsonl \
  --model passthrough

Each loaded row becomes the template context. Column names are available as template variables, and {{row_json}} renders the complete row:

Classify this record:
{{row_json}}

The row_json placeholder is reserved for the complete row, even when an input column has that name. The column's value remains present inside that JSON object.

For CSV input, all values are strings because they come from CSV fields. JSONL preserves the JSON value types. Parquet scalar values are normalized for JSON output and templates; dates/times become ISO strings, decimals become strings, and bytes are decoded as UTF-8 with replacement for invalid bytes.

Parquet SQL selection

For parquet input, --sql can define the rows processed by the batch run. The query is a DuckDB SELECT query over a view named input:

uv run fast-agent batch run \
  --input rows.parquet \
  --output out.jsonl \
  --sql "SELECT id, text FROM input WHERE split = 'eval'"

--sql is intentionally limited to parquet input. It cannot be combined with --limit, --offset, --sample, or --parallel; put filtering, ordering, and limits directly in the SQL query.

When --sql is used, output row_number values are result ordinals from the SQL result set, not stable original parquet row positions. Prefer --id-field with a stable identifier column when using SQL selection, especially with --resume.

Hugging Face Output

--hf-dataset currently applies to exported trace artifacts, not result JSONL output. Use it with --export-traces:

uv run fast-agent batch run \
  --input rows.jsonl \
  --output out.jsonl \
  --export-traces traces/ \
  --hf-dataset owner/trace-dataset

Appending and de-duplicating result rows into a Hugging Face dataset is not implemented yet.

Options

Worker and prompting

Input selection

Output envelopes

Resume, overwrite, and failure limits

Parallel runs

--parallel cannot be combined with --sql, --sample, --max-errors, or --export-traces.

Trackio monitoring

Install the optional Trackio dependency in the environment where fast-agent runs:

uv pip install 'fast-agent-mcp[trackio]'

The extra installs trackio>=0.44.0, also included in the gepa extra. Enable monitoring with --project or --trackio-project. Omit these options or use --no-trackio to use local monitoring only via --telemetry-output and --summary-output.

Trackio logs aggregate batch/ metrics only: progress, timing, usage, and cache behavior. Common keys include batch/progress_fraction, batch/error_rate, batch/rows_per_second, batch/timing/*, batch/usage/*, and batch/cache/*. Row contents, prompts, full outputs, and full errors are not logged by default.

Trace export