> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usebench.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# TypeScript and JavaScript

> Record Node.js agents and tools, then run application tests.

## Copy this into your coding agent

Paste into Cursor, Codex, Claude Code, or another coding agent in your project.

```text theme={null}
Add Bench using https://docs.usebench.ai/sdk/typescript and my Bench SDK setup prompt.
Use the install command on this page, plus my endpoint and server-side key. Match this repository's
TypeScript or JavaScript style. Start with metadata-only capture in staging.
Wrap a real awaited operation and its tools with bench.trace. Preserve the full
stream lifecycle, flush a synthetic event, and confirm receipt in Bench.
Show changed files and any remaining setup steps.
```

<Note>Beta release. All four languages support tracing, application tests and scripted simulations.</Note>

## Install

[Package on npm](https://www.npmjs.com/package/@benchai/sdk) · [Source and examples](https://github.com/trybench/bench-sdk/tree/v0.1.0/examples/typescript)

```sh theme={null}
npm install @benchai/sdk@0.1.0
```

## Record one interaction

Run the installation command above in your server project. Create a repository-scoped
key on the **SDK** page in Bench and keep it in your server’s secret store.

```ts theme={null}
import { Bench } from '@benchai/sdk'

const bench = new Bench({
  apiKey: process.env.BENCH_API_KEY!,
  repository: process.env.BENCH_REPOSITORY!,
  branch: process.env.BENCH_BRANCH!,
  endpoint: process.env.BENCH_API_BASE_URL,
  systemName: 'Support agent',
  environment: process.env.BENCH_ENVIRONMENT ?? 'development',
  captureContent: false,
})

// One synthetic event: no customer content or model request.
await bench.trace(
  { name: 'SDK connection check', kind: 'AGENT' },
  () => ({ ok: true }),
)
await bench.shutdown() // Flush before this one-shot script exits.
```

Use Node.js 20+ on the server. Never use public environment-variable prefixes
such as `NEXT_PUBLIC_` or `VITE_` for the key. Set `BENCH_API_BASE_URL` to the endpoint shown in your account.
Use the API address and installation command shown on the SDK page in your Bench account.

The example uses TypeScript. In JavaScript, remove the `!` non-null assertions
and validate required environment variables when your server starts.

## Wrap agents and tools

Replace the synthetic callback with an existing application operation. Nest tool
calls with `kind: 'TOOL'`; awaited child calls keep their parent trace. Wrap the
complete invocation for Mastra, Vercel AI SDK, LangChain, LangGraph, Deep Agents,
OpenAI Agents or custom server code. These are manual wrappers. More automatic
framework adapters are coming soon.

For streams, keep the span open until the stream is fully consumed. Fire-and-forget
work may finish after the request and needs its own lifecycle handling.

`captureContent` defaults to `false`. When enabled, pass `input` and let the callback
return the output. Built-in filters run before sending. Add a `redact(value)`
callback for extra application fields. Read [privacy and redaction](/guides/security-and-privacy#how-redaction-works).

Call `await bench.flush()` at serverless request boundaries. Reuse the client for
long-running servers and call `await bench.shutdown()` after active work finishes.
`bench.stats` and `onError` expose delivery failures without changing app results.

Set `componentId` to a real prompt component from Bench when linking events to
criteria. Never invent IDs. SDK setup keys cannot spend evaluation credits.

## Test application behavior

This client includes `evaluateSystem` for individual cases and `simulateSystem`
for scripted customer conversations through your app. Both require your actual
application function and test dependencies. Read [application testing](/sdk/system-evaluation)
for complete examples, then [production checks](/sdk/production-checks) to evaluate
recorded interactions.

See [SDK setup](/sdk/quickstart) for connection status, environments and troubleshooting.

## Run in CI

Use Bench with your existing pull-request checks. See [Run tests in CI](/sdk/ci)
for setup, report handling and the features available in each language.