> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reasonblocks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```text theme={null}
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.

<Note>
  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](#migrate-an-older-generated-connection)
  to update it while preserving a backup of the original files.
</Note>

## 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](#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:

```bash theme={null}
uv add rbtrace==1.2.1
```

For a pip-managed environment:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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](/deployment). 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:

```python theme={null}
from anthropic import Anthropic
import reasonblocks_setup

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

For OpenAI:

```python theme={null}
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:

```python theme={null}
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:

```python theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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](/client-integration#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](/full-agent-training).

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

```python theme={null}
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](/agent-workflow) for reviewing data readiness,
training results and application tests through those stages.

## Install the reusable agent skill

Install the reusable setup instructions:

```bash theme={null}
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.