Integrating your agent

Every ReasonBlocks setup sends agent LLM traffic through a hosted capture gateway. That is the only requirement. An optional rbtrace shim labels run boundaries on outbound requests when you need high-yield traces for distillation — nothing changes inside your LLM SDK or agent framework. This page walks through the gateway setup everyone uses, then three paths depending on how your agent runs and whether you need golden (minable) runs for training.

Point your agent at the gateway

Copy your gateway URL from app.reasonblocks.com Quickstart:

export ANTHROPIC_BASE_URL="https://gateway.<your-tenant>.reasonblocks.com"

Your agent keeps using its normal stack — Anthropic SDK, LangChain, CrewAI, or any client that respects ANTHROPIC_BASE_URL. ReasonBlocks records each exchange and forwards to your upstream provider. Your API key passes through and is never stored. OpenAI, Gemini, and other providers use the same gateway with the matching base URL and upstream routing. See Endpoint compatibility. With only this env var, the gateway captures all traffic it sees. Run grouping is inferred from request patterns (prefix pairing, tool ids, thread starts). That is enough for audit logs, dashboard review, and many one-shot deployments.

When to add run labeling

Distillation reads rb_trace_v1 and prefers runs where provenance.supports_universal_claims is true — shown as golden in the dashboard and Quickstart. Golden runs need proven boundaries: a complete step sequence per logical job, not inferred merges. Inference is conservative. Multi-agent crews, repeated similar prompts, and long-lived workers often produce runs marked not minable rather than guessed wrong. That is safe for capture, but low yield for automated training. The rbtrace shim adds two HTTP headers (X-RB-Run, X-RB-Seq) on outbound LLM API calls via httpx (used by most official SDKs). Install it once at process startup; wrap each job in a context manager when one process handles many jobs.

Gateway only is fine if you only need capture and dashboard review, or you can accept lower golden yield. Add the shim (Tier B or C below) when distillation, RL, or compliance pipelines need reliable minable traces.

Pick a path

Path	What you add	Fits
A — Gateway only	Env var	Capture, audit, dashboard review; one job per process is OK with inferred grouping
B — `install()` once	Env var + `rbtrace.client.install()` at startup	One logical job per process, then exit or idle
C — `run()` per job	Env var + `install()` + `with rbtrace.client.run():` per job	Queue workers, batch loops, thread pools

Decision guide

Do you need golden rb_trace_v1 for automated distillation?
│
├─ NO  → Path A (gateway only)
│
└─ YES → Does one process handle exactly one logical job, then stop or idle?
         │
         ├─ YES → Path B (install() at startup)
         │
         └─ NO  → Path C (install() + with rbtrace.client.run() per job)

Path A: Gateway only

Nothing beyond the env var.

export ANTHROPIC_BASE_URL="https://gateway.<your-tenant>.reasonblocks.com"

Choose this when

You want the fastest rollout with no new dependencies or app changes beyond the base URL.
You need a durable audit log of LLM API traffic in hosted storage.
You review capture and golden-run counts in the dashboard.
Each worker handles at most one logical job, then exits (one-shot container, Lambda, python run.py once per invocation).
You can accept inferred run boundaries and lower minable yield for automated distillation.

What you get

Full capture of every LLM request/response the gateway sees.
Run separation by passive inference.
Safe but incomplete grouping: unsound merges are avoided; ambiguous shapes are marked not minable instead of guessed wrong.

What you give up

Proven run completeness (no 1..n sequence proof on the header path).
High minable yield when one process runs many similar jobs or complex multi-agent crews.

Path B: `install()` at startup

Same gateway env var. Add the shim once when the process starts:

pip install rbtrace   # when published to PyPI

import rbtrace.client
rbtrace.client.install()

The shim stamps run headers on outbound LLM API calls only. No other changes to your agent code.

Choose this when

