Claude Agent SDK Instrumentor

Auto-instrument Claude Agent SDK spans for Respan.

1import { Respan } from "@respan/respan";
2import { ClaudeAgentSDKInstrumentor } from "@respan/instrumentation-claude-agent-sdk";
3
4const respan = new Respan({
5 instrumentations: [
6 new ClaudeAgentSDKInstrumentor({
7 sdkModule: {}, // your mutable @anthropic-ai/claude-agent-sdk module
8 }),
9 ],
10});
11await respan.initialize();

Install

$npm install @respan/respan @respan/instrumentation-claude-agent-sdk @anthropic-ai/claude-agent-sdk

@respan/instrumentation-claude-agent-sdk patches query() on the mutable SDK module to capture agent events, tool calls, and streamed message spans.

Configure

ClaudeAgentSDKInstrumentor accepts a small configuration object.

1import { ClaudeAgentSDKInstrumentor } from "@respan/instrumentation-claude-agent-sdk";
2
3const instrumentor = new ClaudeAgentSDKInstrumentor({
4 sdkModule: {}, // required: the mutable Claude Agent SDK module object
5 agentName: "claude-agent-sdk",
6});

Public API

OptionTypeDefaultDescription
sdkModuleRecord<string, unknown>undefinedRequired mutable module reference from @anthropic-ai/claude-agent-sdk to patch (query()).
agentNamestringundefinedOptional display name applied to agent spans.

Example

1import * as _ClaudeAgentSDK from "@anthropic-ai/claude-agent-sdk";
2import { Respan } from "@respan/respan";
3import { ClaudeAgentSDKInstrumentor } from "@respan/instrumentation-claude-agent-sdk";
4
5// ESM namespace objects are read-only; clone before patching.
6const ClaudeAgentSDK = { ..._ClaudeAgentSDK };
7
8const respan = new Respan({
9 instrumentations: [
10 new ClaudeAgentSDKInstrumentor({
11 sdkModule: ClaudeAgentSDK,
12 agentName: "claude-agent-sdk",
13 }),
14 ],
15});
16
17await respan.initialize();
18
19const response = await ClaudeAgentSDK.query({
20 prompt: "Explain observability in one sentence.",
21 options: { model: "sonnet", maxTurns: 1 },
22});
23
24for await (const message of response) {
25 if (message.type === "result") {
26 console.log(message.result);
27 }
28}
29
30await respan.flush();