Capture integration reference

Source URLs, environment variables and the Python helper used by the current ReasonBlocks dashboard connection.

This reference covers the dashboard capture connection. For installation, use Set up with your coding agent. The CLI and helper ship in rbtrace==1.2.1 on PyPI. It labels runs automatically on import, and migrate upgrades generated 1.1.0 connections.

Source configuration

The CLI records the exact dashboard-issued capture URL and provider in .reasonblocks/config.json and generates an adjacent reasonblocks_setup.py. The application imports that helper. See Endpoint compatibility for the two supported provider paths.

Environment variables

Name	Purpose
REASONBLOCKS_CAPTURE_KEY	Dashboard-issued source capture key, supplied at runtime
RB_CAPTURE_KEY	Existing alias; if both names are set, their values must agree
OPENAI_API_KEY / ANTHROPIC_API_KEY	Your normal provider credential, read by the provider client as before
REASONBLOCKS_CAPTURE_URL	Shell variable used in the setup examples to pass the exact source URL to the CLI
RBTRACE_DISABLE	1 turns run labelling off at startup; doctor reports that condition
RBTRACE_HOSTS	Optional extra hosts to label, comma-separated. A plain hostname matches only that exact host; a leading-dot entry such as .example.com matches its subdomains; * matches every host. The helper adds the configured capture hostname itself

Keys do not belong in generated files or CLI arguments. Capture keys expire after seven days, and rotation invalidates the previous key.

client_kwargs()

Returns client settings containing the configured base_url, default_headers with x-reasonblocks-key, and max_retries=0. Pass them to the existing OpenAI or Anthropic Python client constructor. Async clients accept the same settings. Preserve other application settings and merge headers deliberately.

client = OpenAI(**reasonblocks_setup.client_kwargs())

max_retries=0 disables the SDK’s automatic retries. A timeout can leave paid work with an unknown outcome, because the provider may already have accepted the request; a silent retry would repeat it. Reconcile that outcome before retrying. An application with its own reconciliation policy can override max_retries explicitly in the returned dictionary.

Run labelling (automatic)

Importing the generated helper installs run labelling for the process: every model call the provider client makes carries x-rb-run (which task) and x-rb-seq (call number within the task). The dashboard groups a task’s calls by x-rb-run and, with x-rb-snapshot-id, uses that group for full-agent training. The sequence number is carried on every call so a task’s calls stay in order; the dashboard does not currently read it and groups solely by x-rb-run. The labelling patches only the HTTP transport the SDK uses, reads no bodies and sends nothing of its own. It applies to allowlisted hosts; the helper adds the configured capture hostname to the allowlist, and RBTRACE_HOSTS extends it as described above. RBTRACE_DISABLE=1 turns it off; python -m rbtrace doctor reports whether calls from an environment will be labelled.

Without a named task the helper uses one process-wide run ID. That is correct for a process that handles exactly one task; any process that handles more than one task must name each task with run_headers() or an explicit rbtrace.client.run() scope.

run_headers(snapshot_id=None, run_id=None)

Returns headers naming one task; if run_id is omitted, generates a new ID. Call once per task and reuse the result as extra_headers on every model call of that task. Required for any long-lived or multi-task process (queue worker, web server, batch loop); unnecessary only when a process runs a single task. Sequence numbers are still added automatically, keyed by the run ID.

headers = reasonblocks_setup.run_headers()

Header	Requirement
x-rb-run	One ID per task, retained through all its model calls; the dashboard’s grouping key
x-rb-seq	Added automatically: 1, 2, 3 … within the task, so a task’s calls stay in order. Not currently read by the dashboard, which groups by x-rb-run
x-rb-snapshot-id	Included when a real starting snapshot ID is supplied; needed for full-agent training, optional for ordinary capture. Must be 1–128 letters, numbers, underscores, periods, colons or hyphens — a malformed value is rejected, not ignored

The connection answers with x-reasonblocks-capture: accepted or skipped, and with x-reasonblocks-capture-reason when it skipped. A skipped call is still forwarded and still answered; it simply records no training row. See whether a call was captured.

IDs use 1–128 letters, numbers, underscores, periods, colons or hyphens. Header names are case-insensitive: X-RB-Run / X-RB-Seq (as the shim writes them) and x-rb-run / x-rb-seq are the same headers. The helper attaches identifiers; it does not reset tools or create snapshots.

CLI checks and migration

python -m rbtrace doctor --path . --json inspects local configuration, the Python version, SDK availability, whether the selected SDK’s HTTP transport can be labelled, capture-key presence and the task-header contract. It makes no network calls and does not validate provider credentials or prove capture delivery. Use the helper’s actual directory for --path.

python -m rbtrace migrate converts an older generated gateway connection when given a real dashboard capture URL, and upgrades an unmodified generated 1.1.0 connection to the current helper when given its existing URL. It backs up the original files under .reasonblocks/backups/ first. See migration for backup behavior, customized helpers and the required application changes.