Skip to main content

​
Installation

pip install pandaprobe[claude-agent-sdk]

​
Setup

from pandaprobe.integrations.claude_agent_sdk import ClaudeAgentSDKAdapter

adapter = ClaudeAgentSDKAdapter(
    session_id="conversation-123",
    user_id="user-abc",
    tags=["production"],
)
adapter.instrument()

​
Usage

from claude_agent_sdk import ClaudeSDKClient

client = ClaudeSDKClient(model="claude-sonnet-4-20250514")

async for event in client.receive_response(
    prompt="What is the weather in Paris?",
    tools=[...],
):
    print(event)

​
What gets traced

Claude Agent SDK ComponentSpan KindDescription
receive_responseCHAIN + AGENTRoot trace boundary with nested agent span
Assistant messagesLLMThinking blocks extracted, content normalized
PreToolUse / PostToolUse hooksTOOLInput from tool call, output from result
Subagent tool_use blocksAGENTSubagent handoff tracking

​
Tool tracing

The adapter injects tracing hooks into the Claude SDK client at initialization:
  • PreToolUse — Creates a TOOL span with the tool’s input arguments
  • PostToolUse — Sets the tool’s output and marks the span as OK (or ERROR if is_error is true)
  • PostToolUseFailure — Records the error and marks the span as ERROR

​
Extended thinking

Thinking blocks are automatically handled:
  • Thinking content is extracted and stored in metadata as reasoning_summary
  • Thinking-only messages are buffered and combined with the next message’s thinking
  • Thinking blocks are stripped from the visible output

​
Conversation history

The adapter maintains conversation history across turns on the client instance (_pandaprobe_history), allowing multi-turn tracing with proper context.

​
Token usage mapping

Claude SDK FieldPandaProbe Field
input_tokensprompt_tokens
output_tokenscompletion_tokens
cache_read_input_tokenscache_read_tokens