Claude Agent SDK

Trace an agent built on @anthropic-ai/claude-agent-sdk by pointing the engine’s OpenTelemetry export at RunAgain. For guaranteed token/cost columns you can also wrap each run in a manual span with the runagain SDK.

Install

npm i runagain @opentelemetry/api @anthropic-ai/claude-agent-sdk

pnpm add runagain @opentelemetry/api @anthropic-ai/claude-agent-sdk

yarn add runagain @opentelemetry/api @anthropic-ai/claude-agent-sdk

bun add runagain @opentelemetry/api @anthropic-ai/claude-agent-sdk

Configure

.env.local

RUNAGAIN_API_KEY=sk_…
RUNAGAIN_INGEST_URL=https://ingest.runagain.ai

Point the engine at RunAgain

The Claude Agent SDK runs the Claude Code engine, which can export its own OTLP spans. Pass RunAgain’s endpoint + key into the query’s env and it streams runs, tool calls and tokens to your project:

agent.ts

import { query } from "@anthropic-ai/claude-agent-sdk";

const runagainEnv = {
  CLAUDE_CODE_ENABLE_TELEMETRY: "1",
  OTEL_TRACES_EXPORTER: "otlp",
  OTEL_EXPORTER_OTLP_PROTOCOL: "http/protobuf",
  OTEL_EXPORTER_OTLP_ENDPOINT: process.env.RUNAGAIN_INGEST_URL, // base host, no /v1/traces
  OTEL_EXPORTER_OTLP_HEADERS: `x-runagain-key=${process.env.RUNAGAIN_API_KEY}`,
  OTEL_SERVICE_NAME: "support-bot",
};

for await (const message of query({
  prompt: "…",
  options: {
    model: "claude-opus-4-8",
    maxTurns: 5,
    env: { ...process.env, ...runagainEnv },
  },
})) {
  // handle messages…
}

Open your project’s Traces page to see the runs stream in.

Guaranteed token & cost columns

The engine’s beta export can lag; to always land the numeric columns (and add your own identity/metadata), initialize the runagain SDK once at startup and wrap each run in an invoke_agent span, reading token usage off the SDK’s result message:

import { initRunAgain, getTracer, runAgainAttributes } from "runagain";
import { SpanKind } from "@opentelemetry/api";

initRunAgain(); // reads RUNAGAIN_API_KEY / RUNAGAIN_INGEST_URL

async function runAgent(prompt: string, sessionId: string) {
  return getTracer().startActiveSpan("invoke_agent support-bot", { kind: SpanKind.CLIENT }, async (span) => {
    span.setAttributes({
      "gen_ai.operation.name": "invoke_agent",
      "gen_ai.agent.name": "support-bot",
      "gen_ai.input.messages": prompt,
      ...runAgainAttributes({ session: sessionId }),
    });
    let input = 0;
    let output = 0;
    for await (const message of query({ prompt, options: { model: "claude-opus-4-8", maxTurns: 5 } })) {
      if (message.type === "result") {
        for (const u of Object.values(message.modelUsage ?? {})) {
          input += u.inputTokens + u.cacheCreationInputTokens;
          output += u.outputTokens;
        }
      }
    }
    span.setAttributes({ "gen_ai.usage.input_tokens": input, "gen_ai.usage.output_tokens": output });
    span.end();
  });
}

A complete reference (per-tool execute_tool spans, error handling) lives in the runagain-test-agents harness (src/agents/claude).

Prefer to let your coding agent wire this up? Paste into Claude Code or Cursor: “Integrate RunAgain into this Claude Agent SDK project — install runagain, pass the OTLP telemetry env into my query() calls, and read RUNAGAIN_API_KEY / RUNAGAIN_INGEST_URL from env. Keep my agent logic unchanged.”

Get started

Integrations

Concepts

Web app

Install

Configure

Point the engine at RunAgain

Guaranteed token & cost columns

​Install

​Configure

​Point the engine at RunAgain

​Guaranteed token & cost columns

Install

Configure

Point the engine at RunAgain

Guaranteed token & cost columns