Trace Claude Agent SDK JS/TS with Langfuse

The Claude Agent SDK is Anthropic's open-source framework for building AI agents in TypeScript. By combining the Claude Agent SDK with Langfuse, you can trace, monitor, and analyze every agent step, tool call, and model response in development and production.

This notebook demonstrates how to use the ClaudeAgentSDKInstrumentation library from OpenInference to automatically instrument Claude Agent SDK calls and send OpenTelemetry spans to Langfuse.

What is Claude Agent SDK?
The Claude Agent SDK is Anthropic's open-source framework for building AI agents. It provides a clean API for creating tool-using agents with the query() function, including native support for MCP servers and custom tools.

What is Langfuse?
Langfuse is an open source platform for LLM observability and monitoring. It helps you trace and monitor your AI applications by capturing metadata, prompt details, token usage, latency, and more.

Step 1: Install Dependencies

Install the necessary packages:

npm install @anthropic-ai/claude-agent-sdk @arizeai/openinference-instrumentation-claude-agent-sdk @langfuse/otel @opentelemetry/sdk-node

Note: This cookbook uses Deno.js for execution, which requires different syntax for importing packages and setting environment variables. For Node.js applications, the setup process is similar but uses standard npm packages and process.env.

Step 2: Configure Environment

Set up your Langfuse and Anthropic API keys. You can get Langfuse keys by signing up for a free Langfuse Cloud account or by self-hosting Langfuse. Get your Anthropic API key from the Anthropic Console.

Step 3: Initialize OpenTelemetry with Langfuse

Set up the OpenTelemetry SDK with the LangfuseSpanProcessor and the ClaudeAgentSDKInstrumentation from OpenInference. The instrumentation automatically captures agent runs and tool calls, sending them as OpenTelemetry spans to Langfuse.

We also provide a custom shouldExportSpan filter to include spans from the @arizeai/openinference-instrumentation-claude-agent-sdk instrumentation scope alongside the default Langfuse filter.

Step 4: Run the Agent

Use the Claude Agent SDK's query() function to run an agent. All agent steps, tool calls, and model completions are automatically traced and sent to Langfuse.

Step 5: View Traces in Langfuse

After running the agent, navigate to your Langfuse Trace Table. You will find detailed traces of the agent's execution, providing insights into every agent step, tool call, input, output, and performance metric.

Link to example trace in Langfuse