> ## 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. # Integrating your agent > Send LLM traffic through the hosted gateway, then add optional run labeling when you need distillation-ready traces. 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](https://app.reasonblocks.com) Quickstart: ```bash theme={null} export ANTHROPIC_BASE_URL="https://gateway..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](/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](/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. ```bash theme={null} export ANTHROPIC_BASE_URL="https://gateway..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: ```bash theme={null} pip install rbtrace # when published to PyPI ``` ```python theme={null} 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: ```python theme={null} import rbtrace.client rbtrace.client.install() for task in tasks: with rbtrace.client.run(): crew.kickoff(inputs=task) # or agent.run(task), etc. ``` Async: ```python theme={null} 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 End-to-end: capture → distill → serve. Hosted gateway and pipeline; self-hosting appendix. Anthropic, OpenAI, Gemini, and other LLM paths.