Claude Agent SDK

Setup

Install the Braintrust SDK alongside the Claude Agent SDK:

pnpm add braintrust @anthropic-ai/claude-agent-sdk zod

npm install braintrust @anthropic-ai/claude-agent-sdk zod

Auto-instrumentation

To trace the Claude Agent SDK without wrapping it in your application code, run your app with Braintrust’s import hook. The hook patches query on import, so agent queries, tool calls, and sub-agent runs are traced while you use the SDK as normal.

Initialize Braintrust and run your agent

trace-claude-agent-auto.js

import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";
import { initLogger } from "braintrust";
import { z } from "zod";

initLogger({
  projectName: "claude-agent-example", // Replace with your project name
  apiKey: process.env.BRAINTRUST_API_KEY,
});

const calculator = tool(
  "calculator",
  "Performs basic arithmetic operations",
  {
    operation: z.enum(["add", "subtract", "multiply", "divide"]),
    a: z.number(),
    b: z.number(),
  },
  async ({ operation, a, b }) => {
    const results = { add: a + b, subtract: a - b, multiply: a * b, divide: a / b };
    return {
      content: [
        {
          type: "text",
          text: `The result of ${operation}(${a}, ${b}) is ${results[operation]}`,
        },
      ],
    };
  },
);

const result = query({
  prompt: "What is 15 multiplied by 7? Then subtract 5 from the result.",
  options: {
    model: "claude-sonnet-4-5-20250929",
    permissionMode: "bypassPermissions",
    mcpServers: {
      calculator: createSdkMcpServer({
        name: "calculator",
        version: "1.0.0",
        tools: [calculator],
      }),
    },
  },
});

for await (const message of result) {
  console.log(message);
}

Run with the import hook

node --import braintrust/hook.mjs trace-claude-agent-auto.js

The auto-instrumentation example uses plain JavaScript so node --import can run the file directly. The Braintrust APIs work the same in TypeScript projects — compile your TypeScript to JavaScript, then run the compiled file with the import hook.

If you’re using a bundler, see Trace LLM calls for plugin and loader setup.

Manual instrumentation

To trace the Claude Agent SDK explicitly, wrap the SDK module with wrapClaudeAgentSDK and use the returned query, tool, and createSdkMcpServer functions. This example creates a calculator tool and traces a multi-step agent query.

import { initLogger, wrapClaudeAgentSDK } from "braintrust";
import * as claudeSDK from "@anthropic-ai/claude-agent-sdk";
import { z } from "zod";

// Initialize Braintrust logging
initLogger({
  projectName: "claude-agent-example",
  apiKey: process.env.BRAINTRUST_API_KEY,
});

// Wrap the Claude SDK with Braintrust tracing
const { query, tool, createSdkMcpServer } = wrapClaudeAgentSDK(claudeSDK);

// Create a calculator tool
const calculator = tool(
  "calculator",
  "Performs basic arithmetic operations",
  {
    operation: z.enum(["add", "subtract", "multiply", "divide"]),
    a: z.number(),
    b: z.number(),
  },
  async (args: { operation: string; a: number; b: number }) => {
    console.log(`[Tool] Calculating: ${args.a} ${args.operation} ${args.b}`);

    let result = 0;
    switch (args.operation) {
      case "add":
        result = args.a + args.b;
        break;
      case "subtract":
        result = args.a - args.b;
        break;
      case "multiply":
        result = args.a * args.b;
        break;
      case "divide":
        if (args.b === 0) {
          return {
            content: [
              {
                type: "text",
                text: "Error: Division by zero",
              },
            ],
            isError: true,
          };
        }
        result = args.a / args.b;
        break;
    }

    return {
      content: [
        {
          type: "text",
          text: `The result of ${args.operation}(${args.a}, ${args.b}) is ${result}`,
        },
      ],
    };
  },
);

async function main() {
  console.log("Starting Claude Agent SDK example with Braintrust tracing...\n");

  try {
    // Query with mcp server for tool calls
    const result = query({
      prompt: "What is 15 multiplied by 7? Then subtract 5 from the result.",
      options: {
        model: "claude-sonnet-4-5-20250929",
        permissionMode: "bypassPermissions",
        mcpServers: {
          calculator: createSdkMcpServer({
            name: "calculator",
            version: "1.0.0",
            tools: [calculator],
          }),
        },
      },
    });

    // Stream the results
    for await (const message of result) {
      console.log(message);
    }

    console.log("\n\n✓ Example completed! Check Braintrust for tracing data.");
  } catch (error) {
    console.error("Error:", error);
    process.exit(1);
  }
}

main();

Trace nested agent operations

To organize agent calls into parent-child traces, wrap coordinating functions with wrapTraced. Braintrust captures the hierarchical relationships, making multi-step workflows easy to follow in your logs.

nested-agents.ts

import { initLogger, wrapClaudeAgentSDK, wrapTraced } from "braintrust";
import * as claudeSDK from "@anthropic-ai/claude-agent-sdk";

initLogger({
  projectName: "nested-agents-example",
  apiKey: process.env.BRAINTRUST_API_KEY,
});

const { query } = wrapClaudeAgentSDK(claudeSDK);

// Wrapped function creates a child trace
const analyzeData = wrapTraced(
  async (data: string) => {
    const result = query({
      prompt: `Analyze this data and identify key patterns: ${data}`,
      options: {
        model: "claude-sonnet-4-5-20250929",
        permissionMode: "bypassPermissions",
      },
    });

    // Collect and return the analysis
    let analysis = "";
    for await (const message of result) {
      if (message.type === "result") {
        analysis = message.result;
      }
    }
    return analysis;
  },
  { name: "data-analyzer" },
);

// Parent function coordinates multiple operations
async function coordinatorWorkflow() {
  // This call creates a child trace under the parent
  const analysis = await analyzeData("Sales data: Q1=100k, Q2=150k, Q3=180k, Q4=200k");

  console.log("Analysis complete:", analysis);

  // In Braintrust logs, you'll see both operations
  // linked in a parent-child relationship
}

coordinatorWorkflow();

What Braintrust traces

Braintrust captures the Claude Agent SDK span tree for each query:

Agent run spans (Claude Agent), with the prompt as input and the query options as metadata.
Model call spans (anthropic.messages.create), with input messages, model, and assistant output; token metrics including prompt, completion, and cache read and creation tokens.
Tool call spans (named by the tool, such as calculator), with tool input and output, tool name, tool call ID, and MCP server.
Sub-agent spans (named by the sub-agent), with sub-agent metadata and token usage.
Parent-child nesting under any enclosing Braintrust span.

AI providers

SDKs

Developer tools

Setup

Auto-instrumentation

Manual instrumentation

Trace nested agent operations

What Braintrust traces

Resources

​Setup

​Auto-instrumentation

​Manual instrumentation

​Trace nested agent operations

​What Braintrust traces

​Resources

Setup

Auto-instrumentation

Manual instrumentation

Trace nested agent operations

What Braintrust traces

Resources