Claude Agent SDK

Overview

respan-instrumentation-claude-agent-sdk enables the Claude Agent SDK’s native OpenTelemetry emission and normalizes the resulting spans into Respan conventions.

It registers an internal span processor before export, patches the upstream OpenTelemetry helpers for streamed Claude Agent SDK responses, and maps agent, model, tool, usage, cache-token, and cost attributes into the Respan OTLP pipeline.

$pip install respan-instrumentation-claude-agent-sdk

Version: 0.1.0 | Python: >=3.11, <3.14

Dependencies

PackageVersion
respan-tracing^2.16.1
respan-sdk>=2.5.0
claude-agent-sdk>=0.1.58
opentelemetry-claude-agent-sdk>=0.1.4

Quick start

1import asyncio
2import os
3
4import claude_agent_sdk
5from claude_agent_sdk import ClaudeAgentOptions, ResultMessage
6from respan import Respan
7from respan_instrumentation_claude_agent_sdk import ClaudeAgentSDKInstrumentor
8
9respan_api_key = os.environ["RESPAN_API_KEY"]
10respan_base_url = os.getenv("RESPAN_BASE_URL", "https://api.respan.ai/api").rstrip("/")
11
12respan = Respan(
13 api_key=respan_api_key,
14 base_url=respan_base_url,
15 instrumentations=[ClaudeAgentSDKInstrumentor(capture_content=True)],
16)
17
18async def main():
19 async for message in claude_agent_sdk.query(
20 prompt="Explain tracing in one sentence.",
21 options=ClaudeAgentOptions(
22 model="sonnet",
23 max_turns=1,
24 env={
25 "ANTHROPIC_API_KEY": respan_api_key,
26 "ANTHROPIC_AUTH_TOKEN": respan_api_key,
27 "ANTHROPIC_BASE_URL": f"{respan_base_url}/anthropic",
28 },
29 ),
30 ):
31 if isinstance(message, ResultMessage):
32 print(message.result)
33
34asyncio.run(main())
35respan.flush()

Public API

ClaudeAgentSDKInstrumentor

1from respan_instrumentation_claude_agent_sdk import ClaudeAgentSDKInstrumentor
ParameterTypeDefaultDescription
agent_namestr | NoneNoneOverride the agent name attached to emitted spans.
capture_contentboolFalseInclude prompt, response, and tool content in emitted telemetry.
Attribute/MethodTypeDescription
namestr"claude-agent-sdk" — unique plugin identifier.
activate()() -> NoneLoads the upstream Claude Agent SDK OpenTelemetry instrumentor, patches helper behavior, and registers the Respan normalizing span processor.
deactivate()() -> NoneUninstruments the upstream instrumentor, restores patched helpers, and removes the normalizing span processor.

Captured data

The plugin captures Claude Agent SDK agent invocations, streamed assistant output, tool definitions, tool calls, tool results, model names, usage tokens, cache-read/cache-creation tokens, and total cost when the upstream SDK provides it.

Content capture is controlled by capture_content. Set it to True when prompts, responses, and tool payloads should be visible in Respan.

Gateway

For a Respan-key-only runtime setup, see Claude Agent SDK gateway setup.