Setup Install the Braintrust SDK alongside the Claude Agent SDK: ```bash pnpm theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} pnpm add braintrust @anthropic-ai/claude-agent-sdk zod ``` ```bash npm theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} 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. ```javascript title="trace-claude-agent-auto.js" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} 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); } ``` ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} 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](/instrument/trace-llm-calls#auto-instrumentation) 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. ```typescript title="claude-agent.ts" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} 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. ```typescript title="nested-agents.ts" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} 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. Resources * [Claude Agent SDK documentation](https://docs.claude.com/en/api/agent-sdk/) * [Anthropic API documentation](https://docs.anthropic.com/)