Set up with your coding agent

Give your coding agent one instruction to connect your Python application to ReasonBlocks capture and check the local setup.

Give your coding agent this instruction:

Read https://docs.reasonblocks.com/agent-setup.md and integrate ReasonBlocks into this project.

ReasonBlocks provides a CLI, a command-line tool that generates configuration; a small Python integration helper that connects your existing client; and an agent skill with the setup instructions. Your existing OpenAI or Anthropic Python client library—the provider’s SDK—continues making model requests.

The CLI and helper are available on PyPI in rbtrace==1.2.1. It labels runs automatically when you import the generated helper. If you already use a generated 1.1.0 connection, follow Migrate an older generated connection to update it while preserving a backup of the original files.

What you need

• A Python 3.10 or newer application using OpenAI Chat Completions or Anthropic Messages.
• A data source’s exact HTTPS capture URL and capture key from Data → Manage connection. An organization administrator can create the source and generate its key.
• Your existing provider API key, supplied through your application’s secret environment.

Connecting and capturing need no sandbox. You can connect your existing application and collect its normal workflow calls. Training later needs a way to reset and exercise your tools safely; see Preparing for training.

The CLI configures a connection already issued by the dashboard. It does not create an account or invent a source URL. Capture keys expire after seven days; rotating a key invalidates the previous one.

1. Install into the application environment

Use your project’s package manager. For uv:

uv add rbtrace==1.2.1

For a pip-managed environment:

python -m pip install rbtrace==1.2.1

Record the dependency in the existing manifest or requirements file. Use the Python environment that runs the application. uvx installs a tool into a separate environment; it does not add the dependency to your application.

2. Generate the connection files

Set REASONBLOCKS_CAPTURE_URL to the complete URL copied from Data, including the source ID and provider suffix. For Anthropic:

python -m rbtrace init \
  --capture-url "$REASONBLOCKS_CAPTURE_URL" \
  --provider anthropic --path . --json

Use --provider openai with the source’s OpenAI URL. Add --dry-run to preview the files without writing them. The installed rbtrace command accepts the same arguments as python -m rbtrace.

The CLI generates .reasonblocks/config.json, reasonblocks_setup.py and .reasonblocks/SETUP.md. These contain connection settings and instructions, not credentials. Supply the capture key through REASONBLOCKS_CAPTURE_KEY in your secret environment. The existing dashboard name RB_CAPTURE_KEY is also accepted; if both are set, they must agree. Keep your provider key in its usual location, such as OPENAI_API_KEY or ANTHROPIC_API_KEY.

Choose an importable helper location

The --path . example fits a flat project. For an installed package under src/my_agent, generate the helper beside the package modules:

python -m rbtrace init \
  --capture-url "$REASONBLOCKS_CAPTURE_URL" \
  --provider anthropic --path src/my_agent --json

Use from my_agent import reasonblocks_setup or a package-relative import. A script launched directly as python src/my_agent/main.py can import a helper beside it with import reasonblocks_setup; it may not find one at the repository root. Follow the actual application layout instead of adding a sys.path workaround.

Ship reasonblocks_setup.py and its adjacent .reasonblocks/config.json with the application, as described in Deploy your connected application. Include the hidden config directory explicitly in wheel package data or the deployed image; .reasonblocks/SETUP.md is optional in deployments. Test the real entrypoint from outside the repository directory to verify imports and config lookup.

3. Connect your existing client

For Anthropic:

from anthropic import Anthropic
import reasonblocks_setup

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

For OpenAI:

from openai import OpenAI
import reasonblocks_setup

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

Async clients accept the same settings. Preserve the application’s other client settings and merge existing headers without replacing the capture headers. The helper supplies the source base URL, the x-reasonblocks-key header and max_retries=0. Automatic SDK retries are disabled because a timeout can leave paid work with an unknown outcome: the provider may already have accepted the request. Reconcile that outcome before retrying. If your application has chosen its own retry policy, override max_retries explicitly in the returned dictionary rather than adding a retry loop.

Importing the helper installs run labelling for the process, so every model call made through the client carries x-rb-run and x-rb-seq. The dashboard groups a task’s calls by x-rb-run and uses x-rb-snapshot-id 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 — it groups solely by x-rb-run. Importing the helper sends no requests, reads no request bodies and changes no credentials. Set RBTRACE_DISABLE=1 before startup to turn labelling off; doctor reports that condition.

Labelling applies only to allowlisted hosts, and the helper adds your configured capture hostname to the allowlist itself. If you also set RBTRACE_HOSTS, a plain hostname such as capture.example.com matches only that exact host; a leading-dot entry such as .example.com matches its subdomains. Use example.com,.example.com when you intentionally need both the domain and its subdomains. RBTRACE_HOSTS=* labels every host.

Whether you must name tasks depends on the process:

