Runback
← Blog

Three ways to wire an agent into Runback

Runback Team··integrations, getting-started

Runback doesn't replace LangChain, CrewAI, or the Vercel AI SDK — it governs whatever you built on top of them. Which integration you use depends entirely on what your agent is already running on. Here's how to pick, with the actual commands for each.

1. On the Vercel AI SDK: withDebugger

If your agent calls generateText or streamText from the ai package, this is the deepest integration Runback has. It wraps your model with wrapLanguageModel, so every request and response — the full messages array, system prompt, and in-scope tool definitions — is captured at the exact boundary the model saw it, not reconstructed after the fact.

agent.ts
import { withDebugger } from "@runback/sdk";
import { generateText, stepCountIs } from "ai";

const dbg = withDebugger(model, { runName: "my-agent", redact: "standard" });

const result = await generateText({
  model: dbg.model,
  tools: dbg.tools(myTools),      // wraps tool.execute to capture input/output/latency
  stopWhen: stepCountIs(8),
  prompt: task,
});

await dbg.finish({ output: result.text, status: "success" });

That's the whole integration. dbg.tools(myTools) is what makes tool spans and causal links work — clicking a tool call in the inspector jumps straight to the LLM step that requested it, via tool_call_id. This is also the only path that supports replay-from-step-N: because the exact captured request is stored, Runback can re-issue it, or let you edit it and see how the model responds differently.

2. Any other framework: OpenTelemetry

LangChain, CrewAI, and LlamaIndex agents (JS or Python) don't need code changes at the call site — instrument the library itself with an OpenTelemetry GenAI exporter (OpenLLMetry or OpenInference both work) and point it at Runback's OTLP endpoint:

.env
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="https://runback.dev/api/otel/v1/traces"
OTEL_EXPORTER_OTLP_TRACES_PROTOCOL="http/json"
OTEL_EXPORTER_OTLP_TRACES_HEADERS="authorization=Bearer <RUNBACK_API_KEY>"
LangChain — Python
pip install openinference-instrumentation-langchain \
            opentelemetry-exporter-otlp-proto-http

# LangChainInstrumentor().instrument() — then the env vars above
CrewAI — Python
pip install traceloop-sdk
# Traceloop.init(api_endpoint=..., headers=...) — CrewAI spans flow straight in

This is the right default when you're not on the AI SDK, or you're instrumenting a framework in a language other than TypeScript. If it emits GenAI-convention spans, Runback reads it — the trade-off is that you don't get the AI SDK path's replay-from-step-N, since the exact request/response boundary isn't captured the same way a middleware wrap captures it.

3. A custom agent loop: startRun

No framework, no AI SDK — just your own loop calling a model directly. Record steps by hand with the framework-agnostic recorder:

agent.ts
import { startRun } from "@runback/sdk";

const run = startRun({ runName: "my-agent", input: task });

run.llm({
  model: { provider: "openai", model_id: "gpt-4o" },
  request: { messages, tools },
  response: { text, tool_calls },
  usage: { input_tokens, output_tokens, total_tokens },
  latencyMs,
});

run.tool({ toolName: "search", toolCallId: "1", input, output, latencyMs });

await run.finish({ output, status: "success" });

You control exactly what gets recorded and when — useful for loops that don't map cleanly onto a single library's instrumentation hooks, or when you only want to record a subset of steps.

Three integration paths: Vercel AI SDK, OpenTelemetry, or the manual recorderon Vercel AI SDK?withDebugger()~3 linesdeepest capture:context, redaction,step replayLangChain / CrewAI /LlamaIndex / raw SDKs?OpenTelemetry exporterzero code changes toyour calls — instrumentthe library, not the appyour own agent loop?startRun()manual recorderno frameworkrequirement — recordsteps by hand
All three paths write to the same run format — the inspector, replay, and evals don't know or care which one you used.
Whichever path you pick writes to the same run format. The inspector, replay engine, and eval gate don't know or care how a run was captured.

So what?

Most teams end up mixing paths — the AI SDK for the agent doing the interesting work, an OpenTelemetry exporter for a LangChain tool it calls into, maybe startRunfor one bespoke loop nobody wants to refactor. That's fine. Pick the path that matches what you have today; you're not locked into it.

Full reference, model list, and how Runback connects out to CI, SSO, and alerting once runs are captured: see the integrations page →