# Claude Agent SDK (TypeScript)

Trace agents built with Anthropic's @anthropic-ai/claude-agent-sdk in Node.js — every turn, tool call and subagent in one conversation.

Quickstart for agents built with [`@anthropic-ai/claude-agent-sdk`](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk), Anthropic's TypeScript SDK for Claude agents. For the full TypeScript SDK reference, see the [TypeScript SDK guide](/docs/sdks/typescript.md). Using the Python Claude Agent SDK? The [Python SDK](/docs/sdks/python.md) captures it automatically.

## Install

:::tabs
:::tab[npm]
```bash
npm install @brizz/sdk @anthropic-ai/claude-agent-sdk
```
:::tab[yarn]
```bash
yarn add @brizz/sdk @anthropic-ai/claude-agent-sdk
```
:::tab[pnpm]
```bash
pnpm add @brizz/sdk @anthropic-ai/claude-agent-sdk
```
:::

## Initialize

The Claude Agent SDK is ESM-only, and a Node ES module namespace is read-only — the SDK can't be patched in place (and `instrumentModules` doesn't apply). Instead, `instrumentClaudeAgentSDK` hands back a traced copy of the module; **call `query()` on that copy** and every run is traced.

```typescript
import { Brizz } from '@brizz/sdk';
import { instrumentClaudeAgentSDK } from '@brizz/sdk/claude-agent-sdk';
import * as claude from '@anthropic-ai/claude-agent-sdk';

Brizz.initialize({
  apiKey: 'your-brizzai-api-key',
  appName: 'my-agent',
});

const { query } = instrumentClaudeAgentSDK(claude);
```

## Usage

Each turn of a `query()` run is captured automatically — the prompt, the agent's replies, every tool call with its input and result, subagents, token usage, and cost. Wrap the run in `startSession` so it groups into one session:

```typescript
import { startSession, setUser } from '@brizz/sdk';

await startSession('conversation-123', async () => {
  setUser({ id: 'user-42', email: 'dana@example.com' });

  for await (const message of query({ prompt: 'Summarize the open TODOs in this repo.' })) {
    if (message.type === 'result' && message.subtype === 'success') {
      console.log(message.result);
    }
  }
});
```

A multi-turn conversation that streams its prompts into one `query()` call is traced turn by turn, each with its own prompt.

## Complete example

Copy, set `BRIZZ_API_KEY` and `ANTHROPIC_API_KEY`, and run with `tsx agent.ts`.

```typescript
// agent.ts
import { Brizz, startSession, setUser, emitEvent } from '@brizz/sdk';
import { instrumentClaudeAgentSDK } from '@brizz/sdk/claude-agent-sdk';
import * as claude from '@anthropic-ai/claude-agent-sdk';

Brizz.initialize({
  apiKey: process.env.BRIZZ_API_KEY!,
  appName: 'my-agent',
});

const { query } = instrumentClaudeAgentSDK(claude);

await startSession('conversation-123', async () => {
  setUser({ id: 'user-42' });

  const run = query({
    prompt: 'Read package.json and tell me the app name and version.',
    options: { allowedTools: ['Read', 'Glob'] },
  });
  for await (const message of run) {
    if (message.type === 'result' && message.subtype === 'success') {
      console.log(message.result);
    }
  }

  // For a multi-turn conversation, pass `prompt` an async iterable of user messages
  // instead of a string; each message you yield becomes its own turn in Brizz.

  // User feedback — map "feedback.positive" / "feedback.negative" to system
  // events in Org Settings -> Event so it powers filters and the Overview chart.
  emitEvent(
    'feedback.positive',
    { category: 'helpfulness' },
    { comment: 'Exactly what I needed!', context: 'repo-assistant' },
  );
});

// Send what is still queued before the script exits.
await Brizz.flush();
```

The conversation renders in Brizz as user → tool calls → assistant for each turn, with the model badge, token counts, and cost. Expand a tool call to see its input and result. A subagent shows as its own card, with the prompt it was given, its tool calls and its reply.

**Gotchas**

- Call `query()` from the module `instrumentClaudeAgentSDK` returns — calls through the module you imported yourself produce **no spans**.
- A short-lived script can exit before telemetry is sent. Call `await Brizz.flush()` before it exits.
- `query()` is traced; the SDK's unstable session APIs (`unstable_v2_*`) are not.
- To capture each tool's result, Brizz adds a `PostToolUse` hook to the options you pass `query()`; your options object is not changed. If you pass `PostToolUse` hooks of your own, Brizz adds none and records each tool's output as the model was shown it, so output your hook rewrites or redacts reaches Brizz the same way.

## See also

- [Node.js / TypeScript SDK](/docs/sdks/typescript.md) — full SDK reference.
- [Sessions](/docs/instrument/sessions.md) — session capture patterns.
- [Record feedback](/docs/instrument/record-feedback.md) — capture end-user reactions on a conversation.

---

[All Brizz documentation](https://docs.brizz.ai/llms.txt) · [Full documentation (single file)](https://docs.brizz.ai/llms-full.txt)