You need minable rb_trace_v1 for distillation, RL, or compliance pipelines.
The process runs one logical job from start to exit:
- one CrewAI kickoff() then exit,
- one API request → one agent invocation → done,
- one long conversational session (single user thread).
You use async multi-agent frameworks (e.g. CrewAI manager + role agents) and want one trace for the whole crew. Sub-agents inherit the same run id automatically.
You can add rbtrace to the agent environment (~150 lines, open source).

Avoid Path B alone when

A single Python process loops over many unrelated tasks (for task in tasks:). Every task would share the first run id and traces merge → use Path C.
Workers use threading.Thread for parallel jobs. Each thread gets its own run id, not one per task → use Path C inside each thread (or one process per job).

What you get

Proven run boundaries and step order on the header path.
High minable yield on hard shapes (multi-agent, delegation) compared to gateway-only capture.

Path C: `run()` per job

Same gateway and startup as Path B, plus one context manager per logical job:

import rbtrace.client
rbtrace.client.install()

for task in tasks:
    with rbtrace.client.run():
        crew.kickoff(inputs=task)   # or agent.run(task), etc.

Async:

async for task in tasks:
    with rbtrace.client.run():
        await agent.run(task)

Choose this when

One long-lived process handles many jobs (batch queue, worker pool, cron loop).
You need minable traces and each job must be a separate run with proven completeness.
You delegate work to OS threads and need one run id per task (wrap the thread body in with rbtrace.client.run():).
Path B would merge distinct jobs into one trace, which breaks downstream mining.

What you get

Everything in Path B, with a fresh run id per with block.
Safe batch and worker-pool deployments without “super-run” merges.

One extra line per job loop (or per thread entrypoint). Still no changes inside the LLM SDK or framework.

Common deployment patterns

Deployment pattern	Path
Agent on your infra, gateway hosted by ReasonBlocks	A, B, or C
Docker: one container invocation per user request	A or B
Kubernetes Job: one task per pod	A or B
Long-running worker draining a queue	C
`for contract in contracts: crew.kickoff(...)` in one script	C
CrewAI single `kickoff` in a fresh process	B
Distillation consuming only `supports_universal_claims: true`	B or C

Kill switches

Goal	Action
Bypass capture	Unset `ANTHROPIC_BASE_URL` (agent talks to provider directly).
Disable shim without removing it	`RBTRACE_DISABLE=1` (capture continues; grouping falls back to Path A behavior).

What the shim does not do

Parse or log prompts in-process beyond adding two HTTP headers.
Replace the gateway — traffic must still go through ANTHROPIC_BASE_URL.
Affect calls that do not use httpx for LLM traffic (those requests fall back to inferred grouping).

Next steps

Quickstart

End-to-end: capture → distill → serve.

Deployment

Hosted gateway and pipeline; self-hosting appendix.

Endpoint compatibility

Anthropic, OpenAI, Gemini, and other LLM paths.

Getting Started

Reference

Point your agent at the gateway

When to add run labeling

Pick a path

Decision guide

Path A: Gateway only

Choose this when

What you get

What you give up

Path B: `install()` at startup

Choose this when

Avoid Path B alone when

What you get

Path C: `run()` per job

Choose this when

What you get

Common deployment patterns

Kill switches

What the shim does not do

Next steps

Quickstart

Deployment

Endpoint compatibility

​Point your agent at the gateway

​When to add run labeling

​Pick a path

​Decision guide

​Path A: Gateway only

​Choose this when

​What you get

​What you give up

​Path B: install() at startup

​Choose this when

​Avoid Path B alone when

​What you get

​Path C: run() per job

​Choose this when

​What you get

​Common deployment patterns

​Kill switches

​What the shim does not do

​Next steps

Quickstart

Deployment

Endpoint compatibility

Point your agent at the gateway

When to add run labeling

Pick a path

Decision guide

Path A: Gateway only

Choose this when

What you get

What you give up

Path B: `install()` at startup

Choose this when

Avoid Path B alone when

What you get

Path C: `run()` per job

Choose this when

What you get

Common deployment patterns

Kill switches

What the shim does not do

Next steps