Integrating your agent

Use one source URL and one ReasonBlocks server key copied from Data. Keep them through recording, training and supported serving after you approve a release. Your provider SDK, original model ID and tool loop stay in your application. The ReasonBlocks key does not replace your provider credential.

Existing Anthropic or OpenAI client

Set your client’s base_url to the source URL and add the x-reasonblocks-key header from REASONBLOCKS_API_KEY. Anthropic uses https://api.reasonblocks.com/capture/SOURCE_ID/anthropic; OpenAI Chat Completions uses https://api.reasonblocks.com/capture/SOURCE_ID/openai/v1. You do not need a new package or helper to use these URLs. Copy the Quickstart example. Use a unique x-rb-run for each complete task and reuse it for the task’s model calls. For a long-lived client, pass extra_headers={"x-rb-run": task_id} per call. You can add x-rb-snapshot-id when you have a real starting snapshot for full-agent training. Keep the source URL and authentication headers unchanged when enabling a release.

Optional source-based helper

Install rbtrace==1.3.1 if you prefer automatic run labeling and source discovery. This helper is optional for a directly configured Anthropic or OpenAI client. Native Bedrock uses it to retain the existing IAM-signed AWS transport. Existing 1.3.0 integrations remain compatible. Upgrading to 1.3.1 adds Bedrock dispatch diagnostics and needs no new source URL, key or instrumentation code.

from rbtrace import Connection
from anthropic import Anthropic

rb = Connection(source_id="SOURCE_ID")  # reads REASONBLOCKS_API_KEY
client = Anthropic(**rb.client_kwargs("anthropic"))

with rb.run("your-unique-task-id"):
    # Execute the complete agent task using client, including tool calls.
    pass

Use OpenAI(**rb.client_kwargs("openai")) for OpenAI. Your normal provider key stays in its existing environment variable. Give each concurrent or successive task its own run scope. Call rb.status() for remote recording status and rb.diagnostics() for local delivery information. The Manage connection panel checks server status automatically.

Existing generated helper

Existing reasonblocks_setup.py integrations remain supported. The CLI and helper workflow is documented in Set up with your coding agent.

Client construction

The helper supplies the exact source URL and capture authentication header:

from openai import OpenAI
import reasonblocks_setup

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

Use Anthropic from the anthropic package for an Anthropic source. AsyncOpenAI and AsyncAnthropic accept the same settings. The returned dictionary contains base_url, default_headers with x-reasonblocks-key, and max_retries=0. Preserve your existing model, timeout and other application settings, and merge existing headers without overwriting x-reasonblocks-key. Automatic SDK retries are disabled on purpose. A timeout can leave paid work with an unknown outcome, because the provider may already have accepted the request; an SDK that silently retries would repeat it. Reconcile that outcome before retrying. If your application has its own reconciliation policy, override max_retries explicitly in the returned dictionary rather than adding a retry loop around the call. For installed packages, generate the helper inside the importable package and include its adjacent .reasonblocks/config.json in deployment files — see Deploy your connected application. Follow the helper location guide instead of changing sys.path.

Gemini and Bedrock

Bedrock uses its native AWS client and IAM credentials. Gemini uses the hosted source URL; the Connection helper supplies its URL and request headers.

Gemini

from google import genai
from rbtrace import Connection

rb = Connection(source_id="SOURCE_ID")
client = genai.Client(**rb.client_kwargs("gemini"))

with rb.run("your-unique-task-id"):
    # Execute your existing agent using client.
    pass

Keep GEMINI_API_KEY in its existing secret environment. The helper supplies the source endpoint and authentication headers. The hosted Gemini route records and forwards provider calls; it does not imply optimized-model serving compatibility.

Bedrock

Keep your existing boto3 client configuration, including region, retries and IAM credentials. Instrument it after construction:

import boto3
from rbtrace import Connection

rb = Connection(source_id="SOURCE_ID")
client = boto3.client("bedrock-runtime", region_name="us-east-1")
rb.instrument_bedrock(client, serving=True)

with rb.run("your-unique-task-id"):
    # Your existing invoke_model, converse or streaming calls use client.
    pass

print(rb.status())

