Add OpenTelemetry Instrumentation for the Claude Agent SDK

[vasantteja]

What problem do you want to solve?

Add OpenTelemetry instrumentation for the Anthropic Claude Agent SDK (claude-agent-sdk package) to support tracing of agent operations, tool executions, and MCP server interactions, following the GenAI Agent Semantic Conventions.

Describe the solution you'd like

Create a new instrumentation package opentelemetry-instrumentation-anthrophic-agents (or similar naming) that:

Core Instrumentation

• Instruments agent query operations (query() and ClaudeSDKClient.query())
• Creates invoke_agent spans for agent invocations following GenAI agent span conventions.
• Creates execute_tool spans for each tool execution (Read, Write, Bash, Edit, etc.)
• Instruments custom MCP server tool calls created via @tool decorator and create_sdk_mcp_server()
• Captures hook executions (PreToolUse, PostToolUse, etc.) as span events or child spans.

Edit 1: I am working with agent-sdk maintainers to see if they can support trace and span creation. I will update the plan accordingly once I hear back from them.

Describe alternatives you've considered

No response

Additional Context

• Follow the structure of opentelemetry-instrumentation-openai-v2
• Use gen_ai.provider.name = "anthropic" (already in OTel well-known values)
• Map ClaudeAgentOptions fields to appropriate gen_ai.* attributes
• Handle AssistantMessage, UserMessage, ResultMessage, SystemMessage types
• Extract ToolUseBlock and ToolResultBlock for tool span creation

Would you like to implement a fix?

Yes

References

• Claude Agent SDK Repository
• Claude Agent SDK Documentation

Tip

_{React with 👍 to help prioritize this issue. Please use comments to provide useful context, avoiding +1 or me too, to help us triage it. Learn more here.}

[sipercai]

Hi, I'd like to work on this. Could you assign this issue to me? I'll start implementing the instrumentation following the GenAI Agent Semantic Conventions.

[vasantteja]

Howdy @sipercai, thanks for the help. can you please give me sometime before we implement this. I am trying to work with sdk maintainers to add otel support in the sdk before we extract the semantic conventions. I will inform you once it's finished.

[sipercai]

Howdy @vasantteja ，Just to clarify, when you mention 'add otel support in the sdk', does that mean building native OTel support directly into the SDK, similar to how Claude Code has it? If so, that's sounds really cool!

From what I've seen, attributes like cache_tokens and turns do seem very valuable to capture.

Thanks again for driving this foundational work forward. I'm excited to see it progress and look forward to your update!"

[vasantteja]

@sipercai Yeah I am looking to see sdk maintainers are interested in adding native instrumentation like claude-code. But looks like they're swamped as I didn't get a reply back from them. However I am prototyping instrumentation support for sdk to see if that brings traction. Having said that it's better we can start adding the support for this sdk using monkey patching. Quick question, did you use claude-agent-sdk and langsmith for tracing by any chance?

[sipercai]

@vasantteja Yes，I’ve used claude-agent-sdk with LangSmith for tracing. I completely agree that we should start with monkey patching first.