Skip to main content

Tracing the Claude Agent SDK (TypeScript)

MLflow Tracing provides automatic tracing for TypeScript / JavaScript applications built on the Claude Agent SDK. Traces capture:

  • User prompts and assistant responses
  • Tool calls (file reads/edits, bash, web fetches, etc.) with their inputs and outputs
  • Subagent invocations with the full nested trace of every step they ran
  • Skill usage
  • Per-call and per-session token usage and cost
  • Latency for each step
Using Python?

This page covers the TypeScript Claude Agent SDK. For the Python SDK, see Tracing the Claude Agent SDK (Python).

Setup​

Requirements​

bash
npm install @mlflow/core @mlflow/claude-code @anthropic-ai/claude-agent-sdk

Basic setup​

Initialize the MLflow TypeScript SDK once at process startup, then wrap the Claude Agent SDK's query() function with createTracedQuery():

typescript
import * as mlflow from "@mlflow/core";
import { query } from "@anthropic-ai/claude-agent-sdk";
import { createTracedQuery } from "@mlflow/claude-code";

mlflow.init({
  trackingUri: "http://localhost:5000",
  experimentId: "0",
});

const tracedQuery = createTracedQuery(query);

const result = tracedQuery({
  prompt: "List the files in this directory",
  options: {
    permissionMode: "bypassPermissions",
  },
});

for await (const message of result) {
  if (message.type === "result") {
    console.log("Result:", message.result);
  }
}
note

The TypeScript wrapper enables forwardSubagentText automatically so nested sub-agent activity is reconstructed in the MLflow trace.

Tracking Token Usage and Cost​

MLflow automatically tracks token usage and cost for Claude Agent SDK runs without any extra setup. Token counts for each LLM call are logged on the relevant span, and the aggregated cost and time trends are displayed in the built-in experiment dashboard. See Token Usage and Cost Tracking for details.

Troubleshooting​

No traces appearing

  • Make sure you're calling the wrapped function returned by createTracedQuery(query), not the raw SDK query().
  • Verify mlflow.init({ trackingUri, experimentId }) runs before the first traced query.
  • Consume the query result stream to completion so the trace is finalized and flushed.

Tracking URI / experiment issues

  • Confirm the tracking URI is reachable and the experiment exists.
  • Check that your Node.js process can reach the MLflow server.