Native capture does not need an Anthropic key or Bedrock bearer key. AWS requests keep their existing signing and endpoint. The source receives capture events; AWS credentials remain with the native client. With serving=True, an approved rollout may serve compatible nonstreaming requests. An explicit upstream decision uses your original Bedrock operation. A candidate error or uncertain dispatch is not automatically retried against Bedrock. Set serving=False for capture only. In 1.3.1, DispatchError exposes a safe error category, HTTP status when available and dispatch ID. rb.diagnostics()["last_dispatch"] adds the latest dispatch’s timing and outcome. These help distinguish authentication, timeout and other failures without exposing request or response content. See Dispatch diagnostics. An unknown outcome requires reconciliation; do not catch the error and replay the call through AWS or generate a new dispatch ID automatically. Streaming calls stay upstream and are observed while your application consumes them. They do not become optimized-model streams. Incomplete consumption prevents a complete capture event; check rb.diagnostics() for local delivery failures. Legacy applications can still use the hosted /capture/SOURCE_ID/bedrock/REGION relay with a Bedrock bearer/API key. That relay does not support SigV4; the native SDK integration above does.

Run identity and sequence numbers

Use one run for each top-level user turn: the first model call, its tool loop and the final answer. Keep the same run ID throughout that turn, then create a new ID for the next user turn, even within the same conversation. Creating a run for each model call breaks the tool loop; using one for the entire conversation merges separate tasks. For a background job, use the equivalent complete job boundary. Importing the generated helper installs run labelling for the process: every model call your provider client makes carries an x-rb-run header (which task the call belongs to) and an x-rb-seq header (this is call number n of that task). The dashboard groups a task’s calls by x-rb-run; that group is the unit full-agent training works on, together with x-rb-snapshot-id when you supply one. 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. Importing the helper sends no requests. RBTRACE_DISABLE=1 turns the labelling off without removing the import; doctor reports that condition. Labelling applies only to allowlisted hosts. The helper adds your configured capture hostname to the allowlist itself, so ordinary setups need no host configuration. 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 shape:

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

Create the headers once at the start of each task:

headers = reasonblocks_setup.run_headers()

and pass them on every model call in that task:

response = client.chat.completions.create(
    model=model,
    messages=messages,
    tools=tools,
    extra_headers=headers,
)

For Anthropic, pass extra_headers=headers to client.messages.create(...). Reuse the headers through the whole task, including after tool execution. A new task gets new headers. Keep them in task-local state for concurrent jobs and long-lived workers. Pass run_id=existing_task_id if your application already has a suitable ID: 1–128 letters, numbers, underscores, periods, colons or hyphens. The sequence number is still added automatically, keyed by the run ID you passed. Header names are case-insensitive; X-RB-Run and x-rb-run are the same header. An existing with rbtrace.client.run(): scope around each complete task also names the task and can stay in place. Without task headers or scopes, unscoped calls share one process-wide run. Keep the full conversation, policy, tool definitions and actual tool results in each request. Add the returned assistant message and tool results before the next call, as required by your existing agent loop.

Snapshots for later training

Ordinary capture needs no snapshot or sandbox. When preparing full-agent training, connect a test copy of the real tools and data that resets before each task. Then attach its actual starting snapshot:

headers = reasonblocks_setup.run_headers(snapshot_id=starting_snapshot_id)

Keep the same snapshot and run IDs throughout the task. The helper does not create that test state. See Train your complete agent for the adapter and evaluator requirements.

Verify the real application

Run python -m rbtrace doctor --path . --json using your application environment and the directory chosen at initialization. It checks 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, all without network calls. It does not prove authentication or successful capture. Test the actual launch command from outside the repository directory, and verify that the deployed helper and config are present. When running a real workflow is within your intended scope, confirm its records in Data. Normal provider fees apply. The helper runs inside Python. A framework that launches a JavaScript or native child process may make its model calls there; the Python helper does not instrument that process. Integrate at the real request boundary and use the current endpoint contract. For an older generated gateway connection, or a generated 1.1.0 connection that predates automatic labelling, follow the migration procedure.

Getting Started

Reference

Existing Anthropic or OpenAI client

Optional source-based helper

Existing generated helper

Client construction

Gemini and Bedrock

Gemini

Bedrock

Run identity and sequence numbers

Snapshots for later training

Verify the real application

​Existing Anthropic or OpenAI client

​Optional source-based helper

​Existing generated helper

​Client construction

​Gemini and Bedrock

​Gemini

​Bedrock

​Run identity and sequence numbers

​Snapshots for later training

​Verify the real application

Existing Anthropic or OpenAI client

Optional source-based helper

Existing generated helper

Client construction

Gemini and Bedrock

Gemini

Bedrock

Run identity and sequence numbers

Snapshots for later training

Verify the real application