> ## Documentation index
> Fetch the complete documentation index at: https://arize.com/llms.txt
> Ask it with GET https://arize.com/ask?q=<keywords or question>. Short keywords rank best.
> Use these to discover all available pages before exploring further.

# Claude Agent SDK (TypeScript)

> Trace Anthropic's Claude Agent SDK applications in TypeScript/Node.js with Phoenix

<Note>Looking for Python? See the [Python guide](/docs/phoenix/integrations/python/claude-agent-sdk).</Note>

[![NPM Version](https://img.shields.io/npm/v/@arizeai%2Fopeninference-instrumentation-claude-agent-sdk.svg)](https://www.npmjs.com/package/@arizeai/openinference-instrumentation-claude-agent-sdk)

This module provides [OpenInference](https://github.com/Arize-ai/openinference) instrumentation for [Anthropic's Claude Agent SDK](https://platform.claude.com/docs/en/agent-sdk/overview), automatically capturing **AGENT** and **TOOL** spans that follow OpenInference semantic conventions.

## Install

```bash
npm install @anthropic-ai/claude-agent-sdk @arizeai/openinference-instrumentation-claude-agent-sdk @arizeai/phoenix-otel
```

## Setup

To instrument your Claude Agent SDK application, use the `register` function from `@arizeai/phoenix-otel` and set up the Claude Agent SDK instrumentation.

Create the `instrumentation.ts` file:

```typescript expandable
import { register } from "@arizeai/phoenix-otel";
import { ClaudeAgentSDKInstrumentation } from "@arizeai/openinference-instrumentation-claude-agent-sdk";
import * as ClaudeAgentSDKModule from "@anthropic-ai/claude-agent-sdk";

// Initialize Phoenix tracing
export const tracerProvider = register({
  projectName: "claude-agent-sdk-app",
  // If Phoenix is running elsewhere:
  // url: "https://your-phoenix.example.com",
  // apiKey: process.env.PHOENIX_API_KEY,
  // If using self-hosted Phoenix:
  // url: "http://localhost:6006",
});

// Set up Claude Agent SDK instrumentation
const instrumentation = new ClaudeAgentSDKInstrumentation();

// manuallyInstrument() returns an instrumented copy of the SDK module.
// Export it and use it in your application instead of importing the SDK directly.
export const ClaudeAgentSDK = instrumentation.manuallyInstrument(ClaudeAgentSDKModule);

console.log("Claude Agent SDK instrumentation registered");
```

<Note>
The Claude Agent SDK is ESM-only, so `manuallyInstrument()` is used instead of `enable()`. Because ES module exports are read-only, the instrumentation can't patch the SDK in place — `manuallyInstrument()` returns an instrumented copy of the module instead. Call `query()` on that returned copy. If you import `query` directly from `@anthropic-ai/claude-agent-sdk`, no spans are created.
</Note>

## Usage

```typescript expandable
import { ClaudeAgentSDK, tracerProvider } from "./instrumentation.js";

async function main() {
  for await (const message of ClaudeAgentSDK.query({
    prompt: "What files are in this directory?",
    options: {
      allowedTools: ["Glob"],
    },
  })) {
    if (message.type === "result" && message.subtype === "success") {
      console.log(message.result);
    }
  }

  // Export buffered spans before the process exits
  await tracerProvider.forceFlush();
}

main();
```

## Observe

With instrumentation enabled, you will see the following in Phoenix:

- **AGENT spans** wrapping the full `query()` call, capturing the prompt and final response
- **TOOL spans** for each tool invocation made by the agent during execution

These spans follow [OpenInference semantic conventions](https://github.com/Arize-ai/openinference), making them fully compatible with Phoenix's trace visualization and evaluation features.

## Privacy Configuration

You can configure the instrumentation to hide sensitive data using `traceConfig`:

```typescript
const instrumentation = new ClaudeAgentSDKInstrumentation({
  traceConfig: {
    hideInputs: true, // Omit input content from spans
    hideOutputs: true, // Omit output content from spans
  },
});
export const ClaudeAgentSDK = instrumentation.manuallyInstrument(ClaudeAgentSDKModule);
```

## Resources

* [NPM Package](https://www.npmjs.com/package/@arizeai/openinference-instrumentation-claude-agent-sdk)

* [OpenInference package for Claude Agent SDK](https://github.com/Arize-ai/openinference/tree/main/js/packages/openinference-instrumentation-claude-agent-sdk)

* [Claude Agent SDK Documentation](https://platform.claude.com/docs/en/agent-sdk/overview)