• One task per process: nothing more to do; the helper labels every call with one run ID.
• Any long-lived or multi-task process — a queue worker, a web server, a batch loop: run_headers() at every task boundary is required. Without it the helper stamps one process-wide run ID, every task collapses into a single x-rb-run, and for the dashboard one x-rb-run is one training task.

At the start of each task, create its headers once:

headers = reasonblocks_setup.run_headers()

This creates a new x-rb-run identifier. Pass the same headers on every model call in that task. For example, adapt your existing Anthropic call:

response = client.messages.create(
    model=model,
    max_tokens=1536,
    messages=messages,
    tools=tools,
    extra_headers=headers,
)

For OpenAI, pass extra_headers=headers to client.chat.completions.create(...). Keep your real messages, tool definitions and tool results. Create fresh headers for the next task; queue workers and concurrent jobs must each retain their own headers. If your application already has a task ID, pass run_id=existing_task_id to run_headers().

An existing with rbtrace.client.run(): scope around each complete task can supply the boundary instead. Without task headers or scopes, unscoped calls share one process-wide run. Your application continues executing its tools.

4. Check the setup

Run the check in the application’s Python environment:

python -m rbtrace doctor --path . --json

For uv, use uv run python -m rbtrace doctor --path . --json. Use the same --path chosen for initialization, such as src/my_agent.

The check 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. It does not check provider credentials, validate the capture key with the service or prove that your calls reached Data. Run relevant local tests for the integration and test the actual application entrypoint.

When you run a real workflow, normal provider fees apply and the service receives its requests for capture. Confirm the source records in Data before treating the connection as verified end to end.

Migrate an older generated connection

To upgrade an unmodified generated 1.1.0 connection, keep its existing source URL and capture key: pass the same URL to --capture-url and leave REASONBLOCKS_CAPTURE_KEY as it is. If a previous setup generated a gateway configuration, first create a dashboard data source and obtain its actual capture URL and key. Then run:

python -m rbtrace migrate \
  --capture-url "$REASONBLOCKS_CAPTURE_URL" \
  --provider anthropic --path . --json

Use --provider openai for an OpenAI source, and the directory containing the old generated files for --path. Add --dry-run to preview. Migration copies the original generated files to .reasonblocks/backups/<id>/ before writing the current helper and SETUP.md; for a 1.1.0 connection with the same URL and provider, .reasonblocks/config.json is reported unchanged. Repeating a completed migration changes nothing. It refuses to replace a customized helper; your coding agent must inspect and merge those changes.

Update application code to construct the client with client_kwargs(). Importing the generated helper installs labelling, so remove obsolete reasonblocks_setup.install() calls left from an old gateway helper; a separate rbtrace.client.install() call is no longer needed either (a second call is a harmless no-op). Keep an existing explicit rbtrace.client.run() scope around each task, or use fresh run_headers() per task — both name a task, and a process that runs many tasks needs one of them at every task boundary. Remove the old gateway base-URL setting from deployment configuration. Restart the affected clients and processes; changing a config file does not reroute an already-constructed client. The migration command changes generated files; it does not edit arbitrary application code or create dashboard credentials. Re-run doctor and the actual entrypoint after the code changes.

Migrate only a compatible OpenAI Chat Completions or Anthropic Messages client. Do not switch an application to a different provider or API as part of setup. A Gemini or Bedrock application does not use this helper; it is configured in the client — see Gemini and Bedrock. A Fireworks or OpenAI Responses application needs a separately planned compatibility change.

Preparing for training

A sandbox is a test copy of the tools and data your agent works with, reset to a known starting state for each task. For example, a support agent might use a test ticket store and test order records. It does not necessarily mean running a new server yourself.

A small adapter connects snapshot/reset operations, tool execution and an outcome evaluator to that test environment. Your coding agent can help implement it, but it needs your application’s tool contracts, access to the test systems and a way to judge a completed task. See Train your complete agent.

Once a real repeatable snapshot exists, attach its ID at the task boundary:

headers = reasonblocks_setup.run_headers(snapshot_id=starting_snapshot_id)

The snapshot is optional for ordinary capture and required for the full-agent training workflow. The helper attaches an ID; it does not create the snapshot. Earlier captures without a restorable starting state do not automatically become training tasks. Collect tasks with real snapshots or curate replayable starting tasks for the connected test environment. Training preparation, budget approval and enabling a trained release are later steps. See Work with your coding agent for reviewing data readiness, training results and application tests through those stages.

Install the reusable agent skill

Install the reusable setup instructions:

npx skills add https://docs.reasonblocks.com

Select reasonblocks-setup when offered. The skill helps the coding agent inspect your project, place the helper correctly and verify the integration. An MCP server is not required for this setup.

These helpers run in Python applications. They do not reach JavaScript clients or model calls made by a separate child process. Integrate at the process that actually makes the request, and report any unsupported path explicitly.